pycmdcheck 0.1.0__py3-none-any.whl

pycmdcheck/pyproject_reader.py

@@ -0,0 +1,226 @@
+"""Cached pyproject.toml reader utility.
+
+Provides a single, cached entry point for reading ``pyproject.toml`` files.
+This replaces the duplicated TOML-parsing logic that previously lived in
+``config.py``, ``metadata.py``, and ``structure.py``.  The
+:func:`read_pyproject` function is decorated with :func:`functools.lru_cache`
+so each file is read from disk at most once per ``package_path`` per run.
+
+Examples:
+    >>> from pathlib import Path
+    >>> from pycmdcheck.pyproject_reader import read_pyproject, get_project_table
+    >>> data = read_pyproject(Path("."))
+    >>> project = get_project_table(Path("."))
+    >>> project.get("name")
+    'pycmdcheck'
+"""
+
+import re
+import sys
+from functools import lru_cache
+from pathlib import Path
+from typing import Any
+
+if sys.version_info >= (3, 11):
+    import tomllib
+else:
+    import tomli as tomllib
+
+
+@lru_cache(maxsize=8)
+def read_pyproject(package_path: Path) -> dict[str, Any] | None:
+    """Read and parse ``pyproject.toml`` from *package_path*.
+
+    The result is cached (by ``package_path``) so repeated calls for the
+    same path return the identical dict object without re-reading the file.
+
+    Args:
+        package_path: Directory that contains ``pyproject.toml``.
+
+    Returns:
+        Parsed dictionary, or ``None`` if the file does not exist.
+
+    Raises:
+        tomllib.TOMLDecodeError: If the file exists but contains invalid TOML.
+    """
+    pyproject_path = package_path / "pyproject.toml"
+
+    if not pyproject_path.exists():
+        return None
+
+    with open(pyproject_path, "rb") as f:
+        return tomllib.load(f)
+
+
+def get_project_table(package_path: Path) -> dict[str, Any]:
+    """Return the ``[project]`` table from ``pyproject.toml``.
+
+    Args:
+        package_path: Directory that contains ``pyproject.toml``.
+
+    Returns:
+        The ``[project]`` table as a dict, or an empty dict if the file
+        is missing or the table is absent.
+    """
+    data = read_pyproject(package_path)
+    if data is None:
+        return {}
+    project = data.get("project", {})
+    return project if isinstance(project, dict) else {}
+
+
+def get_tool_table(package_path: Path, tool_name: str) -> dict[str, Any]:
+    """Return the ``[tool.<tool_name>]`` table from ``pyproject.toml``.
+
+    Args:
+        package_path: Directory that contains ``pyproject.toml``.
+        tool_name: Name of the tool whose configuration to retrieve
+            (e.g. ``"pycmdcheck"``, ``"ruff"``).
+
+    Returns:
+        The ``[tool.<tool_name>]`` table as a dict, or an empty dict if
+        the file is missing or the table is absent.
+    """
+    data = read_pyproject(package_path)
+    if data is None:
+        return {}
+    tool = data.get("tool", {})
+    if not isinstance(tool, dict):
+        return {}
+    table = tool.get(tool_name, {})
+    return table if isinstance(table, dict) else {}
+
+
+_AUTHOR_RE = re.compile(r"^\s*(?P<name>.*?)\s*(?:<(?P<email>[^>]+)>)?\s*$")
+
+
+def _parse_poetry_authors(authors: Any) -> list[dict[str, str]]:
+    """Convert Poetry ``authors`` (``"Name <email>"`` strings) to PEP 621 form."""
+    if not isinstance(authors, list):
+        return []
+    result: list[dict[str, str]] = []
+    for entry in authors:
+        if not isinstance(entry, str):
+            continue
+        m = _AUTHOR_RE.match(entry)
+        if not m:
+            continue
+        person: dict[str, str] = {}
+        name = (m.group("name") or "").strip()
+        email = (m.group("email") or "").strip()
+        if name:
+            person["name"] = name
+        if email:
+            person["email"] = email
+        if person:
+            result.append(person)
+    return result
+
+
+def poetry_python_to_pep440(constraint: str) -> str | None:
+    """Translate a Poetry ``python`` constraint to a PEP 440 specifier.
+
+    Poetry uses caret (``^3.9``) and tilde (``~3.9``) operators that PEP 440
+    does not. This produces a best-effort PEP 440 specifier preserving the
+    lower bound (which is what the EOL check cares about). PEP 440 operators
+    (``>=``, ``<``, ``==``, ``!=``, comma-separated) and bare versions are
+    handled too. Returns ``None`` for an unusable value.
+    """
+    if not isinstance(constraint, str):
+        return None
+    text = constraint.strip()
+    if not text:
+        return None
+    # Caret/tilde: keep the lower bound (e.g. ^3.9 / ~3.9 -> >=3.9).
+    m = re.match(r"^[\^~]\s*(\d+(?:\.\d+)*)$", text)
+    if m:
+        return f">={m.group(1)}"
+    # Already a PEP 440 operator (or comma-separated set): pass through.
+    if re.search(r"[<>=!~]", text):
+        return text
+    # Bare version (e.g. "3.9"): treat as a lower bound.
+    if re.match(r"^\d+(?:\.\d+)*$", text):
+        return f">={text}"
+    return None
+
+
+def _synthesize_from_poetry(poetry: dict[str, Any]) -> dict[str, Any]:
+    """Build a PEP 621-shaped ``[project]`` dict from a ``[tool.poetry]`` table."""
+    project: dict[str, Any] = {}
+
+    for key in ("name", "version", "description", "readme", "license", "keywords"):
+        if key in poetry:
+            project[key] = poetry[key]
+
+    if isinstance(poetry.get("classifiers"), list):
+        project["classifiers"] = poetry["classifiers"]
+
+    authors = _parse_poetry_authors(poetry.get("authors"))
+    if authors:
+        project["authors"] = authors
+    maintainers = _parse_poetry_authors(poetry.get("maintainers"))
+    if maintainers:
+        project["maintainers"] = maintainers
+
+    # requires-python lives under [tool.poetry.dependencies].python in Poetry.
+    deps = poetry.get("dependencies", {})
+    if isinstance(deps, dict):
+        py = deps.get("python")
+        if isinstance(py, str):
+            translated = poetry_python_to_pep440(py)
+            if translated:
+                project["requires-python"] = translated
+        dep_names = [name for name in deps if name != "python"]
+        if dep_names:
+            project["dependencies"] = dep_names
+
+    # urls: dedicated keys plus an optional [tool.poetry.urls] table.
+    urls: dict[str, str] = {}
+    for label, key in (
+        ("Homepage", "homepage"),
+        ("Repository", "repository"),
+        ("Documentation", "documentation"),
+    ):
+        value = poetry.get(key)
+        if isinstance(value, str):
+            urls[label] = value
+    extra_urls = poetry.get("urls")
+    if isinstance(extra_urls, dict):
+        for label, value in extra_urls.items():
+            if isinstance(value, str):
+                urls[label] = value
+    if urls:
+        project["urls"] = urls
+
+    return project
+
+
+def get_effective_project_table(package_path: Path) -> dict[str, Any]:
+    """Return a PEP 621-shaped ``[project]`` table, accounting for legacy Poetry.
+
+    If a PEP 621 ``[project]`` table is present (even minimally), it is returned
+    unchanged. Otherwise, if a legacy ``[tool.poetry]`` table is present (the
+    metadata format used by Poetry projects before Poetry 2.0), its fields are
+    normalized into a PEP 621-shaped dict so the checks can treat both layouts
+    uniformly. Returns an empty dict if neither is present.
+    """
+    data = read_pyproject(package_path)
+    if data is None:
+        return {}
+    project = data.get("project")
+    if isinstance(project, dict) and project:
+        return project
+    tool = data.get("tool", {})
+    poetry = tool.get("poetry") if isinstance(tool, dict) else None
+    if isinstance(poetry, dict) and poetry:
+        return _synthesize_from_poetry(poetry)
+    return {}
+
+
+def clear_cache() -> None:
+    """Clear the :func:`read_pyproject` LRU cache.
+
+    Call this between test runs or when the underlying ``pyproject.toml``
+    may have changed on disk.
+    """
+    read_pyproject.cache_clear()

pycmdcheck/results.py

@@ -0,0 +1,320 @@
+"""Result types for pycmdcheck."""
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+
+
+class CheckStatus(Enum):
+    """Status of a check result.
+
+    Each check returns one of these statuses to indicate
+    whether the check passed, failed, or encountered issues.
+
+    Attributes:
+        OK: Check passed successfully.
+        NOTE: Informational message, not a problem.
+        WARNING: Potential issue that should be reviewed.
+        ERROR: Check failed.
+        SKIPPED: Check was skipped (e.g., required tool not installed).
+
+    Examples:
+        >>> status = CheckStatus.OK
+        >>> status.symbol
+        '✓'
+        >>> status.color
+        'green'
+        >>> str(status)
+        'ok'
+    """
+
+    OK = "ok"
+    NOTE = "note"
+    WARNING = "warning"
+    ERROR = "error"
+    SKIPPED = "skipped"
+
+    def __str__(self) -> str:
+        """Return the string value of the status.
+
+        Returns:
+            The status value as a lowercase string.
+        """
+        return self.value
+
+    @property
+    def symbol(self) -> str:
+        """Return a visual symbol for the status.
+
+        Returns:
+            A unicode symbol representing the status:
+            ✓ for OK, ℹ for NOTE, ⚠ for WARNING, ✗ for ERROR, ○ for SKIPPED.
+
+        Examples:
+            >>> CheckStatus.OK.symbol
+            '✓'
+            >>> CheckStatus.ERROR.symbol
+            '✗'
+        """
+        symbols = {
+            CheckStatus.OK: "✓",
+            CheckStatus.NOTE: "ℹ",
+            CheckStatus.WARNING: "⚠",
+            CheckStatus.ERROR: "✗",
+            CheckStatus.SKIPPED: "○",
+        }
+        return symbols[self]
+
+    @property
+    def color(self) -> str:
+        """Return a Rich library color name for the status.
+
+        Returns:
+            A color name compatible with the Rich library:
+            green, blue, yellow, red, or dim.
+
+        Examples:
+            >>> CheckStatus.OK.color
+            'green'
+            >>> CheckStatus.ERROR.color
+            'red'
+        """
+        colors = {
+            CheckStatus.OK: "green",
+            CheckStatus.NOTE: "blue",
+            CheckStatus.WARNING: "yellow",
+            CheckStatus.ERROR: "red",
+            CheckStatus.SKIPPED: "dim",
+        }
+        return colors[self]
+
+
+@dataclass
+class CheckResult:
+    """Result of a single check.
+
+    Contains the outcome of running a check, including the status,
+    a human-readable message, and optional details.
+
+    Attributes:
+        name: Name of the check that produced this result (e.g., "metadata").
+        status: The status of the check (OK, WARNING, ERROR, etc.).
+        message: Human-readable message describing the result.
+        details: Optional list of detailed messages providing more context.
+        duration: Time taken to run the check in seconds.
+
+    Examples:
+        Create a successful check result:
+
+        >>> result = CheckResult(
+        ...     name="metadata",
+        ...     status=CheckStatus.OK,
+        ...     message="Package metadata is valid",
+        ... )
+        >>> result.status
+        <CheckStatus.OK: 'ok'>
+
+        Create a result with details:
+
+        >>> result = CheckResult(
+        ...     name="linting",
+        ...     status=CheckStatus.WARNING,
+        ...     message="Found 3 linting issues",
+        ...     details=["Line 10: E501 line too long", "Line 20: W503 line break"],
+        ... )
+        >>> print(result)
+        ⚠ linting: Found 3 linting issues
+    """
+
+    name: str
+    status: CheckStatus
+    message: str
+    details: list[str] = field(default_factory=list)
+    duration: float = 0.0
+
+    def __str__(self) -> str:
+        """Return a formatted string representation.
+
+        Returns:
+            A string in the format "symbol name: message".
+
+        Examples:
+            >>> result = CheckResult("test", CheckStatus.OK, "All tests passed")
+            >>> str(result)
+            '✓ test: All tests passed'
+        """
+        return f"{self.status.symbol} {self.name}: {self.message}"
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary for JSON serialization.
+
+        Returns:
+            A dictionary with keys: name, status, message, details, duration.
+            The status is converted to its string value.
+
+        Examples:
+            >>> result = CheckResult("test", CheckStatus.OK, "Passed")
+            >>> result.to_dict()  # doctest: +NORMALIZE_WHITESPACE
+            {'name': 'test', 'status': 'ok', 'message': 'Passed',
+             'details': [], 'duration': 0.0}
+        """
+        return {
+            "name": self.name,
+            "status": self.status.value,
+            "message": self.message,
+            "details": self.details,
+            "duration": self.duration,
+        }
+
+
+@dataclass
+class Report:
+    """Collection of check results for a package.
+
+    A Report aggregates multiple CheckResult objects and provides
+    methods for querying the overall status and summarizing results.
+
+    Attributes:
+        results: List of CheckResult objects from running checks.
+        package_path: Path to the package that was checked.
+
+    Examples:
+        Create a report and add results:
+
+        >>> report = Report(package_path="/path/to/package")
+        >>> report.add(CheckResult("metadata", CheckStatus.OK, "Valid"))
+        >>> report.add(CheckResult("tests", CheckStatus.OK, "Passed"))
+        >>> report.passed
+        True
+
+        Check for specific failure conditions:
+
+        >>> report.failed_on(["error"])
+        False
+        >>> report.failed_on(["error", "warning"])
+        False
+    """
+
+    results: list[CheckResult] = field(default_factory=list)
+    package_path: str = ""
+
+    def add(self, result: CheckResult) -> None:
+        """Add a check result to the report.
+
+        Args:
+            result: The CheckResult to add.
+
+        Examples:
+            >>> report = Report()
+            >>> report.add(CheckResult("test", CheckStatus.OK, "Passed"))
+            >>> len(report.results)
+            1
+        """
+        self.results.append(result)
+
+    @property
+    def passed(self) -> bool:
+        """Check if all checks passed (no errors).
+
+        Returns:
+            True if no check has ERROR status, False otherwise.
+
+        Examples:
+            >>> report = Report()
+            >>> report.add(CheckResult("test", CheckStatus.OK, "Passed"))
+            >>> report.passed
+            True
+            >>> report.add(CheckResult("lint", CheckStatus.ERROR, "Failed"))
+            >>> report.passed
+            False
+        """
+        return not any(r.status == CheckStatus.ERROR for r in self.results)
+
+    @property
+    def has_warnings(self) -> bool:
+        """Check if any check has warnings.
+
+        Returns:
+            True if any check has WARNING status, False otherwise.
+
+        Examples:
+            >>> report = Report()
+            >>> report.add(CheckResult("test", CheckStatus.OK, "Passed"))
+            >>> report.has_warnings
+            False
+            >>> report.add(CheckResult("lint", CheckStatus.WARNING, "Issues"))
+            >>> report.has_warnings
+            True
+        """
+        return any(r.status == CheckStatus.WARNING for r in self.results)
+
+    def count_by_status(self) -> dict[CheckStatus, int]:
+        """Count results by status.
+
+        Returns:
+            A dictionary mapping each CheckStatus to the count of results
+            with that status.
+
+        Examples:
+            >>> report = Report()
+            >>> report.add(CheckResult("a", CheckStatus.OK, "OK"))
+            >>> report.add(CheckResult("b", CheckStatus.OK, "OK"))
+            >>> report.add(CheckResult("c", CheckStatus.WARNING, "Warn"))
+            >>> counts = report.count_by_status()
+            >>> counts[CheckStatus.OK]
+            2
+            >>> counts[CheckStatus.WARNING]
+            1
+        """
+        counts: dict[CheckStatus, int] = dict.fromkeys(CheckStatus, 0)
+        for result in self.results:
+            counts[result.status] += 1
+        return counts
+
+    def failed_on(self, fail_on: list[str]) -> bool:
+        """Check if any result matches the fail_on criteria.
+
+        Args:
+            fail_on: List of status values to consider as failures
+                (e.g., ["error", "warning"]).
+
+        Returns:
+            True if any result has a status in the fail_on list.
+
+        Examples:
+            >>> report = Report()
+            >>> report.add(CheckResult("test", CheckStatus.WARNING, "Warn"))
+            >>> report.failed_on(["error"])
+            False
+            >>> report.failed_on(["error", "warning"])
+            True
+        """
+        fail_statuses = {CheckStatus(s) for s in fail_on}
+        return any(r.status in fail_statuses for r in self.results)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary for JSON serialization.
+
+        Returns:
+            A dictionary containing:
+            - package_path: The path that was checked
+            - passed: Whether all checks passed
+            - summary: Count of each status
+            - results: List of result dictionaries
+
+        Examples:
+            >>> report = Report(package_path="/pkg")
+            >>> report.add(CheckResult("test", CheckStatus.OK, "OK"))
+            >>> data = report.to_dict()
+            >>> data["passed"]
+            True
+            >>> data["summary"]["ok"]
+            1
+        """
+        counts = self.count_by_status()
+        return {
+            "package_path": self.package_path,
+            "passed": self.passed,
+            "summary": {status.value: count for status, count in counts.items()},
+            "results": [r.to_dict() for r in self.results],
+        }