1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
|
Version Handling
================
.. currentmodule:: packaging.version
A core requirement of dealing with packages is the ability to work with
versions. `PEP 440`_ defines the standard version scheme for Python packages
which has been implemented by this module.
Usage
-----
.. doctest::
>>> from packaging.version import Version, parse
>>> v1 = parse("1.0a5")
>>> v2 = Version("1.0")
>>> v1
<Version('1.0a5')>
>>> v2
<Version('1.0')>
>>> v1 < v2
True
>>> v1.epoch
0
>>> v1.release
(1, 0)
>>> v1.pre
('a', 5)
>>> v1.is_prerelease
True
>>> v2.is_prerelease
False
>>> Version("french toast")
Traceback (most recent call last):
...
InvalidVersion: Invalid version: 'french toast'
>>> Version("1.0").post
>>> Version("1.0").is_postrelease
False
>>> Version("1.0.post0").post
0
>>> Version("1.0.post0").is_postrelease
True
Reference
---------
.. function:: parse(version)
This function takes a version string and will parse it as a
:class:`Version` if the version is a valid PEP 440 version, otherwise it
will parse it as a deprecated :class:`LegacyVersion`.
.. class:: Version(version)
This class abstracts handling of a project's versions. It implements the
scheme defined in `PEP 440`_. A :class:`Version` instance is comparison
aware and can be compared and sorted using the standard Python interfaces.
:param str version: The string representation of a version which will be
parsed and normalized before use.
:raises InvalidVersion: If the ``version`` does not conform to PEP 440 in
any way then this exception will be raised.
.. attribute:: public
A string representing the public version portion of this ``Version()``.
.. attribute:: base_version
A string representing the base version of this :class:`Version`
instance. The base version is the public version of the project without
any pre or post release markers.
.. attribute:: epoch
An integer giving the version epoch of this :class:`Version` instance
.. attribute:: release
A tuple of integers giving the components of the release segment of
this :class:`Version` instance; that is, the ``1.2.3`` part of the
version number, including trailing zeroes but not including the epoch
or any prerelease/development/postrelease suffixes
.. attribute:: major
An integer representing the first item of :attr:`release` or ``0`` if unavailable.
.. attribute:: minor
An integer representing the second item of :attr:`release` or ``0`` if unavailable.
.. attribute:: micro
An integer representing the third item of :attr:`release` or ``0`` if unavailable.
.. attribute:: local
A string representing the local version portion of this ``Version()``
if it has one, or ``None`` otherwise.
.. attribute:: pre
If this :class:`Version` instance represents a prerelease, this
attribute will be a pair of the prerelease phase (the string ``"a"``,
``"b"``, or ``"rc"``) and the prerelease number (an integer). If this
instance is not a prerelease, the attribute will be `None`.
.. attribute:: is_prerelease
A boolean value indicating whether this :class:`Version` instance
represents a prerelease and/or development release.
.. attribute:: dev
If this :class:`Version` instance represents a development release,
this attribute will be the development release number (an integer);
otherwise, it will be `None`.
.. attribute:: is_devrelease
A boolean value indicating whether this :class:`Version` instance
represents a development release.
.. attribute:: post
If this :class:`Version` instance represents a postrelease, this
attribute will be the postrelease number (an integer); otherwise, it
will be `None`.
.. attribute:: is_postrelease
A boolean value indicating whether this :class:`Version` instance
represents a post-release.
.. class:: LegacyVersion(version)
.. deprecated:: 20.5
Use :class:`Version` instead.
This class abstracts handling of a project's versions if they are not
compatible with the scheme defined in `PEP 440`_. It implements a similar
interface to that of :class:`Version`.
This class implements the previous de facto sorting algorithm used by
setuptools, however it will always sort as less than a :class:`Version`
instance.
:param str version: The string representation of a version which will be
used as is.
.. note::
:class:`LegacyVersion` instances are always ordered lower than :class:`Version` instances.
>>> from packaging.version import Version, LegacyVersion
>>> v1 = Version("1.0")
>>> v2 = LegacyVersion("1.0")
>>> v1 > v2
True
>>> v3 = LegacyVersion("1.3")
>>> v1 > v3
True
Also note that some strings are still valid PEP 440 strings (:class:`Version`), even if they look very similar to
other versions that are not (:class:`LegacyVersion`). Examples include versions with `Pre-release spelling`_ and
`Post-release spelling`_.
>>> from packaging.version import parse
>>> v1 = parse('0.9.8a')
>>> v2 = parse('0.9.8beta')
>>> v3 = parse('0.9.8r')
>>> v4 = parse('0.9.8rev')
>>> v5 = parse('0.9.8t')
>>> v1
<Version('0.9.8a0')>
>>> v1.is_prerelease
True
>>> v2
<Version('0.9.8b0')>
>>> v2.is_prerelease
True
>>> v3
<Version('0.9.8.post0')>
>>> v3.is_postrelease
True
>>> v4
<Version('0.9.8.post0')>
>>> v4.is_postrelease
True
>>> v5
<LegacyVersion('0.9.8t')>
>>> v5.is_prerelease
False
>>> v5.is_postrelease
False
.. attribute:: public
A string representing the public version portion of this
:class:`LegacyVersion`. This will always be the entire version string.
.. attribute:: base_version
A string representing the base version portion of this
:class:`LegacyVersion` instance. This will always be the entire version
string.
.. attribute:: epoch
This will always be ``-1`` since without `PEP 440`_ we do not have the
concept of version epochs. The value reflects the fact that
:class:`LegacyVersion` instances always compare less than
:class:`Version` instances.
.. attribute:: release
This will always be ``None`` since without `PEP 440`_ we do not have
the concept of a release segment or its components. It exists
primarily to allow a :class:`LegacyVersion` to be used as a stand in
for a :class:`Version`.
.. attribute:: local
This will always be ``None`` since without `PEP 440`_ we do not have
the concept of a local version. It exists primarily to allow a
:class:`LegacyVersion` to be used as a stand in for a :class:`Version`.
.. attribute:: pre
This will always be ``None`` since without `PEP 440`_ we do not have
the concept of a prerelease. It exists primarily to allow a
:class:`LegacyVersion` to be used as a stand in for a :class:`Version`.
.. attribute:: is_prerelease
A boolean value indicating whether this :class:`LegacyVersion`
represents a prerelease and/or development release. Since without
`PEP 440`_ there is no concept of pre or dev releases this will
always be `False` and exists for compatibility with :class:`Version`.
.. attribute:: dev
This will always be ``None`` since without `PEP 440`_ we do not have
the concept of a development release. It exists primarily to allow a
:class:`LegacyVersion` to be used as a stand in for a :class:`Version`.
.. attribute:: is_devrelease
A boolean value indicating whether this :class:`LegacyVersion`
represents a development release. Since without `PEP 440`_ there is
no concept of dev releases this will always be `False` and exists for
compatibility with :class:`Version`.
.. attribute:: post
This will always be ``None`` since without `PEP 440`_ we do not have
the concept of a postrelease. It exists primarily to allow a
:class:`LegacyVersion` to be used as a stand in for a :class:`Version`.
.. attribute:: is_postrelease
A boolean value indicating whether this :class:`LegacyVersion`
represents a post-release. Since without `PEP 440`_ there is no concept
of post-releases this will always be ``False`` and exists for
compatibility with :class:`Version`.
.. exception:: InvalidVersion
Raised when attempting to create a :class:`Version` with a version string
that does not conform to `PEP 440`_.
.. data:: VERSION_PATTERN
A string containing the regular expression used to match a valid version.
The pattern is not anchored at either end, and is intended for embedding
in larger expressions (for example, matching a version number as part of
a file name). The regular expression should be compiled with the
``re.VERBOSE`` and ``re.IGNORECASE`` flags set.
.. _PEP 440: https://www.python.org/dev/peps/pep-0440/
.. _Pre-release spelling : https://www.python.org/dev/peps/pep-0440/#pre-release-spelling
.. _Post-release spelling : https://www.python.org/dev/peps/pep-0440/#post-release-spelling
|
