Mark semver.compare as PendingDeprecationWarning

It's still unclear if we should deprecate this function or not.
As we don't have a uniform initializer yet, this function stays
in _deprecated.py and decorated with PendingDeprecationWarning.

See python-semver#258 for details

src/semver/__init__.py

@@ -9,6 +9,7 @@
     bump_major,
     bump_minor,
     bump_patch,
+    compare,
     bump_prerelease,
     finalize_version,
     format_version,
@@ -26,7 +27,7 @@
     process,
     main,
 )
-from .version import compare, Version, VersionInfo
+from .version import Version, VersionInfo
 from .__about__ import (
     __version__,
     __author__,

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):
     """
@@ -352,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")

src/semver/version.py

@@ -57,26 +57,6 @@ def _cmp(a, b):  # TODO: type hints
     return (a > b) - (a < b)
 
 
-#: An abbreviated function
-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)
-
-
 class Version:
     """
     A semver compatible version class.