location – Artifact locations and integrity

This module provides classes for representing artifact locations in ProductMD 2.0.

Location objects represent where artifacts (RPMs, images, repositories, extra files) are stored, along with integrity information (checksums, sizes) and local path hints for v1.2 compatibility.

Example:

from productmd.location import Location, FileEntry, compute_checksum

# Create a location from a local file
loc = Location.from_local_file("Server/x86_64/iso/boot.iso", "/path/to/compose")
print(loc.checksum)  # sha256:abc123...

# Create a location with a remote URL
loc = Location(
    url="https://cdn.example.com/Server/x86_64/iso/boot.iso",
    size=1234567,
    checksum="sha256:abc123...",
    local_path="Server/x86_64/iso/boot.iso",
)

# Check location type
if loc.is_remote:
    print("Remote location:", loc.url)

Constants

productmd.location.CHECKSUM_ALGO: str = 'sha256'

str(object=’’) -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to ‘utf-8’. errors defaults to ‘strict’.

productmd.location.CHECKSUM_RE: Pattern[str] = re.compile('^(?P<algorithm>sha256|sha512|sha1|md5):(?P<digest>[a-f0-9]+)$'): Compiled regular expression object.

Functions

productmd.location.compute_checksum(path: str, algorithm: str = 'sha256') → str

Compute checksum of a file.

Parameters:

path (str) – Path to file
algorithm (str) – Hash algorithm (default: sha256)

Returns:

Checksum in “algorithm:hexdigest” format

Return type:

str

productmd.location.parse_checksum(checksum: str) → Tuple[str, str]

Parse a checksum string in “algorithm:hexdigest” format.

Parameters:: checksum (str) – Checksum string
Returns:: Tuple of (algorithm, hexdigest)
Return type:: tuple
Raises:: ValueError – If checksum format is invalid

Classes

Represents artifact location with integrity information.

A Location object describes where an artifact is stored and provides the information needed to:

Download it (url)
Verify its integrity (checksum, size)
Place it in a v1.2 filesystem layout (local_path)

Attributes:

url (str): HTTPS URL, OCI reference, or relative path
size (int): Size in bytes (for OCI images with contents, total image size)
checksum (str): Checksum in “algorithm:hash” format (e.g., “sha256:abc123…”)
local_path (str): Relative path for v1.2 filesystem layout preservation
contents (list[FileEntry], optional): For OCI images, list of files contained in the image (as layers)

URL Schemes:

https:// – Direct HTTPS URL for CDN distribution
http:// – HTTP URL (testing only)
oci:// – OCI registry reference (must include @sha256:… digest)
Relative path – Local compose path (no scheme)

property is_remote: bool

Check if the location is a remote URL (not a local relative path).

Return type:: bool

property is_https: bool

Check if the location is an HTTPS URL.

Return type:: bool

property is_http: bool

Check if the location is an HTTP URL.

Return type:: bool

property is_oci: bool

Check if the location is an OCI registry reference.

Return type:: bool

property is_local: bool

Check if the location is a local relative path.

Return type:: bool

property has_contents: bool

Check if this location has OCI image contents (multiple files as layers).

Return type:: bool

property checksum_algorithm: str | None

Get the checksum algorithm.

Returns:: Algorithm name (e.g., “sha256”)
Return type:: str or None

property checksum_value: str | None

Get the checksum hex digest value.

Returns:: Hex digest string
Return type:: str or None

property oci_registry: str | None

Get the OCI registry hostname (for OCI URLs).

Returns:: Registry hostname or None
Return type:: str or None

property oci_repository: str | None

Get the OCI repository name (for OCI URLs).

Returns:: Repository name or None
Return type:: str or None

property oci_tag: str | None

Get the OCI image tag (for OCI URLs).

Returns:: Tag or None
Return type:: str or None

property oci_digest: str | None

Get the OCI image digest (for OCI URLs).

Returns:: Digest (sha256:…) or None
Return type:: str or None

serialize(parser: Dict[str, Any] | None = None) → Dict[str, Any]

Serialize Location to a dictionary.

Parameters:: parser (dict or None) – Unused, for API compatibility
Returns:: Dictionary representation
Return type:: dict

deserialize(data: Dict[str, Any]) → None

Deserialize Location from a dictionary.

Parameters:: data (dict) – Dictionary with location data

classmethod from_dict(data: Dict[str, Any]) → Location

Create a Location from a dictionary.

Parameters:: data (dict) – Dictionary with location data
Returns:: New Location instance
Return type:: Location

classmethod from_local_file(path: str, base_dir: str, compute_integrity: bool = True) → Location

Create a Location from a local file.

This is useful when upgrading a v1.2 compose to v2.0 format.

Parameters:

path (str) – Relative path to file (will be used as url and local_path)
base_dir (str) – Base directory for computing checksum
compute_integrity (bool) – Whether to compute checksum and size. When False, size and checksum are left as None. The caller is responsible for setting them before serialization.

Returns:

New Location instance

Return type:

Location

with_remote_url(base_url: str) → Location

Create a new Location with a remote URL based on local_path.

This is useful when publishing a local compose to a CDN.

Parameters:: base_url (str) – Base URL to prepend to local_path
Returns:: New Location instance with remote URL
Return type:: Location

get_localized_path(output_dir: str) → str

Get the full filesystem path for localizing this artifact.

Parameters:: output_dir (str) – Base output directory
Returns:: Full path where artifact should be written
Return type:: str

verify_checksum(path: str) → bool

Verify that a file matches this location’s checksum.

Parameters:: path (str) – Path to file to verify
Returns:: True if checksum matches or no checksum is set, False otherwise
Return type:: bool

verify_size(path: str) → bool

Verify that a file matches this location’s size.

Parameters:: path (str) – Path to file to verify
Returns:: True if size matches or no size is set, False otherwise
Return type:: bool

verify(path: str) → bool

Verify that a file matches this location’s size and checksum.

Parameters:: path (str) – Path to file to verify
Returns:: True if both size and checksum match, False otherwise
Return type:: bool

dump(f)

Dump data to a file.

Parameters:: f (file or str) – file-like object or path to file

dumps()

Dump data to a string.

Return type:: str

load(f)

Load data from a file.

Parameters:: f (file or str) – file-like object or path to file

loads(s)

Load data from a string.

Parameters:: s (str) – input data

validate()

Validate attributes by running all self._validate_*() methods.

Raises:

TypeError – if an attribute has invalid type
ValueError – if an attribute contains invalid value

class productmd.location.FileEntry(file: str | None = None, size: int | None = None, checksum: str | None = None, layer_digest: str | None = None)

Represents a file within an OCI image location.

This is used when an OCI image contains multiple files as layers, such as boot files (kernel, initrd, efiboot.img) bundled together.

Attributes:: file (str): Relative path of the file within the container/image size (int): File size in bytes checksum (str): File checksum in “algorithm:hash” format layer_digest (str): OCI layer digest containing this file