Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.11/site-packages/setuptools/_vendor/wheel/vendored/packaging/version.py: 7%

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

166 statements  

1# This file is dual licensed under the terms of the Apache License, Version 

2# 2.0, and the BSD License. See the LICENSE file in the root of this repository 

3# for complete details. 

4""" 

5.. testsetup:: 

6 

7 from packaging.version import parse, Version 

8""" 

9 

10import itertools 

11import re 

12from typing import Any, Callable, NamedTuple, Optional, SupportsInt, Tuple, Union 

13 

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

15 

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

17 

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

19 

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

21CmpLocalType = Union[ 

22 NegativeInfinityType, 

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

24] 

25CmpKey = Tuple[ 

26 int, 

27 Tuple[int, ...], 

28 CmpPrePostDevType, 

29 CmpPrePostDevType, 

30 CmpPrePostDevType, 

31 CmpLocalType, 

32] 

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

34 

35 

36class _Version(NamedTuple): 

37 epoch: int 

38 release: Tuple[int, ...] 

39 dev: Optional[Tuple[str, int]] 

40 pre: Optional[Tuple[str, int]] 

41 post: Optional[Tuple[str, int]] 

42 local: Optional[LocalType] 

43 

44 

45def parse(version: str) -> "Version": 

46 """Parse the given version string. 

47 

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

49 <Version('1.0.dev1')> 

50 

51 :param version: The version string to parse. 

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

53 """ 

54 return Version(version) 

55 

56 

57class InvalidVersion(ValueError): 

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

59 

60 >>> Version("invalid") 

61 Traceback (most recent call last): 

62 ... 

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

64 """ 

65 

66 

67class _BaseVersion: 

68 _key: Tuple[Any, ...] 

69 

70 def __hash__(self) -> int: 

71 return hash(self._key) 

72 

73 # Please keep the duplicated `isinstance` check 

74 # in the six comparisons hereunder 

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

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

77 if not isinstance(other, _BaseVersion): 

78 return NotImplemented 

79 

80 return self._key < other._key 

81 

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

83 if not isinstance(other, _BaseVersion): 

84 return NotImplemented 

85 

86 return self._key <= other._key 

87 

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

89 if not isinstance(other, _BaseVersion): 

90 return NotImplemented 

91 

92 return self._key == other._key 

93 

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

95 if not isinstance(other, _BaseVersion): 

96 return NotImplemented 

97 

98 return self._key >= other._key 

99 

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

101 if not isinstance(other, _BaseVersion): 

102 return NotImplemented 

103 

104 return self._key > other._key 

105 

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

107 if not isinstance(other, _BaseVersion): 

108 return NotImplemented 

109 

110 return self._key != other._key 

111 

112 

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

114# easier for 3rd party code to reuse 

115_VERSION_PATTERN = r""" 

116 v? 

117 (?: 

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

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

120 (?P<pre> # pre-release 

121 [-_\.]? 

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

123 [-_\.]? 

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

125 )? 

126 (?P<post> # post release 

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

128 | 

129 (?: 

130 [-_\.]? 

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

132 [-_\.]? 

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

134 ) 

135 )? 

136 (?P<dev> # dev release 

137 [-_\.]? 

138 (?P<dev_l>dev) 

139 [-_\.]? 

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

141 )? 

142 ) 

143 (?:\+(?P<local>[a-z0-9]+(?:[-_\.][a-z0-9]+)*))? # local version 

144""" 

145 

146VERSION_PATTERN = _VERSION_PATTERN 

147""" 

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

149 

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

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

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

153flags set. 

154 

155:meta hide-value: 

156""" 

157 

158 

159class Version(_BaseVersion): 

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

161 

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

163 sorted using the standard Python interfaces. 

164 

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

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

167 >>> v1 

168 <Version('1.0a5')> 

169 >>> v2 

170 <Version('1.0')> 

171 >>> v1 < v2 

172 True 

173 >>> v1 == v2 

174 False 

175 >>> v1 > v2 

176 False 

177 >>> v1 >= v2 

178 False 

179 >>> v1 <= v2 

180 True 

181 """ 

182 

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

184 _key: CmpKey 

185 

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

187 """Initialize a Version object. 

188 

189 :param version: 

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

191 before use. 

192 :raises InvalidVersion: 

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

194 exception will be raised. 

195 """ 

196 

197 # Validate the version and parse it into pieces 

198 match = self._regex.search(version) 

199 if not match: 

200 raise InvalidVersion(f"Invalid version: '{version}'") 

201 

202 # Store the parsed out pieces of the version 

203 self._version = _Version( 

204 epoch=int(match.group("epoch")) if match.group("epoch") else 0, 

205 release=tuple(int(i) for i in match.group("release").split(".")), 

206 pre=_parse_letter_version(match.group("pre_l"), match.group("pre_n")), 

207 post=_parse_letter_version( 

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

209 ), 

210 dev=_parse_letter_version(match.group("dev_l"), match.group("dev_n")), 

211 local=_parse_local_version(match.group("local")), 

212 ) 

213 

214 # Generate a key which will be used for sorting 

215 self._key = _cmpkey( 

216 self._version.epoch, 

217 self._version.release, 

218 self._version.pre, 

219 self._version.post, 

220 self._version.dev, 

221 self._version.local, 

222 ) 

223 

224 def __repr__(self) -> str: 

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

226 

227 >>> Version('1.0.0') 

228 <Version('1.0.0')> 

229 """ 

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

231 

232 def __str__(self) -> str: 

233 """A string representation of the version that can be rounded-tripped. 

234 

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

236 '1.0a5' 

237 """ 

238 parts = [] 

239 

240 # Epoch 

241 if self.epoch != 0: 

242 parts.append(f"{self.epoch}!") 

243 

244 # Release segment 

245 parts.append(".".join(str(x) for x in self.release)) 

246 

247 # Pre-release 

248 if self.pre is not None: 

249 parts.append("".join(str(x) for x in self.pre)) 

250 

251 # Post-release 

252 if self.post is not None: 

253 parts.append(f".post{self.post}") 

254 

255 # Development release 

256 if self.dev is not None: 

257 parts.append(f".dev{self.dev}") 

258 

259 # Local version segment 

260 if self.local is not None: 

261 parts.append(f"+{self.local}") 

262 

263 return "".join(parts) 

264 

265 @property 

266 def epoch(self) -> int: 

267 """The epoch of the version. 

268 

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

270 0 

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

272 1 

273 """ 

274 return self._version.epoch 

275 

276 @property 

277 def release(self) -> Tuple[int, ...]: 

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

279 

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

281 (1, 2, 3) 

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

283 (2, 0, 0) 

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

285 (2, 0, 0) 

286 

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

288 post-release suffixes. 

289 """ 

290 return self._version.release 

291 

292 @property 

293 def pre(self) -> Optional[Tuple[str, int]]: 

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

295 

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

297 None 

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

299 ('a', 1) 

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

301 ('b', 1) 

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

303 ('rc', 1) 

304 """ 

305 return self._version.pre 

306 

307 @property 

308 def post(self) -> Optional[int]: 

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

310 

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

312 None 

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

314 1 

315 """ 

316 return self._version.post[1] if self._version.post else None 

317 

318 @property 

319 def dev(self) -> Optional[int]: 

320 """The development number of the version. 

321 

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

323 None 

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

325 1 

326 """ 

327 return self._version.dev[1] if self._version.dev else None 

328 

329 @property 

330 def local(self) -> Optional[str]: 

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

332 

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

334 None 

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

336 'abc' 

337 """ 

338 if self._version.local: 

339 return ".".join(str(x) for x in self._version.local) 

340 else: 

341 return None 

342 

343 @property 

344 def public(self) -> str: 

345 """The public portion of the version. 

346 

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

348 '1.2.3' 

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

350 '1.2.3' 

351 >>> Version("1.2.3+abc.dev1").public 

352 '1.2.3' 

353 """ 

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

355 

356 @property 

357 def base_version(self) -> str: 

358 """The "base version" of the version. 

359 

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

361 '1.2.3' 

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

363 '1.2.3' 

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

365 '1!1.2.3' 

366 

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

368 release markers. 

369 """ 

370 parts = [] 

371 

372 # Epoch 

373 if self.epoch != 0: 

374 parts.append(f"{self.epoch}!") 

375 

376 # Release segment 

377 parts.append(".".join(str(x) for x in self.release)) 

378 

379 return "".join(parts) 

380 

381 @property 

382 def is_prerelease(self) -> bool: 

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

384 

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

386 False 

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

388 True 

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

390 True 

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

392 True 

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

394 True 

395 """ 

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

397 

398 @property 

399 def is_postrelease(self) -> bool: 

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

401 

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

403 False 

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

405 True 

406 """ 

407 return self.post is not None 

408 

409 @property 

410 def is_devrelease(self) -> bool: 

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

412 

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

414 False 

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

416 True 

417 """ 

418 return self.dev is not None 

419 

420 @property 

421 def major(self) -> int: 

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

423 

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

425 1 

426 """ 

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

428 

429 @property 

430 def minor(self) -> int: 

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

432 

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

434 2 

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

436 0 

437 """ 

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

439 

440 @property 

441 def micro(self) -> int: 

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

443 

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

445 3 

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

447 0 

448 """ 

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

450 

451 

452def _parse_letter_version( 

453 letter: Optional[str], number: Union[str, bytes, SupportsInt, None] 

454) -> Optional[Tuple[str, int]]: 

455 if letter: 

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

457 # not a numeral associated with it. 

458 if number is None: 

459 number = 0 

460 

461 # We normalize any letters to their lower case form 

462 letter = letter.lower() 

463 

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

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

466 # spelling. 

467 if letter == "alpha": 

468 letter = "a" 

469 elif letter == "beta": 

470 letter = "b" 

471 elif letter in ["c", "pre", "preview"]: 

472 letter = "rc" 

473 elif letter in ["rev", "r"]: 

474 letter = "post" 

475 

476 return letter, int(number) 

477 if not letter and number: 

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

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

480 letter = "post" 

481 

482 return letter, int(number) 

483 

484 return None 

485 

486 

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

488 

489 

490def _parse_local_version(local: Optional[str]) -> Optional[LocalType]: 

491 """ 

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

493 """ 

494 if local is not None: 

495 return tuple( 

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

497 for part in _local_version_separators.split(local) 

498 ) 

499 return None 

500 

501 

502def _cmpkey( 

503 epoch: int, 

504 release: Tuple[int, ...], 

505 pre: Optional[Tuple[str, int]], 

506 post: Optional[Tuple[str, int]], 

507 dev: Optional[Tuple[str, int]], 

508 local: Optional[LocalType], 

509) -> CmpKey: 

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

511 # trailing zeros removed. So we'll use a reverse the list, drop all the now 

512 # leading zeros until we come to something non zero, then take the rest 

513 # re-reverse it back into the correct order and make it a tuple and use 

514 # that for our sorting key. 

515 _release = tuple( 

516 reversed(list(itertools.dropwhile(lambda x: x == 0, reversed(release)))) 

517 ) 

518 

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

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

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

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

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

524 _pre: CmpPrePostDevType = NegativeInfinity 

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

526 # those with one. 

527 elif pre is None: 

528 _pre = Infinity 

529 else: 

530 _pre = pre 

531 

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

533 if post is None: 

534 _post: CmpPrePostDevType = NegativeInfinity 

535 

536 else: 

537 _post = post 

538 

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

540 if dev is None: 

541 _dev: CmpPrePostDevType = Infinity 

542 

543 else: 

544 _dev = dev 

545 

546 if local is None: 

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

548 _local: CmpLocalType = NegativeInfinity 

549 else: 

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

551 # the sorting rules in PEP440. 

552 # - Alpha numeric segments sort before numeric segments 

553 # - Alpha numeric segments sort lexicographically 

554 # - Numeric segments sort numerically 

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

556 # match exactly 

557 _local = tuple( 

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

559 ) 

560 

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