Fix #225: Deprecate module level functions

tomschr · tomschr · commit c8948bab2e9a · 2020-04-10T10:57:47.000+02: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,19 +18,16 @@ 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
 ---------
 
 * :pr:`228`: Added better doctest integration
 
+
 Removals
 --------
 * :gh:`225` (:pr:`229`): Output a DeprecationWarning for the following functions:
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):
         """
@@ -392,31 +406,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):
@@ -437,6 +426,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`
@@ -619,7 +611,7 @@ def format_version(major, minor, patch, prerelease=None, build=None):
     Format a version string 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
@@ -632,7 +624,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):
@@ -750,7 +742,7 @@ def finalize_version(version):
        Added :func:`finalize_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
@@ -760,14 +752,17 @@ 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()
 def replace(version, **parts):
     """
     Replace one or more parts of a version and return the new string.
 
+    .. versionadded:: 2.9.0
+       Added :func:`replace`
+
     .. deprecated:: 2.9.2
        Use :func:`semver.VersionInfo.replace` instead.
 
@@ -927,28 +922,6 @@ def main(cliargs=None):
         return 2
 
 
-def replace(version, **parts):
-    """
-    Replace one or more parts of a version and return the new string.
-
-    .. versionadded:: 2.9.0
-       Added :func:`replace`
-
-    :param str version: the version string to replace
-    :param dict parts: the parts to be updated. Valid keys are:
-      ``major``, ``minor``, ``patch``, ``prerelease``, or ``build``
-    :return: the replaced version string
-    :raises: TypeError, if ``parts`` contains invalid keys
-    :rtype: str
-
-    >>> import semver
-    >>> semver.replace("1.2.3", major=2, patch=10)
-    '2.2.10'
-    """
-    version = parse_version_info(version)
-    return str(version.replace(**parts))
-
-
 if __name__ == "__main__":
     import doctest
 
