Python code coverage for Lib/packaging/version.py

#	count	content
1	n/a	"""Implementation of the versioning scheme defined in PEP 386."""
2	n/a
3	n/a	import re
4	n/a
5	n/a	from packaging.errors import IrrationalVersionError, HugeMajorVersionNumError
6	n/a
7	n/a	__all__ = ['NormalizedVersion', 'suggest_normalized_version',
8	n/a	'VersionPredicate', 'is_valid_version', 'is_valid_versions',
9	n/a	'is_valid_predicate']
10	n/a
11	n/a	# A marker used in the second and third parts of the `parts` tuple, for
12	n/a	# versions that don't have those segments, to sort properly. An example
13	n/a	# of versions in sort order ('highest' last):
14	n/a	# 1.0b1 ((1,0), ('b',1), ('z',))
15	n/a	# 1.0.dev345 ((1,0), ('z',), ('dev', 345))
16	n/a	# 1.0 ((1,0), ('z',), ('z',))
17	n/a	# 1.0.post256.dev345 ((1,0), ('z',), ('z', 'post', 256, 'dev', 345))
18	n/a	# 1.0.post345 ((1,0), ('z',), ('z', 'post', 345, 'z'))
19	n/a	# ^ ^ ^
20	n/a	# 'b' < 'z' ---------------------/ \| \|
21	n/a	# \| \|
22	n/a	# 'dev' < 'z' ----------------------------/ \|
23	n/a	# \|
24	n/a	# 'dev' < 'z' ----------------------------------------------/
25	n/a	# 'f' for 'final' would be kind of nice, but due to bugs in the support of
26	n/a	# 'rc' we must use 'z'
27	n/a	_FINAL_MARKER = ('z',)
28	n/a
29	n/a	_VERSION_RE = re.compile(r'''
30	n/a	^
31	n/a	(?P<version>\d+\.\d+) # minimum 'N.N'
32	n/a	(?P<extraversion>(?:\.\d+)*) # any number of extra '.N' segments
33	n/a	(?:
34	n/a	(?P<prerel>[abc]\|rc) # 'a'=alpha, 'b'=beta, 'c'=release candidate
35	n/a	# 'rc'= alias for release candidate
36	n/a	(?P<prerelversion>\d+(?:\.\d+)*)
37	n/a	)?
38	n/a	(?P<postdev>(\.post(?P<post>\d+))?(\.dev(?P<dev>\d+))?)?
39	n/a	$''', re.VERBOSE)
40	n/a
41	n/a
42	n/a	class NormalizedVersion:
43	n/a	"""A rational version.
44	n/a
45	n/a	Good:
46	n/a	1.2 # equivalent to "1.2.0"
47	n/a	1.2.0
48	n/a	1.2a1
49	n/a	1.2.3a2
50	n/a	1.2.3b1
51	n/a	1.2.3c1
52	n/a	1.2.3.4
53	n/a	TODO: fill this out
54	n/a
55	n/a	Bad:
56	n/a	1 # mininum two numbers
57	n/a	1.2a # release level must have a release serial
58	n/a	1.2.3b
59	n/a	"""
60	n/a	def __init__(self, s, error_on_huge_major_num=True):
61	n/a	"""Create a NormalizedVersion instance from a version string.
62	n/a
63	n/a	@param s {str} The version string.
64	n/a	@param error_on_huge_major_num {bool} Whether to consider an
65	n/a	apparent use of a year or full date as the major version number
66	n/a	an error. Default True. One of the observed patterns on PyPI before
67	n/a	the introduction of `NormalizedVersion` was version numbers like
68	n/a	this:
69	n/a	2009.01.03
70	n/a	20040603
71	n/a	2005.01
72	n/a	This guard is here to strongly encourage the package author to
73	n/a	use an alternate version, because a release deployed into PyPI
74	n/a	and, e.g. downstream Linux package managers, will forever remove
75	n/a	the possibility of using a version number like "1.0" (i.e.
76	n/a	where the major number is less than that huge major number).
77	n/a	"""
78	n/a	self.is_final = True # by default, consider a version as final.
79	n/a	self._parse(s, error_on_huge_major_num)
80	n/a
81	n/a	@classmethod
82	n/a	def from_parts(cls, version, prerelease=_FINAL_MARKER,
83	n/a	devpost=_FINAL_MARKER):
84	n/a	return cls(cls.parts_to_str((version, prerelease, devpost)))
85	n/a
86	n/a	def _parse(self, s, error_on_huge_major_num=True):
87	n/a	"""Parses a string version into parts."""
88	n/a	match = _VERSION_RE.search(s)
89	n/a	if not match:
90	n/a	raise IrrationalVersionError(s)
91	n/a
92	n/a	groups = match.groupdict()
93	n/a	parts = []
94	n/a
95	n/a	# main version
96	n/a	block = self._parse_numdots(groups['version'], s, False, 2)
97	n/a	extraversion = groups.get('extraversion')
98	n/a	if extraversion not in ('', None):
99	n/a	block += self._parse_numdots(extraversion[1:], s)
100	n/a	parts.append(tuple(block))
101	n/a
102	n/a	# prerelease
103	n/a	prerel = groups.get('prerel')
104	n/a	if prerel is not None:
105	n/a	block = [prerel]
106	n/a	block += self._parse_numdots(groups.get('prerelversion'), s,
107	n/a	pad_zeros_length=1)
108	n/a	parts.append(tuple(block))
109	n/a	self.is_final = False
110	n/a	else:
111	n/a	parts.append(_FINAL_MARKER)
112	n/a
113	n/a	# postdev
114	n/a	if groups.get('postdev'):
115	n/a	post = groups.get('post')
116	n/a	dev = groups.get('dev')
117	n/a	postdev = []
118	n/a	if post is not None:
119	n/a	postdev.extend((_FINAL_MARKER[0], 'post', int(post)))
120	n/a	if dev is None:
121	n/a	postdev.append(_FINAL_MARKER[0])
122	n/a	if dev is not None:
123	n/a	postdev.extend(('dev', int(dev)))
124	n/a	self.is_final = False
125	n/a	parts.append(tuple(postdev))
126	n/a	else:
127	n/a	parts.append(_FINAL_MARKER)
128	n/a	self.parts = tuple(parts)
129	n/a	if error_on_huge_major_num and self.parts[0][0] > 1980:
130	n/a	raise HugeMajorVersionNumError("huge major version number, %r, "
131	n/a	"which might cause future problems: %r" % (self.parts[0][0], s))
132	n/a
133	n/a	def _parse_numdots(self, s, full_ver_str, drop_trailing_zeros=True,
134	n/a	pad_zeros_length=0):
135	n/a	"""Parse 'N.N.N' sequences, return a list of ints.
136	n/a
137	n/a	@param s {str} 'N.N.N...' sequence to be parsed
138	n/a	@param full_ver_str {str} The full version string from which this
139	n/a	comes. Used for error strings.
140	n/a	@param drop_trailing_zeros {bool} Whether to drop trailing zeros
141	n/a	from the returned list. Default True.
142	n/a	@param pad_zeros_length {int} The length to which to pad the
143	n/a	returned list with zeros, if necessary. Default 0.
144	n/a	"""
145	n/a	nums = []
146	n/a	for n in s.split("."):
147	n/a	if len(n) > 1 and n[0] == '0':
148	n/a	raise IrrationalVersionError("cannot have leading zero in "
149	n/a	"version number segment: '%s' in %r" % (n, full_ver_str))
150	n/a	nums.append(int(n))
151	n/a	if drop_trailing_zeros:
152	n/a	while nums and nums[-1] == 0:
153	n/a	nums.pop()
154	n/a	while len(nums) < pad_zeros_length:
155	n/a	nums.append(0)
156	n/a	return nums
157	n/a
158	n/a	def __str__(self):
159	n/a	return self.parts_to_str(self.parts)
160	n/a
161	n/a	@classmethod
162	n/a	def parts_to_str(cls, parts):
163	n/a	"""Transforms a version expressed in tuple into its string
164	n/a	representation."""
165	n/a	# XXX This doesn't check for invalid tuples
166	n/a	main, prerel, postdev = parts
167	n/a	s = '.'.join(str(v) for v in main)
168	n/a	if prerel is not _FINAL_MARKER:
169	n/a	s += prerel[0]
170	n/a	s += '.'.join(str(v) for v in prerel[1:])
171	n/a	# XXX clean up: postdev is always true; code is obscure
172	n/a	if postdev and postdev is not _FINAL_MARKER:
173	n/a	if postdev[0] == _FINAL_MARKER[0]:
174	n/a	postdev = postdev[1:]
175	n/a	i = 0
176	n/a	while i < len(postdev):
177	n/a	if i % 2 == 0:
178	n/a	s += '.'
179	n/a	s += str(postdev[i])
180	n/a	i += 1
181	n/a	return s
182	n/a
183	n/a	def __repr__(self):
184	n/a	return "%s('%s')" % (self.__class__.__name__, self)
185	n/a
186	n/a	def _cannot_compare(self, other):
187	n/a	raise TypeError("cannot compare %s and %s"
188	n/a	% (type(self).__name__, type(other).__name__))
189	n/a
190	n/a	def __eq__(self, other):
191	n/a	if not isinstance(other, NormalizedVersion):
192	n/a	self._cannot_compare(other)
193	n/a	return self.parts == other.parts
194	n/a
195	n/a	def __lt__(self, other):
196	n/a	if not isinstance(other, NormalizedVersion):
197	n/a	self._cannot_compare(other)
198	n/a	return self.parts < other.parts
199	n/a
200	n/a	def __ne__(self, other):
201	n/a	return not self.__eq__(other)
202	n/a
203	n/a	def __gt__(self, other):
204	n/a	return not (self.__lt__(other) or self.__eq__(other))
205	n/a
206	n/a	def __le__(self, other):
207	n/a	return self.__eq__(other) or self.__lt__(other)
208	n/a
209	n/a	def __ge__(self, other):
210	n/a	return self.__eq__(other) or self.__gt__(other)
211	n/a
212	n/a	# See http://docs.python.org/reference/datamodel#object.__hash__
213	n/a	def __hash__(self):
214	n/a	return hash(self.parts)
215	n/a
216	n/a
217	n/a	def suggest_normalized_version(s):
218	n/a	"""Suggest a normalized version close to the given version string.
219	n/a
220	n/a	If you have a version string that isn't rational (i.e. NormalizedVersion
221	n/a	doesn't like it) then you might be able to get an equivalent (or close)
222	n/a	rational version from this function.
223	n/a
224	n/a	This does a number of simple normalizations to the given string, based
225	n/a	on observation of versions currently in use on PyPI. Given a dump of
226	n/a	those version during PyCon 2009, 4287 of them:
227	n/a	- 2312 (53.93%) match NormalizedVersion without change
228	n/a	with the automatic suggestion
229	n/a	- 3474 (81.04%) match when using this suggestion method
230	n/a
231	n/a	@param s {str} An irrational version string.
232	n/a	@returns A rational version string, or None, if couldn't determine one.
233	n/a	"""
234	n/a	try:
235	n/a	NormalizedVersion(s)
236	n/a	return s # already rational
237	n/a	except IrrationalVersionError:
238	n/a	pass
239	n/a
240	n/a	rs = s.lower()
241	n/a
242	n/a	# part of this could use maketrans
243	n/a	for orig, repl in (('-alpha', 'a'), ('-beta', 'b'), ('alpha', 'a'),
244	n/a	('beta', 'b'), ('rc', 'c'), ('-final', ''),
245	n/a	('-pre', 'c'),
246	n/a	('-release', ''), ('.release', ''), ('-stable', ''),
247	n/a	('+', '.'), ('_', '.'), (' ', ''), ('.final', ''),
248	n/a	('final', '')):
249	n/a	rs = rs.replace(orig, repl)
250	n/a
251	n/a	# if something ends with dev or pre, we add a 0
252	n/a	rs = re.sub(r"pre$", r"pre0", rs)
253	n/a	rs = re.sub(r"dev$", r"dev0", rs)
254	n/a
255	n/a	# if we have something like "b-2" or "a.2" at the end of the
256	n/a	# version, that is pobably beta, alpha, etc
257	n/a	# let's remove the dash or dot
258	n/a	rs = re.sub(r"([abc]\|rc)[\-\.](\d+)$", r"\1\2", rs)
259	n/a
260	n/a	# 1.0-dev-r371 -> 1.0.dev371
261	n/a	# 0.1-dev-r79 -> 0.1.dev79
262	n/a	rs = re.sub(r"[\-\.](dev)[\-\.]?r?(\d+)$", r".\1\2", rs)
263	n/a
264	n/a	# Clean: 2.0.a.3, 2.0.b1, 0.9.0~c1
265	n/a	rs = re.sub(r"[.~]?([abc])\.?", r"\1", rs)
266	n/a
267	n/a	# Clean: v0.3, v1.0
268	n/a	if rs.startswith('v'):
269	n/a	rs = rs[1:]
270	n/a
271	n/a	# Clean leading '0's on numbers.
272	n/a	#TODO: unintended side-effect on, e.g., "2003.05.09"
273	n/a	# PyPI stats: 77 (~2%) better
274	n/a	rs = re.sub(r"\b0+(\d+)(?!\d)", r"\1", rs)
275	n/a
276	n/a	# Clean a/b/c with no version. E.g. "1.0a" -> "1.0a0". Setuptools infers
277	n/a	# zero.
278	n/a	# PyPI stats: 245 (7.56%) better
279	n/a	rs = re.sub(r"(\d+[abc])$", r"\g<1>0", rs)
280	n/a
281	n/a	# the 'dev-rNNN' tag is a dev tag
282	n/a	rs = re.sub(r"\.?(dev-r\|dev\.r)\.?(\d+)$", r".dev\2", rs)
283	n/a
284	n/a	# clean the - when used as a pre delimiter
285	n/a	rs = re.sub(r"-(a\|b\|c)(\d+)$", r"\1\2", rs)
286	n/a
287	n/a	# a terminal "dev" or "devel" can be changed into ".dev0"
288	n/a	rs = re.sub(r"[\.\-](dev\|devel)$", r".dev0", rs)
289	n/a
290	n/a	# a terminal "dev" can be changed into ".dev0"
291	n/a	rs = re.sub(r"(?![\.\-])dev$", r".dev0", rs)
292	n/a
293	n/a	# a terminal "final" or "stable" can be removed
294	n/a	rs = re.sub(r"(final\|stable)$", "", rs)
295	n/a
296	n/a	# The 'r' and the '-' tags are post release tags
297	n/a	# 0.4a1.r10 -> 0.4a1.post10
298	n/a	# 0.9.33-17222 -> 0.9.33.post17222
299	n/a	# 0.9.33-r17222 -> 0.9.33.post17222
300	n/a	rs = re.sub(r"\.?(r\|-\|-r)\.?(\d+)$", r".post\2", rs)
301	n/a
302	n/a	# Clean 'r' instead of 'dev' usage:
303	n/a	# 0.9.33+r17222 -> 0.9.33.dev17222
304	n/a	# 1.0dev123 -> 1.0.dev123
305	n/a	# 1.0.git123 -> 1.0.dev123
306	n/a	# 1.0.bzr123 -> 1.0.dev123
307	n/a	# 0.1a0dev.123 -> 0.1a0.dev123
308	n/a	# PyPI stats: ~150 (~4%) better
309	n/a	rs = re.sub(r"\.?(dev\|git\|bzr)\.?(\d+)$", r".dev\2", rs)
310	n/a
311	n/a	# Clean '.pre' (normalized from '-pre' above) instead of 'c' usage:
312	n/a	# 0.2.pre1 -> 0.2c1
313	n/a	# 0.2-c1 -> 0.2c1
314	n/a	# 1.0preview123 -> 1.0c123
315	n/a	# PyPI stats: ~21 (0.62%) better
316	n/a	rs = re.sub(r"\.?(pre\|preview\|-c)(\d+)$", r"c\g<2>", rs)
317	n/a
318	n/a	# Tcl/Tk uses "px" for their post release markers
319	n/a	rs = re.sub(r"p(\d+)$", r".post\1", rs)
320	n/a
321	n/a	try:
322	n/a	NormalizedVersion(rs)
323	n/a	return rs # already rational
324	n/a	except IrrationalVersionError:
325	n/a	pass
326	n/a	return None
327	n/a
328	n/a
329	n/a	# A predicate is: "ProjectName (VERSION1, VERSION2, ..)
330	n/a	_PREDICATE = re.compile(r"(?i)^\s(\w[\s\w-](?:\.\w))(.*)")
331	n/a	_VERSIONS = re.compile(r"^\s$(?P<versions>.)$\s$\|^\s"
332	n/a	"(?P<versions2>.)\s$")
333	n/a	_PLAIN_VERSIONS = re.compile(r"^\s(.)\s*$")
334	n/a	_SPLIT_CMP = re.compile(r"^\s(<=\|>=\|<\|>\|!=\|==)\s([^\s,]+)\s*$")
335	n/a
336	n/a
337	n/a	def _split_predicate(predicate):
338	n/a	match = _SPLIT_CMP.match(predicate)
339	n/a	if match is None:
340	n/a	# probably no op, we'll use "=="
341	n/a	comp, version = '==', predicate
342	n/a	else:
343	n/a	comp, version = match.groups()
344	n/a	return comp, NormalizedVersion(version)
345	n/a
346	n/a
347	n/a	class VersionPredicate:
348	n/a	"""Defines a predicate: ProjectName (>ver1,ver2, ..)"""
349	n/a
350	n/a	_operators = {"<": lambda x, y: x < y,
351	n/a	">": lambda x, y: x > y,
352	n/a	"<=": lambda x, y: str(x).startswith(str(y)) or x < y,
353	n/a	">=": lambda x, y: str(x).startswith(str(y)) or x > y,
354	n/a	"==": lambda x, y: str(x).startswith(str(y)),
355	n/a	"!=": lambda x, y: not str(x).startswith(str(y)),
356	n/a	}
357	n/a
358	n/a	def __init__(self, predicate):
359	n/a	self._string = predicate
360	n/a	predicate = predicate.strip()
361	n/a	match = _PREDICATE.match(predicate)
362	n/a	if match is None:
363	n/a	raise ValueError('Bad predicate "%s"' % predicate)
364	n/a
365	n/a	name, predicates = match.groups()
366	n/a	self.name = name.strip()
367	n/a	self.predicates = []
368	n/a	if predicates is None:
369	n/a	return
370	n/a
371	n/a	predicates = _VERSIONS.match(predicates.strip())
372	n/a	if predicates is None:
373	n/a	return
374	n/a
375	n/a	predicates = predicates.groupdict()
376	n/a	if predicates['versions'] is not None:
377	n/a	versions = predicates['versions']
378	n/a	else:
379	n/a	versions = predicates.get('versions2')
380	n/a
381	n/a	if versions is not None:
382	n/a	for version in versions.split(','):
383	n/a	if version.strip() == '':
384	n/a	continue
385	n/a	self.predicates.append(_split_predicate(version))
386	n/a
387	n/a	def match(self, version):
388	n/a	"""Check if the provided version matches the predicates."""
389	n/a	if isinstance(version, str):
390	n/a	version = NormalizedVersion(version)
391	n/a	for operator, predicate in self.predicates:
392	n/a	if not self._operators[operator](version, predicate):
393	n/a	return False
394	n/a	return True
395	n/a
396	n/a	def __repr__(self):
397	n/a	return self._string
398	n/a
399	n/a
400	n/a	class _Versions(VersionPredicate):
401	n/a	def __init__(self, predicate):
402	n/a	predicate = predicate.strip()
403	n/a	match = _PLAIN_VERSIONS.match(predicate)
404	n/a	self.name = None
405	n/a	predicates = match.groups()[0]
406	n/a	self.predicates = [_split_predicate(pred.strip())
407	n/a	for pred in predicates.split(',')]
408	n/a
409	n/a
410	n/a	class _Version(VersionPredicate):
411	n/a	def __init__(self, predicate):
412	n/a	predicate = predicate.strip()
413	n/a	match = _PLAIN_VERSIONS.match(predicate)
414	n/a	self.name = None
415	n/a	self.predicates = _split_predicate(match.groups()[0])
416	n/a
417	n/a
418	n/a	def is_valid_predicate(predicate):
419	n/a	try:
420	n/a	VersionPredicate(predicate)
421	n/a	except (ValueError, IrrationalVersionError):
422	n/a	return False
423	n/a	else:
424	n/a	return True
425	n/a
426	n/a
427	n/a	def is_valid_versions(predicate):
428	n/a	try:
429	n/a	_Versions(predicate)
430	n/a	except (ValueError, IrrationalVersionError):
431	n/a	return False
432	n/a	else:
433	n/a	return True
434	n/a
435	n/a
436	n/a	def is_valid_version(predicate):
437	n/a	try:
438	n/a	_Version(predicate)
439	n/a	except (ValueError, IrrationalVersionError):
440	n/a	return False
441	n/a	else:
442	n/a	return True
443	n/a
444	n/a
445	n/a	def get_version_predicate(requirements):
446	n/a	"""Return a VersionPredicate object, from a string or an already
447	n/a	existing object.
448	n/a	"""
449	n/a	if isinstance(requirements, str):
450	n/a	requirements = VersionPredicate(requirements)
451	n/a	return requirements