pip._vendor.distlib.version Namespace Reference

Data Structures
class	LegacyMatcher
class	LegacyVersion
class	Matcher
class	NormalizedMatcher
class	NormalizedVersion
class	SemanticMatcher
class	SemanticVersion
class	UnsupportedVersionError
class	Version
class	VersionScheme

Functions
	_pep_440_key (s)
	_match_prefix (x, y)
	_suggest_semantic_version (s)
	_suggest_normalized_version (s)
	_legacy_key (s)
	is_semver (s)
	_semantic_key (s)
	get_scheme (name)

Variables
	logger = logging.getLogger(__name__)
	PEP440_VERSION_RE
	_normalized_key = _pep_440_key
tuple	_REPLACEMENTS
tuple	_SUFFIX_REPLACEMENTS
	_NUMERIC_PREFIX = re.compile(r'(\d+(\.\d+)*)')
	_VERSION_PART = re.compile(r'([a-z]+|\d+|[\.-])', re.I)
dict	_VERSION_REPLACE
	_SEMVER_RE
dict	_SCHEMES

Detailed Description

Implementation of a flexible versioning scheme providing support for PEP-440,
setuptools-compatible and semantic versioning.

Function Documentation

_legacy_key()

_legacy_key (   s )

protected

Definition at line 578 of file version.py.

def _legacy_key(s):
    def get_parts(s):
        result = []
        for p in _VERSION_PART.split(s.lower()):
            p = _VERSION_REPLACE.get(p, p)
            if p:
                if '0' <= p[:1] <= '9':
                    p = p.zfill(8)
                else:
                    p = '*' + p
                result.append(p)
        result.append('*final')
        return result
 
    result = []
    for p in get_parts(s):
        if p.startswith('*'):
            if p < '*final':
                while result and result[-1] == '*final-':
                    result.pop()
            while result and result[-1] == '00000000':
                result.pop()
        result.append(p)
    return tuple(result)
 
 

References i.

Referenced by LegacyVersion.parse().

Here is the caller graph for this function:

_match_prefix()

_match_prefix (   x,   y  )

protected

Definition at line 284 of file version.py.

def _match_prefix(x, y):
    x = str(x)
    y = str(y)
    if x == y:
        return True
    if not x.startswith(y):
        return False
    n = len(y)
    return x[n] == '.'
 
 

References i.

Referenced by NormalizedMatcher._match_compatible(), LegacyMatcher._match_compatible(), NormalizedMatcher._match_eq(), NormalizedMatcher._match_gt(), NormalizedMatcher._match_lt(), and NormalizedMatcher._match_ne().

Here is the caller graph for this function:

_pep_440_key()

_pep_440_key (   s )

protected

Definition at line 184 of file version.py.

def _pep_440_key(s):
    s = s.strip()
    m = PEP440_VERSION_RE.match(s)
    if not m:
        raise UnsupportedVersionError('Not a valid version: %s' % s)
    groups = m.groups()
    nums = tuple(int(v) for v in groups[1].split('.'))
    while len(nums) > 1 and nums[-1] == 0:
        nums = nums[:-1]
 
    if not groups[0]:
        epoch = 0
    else:
        epoch = int(groups[0][:-1])
    pre = groups[4:6]
    post = groups[7:9]
    dev = groups[10:12]
    local = groups[13]
    if pre == (None, None):
        pre = ()
    else:
        pre = pre[0], int(pre[1])
    if post == (None, None):
        post = ()
    else:
        post = post[0], int(post[1])
    if dev == (None, None):
        dev = ()
    else:
        dev = dev[0], int(dev[1])
    if local is None:
        local = ()
    else:
        parts = []
        for part in local.split('.'):
            # to ensure that numeric compares as > lexicographic, avoid
            # comparing them directly, but encode a tuple which ensures
            # correct sorting
            if part.isdigit():
                part = (1, int(part))
            else:
                part = (0, part)
            parts.append(part)
        local = tuple(parts)
    if not pre:
        # either before pre-release, or final release and after
        if not post and dev:
            # before pre-release
            pre = ('a', -1)     # to sort before a0
        else:
            pre = ('z',)        # to sort after all pre-releases
    # now look at the state of post and dev.
    if not post:
        post = ('_',)   # sort before 'a'
    if not dev:
        dev = ('final',)
 
    #print('%s -> %s' % (s, m.groups()))
    return epoch, nums, pre, post, dev, local
 
 

References i.

_semantic_key()

_semantic_key (   s )

protected

Definition at line 653 of file version.py.

def _semantic_key(s):
    def make_tuple(s, absent):
        if s is None:
            result = (absent,)
        else:
            parts = s[1:].split('.')
            # We can't compare ints and strings on Python 3, so fudge it
            # by zero-filling numeric values so simulate a numeric comparison
            result = tuple([p.zfill(8) if p.isdigit() else p for p in parts])
        return result
 
    m = is_semver(s)
    if not m:
        raise UnsupportedVersionError(s)
    groups = m.groups()
    major, minor, patch = [int(i) for i in groups[:3]]
    # choose the '|' and '*' so that versions sort correctly
    pre, build = make_tuple(groups[3], '|'), make_tuple(groups[5], '*')
    return (major, minor, patch), pre, build
 
 

References i, and pip._vendor.distlib.version.is_semver().

Referenced by SemanticVersion.parse().

Here is the call graph for this function:

Here is the caller graph for this function:

_suggest_normalized_version()

_suggest_normalized_version (   s )

protected

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.

Definition at line 452 of file version.py.

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:
        _normalized_key(s)
        return s   # already rational
    except UnsupportedVersionError:
        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 probably 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.33.post17222
    #   0.9.33-r17222   ->  0.9.33.post17222
    rs = re.sub(r"\.?(r|-|-r)\.?(\d+)$", r".post\2", rs)
 
    # Clean 'r' instead of 'dev' usage:
    #   0.9.33+r17222   ->  0.9.33.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:
        _normalized_key(rs)
    except UnsupportedVersionError:
        rs = None
    return rs
 
#
#   Legacy version processing (distribute-compatible)
#
 

References pip._vendor.distlib.version._normalized_key, and i.

_suggest_semantic_version()

_suggest_semantic_version (   s )

protected

Try to suggest a semantic form for a version for which
_suggest_normalized_version couldn't come up with anything.

Definition at line 406 of file version.py.

def _suggest_semantic_version(s):
    """
    Try to suggest a semantic form for a version for which
    _suggest_normalized_version couldn't come up with anything.
    """
    result = s.strip().lower()
    for pat, repl in _REPLACEMENTS:
        result = pat.sub(repl, result)
    if not result:
        result = '0.0.0'
 
    # Now look for numeric prefix, and separate it out from
    # the rest.
    #import pdb; pdb.set_trace()
    m = _NUMERIC_PREFIX.match(result)
    if not m:
        prefix = '0.0.0'
        suffix = result
    else:
        prefix = m.groups()[0].split('.')
        prefix = [int(i) for i in prefix]
        while len(prefix) < 3:
            prefix.append(0)
        if len(prefix) == 3:
            suffix = result[m.end():]
        else:
            suffix = '.'.join([str(i) for i in prefix[3:]]) + result[m.end():]
            prefix = prefix[:3]
        prefix = '.'.join([str(i) for i in prefix])
        suffix = suffix.strip()
    if suffix:
        #import pdb; pdb.set_trace()
        # massage the suffix.
        for pat, repl in _SUFFIX_REPLACEMENTS:
            suffix = pat.sub(repl, suffix)
 
    if not suffix:
        result = prefix
    else:
        sep = '-' if 'dev' in suffix else '+'
        result = prefix + sep + suffix
    if not is_semver(result):
        result = None
    return result
 
 

References i, and pip._vendor.distlib.version.is_semver().

Here is the call graph for this function:

get_scheme()

get_scheme

(

name

)

Definition at line 736 of file version.py.

def get_scheme(name):
    if name not in _SCHEMES:
        raise ValueError('unknown scheme name: %r' % name)
    return _SCHEMES[name]

is_semver()

is_semver

(

s

)

Definition at line 649 of file version.py.

def is_semver(s):
    return _SEMVER_RE.match(s)
 
 

References i.

Referenced by pip._vendor.distlib.version._semantic_key(), and pip._vendor.distlib.version._suggest_semantic_version().

Here is the caller graph for this function:

Variable Documentation

_normalized_key

_normalized_key = _pep_440_key

protected

Definition at line 245 of file version.py.

Referenced by pip._vendor.distlib.version._suggest_normalized_version(), and NormalizedVersion.parse().

_NUMERIC_PREFIX

_NUMERIC_PREFIX = re.compile(r'(\d+(\.\d+)*)')

protected

Definition at line 403 of file version.py.

_REPLACEMENTS

tuple _REPLACEMENTS

protected

Initial value:

=  (
    (re.compile('[.+-]$'), ''),                     # remove trailing puncts
    (re.compile(r'^[.](\d)'), r'0.\1'),             # .N -> 0.N at start
    (re.compile('^[.-]'), ''),                      # remove leading puncts
    (re.compile(r'^\‍((.*)\‍)$'), r'\1'),             # remove parentheses
    (re.compile(r'^v(ersion)?\s*(\d+)'), r'\2'),    # remove leading v(ersion)
    (re.compile(r'^r(ev)?\s*(\d+)'), r'\2'),        # remove leading v(ersion)
    (re.compile('[.]{2,}'), '.'),                   # multiple runs of '.'
    (re.compile(r'\b(alfa|apha)\b'), 'alpha'),      # misspelt alpha
    (re.compile(r'\b(pre-alpha|prealpha)\b'),
                'pre.alpha'),                       # standardise
    (re.compile(r'\‍(beta\‍)$'), 'beta'),             # remove parentheses
)

Definition at line 381 of file version.py.

_SCHEMES

dict _SCHEMES

protected

Initial value:

=  {
    'normalized': VersionScheme(_normalized_key, NormalizedMatcher,
                                _suggest_normalized_version),
    'legacy': VersionScheme(_legacy_key, LegacyMatcher, lambda self, s: s),
    'semantic': VersionScheme(_semantic_key, SemanticMatcher,
                              _suggest_semantic_version),
}

Definition at line 725 of file version.py.

_SEMVER_RE

_SEMVER_RE

protected

Initial value:

=  re.compile(r'^(\d+)\.(\d+)\.(\d+)'
                        r'(-[a-z0-9]+(\.[a-z0-9-]+)*)?'
                        r'(\+[a-z0-9]+(\.[a-z0-9-]+)*)?$', re.I)

Definition at line 644 of file version.py.

_SUFFIX_REPLACEMENTS

tuple _SUFFIX_REPLACEMENTS

protected

Initial value:

=  (
    (re.compile('^[:~._+-]+'), ''),                   # remove leading puncts
    (re.compile('[,*")([\\]]'), ''),                  # remove unwanted chars
    (re.compile('[~:+_ -]'), '.'),                    # replace illegal chars
    (re.compile('[.]{2,}'), '.'),                   # multiple runs of '.'
    (re.compile(r'\.$'), ''),                       # trailing '.'
)

Definition at line 395 of file version.py.

_VERSION_PART

_VERSION_PART = re.compile(r'([a-z]+|\d+|[\.-])', re.I)

protected

Definition at line 566 of file version.py.

_VERSION_REPLACE

dict _VERSION_REPLACE

protected

Initial value:

=  {
    'pre': 'c',
    'preview': 'c',
    '-': 'final-',
    'rc': 'c',
    'dev': '@',
    '': None,
    '.': None,
}

Definition at line 567 of file version.py.

logger

logger = logging.getLogger(__name__)

Definition at line 22 of file version.py.

PEP440_VERSION_RE

PEP440_VERSION_RE

Initial value:

=  re.compile(r'^v?(\d+!)?(\d+(\.\d+)*)((a|b|c|rc)(\d+))?'
                               r'(\.(post)(\d+))?(\.(dev)(\d+))?'
                               r'(\+([a-zA-Z\d]+(\.[a-zA-Z\d]+)?))?$')

Definition at line 179 of file version.py.