Fix python-semver#258: Keep semver._deprecated.compare

Although it breaks consistency with module level functions, it
seems it's a much needed/used function.

* Function is also available accessing semver.compare
* Decorate semver.compare as PendingDeprecationWarning
* Adapt `deprecated` decorator and use enforce keyword arguments

It's still unclear if we should deprecate this function or not (that's
why we use PendingDeprecationWarning).
As we don't have a uniform initializer yet, this function stays
in _deprecated.py for the time being until we find a better soltuion.

See python-semver#258 for details

docs/api.rst

@@ -27,8 +27,6 @@ Deprecated Functions in :mod:`semver._deprecated`
 
 .. autofunction:: semver._deprecated.bump_prerelease
 
-.. autofunction:: semver._deprecated.compare
-
 .. autofunction:: semver._deprecated.deprecated
 
 .. autofunction:: semver._deprecated.finalize_version
@@ -78,6 +76,7 @@ Version Handling :mod:`semver.version`
 --------------------------------------
 
 .. automodule:: semver.version
+   :members: compare
 
 .. autoclass:: semver.version.VersionInfo
 

docs/usage/compare-versions.rst

@@ -5,7 +5,7 @@ To compare two versions depends on your type:
 
 * **Two strings**
 
-  Use :func:`semver.compare`::
+  Use :func:`~semver.version.compare`::
 
     >>> semver.compare("1.0.0", "2.0.0")
     -1

src/semver/__init__.py

@@ -9,8 +9,8 @@
     bump_major,
     bump_minor,
     bump_patch,
-    bump_prerelease,
     compare,
+    bump_prerelease,
     finalize_version,
     format_version,
     match,

src/semver/_deprecated.py

@@ -16,8 +16,10 @@
 
 def deprecated(
     func: Optional[F] = None,
+    *,
     replace: Optional[str] = None,
     version: Optional[str] = None,
+    remove: Optional[str] = None,
     category: Type[Warning] = DeprecationWarning,
 ) -> Decorator:
     """
@@ -34,15 +36,26 @@ def deprecated(
     """
 
     if func is None:
-        return partial(deprecated, replace=replace, version=version, category=category)
+        return partial(
+            deprecated,
+            replace=replace,
+            version=version,
+            remove=remove,
+            category=category,
+        )
 
     @wraps(func)
     def wrapper(*args, **kwargs) -> Callable[..., F]:
         msg_list = ["Function 'semver.{f}' is deprecated."]
 
         if version:
             msg_list.append("Deprecated since version {v}. ")
-        msg_list.append("This function will be removed in semver 3.")
+
+        if not remove:
+            msg_list.append("This function will be removed in semver 3.")
+        else:
+            msg_list.append(str(remove))
+
         if replace:
             msg_list.append("Use {r!r} instead.")
         else:
@@ -69,6 +82,30 @@ def wrapper(*args, **kwargs) -> Callable[..., F]:
     return wrapper
 
 
+@deprecated(
+    version="3.0.0",
+    remove="Still under investigation, see #258.",
+    category=PendingDeprecationWarning,
+)
+def compare(ver1: str, ver2: str) -> int:
+    """
+    Compare two versions strings.
+
+    :param ver1: first version string
+    :param ver2: second version string
+    :return: The return value is negative if ver1 < ver2,
+             zero if ver1 == ver2 and strictly positive if ver1 > ver2
+
+    >>> semver.compare("1.0.0", "2.0.0")
+    -1
+    >>> semver.compare("2.0.0", "1.0.0")
+    1
+    >>> semver.compare("2.0.0", "2.0.0")
+    0
+    """
+    return Version.parse(ver1).compare(ver2)
+
+
 @deprecated(version="2.10.0")
 def parse(version):
     """
@@ -126,28 +163,6 @@ def parse_version_info(version):
     return Version.parse(version)
 
 
-@deprecated(version="2.10.0")
-def compare(ver1, ver2):
-    """
-    Compare two versions strings.
-
-    :param ver1: version string 1
-    :param ver2: version string 2
-    :return: The return value is negative if ver1 < ver2,
-             zero if ver1 == ver2 and strictly positive if ver1 > ver2
-    :rtype: int
-
-    >>> semver.compare("1.0.0", "2.0.0")
-    -1
-    >>> semver.compare("2.0.0", "1.0.0")
-    1
-    >>> semver.compare("2.0.0", "2.0.0")
-    0
-    """
-    v1 = Version.parse(ver1)
-    return v1.compare(ver2)
-
-
 @deprecated(version="2.10.0")
 def match(version, match_expr):
     """
@@ -374,10 +389,16 @@ def replace(version, **parts):
 
 
 # CLI
-cmd_bump = deprecated(cli.cmd_bump, "semver.cli.cmd_bump", "3.0.0")
-cmd_check = deprecated(cli.cmd_check, "semver.cli.cmd_check", "3.0.0")
-cmd_compare = deprecated(cli.cmd_compare, "semver.cli.cmd_compare", "3.0.0")
-cmd_nextver = deprecated(cli.cmd_nextver, "semver.cli.cmd_nextver", "3.0.0")
-createparser = deprecated(cli.createparser, "semver.cli.createparser", "3.0.0")
-process = deprecated(cli.process, "semver.cli.process", "3.0.0")
-main = deprecated(cli.main, "semver.cli.main", "3.0.0")
+cmd_bump = deprecated(cli.cmd_bump, replace="semver.cli.cmd_bump", version="3.0.0")
+cmd_check = deprecated(cli.cmd_check, replace="semver.cli.cmd_check", version="3.0.0")
+cmd_compare = deprecated(
+    cli.cmd_compare, replace="semver.cli.cmd_compare", version="3.0.0"
+)
+cmd_nextver = deprecated(
+    cli.cmd_nextver, replace="semver.cli.cmd_nextver", version="3.0.0"
+)
+createparser = deprecated(
+    cli.createparser, replace="semver.cli.createparser", version="3.0.0"
+)
+process = deprecated(cli.process, replace="semver.cli.process", version="3.0.0")
+main = deprecated(cli.main, replace="semver.cli.main", version="3.0.0")

tests/test_deprecated_functions.py

@@ -5,7 +5,6 @@
 from semver import (
     parse,
     parse_version_info,
-    compare,
     match,
     max_ver,
     min_ver,
@@ -36,7 +35,6 @@
         (bump_minor, ("1.2.3",), {}),
         (bump_patch, ("1.2.3",), {}),
         (bump_prerelease, ("1.2.3",), {}),
-        (compare, ("1.2.1", "1.2.2"), {}),
         (format_version, (3, 4, 5), {}),
         (finalize_version, ("1.2.3-rc.5",), {}),
         (match, ("1.0.0", ">=1.0.0"), {}),