D7net
Home
Console
Upload
information
Create File
Create Folder
About
Tools
:
/
opt
/
cloudlinux
/
venv
/
lib
/
python3.11
/
site-packages
/
semver
/
Filename :
version.py
back
Copy
"""Version handling by a semver compatible version class.""" import collections import re from functools import wraps from typing import ( Any, Dict, Iterable, Optional, SupportsInt, Tuple, Union, cast, Callable, Collection, Type, TypeVar, ) from ._types import ( VersionTuple, VersionDict, VersionIterator, String, VersionPart, ) # These types are required here because of circular imports Comparable = Union["Version", Dict[str, VersionPart], Collection[VersionPart], str] Comparator = Callable[["Version", Comparable], bool] T = TypeVar("T", bound="Version") def _comparator(operator: Comparator) -> Comparator: """Wrap a Version binary op method in a type-check.""" @wraps(operator) def wrapper(self: "Version", other: Comparable) -> bool: comparable_types = ( Version, dict, tuple, list, *String.__args__, # type: ignore ) if not isinstance(other, comparable_types): return NotImplemented return operator(self, other) return wrapper def _cmp(a, b): # TODO: type hints """Return negative if a<b, zero if a==b, positive if a>b.""" return (a > b) - (a < b) class Version: """ A semver compatible version class. See specification at https://semver.org. :param major: version when you make incompatible API changes. :param minor: version when you add functionality in a backwards-compatible manner. :param patch: version when you make backwards-compatible bug fixes. :param prerelease: an optional prerelease string :param build: an optional build string """ __slots__ = ("_major", "_minor", "_patch", "_prerelease", "_build") #: The names of the different parts of a version NAMES = tuple([item[1:] for item in __slots__]) #: Regex for number in a prerelease _LAST_NUMBER = re.compile(r"(?:[^\d]*(\d+)[^\d]*)+") #: Regex template for a semver version _REGEX_TEMPLATE = r""" ^ (?P<major>0|[1-9]\d*) (?: \. (?P<minor>0|[1-9]\d*) (?: \. (?P<patch>0|[1-9]\d*) ){opt_patch} ){opt_minor} (?:-(?P<prerelease> (?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*) (?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))* ))? (?:\+(?P<build> [0-9a-zA-Z-]+ (?:\.[0-9a-zA-Z-]+)* ))? $ """ #: Regex for a semver version _REGEX = re.compile( _REGEX_TEMPLATE.format(opt_patch="", opt_minor=""), re.VERBOSE, ) #: Regex for a semver version that might be shorter _REGEX_OPTIONAL_MINOR_AND_PATCH = re.compile( _REGEX_TEMPLATE.format(opt_patch="?", opt_minor="?"), re.VERBOSE, ) def __init__( self, major: SupportsInt, minor: SupportsInt = 0, patch: SupportsInt = 0, prerelease: Optional[Union[String, int]] = None, build: Optional[Union[String, int]] = None, ): # Build a dictionary of the arguments except prerelease and build version_parts = {"major": int(major), "minor": int(minor), "patch": int(patch)} for name, value in version_parts.items(): if value < 0: raise ValueError( "{!r} is negative. A version can only be positive.".format(name) ) self._major = version_parts["major"] self._minor = version_parts["minor"] self._patch = version_parts["patch"] self._prerelease = None if prerelease is None else str(prerelease) self._build = None if build is None else str(build) @classmethod def _nat_cmp(cls, a, b): # TODO: type hints def cmp_prerelease_tag(a, b): if isinstance(a, int) and isinstance(b, int): return _cmp(a, b) elif isinstance(a, int): return -1 elif isinstance(b, int): return 1 else: return _cmp(a, b) a, b = a or "", b or "" a_parts, b_parts = a.split("."), b.split(".") a_parts = [int(x) if re.match(r"^\d+$", x) else x for x in a_parts] b_parts = [int(x) if re.match(r"^\d+$", x) else x for x in b_parts] for sub_a, sub_b in zip(a_parts, b_parts): cmp_result = cmp_prerelease_tag(sub_a, sub_b) if cmp_result != 0: return cmp_result else: return _cmp(len(a), len(b)) @property def major(self) -> int: """The major part of a version (read-only).""" return self._major @major.setter def major(self, value): raise AttributeError("attribute 'major' is readonly") @property def minor(self) -> int: """The minor part of a version (read-only).""" return self._minor @minor.setter def minor(self, value): raise AttributeError("attribute 'minor' is readonly") @property def patch(self) -> int: """The patch part of a version (read-only).""" return self._patch @patch.setter def patch(self, value): raise AttributeError("attribute 'patch' is readonly") @property def prerelease(self) -> Optional[str]: """The prerelease part of a version (read-only).""" return self._prerelease @prerelease.setter def prerelease(self, value): raise AttributeError("attribute 'prerelease' is readonly") @property def build(self) -> Optional[str]: """The build part of a version (read-only).""" return self._build @build.setter def build(self, value): raise AttributeError("attribute 'build' is readonly") def to_tuple(self) -> VersionTuple: """ Convert the Version object to a tuple. .. versionadded:: 2.10.0 Renamed :meth:`Version._astuple` to :meth:`Version.to_tuple` to make this function available in the public API. :return: a tuple with all the parts >>> semver.Version(5, 3, 1).to_tuple() (5, 3, 1, None, None) """ return (self.major, self.minor, self.patch, self.prerelease, self.build) def to_dict(self) -> VersionDict: """ Convert the Version object to an OrderedDict. .. versionadded:: 2.10.0 Renamed :meth:`Version._asdict` to :meth:`Version.to_dict` to make this function available in the public API. :return: an OrderedDict with the keys in the order ``major``, ``minor``, ``patch``, ``prerelease``, and ``build``. >>> semver.Version(3, 2, 1).to_dict() OrderedDict([('major', 3), ('minor', 2), ('patch', 1), \ ('prerelease', None), ('build', None)]) """ return collections.OrderedDict( ( ("major", self.major), ("minor", self.minor), ("patch", self.patch), ("prerelease", self.prerelease), ("build", self.build), ) ) def __iter__(self) -> VersionIterator: """Return iter(self).""" yield from self.to_tuple() @staticmethod def _increment_string(string: str) -> str: """ Look for the last sequence of number(s) in a string and increment. :param string: the string to search for. :return: the incremented string Source: http://code.activestate.com/recipes/442460-increment-numbers-in-a-string/#c1 """ match = Version._LAST_NUMBER.search(string) if match: next_ = str(int(match.group(1)) + 1) start, end = match.span(1) string = string[: max(end - len(next_), start)] + next_ + string[end:] return string def bump_major(self) -> "Version": """ Raise the major part of the version, return a new object but leave self untouched. :return: new object with the raised major part >>> ver = semver.parse("3.4.5") >>> ver.bump_major() Version(major=4, minor=0, patch=0, prerelease=None, build=None) """ cls = type(self) return cls(self._major + 1) def bump_minor(self) -> "Version": """ Raise the minor part of the version, return a new object but leave self untouched. :return: new object with the raised minor part >>> ver = semver.parse("3.4.5") >>> ver.bump_minor() Version(major=3, minor=5, patch=0, prerelease=None, build=None) """ cls = type(self) return cls(self._major, self._minor + 1) def bump_patch(self) -> "Version": """ Raise the patch part of the version, return a new object but leave self untouched. :return: new object with the raised patch part >>> ver = semver.parse("3.4.5") >>> ver.bump_patch() Version(major=3, minor=4, patch=6, prerelease=None, build=None) """ cls = type(self) return cls(self._major, self._minor, self._patch + 1) def bump_prerelease(self, token: Optional[str] = "rc") -> "Version": """ Raise the prerelease part of the version, return a new object but leave self untouched. :param token: defaults to ``'rc'`` :return: new :class:`Version` object with the raised prerelease part. The original object is not modified. >>> ver = semver.parse("3.4.5") >>> ver.bump_prerelease().prerelease 'rc.2' >>> ver.bump_prerelease('').prerelease '1' >>> ver.bump_prerelease(None).prerelease 'rc.1' """ cls = type(self) if self._prerelease is not None: prerelease = self._prerelease elif token == "": prerelease = "0" elif token is None: prerelease = "rc.0" else: prerelease = str(token) + ".0" prerelease = cls._increment_string(prerelease) return cls(self._major, self._minor, self._patch, prerelease) def bump_build(self, token: Optional[str] = "build") -> "Version": """ Raise the build part of the version, return a new object but leave self untouched. :param token: defaults to ``'build'`` :return: new :class:`Version` object with the raised build part. The original object is not modified. >>> ver = semver.parse("3.4.5-rc.1+build.9") >>> ver.bump_build() Version(major=3, minor=4, patch=5, prerelease='rc.1', \ build='build.10') """ cls = type(self) if self._build is not None: build = self._build elif token == "": build = "0" elif token is None: build = "build.0" else: build = str(token) + ".0" # self._build or (token or "build") + ".0" build = cls._increment_string(build) if self._build is not None: build = self._build elif token == "": build = "0" elif token is None: build = "build.0" else: build = str(token) + ".0" # self._build or (token or "build") + ".0" build = cls._increment_string(build) return cls(self._major, self._minor, self._patch, self._prerelease, build) def compare(self, other: Comparable) -> int: """ Compare self with other. :param other: the second version :return: The return value is negative if ver1 < ver2, zero if ver1 == ver2 and strictly positive if ver1 > ver2 >>> semver.compare("2.0.0") -1 >>> semver.compare("1.0.0") 1 >>> semver.compare("2.0.0") 0 >>> semver.compare(dict(major=2, minor=0, patch=0)) 0 """ cls = type(self) if isinstance(other, String.__args__): # type: ignore other = cls.parse(other) elif isinstance(other, dict): other = cls(**other) elif isinstance(other, (tuple, list)): other = cls(*other) elif not isinstance(other, cls): raise TypeError( f"Expected str, bytes, dict, tuple, list, or {cls.__name__} instance, " f"but got {type(other)}" ) v1 = self.to_tuple()[:3] v2 = other.to_tuple()[:3] x = _cmp(v1, v2) if x: return x rc1, rc2 = self.prerelease, other.prerelease rccmp = self._nat_cmp(rc1, rc2) if not rccmp: return 0 if not rc1: return 1 elif not rc2: return -1 return rccmp def next_version(self, part: str, prerelease_token: str = "rc") -> "Version": """ Determines next version, preserving natural order. .. versionadded:: 2.10.0 This function is taking prereleases into account. The "major", "minor", and "patch" raises the respective parts like the ``bump_*`` functions. The real difference is using the "prerelease" part. It gives you the next patch version of the prerelease, for example: >>> str(semver.parse("0.1.4").next_version("prerelease")) '0.1.5-rc.1' :param part: One of "major", "minor", "patch", or "prerelease" :param prerelease_token: prefix string of prerelease, defaults to 'rc' :return: new object with the appropriate part raised """ cls = type(self) # "build" is currently not used, that's why we use [:-1] validparts = cls.NAMES[:-1] if part not in validparts: raise ValueError( f"Invalid part. Expected one of {validparts}, but got {part!r}" ) version = self if (version.prerelease or version.build) and ( part == "patch" or (part == "minor" and version.patch == 0) or (part == "major" and version.minor == version.patch == 0) ): return version.replace(prerelease=None, build=None) # Only check the main parts: if part in cls.NAMES[:3]: return getattr(version, "bump_" + part)() if not version.prerelease: version = version.bump_patch() return version.bump_prerelease(prerelease_token) @_comparator def __eq__(self, other: Comparable) -> bool: # type: ignore return self.compare(other) == 0 @_comparator def __ne__(self, other: Comparable) -> bool: # type: ignore return self.compare(other) != 0 @_comparator def __lt__(self, other: Comparable) -> bool: return self.compare(other) < 0 @_comparator def __le__(self, other: Comparable) -> bool: return self.compare(other) <= 0 @_comparator def __gt__(self, other: Comparable) -> bool: return self.compare(other) > 0 @_comparator def __ge__(self, other: Comparable) -> bool: return self.compare(other) >= 0 def __getitem__( self, index: Union[int, slice] ) -> Union[int, Optional[str], Tuple[Union[int, str], ...]]: """ self.__getitem__(index) <==> self[index] Implement getitem. If the part requested is undefined, or a part of the range requested is undefined, it will throw an index error. Negative indices are not supported. :param index: a positive integer indicating the offset or a :func:`slice` object :raises IndexError: if index is beyond the range or a part is None :return: the requested part of the version at position index >>> ver = semver.Version.parse("3.4.5") >>> ver[0], ver[1], ver[2] (3, 4, 5) """ if isinstance(index, int): index = slice(index, index + 1) index = cast(slice, index) if ( isinstance(index, slice) and (index.start is not None and index.start < 0) or (index.stop is not None and index.stop < 0) ): raise IndexError("Version index cannot be negative") part = tuple( filter(lambda p: p is not None, cast(Iterable, self.to_tuple()[index])) ) if len(part) == 1: return part[0] elif not part: raise IndexError("Version part undefined") return part def __repr__(self) -> str: s = ", ".join("%s=%r" % (key, val) for key, val in self.to_dict().items()) return "%s(%s)" % (type(self).__name__, s) def __str__(self) -> str: version = "%d.%d.%d" % (self.major, self.minor, self.patch) if self.prerelease: version += "-%s" % self.prerelease if self.build: version += "+%s" % self.build return version def __hash__(self) -> int: return hash(self.to_tuple()[:4]) def finalize_version(self) -> "Version": """ Remove any prerelease and build metadata from the version. :return: a new instance with the finalized version string >>> str(semver.Version.parse('1.2.3-rc.5').finalize_version()) '1.2.3' """ cls = type(self) return cls(self.major, self.minor, self.patch) def match(self, match_expr: str) -> bool: """ Compare self to match a match expression. :param match_expr: optional operator and version; valid operators are ``<`` smaller than ``>`` greater than ``>=`` greator or equal than ``<=`` smaller or equal than ``==`` equal ``!=`` not equal :return: True if the expression matches the version, otherwise False >>> semver.Version.parse("2.0.0").match(">=1.0.0") True >>> semver.Version.parse("1.0.0").match(">1.0.0") False >>> semver.Version.parse("4.0.4").match("4.0.4") True """ prefix = match_expr[:2] if prefix in (">=", "<=", "==", "!="): match_version = match_expr[2:] elif prefix and prefix[0] in (">", "<"): prefix = prefix[0] match_version = match_expr[1:] elif match_expr and match_expr[0] in "0123456789": prefix = "==" match_version = match_expr else: raise ValueError( "match_expr parameter should be in format <op><ver>, " "where <op> is one of " "['<', '>', '==', '<=', '>=', '!=']. " "You provided: %r" % match_expr ) possibilities_dict = { ">": (1,), "<": (-1,), "==": (0,), "!=": (-1, 1), ">=": (0, 1), "<=": (-1, 0), } possibilities = possibilities_dict[prefix] cmp_res = self.compare(match_version) return cmp_res in possibilities @classmethod def parse( cls: Type[T], version: String, optional_minor_and_patch: bool = False ) -> T: """ Parse version string to a Version instance. .. versionchanged:: 2.11.0 Changed method from static to classmethod to allow subclasses. .. versionchanged:: 3.0.0 Added optional parameter ``optional_minor_and_patch`` to allow optional minor and patch parts. :param version: version string :param optional_minor_and_patch: if set to true, the version string to parse \ can contain optional minor and patch parts. Optional parts are set to zero. By default (False), the version string to parse has to follow the semver specification. :return: a new :class:`Version` instance :raises ValueError: if version is invalid :raises TypeError: if version contains the wrong type >>> semver.Version.parse('3.4.5-pre.2+build.4') Version(major=3, minor=4, patch=5, \ prerelease='pre.2', build='build.4') """ if isinstance(version, bytes): version = version.decode("UTF-8") elif not isinstance(version, String.__args__): # type: ignore raise TypeError("not expecting type '%s'" % type(version)) if optional_minor_and_patch: match = cls._REGEX_OPTIONAL_MINOR_AND_PATCH.match(version) else: match = cls._REGEX.match(version) if match is None: raise ValueError(f"{version} is not valid SemVer string") matched_version_parts: Dict[str, Any] = match.groupdict() if not matched_version_parts["minor"]: matched_version_parts["minor"] = 0 if not matched_version_parts["patch"]: matched_version_parts["patch"] = 0 return cls(**matched_version_parts) def replace(self, **parts: Union[int, Optional[str]]) -> "Version": """ Replace one or more parts of a version and return a new :class:`Version` object, but leave self untouched .. versionadded:: 2.9.0 Added :func:`Version.replace` :param parts: the parts to be updated. Valid keys are: ``major``, ``minor``, ``patch``, ``prerelease``, or ``build`` :return: the new :class:`~semver.version.Version` object with the changed parts :raises TypeError: if ``parts`` contain invalid keys """ version = self.to_dict() version.update(parts) try: return Version(**version) # type: ignore except TypeError: unknownkeys = set(parts) - set(self.to_dict()) error = "replace() got %d unexpected keyword argument(s): %s" % ( len(unknownkeys), ", ".join(unknownkeys), ) raise TypeError(error) @classmethod def is_valid(cls, version: str) -> bool: """ Check if the string is a valid semver version. .. versionadded:: 2.9.1 .. versionchanged:: 3.0.0 Renamed from :meth:`~semver.version.Version.isvalid` :param version: the version string to check :return: True if the version string is a valid semver version, False otherwise. """ try: cls.parse(version) return True except ValueError: return False def is_compatible(self, other: "Version") -> bool: """ Check if current version is compatible with other version. The result is True, if either of the following is true: * both versions are equal, or * both majors are equal and higher than 0. Same for both minors. Both pre-releases are equal, or * both majors are equal and higher than 0. The minor of b's minor version is higher then a's. Both pre-releases are equal. The algorithm does *not* check patches. .. versionadded:: 3.0.0 :param other: the version to check for compatibility :return: True, if ``other`` is compatible with the old version, otherwise False >>> Version(1, 1, 0).is_compatible(Version(1, 0, 0)) False >>> Version(1, 0, 0).is_compatible(Version(1, 1, 0)) True """ if not isinstance(other, Version): raise TypeError(f"Expected a Version type but got {type(other)}") # All major-0 versions should be incompatible with anything but itself if (0 == self.major == other.major) and (self[:4] != other[:4]): return False return ( (self.major == other.major) and (other.minor >= self.minor) and (self.prerelease == other.prerelease) ) #: Keep the VersionInfo name for compatibility VersionInfo = Version