Version Handling¶
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¶
>>> 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¶
-
packaging.version.
parse
(version)[source]¶ This function takes a version string and will parse it as a
Version
if the version is a valid PEP 440 version, otherwise it will parse it as a deprecatedLegacyVersion
.
-
class
packaging.version.
Version
(version)[source]¶ This class abstracts handling of a project’s versions. It implements the scheme defined in PEP 440. A
Version
instance is comparison aware and can be compared and sorted using the standard Python interfaces.- Parameters
version (str) – 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.
-
public
¶ A string representing the public version portion of this
Version()
.
-
base_version
¶ A string representing the base version of this
Version
instance. The base version is the public version of the project without any pre or post release markers.
-
release
¶ A tuple of integers giving the components of the release segment of this
Version
instance; that is, the1.2.3
part of the version number, including trailing zeroes but not including the epoch or any prerelease/development/postrelease suffixes
-
local
¶ A string representing the local version portion of this
Version()
if it has one, orNone
otherwise.
-
pre
¶ If this
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.
-
is_prerelease
¶ A boolean value indicating whether this
Version
instance represents a prerelease and/or development release.
-
dev
¶ If this
Version
instance represents a development release, this attribute will be the development release number (an integer); otherwise, it will be None.
-
is_devrelease
¶ A boolean value indicating whether this
Version
instance represents a development release.
-
class
packaging.version.
LegacyVersion
(version)[source]¶ Deprecated since version 20.5: Use
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
Version
.This class implements the previous de facto sorting algorithm used by setuptools, however it will always sort as less than a
Version
instance.- Parameters
version (str) – The string representation of a version which will be used as is.
Note
LegacyVersion
instances are always ordered lower thanVersion
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 (
Version
), even if they look very similar to other versions that are not (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
-
public
¶ A string representing the public version portion of this
LegacyVersion
. This will always be the entire version string.
-
base_version
¶ A string representing the base version portion of this
LegacyVersion
instance. This will always be the entire version string.
-
epoch
¶ This will always be
-1
since without PEP 440 we do not have the concept of version epochs. The value reflects the fact thatLegacyVersion
instances always compare less thanVersion
instances.
-
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 aLegacyVersion
to be used as a stand in for aVersion
.
-
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 aLegacyVersion
to be used as a stand in for aVersion
.
-
pre
¶ This will always be
None
since without PEP 440 we do not have the concept of a prerelease. It exists primarily to allow aLegacyVersion
to be used as a stand in for aVersion
.
-
is_prerelease
¶ A boolean value indicating whether this
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 withVersion
.
-
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 aLegacyVersion
to be used as a stand in for aVersion
.
-
is_devrelease
¶ A boolean value indicating whether this
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 withVersion
.
-
post
¶ This will always be
None
since without PEP 440 we do not have the concept of a postrelease. It exists primarily to allow aLegacyVersion
to be used as a stand in for aVersion
.
-
is_postrelease
¶ A boolean value indicating whether this
LegacyVersion
represents a post-release. Since without PEP 440 there is no concept of post-releases this will always beFalse
and exists for compatibility withVersion
.
-
exception
packaging.version.
InvalidVersion
[source]¶ Raised when attempting to create a
Version
with a version string that does not conform to PEP 440.
-
packaging.version.
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
andre.IGNORECASE
flags set.