Fix #225: Deprecate module level functions

tomschr · tomschr · commit ecd7017d8a3e · 2020-03-20T08:08:19.000+01:00
* Add test cases
* In `setup.cfg`, add deprecation warnings filter for pytest
* Implement DeprecationWarning with warnings module and
  the new decorator `deprecated`
* 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
  Add also a deprecation notice in the docstrings of these
  functions
* Update CHANGELOG.rst
diff --git a/CHANGELOG.rst b/CHANGELOG.rst
@@ -18,12 +18,8 @@ Features
 Bug Fixes
 ---------
 
-<<<<<<< HEAD
 * :gh:`224` (:pr:`226`): In ``setup.py``, replaced in class ``clean``,
   ``super(CleanCommand, self).run()`` with ``CleanCommand.run(self)``
-=======
-* :gh:`224` (:pr:`226`): Replaced in class ``clean``, ``super(CleanCommand, self).run()`` with ``CleanCommand.run(self)``
->>>>>>> Fix #225: Deprecate module level functions
 
 
 Additions
diff --git a/semver.py b/semver.py
@@ -35,22 +35,17 @@ def deprecated(replace=None):
     This function will be removed once major version 3 of semver is
     released.
     """
-    # we can't use the 'nonlocal' keyword in Python2, so we need
-    # to circumvent that with a dictionary:
-    r = {"r": replace}
 
     def decorator(func):
+        r = replace or func.__name__
+
         @wraps(func)
         def wrapper(*args, **kwargs):
-            # nonlocal replace
-            replace = r["r"] if r["r"] is not None else func.__name__
             msg = (
                 "Function 'semver.{f}' is deprecated. "
                 "Use the respective 'semver.VersionInfo.{r}' instead."
             )
-            warnings.warn(
-                msg.format(f=func.__name__, r=replace), category=DeprecationWarning
-            )
+            warnings.warn(msg.format(f=func.__name__, r=r), category=DeprecationWarning)
             return func(*args, **kwargs)
 
         return wrapper
@@ -64,7 +59,7 @@ def parse(version):
     Parse version to major, minor, patch, pre-release, build parts.
 
     .. deprecated:: 2.9.2
-       Use :func:`semver.VersionInfo.format_parse` instead.
+       Use :func:`semver.VersionInfo.parse` instead.
 
     :param version: version string
     :return: dictionary with the keys 'build', 'major', 'minor', 'patch',
@@ -318,11 +313,30 @@ def __repr__(self):
         return "%s(%s)" % (type(self).__name__, s)
 
     def __str__(self):
-        return VersionInfo.format_version(*(self._astuple()))
+        """str(self)"""
+        version = "%d.%d.%d" % (self.major, self.minor, self.patch)
+        if self.prerelease:
+            version += "-%s" % self.prerelease
+        if self.build:
+            version += "+%s" % self.build
+        return version
 
     def __hash__(self):
         return hash(self._astuple())
 
+    def finalize_version(self):
+        """
+        Remove any prerelease and build metadata from the version.
+
+        :return: a new instance with the finalized version string
+        :rtype: :class:`VersionInfo`
+
+        >>> str(semver.VersionInfo.parse('1.2.3-rc.5').finalize_version())
+        '1.2.3'
+        """
+        cls = type(self)
+        return cls(self.major, self.minor, self.patch)
+
     @staticmethod
     def parse(version):
         """
@@ -386,31 +400,6 @@ def isvalid(cls, version):
         except ValueError:
             return False
 
-    @staticmethod
-    def format_version(major, minor, patch, prerelease=None, build=None):
-        """
-        Format a version according to the Semantic Versioning specification.
-
-        :param int major: the required major part of a version
-        :param int minor: the required minor part of a version
-        :param int patch: the required patch part of a version
-        :param str prerelease: the optional prerelease part of a version
-        :param str build: the optional build part of a version
-        :return: the formatted string
-        :rtype: str
-
-        >>> semver.VersionInfo.format_version(3, 4, 5, 'pre.2', 'build.4')
-        '3.4.5-pre.2+build.4'
-        """
-        version = "%d.%d.%d" % (major, minor, patch)
-        if prerelease is not None:
-            version = version + "-%s" % prerelease
-
-        if build is not None:
-            version = version + "+%s" % build
-
-        return version
-
 
 def _to_dict(obj):
     if isinstance(obj, VersionInfo):
@@ -428,6 +417,9 @@ def parse_version_info(version):
     .. deprecated:: 2.9.2
        Use :func:`semver.VersionInfo.parse` instead.
 
+    .. versionadded:: 2.7.2
+       Added :func:`parse_version_info`
+
     :param version: version string
     :return: a :class:`VersionInfo` instance
     :rtype: :class:`VersionInfo`
@@ -610,7 +602,7 @@ def format_version(major, minor, patch, prerelease=None, build=None):
     Format a version according to the Semantic Versioning specification.
 
     .. deprecated:: 2.9.2
-       Use :func:`semver.VersionInfo.format_version` instead.
+       Use ``str(VersionInfo(VERSION)`` instead.
 
     :param int major: the required major part of a version
     :param int minor: the required minor part of a version
@@ -623,7 +615,7 @@ def format_version(major, minor, patch, prerelease=None, build=None):
     >>> semver.format_version(3, 4, 5, 'pre.2', 'build.4')
     '3.4.5-pre.2+build.4'
     """
-    return VersionInfo.format_version(major, minor, patch, prerelease, build)
+    return str(VersionInfo(major, minor, patch, prerelease, build))
 
 
 def _increment_string(string):
@@ -738,7 +730,7 @@ def finalize_version(version):
     Remove any prerelease and build metadata from the version.
 
     .. deprecated:: 2.9.2
-       Use :func:`semver.VersionInfo.bump_format_version` instead.
+       Use :func:`semver.VersionInfo.finalize_version` instead.
 
     :param version: version string
     :return: the finalized version string
@@ -748,7 +740,7 @@ def finalize_version(version):
     '1.2.3'
     """
     verinfo = VersionInfo.parse(version)
-    return VersionInfo.format_version(verinfo.major, verinfo.minor, verinfo.patch)
+    return str(verinfo.finalize_version())
 
 
 @deprecated()
