pyprojkit 0.3.0__py3-none-any.whl

pyprojkit/config/project.py

@@ -0,0 +1,219 @@
+"""
+Project-wide configuration, declared in a project's `pyprojconf.py`.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+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.
+    """
+
+    packages_dir: str = "src"
+    """
+    Directory containing packages, relative to the project root.
+    """
+
+    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.
+    """
+
+    @property
+    def package_path(self) -> Path:
+        """
+        Path to the package directory, relative to the project root.
+        """
+        return Path(self.packages_dir) / self.package

pyprojkit/config/tools.py

@@ -0,0 +1,168 @@
+"""
+Configurations for all supported tools.
+
+Formatters are tools which additionally run as part of the `format` task.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any, ClassVar
+
+from .. import _paths
+from .base import BaseFormatterConfig, BaseToolConfig
+
+if TYPE_CHECKING:
+    from .project import ProjectConfig
+
+__all__ = [
+    "AutoflakeConfig",
+    "IsortConfig",
+    "BlackConfig",
+    "DocfmtConfig",
+    "TomlSortConfig",
+    "PytestConfig",
+    "CoverageRunConfig",
+    "CoverageReportConfig",
+    "DoitConfig",
+    "NoxConfig",
+    "MypyConfig",
+]
+
+
+# --- formatters (run order defined by FormattingConfig) ---
+
+
+@dataclass(kw_only=True)
+class AutoflakeConfig(BaseFormatterConfig):
+    table_path: ClassVar[str] = "tool.autoflake"
+
+    in_place: bool | None = True
+    recursive: bool | None = True
+    remove_all_unused_imports: bool | None = field(
+        default=True, metadata={"toml": "remove-all-unused-imports"}
+    )
+    remove_unused_variables: bool | None = field(
+        default=True, metadata={"toml": "remove-unused-variables"}
+    )
+
+    def command(self, py_paths: list[str], toml_paths: list[str]) -> list[str]:
+        return ["autoflake"] + py_paths
+
+
+@dataclass(kw_only=True)
+class IsortConfig(BaseFormatterConfig):
+    table_path: ClassVar[str] = "tool.isort"
+
+    profile: str | None = "black"
+    quiet: bool | None = True
+
+    def command(self, py_paths: list[str], toml_paths: list[str]) -> list[str]:
+        return ["isort"] + py_paths
+
+
+@dataclass(kw_only=True)
+class BlackConfig(BaseFormatterConfig):
+    table_path: ClassVar[str] = "tool.black"
+
+    quiet: bool | None = True
+
+    def extra_toml(self, project: ProjectConfig) -> dict[str, Any]:
+        return {"target-version": project.python.black_targets}
+
+    def command(self, py_paths: list[str], toml_paths: list[str]) -> list[str]:
+        return ["black"] + py_paths
+
+
+@dataclass(kw_only=True)
+class DocfmtConfig(BaseFormatterConfig):
+    table_path: ClassVar[str] = "tool.docfmt"
+
+    # docfmt returns 0 when it writes changes in-place; 1 means "would change"
+    # in check mode and 2 is an error, so only 0 is expected here
+    expect_rc: ClassVar[frozenset[int]] = frozenset({0})
+
+    # line length is left unset: docfmt picks it up from `[tool.black]`
+    in_place: bool | None = field(default=True, metadata={"toml": "in-place"})
+    recursive: bool | None = True
+    summary_on_own_line: bool | None = field(
+        default=True, metadata={"toml": "summary-on-own-line"}
+    )
+    force_reflow: bool | None = field(default=True, metadata={"toml": "force-reflow"})
+
+    def command(self, py_paths: list[str], toml_paths: list[str]) -> list[str]:
+        return ["docfmt"] + py_paths
+
+
+@dataclass(kw_only=True)
+class TomlSortConfig(BaseFormatterConfig):
+    table_path: ClassVar[str] = "tool.tomlsort"
+
+    sort_first: tuple[str, ...] | None = (
+        "project",
+        "dependency-groups",
+        "build-system",
+    )
+    sort_table_keys: bool | None = True
+
+    # explicit since the toml-sort CLI and library defaults disagree; must be
+    # pinned so the sync engine's normalization and the format task agree
+    spaces_before_inline_comment: int | None = 2
+
+    def command(self, py_paths: list[str], toml_paths: list[str]) -> list[str]:
+        return ["toml-sort", "-i"] + toml_paths
+
+
+# --- non-formatter tools ---
+
+
+@dataclass(kw_only=True)
+class PytestConfig(BaseToolConfig):
+    table_path: ClassVar[str] = "tool.pytest.ini_options"
+
+    addopts: str | None = "--import-mode=importlib -s -v -rA"
+    cache_dir: str | None = str(_paths.PYTEST_CACHE_PATH)
+    testpaths: str | None = "test"
+
+
+@dataclass(kw_only=True)
+class CoverageRunConfig(BaseToolConfig):
+    table_path: ClassVar[str] = "tool.coverage.run"
+
+    data_file: str | None = str(_paths.COVERAGE_DATA_PATH)
+
+
+@dataclass(kw_only=True)
+class CoverageReportConfig(BaseToolConfig):
+    table_path: ClassVar[str] = "tool.coverage.report"
+
+    exclude_lines: tuple[str, ...] | None = (
+        "if TYPE_CHECKING:",
+        "\\.\\.\\.$",
+    )
+
+
+@dataclass(kw_only=True)
+class DoitConfig(BaseToolConfig):
+    table_path: ClassVar[str] = "tool.doit"
+
+    dep_file: str | None = str(_paths.DOIT_DB_PATH)
+    verbosity: int | None = 2
+
+
+@dataclass(kw_only=True)
+class NoxConfig(BaseToolConfig):
+    table_path: ClassVar[str] = "tool.nox"
+
+    default_venv_backend: str | None = "uv"
+    envdir: str | None = str(_paths.NOX_ENVDIR_PATH)
+
+
+@dataclass(kw_only=True)
+class MypyConfig(BaseToolConfig):
+    table_path: ClassVar[str] = "tool.mypy"
+
+    ignore_missing_imports: bool | None = True
+
+    def extra_toml(self, project: ProjectConfig) -> dict[str, Any]:
+        return {"python_version": project.python.mypy_version}

pyprojkit/discovery.py

@@ -0,0 +1,51 @@
+"""
+Discovery of a project's `pyprojconf.py`.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import sys
+from pathlib import Path
+
+from .config.base import ConfigError
+from .config.project import ProjectConfig
+
+__all__ = [
+    "load_config",
+]
+
+CONF_FILENAME = "pyprojconf.py"
+
+
+def load_config(root: Path | str | None = None) -> ProjectConfig:
+    """
+    Load `pyprojconf.py` from the given project root (defaulting to the current
+    directory) and return its `config`.
+    """
+    root_path = Path(root) if root else Path.cwd()
+    conf_path = root_path / CONF_FILENAME
+
+    if not conf_path.is_file():
+        raise ConfigError(f"'{conf_path}' not found")
+
+    module_name = f"_pyprojconf_{abs(hash(str(conf_path.resolve())))}"
+    spec = importlib.util.spec_from_file_location(module_name, conf_path)
+    assert spec and spec.loader
+
+    module = importlib.util.module_from_spec(spec)
+    sys.modules[module_name] = module
+    try:
+        spec.loader.exec_module(module)
+    except Exception as exc:
+        raise ConfigError(f"Failed to import '{conf_path}': {exc}") from exc
+    finally:
+        sys.modules.pop(module_name, None)
+
+    config = getattr(module, "config", None)
+    if not isinstance(config, ProjectConfig):
+        raise ConfigError(
+            f"'{conf_path}' must define a module-level `config: ProjectConfig`"
+        )
+
+    return config

pyprojkit/sessions.py

@@ -0,0 +1,71 @@
+"""
+`nox` session factories.
+
+Usage in a project's `noxfile.py`:
+
+```python
+from pyprojkit import NoxFactory
+
+test = NoxFactory().create_test_session()
+```
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Callable
+
+import nox
+from nox import Session
+
+from .config.base import ConfigError
+from .config.project import ProjectConfig
+from .discovery import load_config
+
+__all__ = [
+    "NoxFactory",
+]
+
+
+class NoxFactory:
+    """
+    Factory for `nox` sessions, configured by the project's `pyprojconf.py`.
+
+    Sessions are registered with nox upon creation, so `create_*_session()` must be
+    called at `noxfile.py` import time.
+    """
+
+    _config: ProjectConfig
+    _registered: set[str]
+
+    def __init__(
+        self,
+        config: ProjectConfig | None = None,
+        root: Path | str | None = None,
+    ):
+        self._config = config or load_config(root)
+        self._registered = set()
+        nox.options.envdir = self._config.tools.nox.envdir
+
+    def create_test_session(self, *, group: str = "dev") -> Callable[[Session], None]:
+        """
+        Create and register `test` session which runs pytest over all supported Python
+        versions, installing dependencies from the given dependency group via uv.
+        """
+        if "test" in self._registered:
+            raise ConfigError("Session 'test' already created")
+        self._registered.add("test")
+
+        @nox.session(python=self._config.python.pins, name="test")
+        def test(session: Session):
+            session.run_install(
+                "uv",
+                "sync",
+                f"--group={group}",
+                "--frozen",
+                f"--python={session.python}",  # explicitly pin the version
+                env={"UV_PROJECT_ENVIRONMENT": session.virtualenv.location},
+            )
+            session.run("pytest", *session.posargs)
+
+        return test