• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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.
4"""
5.. testsetup::
6
7    from packaging.version import parse, Version
8"""
9
10import itertools
11import re
12from typing import Any, Callable, NamedTuple, Optional, SupportsInt, Tuple, Union
13
14from ._structures import Infinity, InfinityType, NegativeInfinity, NegativeInfinityType
15
16__all__ = ["VERSION_PATTERN", "parse", "Version", "InvalidVersion"]
17
18LocalType = Tuple[Union[int, str], ...]
19
20CmpPrePostDevType = Union[InfinityType, NegativeInfinityType, Tuple[str, int]]
21CmpLocalType = Union[
22    NegativeInfinityType,
23    Tuple[Union[Tuple[int, str], Tuple[NegativeInfinityType, Union[int, str]]], ...],
24]
25CmpKey = Tuple[
26    int,
27    Tuple[int, ...],
28    CmpPrePostDevType,
29    CmpPrePostDevType,
30    CmpPrePostDevType,
31    CmpLocalType,
32]
33VersionComparisonMethod = Callable[[CmpKey, CmpKey], bool]
34
35
36class _Version(NamedTuple):
37    epoch: int
38    release: Tuple[int, ...]
39    dev: Optional[Tuple[str, int]]
40    pre: Optional[Tuple[str, int]]
41    post: Optional[Tuple[str, int]]
42    local: Optional[LocalType]
43
44
45def parse(version: str) -> "Version":
46    """Parse the given version string.
47
48    >>> parse('1.0.dev1')
49    <Version('1.0.dev1')>
50
51    :param version: The version string to parse.
52    :raises InvalidVersion: When the version string is not a valid version.
53    """
54    return Version(version)
55
56
57class InvalidVersion(ValueError):
58    """Raised when a version string is not a valid version.
59
60    >>> Version("invalid")
61    Traceback (most recent call last):
62        ...
63    packaging.version.InvalidVersion: Invalid version: 'invalid'
64    """
65
66
67class _BaseVersion:
68    _key: Tuple[Any, ...]
69
70    def __hash__(self) -> int:
71        return hash(self._key)
72
73    # Please keep the duplicated `isinstance` check
74    # in the six comparisons hereunder
75    # unless you find a way to avoid adding overhead function calls.
76    def __lt__(self, other: "_BaseVersion") -> bool:
77        if not isinstance(other, _BaseVersion):
78            return NotImplemented
79
80        return self._key < other._key
81
82    def __le__(self, other: "_BaseVersion") -> bool:
83        if not isinstance(other, _BaseVersion):
84            return NotImplemented
85
86        return self._key <= other._key
87
88    def __eq__(self, other: object) -> bool:
89        if not isinstance(other, _BaseVersion):
90            return NotImplemented
91
92        return self._key == other._key
93
94    def __ge__(self, other: "_BaseVersion") -> bool:
95        if not isinstance(other, _BaseVersion):
96            return NotImplemented
97
98        return self._key >= other._key
99
100    def __gt__(self, other: "_BaseVersion") -> bool:
101        if not isinstance(other, _BaseVersion):
102            return NotImplemented
103
104        return self._key > other._key
105
106    def __ne__(self, other: object) -> bool:
107        if not isinstance(other, _BaseVersion):
108            return NotImplemented
109
110        return self._key != other._key
111
112
113# Deliberately not anchored to the start and end of the string, to make it
114# easier for 3rd party code to reuse
115_VERSION_PATTERN = r"""
116    v?
117    (?:
118        (?:(?P<epoch>[0-9]+)!)?                           # epoch
119        (?P<release>[0-9]+(?:\.[0-9]+)*)                  # release segment
120        (?P<pre>                                          # pre-release
121            [-_\.]?
122            (?P<pre_l>alpha|a|beta|b|preview|pre|c|rc)
123            [-_\.]?
124            (?P<pre_n>[0-9]+)?
125        )?
126        (?P<post>                                         # post release
127            (?:-(?P<post_n1>[0-9]+))
128            |
129            (?:
130                [-_\.]?
131                (?P<post_l>post|rev|r)
132                [-_\.]?
133                (?P<post_n2>[0-9]+)?
134            )
135        )?
136        (?P<dev>                                          # dev release
137            [-_\.]?
138            (?P<dev_l>dev)
139            [-_\.]?
140            (?P<dev_n>[0-9]+)?
141        )?
142    )
143    (?:\+(?P<local>[a-z0-9]+(?:[-_\.][a-z0-9]+)*))?       # local version
144"""
145
146VERSION_PATTERN = _VERSION_PATTERN
147"""
148A string containing the regular expression used to match a valid version.
149
150The pattern is not anchored at either end, and is intended for embedding in larger
151expressions (for example, matching a version number as part of a file name). The
152regular expression should be compiled with the ``re.VERBOSE`` and ``re.IGNORECASE``
153flags set.
154
155:meta hide-value:
156"""
157
158
159class Version(_BaseVersion):
160    """This class abstracts handling of a project's versions.
161
162    A :class:`Version` instance is comparison aware and can be compared and
163    sorted using the standard Python interfaces.
164
165    >>> v1 = Version("1.0a5")
166    >>> v2 = Version("1.0")
167    >>> v1
168    <Version('1.0a5')>
169    >>> v2
170    <Version('1.0')>
171    >>> v1 < v2
172    True
173    >>> v1 == v2
174    False
175    >>> v1 > v2
176    False
177    >>> v1 >= v2
178    False
179    >>> v1 <= v2
180    True
181    """
182
183    _regex = re.compile(r"^\s*" + VERSION_PATTERN + r"\s*$", re.VERBOSE | re.IGNORECASE)
184    _key: CmpKey
185
186    def __init__(self, version: str) -> None:
187        """Initialize a Version object.
188
189        :param version:
190            The string representation of a version which will be parsed and normalized
191            before use.
192        :raises InvalidVersion:
193            If the ``version`` does not conform to PEP 440 in any way then this
194            exception will be raised.
195        """
196
197        # Validate the version and parse it into pieces
198        match = self._regex.search(version)
199        if not match:
200            raise InvalidVersion(f"Invalid version: '{version}'")
201
202        # Store the parsed out pieces of the version
203        self._version = _Version(
204            epoch=int(match.group("epoch")) if match.group("epoch") else 0,
205            release=tuple(int(i) for i in match.group("release").split(".")),
206            pre=_parse_letter_version(match.group("pre_l"), match.group("pre_n")),
207            post=_parse_letter_version(
208                match.group("post_l"), match.group("post_n1") or match.group("post_n2")
209            ),
210            dev=_parse_letter_version(match.group("dev_l"), match.group("dev_n")),
211            local=_parse_local_version(match.group("local")),
212        )
213
214        # Generate a key which will be used for sorting
215        self._key = _cmpkey(
216            self._version.epoch,
217            self._version.release,
218            self._version.pre,
219            self._version.post,
220            self._version.dev,
221            self._version.local,
222        )
223
224    def __repr__(self) -> str:
225        """A representation of the Version that shows all internal state.
226
227        >>> Version('1.0.0')
228        <Version('1.0.0')>
229        """
230        return f"<Version('{self}')>"
231
232    def __str__(self) -> str:
233        """A string representation of the version that can be rounded-tripped.
234
235        >>> str(Version("1.0a5"))
236        '1.0a5'
237        """
238        parts = []
239
240        # Epoch
241        if self.epoch != 0:
242            parts.append(f"{self.epoch}!")
243
244        # Release segment
245        parts.append(".".join(str(x) for x in self.release))
246
247        # Pre-release
248        if self.pre is not None:
249            parts.append("".join(str(x) for x in self.pre))
250
251        # Post-release
252        if self.post is not None:
253            parts.append(f".post{self.post}")
254
255        # Development release
256        if self.dev is not None:
257            parts.append(f".dev{self.dev}")
258
259        # Local version segment
260        if self.local is not None:
261            parts.append(f"+{self.local}")
262
263        return "".join(parts)
264
265    @property
266    def epoch(self) -> int:
267        """The epoch of the version.
268
269        >>> Version("2.0.0").epoch
270        0
271        >>> Version("1!2.0.0").epoch
272        1
273        """
274        return self._version.epoch
275
276    @property
277    def release(self) -> Tuple[int, ...]:
278        """The components of the "release" segment of the version.
279
280        >>> Version("1.2.3").release
281        (1, 2, 3)
282        >>> Version("2.0.0").release
283        (2, 0, 0)
284        >>> Version("1!2.0.0.post0").release
285        (2, 0, 0)
286
287        Includes trailing zeroes but not the epoch or any pre-release / development /
288        post-release suffixes.
289        """
290        return self._version.release
291
292    @property
293    def pre(self) -> Optional[Tuple[str, int]]:
294        """The pre-release segment of the version.
295
296        >>> print(Version("1.2.3").pre)
297        None
298        >>> Version("1.2.3a1").pre
299        ('a', 1)
300        >>> Version("1.2.3b1").pre
301        ('b', 1)
302        >>> Version("1.2.3rc1").pre
303        ('rc', 1)
304        """
305        return self._version.pre
306
307    @property
308    def post(self) -> Optional[int]:
309        """The post-release number of the version.
310
311        >>> print(Version("1.2.3").post)
312        None
313        >>> Version("1.2.3.post1").post
314        1
315        """
316        return self._version.post[1] if self._version.post else None
317
318    @property
319    def dev(self) -> Optional[int]:
320        """The development number of the version.
321
322        >>> print(Version("1.2.3").dev)
323        None
324        >>> Version("1.2.3.dev1").dev
325        1
326        """
327        return self._version.dev[1] if self._version.dev else None
328
329    @property
330    def local(self) -> Optional[str]:
331        """The local version segment of the version.
332
333        >>> print(Version("1.2.3").local)
334        None
335        >>> Version("1.2.3+abc").local
336        'abc'
337        """
338        if self._version.local:
339            return ".".join(str(x) for x in self._version.local)
340        else:
341            return None
342
343    @property
344    def public(self) -> str:
345        """The public portion of the version.
346
347        >>> Version("1.2.3").public
348        '1.2.3'
349        >>> Version("1.2.3+abc").public
350        '1.2.3'
351        >>> Version("1.2.3+abc.dev1").public
352        '1.2.3'
353        """
354        return str(self).split("+", 1)[0]
355
356    @property
357    def base_version(self) -> str:
358        """The "base version" of the version.
359
360        >>> Version("1.2.3").base_version
361        '1.2.3'
362        >>> Version("1.2.3+abc").base_version
363        '1.2.3'
364        >>> Version("1!1.2.3+abc.dev1").base_version
365        '1!1.2.3'
366
367        The "base version" is the public version of the project without any pre or post
368        release markers.
369        """
370        parts = []
371
372        # Epoch
373        if self.epoch != 0:
374            parts.append(f"{self.epoch}!")
375
376        # Release segment
377        parts.append(".".join(str(x) for x in self.release))
378
379        return "".join(parts)
380
381    @property
382    def is_prerelease(self) -> bool:
383        """Whether this version is a pre-release.
384
385        >>> Version("1.2.3").is_prerelease
386        False
387        >>> Version("1.2.3a1").is_prerelease
388        True
389        >>> Version("1.2.3b1").is_prerelease
390        True
391        >>> Version("1.2.3rc1").is_prerelease
392        True
393        >>> Version("1.2.3dev1").is_prerelease
394        True
395        """
396        return self.dev is not None or self.pre is not None
397
398    @property
399    def is_postrelease(self) -> bool:
400        """Whether this version is a post-release.
401
402        >>> Version("1.2.3").is_postrelease
403        False
404        >>> Version("1.2.3.post1").is_postrelease
405        True
406        """
407        return self.post is not None
408
409    @property
410    def is_devrelease(self) -> bool:
411        """Whether this version is a development release.
412
413        >>> Version("1.2.3").is_devrelease
414        False
415        >>> Version("1.2.3.dev1").is_devrelease
416        True
417        """
418        return self.dev is not None
419
420    @property
421    def major(self) -> int:
422        """The first item of :attr:`release` or ``0`` if unavailable.
423
424        >>> Version("1.2.3").major
425        1
426        """
427        return self.release[0] if len(self.release) >= 1 else 0
428
429    @property
430    def minor(self) -> int:
431        """The second item of :attr:`release` or ``0`` if unavailable.
432
433        >>> Version("1.2.3").minor
434        2
435        >>> Version("1").minor
436        0
437        """
438        return self.release[1] if len(self.release) >= 2 else 0
439
440    @property
441    def micro(self) -> int:
442        """The third item of :attr:`release` or ``0`` if unavailable.
443
444        >>> Version("1.2.3").micro
445        3
446        >>> Version("1").micro
447        0
448        """
449        return self.release[2] if len(self.release) >= 3 else 0
450
451
452def _parse_letter_version(
453    letter: Optional[str], number: Union[str, bytes, SupportsInt, None]
454) -> Optional[Tuple[str, int]]:
455
456    if letter:
457        # We consider there to be an implicit 0 in a pre-release if there is
458        # not a numeral associated with it.
459        if number is None:
460            number = 0
461
462        # We normalize any letters to their lower case form
463        letter = letter.lower()
464
465        # We consider some words to be alternate spellings of other words and
466        # in those cases we want to normalize the spellings to our preferred
467        # spelling.
468        if letter == "alpha":
469            letter = "a"
470        elif letter == "beta":
471            letter = "b"
472        elif letter in ["c", "pre", "preview"]:
473            letter = "rc"
474        elif letter in ["rev", "r"]:
475            letter = "post"
476
477        return letter, int(number)
478    if not letter and number:
479        # We assume if we are given a number, but we are not given a letter
480        # then this is using the implicit post release syntax (e.g. 1.0-1)
481        letter = "post"
482
483        return letter, int(number)
484
485    return None
486
487
488_local_version_separators = re.compile(r"[\._-]")
489
490
491def _parse_local_version(local: Optional[str]) -> Optional[LocalType]:
492    """
493    Takes a string like abc.1.twelve and turns it into ("abc", 1, "twelve").
494    """
495    if local is not None:
496        return tuple(
497            part.lower() if not part.isdigit() else int(part)
498            for part in _local_version_separators.split(local)
499        )
500    return None
501
502
503def _cmpkey(
504    epoch: int,
505    release: Tuple[int, ...],
506    pre: Optional[Tuple[str, int]],
507    post: Optional[Tuple[str, int]],
508    dev: Optional[Tuple[str, int]],
509    local: Optional[LocalType],
510) -> CmpKey:
511
512    # When we compare a release version, we want to compare it with all of the
513    # trailing zeros removed. So we'll use a reverse the list, drop all the now
514    # leading zeros until we come to something non zero, then take the rest
515    # re-reverse it back into the correct order and make it a tuple and use
516    # that for our sorting key.
517    _release = tuple(
518        reversed(list(itertools.dropwhile(lambda x: x == 0, reversed(release))))
519    )
520
521    # We need to "trick" the sorting algorithm to put 1.0.dev0 before 1.0a0.
522    # We'll do this by abusing the pre segment, but we _only_ want to do this
523    # if there is not a pre or a post segment. If we have one of those then
524    # the normal sorting rules will handle this case correctly.
525    if pre is None and post is None and dev is not None:
526        _pre: CmpPrePostDevType = NegativeInfinity
527    # Versions without a pre-release (except as noted above) should sort after
528    # those with one.
529    elif pre is None:
530        _pre = Infinity
531    else:
532        _pre = pre
533
534    # Versions without a post segment should sort before those with one.
535    if post is None:
536        _post: CmpPrePostDevType = NegativeInfinity
537
538    else:
539        _post = post
540
541    # Versions without a development segment should sort after those with one.
542    if dev is None:
543        _dev: CmpPrePostDevType = Infinity
544
545    else:
546        _dev = dev
547
548    if local is None:
549        # Versions without a local segment should sort before those with one.
550        _local: CmpLocalType = NegativeInfinity
551    else:
552        # Versions with a local segment need that segment parsed to implement
553        # the sorting rules in PEP440.
554        # - Alpha numeric segments sort before numeric segments
555        # - Alpha numeric segments sort lexicographically
556        # - Numeric segments sort numerically
557        # - Shorter versions sort before longer versions when the prefixes
558        #   match exactly
559        _local = tuple(
560            (i, "") if isinstance(i, int) else (NegativeInfinity, i) for i in local
561        )
562
563    return epoch, _release, _pre, _post, _dev, _local
564