105 lines
3.1 KiB
ReStructuredText
105 lines
3.1 KiB
ReStructuredText
|
:mod:`packaging.version` --- Version number classes
|
||
|
|
===================================================
|
||
|
|
|
||
|
|
.. module:: packaging.version
|
||
|
|
:synopsis: Classes that represent project version numbers.
|
||
|
|
|
||
|
|
|
||
|
|
This module contains classes and functions useful to deal with version numbers.
|
||
|
|
It's an implementation of version specifiers `as defined in PEP 345
|
||
|
|
<http://www.python.org/dev/peps/pep-0345/#version-specifiers>`_.
|
||
|
|
|
||
|
|
|
||
|
|
Version numbers
|
||
|
|
---------------
|
||
|
|
|
||
|
|
.. class:: NormalizedVersion(self, s, error_on_huge_major_num=True)
|
||
|
|
|
||
|
|
A specific version of a distribution, as described in PEP 345. *s* is a
|
||
|
|
string object containing the version number (for example ``'1.2b1'``),
|
||
|
|
*error_on_huge_major_num* a boolean specifying whether to consider an
|
||
|
|
apparent use of a year or full date as the major version number an error.
|
||
|
|
|
||
|
|
The rationale for the second argument is that there were projects using years
|
||
|
|
or full dates as version numbers, which could cause problems with some
|
||
|
|
packaging systems sorting.
|
||
|
|
|
||
|
|
Instances of this class can be compared and sorted::
|
||
|
|
|
||
|
|
>>> NormalizedVersion('1.2b1') < NormalizedVersion('1.2')
|
||
|
|
True
|
||
|
|
|
||
|
|
:class:`NormalizedVersion` is used internally by :class:`VersionPredicate` to
|
||
|
|
do its work.
|
||
|
|
|
||
|
|
|
||
|
|
.. class:: IrrationalVersionError
|
||
|
|
|
||
|
|
Exception raised when an invalid string is given to
|
||
|
|
:class:`NormalizedVersion`.
|
||
|
|
|
||
|
|
>>> NormalizedVersion("irrational_version_number")
|
||
|
|
...
|
||
|
|
IrrationalVersionError: irrational_version_number
|
||
|
|
|
||
|
|
|
||
|
|
.. function:: suggest_normalized_version(s)
|
||
|
|
|
||
|
|
Before standardization in PEP 386, various schemes were in use. Packaging
|
||
|
|
provides a function to try to convert any string to a valid, normalized
|
||
|
|
version::
|
||
|
|
|
||
|
|
>>> suggest_normalized_version('2.1-rc1')
|
||
|
|
2.1c1
|
||
|
|
|
||
|
|
|
||
|
|
If :func:`suggest_normalized_version` can't make sense of the given string,
|
||
|
|
it will return ``None``::
|
||
|
|
|
||
|
|
>>> print(suggest_normalized_version('not a version'))
|
||
|
|
None
|
||
|
|
|
||
|
|
|
||
|
|
Version predicates
|
||
|
|
------------------
|
||
|
|
|
||
|
|
.. class:: VersionPredicate(predicate)
|
||
|
|
|
||
|
|
This class deals with the parsing of field values like
|
||
|
|
``ProjectName (>=version)``.
|
||
|
|
|
||
|
|
.. method:: match(version)
|
||
|
|
|
||
|
|
Test if a version number matches the predicate:
|
||
|
|
|
||
|
|
>>> version = VersionPredicate("ProjectName (<1.2, >1.0)")
|
||
|
|
>>> version.match("1.2.1")
|
||
|
|
False
|
||
|
|
>>> version.match("1.1.1")
|
||
|
|
True
|
||
|
|
|
||
|
|
|
||
|
|
Validation helpers
|
||
|
|
------------------
|
||
|
|
|
||
|
|
If you want to use :term:`LBYL`-style checks instead of instantiating the
|
||
|
|
classes and catching :class:`IrrationalVersionError` and :class:`ValueError`,
|
||
|
|
you can use these functions:
|
||
|
|
|
||
|
|
.. function:: is_valid_version(predicate)
|
||
|
|
|
||
|
|
Check whether the given string is a valid version number. Example of valid
|
||
|
|
strings: ``'1.2'``, ``'4.2.0.dev4'``, ``'2.5.4.post2'``.
|
||
|
|
|
||
|
|
|
||
|
|
.. function:: is_valid_versions(predicate)
|
||
|
|
|
||
|
|
Check whether the given string is a valid value for specifying multiple
|
||
|
|
versions, such as in the Requires-Python field. Example: ``'2.7, >=3.2'``.
|
||
|
|
|
||
|
|
|
||
|
|
.. function:: is_valid_predicate(predicate)
|
||
|
|
|
||
|
|
Check whether the given string is a valid version predicate. Examples:
|
||
|
|
``'some.project == 4.5, <= 4.7'``, ``'speciallib (> 1.0, != 1.4.2, < 2.0)'``.
|