* :gh:`225` (:pr:`229`): Output a DeprecationWarning for the following functions:

- ``semver.parse``

- ``semver.parse_version_info``

- ``semver.format_version``

- ``semver.bump_{major,minor,patch,prerelease,build}``

- ``semver.finalize_version``

- ``semver.replace``

- ``semver.VersionInfo._asdict`` (use the new, public available

function ``semver.VersionInfo.to_dict()``)

- ``semver.VersionInfo._astuple`` (use the new, public available

function ``semver.VersionInfo.to_tuple()``)

These deprecated functions will be removed in semver 3.

The semver.org page is the authorative specification of how semantical

versioning is definied.

To know which version of semver.org is implemented in the semver libary,

use the following constant::

Due to historical reasons, the semver project offers two ways of

creating a version:

* through an object oriented approach with the :class:`semver.VersionInfo`

class. This is the preferred method when using semver.

* through module level functions and builtin datatypes (usually strings

and dicts).

These method are still available for compatibility reasons, but are

marked as deprecated. Using one of these will emit a DeprecationWarning.

.. warning:: **Deprecation Warning**

Module level functions are marked as *deprecated* in version 2.9.2 now.

These functions will be removed in semver 3.

For details, see the sections :ref:`sec_replace_deprecated_functions` and

:ref:`sec_display_deprecation_warnings`.

A :class:`semver.VersionInfo` instance can be created in different ways:

* From a string::

* From individual parts by a dictionary::

* From a tuple::

The old, deprecated module level functions are still available. If you

need them, they return different builtin objects (string and dictionary).

Keep in mind, once you have converted a version into a string or dictionary,

it's an ordinary builtin object. It's not a special version object like

the :class:`semver.VersionInfo` class anymore.

Depending on your use case, the following methods are available:

* From individual version parts into a string

In some cases you only need a string from your version data::

* From a string into a dictionary

To access individual parts, you can use the function :func:`semver.parse`::

If you pass an invalid version string you will get a ``ValueError``::

Converting a VersionInfo instance into Different Types

a different type. For example, for displaying or to access all parts.

It is possible to convert a :class:`semver.VersionInfo` instance:

* Into a string with the builtin function :func:`str`::

* Into a dictionary with :func:`semver.VersionInfo.to_dict`::

* Into a tuple with :func:`semver.VersionInfo.to_tuple`::

.. _sec_replace_deprecated_functions:

Replacing Deprecated Functions

The development team of semver has decided to deprecate certain functions on

the module level. The preferred way of using semver is through the

:class:`semver.VersionInfo` class.

The deprecated functions can still be used in version 2.x.y. In version 3 of

semver, the deprecated functions will be removed.

The following list shows the deprecated functions and how you can replace

them with code which is compatible for future versions:

* :func:`semver.bump_major`, :func:`semver.bump_minor`, :func:`semver.bump_patch`, :func:`semver.bump_prerelease`, :func:`semver.bump_build`

Replace them with the respective methods of the :class:`semver.VersionInfo`

class.

For example, the function :func:`semver.bump_major` is replaced by

:func:`semver.VersionInfo.bump_major` and calling the ``str(versionobject)``:

.. code-block:: python

Likewise with the other module level functions.

* :func:`semver.finalize_version`

Replace it with :func:`semver.VersionInfo.finalize_version`:

.. code-block:: python

* :func:`semver.format_version`

Replace it with ``str(versionobject)``:

.. code-block:: python

* :func:`semver.parse`

Replace it with :func:`semver.VersionInfo.parse` and

:func:`semver.VersionInfo.to_dict`:

.. code-block:: python

* :func:`semver.parse_version_info`

Replace it with :func:`semver.VersionInfo.parse`:

.. code-block:: python

* :func:`semver.replace`

Replace it with :func:`semver.VersionInfo.replace`:

.. code-block:: python

.. _sec_display_deprecation_warnings:

Displaying Deprecation Warnings

By default, deprecation warnings are `ignored in Python <https://docs.python.org/3/library/warnings.html#warning-categories>`_.

This also affects semver's own warnings.

It is recommended that you turn on deprecation warnings in your scripts. Use one of

the following methods:

* Use the option `-Wd <https://docs.python.org/3/using/cmdline.html#cmdoption-w>`_

to enable default warnings:

* Directly running the Python command::

* Add the option in the shebang line (something like ``#!/usr/bin/python3``)

after the command::

* In your own scripts add a filter to ensure that *all* warnings are displayed:

.. code-block:: python

For further details, see the section

`Overriding the default filter <https://docs.python.org/3/library/warnings.html#overriding-the-default-filter>`_

of the Python documentation.