version.py 12 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420
  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. from __future__ import absolute_import, division, print_function
  5. import collections
  6. import itertools
  7. import re
  8. from ._structures import Infinity
  9. __all__ = ["parse", "Version", "LegacyVersion", "InvalidVersion", "VERSION_PATTERN"]
  10. _Version = collections.namedtuple(
  11. "_Version", ["epoch", "release", "dev", "pre", "post", "local"]
  12. )
  13. def parse(version):
  14. """
  15. Parse the given version string and return either a :class:`Version` object
  16. or a :class:`LegacyVersion` object depending on if the given version is
  17. a valid PEP 440 version or a legacy version.
  18. """
  19. try:
  20. return Version(version)
  21. except InvalidVersion:
  22. return LegacyVersion(version)
  23. class InvalidVersion(ValueError):
  24. """
  25. An invalid version was found, users should refer to PEP 440.
  26. """
  27. class _BaseVersion(object):
  28. def __hash__(self):
  29. return hash(self._key)
  30. def __lt__(self, other):
  31. return self._compare(other, lambda s, o: s < o)
  32. def __le__(self, other):
  33. return self._compare(other, lambda s, o: s <= o)
  34. def __eq__(self, other):
  35. return self._compare(other, lambda s, o: s == o)
  36. def __ge__(self, other):
  37. return self._compare(other, lambda s, o: s >= o)
  38. def __gt__(self, other):
  39. return self._compare(other, lambda s, o: s > o)
  40. def __ne__(self, other):
  41. return self._compare(other, lambda s, o: s != o)
  42. def _compare(self, other, method):
  43. if not isinstance(other, _BaseVersion):
  44. return NotImplemented
  45. return method(self._key, other._key)
  46. class LegacyVersion(_BaseVersion):
  47. def __init__(self, version):
  48. self._version = str(version)
  49. self._key = _legacy_cmpkey(self._version)
  50. def __str__(self):
  51. return self._version
  52. def __repr__(self):
  53. return "<LegacyVersion({0})>".format(repr(str(self)))
  54. @property
  55. def public(self):
  56. return self._version
  57. @property
  58. def base_version(self):
  59. return self._version
  60. @property
  61. def epoch(self):
  62. return -1
  63. @property
  64. def release(self):
  65. return None
  66. @property
  67. def pre(self):
  68. return None
  69. @property
  70. def post(self):
  71. return None
  72. @property
  73. def dev(self):
  74. return None
  75. @property
  76. def local(self):
  77. return None
  78. @property
  79. def is_prerelease(self):
  80. return False
  81. @property
  82. def is_postrelease(self):
  83. return False
  84. @property
  85. def is_devrelease(self):
  86. return False
  87. _legacy_version_component_re = re.compile(r"(\d+ | [a-z]+ | \.| -)", re.VERBOSE)
  88. _legacy_version_replacement_map = {
  89. "pre": "c",
  90. "preview": "c",
  91. "-": "final-",
  92. "rc": "c",
  93. "dev": "@",
  94. }
  95. def _parse_version_parts(s):
  96. for part in _legacy_version_component_re.split(s):
  97. part = _legacy_version_replacement_map.get(part, part)
  98. if not part or part == ".":
  99. continue
  100. if part[:1] in "0123456789":
  101. # pad for numeric comparison
  102. yield part.zfill(8)
  103. else:
  104. yield "*" + part
  105. # ensure that alpha/beta/candidate are before final
  106. yield "*final"
  107. def _legacy_cmpkey(version):
  108. # We hardcode an epoch of -1 here. A PEP 440 version can only have a epoch
  109. # greater than or equal to 0. This will effectively put the LegacyVersion,
  110. # which uses the defacto standard originally implemented by setuptools,
  111. # as before all PEP 440 versions.
  112. epoch = -1
  113. # This scheme is taken from pkg_resources.parse_version setuptools prior to
  114. # it's adoption of the packaging library.
  115. parts = []
  116. for part in _parse_version_parts(version.lower()):
  117. if part.startswith("*"):
  118. # remove "-" before a prerelease tag
  119. if part < "*final":
  120. while parts and parts[-1] == "*final-":
  121. parts.pop()
  122. # remove trailing zeros from each series of numeric parts
  123. while parts and parts[-1] == "00000000":
  124. parts.pop()
  125. parts.append(part)
  126. parts = tuple(parts)
  127. return epoch, parts
  128. # Deliberately not anchored to the start and end of the string, to make it
  129. # easier for 3rd party code to reuse
  130. VERSION_PATTERN = r"""
  131. v?
  132. (?:
  133. (?:(?P<epoch>[0-9]+)!)? # epoch
  134. (?P<release>[0-9]+(?:\.[0-9]+)*) # release segment
  135. (?P<pre> # pre-release
  136. [-_\.]?
  137. (?P<pre_l>(a|b|c|rc|alpha|beta|pre|preview))
  138. [-_\.]?
  139. (?P<pre_n>[0-9]+)?
  140. )?
  141. (?P<post> # post release
  142. (?:-(?P<post_n1>[0-9]+))
  143. |
  144. (?:
  145. [-_\.]?
  146. (?P<post_l>post|rev|r)
  147. [-_\.]?
  148. (?P<post_n2>[0-9]+)?
  149. )
  150. )?
  151. (?P<dev> # dev release
  152. [-_\.]?
  153. (?P<dev_l>dev)
  154. [-_\.]?
  155. (?P<dev_n>[0-9]+)?
  156. )?
  157. )
  158. (?:\+(?P<local>[a-z0-9]+(?:[-_\.][a-z0-9]+)*))? # local version
  159. """
  160. class Version(_BaseVersion):
  161. _regex = re.compile(r"^\s*" + VERSION_PATTERN + r"\s*$", re.VERBOSE | re.IGNORECASE)
  162. def __init__(self, version):
  163. # Validate the version and parse it into pieces
  164. match = self._regex.search(version)
  165. if not match:
  166. raise InvalidVersion("Invalid version: '{0}'".format(version))
  167. # Store the parsed out pieces of the version
  168. self._version = _Version(
  169. epoch=int(match.group("epoch")) if match.group("epoch") else 0,
  170. release=tuple(int(i) for i in match.group("release").split(".")),
  171. pre=_parse_letter_version(match.group("pre_l"), match.group("pre_n")),
  172. post=_parse_letter_version(
  173. match.group("post_l"), match.group("post_n1") or match.group("post_n2")
  174. ),
  175. dev=_parse_letter_version(match.group("dev_l"), match.group("dev_n")),
  176. local=_parse_local_version(match.group("local")),
  177. )
  178. # Generate a key which will be used for sorting
  179. self._key = _cmpkey(
  180. self._version.epoch,
  181. self._version.release,
  182. self._version.pre,
  183. self._version.post,
  184. self._version.dev,
  185. self._version.local,
  186. )
  187. def __repr__(self):
  188. return "<Version({0})>".format(repr(str(self)))
  189. def __str__(self):
  190. parts = []
  191. # Epoch
  192. if self.epoch != 0:
  193. parts.append("{0}!".format(self.epoch))
  194. # Release segment
  195. parts.append(".".join(str(x) for x in self.release))
  196. # Pre-release
  197. if self.pre is not None:
  198. parts.append("".join(str(x) for x in self.pre))
  199. # Post-release
  200. if self.post is not None:
  201. parts.append(".post{0}".format(self.post))
  202. # Development release
  203. if self.dev is not None:
  204. parts.append(".dev{0}".format(self.dev))
  205. # Local version segment
  206. if self.local is not None:
  207. parts.append("+{0}".format(self.local))
  208. return "".join(parts)
  209. @property
  210. def epoch(self):
  211. return self._version.epoch
  212. @property
  213. def release(self):
  214. return self._version.release
  215. @property
  216. def pre(self):
  217. return self._version.pre
  218. @property
  219. def post(self):
  220. return self._version.post[1] if self._version.post else None
  221. @property
  222. def dev(self):
  223. return self._version.dev[1] if self._version.dev else None
  224. @property
  225. def local(self):
  226. if self._version.local:
  227. return ".".join(str(x) for x in self._version.local)
  228. else:
  229. return None
  230. @property
  231. def public(self):
  232. return str(self).split("+", 1)[0]
  233. @property
  234. def base_version(self):
  235. parts = []
  236. # Epoch
  237. if self.epoch != 0:
  238. parts.append("{0}!".format(self.epoch))
  239. # Release segment
  240. parts.append(".".join(str(x) for x in self.release))
  241. return "".join(parts)
  242. @property
  243. def is_prerelease(self):
  244. return self.dev is not None or self.pre is not None
  245. @property
  246. def is_postrelease(self):
  247. return self.post is not None
  248. @property
  249. def is_devrelease(self):
  250. return self.dev is not None
  251. def _parse_letter_version(letter, number):
  252. if letter:
  253. # We consider there to be an implicit 0 in a pre-release if there is
  254. # not a numeral associated with it.
  255. if number is None:
  256. number = 0
  257. # We normalize any letters to their lower case form
  258. letter = letter.lower()
  259. # We consider some words to be alternate spellings of other words and
  260. # in those cases we want to normalize the spellings to our preferred
  261. # spelling.
  262. if letter == "alpha":
  263. letter = "a"
  264. elif letter == "beta":
  265. letter = "b"
  266. elif letter in ["c", "pre", "preview"]:
  267. letter = "rc"
  268. elif letter in ["rev", "r"]:
  269. letter = "post"
  270. return letter, int(number)
  271. if not letter and number:
  272. # We assume if we are given a number, but we are not given a letter
  273. # then this is using the implicit post release syntax (e.g. 1.0-1)
  274. letter = "post"
  275. return letter, int(number)
  276. _local_version_separators = re.compile(r"[\._-]")
  277. def _parse_local_version(local):
  278. """
  279. Takes a string like abc.1.twelve and turns it into ("abc", 1, "twelve").
  280. """
  281. if local is not None:
  282. return tuple(
  283. part.lower() if not part.isdigit() else int(part)
  284. for part in _local_version_separators.split(local)
  285. )
  286. def _cmpkey(epoch, release, pre, post, dev, local):
  287. # When we compare a release version, we want to compare it with all of the
  288. # trailing zeros removed. So we'll use a reverse the list, drop all the now
  289. # leading zeros until we come to something non zero, then take the rest
  290. # re-reverse it back into the correct order and make it a tuple and use
  291. # that for our sorting key.
  292. release = tuple(
  293. reversed(list(itertools.dropwhile(lambda x: x == 0, reversed(release))))
  294. )
  295. # We need to "trick" the sorting algorithm to put 1.0.dev0 before 1.0a0.
  296. # We'll do this by abusing the pre segment, but we _only_ want to do this
  297. # if there is not a pre or a post segment. If we have one of those then
  298. # the normal sorting rules will handle this case correctly.
  299. if pre is None and post is None and dev is not None:
  300. pre = -Infinity
  301. # Versions without a pre-release (except as noted above) should sort after
  302. # those with one.
  303. elif pre is None:
  304. pre = Infinity
  305. # Versions without a post segment should sort before those with one.
  306. if post is None:
  307. post = -Infinity
  308. # Versions without a development segment should sort after those with one.
  309. if dev is None:
  310. dev = Infinity
  311. if local is None:
  312. # Versions without a local segment should sort before those with one.
  313. local = -Infinity
  314. else:
  315. # Versions with a local segment need that segment parsed to implement
  316. # the sorting rules in PEP440.
  317. # - Alpha numeric segments sort before numeric segments
  318. # - Alpha numeric segments sort lexicographically
  319. # - Numeric segments sort numerically
  320. # - Shorter versions sort before longer versions when the prefixes
  321. # match exactly
  322. local = tuple((i, "") if isinstance(i, int) else (-Infinity, i) for i in local)
  323. return epoch, release, pre, post, dev, local