1# This file is dual licensed under the terms of the Apache License, Version
2# 2.0, and the BSD License. See the LICENSE file in the root of this repository
3# for complete details.
4from __future__ import absolute_import, division, print_function
5
6import collections
7import itertools
8import re
9
10from ._structures import Infinity
11
12
13__all__ = [
14    "parse", "Version", "LegacyVersion", "InvalidVersion", "VERSION_PATTERN"
15]
16
17
18_Version = collections.namedtuple(
19    "_Version",
20    ["epoch", "release", "dev", "pre", "post", "local"],
21)
22
23
24def parse(version):
25    """
26    Parse the given version string and return either a :class:`Version` object
27    or a :class:`LegacyVersion` object depending on if the given version is
28    a valid PEP 440 version or a legacy version.
29    """
30    try:
31        return Version(version)
32    except InvalidVersion:
33        return LegacyVersion(version)
34
35
36class InvalidVersion(ValueError):
37    """
38    An invalid version was found, users should refer to PEP 440.
39    """
40
41
42class _BaseVersion(object):
43
44    def __hash__(self):
45        return hash(self._key)
46
47    def __lt__(self, other):
48        return self._compare(other, lambda s, o: s < o)
49
50    def __le__(self, other):
51        return self._compare(other, lambda s, o: s <= o)
52
53    def __eq__(self, other):
54        return self._compare(other, lambda s, o: s == o)
55
56    def __ge__(self, other):
57        return self._compare(other, lambda s, o: s >= o)
58
59    def __gt__(self, other):
60        return self._compare(other, lambda s, o: s > o)
61
62    def __ne__(self, other):
63        return self._compare(other, lambda s, o: s != o)
64
65    def _compare(self, other, method):
66        if not isinstance(other, _BaseVersion):
67            return NotImplemented
68
69        return method(self._key, other._key)
70
71
72class LegacyVersion(_BaseVersion):
73
74    def __init__(self, version):
75        self._version = str(version)
76        self._key = _legacy_cmpkey(self._version)
77
78    def __str__(self):
79        return self._version
80
81    def __repr__(self):
82        return "<LegacyVersion({0})>".format(repr(str(self)))
83
84    @property
85    def public(self):
86        return self._version
87
88    @property
89    def base_version(self):
90        return self._version
91
92    @property
93    def local(self):
94        return None
95
96    @property
97    def is_prerelease(self):
98        return False
99
100    @property
101    def is_postrelease(self):
102        return False
103
104
105_legacy_version_component_re = re.compile(
106    r"(\d+ | [a-z]+ | \.| -)", re.VERBOSE,
107)
108
109_legacy_version_replacement_map = {
110    "pre": "c", "preview": "c", "-": "final-", "rc": "c", "dev": "@",
111}
112
113
114def _parse_version_parts(s):
115    for part in _legacy_version_component_re.split(s):
116        part = _legacy_version_replacement_map.get(part, part)
117
118        if not part or part == ".":
119            continue
120
121        if part[:1] in "0123456789":
122            # pad for numeric comparison
123            yield part.zfill(8)
124        else:
125            yield "*" + part
126
127    # ensure that alpha/beta/candidate are before final
128    yield "*final"
129
130
131def _legacy_cmpkey(version):
132    # We hardcode an epoch of -1 here. A PEP 440 version can only have a epoch
133    # greater than or equal to 0. This will effectively put the LegacyVersion,
134    # which uses the defacto standard originally implemented by setuptools,
135    # as before all PEP 440 versions.
136    epoch = -1
137
138    # This scheme is taken from pkg_resources.parse_version setuptools prior to
139    # it's adoption of the packaging library.
140    parts = []
141    for part in _parse_version_parts(version.lower()):
142        if part.startswith("*"):
143            # remove "-" before a prerelease tag
144            if part < "*final":
145                while parts and parts[-1] == "*final-":
146                    parts.pop()
147
148            # remove trailing zeros from each series of numeric parts
149            while parts and parts[-1] == "00000000":
150                parts.pop()
151
152        parts.append(part)
153    parts = tuple(parts)
154
155    return epoch, parts
156
157# Deliberately not anchored to the start and end of the string, to make it
158# easier for 3rd party code to reuse
159VERSION_PATTERN = r"""
160    v?
161    (?:
162        (?:(?P<epoch>[0-9]+)!)?                           # epoch
163        (?P<release>[0-9]+(?:\.[0-9]+)*)                  # release segment
164        (?P<pre>                                          # pre-release
165            [-_\.]?
166            (?P<pre_l>(a|b|c|rc|alpha|beta|pre|preview))
167            [-_\.]?
168            (?P<pre_n>[0-9]+)?
169        )?
170        (?P<post>                                         # post release
171            (?:-(?P<post_n1>[0-9]+))
172            |
173            (?:
174                [-_\.]?
175                (?P<post_l>post|rev|r)
176                [-_\.]?
177                (?P<post_n2>[0-9]+)?
178            )
179        )?
180        (?P<dev>                                          # dev release
181            [-_\.]?
182            (?P<dev_l>dev)
183            [-_\.]?
184            (?P<dev_n>[0-9]+)?
185        )?
186    )
187    (?:\+(?P<local>[a-z0-9]+(?:[-_\.][a-z0-9]+)*))?       # local version
188"""
189
190
191class Version(_BaseVersion):
192
193    _regex = re.compile(
194        r"^\s*" + VERSION_PATTERN + r"\s*$",
195        re.VERBOSE | re.IGNORECASE,
196    )
197
198    def __init__(self, version):
199        # Validate the version and parse it into pieces
200        match = self._regex.search(version)
201        if not match:
202            raise InvalidVersion("Invalid version: '{0}'".format(version))
203
204        # Store the parsed out pieces of the version
205        self._version = _Version(
206            epoch=int(match.group("epoch")) if match.group("epoch") else 0,
207            release=tuple(int(i) for i in match.group("release").split(".")),
208            pre=_parse_letter_version(
209                match.group("pre_l"),
210                match.group("pre_n"),
211            ),
212            post=_parse_letter_version(
213                match.group("post_l"),
214                match.group("post_n1") or match.group("post_n2"),
215            ),
216            dev=_parse_letter_version(
217                match.group("dev_l"),
218                match.group("dev_n"),
219            ),
220            local=_parse_local_version(match.group("local")),
221        )
222
223        # Generate a key which will be used for sorting
224        self._key = _cmpkey(
225            self._version.epoch,
226            self._version.release,
227            self._version.pre,
228            self._version.post,
229            self._version.dev,
230            self._version.local,
231        )
232
233    def __repr__(self):
234        return "<Version({0})>".format(repr(str(self)))
235
236    def __str__(self):
237        parts = []
238
239        # Epoch
240        if self._version.epoch != 0:
241            parts.append("{0}!".format(self._version.epoch))
242
243        # Release segment
244        parts.append(".".join(str(x) for x in self._version.release))
245
246        # Pre-release
247        if self._version.pre is not None:
248            parts.append("".join(str(x) for x in self._version.pre))
249
250        # Post-release
251        if self._version.post is not None:
252            parts.append(".post{0}".format(self._version.post[1]))
253
254        # Development release
255        if self._version.dev is not None:
256            parts.append(".dev{0}".format(self._version.dev[1]))
257
258        # Local version segment
259        if self._version.local is not None:
260            parts.append(
261                "+{0}".format(".".join(str(x) for x in self._version.local))
262            )
263
264        return "".join(parts)
265
266    @property
267    def public(self):
268        return str(self).split("+", 1)[0]
269
270    @property
271    def base_version(self):
272        parts = []
273
274        # Epoch
275        if self._version.epoch != 0:
276            parts.append("{0}!".format(self._version.epoch))
277
278        # Release segment
279        parts.append(".".join(str(x) for x in self._version.release))
280
281        return "".join(parts)
282
283    @property
284    def local(self):
285        version_string = str(self)
286        if "+" in version_string:
287            return version_string.split("+", 1)[1]
288
289    @property
290    def is_prerelease(self):
291        return bool(self._version.dev or self._version.pre)
292
293    @property
294    def is_postrelease(self):
295        return bool(self._version.post)
296
297
298def _parse_letter_version(letter, number):
299    if letter:
300        # We consider there to be an implicit 0 in a pre-release if there is
301        # not a numeral associated with it.
302        if number is None:
303            number = 0
304
305        # We normalize any letters to their lower case form
306        letter = letter.lower()
307
308        # We consider some words to be alternate spellings of other words and
309        # in those cases we want to normalize the spellings to our preferred
310        # spelling.
311        if letter == "alpha":
312            letter = "a"
313        elif letter == "beta":
314            letter = "b"
315        elif letter in ["c", "pre", "preview"]:
316            letter = "rc"
317        elif letter in ["rev", "r"]:
318            letter = "post"
319
320        return letter, int(number)
321    if not letter and number:
322        # We assume if we are given a number, but we are not given a letter
323        # then this is using the implicit post release syntax (e.g. 1.0-1)
324        letter = "post"
325
326        return letter, int(number)
327
328
329_local_version_seperators = re.compile(r"[\._-]")
330
331
332def _parse_local_version(local):
333    """
334    Takes a string like abc.1.twelve and turns it into ("abc", 1, "twelve").
335    """
336    if local is not None:
337        return tuple(
338            part.lower() if not part.isdigit() else int(part)
339            for part in _local_version_seperators.split(local)
340        )
341
342
343def _cmpkey(epoch, release, pre, post, dev, local):
344    # When we compare a release version, we want to compare it with all of the
345    # trailing zeros removed. So we'll use a reverse the list, drop all the now
346    # leading zeros until we come to something non zero, then take the rest
347    # re-reverse it back into the correct order and make it a tuple and use
348    # that for our sorting key.
349    release = tuple(
350        reversed(list(
351            itertools.dropwhile(
352                lambda x: x == 0,
353                reversed(release),
354            )
355        ))
356    )
357
358    # We need to "trick" the sorting algorithm to put 1.0.dev0 before 1.0a0.
359    # We'll do this by abusing the pre segment, but we _only_ want to do this
360    # if there is not a pre or a post segment. If we have one of those then
361    # the normal sorting rules will handle this case correctly.
362    if pre is None and post is None and dev is not None:
363        pre = -Infinity
364    # Versions without a pre-release (except as noted above) should sort after
365    # those with one.
366    elif pre is None:
367        pre = Infinity
368
369    # Versions without a post segment should sort before those with one.
370    if post is None:
371        post = -Infinity
372
373    # Versions without a development segment should sort after those with one.
374    if dev is None:
375        dev = Infinity
376
377    if local is None:
378        # Versions without a local segment should sort before those with one.
379        local = -Infinity
380    else:
381        # Versions with a local segment need that segment parsed to implement
382        # the sorting rules in PEP440.
383        # - Alpha numeric segments sort before numeric segments
384        # - Alpha numeric segments sort lexicographically
385        # - Numeric segments sort numerically
386        # - Shorter versions sort before longer versions when the prefixes
387        #   match exactly
388        local = tuple(
389            (i, "") if isinstance(i, int) else (-Infinity, i)
390            for i in local
391        )
392
393    return epoch, release, pre, post, dev, local
394