pkgdx 0.5.0__py3-none-any.whl

pkgdx/_types.py

@@ -0,0 +1,111 @@
+"""Type definitions for Pre-commit hooks and repositories in the TOML config.
+
+This module defines `TypedDict` classes for representing remote, local and
+builtin hooks and repositories as they appear in the Pre-commit configuration.
+"""
+
+from typing import Literal, NotRequired, TypedDict
+
+
+class HookRemote(TypedDict):
+    """Represents a Pre-commit remote hook entry in the TOML config.
+
+    Attributes:
+        id: The unique identifier for the remote hook.
+        name: The name of the remote hook.
+        entry: The entry point for the remote hook.
+        args: The list of arguments for the remote hook.
+        language: The programming language of the remote hook.
+        types_or: The list of file types the hook applies to.
+        exclude: The pattern for files to exclude from the hook.
+        require_serial: Flag indicating if the hook requires serial execution.
+        pass_filenames: Flag indicating if filenames should be passed to the
+            hook.
+    """
+
+    id: str
+    name: NotRequired[str]
+    entry: NotRequired[str]
+    args: NotRequired[list[str]]
+    language: NotRequired[str]
+    types_or: NotRequired[list[str]]
+    exclude: NotRequired[str]
+    require_serial: NotRequired[bool]
+    pass_filenames: NotRequired[bool]
+
+
+class RepoRemote(TypedDict):
+    """Represents a Pre-commit remote repo entry in the TOML config.
+
+    Attributes:
+        repo: The URL of the remote repository.
+        rev: The revision of the remote repository.
+        hooks: A list of remote hooks associated with the repository.
+    """
+
+    repo: str
+    rev: NotRequired[str]
+    hooks: list[HookRemote]
+
+
+class HookLocal(TypedDict):
+    """Represents a Pre-commit local hook entry in the TOML config.
+
+    Attributes:
+        id: The unique identifier for the local hook.
+        name: The name of the local hook.
+        entry: The entry point for the local hook.
+        args: The list of arguments for the local hook.
+        language: The programming language of the local hook.
+        types_or: The list of file types the hook applies to.
+        exclude: The pattern for files to exclude from the hook.
+        require_serial: Flag indicating if the hook requires serial execution.
+        pass_filenames: Flag indicating if filenames should be passed to the
+            hook.
+    """
+
+    id: str
+    name: str
+    entry: str
+    args: NotRequired[list[str]]
+    language: str
+    types_or: NotRequired[list[str]]
+    exclude: NotRequired[str]
+    require_serial: NotRequired[bool]
+    pass_filenames: NotRequired[bool]
+
+
+class RepoLocal(TypedDict):
+    """Represents a Pre-commit local repo entry in the TOML config.
+
+    Attributes:
+        repo: The literal string "local" indicating a local repository.
+        rev: The revision of the local repository.
+        hooks: A list of local hooks associated with the repository.
+    """
+
+    repo: Literal["local"]
+    rev: NotRequired[str]
+    hooks: list[HookLocal]
+
+
+class HookBuiltin(TypedDict):
+    """Represents a Pre-commit builtin hook entry in the TOML config.
+
+    Attributes:
+        id: The unique identifier for the builtin hook.
+    """
+
+    id: str
+
+
+class RepoBuiltin(TypedDict):
+    """Represents a Pre-commit builtin repo entry in the TOML config.
+
+    Attributes:
+        repo: The literal string "builtin" indicating a builtin repository.
+        hooks: A list of builtin hooks associated with the repository.
+    """
+
+    repo: Literal["builtin"]
+    hooks: list[HookBuiltin]

pkgdx/exceptions.py

@@ -0,0 +1,37 @@
+"""Custom exceptions for `pkgdx`."""
+
+
+class Error(Exception):
+    """Base-class for all exceptions raised by `pkgdx`."""
+
+
+class ProjectRootNotFoundError(Error):
+    """Raised when the project root cannot be determined."""
+
+
+class PrekConfigError(Error):
+    """Raised on a malformed consumer `prek.toml` configuration."""
+
+
+class PrekRepoRevisionError(Error):
+    """Raised on missing `rev` key in Prek config."""
+
+
+class PrekRepoURLMissingError(Error):
+    """Raised on missing `repo` key in Prek config."""
+
+
+class ProjectRepoURLMissingError(Error):
+    """Raised on missing `repository` key in `pkgdx` metadata."""
+
+
+class GitTopLevelError(Error):
+    """Raised on failed `git rev-parse --show-toplevel` command."""
+
+
+class RichHandlerNotFound(Error):
+    """Raised on missing Rich logging handler."""
+
+
+class ConfigDirError(Error):
+    """Raised on an invalid `PKGDX_CONFIG_DIR`."""

pkgdx/logging/__init__.py

@@ -0,0 +1,15 @@
+"""__init__ for pkgdx logging module."""
+
+from ._logging import (
+    CLI_CONSOLE,
+    GLOBAL_CONSOLE,
+    configure_cli_logging,
+    configure_pkg_logging,
+)
+
+__all__: list[str] = [
+    "CLI_CONSOLE",
+    "GLOBAL_CONSOLE",
+    "configure_cli_logging",
+    "configure_pkg_logging",
+]

pkgdx/logging/_logging.py

@@ -0,0 +1,49 @@
+"""Logging configuration for `pkgdx`.
+
+The Rich global `Console` (`GLOBAL_CONSOLE`) is configured to use STDERR
+(`reconfigure(stderr=True)`) for logging and progress display. A separate
+`Console` instance (`CLI_CONSOLE`) is used for CLI output on STDOUT.
+
+When a `RichHandler` (logging handler) and `Status`/`Progress` share the same
+`Console` instance (`GLOBAL_CONSOLE`), the output can be automatically
+coordinated by Rich.
+
+NOTE: When `RichHandler` is initialised without a `Console` instance, it will
+use the global `Console` returned by `get_console()` (`GLOBAL_CONSOLE`).
+"""
+
+import logging.config
+import pathlib
+import sys
+import tomllib
+
+from rich import get_console, reconfigure
+from rich.console import Console
+
+CONFIG_PATH = pathlib.Path(__file__).parent / "config.toml"
+CONFIG_STR = CONFIG_PATH.read_text(encoding="utf-8")
+
+reconfigure(stderr=True)
+GLOBAL_CONSOLE = get_console()
+CLI_CONSOLE = Console(force_terminal=sys.stdout.isatty())
+
+
+def configure_cli_logging(level: int = logging.WARNING) -> None:
+    """Configure CLI logging using the `config.toml` settings.
+
+    NOTE: CLI logs are prevented from propagating to the root logger to avoid
+    duplication.
+
+    Args:
+        level: The desired logging level. Defaults to `logging.WARNING`.
+    """
+    logging.config.dictConfig(tomllib.loads(CONFIG_STR))
+
+    logger = logging.getLogger("pkgdx")
+    logger.setLevel(level)
+    logger.propagate = False
+
+
+def configure_pkg_logging() -> None:
+    """Configure package logging using a `NullHandler`."""
+    logging.getLogger("pkgdx").addHandler(logging.NullHandler())

pkgdx/logging/config.toml

@@ -0,0 +1,48 @@
+version = 1
+incremental = false
+disable_existing_loggers = false
+
+[formatters.stdlib-standard-format]
+format = "%(levelname)s: %(message)s"
+datefmt = "%Y-%m-%dT%H:%M:%S%z"
+
+[formatters.rich-standard-format]
+format = "%(message)s"
+datefmt = "[%Y-%m-%dT%H:%M:%S%z]"
+
+[formatters.rich-verbose-format]
+format = "[%(funcName)s] %(message)s"
+datefmt = "[%Y-%m-%dT%H:%M:%S%z]"
+
+[formatters.rich-extra-verbose-format]
+format = "[%(levelname)s|%(module)s|L%(lineno)d] %(asctime)s: %(message)s"
+datefmt = "%Y-%m-%dT%H:%M:%S%z"
+
+[filters]
+# Unused, but kept to match expected `dictConfig` structure
+
+[handlers.rich-standard-handler]
+class = "rich.logging.RichHandler"
+formatter = "rich-standard-format"
+show_path = false
+rich_tracebacks = true
+markup = true
+omit_repeated_times = true
+
+[handlers.rich-verbose-handler]
+class = "rich.logging.RichHandler"
+formatter = "rich-verbose-format"
+show_path = true
+rich_tracebacks = true
+markup = false
+omit_repeated_times = false
+
+[handlers.stdlib-standard-handler]
+class = "logging.StreamHandler"
+formatter = "stdlib-standard-format"
+stream = "ext://sys.stderr"
+
+[loggers.pkgdx]
+level = "WARNING"
+handlers = ["rich-verbose-handler"]
+propagate = true

pkgdx/standards/__init__.py

@@ -0,0 +1,182 @@
+"""__init__ for `pkgdx.standards` module.
+
+Provides access to configuration files for supported tools such as; `mypy`,
+`prek`, `pymarkdown` and `ruff`.
+"""
+
+import logging
+import os
+import sys
+from functools import lru_cache
+from pathlib import Path
+from typing import Any
+
+logger = logging.getLogger(__package__)
+
+MODULE_ROOT: Path = Path(__file__).parent
+MYPY_CONFIG: Path = MODULE_ROOT / "mypy.ini"
+PREK_CONFIG: Path = MODULE_ROOT / "hooks.toml"
+PYMARKDOWN_CONFIG: Path = MODULE_ROOT / "pymarkdown.toml"
+RUFF_CONFIG: Path = MODULE_ROOT / "ruff.toml"
+
+CONFIG_DIR_ENV: str = "PKGDX_CONFIG_DIR"
+BUNDLED_CONFIGS: tuple[Path, ...] = (
+    MYPY_CONFIG,
+    PREK_CONFIG,
+    PYMARKDOWN_CONFIG,
+    RUFF_CONFIG,
+)
+
+
+def user_config_dir() -> Path:
+    """Get the user config directory.
+
+    The environment is read on every call; nothing is cached. The platform
+    directory is returned even if it does not exist.
+
+    Raises:
+        ConfigDirError: If `PKGDX_CONFIG_DIR` is set but not a directory.
+
+    Returns:
+        The `PKGDX_CONFIG_DIR` path, else the platform config directory.
+    """
+    from pkgdx.exceptions import ConfigDirError
+
+    env_value = os.environ.get(CONFIG_DIR_ENV)
+    if env_value:
+        env_dir = Path(env_value).expanduser()
+        if not env_dir.is_dir():
+            msg = f"`{CONFIG_DIR_ENV}` is not an existing directory: {env_dir}"
+            raise ConfigDirError(msg)
+        return env_dir
+
+    appdata = os.environ.get("APPDATA")
+    if sys.platform == "win32" and appdata:
+        return Path(appdata) / "pkgdx"
+
+    xdg = os.environ.get("XDG_CONFIG_HOME")
+    if xdg and Path(xdg).is_absolute():
+        return Path(xdg) / "pkgdx"
+    return Path.home() / ".config" / "pkgdx"
+
+
+def resolve_config(bundled: Path) -> Path:
+    """Resolve a config file, preferring a user override.
+
+    Args:
+        bundled: A bundled config path (for example `RUFF_CONFIG`).
+
+    Raises:
+        ConfigDirError: If `PKGDX_CONFIG_DIR` is set but not a directory.
+
+    Returns:
+        The user config file if it exists, else the bundled file.
+    """
+    user_file = user_config_dir() / bundled.name
+    if user_file.is_file():
+        logger.debug("Using user config %s", user_file)
+        return user_file
+    logger.debug("Using bundled config %s", bundled)
+    return bundled
+
+
+@lru_cache(maxsize=1)
+def _load_prek_config() -> dict[str, Any]:
+    """Load Prek config.
+
+    Returns:
+        The Prek hooks TOML as a dict."""
+    import tomllib
+
+    # Bundled only: validates the package's own template, never a user copy
+    with PREK_CONFIG.open("rb") as f:
+        return tomllib.load(f)
+
+
+@lru_cache(maxsize=1)
+def get_pkgdx_repository() -> str:
+    """Get repository URL from pkgdx metadata.
+
+    Raises:
+        ProjectRepoURLMissingError: On missing repository URL in metadata.
+
+    Returns:
+        Repository URL.
+    """
+    import urllib.parse
+    from importlib.metadata import metadata
+
+    from pkgdx.exceptions import ProjectRepoURLMissingError
+
+    pkgdx_metadata = metadata("pkgdx")
+
+    entry: str
+    for entry in pkgdx_metadata.get_all("Project-URL", failobj=[]):
+        if entry.lower().startswith("repository"):
+            _, URL = entry.split(", ", 1)
+            parsed = urllib.parse.urlparse(URL)
+            if parsed.scheme and parsed.netloc:
+                return URL
+    msg = "Missing repository URL in `pkgdx` metadata (`pyproject.toml`)"
+    raise ProjectRepoURLMissingError(msg)
+
+
+@lru_cache(maxsize=1)
+def get_config_revision() -> str:
+    """Get repo revision from Prek config.
+
+    Raises:
+        PrekRepoRevisionError: On missing revision value.
+
+    Returns:
+        Revision tag.
+    """
+    from pkgdx.exceptions import PrekRepoRevisionError
+
+    config = _load_prek_config()
+    REPO_URL: str = get_pkgdx_repository()
+
+    for repo in config.get("repos", []):
+        if repo.get("repo") == REPO_URL:
+            revision: str | None = repo.get("rev", None)
+            if revision:
+                return revision
+            msg = "Missing `rev` key in Prek config"
+            raise PrekRepoRevisionError(msg)
+    msg = "`pkgdx` metadata URL missing/mismatch for Prek config"
+    raise PrekRepoRevisionError(msg)
+
+
+@lru_cache(maxsize=1)
+def get_config_repository() -> str:
+    """Get repo URL from Prek config.
+
+    Raises:
+        ProjectRepoURLMissingError: On missing repository URL.
+
+    Returns:
+        Repository URL.
+    """
+    from pkgdx.exceptions import ProjectRepoURLMissingError
+
+    config = _load_prek_config()
+    REPO_URL = get_pkgdx_repository()
+
+    for repo in config.get("repos", []):
+        if repo.get("repo") == REPO_URL:
+            return REPO_URL
+
+    msg = "`pkgdx` repository URL from metadata not found in Prek config"
+    raise ProjectRepoURLMissingError(msg)
+
+
+__all__: list[str] = [
+    "BUNDLED_CONFIGS",
+    "CONFIG_DIR_ENV",
+    "MYPY_CONFIG",
+    "PREK_CONFIG",
+    "PYMARKDOWN_CONFIG",
+    "RUFF_CONFIG",
+    "resolve_config",
+    "user_config_dir",
+]