DOCSEARCHbyAlgolia
Submit Docs

rattler

repository·main·Indexed 19 days ago

https://github.com/conda/rattler

A collection of Rust crates for high-performance interaction with the conda ecosystem, providing core logic for solving, installing, and managing conda environments. It is designed for use in non-Python applications via Rust, Python (py-rattler), and JavaScript/TypeScript (js-rattler/WASM) bindings. Key components include rattler-index for creating conda channel indexes, rattler-solve for package satisfiability, and rattler-lock for environment lockfiles.

Tokens
108.7K
Snippets
377
Records
507
Agent score
65%

What's inside rattler

  1. What is Rattler

    main
    Rattler is a Rust-based library designed to provide core functionality for the conda ecosystem. It allows programs and libraries to interact with conda workflows (such as package handling and environment management) without requiring a Python dependency. The js-rattler package specifically provides bindings to the native Rust library compiled to WebAssembly (WASM), making it suitable for JavaScript/TypeScript environments.

  2. What is Rattler and py-rattler?

    main

    Rattler is a Rust-based library providing core functionality for the conda ecosystem. Its goal is to allow programs to interact with conda packages and workflows without a Python dependency.

    py-rattler provides the Python bindings for this library, allowing Python developers to use Rattler's high-performance Rust implementation for tasks like downloading dependencies and creating environments.

  3. Overview of Rattler components

    main

    Rattler is composed of several specialized Rust crates:

    • rattler_conda_types: Foundational types for conda ecosystem data structures.
    • rattler_package_streaming: Downloading, extracting, and creating conda package archives.
    • rattler_repodata_gateway: Downloading and processing index information.
    • rattler_shell: Activating environments and running programs.
    • rattler_solve: Backend-agnostic package satisfiability solver.
    • rattler_virtual_packages: Detection of system capabilities.
    • rattler_index: Creating local conda channels from local packages.
    • rattler: High-level functionality to create complete environments.
    • rattler-lock: Creating and parsing conda environment lockfiles.
    • rattler-networking: Networking utilities (authentication, mirroring, etc.).
    • rattler-bin: An example package manager implementation.

  4. What is coalesced_map?

    main

    coalesced_map is a thread-safe, deduplicating map designed for high-concurrency scenarios. It ensures that expensive computations or resource initializations are executed exactly once per key, even when multiple asynchronous tasks request the same key simultaneously.

    When multiple concurrent requests are made for the same key:

    1. The first request triggers the initialization function.
    2. Subsequent concurrent requests for that same key do not trigger a new computation; instead, they wait for the first request to complete and then receive the same result.

  5. Understand the FileMode abstraction

    main

    In rattler, FileMode is a type used within the rattler.package.paths_json module to specify how file paths should be handled or interpreted when working with package data. It is a core part of the schema used for representing package paths in JSON format.

    rattler.package.paths_json.FileMode

  6. Use IndexJson for package index data

    main
    The rattler.package.index_json module provides functionality for working with the index.json format used by conda channels. This format is a structured representation of the packages available in a specific channel, allowing for efficient querying and inspection of package metadata without downloading individual package files.

  7. Use GenericVirtualPackage to define environment specifications

    main

    In rattler, a GenericVirtualPackage allows you to define a virtual package with specific attributes (like version, build string, or platform) that do not exist as actual files on disk but are used to satisfy dependency requirements during the environment solving process. This is useful for representing system-level capabilities or constraints that the solver must respect.

    # Note: The exact instantiation pattern depends on the rattler.virtual_package.generic API
# which defines virtual packages used during solving.

  8. Configure rattler-index using TOML

    main

    Configuration is managed via a TOML file using the [index-config] section. It follows a hierarchical override pattern similar to pixi configuration:

    1. [index-config]: The global default block.
    2. Per-host: Keys matching a bucket or root path (e.g., [index-config."s3://my-bucket"]) apply to all channels under that host.
    3. Per-channel: The most specific entry (e.g., [index-config."s3://my-bucket/staging"]) wins.

    Matching is performed against the canonical channel target (full URL for remote, absolute path for local) on path-component boundaries. The most specific entry overrides earlier values field by field.

    [index-config]
write-zst = true
write-shards = true

# Per-host override
[index-config."s3://my-bucket"]
base-url = "../packages/"

# Per-channel override (most specific)
[index-config."s3://my-bucket/staging"]
write-shards = false

# Local directory key (absolute path)
[index-config."/srv/conda/internal"]
base-url = "../packages/"

  9. Use PackageHashes to verify package integrity

    main
    The rattler.lock.PackageHashes type is used to store and manage the cryptographic hashes of conda packages. This is typically used during the locking process or when verifying that downloaded package files match their expected signatures to ensure security and integrity.

  10. Understand VirtualPackages in rattler

    main
    In rattler, a VirtualPackage represents a package that is not actually present in a channel or repository but is instead provided by the system or the environment itself. Virtual packages are used to define environment specifications and constraints based on the host system's properties (e.g., operating system, architecture, or kernel version). When solving an environment, the solver uses these virtual packages to ensure that the selected concrete packages are compatible with the actual system running the environment.

  11. Install py-rattler

    main

    You can install the py-rattler Python bindings using several package managers depending on your environment preference.

    # Using PyPI
python3 -m pip install --upgrade py-rattler

# Using Pixi
pixi add py-rattler

# Using Conda
conda install py-rattler

# Using Mamba
mamba install py-rattler -c conda-forge

  12. Use create-resolvo-snapshot to create a snapshot from a conda channel

    main

    The create-resolvo-snapshot tool allows you to generate a resolvo snapshot from a specific conda channel. This is useful for preparing data for the resolvo solver. You must specify the channel name and the architecture subdirectory (e.g., linux-64, noarch, osx-arm64).

    create-resolvo-snapshot conda-forge --subdir linux-64