pyprojkit 0.1.0__py3-none-any.whl

pyprojkit/__init__.py

@@ -0,0 +1,104 @@
+"""
+Development workflow toolkit for Python projects.
+
+Declare configuration once in `pyprojconf.py`; pyprojkit keeps `pyproject.toml` in sync
+and provides `doit` task and `nox` session factories.
+"""
+
+__submodules__ = [
+    "config",
+    "versions",
+    "discovery",
+    "sync",
+    "tasks",
+    "sessions",
+]
+
+# isort: off
+# <AUTOGEN_INIT>
+from .versions import (
+    DEFAULT_PATCH_VERSIONS,
+    PythonVersions,
+)
+from .config import (
+    ConfigError,
+    BaseToolConfig,
+    BaseFormatterConfig,
+    AutoflakeConfig,
+    IsortConfig,
+    BlackConfig,
+    DocformatterConfig,
+    TomlSortConfig,
+    PytestConfig,
+    CoverageRunConfig,
+    CoverageReportConfig,
+    DoitConfig,
+    NoxConfig,
+    MypyConfig,
+    ProjectConfig,
+    ToolsConfig,
+    FormattingConfig,
+    TestConfig,
+    DocConfig,
+    MkinitConfig,
+    SphinxConfig,
+    AnalysisConfig,
+    PublishConfig,
+    get_formatting_profile,
+    get_tools_profile,
+    register_formatting_profile,
+    register_tools_profile,
+)
+from .discovery import (
+    load_config,
+)
+from .sync import (
+    compute_managed_tables,
+    render,
+    sync,
+)
+from .tasks import (
+    TaskFactory,
+)
+from .sessions import (
+    NoxFactory,
+)
+
+__all__ = [
+    "sync",
+    "DEFAULT_PATCH_VERSIONS",
+    "PythonVersions",
+    "ConfigError",
+    "BaseToolConfig",
+    "BaseFormatterConfig",
+    "AutoflakeConfig",
+    "IsortConfig",
+    "BlackConfig",
+    "DocformatterConfig",
+    "TomlSortConfig",
+    "PytestConfig",
+    "CoverageRunConfig",
+    "CoverageReportConfig",
+    "DoitConfig",
+    "NoxConfig",
+    "MypyConfig",
+    "ProjectConfig",
+    "ToolsConfig",
+    "FormattingConfig",
+    "TestConfig",
+    "DocConfig",
+    "MkinitConfig",
+    "SphinxConfig",
+    "AnalysisConfig",
+    "PublishConfig",
+    "get_formatting_profile",
+    "get_tools_profile",
+    "register_formatting_profile",
+    "register_tools_profile",
+    "load_config",
+    "compute_managed_tables",
+    "render",
+    "TaskFactory",
+    "NoxFactory",
+]
+# </AUTOGEN_INIT>

pyprojkit/_paths.py

@@ -0,0 +1,43 @@
+"""
+Shared path conventions for caches, artifacts, and badges.
+
+These are used by config defaults, doit task factories, and nox session factories alike,
+so they must not be coupled to any one tool.
+"""
+
+from pathlib import Path
+
+# caches
+CACHE_PATH = Path("__cache__")
+DOIT_DB_PATH = CACHE_PATH / ".doit.db"
+COVERAGE_DATA_PATH = CACHE_PATH / ".coverage"
+PYTEST_CACHE_PATH = CACHE_PATH / "pytest"
+NOX_ENVDIR_PATH = CACHE_PATH / "nox"
+
+# artifact output
+OUT_PATH = Path("__out__")
+
+# test coverage results
+TESTS_PATH = OUT_PATH / "test"
+JUNIT_PATH = TESTS_PATH / "junit.xml"
+COV_PATH = TESTS_PATH / "cov"
+COV_HTML_PATH = COV_PATH / "html"
+COV_XML_PATH = COV_PATH / "coverage.xml"
+
+# documentation
+DOC_PATH = OUT_PATH / "doc"
+DOC_HTML_PATH = DOC_PATH / "html"
+
+# static analysis results
+ANALYSIS_PATH = OUT_PATH / "analysis"
+MYPY_PATH = ANALYSIS_PATH / "mypy"
+MYPY_HTML_PATH = MYPY_PATH / "html"
+MYPY_XML_PATH = MYPY_PATH / "xml"
+
+# build/publish artifacts
+UV_PATH = OUT_PATH / "uv"
+
+# badges output
+BADGES_PATH = Path("badges")
+PYTEST_BADGE_PATH = BADGES_PATH / "tests.svg"
+COV_BADGE_PATH = BADGES_PATH / "cov.svg"

pyprojkit/_run.py

@@ -0,0 +1,36 @@
+"""
+Subprocess helpers for task actions.
+"""
+
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+
+def run(cmd: list[str], expect_rc: int | set[int] = 0):
+    """
+    Run command, exiting if the return code is not among the expected ones.
+
+    The current interpreter's bin directory is prepended to `PATH` so tools from the
+    active environment are found even if it isn't activated.
+    """
+    expect_rcs = expect_rc if isinstance(expect_rc, set) else {expect_rc}
+    env = os.environ.copy()
+    env["PATH"] = os.pathsep.join(
+        [str(Path(sys.executable).parent), env.get("PATH", "")]
+    )
+    print(f"=== Running: {cmd[0]}")
+    rc = subprocess.call(cmd, env=env)
+    if rc not in expect_rcs:
+        sys.exit(f"{cmd[0]} failed: rc={rc}, cmd={cmd}")
+
+
+def cleanup_dir(output_dir: Path | str):
+    """
+    Remove directory if it exists.
+    """
+    path = Path(output_dir)
+    if path.exists():
+        shutil.rmtree(path)

pyprojkit/cli.py

@@ -0,0 +1,58 @@
+"""
+Command-line interface: `pyprojkit sync [--check]`.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from .config.base import ConfigError
+from .discovery import load_config
+from .sync import sync
+
+__all__ = [
+    "main",
+]
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="pyprojkit", description="Development workflow toolkit"
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    sync_parser = subparsers.add_parser(
+        "sync", help="Sync pyproject.toml from pyprojconf.py"
+    )
+    sync_parser.add_argument(
+        "--check",
+        action="store_true",
+        help="Verify pyproject.toml is in sync without writing; exit 1 if not",
+    )
+    sync_parser.add_argument(
+        "--root",
+        type=Path,
+        default=None,
+        help="Project root (default: current directory)",
+    )
+
+    args = parser.parse_args(argv)
+
+    try:
+        config = load_config(args.root)
+        in_sync = sync(config, args.root, check=args.check)
+    except ConfigError as exc:
+        print(f"Error: {exc}", file=sys.stderr)
+        return 2
+
+    if args.check and not in_sync:
+        print("pyproject.toml is out of sync; run `pyprojkit sync`", file=sys.stderr)
+        return 1
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

pyprojkit/config/__init__.py

@@ -0,0 +1,79 @@
+"""
+Configuration model for pyprojkit.
+"""
+
+__submodules__ = [
+    "base",
+    "tools",
+    "project",
+    "profiles",
+]
+
+# isort: off
+# <AUTOGEN_INIT>
+from .base import (
+    ConfigError,
+    BaseToolConfig,
+    BaseFormatterConfig,
+)
+from .tools import (
+    AutoflakeConfig,
+    IsortConfig,
+    BlackConfig,
+    DocformatterConfig,
+    TomlSortConfig,
+    PytestConfig,
+    CoverageRunConfig,
+    CoverageReportConfig,
+    DoitConfig,
+    NoxConfig,
+    MypyConfig,
+)
+from .project import (
+    ProjectConfig,
+    ToolsConfig,
+    FormattingConfig,
+    TestConfig,
+    DocConfig,
+    MkinitConfig,
+    SphinxConfig,
+    AnalysisConfig,
+    PublishConfig,
+)
+from .profiles import (
+    get_formatting_profile,
+    get_tools_profile,
+    register_formatting_profile,
+    register_tools_profile,
+)
+
+__all__ = [
+    "ConfigError",
+    "BaseToolConfig",
+    "BaseFormatterConfig",
+    "AutoflakeConfig",
+    "IsortConfig",
+    "BlackConfig",
+    "DocformatterConfig",
+    "TomlSortConfig",
+    "PytestConfig",
+    "CoverageRunConfig",
+    "CoverageReportConfig",
+    "DoitConfig",
+    "NoxConfig",
+    "MypyConfig",
+    "ProjectConfig",
+    "ToolsConfig",
+    "FormattingConfig",
+    "TestConfig",
+    "DocConfig",
+    "MkinitConfig",
+    "SphinxConfig",
+    "AnalysisConfig",
+    "PublishConfig",
+    "get_formatting_profile",
+    "get_tools_profile",
+    "register_formatting_profile",
+    "register_tools_profile",
+]
+# </AUTOGEN_INIT>

pyprojkit/config/base.py

@@ -0,0 +1,84 @@
+"""
+Base classes for tool configurations.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, fields
+from typing import TYPE_CHECKING, Any, ClassVar
+
+if TYPE_CHECKING:
+    from .project import ProjectConfig
+
+__all__ = [
+    "ConfigError",
+    "BaseToolConfig",
+    "BaseFormatterConfig",
+]
+
+
+class ConfigError(Exception):
+    """
+    Raised for invalid or missing configuration.
+    """
+
+
+@dataclass(kw_only=True)
+class BaseToolConfig(ABC):
+    """
+    Configuration for a tool which reads its settings from a table in
+    `pyproject.toml`, e.g. `[tool.black]`.
+
+    Dataclass fields map to table entries; a field whose name differs from its
+    TOML key declares the key via `field(metadata={"toml": "some-key"})`.
+    Fields set to `None` are omitted. Values derived from project-wide config
+    (e.g. black's `target-version`) are contributed by `extra_toml()`.
+    """
+
+    table_path: ClassVar[str]
+    """
+    Dotted path of the tool's table, e.g. `"tool.pytest.ini_options"`.
+    """
+
+    def to_toml(self, project: ProjectConfig) -> dict[str, Any]:
+        """
+        Get this tool's table contents.
+        """
+        config: dict[str, Any] = {}
+        for field_ in fields(self):
+            value = getattr(self, field_.name)
+            if value is None:
+                continue
+            key = field_.metadata.get("toml", field_.name)
+            config[key] = list(value) if isinstance(value, tuple) else value
+        config.update(self.extra_toml(project))
+        return config
+
+    def extra_toml(self, project: ProjectConfig) -> dict[str, Any]:
+        """
+        Get extra table entries derived from project-wide config.
+        """
+        return {}
+
+
+@dataclass(kw_only=True)
+class BaseFormatterConfig(BaseToolConfig):
+    """
+    Configuration for a tool which additionally runs as part of the `format` task.
+
+    Adds the command line to invoke and the expected return codes; the order of
+    formatters in `FormattingConfig` is the run order.
+    """
+
+    expect_rc: ClassVar[frozenset[int]] = frozenset({0})
+    """
+    Return codes indicating success.
+    """
+
+    @abstractmethod
+    def command(self, py_paths: list[str], toml_paths: list[str]) -> list[str]:
+        """
+        Get the command line to run, given python and toml paths to format.
+        """
+        ...

pyprojkit/config/profiles.py

@@ -0,0 +1,97 @@
+"""
+Profile registries: named factories for pre-canned configurations.
+
+A tools profile encompasses all tool categories; a formatting profile covers
+just the formatter chain. Third parties can register their own profiles and
+reuse them across projects:
+
+```python
+from pyprojkit import register_tools_profile
+
+register_tools_profile("mycompany", lambda: ToolsConfig(...))
+```
+"""
+
+from __future__ import annotations
+
+from typing import Callable
+
+from .base import ConfigError
+from .project import FormattingConfig, ToolsConfig
+from .tools import (
+    AutoflakeConfig,
+    BlackConfig,
+    DocformatterConfig,
+    IsortConfig,
+    TomlSortConfig,
+)
+
+__all__ = [
+    "get_formatting_profile",
+    "get_tools_profile",
+    "register_formatting_profile",
+    "register_tools_profile",
+]
+
+
+def _default_formatting() -> FormattingConfig:
+    return FormattingConfig(
+        formatters=(
+            AutoflakeConfig(),
+            IsortConfig(),
+            BlackConfig(),
+            DocformatterConfig(),
+            TomlSortConfig(),
+        )
+    )
+
+
+_FORMATTING_PROFILES: dict[str, Callable[[], FormattingConfig]] = {
+    "default": _default_formatting,
+}
+
+# the zero-arg ToolsConfig constructor is itself the default profile, as its
+# field defaults resolve to the default sub-configs
+_TOOLS_PROFILES: dict[str, Callable[[], ToolsConfig]] = {
+    "default": ToolsConfig,
+}
+
+
+def get_formatting_profile(name: str) -> FormattingConfig:
+    """
+    Get a new instance of the given formatting profile.
+    """
+    try:
+        factory = _FORMATTING_PROFILES[name]
+    except KeyError:
+        raise ConfigError(
+            f"Unknown formatting profile '{name}'; have {sorted(_FORMATTING_PROFILES)}"
+        ) from None
+    return factory()
+
+
+def get_tools_profile(name: str) -> ToolsConfig:
+    """
+    Get a new instance of the given tools profile.
+    """
+    try:
+        factory = _TOOLS_PROFILES[name]
+    except KeyError:
+        raise ConfigError(
+            f"Unknown tools profile '{name}'; have {sorted(_TOOLS_PROFILES)}"
+        ) from None
+    return factory()
+
+
+def register_formatting_profile(name: str, factory: Callable[[], FormattingConfig]):
+    """
+    Register a named formatting profile.
+    """
+    _FORMATTING_PROFILES[name] = factory
+
+
+def register_tools_profile(name: str, factory: Callable[[], ToolsConfig]):
+    """
+    Register a named tools profile.
+    """
+    _TOOLS_PROFILES[name] = factory

pyprojkit/config/project.py

@@ -0,0 +1,194 @@
+"""
+Project-wide configuration, declared in a project's `pyprojconf.py`.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Sequence
+
+from .. import _paths
+from ..versions import PythonVersions
+from .base import BaseFormatterConfig
+from .tools import (
+    CoverageReportConfig,
+    CoverageRunConfig,
+    DoitConfig,
+    MypyConfig,
+    NoxConfig,
+    PytestConfig,
+)
+
+__all__ = [
+    "ProjectConfig",
+    "ToolsConfig",
+    "FormattingConfig",
+    "TestConfig",
+    "DocConfig",
+    "MkinitConfig",
+    "SphinxConfig",
+    "AnalysisConfig",
+    "PublishConfig",
+]
+
+
+@dataclass(kw_only=True)
+class FormattingConfig:
+    """
+    Formatting configuration: which formatters run (in order) and their settings.
+    """
+
+    formatters: tuple[BaseFormatterConfig, ...]
+    """
+    Formatters in run order.
+    """
+
+    @classmethod
+    def default(cls) -> FormattingConfig:
+        """
+        Get the default formatting profile.
+        """
+        from .profiles import get_formatting_profile
+
+        return get_formatting_profile("default")
+
+
+@dataclass(kw_only=True)
+class TestConfig:
+    """
+    Testing configuration (pytest + coverage).
+    """
+
+    pytest: PytestConfig = field(default_factory=PytestConfig)
+    coverage_run: CoverageRunConfig = field(default_factory=CoverageRunConfig)
+    coverage_report: CoverageReportConfig = field(default_factory=CoverageReportConfig)
+
+
+@dataclass(kw_only=True)
+class MkinitConfig:
+    """
+    Configuration for generating `__init__.py` files using mkinit.
+    """
+
+    args: tuple[str, ...] = (
+        "--recursive",
+        "--nomods",
+        "--relative",
+        "-i",
+        "--source-order",
+    )
+    """
+    Arguments passed to mkinit.
+    """
+
+@dataclass(kw_only=True)
+class SphinxConfig:
+    """
+    Configuration for building documentation using sphinx.
+    """
+
+    source_dir: str = "doc"
+    """
+    Directory containing sphinx sources.
+    """
+
+    copy_env_var: str | None = None
+    """
+    Name of environment variable (or `.env` entry) giving a directory to which to copy
+    built documentation when the doc task is run with `--copy`.
+    """
+
+@dataclass(kw_only=True)
+class DocConfig:
+    """
+    Documentation tool configurations.
+    """
+
+    mkinit: MkinitConfig | None = field(default_factory=MkinitConfig)
+    """
+    Enables the `init` task; enabled by default.
+    """
+
+    sphinx: SphinxConfig | None = None
+    """
+    Enables the `doc` task; opt-in.
+    """
+
+@dataclass(kw_only=True)
+class AnalysisConfig:
+    """
+    Static analysis configuration.
+    """
+    mypy: MypyConfig | None = field(default_factory=MypyConfig)
+    pyright: bool = True
+
+
+@dataclass(kw_only=True)
+class PublishConfig:
+    """
+    Configuration for building and publishing via uv.
+    """
+    out_dir: str = str(_paths.UV_PATH)
+    """
+    Directory for build artifacts; cleaned before each build so stale artifacts are
+    never published.
+    """
+@dataclass(kw_only=True)
+class ToolsConfig:
+    """
+    Development tool configurations, grouped by broad tool category.
+
+    A "tools profile" is simply a pre-canned `ToolsConfig` factory; see
+    `pyprojkit.config.profiles`. The default instance corresponds to the default
+    profile.
+    """
+    formatting: FormattingConfig = field(default_factory=FormattingConfig.default)
+    test: TestConfig | None = field(default_factory=TestConfig)
+    doit: DoitConfig = field(default_factory=DoitConfig)
+    nox: NoxConfig = field(default_factory=NoxConfig)
+    doc: DocConfig = field(default_factory=DocConfig)
+    analysis: AnalysisConfig | None = None
+    publish: PublishConfig = field(default_factory=PublishConfig)
+
+    tool_overrides: dict[str, dict[str, Any]] = field(default_factory=dict)
+    """
+    Escape hatch: extra entries merged last into managed tables, keyed by table path,
+    e.g. `{"tool.pytest.ini_options": {"addopts": "..."}}`.
+
+    A key not otherwise managed creates a new managed table.
+    """
+    @classmethod
+    def default(cls) -> ToolsConfig:
+        """
+        Get the default tools profile.
+        """
+        from .profiles import get_tools_profile
+
+        return get_tools_profile("default")
+
+
+@dataclass(kw_only=True)
+class ProjectConfig:
+    """
+    Top-level project configuration.
+
+    A project's `pyprojconf.py` must define a module-level instance named `config`.
+    """
+    package: str
+    """
+    Import name of the package, e.g. `"trilium_alchemy"`.
+    """
+    python: PythonVersions
+    """
+    Supported Python versions.
+    """
+    format_paths: Sequence[str] = ("src", "test", "doc", "examples")
+    """
+    Directories to format (those which exist), in addition to `*.py` and `*.toml` files
+    at the project root.
+    """
+
+    tools: ToolsConfig = field(default_factory=ToolsConfig.default)
+    """
+    Tool configurations.
+    """