Doc/library/packaging.version.rst

: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)'``.