Improve documentation of deprecated functions

tomschr · tomschr · commit c4ac0ece0329 · 2020-04-10T18:57:51.000+02:00
* List deprecated module level functions
* Make recommendation and show equivalent code
* Mention that deprecated functions will be replaced in
  major 4 of semver. That means, they will be still
  available in semver 3.
diff --git a/CHANGELOG.rst b/CHANGELOG.rst
@@ -40,6 +40,8 @@ Removals
   - ``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 functions will be removed in major 4 of semver.
 
diff --git a/docs/usage.rst b/docs/usage.rst
@@ -14,9 +14,10 @@ are met.
 Knowing the Implemented semver.org Version
 ------------------------------------------
 
-The semver.org 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::
+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::
 
    >>> semver.SEMVER_SPEC_VERSION
    '2.0.0'
@@ -25,6 +26,25 @@ libary, use the following constant::
 Creating a Version
 ------------------
 
+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 4.
+    For details, see section :ref:`sec_replace_deprecated_functions`.
+
+
 A version can be created in different ways:
 
 * as a complete version string::
@@ -362,8 +382,96 @@ For example:
 
 .. code-block:: python
 
-    >>> coerce("v1.2")                                                                                                                                       
+    >>> coerce("v1.2")
     (VersionInfo(major=1, minor=2, patch=0, prerelease=None, build=None), '')
     >>> coerce("v2.5.2-bla")
     (VersionInfo(major=2, minor=5, patch=2, prerelease=None, build=None), '-bla')
 
+
+.. _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 until semver 3. In version 4 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
+
+     >>> s1 = semver.bump_major("3.4.5")
+     >>> s2 = str(semver.VersionInfo.parse("3.4.5").bump_major())
+     >>> s1 == s2
+     True
+
+  Likewise with the other module level functions.
+
+* :func:`semver.finalize_version`
+
+  Replace it with :func:`semver.VersionInfo.finalize_version`:
+
+  .. code-block:: python
+
+     >>> s1 = semver.finalize_version('1.2.3-rc.5')
+     >>> s2 = str(semver.VersionInfo.parse('1.2.3-rc.5').finalize_version())
+     >>> s1 == s2
+     True
+
+* :func:`semver.format_version`
+
+  Replace it with ``str(versionobject)``:
+
+  .. code-block:: python
+
+     >>> s1 = semver.format_version(5, 4, 3, 'pre.2', 'build.1')
+     >>> s2 = str(semver.VersionInfo(5, 4, 3, 'pre.2', 'build.1'))
+     >>> s1 == s2
+     True
+
+* :func:`semver.parse`
+
+  Replace it with :func:`semver.VersionInfo.parse` and
+  :func:`semver.VersionInfo.to_dict`:
+
+  .. code-block:: python
+
+     >>> v1 = semver.parse("1.2.3")
+     >>> v2 = semver.VersionInfo.parse("1.2.3").to_dict()
+     >>> v1 == v2
+     True
+
+* :func:`semver.parse_version_info`
+
+  Replace it with :func:`semver.VersionInfo.parse`:
+
+  .. code-block:: python
+
+     >>> v1 = semver.parse_version_info("3.4.5")
+     >>> v2 = semver.VersionInfo.parse("3.4.5")
+     >>> v1 == v2
+     True
+
+* :func:`semver.replace`
+
+  Replace it with :func:`semver.VersionInfo.replace`:
+
+  .. code-block:: python
+
+     >>> s1 = semver.replace("1.2.3", major=2, patch=10)
+     >>> s2 = str(semver.VersionInfo.parse('1.2.3').replace(major=2, patch=10))
+     >>> s1 == s2
+     True
diff --git a/semver.py b/semver.py
@@ -32,7 +32,10 @@ def deprecated(replace=None):
     """
     Decorates a function to output a deprecation warning.
 
-    This function will be removed once major version 3 of semver is
+    :param str replace: the name of the function which the deprecated
+                        function should be replaced with
+
+    This function will be removed once major version 4 of semver is
     released.
     """
 
