Archives

Public archive APIs for creating, inspecting, verifying, extracting, and installing workspace archives.

Archive creation and extraction for conda workspaces.

Provides functions for collecting workspace files, creating tar archives (gzip or zstandard), extracting with path traversal protection, bundling conda packages for offline use, and inspecting archive contents.

class conda_workspaces.archive.WorkspaceArchive(path: str | Path, receipt: bool | str | Path | None = None)

High-level API for creating, extracting, and installing archives.

static build_receipt(*, ctx: WorkspaceContext, archive_path: Path, archive_config: ArchiveConfig, manifest_path: Path, lockfile_path: Path, options: dict[str, object]) → ArchiveReceipt

Build the external receipt for a newly created archive.

classmethod create(*, workspace: str | Path | None = None, output: str | Path | None = None, lock: bool = False, bundle: bool = False, exclude: tuple[str, ...] = (), receipt: bool | str | Path | None = None) → WorkspaceArchive

Create an archive for workspace and return its handle.

static default_output_path(ctx: WorkspaceContext, output: str | Path | None) → Path

Return the explicit or workspace-name-derived output path.

default_target(cwd: str | Path | None = None) → Path

Return the default extraction target derived from the archive name.

extract(*, target: str | Path | None = None, require_sha256: bool = False, prime_cache: bool = True, package_cache: str | Path | None = None) → WorkspaceArchiveExtractResult

Extract the archive and optionally prime bundled package cache files.

inspect() → dict[str, object]

Return archive metadata without extracting it.

install(*, target: str | Path | None = None, environment: str | None = None, prefix: str | Path | None = None, dest: str | Path | None = None, require_sha256: bool = False, prime_cache: bool = True, package_cache: str | Path | None = None, install_handler: Callable[[Path, str | None, Path | None, str | None], int] | None = None) → WorkspaceArchiveInstallResult

Extract the archive and install environments from its lockfile.

static install_from_lockfile(workspace: Path, environment: str | None, prefix: Path | None, target_prefix_override: str | None) → int

Install workspace environments from conda.lock without the CLI.

property receipt_path: Path | None

Return the configured external receipt path, if any.

require_existing_archive() → Path

Return path after verifying that it points to an archive file.

static validate_receipt_inputs(*, root: Path, output: Path, archive_config: ArchiveConfig, manifest_path: Path, lockfile_path: Path, receipt_path: Path) → None

Validate inputs required to write a receipt for a new archive.

verify() → ArchiveReceipt

Verify the archive against its external receipt.

class conda_workspaces.archive.WorkspaceArchiveExtractResult(target: Path, receipt_path: Path | None, verified: bool, info: dict[str, object], primed_packages: int = 0, cache_priming_skipped: bool = False)

Result returned by WorkspaceArchive.extract().

class conda_workspaces.archive.WorkspaceArchiveInstallResult(target: Path, environment: str | None, install_prefix: Path | None, runtime_prefix: str | None, receipt_path: Path | None, verified: bool, info: dict[str, object], return_code: int = 0, primed_packages: int = 0, cache_priming_skipped: bool = False, prefix_reference_matches: tuple[Path, ...] = (), prefix_reference_matches_truncated: bool = False)

Result returned by WorkspaceArchive.install().