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 Tuple,
22 TypedDict,
23 Union,
24)
26if typing.TYPE_CHECKING:
27 from typing_extensions import Self, Unpack
29if sys.version_info >= (3, 13): # pragma: no cover
30 from warnings import deprecated as _deprecated
31elif typing.TYPE_CHECKING:
32 from typing_extensions import deprecated as _deprecated
33else: # pragma: no cover
34 import functools
35 import warnings
37 def _deprecated(message: str) -> object:
38 def decorator(func: Callable[[...], object]) -> object:
39 @functools.wraps(func)
40 def wrapper(*args: object, **kwargs: object) -> object:
41 warnings.warn(
42 message,
43 category=DeprecationWarning,
44 stacklevel=2,
45 )
46 return func(*args, **kwargs)
48 return wrapper
50 return decorator
53_LETTER_NORMALIZATION = {
54 "alpha": "a",
55 "beta": "b",
56 "c": "rc",
57 "pre": "rc",
58 "preview": "rc",
59 "rev": "post",
60 "r": "post",
61}
63__all__ = ["VERSION_PATTERN", "InvalidVersion", "Version", "normalize_pre", "parse"]
66def __dir__() -> list[str]:
67 return __all__
70LocalType = Tuple[Union[int, str], ...]
72CmpLocalType = Tuple[Tuple[int, str], ...]
73CmpSuffix = Tuple[int, int, int, int, int, int]
74CmpKey = Union[
75 Tuple[int, Tuple[int, ...], CmpSuffix],
76 Tuple[int, Tuple[int, ...], CmpSuffix, CmpLocalType],
77]
78VersionComparisonMethod = Callable[[CmpKey, CmpKey], bool]
81class _VersionReplace(TypedDict, total=False):
82 epoch: int | None
83 release: tuple[int, ...] | None
84 pre: tuple[str, int] | None
85 post: int | None
86 dev: int | None
87 local: str | None
90def normalize_pre(letter: str, /) -> str:
91 """Normalize the pre-release segment of a version string.
93 Returns a lowercase version of the string if not a known pre-release
94 identifier.
96 >>> normalize_pre('alpha')
97 'a'
98 >>> normalize_pre('BETA')
99 'b'
100 >>> normalize_pre('rc')
101 'rc'
103 :param letter:
105 .. versionadded:: 26.1
106 """
107 letter = letter.lower()
108 return _LETTER_NORMALIZATION.get(letter, letter)
111def parse(version: str) -> Version:
112 """Parse the given version string.
114 This is identical to the :class:`Version` constructor.
116 >>> parse('1.0.dev1')
117 <Version('1.0.dev1')>
119 :param version: The version string to parse.
120 :raises InvalidVersion: When the version string is not a valid version.
121 """
122 return Version(version)
125class InvalidVersion(ValueError):
126 """Raised when a version string is not a valid version.
128 >>> Version("invalid")
129 Traceback (most recent call last):
130 ...
131 packaging.version.InvalidVersion: Invalid version: 'invalid'
132 """
135class _BaseVersion:
136 __slots__ = ()
138 # This can also be a normal member (see the packaging_legacy package);
139 # we are just requiring it to be readable. Actually defining a property
140 # has runtime effect on subclasses, so it's typing only.
141 if typing.TYPE_CHECKING:
143 @property
144 def _key(self) -> tuple[Any, ...]: ...
146 def __hash__(self) -> int:
147 return hash(self._key)
149 # Please keep the duplicated `isinstance` check
150 # in the six comparisons hereunder
151 # unless you find a way to avoid adding overhead function calls.
152 def __lt__(self, other: _BaseVersion) -> bool:
153 if not isinstance(other, _BaseVersion):
154 return NotImplemented
156 return self._key < other._key
158 def __le__(self, other: _BaseVersion) -> bool:
159 if not isinstance(other, _BaseVersion):
160 return NotImplemented
162 return self._key <= other._key
164 def __eq__(self, other: object) -> bool:
165 if not isinstance(other, _BaseVersion):
166 return NotImplemented
168 return self._key == other._key
170 def __ge__(self, other: _BaseVersion) -> bool:
171 if not isinstance(other, _BaseVersion):
172 return NotImplemented
174 return self._key >= other._key
176 def __gt__(self, other: _BaseVersion) -> bool:
177 if not isinstance(other, _BaseVersion):
178 return NotImplemented
180 return self._key > other._key
182 def __ne__(self, other: object) -> bool:
183 if not isinstance(other, _BaseVersion):
184 return NotImplemented
186 return self._key != other._key
189# Deliberately not anchored to the start and end of the string, to make it
190# easier for 3rd party code to reuse
192# Note that ++ doesn't behave identically on CPython and PyPy, so not using it here
193_VERSION_PATTERN = r"""
194 v?+ # optional leading v
195 (?a:
196 (?:(?P<epoch>[0-9]+)!)?+ # epoch
197 (?P<release>[0-9]+(?:\.[0-9]+)*+) # release segment
198 (?P<pre> # pre-release
199 [._-]?+
200 (?P<pre_l>alpha|a|beta|b|preview|pre|c|rc)
201 [._-]?+
202 (?P<pre_n>[0-9]+)?
203 )?+
204 (?P<post> # post release
205 (?:-(?P<post_n1>[0-9]+))
206 |
207 (?:
208 [._-]?
209 (?P<post_l>post|rev|r)
210 [._-]?
211 (?P<post_n2>[0-9]+)?
212 )
213 )?+
214 (?P<dev> # dev release
215 [._-]?+
216 (?P<dev_l>dev)
217 [._-]?+
218 (?P<dev_n>[0-9]+)?
219 )?+
220 )
221 (?a:\+
222 (?P<local> # local version
223 [a-z0-9]+
224 (?:[._-][a-z0-9]+)*+
225 )
226 )?+
227"""
229_VERSION_PATTERN_OLD = _VERSION_PATTERN.replace("*+", "*").replace("?+", "?")
231# Possessive qualifiers were added in Python 3.11.
232# CPython 3.11.0-3.11.4 had a bug: https://github.com/python/cpython/pull/107795
233# Older PyPy also had a bug.
234VERSION_PATTERN = (
235 _VERSION_PATTERN_OLD
236 if (sys.implementation.name == "cpython" and sys.version_info < (3, 11, 5))
237 or (sys.implementation.name == "pypy" and sys.version_info < (3, 11, 13))
238 or sys.version_info < (3, 11)
239 else _VERSION_PATTERN
240)
241"""
242A string containing the regular expression used to match a valid version.
244The pattern is not anchored at either end, and is intended for embedding in larger
245expressions (for example, matching a version number as part of a file name). The
246regular expression should be compiled with the ``re.VERBOSE`` and ``re.IGNORECASE``
247flags set.
249.. versionchanged:: 26.0
251 The regex now uses possessive qualifiers on Python 3.11 if they are
252 supported (CPython 3.11.5+, PyPy 3.11.13+).
254:meta hide-value:
255"""
258# Validation pattern for local version in replace()
259_LOCAL_PATTERN = re.compile(r"[a-z0-9]+(?:[._-][a-z0-9]+)*", re.IGNORECASE | re.ASCII)
261# Fast path: If a version has only digits and dots then we
262# can skip the regex and parse it as a release segment
263_SIMPLE_VERSION_INDICATORS = frozenset(".0123456789")
266def _validate_epoch(value: object, /) -> int:
267 epoch = value or 0
268 if isinstance(epoch, int) and epoch >= 0:
269 return epoch
270 msg = f"epoch must be non-negative integer, got {epoch}"
271 raise InvalidVersion(msg)
274def _validate_release(value: object, /) -> tuple[int, ...]:
275 release = (0,) if value is None else value
276 if (
277 isinstance(release, tuple)
278 and len(release) > 0
279 and all(isinstance(i, int) and i >= 0 for i in release)
280 ):
281 return release
282 msg = f"release must be a non-empty tuple of non-negative integers, got {release}"
283 raise InvalidVersion(msg)
286def _validate_pre(value: object, /) -> tuple[Literal["a", "b", "rc"], int] | None:
287 if value is None:
288 return value
289 if isinstance(value, tuple) and len(value) == 2:
290 letter, number = value
291 letter = normalize_pre(letter)
292 if letter in {"a", "b", "rc"} and isinstance(number, int) and number >= 0:
293 # type checkers can't infer the Literal type here on letter
294 return (letter, number) # type: ignore[return-value]
295 msg = f"pre must be a tuple of ('a'|'b'|'rc', non-negative int), got {value}"
296 raise InvalidVersion(msg)
299def _validate_post(value: object, /) -> tuple[Literal["post"], int] | None:
300 if value is None:
301 return value
302 if isinstance(value, int) and value >= 0:
303 return ("post", value)
304 msg = f"post must be non-negative integer, got {value}"
305 raise InvalidVersion(msg)
308def _validate_dev(value: object, /) -> tuple[Literal["dev"], int] | None:
309 if value is None:
310 return value
311 if isinstance(value, int) and value >= 0:
312 return ("dev", value)
313 msg = f"dev must be non-negative integer, got {value}"
314 raise InvalidVersion(msg)
317def _validate_local(value: object, /) -> LocalType | None:
318 if value is None:
319 return value
320 if isinstance(value, str) and _LOCAL_PATTERN.fullmatch(value):
321 return _parse_local_version(value)
322 msg = f"local must be a valid version string, got {value!r}"
323 raise InvalidVersion(msg)
326# Backward compatibility for internals before 26.0. Do not use.
327class _Version(NamedTuple):
328 epoch: int
329 release: tuple[int, ...]
330 dev: tuple[Literal["dev"], int] | None
331 pre: tuple[Literal["a", "b", "rc"], int] | None
332 post: tuple[Literal["post"], int] | None
333 local: LocalType | None
336class Version(_BaseVersion):
337 """This class abstracts handling of a project's versions.
339 A :class:`Version` instance is comparison aware and can be compared and
340 sorted using the standard Python interfaces.
342 >>> v1 = Version("1.0a5")
343 >>> v2 = Version("1.0")
344 >>> v1
345 <Version('1.0a5')>
346 >>> v2
347 <Version('1.0')>
348 >>> v1 < v2
349 True
350 >>> v1 == v2
351 False
352 >>> v1 > v2
353 False
354 >>> v1 >= v2
355 False
356 >>> v1 <= v2
357 True
359 :class:`Version` is immutable; use :meth:`__replace__` to change
360 part of a version.
362 Instances are safe to serialize with :mod:`pickle`. They use a stable
363 format so the same pickle can be loaded in future packaging releases.
365 .. versionchanged:: 26.2
367 Added a stable pickle format. Pickles created with packaging 26.2+ can
368 be unpickled with future releases. Backward compatibility with pickles
369 from pip._vendor.packaging < 26.2 is supported but may be removed in a future
370 release.
371 """
373 __slots__ = (
374 "_dev",
375 "_epoch",
376 "_hash_cache",
377 "_key_cache",
378 "_local",
379 "_post",
380 "_pre",
381 "_release",
382 )
383 __match_args__ = ("_str",)
384 """
385 Pattern matching is supported on Python 3.10+.
387 .. versionadded:: 26.0
389 :meta hide-value:
390 """
392 _regex = re.compile(r"\s*" + VERSION_PATTERN + r"\s*", re.VERBOSE | re.IGNORECASE)
394 _epoch: int
395 _release: tuple[int, ...]
396 _dev: tuple[Literal["dev"], int] | None
397 _pre: tuple[Literal["a", "b", "rc"], int] | None
398 _post: tuple[Literal["post"], int] | None
399 _local: LocalType | None
401 _hash_cache: int | None
402 _key_cache: CmpKey | None
404 def __init__(self, version: str) -> None:
405 """Initialize a Version object.
407 :param version:
408 The string representation of a version which will be parsed and normalized
409 before use.
410 :raises InvalidVersion:
411 If the ``version`` does not conform to PEP 440 in any way then this
412 exception will be raised.
413 """
414 if _SIMPLE_VERSION_INDICATORS.issuperset(version):
415 try:
416 self._release = tuple(map(int, version.split(".")))
417 except ValueError:
418 # Empty parts (from "1..2", ".1", etc.) are invalid versions.
419 # Any other ValueError (e.g. int str-digits limit) should
420 # propagate to the caller.
421 if "" in version.split("."):
422 raise InvalidVersion(f"Invalid version: {version!r}") from None
423 # TODO: remove "no cover" when Python 3.9 is dropped.
424 raise # pragma: no cover
426 self._epoch = 0
427 self._pre = None
428 self._post = None
429 self._dev = None
430 self._local = None
431 self._key_cache = None
432 self._hash_cache = None
433 return
435 # Validate the version and parse it into pieces
436 match = self._regex.fullmatch(version)
437 if not match:
438 raise InvalidVersion(f"Invalid version: {version!r}")
439 self._epoch = int(match.group("epoch")) if match.group("epoch") else 0
440 self._release = tuple(map(int, match.group("release").split(".")))
441 # We can type ignore the assignments below because the regex guarantees
442 # the correct strings
443 self._pre = _parse_letter_version(match.group("pre_l"), match.group("pre_n")) # type: ignore[assignment]
444 self._post = _parse_letter_version( # type: ignore[assignment]
445 match.group("post_l"), match.group("post_n1") or match.group("post_n2")
446 )
447 self._dev = _parse_letter_version(match.group("dev_l"), match.group("dev_n")) # type: ignore[assignment]
448 self._local = _parse_local_version(match.group("local"))
450 # Key which will be used for sorting
451 self._key_cache = None
452 self._hash_cache = None
454 @classmethod
455 def from_parts(
456 cls,
457 *,
458 epoch: int = 0,
459 release: tuple[int, ...],
460 pre: tuple[str, int] | None = None,
461 post: int | None = None,
462 dev: int | None = None,
463 local: str | None = None,
464 ) -> Self:
465 """
466 Return a new version composed of the various parts.
468 This allows you to build a version without going though a string and
469 running a regular expression. It normalizes pre-release strings. The
470 ``release=`` keyword argument is required.
472 >>> Version.from_parts(release=(1,2,3))
473 <Version('1.2.3')>
474 >>> Version.from_parts(release=(0,1,0), pre=("b", 1))
475 <Version('0.1.0b1')>
477 :param epoch:
478 :param release: This version tuple is required
480 .. versionadded:: 26.1
481 """
482 _epoch = _validate_epoch(epoch)
483 _release = _validate_release(release)
484 _pre = _validate_pre(pre) if pre is not None else None
485 _post = _validate_post(post) if post is not None else None
486 _dev = _validate_dev(dev) if dev is not None else None
487 _local = _validate_local(local) if local is not None else None
489 new_version = cls.__new__(cls)
490 new_version._key_cache = None
491 new_version._hash_cache = None
492 new_version._epoch = _epoch
493 new_version._release = _release
494 new_version._pre = _pre
495 new_version._post = _post
496 new_version._dev = _dev
497 new_version._local = _local
499 return new_version
501 def __replace__(self, **kwargs: Unpack[_VersionReplace]) -> Self:
502 """
503 __replace__(*, epoch=..., release=..., pre=..., post=..., dev=..., local=...)
505 Return a new version with parts replaced.
507 This returns a new version (unless no parts were changed). The
508 pre-release is normalized. Setting a value to ``None`` clears it.
510 >>> v = Version("1.2.3")
511 >>> v.__replace__(pre=("a", 1))
512 <Version('1.2.3a1')>
514 :param int | None epoch:
515 :param tuple[int, ...] | None release:
516 :param tuple[str, int] | None pre:
517 :param int | None post:
518 :param int | None dev:
519 :param str | None local:
521 .. versionadded:: 26.0
522 .. versionchanged:: 26.1
524 The pre-release portion is now normalized.
525 """
526 epoch = _validate_epoch(kwargs["epoch"]) if "epoch" in kwargs else self._epoch
527 release = (
528 _validate_release(kwargs["release"])
529 if "release" in kwargs
530 else self._release
531 )
532 pre = _validate_pre(kwargs["pre"]) if "pre" in kwargs else self._pre
533 post = _validate_post(kwargs["post"]) if "post" in kwargs else self._post
534 dev = _validate_dev(kwargs["dev"]) if "dev" in kwargs else self._dev
535 local = _validate_local(kwargs["local"]) if "local" in kwargs else self._local
537 if (
538 epoch == self._epoch
539 and release == self._release
540 and pre == self._pre
541 and post == self._post
542 and dev == self._dev
543 and local == self._local
544 ):
545 return self
547 new_version = self.__class__.__new__(self.__class__)
548 new_version._key_cache = None
549 new_version._hash_cache = None
550 new_version._epoch = epoch
551 new_version._release = release
552 new_version._pre = pre
553 new_version._post = post
554 new_version._dev = dev
555 new_version._local = local
557 return new_version
559 @property
560 def _key(self) -> CmpKey:
561 if self._key_cache is None:
562 self._key_cache = _cmpkey(
563 self._epoch,
564 self._release,
565 self._pre,
566 self._post,
567 self._dev,
568 self._local,
569 )
570 return self._key_cache
572 # __hash__ must be defined when __eq__ is overridden,
573 # otherwise Python sets __hash__ to None.
574 def __hash__(self) -> int:
575 if (cached_hash := self._hash_cache) is not None:
576 return cached_hash
578 if (key := self._key_cache) is None:
579 self._key_cache = key = _cmpkey(
580 self._epoch,
581 self._release,
582 self._pre,
583 self._post,
584 self._dev,
585 self._local,
586 )
587 self._hash_cache = cached_hash = hash(key)
588 return cached_hash
590 # Override comparison methods to use direct _key_cache access
591 # This is faster than property access, especially before Python 3.12
592 def __lt__(self, other: _BaseVersion) -> bool:
593 if isinstance(other, Version):
594 if self._key_cache is None:
595 self._key_cache = _cmpkey(
596 self._epoch,
597 self._release,
598 self._pre,
599 self._post,
600 self._dev,
601 self._local,
602 )
603 if other._key_cache is None:
604 other._key_cache = _cmpkey(
605 other._epoch,
606 other._release,
607 other._pre,
608 other._post,
609 other._dev,
610 other._local,
611 )
612 return self._key_cache < other._key_cache
614 if not isinstance(other, _BaseVersion):
615 return NotImplemented
617 return super().__lt__(other)
619 def __le__(self, other: _BaseVersion) -> bool:
620 if isinstance(other, Version):
621 if self._key_cache is None:
622 self._key_cache = _cmpkey(
623 self._epoch,
624 self._release,
625 self._pre,
626 self._post,
627 self._dev,
628 self._local,
629 )
630 if other._key_cache is None:
631 other._key_cache = _cmpkey(
632 other._epoch,
633 other._release,
634 other._pre,
635 other._post,
636 other._dev,
637 other._local,
638 )
639 return self._key_cache <= other._key_cache
641 if not isinstance(other, _BaseVersion):
642 return NotImplemented
644 return super().__le__(other)
646 def __eq__(self, other: object) -> bool:
647 if isinstance(other, Version):
648 if self._key_cache is None:
649 self._key_cache = _cmpkey(
650 self._epoch,
651 self._release,
652 self._pre,
653 self._post,
654 self._dev,
655 self._local,
656 )
657 if other._key_cache is None:
658 other._key_cache = _cmpkey(
659 other._epoch,
660 other._release,
661 other._pre,
662 other._post,
663 other._dev,
664 other._local,
665 )
666 return self._key_cache == other._key_cache
668 if not isinstance(other, _BaseVersion):
669 return NotImplemented
671 return super().__eq__(other)
673 def __ge__(self, other: _BaseVersion) -> bool:
674 if isinstance(other, Version):
675 if self._key_cache is None:
676 self._key_cache = _cmpkey(
677 self._epoch,
678 self._release,
679 self._pre,
680 self._post,
681 self._dev,
682 self._local,
683 )
684 if other._key_cache is None:
685 other._key_cache = _cmpkey(
686 other._epoch,
687 other._release,
688 other._pre,
689 other._post,
690 other._dev,
691 other._local,
692 )
693 return self._key_cache >= other._key_cache
695 if not isinstance(other, _BaseVersion):
696 return NotImplemented
698 return super().__ge__(other)
700 def __gt__(self, other: _BaseVersion) -> bool:
701 if isinstance(other, Version):
702 if self._key_cache is None:
703 self._key_cache = _cmpkey(
704 self._epoch,
705 self._release,
706 self._pre,
707 self._post,
708 self._dev,
709 self._local,
710 )
711 if other._key_cache is None:
712 other._key_cache = _cmpkey(
713 other._epoch,
714 other._release,
715 other._pre,
716 other._post,
717 other._dev,
718 other._local,
719 )
720 return self._key_cache > other._key_cache
722 if not isinstance(other, _BaseVersion):
723 return NotImplemented
725 return super().__gt__(other)
727 def __ne__(self, other: object) -> bool:
728 if isinstance(other, Version):
729 if self._key_cache is None:
730 self._key_cache = _cmpkey(
731 self._epoch,
732 self._release,
733 self._pre,
734 self._post,
735 self._dev,
736 self._local,
737 )
738 if other._key_cache is None:
739 other._key_cache = _cmpkey(
740 other._epoch,
741 other._release,
742 other._pre,
743 other._post,
744 other._dev,
745 other._local,
746 )
747 return self._key_cache != other._key_cache
749 if not isinstance(other, _BaseVersion):
750 return NotImplemented
752 return super().__ne__(other)
754 def __getstate__(
755 self,
756 ) -> tuple[
757 int,
758 tuple[int, ...],
759 tuple[str, int] | None,
760 tuple[str, int] | None,
761 tuple[str, int] | None,
762 LocalType | None,
763 ]:
764 # Return state as a 6-item tuple for compactness:
765 # (epoch, release, pre, post, dev, local)
766 # Cache members are excluded and will be recomputed on demand
767 return (
768 self._epoch,
769 self._release,
770 self._pre,
771 self._post,
772 self._dev,
773 self._local,
774 )
776 def __setstate__(self, state: object) -> None:
777 # Always discard cached values — they may contain stale references
778 # (e.g. packaging._structures.InfinityType from pre-26.1 pickles)
779 # and will be recomputed on demand from the core fields above.
780 self._key_cache = None
781 self._hash_cache = None
783 if isinstance(state, tuple):
784 if len(state) == 6:
785 # New format (26.2+): (epoch, release, pre, post, dev, local)
786 (
787 self._epoch,
788 self._release,
789 self._pre,
790 self._post,
791 self._dev,
792 self._local,
793 ) = state
794 return
795 if len(state) == 2:
796 # Format (packaging 26.0-26.1): (None, {slot: value}).
797 _, slot_dict = state
798 if isinstance(slot_dict, dict):
799 self._epoch = slot_dict["_epoch"]
800 self._release = slot_dict["_release"]
801 self._pre = slot_dict.get("_pre")
802 self._post = slot_dict.get("_post")
803 self._dev = slot_dict.get("_dev")
804 self._local = slot_dict.get("_local")
805 return
806 if isinstance(state, dict):
807 # Old format (packaging <= 25.x, no __slots__): state is a plain
808 # dict with "_version" (_Version NamedTuple) and "_key" entries.
809 version_nt = state.get("_version")
810 if version_nt is not None:
811 self._epoch = version_nt.epoch
812 self._release = version_nt.release
813 self._pre = version_nt.pre
814 self._post = version_nt.post
815 self._dev = version_nt.dev
816 self._local = version_nt.local
817 return
819 raise TypeError(f"Cannot restore Version from {state!r}")
821 @property
822 @_deprecated("Version._version is private and will be removed soon")
823 def _version(self) -> _Version:
824 return _Version(
825 self._epoch, self._release, self._dev, self._pre, self._post, self._local
826 )
828 @_version.setter
829 @_deprecated("Version._version is private and will be removed soon")
830 def _version(self, value: _Version) -> None:
831 self._epoch = value.epoch
832 self._release = value.release
833 self._dev = value.dev
834 self._pre = value.pre
835 self._post = value.post
836 self._local = value.local
837 self._key_cache = None
838 self._hash_cache = None
840 def __repr__(self) -> str:
841 """A representation of the Version that shows all internal state.
843 >>> Version('1.0.0')
844 <Version('1.0.0')>
845 """
846 return f"<{self.__class__.__name__}({str(self)!r})>"
848 def __str__(self) -> str:
849 """A string representation of the version that can be round-tripped.
851 >>> str(Version("1.0a5"))
852 '1.0a5'
853 """
854 # This is a hot function, so not calling self.base_version
855 version = ".".join(map(str, self.release))
857 # Epoch
858 if self.epoch:
859 version = f"{self.epoch}!{version}"
861 # Pre-release
862 if self.pre is not None:
863 version += "".join(map(str, self.pre))
865 # Post-release
866 if self.post is not None:
867 version += f".post{self.post}"
869 # Development release
870 if self.dev is not None:
871 version += f".dev{self.dev}"
873 # Local version segment
874 if self.local is not None:
875 version += f"+{self.local}"
877 return version
879 @property
880 def _str(self) -> str:
881 """Internal property for match_args"""
882 return str(self)
884 @property
885 def epoch(self) -> int:
886 """The epoch of the version.
888 >>> Version("2.0.0").epoch
889 0
890 >>> Version("1!2.0.0").epoch
891 1
892 """
893 return self._epoch
895 @property
896 def release(self) -> tuple[int, ...]:
897 """The components of the "release" segment of the version.
899 >>> Version("1.2.3").release
900 (1, 2, 3)
901 >>> Version("2.0.0").release
902 (2, 0, 0)
903 >>> Version("1!2.0.0.post0").release
904 (2, 0, 0)
906 Includes trailing zeroes but not the epoch or any pre-release / development /
907 post-release suffixes.
908 """
909 return self._release
911 @property
912 def pre(self) -> tuple[Literal["a", "b", "rc"], int] | None:
913 """The pre-release segment of the version.
915 >>> print(Version("1.2.3").pre)
916 None
917 >>> Version("1.2.3a1").pre
918 ('a', 1)
919 >>> Version("1.2.3b1").pre
920 ('b', 1)
921 >>> Version("1.2.3rc1").pre
922 ('rc', 1)
923 """
924 return self._pre
926 @property
927 def post(self) -> int | None:
928 """The post-release number of the version.
930 >>> print(Version("1.2.3").post)
931 None
932 >>> Version("1.2.3.post1").post
933 1
934 """
935 return self._post[1] if self._post else None
937 @property
938 def dev(self) -> int | None:
939 """The development number of the version.
941 >>> print(Version("1.2.3").dev)
942 None
943 >>> Version("1.2.3.dev1").dev
944 1
945 """
946 return self._dev[1] if self._dev else None
948 @property
949 def local(self) -> str | None:
950 """The local version segment of the version.
952 >>> print(Version("1.2.3").local)
953 None
954 >>> Version("1.2.3+abc").local
955 'abc'
956 """
957 if self._local:
958 return ".".join(str(x) for x in self._local)
959 else:
960 return None
962 @property
963 def public(self) -> str:
964 """The public portion of the version.
966 This returns a string. If you want a :class:`Version` again and care
967 about performance, use ``v.__replace__(local=None)`` instead.
969 >>> Version("1.2.3").public
970 '1.2.3'
971 >>> Version("1.2.3+abc").public
972 '1.2.3'
973 >>> Version("1!1.2.3dev1+abc").public
974 '1!1.2.3.dev1'
975 """
976 return str(self).split("+", 1)[0]
978 @property
979 def base_version(self) -> str:
980 """The "base version" of the version.
982 This returns a string. If you want a :class:`Version` again and care
983 about performance, use
984 ``v.__replace__(pre=None, post=None, dev=None, local=None)`` instead.
986 >>> Version("1.2.3").base_version
987 '1.2.3'
988 >>> Version("1.2.3+abc").base_version
989 '1.2.3'
990 >>> Version("1!1.2.3dev1+abc").base_version
991 '1!1.2.3'
993 The "base version" is the public version of the project without any pre or post
994 release markers.
995 """
996 release_segment = ".".join(map(str, self.release))
997 return f"{self.epoch}!{release_segment}" if self.epoch else release_segment
999 @property
1000 def is_prerelease(self) -> bool:
1001 """Whether this version is a pre-release.
1003 >>> Version("1.2.3").is_prerelease
1004 False
1005 >>> Version("1.2.3a1").is_prerelease
1006 True
1007 >>> Version("1.2.3b1").is_prerelease
1008 True
1009 >>> Version("1.2.3rc1").is_prerelease
1010 True
1011 >>> Version("1.2.3dev1").is_prerelease
1012 True
1013 """
1014 return self.dev is not None or self.pre is not None
1016 @property
1017 def is_postrelease(self) -> bool:
1018 """Whether this version is a post-release.
1020 >>> Version("1.2.3").is_postrelease
1021 False
1022 >>> Version("1.2.3.post1").is_postrelease
1023 True
1024 """
1025 return self.post is not None
1027 @property
1028 def is_devrelease(self) -> bool:
1029 """Whether this version is a development release.
1031 >>> Version("1.2.3").is_devrelease
1032 False
1033 >>> Version("1.2.3.dev1").is_devrelease
1034 True
1035 """
1036 return self.dev is not None
1038 @property
1039 def major(self) -> int:
1040 """The first item of :attr:`release` or ``0`` if unavailable.
1042 >>> Version("1.2.3").major
1043 1
1044 """
1045 return self.release[0] if len(self.release) >= 1 else 0
1047 @property
1048 def minor(self) -> int:
1049 """The second item of :attr:`release` or ``0`` if unavailable.
1051 >>> Version("1.2.3").minor
1052 2
1053 >>> Version("1").minor
1054 0
1055 """
1056 return self.release[1] if len(self.release) >= 2 else 0
1058 @property
1059 def micro(self) -> int:
1060 """The third item of :attr:`release` or ``0`` if unavailable.
1062 >>> Version("1.2.3").micro
1063 3
1064 >>> Version("1").micro
1065 0
1066 """
1067 return self.release[2] if len(self.release) >= 3 else 0
1070class _TrimmedRelease(Version):
1071 __slots__ = ()
1073 def __init__(self, version: str | Version) -> None:
1074 if isinstance(version, Version):
1075 self._epoch = version._epoch
1076 self._release = version._release
1077 self._dev = version._dev
1078 self._pre = version._pre
1079 self._post = version._post
1080 self._local = version._local
1081 self._key_cache = version._key_cache
1082 return
1083 super().__init__(version) # pragma: no cover
1085 @property
1086 def release(self) -> tuple[int, ...]:
1087 """
1088 Release segment without any trailing zeros.
1090 >>> _TrimmedRelease('1.0.0').release
1091 (1,)
1092 >>> _TrimmedRelease('0.0').release
1093 (0,)
1094 """
1095 # This leaves one 0.
1096 rel = super().release
1097 len_release = len(rel)
1098 i = len_release
1099 while i > 1 and rel[i - 1] == 0:
1100 i -= 1
1101 return rel if i == len_release else rel[:i]
1104def _parse_letter_version(
1105 letter: str | None, number: str | bytes | SupportsInt | None
1106) -> tuple[str, int] | None:
1107 if letter:
1108 # We normalize any letters to their lower case form
1109 letter = letter.lower()
1111 # We consider some words to be alternate spellings of other words and
1112 # in those cases we want to normalize the spellings to our preferred
1113 # spelling.
1114 letter = _LETTER_NORMALIZATION.get(letter, letter)
1116 # We consider there to be an implicit 0 in a pre-release if there is
1117 # not a numeral associated with it.
1118 return letter, int(number or 0)
1120 if number:
1121 # We assume if we are given a number, but we are not given a letter
1122 # then this is using the implicit post release syntax (e.g. 1.0-1)
1123 return "post", int(number)
1125 return None
1128_local_version_separators = re.compile(r"[\._-]")
1131def _parse_local_version(local: str | None) -> LocalType | None:
1132 """
1133 Takes a string like ``"abc.1.twelve"`` and turns it into
1134 ``("abc", 1, "twelve")``.
1135 """
1136 if local is not None:
1137 return tuple(
1138 part.lower() if not part.isdigit() else int(part)
1139 for part in _local_version_separators.split(local)
1140 )
1141 return None
1144# Sort ranks for pre-release: dev-only < a < b < rc < stable (no pre-release).
1145_PRE_RANK = {"a": 0, "b": 1, "rc": 2}
1146_PRE_RANK_DEV_ONLY = -1 # sorts before a(0)
1147_PRE_RANK_STABLE = 3 # sorts after rc(2)
1149# In local version segments, strings sort before ints per PEP 440.
1150_LOCAL_STR_RANK = -1 # sorts before all non-negative ints
1152# Pre-computed suffix for stable releases (no pre, post, or dev segments).
1153# See _cmpkey() for the suffix layout.
1154_STABLE_SUFFIX = (_PRE_RANK_STABLE, 0, 0, 0, 1, 0)
1157def _cmpkey(
1158 epoch: int,
1159 release: tuple[int, ...],
1160 pre: tuple[str, int] | None,
1161 post: tuple[str, int] | None,
1162 dev: tuple[str, int] | None,
1163 local: LocalType | None,
1164) -> CmpKey:
1165 """Build a comparison key for PEP 440 ordering.
1167 Returns ``(epoch, release, suffix)`` or
1168 ``(epoch, release, suffix, local)`` so that plain tuple
1169 comparison gives the correct order.
1171 Trailing zeros are stripped from the release so that ``1.0.0 == 1``.
1173 The suffix is a flat 6-int tuple that encodes pre/post/dev:
1174 ``(pre_rank, pre_n, post_rank, post_n, dev_rank, dev_n)``
1176 pre_rank: dev-only=-1, a=0, b=1, rc=2, no-pre=3
1177 Dev-only releases (no pre or post) get -1 so they sort before
1178 any alpha/beta/rc. Releases without a pre-release tag get 3
1179 so they sort after rc.
1180 post_rank: no-post=0, post=1
1181 Releases without a post segment sort before those with one.
1182 dev_rank: dev=0, no-dev=1
1183 Releases without a dev segment sort after those with one.
1185 Local segments use ``(n, "")`` for ints and ``(-1, s)`` for strings,
1186 following PEP 440: strings sort before ints, strings compare
1187 lexicographically, ints compare numerically, and shorter segments
1188 sort before longer when prefixes match. Versions without a local
1189 segment sort before those with one (3-tuple < 4-tuple).
1191 >>> _cmpkey(0, (1, 0, 0), None, None, None, None)
1192 (0, (1,), (3, 0, 0, 0, 1, 0))
1193 >>> _cmpkey(0, (1,), ("a", 1), None, None, None)
1194 (0, (1,), (0, 1, 0, 0, 1, 0))
1195 >>> _cmpkey(0, (1,), None, None, None, ("ubuntu", 1))
1196 (0, (1,), (3, 0, 0, 0, 1, 0), ((-1, 'ubuntu'), (1, '')))
1197 """
1198 # Strip trailing zeros: 1.0.0 compares equal to 1.
1199 len_release = len(release)
1200 i = len_release
1201 while i and release[i - 1] == 0:
1202 i -= 1
1203 trimmed = release if i == len_release else release[:i]
1205 # Fast path: stable release with no local segment.
1206 if pre is None and post is None and dev is None and local is None:
1207 return epoch, trimmed, _STABLE_SUFFIX
1209 if pre is None and post is None and dev is not None:
1210 # dev-only (e.g. 1.0.dev1) sorts before all pre-releases.
1211 pre_rank, pre_n = _PRE_RANK_DEV_ONLY, 0
1212 elif pre is None:
1213 pre_rank, pre_n = _PRE_RANK_STABLE, 0
1214 else:
1215 pre_rank, pre_n = _PRE_RANK[pre[0]], pre[1]
1217 post_rank = 0 if post is None else 1
1218 post_n = 0 if post is None else post[1]
1220 dev_rank = 1 if dev is None else 0
1221 dev_n = 0 if dev is None else dev[1]
1223 suffix = (pre_rank, pre_n, post_rank, post_n, dev_rank, dev_n)
1225 if local is None:
1226 return epoch, trimmed, suffix
1228 cmp_local: CmpLocalType = tuple(
1229 (seg, "") if isinstance(seg, int) else (_LOCAL_STR_RANK, seg) for seg in local
1230 )
1231 return epoch, trimmed, suffix, cmp_local