Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.11/site-packages/packaging/version.py: 5%

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 packaging.version import parse, Version

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)

26from ._structures import Infinity, InfinityType, NegativeInfinity, NegativeInfinityType

28if typing.TYPE_CHECKING:

29 from typing_extensions import Self, Unpack

31if sys.version_info >= (3, 13): # pragma: no cover

32 from warnings import deprecated as _deprecated

33elif typing.TYPE_CHECKING:

34 from typing_extensions import deprecated as _deprecated

35else: # pragma: no cover

36 import functools

37 import warnings

39 def _deprecated(message: str) -> object:

40 def decorator(func: object) -> object:

41 @functools.wraps(func)

42 def wrapper(*args: object, **kwargs: object) -> object:

43 warnings.warn(

44 message,

45 category=DeprecationWarning,

46 stacklevel=2,

47 )

48 return func(*args, **kwargs)

50 return wrapper

52 return decorator

55_LETTER_NORMALIZATION = {

56 "alpha": "a",

57 "beta": "b",

58 "c": "rc",

59 "pre": "rc",

60 "preview": "rc",

61 "rev": "post",

62 "r": "post",

63}

65__all__ = ["VERSION_PATTERN", "InvalidVersion", "Version", "parse"]

67LocalType = Tuple[Union[int, str], ...]

69CmpPrePostDevType = Union[InfinityType, NegativeInfinityType, Tuple[str, int]]

70CmpLocalType = Union[

71 NegativeInfinityType,

72 Tuple[Union[Tuple[int, str], Tuple[NegativeInfinityType, Union[int, str]]], ...],

73]

74CmpKey = Tuple[

75 int,

76 Tuple[int, ...],

77 CmpPrePostDevType,

78 CmpPrePostDevType,

79 CmpPrePostDevType,

80 CmpLocalType,

81]

82VersionComparisonMethod = Callable[[CmpKey, CmpKey], bool]

85class _VersionReplace(TypedDict, total=False):

86 epoch: int | None

87 release: tuple[int, ...] | None

88 pre: tuple[Literal["a", "b", "rc"], int] | None

89 post: int | None

90 dev: int | None

91 local: str | None

94def parse(version: str) -> Version:

95 """Parse the given version string.

97 >>> parse('1.0.dev1')

98 <Version('1.0.dev1')>

100 :param version: The version string to parse.

101 :raises InvalidVersion: When the version string is not a valid version.

102 """

103 return Version(version)

104

105

106class InvalidVersion(ValueError):

107 """Raised when a version string is not a valid version.

108

109 >>> Version("invalid")

110 Traceback (most recent call last):

111 ...

112 packaging.version.InvalidVersion: Invalid version: 'invalid'

113 """

114

115

116class _BaseVersion:

117 __slots__ = ()

118

119 # This can also be a normal member (see the packaging_legacy package);

120 # we are just requiring it to be readable. Actually defining a property

121 # has runtime effect on subclasses, so it's typing only.

122 if typing.TYPE_CHECKING:

123

124 @property

125 def _key(self) -> tuple[Any, ...]: ...

126

127 def __hash__(self) -> int:

128 return hash(self._key)

129

130 # Please keep the duplicated `isinstance` check

131 # in the six comparisons hereunder

132 # unless you find a way to avoid adding overhead function calls.

133 def __lt__(self, other: _BaseVersion) -> bool:

134 if not isinstance(other, _BaseVersion):

135 return NotImplemented

136

137 return self._key < other._key

138

139 def __le__(self, other: _BaseVersion) -> bool:

140 if not isinstance(other, _BaseVersion):

141 return NotImplemented

142

143 return self._key <= other._key

144

145 def __eq__(self, other: object) -> bool:

146 if not isinstance(other, _BaseVersion):

147 return NotImplemented

148

149 return self._key == other._key

150

151 def __ge__(self, other: _BaseVersion) -> bool:

152 if not isinstance(other, _BaseVersion):

153 return NotImplemented

154

155 return self._key >= other._key

156

157 def __gt__(self, other: _BaseVersion) -> bool:

158 if not isinstance(other, _BaseVersion):

159 return NotImplemented

160

161 return self._key > other._key

162

163 def __ne__(self, other: object) -> bool:

164 if not isinstance(other, _BaseVersion):

165 return NotImplemented

166

167 return self._key != other._key

168

169

170# Deliberately not anchored to the start and end of the string, to make it

171# easier for 3rd party code to reuse

172

173# Note that ++ doesn't behave identically on CPython and PyPy, so not using it here

174_VERSION_PATTERN = r"""

175 v?+ # optional leading v

176 (?:

177 (?:(?P<epoch>[0-9]+)!)?+ # epoch

178 (?P<release>[0-9]+(?:\.[0-9]+)*+) # release segment

179 (?P<pre> # pre-release

180 [._-]?+

181 (?P<pre_l>alpha|a|beta|b|preview|pre|c|rc)

182 [._-]?+

183 (?P<pre_n>[0-9]+)?

184 )?+

185 (?P<post> # post release

186 (?:-(?P<post_n1>[0-9]+))

187 |

188 (?:

189 [._-]?

190 (?P<post_l>post|rev|r)

191 [._-]?

192 (?P<post_n2>[0-9]+)?

193 )

194 )?+

195 (?P<dev> # dev release

196 [._-]?+

197 (?P<dev_l>dev)

198 [._-]?+

199 (?P<dev_n>[0-9]+)?

200 )?+

201 )

202 (?:\+

203 (?P<local> # local version

204 [a-z0-9]+

205 (?:[._-][a-z0-9]+)*+

206 )

207 )?+

208"""

209

210_VERSION_PATTERN_OLD = _VERSION_PATTERN.replace("*+", "*").replace("?+", "?")

211

212# Possessive qualifiers were added in Python 3.11.

213# CPython 3.11.0-3.11.4 had a bug: https://github.com/python/cpython/pull/107795

214# Older PyPy also had a bug.

215VERSION_PATTERN = (

216 _VERSION_PATTERN_OLD

217 if (sys.implementation.name == "cpython" and sys.version_info < (3, 11, 5))

218 or (sys.implementation.name == "pypy" and sys.version_info < (3, 11, 13))

219 or sys.version_info < (3, 11)

220 else _VERSION_PATTERN

221)

222"""

223A string containing the regular expression used to match a valid version.

224

225The pattern is not anchored at either end, and is intended for embedding in larger

226expressions (for example, matching a version number as part of a file name). The

227regular expression should be compiled with the ``re.VERBOSE`` and ``re.IGNORECASE``

228flags set.

229

230:meta hide-value:

231"""

232

233

234# Validation pattern for local version in replace()

235_LOCAL_PATTERN = re.compile(r"[a-z0-9]+(?:[._-][a-z0-9]+)*", re.IGNORECASE)

236

237

238def _validate_epoch(value: object, /) -> int:

239 epoch = value or 0

240 if isinstance(epoch, int) and epoch >= 0:

241 return epoch

242 msg = f"epoch must be non-negative integer, got {epoch}"

243 raise InvalidVersion(msg)

244

245

246def _validate_release(value: object, /) -> tuple[int, ...]:

247 release = (0,) if value is None else value

248 if (

249 isinstance(release, tuple)

250 and len(release) > 0

251 and all(isinstance(i, int) and i >= 0 for i in release)

252 ):

253 return release

254 msg = f"release must be a non-empty tuple of non-negative integers, got {release}"

255 raise InvalidVersion(msg)

256

257

258def _validate_pre(value: object, /) -> tuple[Literal["a", "b", "rc"], int] | None:

259 if value is None:

260 return value

261 if (

262 isinstance(value, tuple)

263 and len(value) == 2

264 and value[0] in ("a", "b", "rc")

265 and isinstance(value[1], int)

266 and value[1] >= 0

267 ):

268 return value

269 msg = f"pre must be a tuple of ('a'|'b'|'rc', non-negative int), got {value}"

270 raise InvalidVersion(msg)

271

272

273def _validate_post(value: object, /) -> tuple[Literal["post"], int] | None:

274 if value is None:

275 return value

276 if isinstance(value, int) and value >= 0:

277 return ("post", value)

278 msg = f"post must be non-negative integer, got {value}"

279 raise InvalidVersion(msg)

280

281

282def _validate_dev(value: object, /) -> tuple[Literal["dev"], int] | None:

283 if value is None:

284 return value

285 if isinstance(value, int) and value >= 0:

286 return ("dev", value)

287 msg = f"dev must be non-negative integer, got {value}"

288 raise InvalidVersion(msg)

289

290

291def _validate_local(value: object, /) -> LocalType | None:

292 if value is None:

293 return value

294 if isinstance(value, str) and _LOCAL_PATTERN.fullmatch(value):

295 return _parse_local_version(value)

296 msg = f"local must be a valid version string, got {value!r}"

297 raise InvalidVersion(msg)

298

299

300# Backward compatibility for internals before 26.0. Do not use.

301class _Version(NamedTuple):

302 epoch: int

303 release: tuple[int, ...]

304 dev: tuple[str, int] | None

305 pre: tuple[str, int] | None

306 post: tuple[str, int] | None

307 local: LocalType | None

308

309

310class Version(_BaseVersion):

311 """This class abstracts handling of a project's versions.

312

313 A :class:`Version` instance is comparison aware and can be compared and

314 sorted using the standard Python interfaces.

315

316 >>> v1 = Version("1.0a5")

317 >>> v2 = Version("1.0")

318 >>> v1

319 <Version('1.0a5')>

320 >>> v2

321 <Version('1.0')>

322 >>> v1 < v2

323 True

324 >>> v1 == v2

325 False

326 >>> v1 > v2

327 False

328 >>> v1 >= v2

329 False

330 >>> v1 <= v2

331 True

332 """

333

334 __slots__ = ("_dev", "_epoch", "_key_cache", "_local", "_post", "_pre", "_release")

335 __match_args__ = ("_str",)

336

337 _regex = re.compile(r"\s*" + VERSION_PATTERN + r"\s*", re.VERBOSE | re.IGNORECASE)

338

339 _epoch: int

340 _release: tuple[int, ...]

341 _dev: tuple[str, int] | None

342 _pre: tuple[str, int] | None

343 _post: tuple[str, int] | None

344 _local: LocalType | None

345

346 _key_cache: CmpKey | None

347

348 def __init__(self, version: str) -> None:

349 """Initialize a Version object.

350

351 :param version:

352 The string representation of a version which will be parsed and normalized

353 before use.

354 :raises InvalidVersion:

355 If the ``version`` does not conform to PEP 440 in any way then this

356 exception will be raised.

357 """

358 # Validate the version and parse it into pieces

359 match = self._regex.fullmatch(version)

360 if not match:

361 raise InvalidVersion(f"Invalid version: {version!r}")

362 self._epoch = int(match.group("epoch")) if match.group("epoch") else 0

363 self._release = tuple(map(int, match.group("release").split(".")))

364 self._pre = _parse_letter_version(match.group("pre_l"), match.group("pre_n"))

365 self._post = _parse_letter_version(

366 match.group("post_l"), match.group("post_n1") or match.group("post_n2")

367 )

368 self._dev = _parse_letter_version(match.group("dev_l"), match.group("dev_n"))

369 self._local = _parse_local_version(match.group("local"))

370

371 # Key which will be used for sorting

372 self._key_cache = None

373

374 def __replace__(self, **kwargs: Unpack[_VersionReplace]) -> Self:

375 epoch = _validate_epoch(kwargs["epoch"]) if "epoch" in kwargs else self._epoch

376 release = (

377 _validate_release(kwargs["release"])

378 if "release" in kwargs

379 else self._release

380 )

381 pre = _validate_pre(kwargs["pre"]) if "pre" in kwargs else self._pre

382 post = _validate_post(kwargs["post"]) if "post" in kwargs else self._post

383 dev = _validate_dev(kwargs["dev"]) if "dev" in kwargs else self._dev

384 local = _validate_local(kwargs["local"]) if "local" in kwargs else self._local

385

386 if (

387 epoch == self._epoch

388 and release == self._release

389 and pre == self._pre

390 and post == self._post

391 and dev == self._dev

392 and local == self._local

393 ):

394 return self

395

396 new_version = self.__class__.__new__(self.__class__)

397 new_version._key_cache = None

398 new_version._epoch = epoch

399 new_version._release = release

400 new_version._pre = pre

401 new_version._post = post

402 new_version._dev = dev

403 new_version._local = local

404

405 return new_version

406

407 @property

408 def _key(self) -> CmpKey:

409 if self._key_cache is None:

410 self._key_cache = _cmpkey(

411 self._epoch,

412 self._release,

413 self._pre,

414 self._post,

415 self._dev,

416 self._local,

417 )

418 return self._key_cache

419

420 @property

421 @_deprecated("Version._version is private and will be removed soon")

422 def _version(self) -> _Version:

423 return _Version(

424 self._epoch, self._release, self._dev, self._pre, self._post, self._local

425 )

426

427 @_version.setter

428 @_deprecated("Version._version is private and will be removed soon")

429 def _version(self, value: _Version) -> None:

430 self._epoch = value.epoch

431 self._release = value.release

432 self._dev = value.dev

433 self._pre = value.pre

434 self._post = value.post

435 self._local = value.local

436 self._key_cache = None

437

438 def __repr__(self) -> str:

439 """A representation of the Version that shows all internal state.

440

441 >>> Version('1.0.0')

442 <Version('1.0.0')>

443 """

444 return f"<Version('{self}')>"

445

446 def __str__(self) -> str:

447 """A string representation of the version that can be round-tripped.

448

449 >>> str(Version("1.0a5"))

450 '1.0a5'

451 """

452 # This is a hot function, so not calling self.base_version

453 version = ".".join(map(str, self.release))

454

455 # Epoch

456 if self.epoch:

457 version = f"{self.epoch}!{version}"

458

459 # Pre-release

460 if self.pre is not None:

461 version += "".join(map(str, self.pre))

462

463 # Post-release

464 if self.post is not None:

465 version += f".post{self.post}"

466

467 # Development release

468 if self.dev is not None:

469 version += f".dev{self.dev}"

470

471 # Local version segment

472 if self.local is not None:

473 version += f"+{self.local}"

474

475 return version

476

477 @property

478 def _str(self) -> str:

479 """Internal property for match_args"""

480 return str(self)

481

482 @property

483 def epoch(self) -> int:

484 """The epoch of the version.

485

486 >>> Version("2.0.0").epoch

487 0

488 >>> Version("1!2.0.0").epoch

489 1

490 """

491 return self._epoch

492

493 @property

494 def release(self) -> tuple[int, ...]:

495 """The components of the "release" segment of the version.

496

497 >>> Version("1.2.3").release

498 (1, 2, 3)

499 >>> Version("2.0.0").release

500 (2, 0, 0)

501 >>> Version("1!2.0.0.post0").release

502 (2, 0, 0)

503

504 Includes trailing zeroes but not the epoch or any pre-release / development /

505 post-release suffixes.

506 """

507 return self._release

508

509 @property

510 def pre(self) -> tuple[str, int] | None:

511 """The pre-release segment of the version.

512

513 >>> print(Version("1.2.3").pre)

514 None

515 >>> Version("1.2.3a1").pre

516 ('a', 1)

517 >>> Version("1.2.3b1").pre

518 ('b', 1)

519 >>> Version("1.2.3rc1").pre

520 ('rc', 1)

521 """

522 return self._pre

523

524 @property

525 def post(self) -> int | None:

526 """The post-release number of the version.

527

528 >>> print(Version("1.2.3").post)

529 None

530 >>> Version("1.2.3.post1").post

531 1

532 """

533 return self._post[1] if self._post else None

534

535 @property

536 def dev(self) -> int | None:

537 """The development number of the version.

538

539 >>> print(Version("1.2.3").dev)

540 None

541 >>> Version("1.2.3.dev1").dev

542 1

543 """

544 return self._dev[1] if self._dev else None

545

546 @property

547 def local(self) -> str | None:

548 """The local version segment of the version.

549

550 >>> print(Version("1.2.3").local)

551 None

552 >>> Version("1.2.3+abc").local

553 'abc'

554 """

555 if self._local:

556 return ".".join(str(x) for x in self._local)

557 else:

558 return None

559

560 @property

561 def public(self) -> str:

562 """The public portion of the version.

563

564 >>> Version("1.2.3").public

565 '1.2.3'

566 >>> Version("1.2.3+abc").public

567 '1.2.3'

568 >>> Version("1!1.2.3dev1+abc").public

569 '1!1.2.3.dev1'

570 """

571 return str(self).split("+", 1)[0]

572

573 @property

574 def base_version(self) -> str:

575 """The "base version" of the version.

576

577 >>> Version("1.2.3").base_version

578 '1.2.3'

579 >>> Version("1.2.3+abc").base_version

580 '1.2.3'

581 >>> Version("1!1.2.3dev1+abc").base_version

582 '1!1.2.3'

583

584 The "base version" is the public version of the project without any pre or post

585 release markers.

586 """

587 release_segment = ".".join(map(str, self.release))

588 return f"{self.epoch}!{release_segment}" if self.epoch else release_segment

589

590 @property

591 def is_prerelease(self) -> bool:

592 """Whether this version is a pre-release.

593

594 >>> Version("1.2.3").is_prerelease

595 False

596 >>> Version("1.2.3a1").is_prerelease

597 True

598 >>> Version("1.2.3b1").is_prerelease

599 True

600 >>> Version("1.2.3rc1").is_prerelease

601 True

602 >>> Version("1.2.3dev1").is_prerelease

603 True

604 """

605 return self.dev is not None or self.pre is not None

606

607 @property

608 def is_postrelease(self) -> bool:

609 """Whether this version is a post-release.

610

611 >>> Version("1.2.3").is_postrelease

612 False

613 >>> Version("1.2.3.post1").is_postrelease

614 True

615 """

616 return self.post is not None

617

618 @property

619 def is_devrelease(self) -> bool:

620 """Whether this version is a development release.

621

622 >>> Version("1.2.3").is_devrelease

623 False

624 >>> Version("1.2.3.dev1").is_devrelease

625 True

626 """

627 return self.dev is not None

628

629 @property

630 def major(self) -> int:

631 """The first item of :attr:`release` or ``0`` if unavailable.

632

633 >>> Version("1.2.3").major

634 1

635 """

636 return self.release[0] if len(self.release) >= 1 else 0

637

638 @property

639 def minor(self) -> int:

640 """The second item of :attr:`release` or ``0`` if unavailable.

641

642 >>> Version("1.2.3").minor

643 2

644 >>> Version("1").minor

645 0

646 """

647 return self.release[1] if len(self.release) >= 2 else 0

648

649 @property

650 def micro(self) -> int:

651 """The third item of :attr:`release` or ``0`` if unavailable.

652

653 >>> Version("1.2.3").micro

654 3

655 >>> Version("1").micro

656 0

657 """

658 return self.release[2] if len(self.release) >= 3 else 0

659

660

661class _TrimmedRelease(Version):

662 __slots__ = ()

663

664 def __init__(self, version: str | Version) -> None:

665 if isinstance(version, Version):

666 self._epoch = version._epoch

667 self._release = version._release

668 self._dev = version._dev

669 self._pre = version._pre

670 self._post = version._post

671 self._local = version._local

672 self._key_cache = version._key_cache

673 return

674 super().__init__(version) # pragma: no cover

675

676 @property

677 def release(self) -> tuple[int, ...]:

678 """

679 Release segment without any trailing zeros.

680

681 >>> _TrimmedRelease('1.0.0').release

682 (1,)

683 >>> _TrimmedRelease('0.0').release

684 (0,)

685 """

686 # This leaves one 0.

687 rel = super().release

688 len_release = len(rel)

689 i = len_release

690 while i > 1 and rel[i - 1] == 0:

691 i -= 1

692 return rel if i == len_release else rel[:i]

693

694

695def _parse_letter_version(

696 letter: str | None, number: str | bytes | SupportsInt | None

697) -> tuple[str, int] | None:

698 if letter:

699 # We normalize any letters to their lower case form

700 letter = letter.lower()

701

702 # We consider some words to be alternate spellings of other words and

703 # in those cases we want to normalize the spellings to our preferred

704 # spelling.

705 letter = _LETTER_NORMALIZATION.get(letter, letter)

706

707 # We consider there to be an implicit 0 in a pre-release if there is

708 # not a numeral associated with it.

709 return letter, int(number or 0)

710

711 if number:

712 # We assume if we are given a number, but we are not given a letter

713 # then this is using the implicit post release syntax (e.g. 1.0-1)

714 return "post", int(number)

715

716 return None

717

718

719_local_version_separators = re.compile(r"[\._-]")

720

721

722def _parse_local_version(local: str | None) -> LocalType | None:

723 """

724 Takes a string like abc.1.twelve and turns it into ("abc", 1, "twelve").

725 """

726 if local is not None:

727 return tuple(

728 part.lower() if not part.isdigit() else int(part)

729 for part in _local_version_separators.split(local)

730 )

731 return None

732

733

734def _cmpkey(

735 epoch: int,

736 release: tuple[int, ...],

737 pre: tuple[str, int] | None,

738 post: tuple[str, int] | None,

739 dev: tuple[str, int] | None,

740 local: LocalType | None,

741) -> CmpKey:

742 # When we compare a release version, we want to compare it with all of the

743 # trailing zeros removed. We will use this for our sorting key.

744 len_release = len(release)

745 i = len_release

746 while i and release[i - 1] == 0:

747 i -= 1

748 _release = release if i == len_release else release[:i]

749

750 # We need to "trick" the sorting algorithm to put 1.0.dev0 before 1.0a0.

751 # We'll do this by abusing the pre segment, but we _only_ want to do this

752 # if there is not a pre or a post segment. If we have one of those then

753 # the normal sorting rules will handle this case correctly.

754 if pre is None and post is None and dev is not None:

755 _pre: CmpPrePostDevType = NegativeInfinity

756 # Versions without a pre-release (except as noted above) should sort after

757 # those with one.

758 elif pre is None:

759 _pre = Infinity

760 else:

761 _pre = pre

762

763 # Versions without a post segment should sort before those with one.

764 if post is None:

765 _post: CmpPrePostDevType = NegativeInfinity

766

767 else:

768 _post = post

769

770 # Versions without a development segment should sort after those with one.

771 if dev is None:

772 _dev: CmpPrePostDevType = Infinity

773

774 else:

775 _dev = dev

776

777 if local is None:

778 # Versions without a local segment should sort before those with one.

779 _local: CmpLocalType = NegativeInfinity

780 else:

781 # Versions with a local segment need that segment parsed to implement

782 # the sorting rules in PEP440.

783 # - Alpha numeric segments sort before numeric segments

784 # - Alpha numeric segments sort lexicographically

785 # - Numeric segments sort numerically

786 # - Shorter versions sort before longer versions when the prefixes

787 # match exactly

788 _local = tuple(

789 (i, "") if isinstance(i, int) else (NegativeInfinity, i) for i in local

790 )

791

792 return epoch, _release, _pre, _post, _dev, _local