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, dry_run: bool = False) → WorkspaceArchive

Create an archive for workspace and return its handle.

When dry_run is true, all inputs are resolved and validated without writing the lockfile, archive, receipt, or package cache.

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, dry_run: bool = False) → 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, dry_run: bool = False) → WorkspaceArchiveInstallResult

Extract the archive and install environments from its lockfile.

When dry_run is true, archive and install inputs are validated without extracting files or changing an environment prefix.

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.

static package_cache_record(package: Path, receipt_record: dict[str, object]) → str

Render the conda cache record for one verified bundled package.

static package_cache_record_matches(package: Path, receipt_record: dict[str, object], extracted: Path) → bool

Return whether an existing extracted cache entry matches the receipt.

classmethod publish_package_cache_record(package: Path, receipt_record: dict[str, object], cache_path: Path) → None

Publish one fetched package record without replacing extracted content.

property receipt_path: Path | None

Return the configured external receipt path, if any.

static remove_created_output(path: Path, expected: tuple[int, int]) → None

Remove path only while it still names the created output.

require_existing_archive() → Path

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

static resolve_extracted_manifest(workspace: Path) → Path

Return the sole valid workspace manifest at an extracted archive root.

static snapshot_archive(source: Path, destination: Path) → None

Copy one no-follow archive generation into private staging.

static validate_lockfile_credentials(data: dict[str, object], content: str) → None

Reject a lockfile whose serialized URLs require redaction.

static validate_manifest_credentials(content: str) → None

Reject credential-bearing strings before copying a manifest.

static validate_receipt_inputs(*, root: Path, output: Path, archive_config: ArchiveConfig, manifest_path: Path, lockfile_path: Path, receipt_path: Path, extra_files: tuple[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().