orchestrata_ultimate.cxp.version

Reference › orchestrata_ultimate › cxp › version

version models CXP protocol versions (Spec 004 US-010). ProtocolVersion parses a major.minor.patch string, with a default of 1.0.0 from constants, exposes major, minor and patch, supports equality, ordering and hashing on the version tuple, and converts with to_dict and from_string. is_compatible_with is true when two versions share the same major number. parse_version is the module-level parser. version_compat builds on it. See cxp.

At a glance

Class diagram

Dependency diagram

API

Constants

Classes

ProtocolVersion

Decorators: traces(spec='004', story='US-010', reqs=['REQ-004-US-010-001', 'REQ-004-US-001-012']) · Line 21

Semantic version representation for the CXP protocol.

Functions

Source

Permalink: https://gitlab.com/MSamy/orchestrata-ultimate-architecture/-/blob/a4cbc2bdf/src/orchestrata_ultimate/cxp/version.py

"""CXP Protocol Versioning — Spec 004, Section US-010.

Semantic versioning for the CXP protocol with parsing, comparison,
and compatibility checking.
"""

from __future__ import annotations

import re
from typing import Any

from orchestrata_ultimate.core.base.traces import traces
from orchestrata_ultimate.cxp.constants import PROTOCOL_VERSION, SEMVER_PATTERN


@traces(
    spec="004",
    story="US-010",
    reqs=["REQ-004-US-010-001", "REQ-004-US-001-012"],
)
class ProtocolVersion:
    """Semantic version representation for the CXP protocol."""

    @traces(
        spec="004",
        story="US-001",
        reqs=[
            "REQ-004-US-001-024",
            "REQ-004-US-010-002",
            "REQ-004-US-010-003",
        ],
    )
    def __init__(self, version_string: str = "1.0.0") -> None:
        match = re.match(SEMVER_PATTERN, version_string)
        if not match:
            raise ValueError(
                f"Invalid semver string: {version_string!r}. "
                f"Expected format: major.minor.patch"
            )
        parts = version_string.split(".")
        self._major = int(parts[0])
        self._minor = int(parts[1])
        self._patch = int(parts[2])

    # ── Properties ──────────────────────────────────────────────

    @property
    @traces(spec="004", story="US-010", reqs=["REQ-004-US-010-001"])
    def major(self) -> int:
        return self._major

    @property
    @traces(spec="004", story="US-010", reqs=["REQ-004-US-010-001"])
    def minor(self) -> int:
        return self._minor

    @property
    @traces(spec="004", story="US-010", reqs=["REQ-004-US-010-001"])
    def patch(self) -> int:
        return self._patch

    # ── String / Hash ───────────────────────────────────────────

    def __str__(self) -> str:
        return f"{self._major}.{self._minor}.{self._patch}"

    def __repr__(self) -> str:
        return f"ProtocolVersion('{self}')"

    def __hash__(self) -> int:
        return hash((self._major, self._minor, self._patch))

    # ── Comparison operators ────────────────────────────────────

    def _as_tuple(self) -> tuple[int, int, int]:
        return (self._major, self._minor, self._patch)

    def __eq__(self, other: Any) -> bool:
        if not isinstance(other, ProtocolVersion):
            return NotImplemented
        return self._as_tuple() == other._as_tuple()

    def __lt__(self, other: Any) -> bool:
        if not isinstance(other, ProtocolVersion):
            return NotImplemented
        return self._as_tuple() < other._as_tuple()

    def __le__(self, other: Any) -> bool:
        if not isinstance(other, ProtocolVersion):
            return NotImplemented
        return self._as_tuple() <= other._as_tuple()

    def __gt__(self, other: Any) -> bool:
        if not isinstance(other, ProtocolVersion):
            return NotImplemented
        return self._as_tuple() > other._as_tuple()

    def __ge__(self, other: Any) -> bool:
        if not isinstance(other, ProtocolVersion):
            return NotImplemented
        return self._as_tuple() >= other._as_tuple()

    # ── Compatibility ───────────────────────────────────────────

    @traces(
        spec="004",
        story="US-007",
        reqs=[
            "REQ-004-US-007-017",
            "REQ-004-US-010-006",
        ],
    )
    def is_compatible_with(self, other: ProtocolVersion) -> bool:
        """Two versions are compatible when they share the same major version."""
        return self._major == other._major

    # ── Serialisation helpers ───────────────────────────────────

    def to_dict(self) -> dict[str, int]:
        return {
            "major": self._major,
            "minor": self._minor,
            "patch": self._patch,
        }

    @classmethod
    def from_string(cls, s: str) -> ProtocolVersion:
        return cls(s)


# ── Module-level conveniences ───────────────────────────────────

CURRENT_VERSION: ProtocolVersion = ProtocolVersion(PROTOCOL_VERSION)


@traces(
    spec="004",
    story="US-010",
    reqs=[
        "REQ-004-US-010-003",
    ],
)
def parse_version(s: str) -> ProtocolVersion:
    """Parse a semver string into a ProtocolVersion."""
    return ProtocolVersion(s)