Semver API Reference¶

class InvalidVersion(ValueError):
    """Raised when a version string does not conform to PEP 440."""

@functools.total_ordering
class Version:
    """A PEP 440 version.

    Args:
        version: A PEP 440 compliant version string.

    Raises:
        InvalidVersion: If *version* does not conform to PEP 440.

    Example::

        >>> v = Version("1.2.3rc1")
        >>> v.is_prerelease
        True
        >>> str(v)
        '1.2.3rc1'
    """

    __slots__ = (
        "_epoch",
        "_release",
        "_pre",
        "_post",
        "_dev",
        "_local",
        "_key",
        "_str",
    )

    def __init__(self, version: str) -> None:
        match = _VERSION_RE.match(version)
        if not match:
            raise InvalidVersion(f"Invalid version: {version!r}")

        # Extract all groups at once via positional tuple (fastest).
        # Index map: 0=epoch, 1=release, 2=pre, 3=pre_l, 4=pre_n,
        #   5=post, 6=post_n1, 7=post_l, 8=post_n2, 9=dev, 10=dev_l,
        #   11=dev_n, 12=local
        (
            g_epoch,
            g_release,
            _,
            g_pre_l,
            g_pre_n,
            _,
            g_post_n1,
            g_post_l,
            g_post_n2,
            _,
            g_dev_l,
            g_dev_n,
            g_local,
        ) = match.groups()

        # ── Parse components ────────────────────────────────────────
        epoch = int(g_epoch) if g_epoch else 0
        release = tuple(map(int, g_release.split(".")))

        # Pre-release
        if g_pre_l:
            pre_letter = _PRE_NORMALIZE[g_pre_l.lower()]
            pre_num = int(g_pre_n) if g_pre_n else 0
            pre: tuple[str, int] | None = (pre_letter, pre_num)
        else:
            pre = None

        # Post-release
        if g_post_l:
            post_num = int(g_post_n2) if g_post_n2 else 0
            post: tuple[str, int] | None = ("post", post_num)
        elif g_post_n1 is not None:
            post = ("post", int(g_post_n1))
        else:
            post = None

        # Dev-release
        if g_dev_l:
            dev_num = int(g_dev_n) if g_dev_n else 0
            dev: tuple[str, int] | None = ("dev", dev_num)
        else:
            dev = None

        # Local version
        if g_local is not None:
            local: tuple[int | str, ...] | None = tuple(
                int(p) if p.isdigit() else p.lower()
                for p in _LOCAL_SPLIT_RE.split(g_local)
            )
        else:
            local = None

        self._epoch = epoch
        self._release = release
        self._pre = pre
        self._post = post
        self._dev = dev
        self._local = local

        # ── Build comparison key (inlined _cmpkey) ──────────────────
        # Strip trailing zeros from release for comparison.
        cmp_release = release
        i = len(release) - 1
        while i > 0 and release[i] == 0:
            i -= 1
        if i < len(release) - 1:
            cmp_release = release[: i + 1]

        # Pre-release key: dev-only < pre-release < final
        if pre is None and post is None and dev is not None:
            cmp_pre = _PRE_SENTINEL_NEG
        elif pre is not None:
            cmp_pre = (_PRE_LETTER_INT[pre[0]], pre[1])
        else:
            cmp_pre = _PRE_SENTINEL_INF

        # Post-release key: absent sorts before any post
        cmp_post = (0, post[1]) if post is not None else _POST_SENTINEL_NEG

        # Dev-release key: absent sorts after any dev
        cmp_dev = (0, dev[1]) if dev is not None else _DEV_SENTINEL_INF

        # Local version key: absent sorts before any local
        if local is None:
            cmp_local: tuple[tuple[int, ...] | tuple[int, str], ...] = (
                _LOCAL_SENTINEL_NEG
            )
        else:
            cmp_local = tuple((p, "") if isinstance(p, int) else (-1, p) for p in local)

        self._key = (epoch, cmp_release, cmp_pre, cmp_post, cmp_dev, cmp_local)
        self._str: str | None = None  # lazy-cached canonical string

    # ── Comparison ───────────────────────────────────────────────────

    def __eq__(self, other: object) -> bool:
        if not isinstance(other, Version):
            return NotImplemented
        return self._key == other._key

    def __lt__(self, other: object) -> bool:
        if not isinstance(other, Version):
            return NotImplemented
        return self._key < other._key

    def __hash__(self) -> int:
        return hash(self._key)

    # ── String representations ───────────────────────────────────────

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

    def __str__(self) -> str:
        cached = self._str
        if cached is not None:
            return cached
        parts: list[str] = []
        if self._epoch != 0:
            parts.append(f"{self._epoch}!")
        parts.append(".".join(map(str, self._release)))
        if self._pre is not None:
            parts.append(f"{self._pre[0]}{self._pre[1]}")
        if self._post is not None:
            parts.append(f".post{self._post[1]}")
        if self._dev is not None:
            parts.append(f".dev{self._dev[1]}")
        if self._local is not None:
            parts.append("+")
            parts.append(".".join(str(x) for x in self._local))
        result = "".join(parts)
        self._str = result
        return result

    # ── Public properties ────────────────────────────────────────────

    @property
    def epoch(self) -> int:
        """The epoch segment of the version (``0`` when absent)."""
        return self._epoch

    @property
    def release(self) -> tuple[int, ...]:
        """The release segment as a tuple of integers."""
        return self._release

    @property
    def pre(self) -> tuple[str, int] | None:
        """The pre-release tag as ``(letter, number)`` or ``None``."""
        return self._pre

    @property
    def post(self) -> int | None:
        """The post-release number, or ``None``."""
        return self._post[1] if self._post else None

    @property
    def dev(self) -> int | None:
        """The dev-release number, or ``None``."""
        return self._dev[1] if self._dev else None

    @property
    def local(self) -> str | None:
        """The local version label, or ``None``."""
        if self._local is None:
            return None
        return ".".join(str(x) for x in self._local)

    @property
    def is_prerelease(self) -> bool:
        """``True`` if this is a pre-release or dev-release version."""
        return self._dev is not None or self._pre is not None

    @property
    def is_devrelease(self) -> bool:
        """``True`` if this is a dev-release version."""
        return self._dev is not None

    @property
    def is_postrelease(self) -> bool:
        """``True`` if this is a post-release version."""
        return self._post is not None

    @property
    def major(self) -> int:
        """The first component of the release segment."""
        return self._release[0]

    @property
    def minor(self) -> int:
        """The second component (``0`` if absent)."""
        return self._release[1] if len(self._release) > 1 else 0

    @property
    def micro(self) -> int:
        """The third component (``0`` if absent)."""
        return self._release[2] if len(self._release) > 2 else 0

    @property
    def base_version(self) -> str:
        """The version without pre/post/dev/local suffixes."""
        parts: list[str] = []
        if self._epoch != 0:
            parts.append(f"{self._epoch}!")
        parts.append(".".join(str(x) for x in self._release))
        return "".join(parts)

    @property
    def public(self) -> str:
        """The version without the local segment."""
        return str(self).split("+", 1)[0]