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

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, normalize_pre, Version, _cmpkey 

8""" 

9 

10from __future__ import annotations 

11 

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) 

25 

26if typing.TYPE_CHECKING: 

27 from typing_extensions import Self, Unpack 

28 

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 

36 

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) 

47 

48 return wrapper 

49 

50 return decorator 

51 

52 

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} 

62 

63__all__ = ["VERSION_PATTERN", "InvalidVersion", "Version", "normalize_pre", "parse"] 

64 

65 

66def __dir__() -> list[str]: 

67 return __all__ 

68 

69 

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

71 

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] 

79 

80 

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 

88 

89 

90def normalize_pre(letter: str, /) -> str: 

91 """Normalize the pre-release segment of a version string. 

92 

93 Returns a lowercase version of the string if not a known pre-release 

94 identifier. 

95 

96 >>> normalize_pre('alpha') 

97 'a' 

98 >>> normalize_pre('BETA') 

99 'b' 

100 >>> normalize_pre('rc') 

101 'rc' 

102 

103 :param letter: 

104 

105 .. versionadded:: 26.1 

106 """ 

107 letter = letter.lower() 

108 return _LETTER_NORMALIZATION.get(letter, letter) 

109 

110 

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

112 """Parse the given version string. 

113 

114 This is identical to the :class:`Version` constructor. 

115 

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

117 <Version('1.0.dev1')> 

118 

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) 

123 

124 

125class InvalidVersion(ValueError): 

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

127 

128 >>> Version("invalid") 

129 Traceback (most recent call last): 

130 ... 

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

132 """ 

133 

134 

135class _BaseVersion: 

136 __slots__ = () 

137 

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: 

142 

143 @property 

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

145 

146 def __hash__(self) -> int: 

147 return hash(self._key) 

148 

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 

155 

156 return self._key < other._key 

157 

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

159 if not isinstance(other, _BaseVersion): 

160 return NotImplemented 

161 

162 return self._key <= other._key 

163 

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

165 if not isinstance(other, _BaseVersion): 

166 return NotImplemented 

167 

168 return self._key == other._key 

169 

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

171 if not isinstance(other, _BaseVersion): 

172 return NotImplemented 

173 

174 return self._key >= other._key 

175 

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

177 if not isinstance(other, _BaseVersion): 

178 return NotImplemented 

179 

180 return self._key > other._key 

181 

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

183 if not isinstance(other, _BaseVersion): 

184 return NotImplemented 

185 

186 return self._key != other._key 

187 

188 

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

190# easier for 3rd party code to reuse 

191 

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""" 

228 

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

230 

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. 

243 

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. 

248 

249.. versionchanged:: 26.0 

250 

251 The regex now uses possessive qualifiers on Python 3.11 if they are 

252 supported (CPython 3.11.5+, PyPy 3.11.13+). 

253 

254:meta hide-value: 

255""" 

256 

257 

258# Validation pattern for local version in replace() 

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

260 

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") 

264 

265 

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) 

272 

273 

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) 

284 

285 

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) 

297 

298 

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) 

306 

307 

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) 

315 

316 

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) 

324 

325 

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 

334 

335 

336class Version(_BaseVersion): 

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

338 

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

340 sorted using the standard Python interfaces. 

341 

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 

358 

359 :class:`Version` is immutable; use :meth:`__replace__` to change 

360 part of a version. 

361 """ 

362 

363 __slots__ = ( 

364 "_dev", 

365 "_epoch", 

366 "_hash_cache", 

367 "_key_cache", 

368 "_local", 

369 "_post", 

370 "_pre", 

371 "_release", 

372 ) 

373 __match_args__ = ("_str",) 

374 """ 

375 Pattern matching is supported on Python 3.10+. 

376 

377 .. versionadded:: 26.0 

378 

379 :meta hide-value: 

380 """ 

381 

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

383 

384 _epoch: int 

385 _release: tuple[int, ...] 

386 _dev: tuple[Literal["dev"], int] | None 

387 _pre: tuple[Literal["a", "b", "rc"], int] | None 

388 _post: tuple[Literal["post"], int] | None 

389 _local: LocalType | None 

390 

391 _hash_cache: int | None 

392 _key_cache: CmpKey | None 

393 

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

395 """Initialize a Version object. 

396 

397 :param version: 

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

399 before use. 

400 :raises InvalidVersion: 

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

402 exception will be raised. 

403 """ 

404 if _SIMPLE_VERSION_INDICATORS.issuperset(version): 

405 try: 

406 self._release = tuple(map(int, version.split("."))) 

407 except ValueError: 

408 raise InvalidVersion(f"Invalid version: {version!r}") from None 

409 

410 self._epoch = 0 

411 self._pre = None 

412 self._post = None 

413 self._dev = None 

414 self._local = None 

415 self._key_cache = None 

416 self._hash_cache = None 

417 return 

418 

419 # Validate the version and parse it into pieces 

420 match = self._regex.fullmatch(version) 

421 if not match: 

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

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

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

425 # We can type ignore the assignments below because the regex guarantees 

426 # the correct strings 

427 self._pre = _parse_letter_version(match.group("pre_l"), match.group("pre_n")) # type: ignore[assignment] 

428 self._post = _parse_letter_version( # type: ignore[assignment] 

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

430 ) 

431 self._dev = _parse_letter_version(match.group("dev_l"), match.group("dev_n")) # type: ignore[assignment] 

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

433 

434 # Key which will be used for sorting 

435 self._key_cache = None 

436 self._hash_cache = None 

437 

438 @classmethod 

439 def from_parts( 

440 cls, 

441 *, 

442 epoch: int = 0, 

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

444 pre: tuple[str, int] | None = None, 

445 post: int | None = None, 

446 dev: int | None = None, 

447 local: str | None = None, 

448 ) -> Self: 

449 """ 

450 Return a new version composed of the various parts. 

451 

452 This allows you to build a version without going though a string and 

453 running a regular expression. It normalizes pre-release strings. The 

454 ``release=`` keyword argument is required. 

455 

456 >>> Version.from_parts(release=(1,2,3)) 

457 <Version('1.2.3')> 

458 >>> Version.from_parts(release=(0,1,0), pre=("b", 1)) 

459 <Version('0.1.0b1')> 

460 

461 :param epoch: 

462 :param release: This version tuple is required 

463 

464 .. versionadded:: 26.1 

465 """ 

466 _epoch = _validate_epoch(epoch) 

467 _release = _validate_release(release) 

468 _pre = _validate_pre(pre) if pre is not None else None 

469 _post = _validate_post(post) if post is not None else None 

470 _dev = _validate_dev(dev) if dev is not None else None 

471 _local = _validate_local(local) if local is not None else None 

472 

473 new_version = cls.__new__(cls) 

474 new_version._key_cache = None 

475 new_version._hash_cache = None 

476 new_version._epoch = _epoch 

477 new_version._release = _release 

478 new_version._pre = _pre 

479 new_version._post = _post 

480 new_version._dev = _dev 

481 new_version._local = _local 

482 

483 return new_version 

484 

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

486 """ 

487 __replace__(*, epoch=..., release=..., pre=..., post=..., dev=..., local=...) 

488 

489 Return a new version with parts replaced. 

490 

491 This returns a new version (unless no parts were changed). The 

492 pre-release is normalized. Setting a value to ``None`` clears it. 

493 

494 >>> v = Version("1.2.3") 

495 >>> v.__replace__(pre=("a", 1)) 

496 <Version('1.2.3a1')> 

497 

498 :param int | None epoch: 

499 :param tuple[int, ...] | None release: 

500 :param tuple[str, int] | None pre: 

501 :param int | None post: 

502 :param int | None dev: 

503 :param str | None local: 

504 

505 .. versionadded:: 26.0 

506 .. versionchanged:: 26.1 

507 

508 The pre-release portion is now normalized. 

509 """ 

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

511 release = ( 

512 _validate_release(kwargs["release"]) 

513 if "release" in kwargs 

514 else self._release 

515 ) 

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

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

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

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

520 

521 if ( 

522 epoch == self._epoch 

523 and release == self._release 

524 and pre == self._pre 

525 and post == self._post 

526 and dev == self._dev 

527 and local == self._local 

528 ): 

529 return self 

530 

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

532 new_version._key_cache = None 

533 new_version._hash_cache = None 

534 new_version._epoch = epoch 

535 new_version._release = release 

536 new_version._pre = pre 

537 new_version._post = post 

538 new_version._dev = dev 

539 new_version._local = local 

540 

541 return new_version 

542 

543 @property 

544 def _key(self) -> CmpKey: 

545 if self._key_cache is None: 

546 self._key_cache = _cmpkey( 

547 self._epoch, 

548 self._release, 

549 self._pre, 

550 self._post, 

551 self._dev, 

552 self._local, 

553 ) 

554 return self._key_cache 

555 

556 # __hash__ must be defined when __eq__ is overridden, 

557 # otherwise Python sets __hash__ to None. 

558 def __hash__(self) -> int: 

559 if (cached_hash := self._hash_cache) is not None: 

560 return cached_hash 

561 

562 if (key := self._key_cache) is None: 

563 self._key_cache = key = _cmpkey( 

564 self._epoch, 

565 self._release, 

566 self._pre, 

567 self._post, 

568 self._dev, 

569 self._local, 

570 ) 

571 self._hash_cache = cached_hash = hash(key) 

572 return cached_hash 

573 

574 # Override comparison methods to use direct _key_cache access 

575 # This is faster than property access, especially before Python 3.12 

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

577 if isinstance(other, Version): 

578 if self._key_cache is None: 

579 self._key_cache = _cmpkey( 

580 self._epoch, 

581 self._release, 

582 self._pre, 

583 self._post, 

584 self._dev, 

585 self._local, 

586 ) 

587 if other._key_cache is None: 

588 other._key_cache = _cmpkey( 

589 other._epoch, 

590 other._release, 

591 other._pre, 

592 other._post, 

593 other._dev, 

594 other._local, 

595 ) 

596 return self._key_cache < other._key_cache 

597 

598 if not isinstance(other, _BaseVersion): 

599 return NotImplemented 

600 

601 return super().__lt__(other) 

602 

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

604 if isinstance(other, Version): 

605 if self._key_cache is None: 

606 self._key_cache = _cmpkey( 

607 self._epoch, 

608 self._release, 

609 self._pre, 

610 self._post, 

611 self._dev, 

612 self._local, 

613 ) 

614 if other._key_cache is None: 

615 other._key_cache = _cmpkey( 

616 other._epoch, 

617 other._release, 

618 other._pre, 

619 other._post, 

620 other._dev, 

621 other._local, 

622 ) 

623 return self._key_cache <= other._key_cache 

624 

625 if not isinstance(other, _BaseVersion): 

626 return NotImplemented 

627 

628 return super().__le__(other) 

629 

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

631 if isinstance(other, Version): 

632 if self._key_cache is None: 

633 self._key_cache = _cmpkey( 

634 self._epoch, 

635 self._release, 

636 self._pre, 

637 self._post, 

638 self._dev, 

639 self._local, 

640 ) 

641 if other._key_cache is None: 

642 other._key_cache = _cmpkey( 

643 other._epoch, 

644 other._release, 

645 other._pre, 

646 other._post, 

647 other._dev, 

648 other._local, 

649 ) 

650 return self._key_cache == other._key_cache 

651 

652 if not isinstance(other, _BaseVersion): 

653 return NotImplemented 

654 

655 return super().__eq__(other) 

656 

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

658 if isinstance(other, Version): 

659 if self._key_cache is None: 

660 self._key_cache = _cmpkey( 

661 self._epoch, 

662 self._release, 

663 self._pre, 

664 self._post, 

665 self._dev, 

666 self._local, 

667 ) 

668 if other._key_cache is None: 

669 other._key_cache = _cmpkey( 

670 other._epoch, 

671 other._release, 

672 other._pre, 

673 other._post, 

674 other._dev, 

675 other._local, 

676 ) 

677 return self._key_cache >= other._key_cache 

678 

679 if not isinstance(other, _BaseVersion): 

680 return NotImplemented 

681 

682 return super().__ge__(other) 

683 

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

685 if isinstance(other, Version): 

686 if self._key_cache is None: 

687 self._key_cache = _cmpkey( 

688 self._epoch, 

689 self._release, 

690 self._pre, 

691 self._post, 

692 self._dev, 

693 self._local, 

694 ) 

695 if other._key_cache is None: 

696 other._key_cache = _cmpkey( 

697 other._epoch, 

698 other._release, 

699 other._pre, 

700 other._post, 

701 other._dev, 

702 other._local, 

703 ) 

704 return self._key_cache > other._key_cache 

705 

706 if not isinstance(other, _BaseVersion): 

707 return NotImplemented 

708 

709 return super().__gt__(other) 

710 

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

712 if isinstance(other, Version): 

713 if self._key_cache is None: 

714 self._key_cache = _cmpkey( 

715 self._epoch, 

716 self._release, 

717 self._pre, 

718 self._post, 

719 self._dev, 

720 self._local, 

721 ) 

722 if other._key_cache is None: 

723 other._key_cache = _cmpkey( 

724 other._epoch, 

725 other._release, 

726 other._pre, 

727 other._post, 

728 other._dev, 

729 other._local, 

730 ) 

731 return self._key_cache != other._key_cache 

732 

733 if not isinstance(other, _BaseVersion): 

734 return NotImplemented 

735 

736 return super().__ne__(other) 

737 

738 @property 

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

740 def _version(self) -> _Version: 

741 return _Version( 

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

743 ) 

744 

745 @_version.setter 

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

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

748 self._epoch = value.epoch 

749 self._release = value.release 

750 self._dev = value.dev 

751 self._pre = value.pre 

752 self._post = value.post 

753 self._local = value.local 

754 self._key_cache = None 

755 self._hash_cache = None 

756 

757 def __repr__(self) -> str: 

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

759 

760 >>> Version('1.0.0') 

761 <Version('1.0.0')> 

762 """ 

763 return f"<{self.__class__.__name__}({str(self)!r})>" 

764 

765 def __str__(self) -> str: 

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

767 

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

769 '1.0a5' 

770 """ 

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

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

773 

774 # Epoch 

775 if self.epoch: 

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

777 

778 # Pre-release 

779 if self.pre is not None: 

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

781 

782 # Post-release 

783 if self.post is not None: 

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

785 

786 # Development release 

787 if self.dev is not None: 

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

789 

790 # Local version segment 

791 if self.local is not None: 

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

793 

794 return version 

795 

796 @property 

797 def _str(self) -> str: 

798 """Internal property for match_args""" 

799 return str(self) 

800 

801 @property 

802 def epoch(self) -> int: 

803 """The epoch of the version. 

804 

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

806 0 

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

808 1 

809 """ 

810 return self._epoch 

811 

812 @property 

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

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

815 

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

817 (1, 2, 3) 

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

819 (2, 0, 0) 

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

821 (2, 0, 0) 

822 

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

824 post-release suffixes. 

825 """ 

826 return self._release 

827 

828 @property 

829 def pre(self) -> tuple[Literal["a", "b", "rc"], int] | None: 

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

831 

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

833 None 

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

835 ('a', 1) 

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

837 ('b', 1) 

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

839 ('rc', 1) 

840 """ 

841 return self._pre 

842 

843 @property 

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

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

846 

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

848 None 

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

850 1 

851 """ 

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

853 

854 @property 

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

856 """The development number of the version. 

857 

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

859 None 

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

861 1 

862 """ 

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

864 

865 @property 

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

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

868 

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

870 None 

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

872 'abc' 

873 """ 

874 if self._local: 

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

876 else: 

877 return None 

878 

879 @property 

880 def public(self) -> str: 

881 """The public portion of the version. 

882 

883 This returns a string. If you want a :class:`Version` again and care 

884 about performance, use ``v.__replace__(local=None)`` instead. 

885 

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

887 '1.2.3' 

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

889 '1.2.3' 

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

891 '1!1.2.3.dev1' 

892 """ 

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

894 

895 @property 

896 def base_version(self) -> str: 

897 """The "base version" of the version. 

898 

899 This returns a string. If you want a :class:`Version` again and care 

900 about performance, use 

901 ``v.__replace__(pre=None, post=None, dev=None, local=None)`` instead. 

902 

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

904 '1.2.3' 

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

906 '1.2.3' 

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

908 '1!1.2.3' 

909