Source code for setuptools.extern.packaging.version

# This file is dual licensed under the terms of the Apache License, Version
# 2.0, and the BSD License. See the LICENSE file in the root of this repository
# for complete details.
.. testsetup::

    from packaging.version import parse, Version

import collections
import itertools
import re
from typing import Any, Callable, Optional, SupportsInt, Tuple, Union

from ._structures import Infinity, InfinityType, NegativeInfinity, NegativeInfinityType

__all__ = ["VERSION_PATTERN", "parse", "Version", "InvalidVersion"]

InfiniteTypes = Union[InfinityType, NegativeInfinityType]
PrePostDevType = Union[InfiniteTypes, Tuple[str, int]]
SubLocalType = Union[InfiniteTypes, int, str]
LocalType = Union[
            Tuple[SubLocalType, str],
            Tuple[NegativeInfinityType, SubLocalType],
CmpKey = Tuple[
    int, Tuple[int, ...], PrePostDevType, PrePostDevType, PrePostDevType, LocalType
VersionComparisonMethod = Callable[[CmpKey, CmpKey], bool]

_Version = collections.namedtuple(
    "_Version", ["epoch", "release", "dev", "pre", "post", "local"]

def parse(version: str) -> "Version":
    """Parse the given version string.

    >>> parse('1.0.dev1')

    :param version: The version string to parse.
    :raises InvalidVersion: When the version string is not a valid version.
    return Version(version)

[docs] class InvalidVersion(ValueError): """Raised when a version string is not a valid version. >>> Version("invalid") Traceback (most recent call last): ... packaging.version.InvalidVersion: Invalid version: 'invalid' """
class _BaseVersion: _key: Tuple[Any, ...] def __hash__(self) -> int: return hash(self._key) # Please keep the duplicated `isinstance` check # in the six comparisons hereunder # unless you find a way to avoid adding overhead function calls. def __lt__(self, other: "_BaseVersion") -> bool: if not isinstance(other, _BaseVersion): return NotImplemented return self._key < other._key def __le__(self, other: "_BaseVersion") -> bool: if not isinstance(other, _BaseVersion): return NotImplemented return self._key <= other._key def __eq__(self, other: object) -> bool: if not isinstance(other, _BaseVersion): return NotImplemented return self._key == other._key def __ge__(self, other: "_BaseVersion") -> bool: if not isinstance(other, _BaseVersion): return NotImplemented return self._key >= other._key def __gt__(self, other: "_BaseVersion") -> bool: if not isinstance(other, _BaseVersion): return NotImplemented return self._key > other._key def __ne__(self, other: object) -> bool: if not isinstance(other, _BaseVersion): return NotImplemented return self._key != other._key # Deliberately not anchored to the start and end of the string, to make it # easier for 3rd party code to reuse _VERSION_PATTERN = r""" v? (?: (?:(?P<epoch>[0-9]+)!)? # epoch (?P<release>[0-9]+(?:\.[0-9]+)*) # release segment (?P<pre> # pre-release [-_\.]? (?P<pre_l>(a|b|c|rc|alpha|beta|pre|preview)) [-_\.]? (?P<pre_n>[0-9]+)? )? (?P<post> # post release (?:-(?P<post_n1>[0-9]+)) | (?: [-_\.]? (?P<post_l>post|rev|r) [-_\.]? (?P<post_n2>[0-9]+)? ) )? (?P<dev> # dev release [-_\.]? (?P<dev_l>dev) [-_\.]? (?P<dev_n>[0-9]+)? )? ) (?:\+(?P<local>[a-z0-9]+(?:[-_\.][a-z0-9]+)*))? # local version """ VERSION_PATTERN = _VERSION_PATTERN """ A string containing the regular expression used to match a valid version. The pattern is not anchored at either end, and is intended for embedding in larger expressions (for example, matching a version number as part of a file name). The regular expression should be compiled with the ``re.VERBOSE`` and ``re.IGNORECASE`` flags set. :meta hide-value: """ class Version(_BaseVersion): """This class abstracts handling of a project's versions. A :class:`Version` instance is comparison aware and can be compared and sorted using the standard Python interfaces. >>> v1 = Version("1.0a5") >>> v2 = Version("1.0") >>> v1 <Version('1.0a5')> >>> v2 <Version('1.0')> >>> v1 < v2 True >>> v1 == v2 False >>> v1 > v2 False >>> v1 >= v2 False >>> v1 <= v2 True """ _regex = re.compile(r"^\s*" + VERSION_PATTERN + r"\s*$", re.VERBOSE | re.IGNORECASE) _key: CmpKey def __init__(self, version: str) -> None: """Initialize a Version object. :param version: The string representation of a version which will be parsed and normalized before use. :raises InvalidVersion: If the ``version`` does not conform to PEP 440 in any way then this exception will be raised. """ # Validate the version and parse it into pieces match = if not match: raise InvalidVersion(f"Invalid version: '{version}'") # Store the parsed out pieces of the version self._version = _Version( epoch=int("epoch")) if"epoch") else 0, release=tuple(int(i) for i in"release").split(".")), pre=_parse_letter_version("pre_l"),"pre_n")), post=_parse_letter_version("post_l"),"post_n1") or"post_n2") ), dev=_parse_letter_version("dev_l"),"dev_n")), local=_parse_local_version("local")), ) # Generate a key which will be used for sorting self._key = _cmpkey( self._version.epoch, self._version.release, self._version.pre,,, self._version.local, ) def __repr__(self) -> str: """A representation of the Version that shows all internal state. >>> Version('1.0.0') <Version('1.0.0')> """ return f"<Version('{self}')>" def __str__(self) -> str: """A string representation of the version that can be rounded-tripped. >>> str(Version("1.0a5")) '1.0a5' """ parts = [] # Epoch if self.epoch != 0: parts.append(f"{self.epoch}!") # Release segment parts.append(".".join(str(x) for x in self.release)) # Pre-release if self.pre is not None: parts.append("".join(str(x) for x in self.pre)) # Post-release if is not None: parts.append(f".post{}") # Development release if is not None: parts.append(f".dev{}") # Local version segment if self.local is not None: parts.append(f"+{self.local}") return "".join(parts) @property def epoch(self) -> int: """The epoch of the version. >>> Version("2.0.0").epoch 0 >>> Version("1!2.0.0").epoch 1 """ _epoch: int = self._version.epoch return _epoch @property def release(self) -> Tuple[int, ...]: """The components of the "release" segment of the version. >>> Version("1.2.3").release (1, 2, 3) >>> Version("2.0.0").release (2, 0, 0) >>> Version("1!2.0.0.post0").release (2, 0, 0) Includes trailing zeroes but not the epoch or any pre-release / development / post-release suffixes. """ _release: Tuple[int, ...] = self._version.release return _release @property def pre(self) -> Optional[Tuple[str, int]]: """The pre-release segment of the version. >>> print(Version("1.2.3").pre) None >>> Version("1.2.3a1").pre ('a', 1) >>> Version("1.2.3b1").pre ('b', 1) >>> Version("1.2.3rc1").pre ('rc', 1) """ _pre: Optional[Tuple[str, int]] = self._version.pre return _pre @property def post(self) -> Optional[int]: """The post-release number of the version. >>> print(Version("1.2.3").post) None >>> Version("1.2.3.post1").post 1 """ return[1] if else None @property def dev(self) -> Optional[int]: """The development number of the version. >>> print(Version("1.2.3").dev) None >>> Version("1.2.3.dev1").dev 1 """ return[1] if else None @property def local(self) -> Optional[str]: """The local version segment of the version. >>> print(Version("1.2.3").local) None >>> Version("1.2.3+abc").local 'abc' """ if self._version.local: return ".".join(str(x) for x in self._version.local) else: return None @property def public(self) -> str: """The public portion of the version. >>> Version("1.2.3").public '1.2.3' >>> Version("1.2.3+abc").public '1.2.3' >>> Version("1.2.3+abc.dev1").public '1.2.3' """ return str(self).split("+", 1)[0] @property def base_version(self) -> str: """The "base version" of the version. >>> Version("1.2.3").base_version '1.2.3' >>> Version("1.2.3+abc").base_version '1.2.3' >>> Version("1!1.2.3+abc.dev1").base_version '1!1.2.3' The "base version" is the public version of the project without any pre or post release markers. """ parts = [] # Epoch if self.epoch != 0: parts.append(f"{self.epoch}!") # Release segment parts.append(".".join(str(x) for x in self.release)) return "".join(parts) @property def is_prerelease(self) -> bool: """Whether this version is a pre-release. >>> Version("1.2.3").is_prerelease False >>> Version("1.2.3a1").is_prerelease True >>> Version("1.2.3b1").is_prerelease True >>> Version("1.2.3rc1").is_prerelease True >>> Version("1.2.3dev1").is_prerelease True """ return is not None or self.pre is not None @property def is_postrelease(self) -> bool: """Whether this version is a post-release. >>> Version("1.2.3").is_postrelease False >>> Version("1.2.3.post1").is_postrelease True """ return is not None @property def is_devrelease(self) -> bool: """Whether this version is a development release. >>> Version("1.2.3").is_devrelease False >>> Version("1.2.3.dev1").is_devrelease True """ return is not None @property def major(self) -> int: """The first item of :attr:`release` or ``0`` if unavailable. >>> Version("1.2.3").major 1 """ return self.release[0] if len(self.release) >= 1 else 0 @property def minor(self) -> int: """The second item of :attr:`release` or ``0`` if unavailable. >>> Version("1.2.3").minor 2 >>> Version("1").minor 0 """ return self.release[1] if len(self.release) >= 2 else 0 @property def micro(self) -> int: """The third item of :attr:`release` or ``0`` if unavailable. >>> Version("1.2.3").micro 3 >>> Version("1").micro 0 """ return self.release[2] if len(self.release) >= 3 else 0 def _parse_letter_version( letter: str, number: Union[str, bytes, SupportsInt] ) -> Optional[Tuple[str, int]]: if letter: # We consider there to be an implicit 0 in a pre-release if there is # not a numeral associated with it. if number is None: number = 0 # We normalize any letters to their lower case form letter = letter.lower() # We consider some words to be alternate spellings of other words and # in those cases we want to normalize the spellings to our preferred # spelling. if letter == "alpha": letter = "a" elif letter == "beta": letter = "b" elif letter in ["c", "pre", "preview"]: letter = "rc" elif letter in ["rev", "r"]: letter = "post" return letter, int(number) if not letter and number: # We assume if we are given a number, but we are not given a letter # then this is using the implicit post release syntax (e.g. 1.0-1) letter = "post" return letter, int(number) return None _local_version_separators = re.compile(r"[\._-]") def _parse_local_version(local: str) -> Optional[LocalType]: """ Takes a string like abc.1.twelve and turns it into ("abc", 1, "twelve"). """ if local is not None: return tuple( part.lower() if not part.isdigit() else int(part) for part in _local_version_separators.split(local) ) return None def _cmpkey( epoch: int, release: Tuple[int, ...], pre: Optional[Tuple[str, int]], post: Optional[Tuple[str, int]], dev: Optional[Tuple[str, int]], local: Optional[Tuple[SubLocalType]], ) -> CmpKey: # When we compare a release version, we want to compare it with all of the # trailing zeros removed. So we'll use a reverse the list, drop all the now # leading zeros until we come to something non zero, then take the rest # re-reverse it back into the correct order and make it a tuple and use # that for our sorting key. _release = tuple( reversed(list(itertools.dropwhile(lambda x: x == 0, reversed(release)))) ) # We need to "trick" the sorting algorithm to put 1.0.dev0 before 1.0a0. # We'll do this by abusing the pre segment, but we _only_ want to do this # if there is not a pre or a post segment. If we have one of those then # the normal sorting rules will handle this case correctly. if pre is None and post is None and dev is not None: _pre: PrePostDevType = NegativeInfinity # Versions without a pre-release (except as noted above) should sort after # those with one. elif pre is None: _pre = Infinity else: _pre = pre # Versions without a post segment should sort before those with one. if post is None: _post: PrePostDevType = NegativeInfinity else: _post = post # Versions without a development segment should sort after those with one. if dev is None: _dev: PrePostDevType = Infinity else: _dev = dev if local is None: # Versions without a local segment should sort before those with one. _local: LocalType = NegativeInfinity else: # Versions with a local segment need that segment parsed to implement # the sorting rules in PEP440. # - Alpha numeric segments sort before numeric segments # - Alpha numeric segments sort lexicographically # - Numeric segments sort numerically # - Shorter versions sort before longer versions when the prefixes # match exactly _local = tuple( (i, "") if isinstance(i, int) else (NegativeInfinity, i) for i in local ) return epoch, _release, _pre, _post, _dev, _local