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