pyprojkit 0.1.0__py3-none-any.whl

pyprojkit/config/tools.py

@@ -0,0 +1,170 @@
+"""
+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",
+    "DocformatterConfig",
+    "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 DocformatterConfig(BaseFormatterConfig):
+    table_path: ClassVar[str] = "tool.docformatter"
+
+    # docformatter returns 3 when files were changed
+    expect_rc: ClassVar[frozenset[int]] = frozenset({0, 3})
+
+    black: bool | None = True
+    in_place: bool | None = field(default=True, metadata={"toml": "in-place"})
+    make_summary_multi_line: bool | None = field(
+        default=True, metadata={"toml": "make-summary-multi-line"}
+    )
+    non_strict: bool | None = field(default=True, metadata={"toml": "non-strict"})
+    pre_summary_newline: bool | None = field(
+        default=True, metadata={"toml": "pre-summary-newline"}
+    )
+    recursive: bool | None = True
+
+    def command(self, py_paths: list[str], toml_paths: list[str]) -> list[str]:
+        return ["docformatter"] + 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

pyprojkit/sync.py

@@ -0,0 +1,243 @@
+"""
+Sync engine: writes managed parts of `pyproject.toml` from a project's `pyprojconf.py`.
+
+Managed content:
+
+- `project.requires-python`
+- Python version classifiers (`Programming Language :: Python :: 3[.X]`);
+  other classifiers are left untouched
+- One `[tool.X]` table per enabled tool (fully owned — any hand edits or
+  comments inside are overwritten)
+- `[tool.pyprojkit].managed`: bookkeeping list of owned tables, enabling safe
+  removal of tables for tools dropped from the configuration
+
+Everything else (dependencies, build-system, urls, unmanaged tool tables,
+etc.) is preserved. Output is normalized with toml-sort (as a library, using
+the same settings as the managed `[tool.tomlsort]` table), so a subsequent
+`toml-sort` run in the format task is a no-op.
+"""
+
+from __future__ import annotations
+
+import difflib
+import re
+from pathlib import Path
+from typing import Any, cast
+
+import tomlkit
+from tomlkit import TOMLDocument
+from tomlkit.items import Table
+
+from .config.base import ConfigError
+from .config.project import ProjectConfig
+from .config.tools import TomlSortConfig
+
+__all__ = [
+    "compute_managed_tables",
+    "render",
+    "sync",
+]
+
+_CLASSIFIER_RE = re.compile(r"^Programming Language :: Python :: \d+(\.\d+)?$")
+
+_MANAGED_COMMENT = "managed by pyprojkit"
+
+
+def compute_managed_tables(config: ProjectConfig) -> dict[str, dict[str, Any]]:
+    """
+    Compute contents of all managed tables, keyed by dotted table path.
+    """
+    tables: dict[str, dict[str, Any]] = {}
+    tools = config.tools
+
+    for formatter in tools.formatting.formatters:
+        tables[formatter.table_path] = formatter.to_toml(config)
+
+    if test := tools.test:
+        for tool in (test.pytest, test.coverage_run, test.coverage_report):
+            tables[tool.table_path] = tool.to_toml(config)
+
+    tables[tools.doit.table_path] = tools.doit.to_toml(config)
+    tables[tools.nox.table_path] = tools.nox.to_toml(config)
+
+    if (analysis := tools.analysis) and analysis.mypy:
+        tables[analysis.mypy.table_path] = analysis.mypy.to_toml(config)
+
+    # merge escape-hatch overrides last; unknown paths become managed tables
+    for path, overrides in tools.tool_overrides.items():
+        tables.setdefault(path, {}).update(overrides)
+
+    return tables
+
+
+def render(config: ProjectConfig, text: str) -> str:
+    """
+    Render the synced `pyproject.toml` contents from existing contents.
+    """
+    doc = tomlkit.parse(text)
+
+    project = doc.get("project")
+    if project is None:
+        raise ConfigError("pyproject.toml has no [project] table")
+
+    project["requires-python"] = config.python.requires_python
+    project["requires-python"].comment(_MANAGED_COMMENT)
+    _update_classifiers(project, config)
+
+    tables = compute_managed_tables(config)
+
+    prev_managed = _get_managed_list(doc)
+    for path in prev_managed:
+        if path not in tables:
+            _delete_table(doc, path)
+
+    for path, content in tables.items():
+        _set_table(doc, path, content)
+
+    _set_table(doc, "tool.pyprojkit", {"managed": sorted(tables)})
+
+    return _normalize(config, tomlkit.dumps(doc))
+
+
+def sync(
+    config: ProjectConfig,
+    root: Path | str | None = None,
+    *,
+    check: bool = False,
+) -> bool:
+    """
+    Sync `pyproject.toml` under the given project root (defaulting to the current
+    directory).
+
+    In check mode, nothing is written; prints a diff and returns `False` if out of sync.
+    In write mode, returns `True` (having updated the file if needed).
+    """
+    path = (Path(root) if root else Path.cwd()) / "pyproject.toml"
+    if not path.is_file():
+        raise ConfigError(f"'{path}' not found")
+
+    old = path.read_text()
+    new = render(config, old)
+
+    if old == new:
+        return True
+
+    if check:
+        diff = difflib.unified_diff(
+            old.splitlines(keepends=True),
+            new.splitlines(keepends=True),
+            fromfile="pyproject.toml (on disk)",
+            tofile="pyproject.toml (synced)",
+        )
+        print("".join(diff), end="")
+        return False
+
+    path.write_text(new)
+    return True
+
+
+def _update_classifiers(project: Table, config: ProjectConfig):
+    """
+    Replace python version classifiers with those derived from config, preserving all
+    others; result is sorted, with managed entries marked by an inline comment.
+    """
+    existing = cast(list[str], [str(c) for c in project.get("classifiers", [])])
+    kept = [c for c in existing if not _CLASSIFIER_RE.match(c)]
+    managed = set(config.python.classifiers)
+
+    array = tomlkit.array()
+    for entry in sorted(set(kept) | managed):
+        array.add_line(
+            entry,
+            indent="  ",
+            comment=_MANAGED_COMMENT if entry in managed else None,
+        )
+    array.add_line(indent="")
+    project["classifiers"] = array
+
+
+def _get_managed_list(doc: TOMLDocument) -> list[str]:
+    try:
+        return list(doc["tool"]["pyprojkit"]["managed"])  # type: ignore[index]
+    except (KeyError, TypeError):
+        return []
+
+
+def _set_table(doc: TOMLDocument, path: str, content: dict[str, Any]):
+    parts = path.split(".")
+    container: Any = doc
+    for part in parts[:-1]:
+        if part in container:
+            container = container[part]
+        else:
+            table = tomlkit.table(is_super_table=True)
+            container[part] = table
+            container = table
+
+    leaf = tomlkit.table()
+    leaf.comment(_MANAGED_COMMENT)
+    for key, value in content.items():
+        leaf[key] = _to_item(value)
+    container[parts[-1]] = leaf
+
+
+def _delete_table(doc: TOMLDocument, path: str):
+    parts = path.split(".")
+
+    # walk to leaf's parent
+    containers: list[Any] = [doc]
+    for part in parts[:-1]:
+        container = containers[-1].get(part)
+        if container is None:
+            return
+        containers.append(container)
+
+    if parts[-1] not in containers[-1]:
+        return
+    del containers[-1][parts[-1]]
+
+    # prune emptied parents (but never the document itself)
+    for i in range(len(containers) - 1, 0, -1):
+        if len(containers[i]) == 0:
+            del containers[i - 1][parts[i - 1]]
+
+
+def _to_item(value: Any) -> Any:
+    if isinstance(value, (list, tuple)):
+        array = tomlkit.array()
+        array.extend(value)
+        if len(array) >= 2:
+            array.multiline(True)
+        return array
+    return value
+
+
+def _normalize(config: ProjectConfig, text: str) -> str:
+    """
+    Normalize with toml-sort as a library, driven by the project's `TomlSortConfig`
+    (skipped if toml-sort is not among the formatters).
+    """
+    tomlsort_config = next(
+        (
+            f
+            for f in config.tools.formatting.formatters
+            if isinstance(f, TomlSortConfig)
+        ),
+        None,
+    )
+    if tomlsort_config is None:
+        return text
+
+    from toml_sort import TomlSort
+    from toml_sort.tomlsort import FormattingConfiguration, SortConfiguration
+
+    sort_config = SortConfiguration(
+        table_keys=bool(tomlsort_config.sort_table_keys),
+        first=list(tomlsort_config.sort_first or []),
+    )
+    format_config = FormattingConfiguration(
+        spaces_before_inline_comment=tomlsort_config.spaces_before_inline_comment or 1,
+    )
+    return TomlSort(
+        input_toml=text, sort_config=sort_config, format_config=format_config
+    ).sorted()