: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>`_.

.. warning:: This documentation has not been updated since being copied over
   from ``distutils2``, and may not be up to date.

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` / :pep:`426`, various schemes were in
   use. This is 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)'``.
