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