Python code coverage for Lib/distutils/version.py

#	count	content
1	n/a	#
2	n/a	# distutils/version.py
3	n/a	#
4	n/a	# Implements multiple version numbering conventions for the
5	n/a	# Python Module Distribution Utilities.
6	n/a	#
7	n/a	# $Id$
8	n/a	#
9	n/a
10	n/a	"""Provides classes to represent module version numbers (one class for
11	n/a	each style of version numbering). There are currently two such classes
12	n/a	implemented: StrictVersion and LooseVersion.
13	n/a
14	n/a	Every version number class implements the following interface:
15	n/a	* the 'parse' method takes a string and parses it to some internal
16	n/a	representation; if the string is an invalid version number,
17	n/a	'parse' raises a ValueError exception
18	n/a	* the class constructor takes an optional string argument which,
19	n/a	if supplied, is passed to 'parse'
20	n/a	* __str__ reconstructs the string that was passed to 'parse' (or
21	n/a	an equivalent string -- ie. one that will generate an equivalent
22	n/a	version number instance)
23	n/a	* __repr__ generates Python code to recreate the version number instance
24	n/a	* _cmp compares the current instance with either another instance
25	n/a	of the same class or a string (which will be parsed to an instance
26	n/a	of the same class, thus must follow the same rules)
27	n/a	"""
28	n/a
29	n/a	import re
30	n/a
31	n/a	class Version:
32	n/a	"""Abstract base class for version numbering classes. Just provides
33	n/a	constructor (__init__) and reproducer (__repr__), because those
34	n/a	seem to be the same for all version numbering classes; and route
35	n/a	rich comparisons to _cmp.
36	n/a	"""
37	n/a
38	n/a	def __init__ (self, vstring=None):
39	n/a	if vstring:
40	n/a	self.parse(vstring)
41	n/a
42	n/a	def __repr__ (self):
43	n/a	return "%s ('%s')" % (self.__class__.__name__, str(self))
44	n/a
45	n/a	def __eq__(self, other):
46	n/a	c = self._cmp(other)
47	n/a	if c is NotImplemented:
48	n/a	return c
49	n/a	return c == 0
50	n/a
51	n/a	def __lt__(self, other):
52	n/a	c = self._cmp(other)
53	n/a	if c is NotImplemented:
54	n/a	return c
55	n/a	return c < 0
56	n/a
57	n/a	def __le__(self, other):
58	n/a	c = self._cmp(other)
59	n/a	if c is NotImplemented:
60	n/a	return c
61	n/a	return c <= 0
62	n/a
63	n/a	def __gt__(self, other):
64	n/a	c = self._cmp(other)
65	n/a	if c is NotImplemented:
66	n/a	return c
67	n/a	return c > 0
68	n/a
69	n/a	def __ge__(self, other):
70	n/a	c = self._cmp(other)
71	n/a	if c is NotImplemented:
72	n/a	return c
73	n/a	return c >= 0
74	n/a
75	n/a
76	n/a	# Interface for version-number classes -- must be implemented
77	n/a	# by the following classes (the concrete ones -- Version should
78	n/a	# be treated as an abstract class).
79	n/a	# __init__ (string) - create and take same action as 'parse'
80	n/a	# (string parameter is optional)
81	n/a	# parse (string) - convert a string representation to whatever
82	n/a	# internal representation is appropriate for
83	n/a	# this style of version numbering
84	n/a	# __str__ (self) - convert back to a string; should be very similar
85	n/a	# (if not identical to) the string supplied to parse
86	n/a	# __repr__ (self) - generate Python code to recreate
87	n/a	# the instance
88	n/a	# _cmp (self, other) - compare two version numbers ('other' may
89	n/a	# be an unparsed version string, or another
90	n/a	# instance of your version class)
91	n/a
92	n/a
93	n/a	class StrictVersion (Version):
94	n/a
95	n/a	"""Version numbering for anal retentives and software idealists.
96	n/a	Implements the standard interface for version number classes as
97	n/a	described above. A version number consists of two or three
98	n/a	dot-separated numeric components, with an optional "pre-release" tag
99	n/a	on the end. The pre-release tag consists of the letter 'a' or 'b'
100	n/a	followed by a number. If the numeric components of two version
101	n/a	numbers are equal, then one with a pre-release tag will always
102	n/a	be deemed earlier (lesser) than one without.
103	n/a
104	n/a	The following are valid version numbers (shown in the order that
105	n/a	would be obtained by sorting according to the supplied cmp function):
106	n/a
107	n/a	0.4 0.4.0 (these two are equivalent)
108	n/a	0.4.1
109	n/a	0.5a1
110	n/a	0.5b3
111	n/a	0.5
112	n/a	0.9.6
113	n/a	1.0
114	n/a	1.0.4a3
115	n/a	1.0.4b1
116	n/a	1.0.4
117	n/a
118	n/a	The following are examples of invalid version numbers:
119	n/a
120	n/a	1
121	n/a	2.7.2.2
122	n/a	1.3.a4
123	n/a	1.3pl1
124	n/a	1.3c4
125	n/a
126	n/a	The rationale for this version numbering system will be explained
127	n/a	in the distutils documentation.
128	n/a	"""
129	n/a
130	n/a	version_re = re.compile(r'^(\d+) \. (\d+) (\. (\d+))? ([ab](\d+))?$',
131	n/a	re.VERBOSE \| re.ASCII)
132	n/a
133	n/a
134	n/a	def parse (self, vstring):
135	n/a	match = self.version_re.match(vstring)
136	n/a	if not match:
137	n/a	raise ValueError("invalid version number '%s'" % vstring)
138	n/a
139	n/a	(major, minor, patch, prerelease, prerelease_num) = \
140	n/a	match.group(1, 2, 4, 5, 6)
141	n/a
142	n/a	if patch:
143	n/a	self.version = tuple(map(int, [major, minor, patch]))
144	n/a	else:
145	n/a	self.version = tuple(map(int, [major, minor])) + (0,)
146	n/a
147	n/a	if prerelease:
148	n/a	self.prerelease = (prerelease[0], int(prerelease_num))
149	n/a	else:
150	n/a	self.prerelease = None
151	n/a
152	n/a
153	n/a	def __str__ (self):
154	n/a
155	n/a	if self.version[2] == 0:
156	n/a	vstring = '.'.join(map(str, self.version[0:2]))
157	n/a	else:
158	n/a	vstring = '.'.join(map(str, self.version))
159	n/a
160	n/a	if self.prerelease:
161	n/a	vstring = vstring + self.prerelease[0] + str(self.prerelease[1])
162	n/a
163	n/a	return vstring
164	n/a
165	n/a
166	n/a	def _cmp (self, other):
167	n/a	if isinstance(other, str):
168	n/a	other = StrictVersion(other)
169	n/a
170	n/a	if self.version != other.version:
171	n/a	# numeric versions don't match
172	n/a	# prerelease stuff doesn't matter
173	n/a	if self.version < other.version:
174	n/a	return -1
175	n/a	else:
176	n/a	return 1
177	n/a
178	n/a	# have to compare prerelease
179	n/a	# case 1: neither has prerelease; they're equal
180	n/a	# case 2: self has prerelease, other doesn't; other is greater
181	n/a	# case 3: self doesn't have prerelease, other does: self is greater
182	n/a	# case 4: both have prerelease: must compare them!
183	n/a
184	n/a	if (not self.prerelease and not other.prerelease):
185	n/a	return 0
186	n/a	elif (self.prerelease and not other.prerelease):
187	n/a	return -1
188	n/a	elif (not self.prerelease and other.prerelease):
189	n/a	return 1
190	n/a	elif (self.prerelease and other.prerelease):
191	n/a	if self.prerelease == other.prerelease:
192	n/a	return 0
193	n/a	elif self.prerelease < other.prerelease:
194	n/a	return -1
195	n/a	else:
196	n/a	return 1
197	n/a	else:
198	n/a	assert False, "never get here"
199	n/a
200	n/a	# end class StrictVersion
201	n/a
202	n/a
203	n/a	# The rules according to Greg Stein:
204	n/a	# 1) a version number has 1 or more numbers separated by a period or by
205	n/a	# sequences of letters. If only periods, then these are compared
206	n/a	# left-to-right to determine an ordering.
207	n/a	# 2) sequences of letters are part of the tuple for comparison and are
208	n/a	# compared lexicographically
209	n/a	# 3) recognize the numeric components may have leading zeroes
210	n/a	#
211	n/a	# The LooseVersion class below implements these rules: a version number
212	n/a	# string is split up into a tuple of integer and string components, and
213	n/a	# comparison is a simple tuple comparison. This means that version
214	n/a	# numbers behave in a predictable and obvious way, but a way that might
215	n/a	# not necessarily be how people want version numbers to behave. There
216	n/a	# wouldn't be a problem if people could stick to purely numeric version
217	n/a	# numbers: just split on period and compare the numbers as tuples.
218	n/a	# However, people insist on putting letters into their version numbers;
219	n/a	# the most common purpose seems to be:
220	n/a	# - indicating a "pre-release" version
221	n/a	# ('alpha', 'beta', 'a', 'b', 'pre', 'p')
222	n/a	# - indicating a post-release patch ('p', 'pl', 'patch')
223	n/a	# but of course this can't cover all version number schemes, and there's
224	n/a	# no way to know what a programmer means without asking him.
225	n/a	#
226	n/a	# The problem is what to do with letters (and other non-numeric
227	n/a	# characters) in a version number. The current implementation does the
228	n/a	# obvious and predictable thing: keep them as strings and compare
229	n/a	# lexically within a tuple comparison. This has the desired effect if
230	n/a	# an appended letter sequence implies something "post-release":
231	n/a	# eg. "0.99" < "0.99pl14" < "1.0", and "5.001" < "5.001m" < "5.002".
232	n/a	#
233	n/a	# However, if letters in a version number imply a pre-release version,
234	n/a	# the "obvious" thing isn't correct. Eg. you would expect that
235	n/a	# "1.5.1" < "1.5.2a2" < "1.5.2", but under the tuple/lexical comparison
236	n/a	# implemented here, this just isn't so.
237	n/a	#
238	n/a	# Two possible solutions come to mind. The first is to tie the
239	n/a	# comparison algorithm to a particular set of semantic rules, as has
240	n/a	# been done in the StrictVersion class above. This works great as long
241	n/a	# as everyone can go along with bondage and discipline. Hopefully a
242	n/a	# (large) subset of Python module programmers will agree that the
243	n/a	# particular flavour of bondage and discipline provided by StrictVersion
244	n/a	# provides enough benefit to be worth using, and will submit their
245	n/a	# version numbering scheme to its domination. The free-thinking
246	n/a	# anarchists in the lot will never give in, though, and something needs
247	n/a	# to be done to accommodate them.
248	n/a	#
249	n/a	# Perhaps a "moderately strict" version class could be implemented that
250	n/a	# lets almost anything slide (syntactically), and makes some heuristic
251	n/a	# assumptions about non-digits in version number strings. This could
252	n/a	# sink into special-case-hell, though; if I was as talented and
253	n/a	# idiosyncratic as Larry Wall, I'd go ahead and implement a class that
254	n/a	# somehow knows that "1.2.1" < "1.2.2a2" < "1.2.2" < "1.2.2pl3", and is
255	n/a	# just as happy dealing with things like "2g6" and "1.13++". I don't
256	n/a	# think I'm smart enough to do it right though.
257	n/a	#
258	n/a	# In any case, I've coded the test suite for this module (see
259	n/a	# ../test/test_version.py) specifically to fail on things like comparing
260	n/a	# "1.2a2" and "1.2". That's not because the code is doing anything
261	n/a	# wrong, it's because the simple, obvious design doesn't match my
262	n/a	# complicated, hairy expectations for real-world version numbers. It
263	n/a	# would be a snap to fix the test suite to say, "Yep, LooseVersion does
264	n/a	# the Right Thing" (ie. the code matches the conception). But I'd rather
265	n/a	# have a conception that matches common notions about version numbers.
266	n/a
267	n/a	class LooseVersion (Version):
268	n/a
269	n/a	"""Version numbering for anarchists and software realists.
270	n/a	Implements the standard interface for version number classes as
271	n/a	described above. A version number consists of a series of numbers,
272	n/a	separated by either periods or strings of letters. When comparing
273	n/a	version numbers, the numeric components will be compared
274	n/a	numerically, and the alphabetic components lexically. The following
275	n/a	are all valid version numbers, in no particular order:
276	n/a
277	n/a	1.5.1
278	n/a	1.5.2b2
279	n/a	161
280	n/a	3.10a
281	n/a	8.02
282	n/a	3.4j
283	n/a	1996.07.12
284	n/a	3.2.pl0
285	n/a	3.1.1.6
286	n/a	2g6
287	n/a	11g
288	n/a	0.960923
289	n/a	2.2beta29
290	n/a	1.13++
291	n/a	5.5.kw
292	n/a	2.0b1pl0
293	n/a
294	n/a	In fact, there is no such thing as an invalid version number under
295	n/a	this scheme; the rules for comparison are simple and predictable,
296	n/a	but may not always give the results you want (for some definition
297	n/a	of "want").
298	n/a	"""
299	n/a
300	n/a	component_re = re.compile(r'(\d+ \| [a-z]+ \| \.)', re.VERBOSE)
301	n/a
302	n/a	def __init__ (self, vstring=None):
303	n/a	if vstring:
304	n/a	self.parse(vstring)
305	n/a
306	n/a
307	n/a	def parse (self, vstring):
308	n/a	# I've given up on thinking I can reconstruct the version string
309	n/a	# from the parsed tuple -- so I just store the string here for
310	n/a	# use by __str__
311	n/a	self.vstring = vstring
312	n/a	components = [x for x in self.component_re.split(vstring)
313	n/a	if x and x != '.']
314	n/a	for i, obj in enumerate(components):
315	n/a	try:
316	n/a	components[i] = int(obj)
317	n/a	except ValueError:
318	n/a	pass
319	n/a
320	n/a	self.version = components
321	n/a
322	n/a
323	n/a	def __str__ (self):
324	n/a	return self.vstring
325	n/a
326	n/a
327	n/a	def __repr__ (self):
328	n/a	return "LooseVersion ('%s')" % str(self)
329	n/a
330	n/a
331	n/a	def _cmp (self, other):
332	n/a	if isinstance(other, str):
333	n/a	other = LooseVersion(other)
334	n/a
335	n/a	if self.version == other.version:
336	n/a	return 0
337	n/a	if self.version < other.version:
338	n/a	return -1
339	n/a	if self.version > other.version:
340	n/a	return 1
341	n/a
342	n/a
343	n/a	# end class LooseVersion