1"""Module for parsing and testing package version predicate strings.
2"""
3import re
4import distutils.version
5import operator
6
7
8re_validPackage = re.compile(r"(?i)^\s*([a-z_]\w*(?:\.[a-z_]\w*)*)(.*)",
9    re.ASCII)
10# (package) (rest)
11
12re_paren = re.compile(r"^\s*\((.*)\)\s*$") # (list) inside of parentheses
13re_splitComparison = re.compile(r"^\s*(<=|>=|<|>|!=|==)\s*([^\s,]+)\s*$")
14# (comp) (version)
15
16
17def splitUp(pred):
18    """Parse a single version comparison.
19
20    Return (comparison string, StrictVersion)
21    """
22    res = re_splitComparison.match(pred)
23    if not res:
24        raise ValueError("bad package restriction syntax: %r" % pred)
25    comp, verStr = res.groups()
26    with distutils.version.suppress_known_deprecation():
27        other = distutils.version.StrictVersion(verStr)
28    return (comp, other)
29
30compmap = {"<": operator.lt, "<=": operator.le, "==": operator.eq,
31           ">": operator.gt, ">=": operator.ge, "!=": operator.ne}
32
33class VersionPredicate:
34    """Parse and test package version predicates.
35
36    >>> v = VersionPredicate('pyepat.abc (>1.0, <3333.3a1, !=1555.1b3)')
37
38    The `name` attribute provides the full dotted name that is given::
39
40    >>> v.name
41    'pyepat.abc'
42
43    The str() of a `VersionPredicate` provides a normalized
44    human-readable version of the expression::
45
46    >>> print(v)
47    pyepat.abc (> 1.0, < 3333.3a1, != 1555.1b3)
48
49    The `satisfied_by()` method can be used to determine with a given
50    version number is included in the set described by the version
51    restrictions::
52
53    >>> v.satisfied_by('1.1')
54    True
55    >>> v.satisfied_by('1.4')
56    True
57    >>> v.satisfied_by('1.0')
58    False
59    >>> v.satisfied_by('4444.4')
60    False
61    >>> v.satisfied_by('1555.1b3')
62    False
63
64    `VersionPredicate` is flexible in accepting extra whitespace::
65
66    >>> v = VersionPredicate(' pat( ==  0.1  )  ')
67    >>> v.name
68    'pat'
69    >>> v.satisfied_by('0.1')
70    True
71    >>> v.satisfied_by('0.2')
72    False
73
74    If any version numbers passed in do not conform to the
75    restrictions of `StrictVersion`, a `ValueError` is raised::
76
77    >>> v = VersionPredicate('p1.p2.p3.p4(>=1.0, <=1.3a1, !=1.2zb3)')
78    Traceback (most recent call last):
79      ...
80    ValueError: invalid version number '1.2zb3'
81
82    It the module or package name given does not conform to what's
83    allowed as a legal module or package name, `ValueError` is
84    raised::
85
86    >>> v = VersionPredicate('foo-bar')
87    Traceback (most recent call last):
88      ...
89    ValueError: expected parenthesized list: '-bar'
90
91    >>> v = VersionPredicate('foo bar (12.21)')
92    Traceback (most recent call last):
93      ...
94    ValueError: expected parenthesized list: 'bar (12.21)'
95
96    """
97
98    def __init__(self, versionPredicateStr):
99        """Parse a version predicate string.
100        """
101        # Fields:
102        #    name:  package name
103        #    pred:  list of (comparison string, StrictVersion)
104
105        versionPredicateStr = versionPredicateStr.strip()
106        if not versionPredicateStr:
107            raise ValueError("empty package restriction")
108        match = re_validPackage.match(versionPredicateStr)
109        if not match:
110            raise ValueError("bad package name in %r" % versionPredicateStr)
111        self.name, paren = match.groups()
112        paren = paren.strip()
113        if paren:
114            match = re_paren.match(paren)
115            if not match:
116                raise ValueError("expected parenthesized list: %r" % paren)
117            str = match.groups()[0]
118            self.pred = [splitUp(aPred) for aPred in str.split(",")]
119            if not self.pred:
120                raise ValueError("empty parenthesized list in %r"
121                                 % versionPredicateStr)
122        else:
123            self.pred = []
124
125    def __str__(self):
126        if self.pred:
127            seq = [cond + " " + str(ver) for cond, ver in self.pred]
128            return self.name + " (" + ", ".join(seq) + ")"
129        else:
130            return self.name
131
132    def satisfied_by(self, version):
133        """True if version is compatible with all the predicates in self.
134        The parameter version must be acceptable to the StrictVersion
135        constructor.  It may be either a string or StrictVersion.
136        """
137        for cond, ver in self.pred:
138            if not compmap[cond](version, ver):
139                return False
140        return True
141
142
143_provision_rx = None
144
145def split_provision(value):
146    """Return the name and optional version number of a provision.
147
148    The version number, if given, will be returned as a `StrictVersion`
149    instance, otherwise it will be `None`.
150
151    >>> split_provision('mypkg')
152    ('mypkg', None)
153    >>> split_provision(' mypkg( 1.2 ) ')
154    ('mypkg', StrictVersion ('1.2'))
155    """
156    global _provision_rx
157    if _provision_rx is None:
158        _provision_rx = re.compile(
159            r"([a-zA-Z_]\w*(?:\.[a-zA-Z_]\w*)*)(?:\s*\(\s*([^)\s]+)\s*\))?$",
160            re.ASCII)
161    value = value.strip()
162    m = _provision_rx.match(value)
163    if not m:
164        raise ValueError("illegal provides specification: %r" % value)
165    ver = m.group(2) or None
166    if ver:
167        with distutils.version.suppress_known_deprecation():
168            ver = distutils.version.StrictVersion(ver)
169    return m.group(1), ver
170