pycmdcheck 0.1.0__py3-none-any.whl

pycmdcheck/discovery.py

@@ -0,0 +1,127 @@
+"""Plugin discovery via entry points.
+
+This module provides functionality to discover and load check plugins
+registered via Python entry points. Third-party packages can register
+custom checks by adding entries to the ``pycmdcheck.checks`` entry point
+group in their pyproject.toml.
+
+Example entry point registration in pyproject.toml:
+
+    [project.entry-points."pycmdcheck.checks"]
+    my_check = "my_package.checks:MyCheck"
+"""
+
+import functools
+import logging
+from importlib.metadata import entry_points
+from typing import TYPE_CHECKING
+
+logger = logging.getLogger(__name__)
+
+if TYPE_CHECKING:
+    from pycmdcheck.checks.base import Check
+
+ENTRY_POINT_GROUP = "pycmdcheck.checks"
+"""Entry point group name for check plugins."""
+
+
+@functools.lru_cache(maxsize=1)
+def discover_checks() -> dict[str, type["Check"]]:
+    """Discover all registered checks via entry points.
+
+    Scans the ``pycmdcheck.checks`` entry point group and loads all
+    registered check classes. Built-in checks are registered in the
+    package's pyproject.toml, and third-party packages can register
+    additional checks.
+
+    If a check fails to load (e.g., due to an import error), a
+    UserWarning is issued but discovery continues with other checks.
+
+    Returns:
+        A dictionary mapping check names (strings) to check classes.
+        The check classes implement the Check protocol from
+        pycmdcheck.checks.base.
+
+    Examples:
+        Discover all available checks:
+
+        >>> checks = discover_checks()
+        >>> "metadata" in checks
+        True
+        >>> "tests" in checks
+        True
+
+        Get a specific check class:
+
+        >>> checks = discover_checks()
+        >>> MetadataCheck = checks["metadata"]
+        >>> instance = MetadataCheck()
+        >>> instance.name
+        'metadata'
+    """
+    checks: dict[str, type[Check]] = {}
+
+    eps = entry_points(group=ENTRY_POINT_GROUP)
+    for ep in eps:
+        try:
+            check_class = ep.load()
+            checks[ep.name] = check_class
+        except (ImportError, AttributeError, TypeError) as e:
+            # Log warning but continue with other checks
+            logger.warning(
+                "Failed to load check '%s' from %s: %s",
+                ep.name,
+                ep.value,
+                e,
+            )
+
+    logger.debug("Discovered %d checks: %s", len(checks), ", ".join(sorted(checks)))
+    return checks
+
+
+def list_available_checks() -> list[tuple[str, str]]:
+    """List all available checks with their descriptions.
+
+    Discovers all registered checks and returns their names and
+    descriptions in a format suitable for display (e.g., in CLI help).
+    Results are sorted alphabetically by check name.
+
+    Returns:
+        A list of (name, description) tuples, sorted alphabetically
+        by name. Each tuple contains:
+
+        - name: The check's unique identifier (str)
+        - description: Human-readable description of what the check does (str)
+
+        If a check's description cannot be retrieved, "No description
+        available" is used as a fallback.
+
+    Examples:
+        List all checks for display:
+
+        >>> checks = list_available_checks()
+        >>> len(checks) > 0
+        True
+        >>> name, description = checks[0]
+        >>> isinstance(name, str) and isinstance(description, str)
+        True
+
+        Display in CLI:
+
+        >>> for name, desc in list_available_checks():
+        ...     print(f"  {name}: {desc}")  # doctest: +SKIP
+          docs: Check documentation presence
+          imports: Check that package imports work
+          ...
+    """
+    checks = discover_checks()
+    result: list[tuple[str, str]] = []
+
+    for name, check_class in sorted(checks.items()):
+        try:
+            description = getattr(check_class, "description", "No description")
+            result.append((name, description))
+        except (AttributeError, TypeError):
+            result.append((name, "No description available"))
+
+    return result

pycmdcheck/package_layout.py

@@ -0,0 +1,234 @@
+"""Shared utility for discovering Python package layout and files.
+
+This module provides the :class:`PackageLayout` class, which consolidates
+all package/directory discovery logic into a single, reusable component.
+It replaces duplicated ``_find_package_dir``, ``_get_local_packages``, and
+hardcoded exclusion sets that were previously scattered across check modules.
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+# ── Shared exclusion sets ─────────────────────────────────────────────
+
+EXCLUDED_DIRS: frozenset[str] = frozenset(
+    {
+        "venv",
+        ".venv",
+        "env",
+        ".env",
+        "build",
+        "dist",
+        ".git",
+        "__pycache__",
+        ".tox",
+        ".nox",
+        ".mypy_cache",
+        ".pytest_cache",
+        ".ruff_cache",
+        "node_modules",
+        ".eggs",
+    }
+)
+"""Directories that should always be skipped when walking a project tree."""
+
+NON_PACKAGE_DIRS: frozenset[str] = frozenset(
+    {
+        "tests",
+        "test",
+        "docs",
+        "doc",
+        "build",
+        "dist",
+        "venv",
+        ".venv",
+    }
+)
+"""Top-level directories that are never real packages in a flat layout."""
+
+NON_MODULE_FILES: frozenset[str] = frozenset(
+    {
+        "setup.py",
+        "conftest.py",
+        "noxfile.py",
+        "tasks.py",
+        "manage.py",
+        "versioneer.py",
+        "__init__.py",
+        "__main__.py",
+    }
+)
+"""Top-level ``.py`` files that are tooling/scripts, not the package module."""
+
+
+class PackageLayout:
+    """Discover and expose the layout of a Python project.
+
+    Supports both *src/* layout and flat layout.  Filesystem scanning is
+    deferred until the first property access (lazy discovery).
+
+    Args:
+        project_root: Path to the project root (the directory containing
+            ``pyproject.toml`` or equivalent).
+        package_name: Optional hint for the primary package name.  When
+            given, it is used to select :attr:`primary_package` from the
+            discovered packages.
+    """
+
+    def __init__(
+        self,
+        project_root: Path,
+        *,
+        package_name: str | None = None,
+    ) -> None:
+        self._root = project_root
+        self._package_name = package_name
+
+        # Lazily populated by ``_discover()``
+        self._is_src_layout: bool | None = None
+        self._package_dirs: list[Path] | None = None
+
+    # ── Public properties ─────────────────────────────────────────────
+
+    @property
+    def is_src_layout(self) -> bool:
+        """Return ``True`` if the project uses a ``src/`` layout."""
+        if self._is_src_layout is None:
+            self._discover()
+        assert self._is_src_layout is not None
+        return self._is_src_layout
+
+    @property
+    def package_dirs(self) -> list[Path]:
+        """Return all package directories that contain ``__init__.py``."""
+        if self._package_dirs is None:
+            self._discover()
+        assert self._package_dirs is not None
+        return list(self._package_dirs)
+
+    @property
+    def primary_package(self) -> Path | None:
+        """Return the main package directory.
+
+        If *package_name* was given at construction time and a matching
+        package exists, that package is returned.  Otherwise the first
+        discovered package is returned (or ``None`` if no packages exist).
+        """
+        dirs = self.package_dirs
+        if not dirs:
+            return None
+
+        if self._package_name:
+            for d in dirs:
+                if d.name == self._package_name:
+                    return d
+
+        return dirs[0]
+
+    # ── Public methods ────────────────────────────────────────────────
+
+    def python_files(self, *, include_tests: bool = False) -> list[Path]:
+        """Return all ``.py`` files inside discovered packages.
+
+        Args:
+            include_tests: When ``False`` (the default), files under
+                directories named ``tests`` or ``test`` are excluded.
+
+        Returns:
+            Sorted list of ``.py`` file paths.
+        """
+        result: list[Path] = []
+        for pkg_dir in self.package_dirs:
+            for py_file in pkg_dir.rglob("*.py"):
+                parts = set(py_file.relative_to(pkg_dir).parts)
+                # Always skip globally excluded dirs
+                if parts & EXCLUDED_DIRS:
+                    continue
+                if not include_tests and parts & {"tests", "test"}:
+                    continue
+                result.append(py_file)
+
+        # Also filter based on the full path parts (catches excluded dirs
+        # that sit *above* the package dir, e.g. a .venv ancestor).
+        result = [
+            f for f in result if not any(part in EXCLUDED_DIRS for part in f.parts)
+        ]
+        return sorted(result)
+
+    def local_package_names(self) -> set[str]:
+        """Return the names of all discovered local packages."""
+        return {d.name for d in self.package_dirs}
+
+    @property
+    def import_root(self) -> Path:
+        """Return the directory imports resolve from (``src/`` or the root)."""
+        if self._is_src_layout is None:
+            self._discover()
+        src_dir = self._root / "src"
+        return src_dir if (self._is_src_layout and src_dir.is_dir()) else self._root
+
+    def top_level_modules(self) -> list[Path]:
+        """Return single-file top-level modules at the import root.
+
+        Finds ``.py`` files directly under the import root (``src/`` for a
+        src-layout, otherwise the project root) that represent the package
+        itself — e.g. a single-module package ``foo.py`` — excluding common
+        tooling scripts (``setup.py``, ``conftest.py``, …). Used to support
+        single-module packages that have no package directory / ``__init__.py``.
+        """
+        base = self.import_root
+        if not base.is_dir():
+            return []
+        modules: list[Path] = []
+        for item in sorted(base.iterdir()):
+            if (
+                item.is_file()
+                and item.suffix == ".py"
+                and item.name not in NON_MODULE_FILES
+                and not item.name.startswith(".")
+            ):
+                modules.append(item)
+        return modules
+
+    # ── Internal discovery ────────────────────────────────────────────
+
+    def _discover(self) -> None:
+        """Scan the filesystem and populate internal caches."""
+        logger.debug("Discovering package layout under %s", self._root)
+
+        dirs: list[Path] = []
+        src_dir = self._root / "src"
+
+        if src_dir.is_dir():
+            self._is_src_layout = True
+            logger.debug("Detected src/ layout")
+            for item in sorted(src_dir.iterdir()):
+                if (
+                    item.is_dir()
+                    and not item.name.startswith((".", "_"))
+                    and (item / "__init__.py").exists()
+                ):
+                    logger.debug("  Found src-layout package: %s", item.name)
+                    dirs.append(item)
+        else:
+            self._is_src_layout = False
+            logger.debug("No src/ directory; checking flat layout")
+            for item in sorted(self._root.iterdir()):
+                if (
+                    item.is_dir()
+                    and item.name not in NON_PACKAGE_DIRS
+                    and not item.name.startswith(".")
+                    and (item / "__init__.py").exists()
+                ):
+                    logger.debug("  Found flat-layout package: %s", item.name)
+                    dirs.append(item)
+
+        self._package_dirs = dirs
+        logger.debug(
+            "Discovery complete: %d package(s) found",
+            len(self._package_dirs),
+        )

pycmdcheck/profiles.py

@@ -0,0 +1,158 @@
+"""Check profiles for pycmdcheck.
+
+Profiles define named sets of checks and configuration overrides
+for common use cases like pyOpenSci onboarding or strict quality gates.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+# All checks that ship with pycmdcheck
+ALL_CHECKS: frozenset[str] = frozenset(
+    {
+        "metadata",
+        "structure",
+        "tests",
+        "linting",
+        "typing",
+        "imports",
+        "license",
+        "docs",
+        "dependencies",
+        "build",
+        "formatting",
+        "version",
+        "py_typed",
+        # New checks
+        "community",
+        "ci",
+        "changelog",
+        "citation",
+        "python_versions",
+        "urls",
+        "doctests",
+    }
+)
+
+# Original 13 checks (pre-pyOpenSci)
+ORIGINAL_CHECKS: frozenset[str] = frozenset(
+    {
+        "metadata",
+        "structure",
+        "tests",
+        "linting",
+        "typing",
+        "imports",
+        "license",
+        "docs",
+        "dependencies",
+        "build",
+        "formatting",
+        "version",
+        "py_typed",
+    }
+)
+
+# Checks that require installing the package, running external tools
+# (pytest/ruff/mypy), or network access. These produce false results when run
+# against an arbitrary repository that has NOT been installed (e.g. a CI triage
+# bot), so they are excluded from the static-only "triage" profile.
+DYNAMIC_CHECKS: frozenset[str] = frozenset(
+    {
+        "tests",  # runs pytest
+        "imports",  # resolves imports against the running interpreter
+        "dependencies",  # resolves imports against the installed environment
+        "build",  # builds the package
+        "linting",  # runs ruff/flake8
+        "typing",  # runs mypy/pyright
+        "formatting",  # runs ruff/black
+        "doctests",  # runs pytest --doctest
+        "urls",  # validates links over the network
+    }
+)
+
+# Static, no-install, no-network checks — safe to run against an arbitrary
+# submitted repository without building or installing it.
+STATIC_CHECKS: frozenset[str] = ALL_CHECKS - DYNAMIC_CHECKS
+
+
+@dataclass(frozen=True)
+class Profile:
+    """A named profile defining which checks to run and configuration."""
+
+    name: str
+    description: str
+    checks: frozenset[str]
+    config_overrides: dict[str, dict[str, Any]] = field(default_factory=dict)
+
+
+PROFILES: dict[str, Profile] = {
+    "minimal": Profile(
+        name="minimal",
+        description="Quick sanity checks (metadata, structure, license)",
+        checks=frozenset({"metadata", "structure", "license"}),
+    ),
+    "triage": Profile(
+        name="triage",
+        description=(
+            "Static packaging/docs checks only — no install, external tools, "
+            "or network (for CI triage of arbitrary repositories)"
+        ),
+        checks=STATIC_CHECKS,
+        config_overrides={
+            "docs": {
+                "require_readme": True,
+                "check_readme_sections": True,
+            },
+        },
+    ),
+    "default": Profile(
+        name="default",
+        description="Standard checks (original 13 built-in checks)",
+        checks=ORIGINAL_CHECKS,
+    ),
+    "pyopensci": Profile(
+        name="pyopensci",
+        description="pyOpenSci onboarding requirements",
+        checks=ALL_CHECKS,
+        config_overrides={
+            "docs": {
+                "require_readme": True,
+                "check_docstrings": True,
+                "check_readme_sections": True,
+            },
+        },
+    ),
+    "strict": Profile(
+        name="strict",
+        description="All checks at maximum strictness",
+        checks=ALL_CHECKS,
+        config_overrides={
+            "docs": {
+                "require_readme": True,
+                "check_docstrings": True,
+                "check_readme_sections": True,
+            },
+            "typing": {"strict": True},
+        },
+    ),
+}
+
+
+def get_profile(name: str) -> Profile | None:
+    """Look up a profile by name.
+
+    Args:
+        name: Profile name (minimal, default, pyopensci, strict).
+
+    Returns:
+        The Profile, or None if not found.
+    """
+    return PROFILES.get(name)
+
+
+def list_profiles() -> list[tuple[str, str]]:
+    """Return all profiles as (name, description) pairs."""
+    return [(p.name, p.description) for p in PROFILES.values()]