450 lines
15 KiB
Python
450 lines
15 KiB
Python
"""Implementation of the versioning scheme defined in PEP 386."""
|
|
|
|
import re
|
|
|
|
from packaging.errors import IrrationalVersionError, HugeMajorVersionNumError
|
|
|
|
__all__ = ['NormalizedVersion', 'suggest_normalized_version',
|
|
'VersionPredicate', 'is_valid_version', 'is_valid_versions',
|
|
'is_valid_predicate']
|
|
|
|
# A marker used in the second and third parts of the `parts` tuple, for
|
|
# versions that don't have those segments, to sort properly. An example
|
|
# of versions in sort order ('highest' last):
|
|
# 1.0b1 ((1,0), ('b',1), ('f',))
|
|
# 1.0.dev345 ((1,0), ('f',), ('dev', 345))
|
|
# 1.0 ((1,0), ('f',), ('f',))
|
|
# 1.0.post256.dev345 ((1,0), ('f',), ('f', 'post', 256, 'dev', 345))
|
|
# 1.0.post345 ((1,0), ('f',), ('f', 'post', 345, 'f'))
|
|
# ^ ^ ^
|
|
# 'b' < 'f' ---------------------/ | |
|
|
# | |
|
|
# 'dev' < 'f' < 'post' -------------------/ |
|
|
# |
|
|
# 'dev' < 'f' ----------------------------------------------/
|
|
# Other letters would do, but 'f' for 'final' is kind of nice.
|
|
_FINAL_MARKER = ('f',)
|
|
|
|
_VERSION_RE = re.compile(r'''
|
|
^
|
|
(?P<version>\d+\.\d+) # minimum 'N.N'
|
|
(?P<extraversion>(?:\.\d+)*) # any number of extra '.N' segments
|
|
(?:
|
|
(?P<prerel>[abc]|rc) # 'a'=alpha, 'b'=beta, 'c'=release candidate
|
|
# 'rc'= alias for release candidate
|
|
(?P<prerelversion>\d+(?:\.\d+)*)
|
|
)?
|
|
(?P<postdev>(\.post(?P<post>\d+))?(\.dev(?P<dev>\d+))?)?
|
|
$''', re.VERBOSE)
|
|
|
|
|
|
class NormalizedVersion:
|
|
"""A rational version.
|
|
|
|
Good:
|
|
1.2 # equivalent to "1.2.0"
|
|
1.2.0
|
|
1.2a1
|
|
1.2.3a2
|
|
1.2.3b1
|
|
1.2.3c1
|
|
1.2.3.4
|
|
TODO: fill this out
|
|
|
|
Bad:
|
|
1 # mininum two numbers
|
|
1.2a # release level must have a release serial
|
|
1.2.3b
|
|
"""
|
|
def __init__(self, s, error_on_huge_major_num=True):
|
|
"""Create a NormalizedVersion instance from a version string.
|
|
|
|
@param s {str} The version string.
|
|
@param error_on_huge_major_num {bool} Whether to consider an
|
|
apparent use of a year or full date as the major version number
|
|
an error. Default True. One of the observed patterns on PyPI before
|
|
the introduction of `NormalizedVersion` was version numbers like
|
|
this:
|
|
2009.01.03
|
|
20040603
|
|
2005.01
|
|
This guard is here to strongly encourage the package author to
|
|
use an alternate version, because a release deployed into PyPI
|
|
and, e.g. downstream Linux package managers, will forever remove
|
|
the possibility of using a version number like "1.0" (i.e.
|
|
where the major number is less than that huge major number).
|
|
"""
|
|
self.is_final = True # by default, consider a version as final.
|
|
self._parse(s, error_on_huge_major_num)
|
|
|
|
@classmethod
|
|
def from_parts(cls, version, prerelease=_FINAL_MARKER,
|
|
devpost=_FINAL_MARKER):
|
|
return cls(cls.parts_to_str((version, prerelease, devpost)))
|
|
|
|
def _parse(self, s, error_on_huge_major_num=True):
|
|
"""Parses a string version into parts."""
|
|
match = _VERSION_RE.search(s)
|
|
if not match:
|
|
raise IrrationalVersionError(s)
|
|
|
|
groups = match.groupdict()
|
|
parts = []
|
|
|
|
# main version
|
|
block = self._parse_numdots(groups['version'], s, False, 2)
|
|
extraversion = groups.get('extraversion')
|
|
if extraversion not in ('', None):
|
|
block += self._parse_numdots(extraversion[1:], s)
|
|
parts.append(tuple(block))
|
|
|
|
# prerelease
|
|
prerel = groups.get('prerel')
|
|
if prerel is not None:
|
|
block = [prerel]
|
|
block += self._parse_numdots(groups.get('prerelversion'), s,
|
|
pad_zeros_length=1)
|
|
parts.append(tuple(block))
|
|
self.is_final = False
|
|
else:
|
|
parts.append(_FINAL_MARKER)
|
|
|
|
# postdev
|
|
if groups.get('postdev'):
|
|
post = groups.get('post')
|
|
dev = groups.get('dev')
|
|
postdev = []
|
|
if post is not None:
|
|
postdev.extend((_FINAL_MARKER[0], 'post', int(post)))
|
|
if dev is None:
|
|
postdev.append(_FINAL_MARKER[0])
|
|
if dev is not None:
|
|
postdev.extend(('dev', int(dev)))
|
|
self.is_final = False
|
|
parts.append(tuple(postdev))
|
|
else:
|
|
parts.append(_FINAL_MARKER)
|
|
self.parts = tuple(parts)
|
|
if error_on_huge_major_num and self.parts[0][0] > 1980:
|
|
raise HugeMajorVersionNumError("huge major version number, %r, "
|
|
"which might cause future problems: %r" % (self.parts[0][0], s))
|
|
|
|
def _parse_numdots(self, s, full_ver_str, drop_trailing_zeros=True,
|
|
pad_zeros_length=0):
|
|
"""Parse 'N.N.N' sequences, return a list of ints.
|
|
|
|
@param s {str} 'N.N.N...' sequence to be parsed
|
|
@param full_ver_str {str} The full version string from which this
|
|
comes. Used for error strings.
|
|
@param drop_trailing_zeros {bool} Whether to drop trailing zeros
|
|
from the returned list. Default True.
|
|
@param pad_zeros_length {int} The length to which to pad the
|
|
returned list with zeros, if necessary. Default 0.
|
|
"""
|
|
nums = []
|
|
for n in s.split("."):
|
|
if len(n) > 1 and n[0] == '0':
|
|
raise IrrationalVersionError("cannot have leading zero in "
|
|
"version number segment: '%s' in %r" % (n, full_ver_str))
|
|
nums.append(int(n))
|
|
if drop_trailing_zeros:
|
|
while nums and nums[-1] == 0:
|
|
nums.pop()
|
|
while len(nums) < pad_zeros_length:
|
|
nums.append(0)
|
|
return nums
|
|
|
|
def __str__(self):
|
|
return self.parts_to_str(self.parts)
|
|
|
|
@classmethod
|
|
def parts_to_str(cls, parts):
|
|
"""Transforms a version expressed in tuple into its string
|
|
representation."""
|
|
# XXX This doesn't check for invalid tuples
|
|
main, prerel, postdev = parts
|
|
s = '.'.join(str(v) for v in main)
|
|
if prerel is not _FINAL_MARKER:
|
|
s += prerel[0]
|
|
s += '.'.join(str(v) for v in prerel[1:])
|
|
if postdev and postdev is not _FINAL_MARKER:
|
|
if postdev[0] == 'f':
|
|
postdev = postdev[1:]
|
|
i = 0
|
|
while i < len(postdev):
|
|
if i % 2 == 0:
|
|
s += '.'
|
|
s += str(postdev[i])
|
|
i += 1
|
|
return s
|
|
|
|
def __repr__(self):
|
|
return "%s('%s')" % (self.__class__.__name__, self)
|
|
|
|
def _cannot_compare(self, other):
|
|
raise TypeError("cannot compare %s and %s"
|
|
% (type(self).__name__, type(other).__name__))
|
|
|
|
def __eq__(self, other):
|
|
if not isinstance(other, NormalizedVersion):
|
|
self._cannot_compare(other)
|
|
return self.parts == other.parts
|
|
|
|
def __lt__(self, other):
|
|
if not isinstance(other, NormalizedVersion):
|
|
self._cannot_compare(other)
|
|
return self.parts < other.parts
|
|
|
|
def __ne__(self, other):
|
|
return not self.__eq__(other)
|
|
|
|
def __gt__(self, other):
|
|
return not (self.__lt__(other) or self.__eq__(other))
|
|
|
|
def __le__(self, other):
|
|
return self.__eq__(other) or self.__lt__(other)
|
|
|
|
def __ge__(self, other):
|
|
return self.__eq__(other) or self.__gt__(other)
|
|
|
|
# See http://docs.python.org/reference/datamodel#object.__hash__
|
|
def __hash__(self):
|
|
return hash(self.parts)
|
|
|
|
|
|
def suggest_normalized_version(s):
|
|
"""Suggest a normalized version close to the given version string.
|
|
|
|
If you have a version string that isn't rational (i.e. NormalizedVersion
|
|
doesn't like it) then you might be able to get an equivalent (or close)
|
|
rational version from this function.
|
|
|
|
This does a number of simple normalizations to the given string, based
|
|
on observation of versions currently in use on PyPI. Given a dump of
|
|
those version during PyCon 2009, 4287 of them:
|
|
- 2312 (53.93%) match NormalizedVersion without change
|
|
with the automatic suggestion
|
|
- 3474 (81.04%) match when using this suggestion method
|
|
|
|
@param s {str} An irrational version string.
|
|
@returns A rational version string, or None, if couldn't determine one.
|
|
"""
|
|
try:
|
|
NormalizedVersion(s)
|
|
return s # already rational
|
|
except IrrationalVersionError:
|
|
pass
|
|
|
|
rs = s.lower()
|
|
|
|
# part of this could use maketrans
|
|
for orig, repl in (('-alpha', 'a'), ('-beta', 'b'), ('alpha', 'a'),
|
|
('beta', 'b'), ('rc', 'c'), ('-final', ''),
|
|
('-pre', 'c'),
|
|
('-release', ''), ('.release', ''), ('-stable', ''),
|
|
('+', '.'), ('_', '.'), (' ', ''), ('.final', ''),
|
|
('final', '')):
|
|
rs = rs.replace(orig, repl)
|
|
|
|
# if something ends with dev or pre, we add a 0
|
|
rs = re.sub(r"pre$", r"pre0", rs)
|
|
rs = re.sub(r"dev$", r"dev0", rs)
|
|
|
|
# if we have something like "b-2" or "a.2" at the end of the
|
|
# version, that is pobably beta, alpha, etc
|
|
# let's remove the dash or dot
|
|
rs = re.sub(r"([abc]|rc)[\-\.](\d+)$", r"\1\2", rs)
|
|
|
|
# 1.0-dev-r371 -> 1.0.dev371
|
|
# 0.1-dev-r79 -> 0.1.dev79
|
|
rs = re.sub(r"[\-\.](dev)[\-\.]?r?(\d+)$", r".\1\2", rs)
|
|
|
|
# Clean: 2.0.a.3, 2.0.b1, 0.9.0~c1
|
|
rs = re.sub(r"[.~]?([abc])\.?", r"\1", rs)
|
|
|
|
# Clean: v0.3, v1.0
|
|
if rs.startswith('v'):
|
|
rs = rs[1:]
|
|
|
|
# Clean leading '0's on numbers.
|
|
#TODO: unintended side-effect on, e.g., "2003.05.09"
|
|
# PyPI stats: 77 (~2%) better
|
|
rs = re.sub(r"\b0+(\d+)(?!\d)", r"\1", rs)
|
|
|
|
# Clean a/b/c with no version. E.g. "1.0a" -> "1.0a0". Setuptools infers
|
|
# zero.
|
|
# PyPI stats: 245 (7.56%) better
|
|
rs = re.sub(r"(\d+[abc])$", r"\g<1>0", rs)
|
|
|
|
# the 'dev-rNNN' tag is a dev tag
|
|
rs = re.sub(r"\.?(dev-r|dev\.r)\.?(\d+)$", r".dev\2", rs)
|
|
|
|
# clean the - when used as a pre delimiter
|
|
rs = re.sub(r"-(a|b|c)(\d+)$", r"\1\2", rs)
|
|
|
|
# a terminal "dev" or "devel" can be changed into ".dev0"
|
|
rs = re.sub(r"[\.\-](dev|devel)$", r".dev0", rs)
|
|
|
|
# a terminal "dev" can be changed into ".dev0"
|
|
rs = re.sub(r"(?![\.\-])dev$", r".dev0", rs)
|
|
|
|
# a terminal "final" or "stable" can be removed
|
|
rs = re.sub(r"(final|stable)$", "", rs)
|
|
|
|
# The 'r' and the '-' tags are post release tags
|
|
# 0.4a1.r10 -> 0.4a1.post10
|
|
# 0.9.33-17222 -> 0.9.3.post17222
|
|
# 0.9.33-r17222 -> 0.9.3.post17222
|
|
rs = re.sub(r"\.?(r|-|-r)\.?(\d+)$", r".post\2", rs)
|
|
|
|
# Clean 'r' instead of 'dev' usage:
|
|
# 0.9.33+r17222 -> 0.9.3.dev17222
|
|
# 1.0dev123 -> 1.0.dev123
|
|
# 1.0.git123 -> 1.0.dev123
|
|
# 1.0.bzr123 -> 1.0.dev123
|
|
# 0.1a0dev.123 -> 0.1a0.dev123
|
|
# PyPI stats: ~150 (~4%) better
|
|
rs = re.sub(r"\.?(dev|git|bzr)\.?(\d+)$", r".dev\2", rs)
|
|
|
|
# Clean '.pre' (normalized from '-pre' above) instead of 'c' usage:
|
|
# 0.2.pre1 -> 0.2c1
|
|
# 0.2-c1 -> 0.2c1
|
|
# 1.0preview123 -> 1.0c123
|
|
# PyPI stats: ~21 (0.62%) better
|
|
rs = re.sub(r"\.?(pre|preview|-c)(\d+)$", r"c\g<2>", rs)
|
|
|
|
# Tcl/Tk uses "px" for their post release markers
|
|
rs = re.sub(r"p(\d+)$", r".post\1", rs)
|
|
|
|
try:
|
|
NormalizedVersion(rs)
|
|
return rs # already rational
|
|
except IrrationalVersionError:
|
|
pass
|
|
return None
|
|
|
|
|
|
# A predicate is: "ProjectName (VERSION1, VERSION2, ..)
|
|
_PREDICATE = re.compile(r"(?i)^\s*(\w[\s\w-]*(?:\.\w*)*)(.*)")
|
|
_VERSIONS = re.compile(r"^\s*\((?P<versions>.*)\)\s*$|^\s*"
|
|
"(?P<versions2>.*)\s*$")
|
|
_PLAIN_VERSIONS = re.compile(r"^\s*(.*)\s*$")
|
|
_SPLIT_CMP = re.compile(r"^\s*(<=|>=|<|>|!=|==)\s*([^\s,]+)\s*$")
|
|
|
|
|
|
def _split_predicate(predicate):
|
|
match = _SPLIT_CMP.match(predicate)
|
|
if match is None:
|
|
# probably no op, we'll use "=="
|
|
comp, version = '==', predicate
|
|
else:
|
|
comp, version = match.groups()
|
|
return comp, NormalizedVersion(version)
|
|
|
|
|
|
class VersionPredicate:
|
|
"""Defines a predicate: ProjectName (>ver1,ver2, ..)"""
|
|
|
|
_operators = {"<": lambda x, y: x < y,
|
|
">": lambda x, y: x > y,
|
|
"<=": lambda x, y: str(x).startswith(str(y)) or x < y,
|
|
">=": lambda x, y: str(x).startswith(str(y)) or x > y,
|
|
"==": lambda x, y: str(x).startswith(str(y)),
|
|
"!=": lambda x, y: not str(x).startswith(str(y)),
|
|
}
|
|
|
|
def __init__(self, predicate):
|
|
self._string = predicate
|
|
predicate = predicate.strip()
|
|
match = _PREDICATE.match(predicate)
|
|
if match is None:
|
|
raise ValueError('Bad predicate "%s"' % predicate)
|
|
|
|
name, predicates = match.groups()
|
|
self.name = name.strip()
|
|
self.predicates = []
|
|
if predicates is None:
|
|
return
|
|
|
|
predicates = _VERSIONS.match(predicates.strip())
|
|
if predicates is None:
|
|
return
|
|
|
|
predicates = predicates.groupdict()
|
|
if predicates['versions'] is not None:
|
|
versions = predicates['versions']
|
|
else:
|
|
versions = predicates.get('versions2')
|
|
|
|
if versions is not None:
|
|
for version in versions.split(','):
|
|
if version.strip() == '':
|
|
continue
|
|
self.predicates.append(_split_predicate(version))
|
|
|
|
def match(self, version):
|
|
"""Check if the provided version matches the predicates."""
|
|
if isinstance(version, str):
|
|
version = NormalizedVersion(version)
|
|
for operator, predicate in self.predicates:
|
|
if not self._operators[operator](version, predicate):
|
|
return False
|
|
return True
|
|
|
|
def __repr__(self):
|
|
return self._string
|
|
|
|
|
|
class _Versions(VersionPredicate):
|
|
def __init__(self, predicate):
|
|
predicate = predicate.strip()
|
|
match = _PLAIN_VERSIONS.match(predicate)
|
|
self.name = None
|
|
predicates = match.groups()[0]
|
|
self.predicates = [_split_predicate(pred.strip())
|
|
for pred in predicates.split(',')]
|
|
|
|
|
|
class _Version(VersionPredicate):
|
|
def __init__(self, predicate):
|
|
predicate = predicate.strip()
|
|
match = _PLAIN_VERSIONS.match(predicate)
|
|
self.name = None
|
|
self.predicates = _split_predicate(match.groups()[0])
|
|
|
|
|
|
def is_valid_predicate(predicate):
|
|
try:
|
|
VersionPredicate(predicate)
|
|
except (ValueError, IrrationalVersionError):
|
|
return False
|
|
else:
|
|
return True
|
|
|
|
|
|
def is_valid_versions(predicate):
|
|
try:
|
|
_Versions(predicate)
|
|
except (ValueError, IrrationalVersionError):
|
|
return False
|
|
else:
|
|
return True
|
|
|
|
|
|
def is_valid_version(predicate):
|
|
try:
|
|
_Version(predicate)
|
|
except (ValueError, IrrationalVersionError):
|
|
return False
|
|
else:
|
|
return True
|
|
|
|
|
|
def get_version_predicate(requirements):
|
|
"""Return a VersionPredicate object, from a string or an already
|
|
existing object.
|
|
"""
|
|
if isinstance(requirements, str):
|
|
requirements = VersionPredicate(requirements)
|
|
return requirements
|