♻️ refactor(tests): stop importing private modules directly

Use from-imports and mocker.patch string paths instead of importing
private modules as objects for monkeypatching.

Author: gaborbernat

docs/conf.py

@@ -1,3 +1,5 @@
+"""Sphinx configuration for py-discovery documentation."""
+
 from __future__ import annotations
 
 from datetime import datetime, timezone

pyproject.toml

@@ -74,51 +74,40 @@ lint.select = [
   "ALL",
 ]
 lint.ignore = [
-  "ANN001",  # Missing type annotation for function argument
-  "ANN002",  # Missing type annotation for *args
-  "ANN202",  # Missing return type annotation for private function
-  "ANN204",  # Missing return type annotation for special method
-  "ANN205",  # Missing return type annotation for staticmethod
-  "ANN206",  # Missing return type annotation for classmethod
-  "ANN401",  # Dynamically typed expressions (typing.Any)
-  "ARG001",  # Unused function argument
-  "ARG005",  # Unused lambda argument
-  "B905",    # zip-without-explicit-strict (conflicts with ty on 3.8)
-  "C901",    # Too complex
-  "COM812",  # Conflict with formatter
-  "CPY",     # No copyright statements
-  "D",       # Docstring rules
-  "DOC",     # Docstring content rules
-  "E501",    # Line too long (formatter handles it)
-  "FBT",     # Boolean positional arguments
-  "INP001",  # Implicit namespace package
-  "ISC001",  # Conflict with formatter
-  "PLC0415", # import at top level
-  "PLR0904", # Too many public methods
-  "PLR0911", # Too many return statements
-  "PLR0912", # Too many branches
-  "PLR0913", # Too many arguments
-  "PLR0914", # Too many local variables
-  "PLR0915", # Too many statements
-  "PLR0917", # Too many positional arguments
-  "PLR1702", # Too many nested blocks
-  "PLR2004", # Magic value used in comparison
-  "PLR6301", # Method could be a function
-  "PTH",     # Use pathlib (existing code uses os.path)
-  "PYI024",  # Use `typing.NamedTuple` instead of `collections.namedtuple`
-  "RUF067",  # __init__ module should only contain re-exports
-  "S104",    # Possible binding to all interface
-  "S404",    # subprocess module is possibly insecure
-  "S603",    # `subprocess` call: check for execution of untrusted input
-  "SLF001",  # Private member accessed
-  "TID252",  # Prefer absolute imports over relative (internal package uses relative)
-  "TRY301",  # Abstract `raise` to an inner function
+  "COM812", # Conflict with formatter
+  "CPY",    # No copyright statements
+  "D203",   # `one-blank-line-before-class` and `no-blank-line-before-class` are incompatible
+  "D212",   # `multi-line-summary-first-line` and `multi-line-summary-second-line` are incompatible
+  "DOC201", # `return` is not documented in docstring
+  "DOC402", # `yield` is not documented in docstring
+  "DOC501", # `raises` is not documented in docstring
+  "ISC001", # Conflict with formatter
+  "S104",   # Possible binding to all interface
+]
+lint.per-file-ignores."docs/**/*.py" = [
+  "INP001", # no __init__.py in docs directory
+]
+lint.per-file-ignores."src/py_discovery/_discovery.py" = [
+  "PTH", # shim resolution uses string-based os.path for consistency with env variables
+]
+lint.per-file-ignores."src/py_discovery/_py_info.py" = [
+  "PTH", # must use os.path — file runs as subprocess script with only stdlib
+]
+lint.per-file-ignores."src/py_discovery/_windows/_pep514.py" = [
+  "PTH", # os.path.exists is monkeypatched in tests; pathlib.Path.exists bypasses the mock
 ]
 lint.per-file-ignores."tests/**/*.py" = [
+  "D",       # don't care about documentation in tests
+  "FBT",     # don't care about booleans as positional arguments in tests
   "INP001",  # no implicit namespace
-  "PLC2701", # Private imports
+  "PLC0415", # imports inside test functions (conditional on mocking)
+  "PLC2701", # private imports needed to test internal APIs
+  "PLR0913", # too many arguments (pytest fixtures)
+  "PLR2004", # Magic value used in comparison
   "S101",    # asserts allowed in tests
-  "S102",    # use of exec
+  "S404",    # subprocess import
+  "S603",    # `subprocess` call: check for execution of untrusted input
+  "SLF001",  # private member access needed to test internals
 ]
 lint.per-file-ignores."tests/windows/winreg_mock_values.py" = [
   "F821", # undefined name (winreg available only on Windows)
@@ -173,5 +162,15 @@ paths.source = [
 src.exclude = [ "tests/windows/winreg_mock_values.py" ]
 
 [[tool.ty.overrides]]
-include = [ "src/py_discovery/_py_info.py", "tests/test_py_info_extra.py" ]
+include = [ "src/py_discovery/_py_info.py", "src/py_discovery/_py_spec.py" ]
+rules.unused-ignore-comment = "ignore"
+rules.invalid-argument-type = "ignore"
+rules.invalid-return-type = "ignore"
+rules.no-matching-overload = "ignore"
+
+[[tool.ty.overrides]]
+include = [ "tests/**/*.py" ]
 rules.unused-ignore-comment = "ignore"
+rules.invalid-argument-type = "ignore"
+rules.no-matching-overload = "ignore"
+rules.unresolved-attribute = "ignore"

src/py_discovery/_cache.py

@@ -6,13 +6,13 @@
 import logging
 from contextlib import contextmanager, suppress
 from hashlib import sha256
-from typing import TYPE_CHECKING, Protocol, runtime_checkable
+from typing import TYPE_CHECKING, Final, Protocol, runtime_checkable
 
 if TYPE_CHECKING:
     from collections.abc import Generator
     from pathlib import Path
 
-LOGGER = logging.getLogger(__name__)
+_LOGGER: Final[logging.Logger] = logging.getLogger(__name__)
 
 
 @runtime_checkable
@@ -61,9 +61,9 @@ def read(self) -> dict | None:
         except ValueError:
             bad_format = True
         except OSError:
-            LOGGER.debug("failed to read %s", self._file, exc_info=True)
+            _LOGGER.debug("failed to read %s", self._file, exc_info=True)
         else:
-            LOGGER.debug("got python info from %s", self._file)
+            _LOGGER.debug("got python info from %s", self._file)
             return data
         if bad_format:
             with suppress(OSError):
@@ -73,16 +73,16 @@ def read(self) -> dict | None:
     def write(self, content: dict) -> None:
         self._folder.mkdir(parents=True, exist_ok=True)
         self._file.write_text(json.dumps(content, sort_keys=True, indent=2), encoding="utf-8")
-        LOGGER.debug("wrote python info at %s", self._file)
+        _LOGGER.debug("wrote python info at %s", self._file)
 
     def remove(self) -> None:
         with suppress(OSError):
             self._file.unlink()
-        LOGGER.debug("removed python info at %s", self._file)
+        _LOGGER.debug("removed python info at %s", self._file)
 
     @contextmanager
     def locked(self) -> Generator[None]:
-        from filelock import FileLock
+        from filelock import FileLock  # noqa: PLC0415
 
         lock_path = self._folder / f"{self._key}.lock"
         lock_path.parent.mkdir(parents=True, exist_ok=True)
@@ -91,11 +91,7 @@ def locked(self) -> Generator[None]:
 
 
 class DiskCache:
-    """File-system based Python interpreter info cache.
-
-    Layout: ``<root>/py_info/4/<sha256(str(path))>.json`` -- identical to virtualenv's ``AppDataDiskFolder``.
-
-    """
+    """File-system based Python interpreter info cache (``<root>/py_info/4/<sha256>.json``)."""
 
     def __init__(self, root: Path) -> None:
         self._root = root
@@ -111,19 +107,19 @@ def py_info(self, path: Path) -> DiskContentStore:
     def py_info_clear(self) -> None:
         folder = self._py_info_dir
         if folder.exists():
-            for f in folder.iterdir():
-                if f.suffix == ".json":
+            for entry in folder.iterdir():
+                if entry.suffix == ".json":
                     with suppress(OSError):
-                        f.unlink()
+                        entry.unlink()
 
 
-class NoOpContentStore:
-    """Content store that does nothing."""
+class NoOpContentStore(ContentStore):
+    """Content store that does nothing -- implements ContentStore protocol."""
 
-    def exists(self) -> bool:
+    def exists(self) -> bool:  # noqa: PLR6301
         return False
 
-    def read(self) -> dict | None:
+    def read(self) -> dict | None:  # noqa: PLR6301
         return None
 
     def write(self, content: dict) -> None:
@@ -133,14 +129,14 @@ def remove(self) -> None:
         pass
 
     @contextmanager
-    def locked(self) -> Generator[None]:
+    def locked(self) -> Generator[None]:  # noqa: PLR6301
         yield
 
 
-class NoOpCache:
-    """Cache that does nothing -- used when caching is disabled."""
+class NoOpCache(PyInfoCache):
+    """Cache that does nothing -- implements PyInfoCache protocol."""
 
-    def py_info(self, _path: Path) -> NoOpContentStore:
+    def py_info(self, path: Path) -> NoOpContentStore:  # noqa: ARG002, PLR6301
         return NoOpContentStore()
 
     def py_info_clear(self) -> None: