fix: install .pth files the right way #2100

nedbat · nedbat · commit 3fd5727f21b3 · 2025-12-04T08:28:12.000-05:00
diff --git a/.gitignore b/.gitignore
@@ -49,7 +49,7 @@ doc/sample_html_beta
 
 # Build intermediaries.
 tmp
-zzz_coverage.pth
+a1_coverage.pth
 
 # OS junk
 .DS_Store
diff --git a/CHANGES.rst b/CHANGES.rst
@@ -23,11 +23,16 @@ upgrading your version of coverage.py.
 Unreleased
 ----------
 
+- The .pth file we install was done incorrectly and didn't work when using
+  the source wheel (`py3-none-any`).  This is now fixed. Thanks, `Henry
+  Schreiner <pull 2100_>`_.
+
 - 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.
 
+.. _pull 2100: https://github.com/coveragepy/coveragepy/pull/2100
 
 .. start-releases
 
diff --git a/Makefile b/Makefile
@@ -37,12 +37,12 @@ clean: debug_clean _clean_platform	## Remove artifacts of test execution, instal
 	@rm -f MANIFEST
 	@rm -f .coverage .coverage.* .metacov*
 	@rm -f coverage.xml coverage.json
-	@rm -f .tox/*/lib/*/site-packages/zzz_metacov.pth
+	@rm -f .tox/*/lib/*/site-packages/a0_metacov.pth
 	@rm -f */.coverage */*/.coverage */*/*/.coverage */*/*/*/.coverage */*/*/*/*/.coverage */*/*/*/*/*/.coverage
 	@rm -f tests/covmain.zip tests/zipmods.zip tests/zip1.zip
 	@rm -rf doc/_build doc/_spell doc/sample_html_beta
 	@rm -rf tmp
-	@rm -rf zzz_coverage.pth
+	@rm -rf a1_coverage.pth
 	@rm -rf .*cache */.*cache */*/.*cache */*/*/.*cache .hypothesis
 	@rm -rf tests/actual
 	@-make -C tests/gold/html clean
diff --git a/igor.py b/igor.py
@@ -182,7 +182,7 @@ def run_tests_with_coverage(core, *runner_args):
     # or the sys.path entries aren't created right?
     # There's an entry in "make clean" to get rid of this file.
     pth_dir = sysconfig.get_path("purelib")
-    pth_path = os.path.join(pth_dir, "zzy_metacov.pth")
+    pth_path = os.path.join(pth_dir, "a0_metacov.pth")
     with open(pth_path, "w", encoding="utf-8") as pth_file:
         pth_file.write("import coverage; coverage.process_startup(slug='meta')\n")
 
diff --git a/setup.py b/setup.py
@@ -10,14 +10,16 @@
 import os
 import os.path
 import platform
-import site
 import sys
 import textwrap
+import zipfile
 
+from pathlib import Path
 from typing import Any
 
 from setuptools import Extension, errors, setup
-from setuptools.command.build_ext import build_ext  # pylint: disable=wrong-import-order
+from setuptools.command.build_ext import build_ext
+from setuptools.command.editable_wheel import editable_wheel
 
 
 def get_version_data() -> dict[str, Any]:
@@ -89,6 +91,14 @@ def get_classifiers(version_info: tuple[int, int, int, str, int]) -> list[str]:
     return classifier_list
 
 
+# The names of .pth files matter because they are read in lexicographic order.
+# Editable installs work because of `__editable__*.pth` files, so we need our
+# .pth files to come after those. But we want ours to be earlyish in the
+# sequence, so we start with `a`. The metacov .pth file should come before the
+# coverage .pth file, so we use `a0_metacov.pth` and `a1_coverage.pth`.
+PTH_NAME = "a1_coverage.pth"
+
+
 def make_pth_file() -> None:
     """Make the packaged .pth file used for measuring subprocess coverage."""
 
@@ -100,10 +110,20 @@ def make_pth_file() -> None:
 
     # `import sys` is needed because .pth files are executed only if they start
     # with `import `.
-    with open("zzz_coverage.pth", "w", encoding="utf-8") as pth_file:
+    with open(PTH_NAME, "w", encoding="utf-8") as pth_file:
         pth_file.write(f"import sys; exec({code!r})\n")
 
 
+class EditableWheelWithPth(editable_wheel):  # type: ignore[misc]
+    """Override the editable_wheel command to insert our .pth file into the wheel."""
+
+    def run(self) -> None:
+        super().run()
+        for whl in Path(self.dist_dir).glob("*editable*.whl"):
+            with zipfile.ZipFile(whl, "a") as zf:
+                zf.write(PTH_NAME, PTH_NAME)
+
+
 # A replacement for the build_ext command which raises a single exception
 # if the build fails, so we can fallback nicely.
 
@@ -158,6 +178,7 @@ def build_extension(self, ext: Any) -> None:
 version_data = get_version_data()
 make_pth_file()
 
+
 # Create the keyword arguments for setup()
 
 setup_args = dict(
@@ -170,17 +191,9 @@ def build_extension(self, ext: Any) -> None:
         "coverage": [
             "htmlfiles/*.*",
             "py.typed",
+            f"../{PTH_NAME}",
         ],
     },
-    data_files=[
-        # Write the .pth file into all site-packages directories. Different
-        # platforms read different directories for .pth files, so put it
-        # everywhere.  The process_startup function called in the .pth file
-        # does nothing the second time it's called, so it's fine to have
-        # multiple .pth files.
-        (os.path.relpath(sp, sys.prefix), ["zzz_coverage.pth"])
-        for sp in site.getsitepackages()
-    ],
     entry_points={
         "console_scripts": [
             # Install a script as "coverage".
@@ -196,6 +209,7 @@ def build_extension(self, ext: Any) -> None:
     },
     cmdclass={
         "build_ext": ve_build_ext,
+        "editable_wheel": EditableWheelWithPth,
     },
     # We need to get HTML assets from our htmlfiles directory.
     zip_safe=False,
diff --git a/tox.ini b/tox.ini
@@ -108,7 +108,7 @@ commands =
     python -m cogapp -cP --check --check-fail-msg='run `make workflows`' --verbosity=1 .github/workflows/*.yml
     ruff format --check
     python -m pylint -j 0 --notes= --ignore-paths 'doc/_build/.*' {env:LINTABLE}
-    check-manifest --ignore "doc/sample_html/*,zzz_coverage.pth"
+    check-manifest --ignore "doc/sample_html/*,a1_coverage.pth"
     # If 'build -q' becomes a thing (https://github.com/pypa/build/issues/188),
     # this can be simplified:
     python igor.py quietly "python -m build"
