Archive Fetch Helper

GitHub Link to Code.

Helpers for resolving archive sources and optional SHA256 verification.

This module keeps URL/download handling separate from archive extraction so PipelineManager can expose a compact API while ArchiveUtils remains focused on local archive files.

class mdxplain.utils.archive_fetch_helper.ArchiveFetchHelper

Resolve archive sources and verify downloaded archives when requested.

The helper accepts either local paths or URLs, downloads remote archives into a deterministic local file when needed, and optionally validates the resulting archive via SHA256.

static is_url(value: str) → bool

Return whether value looks like a supported URL.

Parameters

valuestr: Candidate archive or SHA source.

Returns

bool: True when the value has an HTTP(S) or file URL scheme.

static validate_load_inputs(file_path: str, verify: bool, sha: str | None, download_url: str | None) → None

Validate public load_from_archive fetch parameters.

Parameters

file_pathstr: Local archive path, local download target, or remote archive URL.
verifybool: Requested verification mode.
shastr or None: SHA256 input as raw hash, local file path, or URL.
download_urlstr or None: Optional remote source URL when file_path should be treated as the local download target.

Returns

None: Raises ValueError for invalid argument combinations.

static should_verify_archive(verify: bool, sha: str | None) → bool

Return whether archive SHA256 verification should be performed.

Parameters

verifybool: User-requested verification flag.
shastr or None: Optional SHA256 input. When present, verification is always enabled.

Returns

bool: True when archive verification should run.

static resolve_archive_path(file_path: str, cache_dir: str, verify: bool, sha: str | None, download_url: str | None, overwrite: bool) → str

Resolve a local archive path from a user-provided source.

Parameters

file_pathstr: Local archive path, local download target, or remote archive URL.
cache_dirstr: Cache root used to derive a default download location.
verifybool: Requested verification mode.
shastr or None: SHA256 input as raw hash, file path, or URL.
download_urlstr or None: Optional remote source URL when file_path is the desired local archive target.
overwritebool: Whether an existing download target should be replaced.

Returns

str: Normalized absolute path to the local archive file.

static resolve_expected_sha256(sha: str) → str

Resolve a SHA256 value from raw text, a local file, or a URL.

Parameters

shastr: Raw SHA256 hex string, local path to a .sha file, or URL.

Returns

str: Normalized lowercase SHA256 hex string.

static verify_archive_sha256(file_path: str, sha: str) → None

Validate an archive file against an expected SHA256 value.

Parameters

file_pathstr: Local archive file path.
shastr: Raw SHA256 hex string, local path to a .sha file, or URL.

Returns

None: Raises ValueError if verification fails.