Shortcuts on this page
r m x toggle line displays
j k next/prev highlighted chunk
0 (zero) top of page
1 (one) first highlighted chunk
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::
7 from pip._vendor.packaging.version import parse, normalize_pre, Version, _cmpkey
8"""
10from __future__ import annotations
12import re
13import sys
14import typing
15from typing import (
16 Any,
17 Callable,
18 Literal,
19 NamedTuple,
20 SupportsInt,
21 TypedDict,
22 Union,
23)
25if typing.TYPE_CHECKING:
26 from typing_extensions import Self, Unpack
28if sys.version_info >= (3, 13): # pragma: no cover
29 from warnings import deprecated as _deprecated
30elif typing.TYPE_CHECKING:
31 from typing_extensions import deprecated as _deprecated
32else: # pragma: no cover
33 import functools
34 import warnings
36 def _deprecated(message: str) -> object:
37 def decorator(func: Callable[[...], object]) -> object:
38 @functools.wraps(func)
39 def wrapper(*args: object, **kwargs: object) -> object:
40 warnings.warn(
41 message,
42 category=DeprecationWarning,
43 stacklevel=2,
44 )
45 return func(*args, **kwargs)
47 return wrapper
49 return decorator
52_LETTER_NORMALIZATION = {
53 "alpha": "a",
54 "beta": "b",
55 "c": "rc",
56 "pre": "rc",
57 "preview": "rc",
58 "rev": "post",
59 "r": "post",
60}
62__all__ = ["VERSION_PATTERN", "InvalidVersion", "Version", "normalize_pre", "parse"]
65def __dir__() -> list[str]:
66 return __all__
69LocalType = tuple[Union[int, str], ...]
71CmpLocalType = tuple[tuple[int, str], ...]
72CmpSuffix = tuple[int, int, int, int, int, int]
73CmpKey = Union[
74 tuple[int, tuple[int, ...], CmpSuffix],
75 tuple[int, tuple[int, ...], CmpSuffix, CmpLocalType],
76]
77VersionComparisonMethod = Callable[[CmpKey, CmpKey], bool]
80class _VersionReplace(TypedDict, total=False):
81 epoch: int | None
82 release: tuple[int, ...] | None
83 pre: tuple[str, int] | None
84 post: int | None
85 dev: int | None
86 local: str | None
89def normalize_pre(letter: str, /) -> str:
90 """Normalize the pre-release segment of a version string.
92 Returns a lowercase version of the string if not a known pre-release
93 identifier.
95 >>> normalize_pre('alpha')
96 'a'
97 >>> normalize_pre('BETA')
98 'b'
99 >>> normalize_pre('rc')
100 'rc'
102 :param letter:
104 .. versionadded:: 26.1
105 """
106 letter = letter.lower()
107 return _LETTER_NORMALIZATION.get(letter, letter)
110def parse(version: str) -> Version:
111 """Parse the given version string.
113 This is identical to the :class:`Version` constructor.
115 >>> parse('1.0.dev1')
116 <Version('1.0.dev1')>
118 :param version: The version string to parse.
119 :raises InvalidVersion: When the version string is not a valid version.
120 """
121 return Version(version)
124class InvalidVersion(ValueError):
125 """Raised when a version string is not a valid version.
127 >>> Version("invalid")
128 Traceback (most recent call last):
129 ...
130 packaging.version.InvalidVersion: Invalid version: 'invalid'
131 """
134class _BaseVersion:
135 __slots__ = ()
137 # This can also be a normal member (see the packaging_legacy package);
138 # we are just requiring it to be readable. Actually defining a property
139 # has runtime effect on subclasses, so it's typing only.
140 if typing.TYPE_CHECKING:
142 @property
143 def _key(self) -> tuple[Any, ...]: ...
145 def __hash__(self) -> int:
146 return hash(self._key)
148 # Please keep the duplicated `isinstance` check
149 # in the six comparisons hereunder
150 # unless you find a way to avoid adding overhead function calls.
151 def __lt__(self, other: _BaseVersion) -> bool:
152 if not isinstance(other, _BaseVersion):
153 return NotImplemented
155 return self._key < other._key
157 def __le__(self, other: _BaseVersion) -> bool:
158 if not isinstance(other, _BaseVersion):
159 return NotImplemented
161 return self._key <= other._key
163 def __eq__(self, other: object) -> bool:
164 if not isinstance(other, _BaseVersion):
165 return NotImplemented
167 return self._key == other._key
169 def __ge__(self, other: _BaseVersion) -> bool:
170 if not isinstance(other, _BaseVersion):
171 return NotImplemented
173 return self._key >= other._key
175 def __gt__(self, other: _BaseVersion) -> bool:
176 if not isinstance(other, _BaseVersion):
177 return NotImplemented
179 return self._key > other._key
181 def __ne__(self, other: object) -> bool:
182 if not isinstance(other, _BaseVersion):
183 return NotImplemented
185 return self._key != other._key
188# Deliberately not anchored to the start and end of the string, to make it
189# easier for 3rd party code to reuse
191# Note that ++ doesn't behave identically on CPython and PyPy, so not using it here
192_VERSION_PATTERN = r"""
193 v?+ # optional leading v
194 (?a:
195 (?:(?P<epoch>[0-9]+)!)?+ # epoch
196 (?P<release>[0-9]+(?:\.[0-9]+)*+) # release segment
197 (?P<pre> # pre-release
198 [._-]?+
199 (?P<pre_l>alpha|a|beta|b|preview|pre|c|rc)
200 [._-]?+
201 (?P<pre_n>[0-9]+)?
202 )?+
203 (?P<post> # post release
204 (?:-(?P<post_n1>[0-9]+))
205 |
206 (?:
207 [._-]?
208 (?P<post_l>post|rev|r)
209 [._-]?
210 (?P<post_n2>[0-9]+)?
211 )
212 )?+
213 (?P<dev> # dev release
214 [._-]?+
215 (?P<dev_l>dev)
216 [._-]?+
217 (?P<dev_n>[0-9]+)?
218 )?+
219 )
220 (?a:\+
221 (?P<local> # local version
222 [a-z0-9]+
223 (?:[._-][a-z0-9]+)*+
224 )
225 )?+
226"""
228_VERSION_PATTERN_OLD = _VERSION_PATTERN.replace("*+", "*").replace("?+", "?")
230# Possessive qualifiers were added in Python 3.11.
231# CPython 3.11.0-3.11.4 had a bug: https://github.com/python/cpython/pull/107795
232# Older PyPy also had a bug.
233VERSION_PATTERN = (
234 _VERSION_PATTERN_OLD
235 if (sys.implementation.name == "cpython" and sys.version_info < (3, 11, 5))
236 or (sys.implementation.name == "pypy" and sys.version_info < (3, 11, 13))
237 or sys.version_info < (3, 11)
238 else _VERSION_PATTERN
239)
240"""
241A string containing the regular expression used to match a valid version.
243The pattern is not anchored at either end, and is intended for embedding in larger
244expressions (for example, matching a version number as part of a file name). The
245regular expression should be compiled with the ``re.VERBOSE`` and ``re.IGNORECASE``
246flags set.
248.. versionchanged:: 26.0
250 The regex now uses possessive qualifiers on Python 3.11 if they are
251 supported (CPython 3.11.5+, PyPy 3.11.13+).
253:meta hide-value:
254"""
257# Validation pattern for local version in replace()
258_LOCAL_PATTERN = re.compile(r"[a-z0-9]+(?:[._-][a-z0-9]+)*", re.IGNORECASE | re.ASCII)
260# Fast path: If a version has only digits and dots then we
261# can skip the regex and parse it as a release segment
262_SIMPLE_VERSION_INDICATORS = frozenset(".0123456789")
265def _validate_epoch(value: object, /) -> int:
266 epoch = value or 0
267 if isinstance(epoch, int) and epoch >= 0:
268 return epoch
269 msg = f"epoch must be non-negative integer, got {epoch}"
270 raise InvalidVersion(msg)
273def _validate_release(value: object, /) -> tuple[int, ...]:
274 release = (0,) if value is None else value
275 if (
276 isinstance(release, tuple)
277 and len(release) > 0
278 and all(isinstance(i, int) and i >= 0 for i in release)
279 ):
280 return release
281 msg = f"release must be a non-empty tuple of non-negative integers, got {release}"
282 raise InvalidVersion(msg)
285def _validate_pre(value: object, /) -> tuple[Literal["a", "b", "rc"], int] | None:
286 if value is None:
287 return value
288 if isinstance(value, tuple) and len(value) == 2:
289 letter, number = value
290 # The letter must be a string before it can be normalized.
291 if (
292 isinstance(letter, str)
293 and (normalized := normalize_pre(letter)) in {"a", "b", "rc"}
294 and isinstance(number, int)
295 and number >= 0
296 ):
297 # type checkers can't infer the Literal type here on letter
298 return (normalized, number) # type: ignore[return-value]
299 msg = f"pre must be a tuple of ('a'|'b'|'rc', non-negative int), got {value}"
300 raise InvalidVersion(msg)
303def _validate_post(value: object, /) -> tuple[Literal["post"], int] | None:
304 if value is None:
305 return value
306 if isinstance(value, int) and value >= 0:
307 return ("post", value)
308 msg = f"post must be non-negative integer, got {value}"
309 raise InvalidVersion(msg)
312def _validate_dev(value: object, /) -> tuple[Literal["dev"], int] | None:
313 if value is None:
314 return value
315 if isinstance(value, int) and value >= 0:
316 return ("dev", value)
317 msg = f"dev must be non-negative integer, got {value}"
318 raise InvalidVersion(msg)
321def _validate_local(value: object, /) -> LocalType | None:
322 if value is None:
323 return value
324 if isinstance(value, str) and _LOCAL_PATTERN.fullmatch(value):
325 return _parse_local_version(value)
326 msg = f"local must be a valid version string, got {value!r}"
327 raise InvalidVersion(msg)
330# Backward compatibility for internals before 26.0. Do not use.
331class _Version(NamedTuple):
332 epoch: int
333 release: tuple[int, ...]
334 dev: tuple[Literal["dev"], int] | None
335 pre: tuple[Literal["a", "b", "rc"], int] | None
336 post: tuple[Literal["post"], int] | None
337 local: LocalType | None
340class Version(_BaseVersion):
341 """This class abstracts handling of a project's versions.
343 A :class:`Version` instance is comparison aware and can be compared and
344 sorted using the standard Python interfaces.
346 >>> v1 = Version("1.0a5")
347 >>> v2 = Version("1.0")
348 >>> v1
349 <Version('1.0a5')>
350 >>> v2
351 <Version('1.0')>
352 >>> v1 < v2
353 True
354 >>> v1 == v2
355 False
356 >>> v1 > v2
357 False
358 >>> v1 >= v2
359 False
360 >>> v1 <= v2
361 True
363 :class:`Version` is immutable; use :meth:`__replace__` to change
364 part of a version.
366 Instances are safe to serialize with :mod:`pickle`. They use a stable
367 format so the same pickle can be loaded in future packaging releases.
369 .. versionchanged:: 26.2
371 Added a stable pickle format. Pickles created with packaging 26.2+ can
372 be unpickled with future releases. Backward compatibility with pickles
373 from pip._vendor.packaging < 26.2 is supported but may be removed in a future
374 release.
375 """
377 __slots__ = (
378 "_dev",
379 "_epoch",
380 "_hash_cache",
381 "_key_cache",
382 "_local",
383 "_post",
384 "_pre",
385 "_release",
386 )
387 __match_args__ = ("_str",)
388 """
389 Pattern matching is supported on Python 3.10+.
391 .. versionadded:: 26.0
393 :meta hide-value:
394 """
396 _regex = re.compile(r"\s*" + VERSION_PATTERN + r"\s*", re.VERBOSE | re.IGNORECASE)
398 _epoch: int
399 _release: tuple[int, ...]
400 _dev: tuple[Literal["dev"], int] | None
401 _pre: tuple[Literal["a", "b", "rc"], int] | None
402 _post: tuple[Literal["post"], int] | None
403 _local: LocalType | None
405 _hash_cache: int | None
406 _key_cache: CmpKey | None
408 def __init__(self, version: str) -> None:
409 """Initialize a Version object.
411 :param version:
412 The string representation of a version which will be parsed and normalized
413 before use.
414 :raises InvalidVersion:
415 If the ``version`` does not conform to PEP 440 in any way then this
416 exception will be raised.
417 """
418 try:
419 is_simple = _SIMPLE_VERSION_INDICATORS.issuperset(version)
420 except TypeError:
421 raise InvalidVersion(f"Invalid version: {version!r}") from None
423 if is_simple:
424 try:
425 self._release = tuple(map(int, version.split(".")))
426 except AttributeError:
427 raise InvalidVersion(f"Invalid version: {version!r}") from None
428 except ValueError:
429 # Empty parts (from "1..2", ".1", etc.) are invalid versions.
430 # Any other ValueError (e.g. int str-digits limit) should
431 # propagate to the caller.
432 if "" in version.split("."):
433 raise InvalidVersion(f"Invalid version: {version!r}") from None
434 # TODO: remove "no cover" when Python 3.9 is dropped.
435 raise # pragma: no cover
437 self._epoch = 0
438 self._pre = None
439 self._post = None
440 self._dev = None
441 self._local = None
442 self._key_cache = None
443 self._hash_cache = None
444 return
446 # Validate the version and parse it into pieces
447 try:
448 match = self._regex.fullmatch(version)
449 except TypeError:
450 raise InvalidVersion(f"Invalid version: {version!r}") from None
451 if not match:
452 raise InvalidVersion(f"Invalid version: {version!r}")
453 self._epoch = int(match.group("epoch")) if match.group("epoch") else 0
454 self._release = tuple(map(int, match.group("release").split(".")))
455 # We can type ignore the assignments below because the regex guarantees
456 # the correct strings
457 self._pre = _parse_letter_version(match.group("pre_l"), match.group("pre_n")) # type: ignore[assignment]
458 self._post = _parse_letter_version( # type: ignore[assignment]
459 match.group("post_l"), match.group("post_n1") or match.group("post_n2")
460 )
461 self._dev = _parse_letter_version(match.group("dev_l"), match.group("dev_n")) # type: ignore[assignment]
462 self._local = _parse_local_version(match.group("local"))
464 # Key which will be used for sorting
465 self._key_cache = None
466 self._hash_cache = None
468 @classmethod
469 def from_parts(
470 cls,
471 *,
472 epoch: int = 0,
473 release: tuple[int, ...],
474 pre: tuple[str, int] | None = None,
475 post: int | None = None,
476 dev: int | None = None,
477 local: str | None = None,
478 ) -> Self:
479 """
480 Return a new version composed of the various parts.
482 This allows you to build a version without going though a string and
483 running a regular expression. It normalizes pre-release strings. The
484 ``release=`` keyword argument is required.
486 >>> Version.from_parts(release=(1,2,3))
487 <Version('1.2.3')>
488 >>> Version.from_parts(release=(0,1,0), pre=("b", 1))
489 <Version('0.1.0b1')>
491 :param epoch:
492 :param release: This version tuple is required
494 .. versionadded:: 26.1
495 """
496 _epoch = _validate_epoch(epoch)
497 _release = _validate_release(release)
498 _pre = _validate_pre(pre) if pre is not None else None
499 _post = _validate_post(post) if post is not None else None
500 _dev = _validate_dev(dev) if dev is not None else None
501 _local = _validate_local(local) if local is not None else None
503 new_version = cls.__new__(cls)
504 new_version._key_cache = None
505 new_version._hash_cache = None
506 new_version._epoch = _epoch
507 new_version._release = _release
508 new_version._pre = _pre
509 new_version._post = _post
510 new_version._dev = _dev
511 new_version._local = _local
513 return new_version
515 def __replace__(self, **kwargs: Unpack[_VersionReplace]) -> Self:
516 """
517 __replace__(*, epoch=..., release=..., pre=..., post=..., dev=..., local=...)
519 Return a new version with parts replaced.
521 This returns a new version (unless no parts were changed). The
522 pre-release is normalized. Setting a value to ``None`` clears it.
524 >>> v = Version("1.2.3")
525 >>> v.__replace__(pre=("a", 1))
526 <Version('1.2.3a1')>
528 :param int | None epoch:
529 :param tuple[int, ...] | None release:
530 :param tuple[str, int] | None pre:
531 :param int | None post:
532 :param int | None dev:
533 :param str | None local:
535 .. versionadded:: 26.0
536 .. versionchanged:: 26.1
538 The pre-release portion is now normalized.
539 """
540 epoch = _validate_epoch(kwargs["epoch"]) if "epoch" in kwargs else self._epoch
541 release = (
542 _validate_release(kwargs["release"])
543 if "release" in kwargs
544 else self._release
545 )
546 pre = _validate_pre(kwargs["pre"]) if "pre" in kwargs else self._pre
547 post = _validate_post(kwargs["post"]) if "post" in kwargs else self._post
548 dev = _validate_dev(kwargs["dev"]) if "dev" in kwargs else self._dev
549 local = _validate_local(kwargs["local"]) if "local" in kwargs else self._local
551 if (
552 epoch == self._epoch
553 and release == self._release
554 and pre == self._pre
555 and post == self._post
556 and dev == self._dev
557 and local == self._local
558 ):
559 return self
561 new_version = self.__class__.__new__(self.__class__)
562 new_version._key_cache = None
563 new_version._hash_cache = None
564 new_version._epoch = epoch
565 new_version._release = release
566 new_version._pre = pre
567 new_version._post = post
568 new_version._dev = dev
569 new_version._local = local
571 return new_version
573 @property
574 def _key(self) -> CmpKey:
575 if self._key_cache is None:
576 self._key_cache = _cmpkey(
577 self._epoch,
578 self._release,
579 self._pre,
580 self._post,
581 self._dev,
582 self._local,
583 )
584 return self._key_cache
586 # __hash__ must be defined when __eq__ is overridden,
587 # otherwise Python sets __hash__ to None.
588 def __hash__(self) -> int:
589 if (cached_hash := self._hash_cache) is not None:
590 return cached_hash
592 if (key := self._key_cache) is None:
593 self._key_cache = key = _cmpkey(
594 self._epoch,
595 self._release,
596 self._pre,
597 self._post,
598 self._dev,
599 self._local,
600 )
601 self._hash_cache = cached_hash = hash(key)
602 return cached_hash
604 # Override comparison methods to use direct _key_cache access
605 # This is faster than property access, especially before Python 3.12
606 def __lt__(self, other: _BaseVersion) -> bool:
607 if isinstance(other, Version):
608 if self._key_cache is None:
609 self._key_cache = _cmpkey(
610 self._epoch,
611 self._release,
612 self._pre,
613 self._post,
614 self._dev,
615 self._local,
616 )
617 if other._key_cache is None:
618 other._key_cache = _cmpkey(
619 other._epoch,
620 other._release,
621 other._pre,
622 other._post,
623 other._dev,
624 other._local,
625 )
626 return self._key_cache < other._key_cache
628 if not isinstance(other, _BaseVersion):
629 return NotImplemented
631 return super().__lt__(other)
633 def __le__(self, other: _BaseVersion) -> bool:
634 if isinstance(other, Version):
635 if self._key_cache is None:
636 self._key_cache = _cmpkey(
637 self._epoch,
638 self._release,
639 self._pre,
640 self._post,
641 self._dev,
642 self._local,
643 )
644 if other._key_cache is None:
645 other._key_cache = _cmpkey(
646 other._epoch,
647 other._release,
648 other._pre,
649 other._post,
650 other._dev,
651 other._local,
652 )
653 return self._key_cache <= other._key_cache
655 if not isinstance(other, _BaseVersion):
656 return NotImplemented
658 return super().__le__(other)
660 def __eq__(self, other: object) -> bool:
661 if isinstance(other, Version):
662 if self._key_cache is None:
663 self._key_cache = _cmpkey(
664 self._epoch,
665 self._release,
666 self._pre,
667 self._post,
668 self._dev,
669 self._local,
670 )
671 if other._key_cache is None:
672 other._key_cache = _cmpkey(
673 other._epoch,
674 other._release,
675 other._pre,
676 other._post,
677 other._dev,
678 other._local,
679 )
680 return self._key_cache == other._key_cache
682 if not isinstance(other, _BaseVersion):
683 return NotImplemented
685 return super().__eq__(other)
687 def __ge__(self, other: _BaseVersion) -> bool:
688 if isinstance(other, Version):
689 if self._key_cache is None:
690 self._key_cache = _cmpkey(
691 self._epoch,
692 self._release,
693 self._pre,
694 self._post,
695 self._dev,
696 self._local,
697 )
698 if other._key_cache is None:
699 other._key_cache = _cmpkey(
700 other._epoch,
701 other._release,
702 other._pre,
703 other._post,
704 other._dev,
705 other._local,
706 )
707 return self._key_cache >= other._key_cache
709 if not isinstance(other, _BaseVersion):
710 return NotImplemented
712 return super().__ge__(other)
714 def __gt__(self, other: _BaseVersion) -> bool:
715 if isinstance(other, Version):
716 if self._key_cache is None:
717 self._key_cache = _cmpkey(
718 self._epoch,
719 self._release,
720 self._pre,
721 self._post,
722 self._dev,
723 self._local,
724 )
725 if other._key_cache is None:
726 other._key_cache = _cmpkey(
727 other._epoch,
728 other._release,
729 other._pre,
730 other._post,
731 other._dev,
732 other._local,
733 )
734 return self._key_cache > other._key_cache
736 if not isinstance(other, _BaseVersion):
737 return NotImplemented
739 return super().__gt__(other)
741 def __ne__(self, other: object) -> bool:
742 if isinstance(other, Version):
743 if self._key_cache is None:
744 self._key_cache = _cmpkey(
745 self._epoch,
746 self._release,
747 self._pre,
748 self._post,
749 self._dev,
750 self._local,
751 )
752 if other._key_cache is None:
753 other._key_cache = _cmpkey(
754 other._epoch,
755 other._release,
756 other._pre,
757 other._post,
758 other._dev,
759 other._local,
760 )
761 return self._key_cache != other._key_cache
763 if not isinstance(other, _BaseVersion):
764 return NotImplemented
766 return super().__ne__(other)
768 def __getstate__(
769 self,
770 ) -> tuple[
771 int,
772 tuple[int, ...],
773 tuple[str, int] | None,
774 tuple[str, int] | None,
775 tuple[str, int] | None,
776 LocalType | None,
777 ]:
778 # Return state as a 6-item tuple for compactness:
779 # (epoch, release, pre, post, dev, local)
780 # Cache members are excluded and will be recomputed on demand
781 return (
782 self._epoch,
783 self._release,
784 self._pre,
785 self._post,
786 self._dev,
787 self._local,
788 )
790 def __setstate__(self, state: object) -> None:
791 # Always discard cached values — they may contain stale references
792 # (e.g. packaging._structures.InfinityType from pre-26.1 pickles)
793 # and will be recomputed on demand from the core fields above.
794 self._key_cache = None
795 self._hash_cache = None
797 if isinstance(state, tuple):
798 if len(state) == 6:
799 # New format (26.2+): (epoch, release, pre, post, dev, local)
800 (
801 self._epoch,
802 self._release,
803 self._pre,
804 self._post,
805 self._dev,
806 self._local,
807 ) = state
808 return
809 if len(state) == 2:
810 # Format (packaging 26.0-26.1): (None, {slot: value}).
811 _, slot_dict = state
812 if isinstance(slot_dict, dict):
813 self._epoch = slot_dict["_epoch"]
814 self._release = slot_dict["_release"]
815 self._pre = slot_dict.get("_pre")
816 self._post = slot_dict.get("_post")
817 self._dev = slot_dict.get("_dev")
818 self._local = slot_dict.get("_local")
819 return
820 if isinstance(state, dict):
821 # Old format (packaging <= 25.x, no __slots__): state is a plain
822 # dict with "_version" (_Version NamedTuple) and "_key" entries.
823 version_nt = state.get("_version")
824 if version_nt is not None:
825 self._epoch = version_nt.epoch
826 self._release = version_nt.release
827 self._pre = version_nt.pre
828 self._post = version_nt.post
829 self._dev = version_nt.dev
830 self._local = version_nt.local
831 return
833 raise TypeError(f"Cannot restore Version from {state!r}")
835 @property
836 @_deprecated("Version._version is private and will be removed soon")
837 def _version(self) -> _Version:
838 return _Version(
839 self._epoch, self._release, self._dev, self._pre, self._post, self._local
840 )
842 @_version.setter
843 @_deprecated("Version._version is private and will be removed soon")
844 def _version(self, value: _Version) -> None:
845 self._epoch = value.epoch
846 self._release = value.release
847 self._dev = value.dev
848 self._pre = value.pre
849 self._post = value.post
850 self._local = value.local
851 self._key_cache = None
852 self._hash_cache = None
854 def __repr__(self) -> str:
855 """A representation of the Version that shows all internal state.
857 >>> Version('1.0.0')
858 <Version('1.0.0')>
859 """
860 return f"<{self.__class__.__name__}({str(self)!r})>"
862 def __str__(self) -> str:
863 """A string representation of the version that can be round-tripped.
865 >>> str(Version("1.0a5"))
866 '1.0a5'
867 """
868 # This is a hot function, so not calling self.base_version
869 version = ".".join(map(str, self.release))
871 # Epoch
872 if self.epoch:
873 version = f"{self.epoch}!{version}"
875 # Pre-release
876 if self.pre is not None:
877 version += "".join(map(str, self.pre))
879 # Post-release
880 if self.post is not None:
881 version += f".post{self.post}"
883 # Development release
884 if self.dev is not None:
885 version += f".dev{self.dev}"
887 # Local version segment
888 if self.local is not None:
889 version += f"+{self.local}"
891 return version
893 @property
894 def _str(self) -> str:
895 """Internal property for match_args"""
896 return str(self)
898 @property
899 def epoch(self) -> int:
900 """The epoch of the version.
902 >>> Version("2.0.0").epoch
903 0
904 >>> Version("1!2.0.0").epoch
905 1
906 """
907 return self._epoch
909 @property
910 def release(self) -> tuple[int, ...]:
911 """The components of the "release" segment of the version.
913 >>> Version("1.2.3").release
914 (1, 2, 3)
915 >>> Version("2.0.0").release
916 (2, 0, 0)
917 >>> Version("1!2.0.0.post0").release
918 (2, 0, 0)
920 Includes trailing zeroes but not the epoch or any pre-release / development /
921 post-release suffixes.
922 """
923 return self._release
925 @property
926 def pre(self) -> tuple[Literal["a", "b", "rc"], int] | None:
927 """The pre-release segment of the version.
929 >>> print(Version("1.2.3").pre)
930 None
931 >>> Version("1.2.3a1").pre
932 ('a', 1)
933 >>> Version("1.2.3b1").pre
934 ('b', 1)
935 >>> Version("1.2.3rc1").pre
936 ('rc', 1)
937 """
938 return self._pre
940 @property
941 def post(self) -> int | None:
942 """The post-release number of the version.
944 >>> print(Version("1.2.3").post)
945 None
946 >>> Version("1.2.3.post1").post
947 1
948 """
949 return self._post[1] if self._post else None
951 @property
952 def dev(self) -> int | None:
953 """The development number of the version.
955 >>> print(Version("1.2.3").dev)
956 None
957 >>> Version("1.2.3.dev1").dev
958 1
959 """
960 return self._dev[1] if self._dev else None
962 @property
963 def local(self) -> str | None:
964 """The local version segment of the version.
966 >>> print(Version("1.2.3").local)
967 None
968 >>> Version("1.2.3+abc").local
969 'abc'
970 """
971 if self._local:
972 return ".".join(str(x) for x in self._local)
973 else:
974 return None
976 @property
977 def public(self) -> str:
978 """The public portion of the version.
980 This returns a string. If you want a :class:`Version` again and care
981 about performance, use ``v.__replace__(local=None)`` instead.
983 >>> Version("1.2.3").public
984 '1.2.3'
985 >>> Version("1.2.3+abc").public
986 '1.2.3'
987 >>> Version("1!1.2.3dev1+abc").public
988 '1!1.2.3.dev1'
989 """
990 return str(self).split("+", 1)[0]
992 @property
993 def base_version(self) -> str:
994 """The "base version" of the version.
996 This returns a string. If you want a :class:`Version` again and care
997 about performance, use
998 ``v.__replace__(pre=None, post=None, dev=None, local=None)`` instead.
1000 >>> Version("1.2.3").base_version
1001 '1.2.3'
1002 >>> Version("1.2.3+abc").base_version
1003 '1.2.3'
1004 >>> Version("1!1.2.3dev1+abc").base_version
1005 '1!1.2.3'
1007 The "base version" is the public version of the project without any pre or post
1008 release markers.
1009 """
1010 release_segment = ".".join(map(str, self.release))
1011 return f"{self.epoch}!{release_segment}" if self.epoch else release_segment
1013 @property
1014 def is_prerelease(self) -> bool:
1015 """Whether this version is a pre-release.
1017 >>> Version("1.2.3").is_prerelease
1018 False
1019 >>> Version("1.2.3a1").is_prerelease
1020 True
1021 >>> Version("1.2.3b1").is_prerelease
1022 True
1023 >>> Version("1.2.3rc1").is_prerelease
1024 True
1025 >>> Version("1.2.3dev1").is_prerelease
1026 True
1027 """
1028 return self.dev is not None or self.pre is not None
1030 @property
1031 def is_postrelease(self) -> bool:
1032 """Whether this version is a post-release.
1034 >>> Version("1.2.3").is_postrelease
1035 False
1036 >>> Version("1.2.3.post1").is_postrelease
1037 True
1038 """
1039 return self.post is not None
1041 @property
1042 def is_devrelease(self) -> bool:
1043 """Whether this version is a development release.
1045 >>> Version("1.2.3").is_devrelease
1046 False
1047 >>> Version("1.2.3.dev1").is_devrelease
1048 True
1049 """
1050 return self.dev is not None
1052 @property
1053 def major(self) -> int:
1054 """The first item of :attr:`release` or ``0`` if unavailable.
1056 >>> Version("1.2.3").major
1057 1
1059 .. versionadded:: 20.0
1060 """
1061 return self.release[0] if len(self.release) >= 1 else 0
1063 @property
1064 def minor(self) -> int:
1065 """The second item of :attr:`release` or ``0`` if unavailable.
1067 >>> Version("1.2.3").minor
1068 2
1069 >>> Version("1").minor
1070 0
1072 .. versionadded:: 20.0
1073 """
1074 return self.release[1] if len(self.release) >= 2 else 0
1076 @property
1077 def micro(self) -> int:
1078 """The third item of :attr:`release` or ``0`` if unavailable.
1080 >>> Version("1.2.3").micro
1081 3
1082 >>> Version("1").micro
1083 0
1085 .. versionadded:: 20.0
1086 """
1087 return self.release[2] if len(self.release) >= 3 else 0
1090class _TrimmedRelease(Version):
1091 __slots__ = ()
1093 def __init__(self, version: str | Version) -> None:
1094 if isinstance(version, Version):
1095 self._epoch = version._epoch
1096 self._release = version._release
1097 self._dev = version._dev
1098 self._pre = version._pre
1099 self._post = version._post
1100 self._local = version._local
1101 self._key_cache = version._key_cache
1102 self._hash_cache = version._hash_cache
1103 return
1104 super().__init__(version) # pragma: no cover
1106 @property
1107 def release(self) -> tuple[int, ...]:
1108 """
1109 Release segment without any trailing zeros.
1111 >>> _TrimmedRelease('1.0.0').release
1112 (1,)
1113 >>> _TrimmedRelease('0.0').release
1114 (0,)
1115 """
1116 # This leaves one 0.
1117 rel = super().release
1118 len_release = len(rel)
1119 i = len_release
1120 while i > 1 and rel[i - 1] == 0:
1121 i -= 1
1122 return rel if i == len_release else rel[:i]
1125def _parse_letter_version(
1126 letter: str | None, number: str | bytes | SupportsInt | None
1127) -> tuple[str, int] | None:
1128 if letter:
1129 # We normalize any letters to their lower case form
1130 letter = letter.lower()
1132 # We consider some words to be alternate spellings of other words and
1133 # in those cases we want to normalize the spellings to our preferred
1134 # spelling.
1135 letter = _LETTER_NORMALIZATION.get(letter, letter)
1137 # We consider there to be an implicit 0 in a pre-release if there is
1138 # not a numeral associated with it.
1139 return letter, int(number or 0)
1141 if number:
1142 # We assume if we are given a number, but we are not given a letter
1143 # then this is using the implicit post release syntax (e.g. 1.0-1)
1144 return "post", int(number)
1146 return None
1149_local_version_separators = re.compile(r"[\._-]")
1152def _parse_local_version(local: str | None) -> LocalType | None:
1153 """
1154 Takes a string like ``"abc.1.twelve"`` and turns it into
1155 ``("abc", 1, "twelve")``.
1156 """
1157 if local is not None:
1158 return tuple(
1159 part.lower() if not part.isdigit() else int(part)
1160 for part in _local_version_separators.split(local)
1161 )
1162 return None
1165# Sort ranks for pre-release: dev-only < a < b < rc < stable (no pre-release).
1166_PRE_RANK = {"a": 0, "b": 1, "rc": 2}
1167_PRE_RANK_DEV_ONLY = -1 # sorts before a(0)
1168_PRE_RANK_STABLE = 3 # sorts after rc(2)
1170# In local version segments, strings sort before ints per PEP 440.
1171_LOCAL_STR_RANK = -1 # sorts before all non-negative ints
1173# Pre-computed suffix for stable releases (no pre, post, or dev segments).
1174# See _cmpkey() for the suffix layout.
1175_STABLE_SUFFIX = (_PRE_RANK_STABLE, 0, 0, 0, 1, 0)
1178def _cmpkey(
1179 epoch: int,
1180 release: tuple[int, ...],
1181 pre: tuple[str, int] | None,
1182 post: tuple[str, int] | None,
1183 dev: tuple[str, int] | None,
1184 local: LocalType | None,
1185) -> CmpKey:
1186 """Build a comparison key for PEP 440 ordering.
1188 Returns ``(epoch, release, suffix)`` or
1189 ``(epoch, release, suffix, local)`` so that plain tuple
1190 comparison gives the correct order.
1192 Trailing zeros are stripped from the release so that ``1.0.0 == 1``.
1194 The suffix is a flat 6-int tuple that encodes pre/post/dev:
1195 ``(pre_rank, pre_n, post_rank, post_n, dev_rank, dev_n)``
1197 pre_rank: dev-only=-1, a=0, b=1, rc=2, no-pre=3
1198 Dev-only releases (no pre or post) get -1 so they sort before
1199 any alpha/beta/rc. Releases without a pre-release tag get 3
1200 so they sort after rc.
1201 post_rank: no-post=0, post=1
1202 Releases without a post segment sort before those with one.
1203 dev_rank: dev=0, no-dev=1
1204 Releases without a dev segment sort after those with one.
1206 Local segments use ``(n, "")`` for ints and ``(-1, s)`` for strings,
1207 following PEP 440: strings sort before ints, strings compare
1208 lexicographically, ints compare numerically, and shorter segments
1209 sort before longer when prefixes match. Versions without a local
1210 segment sort before those with one (3-tuple < 4-tuple).
1212 >>> _cmpkey(0, (1, 0, 0), None, None, None, None)
1213 (0, (1,), (3, 0, 0, 0, 1, 0))
1214 >>> _cmpkey(0, (1,), ("a", 1), None, None, None)
1215 (0, (1,), (0, 1, 0, 0, 1, 0))
1216 >>> _cmpkey(0, (1,), None, None, None, ("ubuntu", 1))
1217 (0, (1,), (3, 0, 0, 0, 1, 0), ((-1, 'ubuntu'), (1, '')))
1218 """
1219 # Strip trailing zeros: 1.0.0 compares equal to 1.
1220 len_release = len(release)
1221 i = len_release
1222 while i and release[i - 1] == 0:
1223 i -= 1
1224 trimmed = release if i == len_release else release[:i]
1226 # Fast path: stable release with no local segment.
1227 if pre is None and post is None and dev is None and local is None:
1228 return epoch, trimmed, _STABLE_SUFFIX
1230 if pre is None and post is None and dev is not None:
1231 # dev-only (e.g. 1.0.dev1) sorts before all pre-releases.
1232 pre_rank, pre_n = _PRE_RANK_DEV_ONLY, 0
1233 elif pre is None:
1234 pre_rank, pre_n = _PRE_RANK_STABLE, 0
1235 else:
1236 pre_rank, pre_n = _PRE_RANK[pre[0]], pre[1]
1238 post_rank = 0 if post is None else 1
1239 post_n = 0 if post is None else post[1]
1241 dev_rank = 1 if dev is None else 0
1242 dev_n = 0 if dev is None else dev[1]
1244 suffix = (pre_rank, pre_n, post_rank, post_n, dev_rank, dev_n)
1246 if local is None:
1247 return epoch, trimmed, suffix
1249 cmp_local: CmpLocalType = tuple(
1250 (seg, "") if isinstance(seg, int) else (_LOCAL_STR_RANK, seg) for seg in local
1251 )
1252 return epoch, trimmed, suffix, cmp_local