version – Version detection and handling

This module provides version detection and handling utilities for ProductMD metadata.

ProductMD supports multiple metadata format versions:

v1.x (1.0, 1.1, 1.2): Local compose format with relative paths
v2.0: Distributed compose format with Location objects

This module provides utilities to: - Detect the version of parsed metadata - Check version compatibility - Convert between version representations

Example:

from productmd.version import (
    detect_version_from_data,
    is_v1,
    is_v2,
    VERSION_1_2,
    VERSION_2_0,
)

# Detect version from parsed JSON data
data = {"header": {"version": "2.0", "type": "productmd.images"}, "payload": {}}
version = detect_version_from_data(data)
print(version)  # (2, 0)

# Check version type
if is_v2(version):
    print("This is a v2.0 distributed compose")
elif is_v1(version):
    print("This is a v1.x local compose")

# Version constants
print(VERSION_2_0)  # (2, 0)

Constants

productmd.version.VERSION_1_0: Tuple[int, int] = (1, 0)

Built-in immutable sequence.

If no argument is given, the constructor returns an empty tuple. If iterable is specified the tuple is initialized from iterable’s items.

If the argument is a tuple, the return value is the same object.

productmd.version.VERSION_1_1: Tuple[int, int] = (1, 1)

Built-in immutable sequence.

If no argument is given, the constructor returns an empty tuple. If iterable is specified the tuple is initialized from iterable’s items.

If the argument is a tuple, the return value is the same object.

productmd.version.VERSION_1_2: Tuple[int, int] = (1, 2)

Built-in immutable sequence.

If no argument is given, the constructor returns an empty tuple. If iterable is specified the tuple is initialized from iterable’s items.

If the argument is a tuple, the return value is the same object.

productmd.version.VERSION_2_0: Tuple[int, int] = (2, 0)

Built-in immutable sequence.

If no argument is given, the constructor returns an empty tuple. If iterable is specified the tuple is initialized from iterable’s items.

If the argument is a tuple, the return value is the same object.

productmd.version.OUTPUT_FORMAT_VERSION: Tuple[int, int] = (2, 0)

Built-in immutable sequence.

If no argument is given, the constructor returns an empty tuple. If iterable is specified the tuple is initialized from iterable’s items.

If the argument is a tuple, the return value is the same object.

Functions

productmd.version.version_to_string(version: Tuple[int, int]) → str

Convert a version tuple to a string.

Parameters:: version (tuple) – Version tuple (major, minor)
Returns:: Version string like “2.0”
Return type:: str

productmd.version.string_to_version(version_str: str) → Tuple[int, int]

Convert a version string to a tuple.

Parameters:: version_str (str) – Version string like “2.0”
Returns:: Version tuple (major, minor)
Return type:: tuple
Raises:: ValueError – If version string is invalid

productmd.version.get_version_tuple(version: str | Tuple[int, int]) → Tuple[int, int]

Normalize version to a tuple.

Parameters:: version (str or tuple) – Version as string or tuple
Returns:: Version tuple (major, minor)
Return type:: tuple

productmd.version.is_v1(version: str | Tuple[int, int]) → bool

Check if version is v1.x (1.0, 1.1, 1.2).

Parameters:: version (str or tuple) – Version to check
Returns:: True if v1.x
Return type:: bool

productmd.version.is_v2(version: str | Tuple[int, int]) → bool

Check if version is v2.x (2.0+).

Parameters:: version (str or tuple) – Version to check
Returns:: True if v2.x
Return type:: bool

productmd.version.supports_location_objects(version: str | Tuple[int, int]) → bool

Check if version supports Location objects.

Parameters:: version (str or tuple) – Version to check
Returns:: True if Location objects are supported
Return type:: bool

productmd.version.detect_version_from_data(data: Dict[str, Any]) → Tuple[int, int]

Detect the version from parsed metadata.

Parameters:: data (dict) – Parsed JSON data
Returns:: Version tuple (major, minor)
Return type:: tuple
Raises:: ValueError – If version cannot be determined

Classes

class productmd.version.VersionedMetadataMixin

Mixin class providing version-aware serialization/deserialization.

Subclasses can set _default_output_version to control the fallback version used when output_version has not been explicitly set. Defaults to OUTPUT_FORMAT_VERSION.

Usage:

class MyMetadata(MetadataBase, VersionedMetadataMixin):
    def deserialize(self, data):
        version = self.detect_data_version(data)
        if is_v2(version):
            self._deserialize_v2(data)
        else:
            self._deserialize_v1(data)

property output_version: Tuple[int, int]

Get the version to use when serializing.

Returns the instance override if set, otherwise the class default.

Returns:: Version tuple (major, minor)
Return type:: tuple

get_output_version(force_version: Tuple[int, int] | None = None) → Tuple[int, int]

Resolve the effective output version.

Priority: force_version > output_version (instance) > _default_output_version (class)

Parameters:: force_version (tuple or None) – Explicit version override
Returns:: Version tuple
Return type:: tuple

detect_data_version(data: Dict[str, Any]) → Tuple[int, int]

Detect version from parsed data.

Parameters:: data (dict) – Parsed metadata
Returns:: Version tuple
Return type:: tuple

should_use_locations() → bool

Check if Location objects should be used for output.

Returns:: True if using v2.0+ format
Return type:: bool

class productmd.version.VersionError: Base exception for version-related errors.

class productmd.version.UnsupportedVersionError(version: Tuple[int, int], supported: list = None): Raised when a metadata file has an unsupported version.