fix: deprecate coverage3 and coverage-3.10 entry points

nedbat · nedbat · commit 50fffb06e531 · 2025-12-01T19:20:00.000-05:00
diff --git a/CHANGES.rst b/CHANGES.rst
@@ -23,7 +23,10 @@ upgrading your version of coverage.py.
 Unreleased
 ----------
 
-Nothing yet.
+- Deprecated: when coverage.py is installed, it creates three command entry
+  points: `coverage`, `coverage3`, and `coverage-3.10` (if installed for Python
+  3.10). The second and third of these are not needed and will eventually be
+  removed.
 
 
 .. start-releases
diff --git a/coverage/cmdline.py b/coverage/cmdline.py
@@ -1161,6 +1161,20 @@ def main(argv: list[str] | None = None) -> int | None:
     return status
 
 
+def main_deprecated(argv: list[str] | None = None) -> int | None:
+    """For entry points we'll be getting rid of."""
+    print(
+        textwrap.dedent("""\
+        **
+        ** This entry point is deprecated and will be removed.
+        ** Send me an email if you want to keep this command name working:
+        ** ned@nedbatchelder.com
+        **
+        """)
+    )
+    return main(argv)
+
+
 # Profiling using ox_profile.  Install it from GitHub:
 #   pip install git+https://github.com/emin63/ox_profile.git
 #
diff --git a/doc/commands/index.rst b/doc/commands/index.rst
@@ -9,14 +9,8 @@ Commands
 
 .. highlight:: console
 
-When you install coverage.py, a command-line script called ``coverage`` is
-placed on your path.  To help with multi-version installs, it will also create
-a ``coverage3`` alias, and a ``coverage-X.Y`` alias, depending on the version
-of Python you're using.  For example, when installing on Python 3.10, you will
-be able to use ``coverage``, ``coverage3``, or ``coverage-3.10`` on the command
-line.
-
-Coverage.py has a number of commands:
+When you install coverage.py, a command called ``coverage`` is installed for
+command-line use.  It has a number of commands:
 
 * **run** -- :ref:`Run a Python program and collect execution data <cmd_run>`.
 
diff --git a/setup.py b/setup.py
@@ -116,12 +116,12 @@ def do_make_pth():
         for sp in site.getsitepackages()
     ],
     entry_points={
-        # Install a script as "coverage", and as "coverage3", and as
-        # "coverage-3.7" (or whatever).
         "console_scripts": [
+            # Install a script as "coverage".
             "coverage = coverage.cmdline:main",
-            "coverage%d = coverage.cmdline:main" % sys.version_info[:1],
-            "coverage-%d.%d = coverage.cmdline:main" % sys.version_info[:2],
+            # And as "coverage3", and as "coverage-3.7" (or whatever), but deprecated.
+            "coverage%d = coverage.cmdline:main_deprecated" % sys.version_info[:1],
+            "coverage-%d.%d = coverage.cmdline:main_deprecated" % sys.version_info[:2],
         ],
     },
     extras_require={
diff --git a/tests/test_process.py b/tests/test_process.py
@@ -1206,6 +1206,7 @@ def test_major_version_works(self) -> None:
         # "coverage3" works on py3
         cmd = "coverage%d" % sys.version_info[0]
         out = self.run_command(cmd)
+        assert "deprecated" in out
         assert "Code coverage for Python" in out
 
     def test_wrong_alias_doesnt_work(self) -> None:
@@ -1220,6 +1221,7 @@ def test_specific_alias_works(self) -> None:
         # "coverage-3.9" works on py3.9
         cmd = "coverage-%d.%d" % sys.version_info[:2]
         out = self.run_command(cmd)
+        assert "deprecated" in out
         assert "Code coverage for Python" in out
 
     @pytest.mark.parametrize(
