Commit 561384c

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

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