pycmdcheck 0.1.0__py3-none-any.whl

pycmdcheck/checks/py_typed.py

@@ -0,0 +1,207 @@
+"""PEP 561 py.typed marker check.
+
+This module provides the PyTypedCheck class which verifies that packages
+using type annotations include a ``py.typed`` marker file as required by
+PEP 561 for downstream type checkers to recognise the package as typed.
+"""
+
+import ast
+import logging
+from pathlib import Path
+from typing import Any
+
+from pycmdcheck.ast_cache import parse_file
+from pycmdcheck.checks.base import BaseCheck
+from pycmdcheck.constants import MAX_TYPE_SCAN_FILES
+from pycmdcheck.package_layout import PackageLayout
+from pycmdcheck.results import CheckResult, CheckStatus
+
+logger = logging.getLogger(__name__)
+
+
+class PyTypedCheck(BaseCheck):
+    """Check for PEP 561 ``py.typed`` marker file.
+
+    Scans the package source for type annotation usage and verifies
+    that a ``py.typed`` marker file exists in the package directory.
+    If annotations are found but the marker is missing, downstream
+    type checkers (mypy, pyright) will not recognise the package as
+    typed.
+
+    Attributes:
+        name: The check identifier (``"py_typed"``).
+        description: Human-readable description of this check.
+
+    Examples:
+        Run the py.typed check:
+
+        >>> from pathlib import Path
+        >>> check = PyTypedCheck()
+        >>> result = check.run(Path("."), {"enabled": True})
+        >>> result.name
+        'py_typed'
+    """
+
+    name = "py_typed"
+    description = "Check for PEP 561 py.typed marker"
+
+    def run(self, package_path: Path, config: dict[str, Any]) -> CheckResult:
+        """Check for py.typed marker in typed packages.
+
+        Locates the main package directory, determines whether type
+        annotations are used, and checks for the ``py.typed`` marker.
+
+        Args:
+            package_path: Path to the package directory to check.
+            config: Configuration dictionary for this check. Currently
+                no check-specific options are used.
+
+        Returns:
+            A CheckResult with:
+
+            - OK status if ``py.typed`` is present
+            - NOTE status if types are used but no ``py.typed`` marker
+            - OK status if no type annotations detected (marker not needed)
+            - NOTE status if no package directory found
+        """
+        details: list[str] = []
+
+        # Locate the package directory (the one with __init__.py)
+        package_dir = PackageLayout(package_path).primary_package
+        if package_dir is None:
+            return CheckResult(
+                name=self.name,
+                status=CheckStatus.NOTE,
+                message="No package directory found",
+                details=["Could not locate a package with __init__.py"],
+            )
+
+        details.append(f"Package directory: {package_dir.relative_to(package_path)}")
+
+        py_typed_path = package_dir / "py.typed"
+        has_marker = py_typed_path.exists()
+
+        if has_marker:
+            details.append("py.typed marker file present")
+
+        # Scan for type annotation usage
+        uses_types = self._package_uses_types(package_dir)
+
+        if has_marker and uses_types:
+            details.append("Package uses type annotations")
+            return CheckResult(
+                name=self.name,
+                status=CheckStatus.OK,
+                message="py.typed marker present in typed package",
+                details=details,
+            )
+
+        if has_marker and not uses_types:
+            details.append("No type annotations detected (marker still valid)")
+            return CheckResult(
+                name=self.name,
+                status=CheckStatus.OK,
+                message="py.typed marker present",
+                details=details,
+            )
+
+        if uses_types and not has_marker:
+            details.append("Package uses type annotations but has no py.typed marker")
+            details.append(
+                f"Add an empty file: {py_typed_path.relative_to(package_path)}"
+            )
+            return CheckResult(
+                name=self.name,
+                status=CheckStatus.NOTE,
+                message="Missing py.typed marker for typed package",
+                details=details,
+            )
+
+        # No types used, no marker -- nothing to do
+        details.append("No type annotations detected; py.typed not required")
+        return CheckResult(
+            name=self.name,
+            status=CheckStatus.OK,
+            message="py.typed not needed (no type annotations found)",
+            details=details,
+        )
+
+    # ------------------------------------------------------------------
+    # Private helpers
+    # ------------------------------------------------------------------
+
+    def _package_uses_types(self, package_dir: Path) -> bool:
+        """Determine whether the package uses type annotations.
+
+        Scans Python files for function/method parameter annotations,
+        return annotations, and variable annotations. Only the first
+        20 files are checked for performance.
+
+        Args:
+            package_dir: Path to the package directory.
+
+        Returns:
+            True if any type annotation usage is detected.
+        """
+        py_files = list(package_dir.rglob("*.py"))
+        # Exclude __pycache__
+        py_files = [f for f in py_files if "__pycache__" not in f.parts]
+
+        for py_file in py_files[:MAX_TYPE_SCAN_FILES]:
+            try:
+                if self._file_uses_types(py_file):
+                    return True
+            except (OSError, UnicodeDecodeError) as exc:
+                logger.debug("Could not check %s for types: %s", py_file, exc)
+                continue
+
+        return False
+
+    def _file_uses_types(self, py_file: Path) -> bool:
+        """Check if a single Python file uses type annotations.
+
+        Looks for:
+        - Function parameter annotations (``def f(x: int)``)
+        - Return annotations (``def f() -> str``)
+        - Variable annotations (``x: int = 1``)
+        - Imports from ``typing`` or ``typing_extensions``
+
+        Args:
+            py_file: Path to a ``.py`` file.
+
+        Returns:
+            True if any annotation usage is found.
+        """
+        tree = parse_file(py_file)
+        if tree is None:
+            return False
+
+        for node in ast.walk(tree):
+            # Check for function annotations
+            if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                # Return annotation
+                if node.returns is not None:
+                    return True
+                # Parameter annotations
+                all_args = node.args.posonlyargs + node.args.args + node.args.kwonlyargs
+                for arg in all_args:
+                    if arg.annotation is not None:
+                        return True
+                if node.args.vararg and node.args.vararg.annotation is not None:
+                    return True
+                if node.args.kwarg and node.args.kwarg.annotation is not None:
+                    return True
+
+            # Check for variable annotations
+            elif isinstance(node, ast.AnnAssign):
+                return True
+
+            # Check for typing imports
+            elif isinstance(node, ast.ImportFrom):
+                if node.module and node.module.split(".")[0] in (
+                    "typing",
+                    "typing_extensions",
+                ):
+                    return True
+
+        return False

pycmdcheck/checks/python_versions.py

@@ -0,0 +1,188 @@
+"""Python version support check.
+
+Verifies that a package's ``requires-python`` specifier excludes
+end-of-life Python versions.
+"""
+
+import configparser
+import datetime
+import re
+from pathlib import Path
+from typing import Any
+
+from pycmdcheck.checks.base import BaseCheck
+from pycmdcheck.constants import PYTHON_EOL_VERSIONS
+from pycmdcheck.pyproject_reader import get_effective_project_table, read_pyproject
+from pycmdcheck.results import CheckResult, CheckStatus
+
+
+class PythonVersionsCheck(BaseCheck):
+    """Check that requires-python excludes end-of-life Python versions.
+
+    Parses the ``requires-python`` field from pyproject.toml and checks
+    whether it allows any Python versions that have reached end-of-life.
+
+    Attributes:
+        name: The check identifier ("python_versions").
+        description: Human-readable description of this check.
+    """
+
+    name = "python_versions"
+    description = "Check Python version support (EOL versions)"
+
+    def run(self, package_path: Path, config: dict[str, Any]) -> CheckResult:
+        """Check requires-python against EOL versions.
+
+        Args:
+            package_path: Path to the package directory to check.
+            config: Configuration dictionary for this check.
+
+        Returns:
+            A CheckResult with:
+
+            - OK status if requires-python excludes all EOL versions
+            - NOTE status if requires-python allows EOL versions
+            - WARNING status if no requires-python specified
+            - NOTE status if no pyproject.toml found
+        """
+        details: list[str] = []
+
+        # Resolve a Python constraint from any declared source: PEP 621
+        # [project], legacy Poetry [tool.poetry.dependencies].python, or
+        # setup.cfg [options] python_requires.
+        requires_python = self._get_requires_python(package_path)
+
+        if not requires_python:
+            no_pyproject = read_pyproject(package_path) is None
+            no_setup_cfg = not (package_path / "setup.cfg").exists()
+            if no_pyproject and no_setup_cfg:
+                return CheckResult(
+                    name=self.name,
+                    status=CheckStatus.NOTE,
+                    message="No pyproject.toml found",
+                    details=["Cannot check requires-python without pyproject.toml"],
+                )
+            return CheckResult(
+                name=self.name,
+                status=CheckStatus.WARNING,
+                message="No requires-python specified",
+                details=[
+                    "Add requires-python to [project] in pyproject.toml",
+                    'Example: requires-python = ">=3.10"',
+                ],
+            )
+
+        details.append(f"requires-python: {requires_python}")
+
+        # Determine which EOL versions are currently past EOL
+        now = datetime.datetime.now(tz=datetime.timezone.utc)
+        current_date = (now.year, now.month)
+
+        eol_allowed: list[str] = []
+        for version, eol_date in PYTHON_EOL_VERSIONS.items():
+            if eol_date <= current_date:
+                # This version is past EOL — check if requires-python allows it
+                if self._specifier_allows(requires_python, version):
+                    eol_allowed.append(version)
+                    details.append(f"Python {version} is EOL but allowed")
+
+        if eol_allowed:
+            return CheckResult(
+                name=self.name,
+                status=CheckStatus.NOTE,
+                message=(
+                    f"requires-python allows EOL version(s): {', '.join(eol_allowed)}"
+                ),
+                details=details,
+            )
+
+        details.append("All allowed Python versions are supported")
+        return CheckResult(
+            name=self.name,
+            status=CheckStatus.OK,
+            message="Python version requirement is current",
+            details=details,
+        )
+
+    def _get_requires_python(self, package_path: Path) -> str | None:
+        """Return a declared Python constraint from any supported source."""
+        project = get_effective_project_table(package_path)
+        requires_python = project.get("requires-python")
+        if isinstance(requires_python, str) and requires_python.strip():
+            return requires_python
+        return self._setup_cfg_python_requires(package_path)
+
+    @staticmethod
+    def _setup_cfg_python_requires(package_path: Path) -> str | None:
+        """Read ``python_requires`` from ``setup.cfg`` ``[options]`` if present."""
+        setup_cfg = package_path / "setup.cfg"
+        if not setup_cfg.exists():
+            return None
+        parser = configparser.ConfigParser()
+        try:
+            parser.read(setup_cfg, encoding="utf-8")
+        except (OSError, configparser.Error):
+            return None
+        if parser.has_option("options", "python_requires"):
+            value = parser.get("options", "python_requires").strip()
+            return value or None
+        return None
+
+    def _specifier_allows(self, specifier: str, version: str) -> bool:
+        """Check if a PEP 440 specifier allows the given version.
+
+        Prefers the accurate ``packaging`` library (a declared dependency).
+        Falls back to a conservative hand parser only if ``packaging`` is
+        somehow unavailable.
+        """
+        try:
+            from packaging.specifiers import InvalidSpecifier, SpecifierSet
+
+            try:
+                return version in SpecifierSet(specifier, prereleases=True)
+            except InvalidSpecifier:
+                return False
+        except ImportError:
+            return self._fallback_allows(specifier, version)
+
+    def _fallback_allows(self, specifier: str, version: str) -> bool:
+        """Conservative fallback used only when ``packaging`` is missing.
+
+        Handles comma-separated ``>=``, ``>``, ``<=``, ``<``, ``==`` (incl.
+        ``==X.*``), ``!=`` and ``~=`` clauses. Returns ``False`` whenever the
+        specifier cannot be confidently parsed, so an EOL version is never
+        falsely reported as allowed.
+        """
+        target = self._version_tuple(version)
+        clauses = [c.strip() for c in specifier.split(",") if c.strip()]
+        if not clauses:
+            return False
+        for clause in clauses:
+            match = re.match(r"(>=|<=|==|~=|!=|>|<)\s*(\d+(?:\.\d+)*)(\.\*)?$", clause)
+            if not match:
+                return False
+            op, num, wildcard = match.group(1), match.group(2), match.group(3)
+            bound = self._version_tuple(num)
+            if op == ">=" and not target >= bound:
+                return False
+            if op == ">" and not target > bound:
+                return False
+            if op == "<=" and not target <= bound:
+                return False
+            if op == "<" and not target < bound:
+                return False
+            if op == "~=" and not target >= bound:
+                return False
+            if op == "==":
+                if wildcard:
+                    if target[: len(bound)] != bound:
+                        return False
+                elif target != bound:
+                    return False
+            if op == "!=" and target == bound:
+                return False
+        return True
+
+    def _version_tuple(self, version: str) -> tuple[int, ...]:
+        """Convert a version string to a comparable tuple."""
+        return tuple(int(x) for x in version.split("."))

pycmdcheck/checks/structure.py

@@ -0,0 +1,282 @@
+"""Package structure validation check.
+
+This module provides the StructureCheck class which validates that a
+Python package follows standard directory layouts (src layout or flat layout).
+"""
+
+from pathlib import Path
+from typing import Any
+
+from pycmdcheck.checks.base import BaseCheck
+from pycmdcheck.package_layout import NON_PACKAGE_DIRS
+from pycmdcheck.pyproject_reader import read_pyproject
+from pycmdcheck.results import CheckResult, CheckStatus
+
+# Build backends that produce native-extension packages which may have no
+# Python source under src/ (or have it under a different directory).
+NATIVE_BUILD_BACKENDS = (
+    "maturin",
+    "scikit_build",
+    "setuptools_rust",
+    "mesonpy",
+    "meson_python",
+)
+
+
+class StructureCheck(BaseCheck):
+    """Check that package has a valid directory structure.
+
+    Validates that the package follows one of the standard Python
+    package layouts:
+
+    - **src layout**: Package code in ``src/<package_name>/``
+    - **flat layout**: Package code directly in project root
+
+    The check verifies that package directories contain ``__init__.py``
+    files and are properly structured.
+
+    Attributes:
+        name: The check identifier ("structure").
+        description: Human-readable description of this check.
+
+    Examples:
+        Run the structure check:
+
+        >>> from pathlib import Path
+        >>> check = StructureCheck()
+        >>> result = check.run(Path("."), {"enabled": True})
+        >>> result.name
+        'structure'
+
+        Check a package with src layout:
+
+        >>> # For a package with src/mypackage/__init__.py
+        >>> # result.status == CheckStatus.OK
+        >>> # result.details contains "Using src layout"
+    """
+
+    name = "structure"
+    description = "Validate package directory structure"
+
+    def run(self, package_path: Path, config: dict[str, Any]) -> CheckResult:
+        """Check package directory structure.
+
+        Determines the layout type (src or flat) and validates that
+        the package directories are properly formed with ``__init__.py``
+        files.
+
+        Args:
+            package_path: Path to the package directory to check.
+            config: Configuration dictionary for this check. Currently
+                no check-specific options are used.
+
+        Returns:
+            A CheckResult with:
+
+            - OK status if valid src or flat layout found
+            - WARNING status if packages missing ``__init__.py``
+            - ERROR status if no package or module found
+        """
+        details: list[str] = []
+
+        # Check for src layout
+        src_path = package_path / "src"
+        if src_path.is_dir():
+            return self._check_src_layout(package_path, src_path, details)
+
+        # Check for flat layout
+        return self._check_flat_layout(package_path, details)
+
+    def _check_src_layout(
+        self,
+        package_path: Path,
+        src_path: Path,
+        details: list[str],
+    ) -> CheckResult:
+        """Validate src layout structure."""
+        details.append("Using src layout")
+
+        # Find candidate package directories in src/
+        package_dirs = [
+            d
+            for d in src_path.iterdir()
+            if d.is_dir() and not d.name.startswith((".", "_"))
+        ]
+
+        if not package_dirs:
+            return self._handle_no_src_package(package_path, src_path, details)
+
+        # Classify each candidate: regular package, PEP 420 namespace package,
+        # or a directory genuinely missing __init__.py.
+        missing_init: list[str] = []
+        for pkg_dir in package_dirs:
+            if (pkg_dir / "__init__.py").exists():
+                details.append(f"Found package: {pkg_dir.name}")
+            elif self._is_namespace_package(pkg_dir):
+                details.append(f"Found namespace package: {pkg_dir.name}")
+            else:
+                missing_init.append(pkg_dir.name)
+
+        if missing_init:
+            details.append(f"Missing __init__.py in: {', '.join(missing_init)}")
+            return CheckResult(
+                name=self.name,
+                status=CheckStatus.WARNING,
+                message="Some packages missing __init__.py",
+                details=details,
+            )
+
+        return CheckResult(
+            name=self.name,
+            status=CheckStatus.OK,
+            message="Valid src layout structure",
+            details=details,
+        )
+
+    def _handle_no_src_package(
+        self,
+        package_path: Path,
+        src_path: Path,
+        details: list[str],
+    ) -> CheckResult:
+        """Handle a ``src/`` directory with no candidate package subdirectory.
+
+        Covers single-module src layouts (``src/foo.py``) and native-extension
+        packages (maturin/scikit-build/setuptools-rust) whose ``src/`` holds no
+        Python at all — neither should be a hard ERROR.
+        """
+        # Single-module src layout: src/foo.py
+        modules = [f for f in sorted(src_path.glob("*.py")) if f.name != "__init__.py"]
+        if modules:
+            details.append(
+                f"Found single-file modules: {', '.join(m.name for m in modules)}"
+            )
+            return CheckResult(
+                name=self.name,
+                status=CheckStatus.OK,
+                message="Valid single-file module structure",
+                details=details,
+            )
+
+        # Native-extension package (maturin/scikit-build/setuptools-rust): the
+        # Python lives elsewhere (or there is none), so a missing Python package
+        # under src/ is expected, not an error.
+        if self._is_native_backend(package_path):
+            details.append(
+                "No Python package under src/ (native-extension build backend detected)"
+            )
+            return CheckResult(
+                name=self.name,
+                status=CheckStatus.NOTE,
+                message="No Python package in src/ (native-extension layout)",
+                details=details,
+            )
+
+        return CheckResult(
+            name=self.name,
+            status=CheckStatus.ERROR,
+            message="No package directory found in src/",
+            details=details,
+        )
+
+    def _check_flat_layout(
+        self,
+        package_path: Path,
+        details: list[str],
+    ) -> CheckResult:
+        """Validate flat layout structure."""
+        details.append("Using flat layout")
+
+        # Look for package directories (not src/)
+        package_dirs = [
+            d
+            for d in package_path.iterdir()
+            if d.is_dir()
+            and not d.name.startswith((".", "_"))
+            and d.name not in NON_PACKAGE_DIRS
+            and (d / "__init__.py").exists()
+        ]
+
+        if not package_dirs:
+            # Check if there are any .py files at root (single-file module)
+            py_files = list(package_path.glob("*.py"))
+            py_files = [
+                f for f in py_files if f.name not in ("setup.py", "conftest.py")
+            ]
+
+            if py_files:
+                details.append(
+                    f"Found single-file modules: {', '.join(f.name for f in py_files)}"
+                )
+                return CheckResult(
+                    name=self.name,
+                    status=CheckStatus.OK,
+                    message="Valid single-file module structure",
+                    details=details,
+                )
+
+            # PEP 420 namespace package: a top-level dir without __init__.py
+            # that nonetheless contains a nested package/module.
+            namespace_dirs = [
+                d
+                for d in package_path.iterdir()
+                if d.is_dir()
+                and not d.name.startswith((".", "_"))
+                and d.name not in NON_PACKAGE_DIRS
+                and self._is_namespace_package(d)
+            ]
+            if namespace_dirs:
+                details.append(
+                    "Found namespace package(s): "
+                    + ", ".join(d.name for d in namespace_dirs)
+                )
+                return CheckResult(
+                    name=self.name,
+                    status=CheckStatus.OK,
+                    message="Valid namespace package structure",
+                    details=details,
+                )
+
+            return CheckResult(
+                name=self.name,
+                status=CheckStatus.ERROR,
+                message="No package or module found",
+                details=details + ["Consider using src/ layout or adding __init__.py"],
+            )
+
+        for pkg_dir in package_dirs:
+            details.append(f"Found package: {pkg_dir.name}")
+
+        return CheckResult(
+            name=self.name,
+            status=CheckStatus.OK,
+            message="Valid flat layout structure",
+            details=details,
+        )
+
+    @staticmethod
+    def _is_namespace_package(directory: Path) -> bool:
+        """Return whether *directory* is a PEP 420 implicit namespace package.
+
+        A namespace package has no ``__init__.py`` of its own but contains a
+        nested subpackage (a directory with ``__init__.py``) somewhere beneath
+        it. This distinguishes it from a regular package that simply forgot its
+        ``__init__.py``.
+        """
+        if (directory / "__init__.py").exists():
+            return False
+        for nested in directory.rglob("__init__.py"):
+            if nested.parent != directory:
+                return True
+        return False
+
+    @staticmethod
+    def _is_native_backend(package_path: Path) -> bool:
+        """Return whether pyproject.toml declares a native-extension backend."""
+        data = read_pyproject(package_path)
+        if not data:
+            return False
+        backend = data.get("build-system", {}).get("build-backend", "")
+        if not isinstance(backend, str):
+            return False
+        return any(native in backend for native in NATIVE_BUILD_BACKENDS)