Home | History | Annotate | Download | only in distutils 
      1 """Module for parsing and testing package version predicate strings.
      2 """
      3 import re
      4 import distutils.version
      5 import operator
      6 
      7 
      8 re_validPackage = re.compile(r"(?i)^\s*([a-z_]\w*(?:\.[a-z_]\w*)*)(.*)")
      9 # (package) (rest)
     10 
     11 re_paren = re.compile(r"^\s*\((.*)\)\s*$") # (list) inside of parentheses
     12 re_splitComparison = re.compile(r"^\s*(<=|>=|<|>|!=|==)\s*([^\s,]+)\s*$")
     13 # (comp) (version)
     14 
     15 
     16 def 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 
     27 compmap = {"<": operator.lt, "<=": operator.le, "==": operator.eq,
     28            ">": operator.gt, ">=": operator.ge, "!=": operator.ne}
     29 
     30 class 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 
    142 def 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