pyprojkit 0.3.0__py3-none-any.whl

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()

pyprojkit/tasks.py

@@ -0,0 +1,393 @@
+"""
+`doit` task factories.
+
+Usage in a project's `dodo.py`:
+
+```python
+from pyprojkit import TaskFactory
+
+factory = TaskFactory()  # auto-loads ./pyprojconf.py
+
+task_sync = factory.create_sync_task()
+task_format = factory.create_format_task()
+task_test = factory.create_test_task()
+task_badges = factory.create_badges_task()
+task_publish = factory.create_publish_task()
+```
+
+or equivalently: `globals().update(factory.create_all_tasks())`.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import xml.etree.ElementTree as ET
+from pathlib import Path
+from typing import Callable
+
+from doit import task_params
+from doit.task import Task
+from doit.tools import create_folder
+
+from . import _paths
+from ._run import cleanup_dir, run
+from .config.base import ConfigError
+from .config.project import ProjectConfig
+from .discovery import load_config
+from .sync import sync
+
+__all__ = [
+    "TaskFactory",
+]
+
+type TaskCreator = Callable[..., Task]
+
+
+def _normalize_svg(path: Path | str):
+    """
+    Rewrite SVG with attributes sorted, as genbadge doesn't order them
+    deterministically.
+    """
+    ET.register_namespace("", "http://www.w3.org/2000/svg")
+    ET.register_namespace("xlink", "http://www.w3.org/1999/xlink")
+    tree = ET.parse(path)
+    for elem in tree.iter():
+        attrib = sorted(elem.attrib.items())
+        elem.attrib.clear()
+        elem.attrib.update(attrib)
+    tree.write(path, encoding="unicode")
+
+
+class TaskFactory:
+    """
+    Factory for `doit` tasks, configured by the project's `pyprojconf.py`.
+    """
+
+    _config: ProjectConfig
+    _root: Path
+
+    def __init__(
+        self,
+        config: ProjectConfig | None = None,
+        root: Path | str | None = None,
+    ):
+        self._root = Path(root) if root else Path.cwd()
+        self._config = config or load_config(self._root)
+        _paths.CACHE_PATH.mkdir(parents=True, exist_ok=True)
+
+    def create_sync_task(self) -> TaskCreator:
+        """
+        Create `sync` task which updates `pyproject.toml` from `pyprojconf.py`.
+        """
+        config, root = self._config, self._root
+
+        def task_sync() -> Task:
+            return Task(
+                "sync",
+                actions=[(sync, (config, root))],
+                targets=[],
+                file_dep=[],
+                doc="Sync pyproject.toml from pyprojconf.py",
+            )
+
+        return task_sync
+
+    def create_format_task(self) -> TaskCreator:
+        """
+        Create `format` task which runs the configured formatters.
+        """
+        config, root = self._config, self._root
+
+        def task_format() -> Task:
+            # aggregate files to format
+            py_paths = [str(p) for p in sorted(root.glob("*.py"))] + [
+                path for path in config.format_paths if (root / path).is_dir()
+            ]
+            toml_paths = [str(p) for p in sorted(root.glob("*.toml"))]
+
+            actions = [
+                (
+                    run,
+                    (formatter.command(py_paths, toml_paths), set(formatter.expect_rc)),
+                )
+                for formatter in config.tools.formatting.formatters
+            ]
+
+            return Task(
+                "format",
+                actions=actions,
+                targets=[],
+                file_dep=[],
+                doc="Run formatters",
+            )
+
+        return task_format
+
+    def create_test_task(self) -> TaskCreator:
+        """
+        Create `test` task which runs pytest and generates coverage reports.
+        """
+        self._require(self._config.tools.test, "tools.test")
+
+        def task_test() -> Task:
+            args = [
+                "pytest",
+                f"--cov={self._config.package}",
+                f"--cov-report=html:{_paths.COV_HTML_PATH}",
+                f"--cov-report=xml:{_paths.COV_XML_PATH}",
+                f"--junitxml={_paths.JUNIT_PATH}",
+            ]
+
+            return Task(
+                "test",
+                actions=[
+                    (create_folder, [_paths.COV_PATH]),
+                    (run, (args,)),
+                ],
+                targets=[
+                    f"{_paths.COV_HTML_PATH}/index.html",
+                    str(_paths.COV_XML_PATH),
+                    str(_paths.JUNIT_PATH),
+                ],
+                file_dep=[],
+                clean=[(cleanup_dir, [_paths.TESTS_PATH])],
+                doc="Run pytest and generate coverage reports",
+            )
+
+        return task_test
+
+    def create_badges_task(self) -> TaskCreator:
+        """
+        Create `badges` task which generates badges from test results.
+        """
+        self._require(self._config.tools.test, "tools.test")
+
+        def task_badges() -> Task:
+            tests_args = [
+                "genbadge",
+                "tests",
+                "-i",
+                str(_paths.JUNIT_PATH),
+                "-o",
+                str(_paths.PYTEST_BADGE_PATH),
+            ]
+
+            cov_args = [
+                "genbadge",
+                "coverage",
+                "-i",
+                str(_paths.COV_XML_PATH),
+                "-o",
+                str(_paths.COV_BADGE_PATH),
+            ]
+
+            return Task(
+                "badges",
+                actions=[
+                    (create_folder, [_paths.BADGES_PATH]),
+                    (run, (tests_args,)),
+                    (run, (cov_args,)),
+                    (_normalize_svg, [_paths.PYTEST_BADGE_PATH]),
+                    (_normalize_svg, [_paths.COV_BADGE_PATH]),
+                ],
+                targets=[
+                    str(_paths.PYTEST_BADGE_PATH),
+                    str(_paths.COV_BADGE_PATH),
+                ],
+                file_dep=[
+                    str(_paths.JUNIT_PATH),
+                    str(_paths.COV_XML_PATH),
+                ],
+                doc="Generate badges from test results",
+            )
+
+        return task_badges
+
+    def create_publish_task(self) -> TaskCreator:
+        """
+        Create `publish` task which builds and publishes the package via uv.
+        """
+        out_dir = Path(self._config.tools.publish.out_dir)
+
+        def _publish():
+            artifacts = [str(p) for p in sorted(out_dir.iterdir())]
+            assert artifacts, f"No build artifacts in {out_dir}"
+            run(["uv", "publish", *artifacts])
+
+        def task_publish() -> Task:
+            return Task(
+                "publish",
+                actions=[
+                    # clean first so stale artifacts are never published
+                    (cleanup_dir, [out_dir]),
+                    (run, (["uv", "build", "--out-dir", str(out_dir)],)),
+                    (_publish,),
+                ],
+                targets=[],
+                file_dep=[],
+                doc="Build and publish package via uv",
+            )
+
+        return task_publish
+
+    def create_init_task(self) -> TaskCreator:
+        """
+        Create `init` task which generates `__init__.py` files using mkinit.
+        """
+        mkinit = self._require(self._config.tools.doc.mkinit, "tools.doc.mkinit")
+        package_path = self._config.package_path
+
+        def task_init() -> Task:
+            return Task(
+                "init",
+                actions=[
+                    (run, (["mkinit", str(package_path), *mkinit.args],)),
+                ],
+                targets=[],
+                file_dep=[],
+                doc="Generate __init__.py files using mkinit",
+            )
+
+        return task_init
+
+    def create_doc_task(self) -> TaskCreator:
+        """
+        Create `doc` task which builds documentation using sphinx.
+        """
+        sphinx = self._require(self._config.tools.doc.sphinx, "tools.doc.sphinx")
+
+        def _do_copy(copy: bool):
+            if not copy:
+                return
+
+            from dotenv import load_dotenv
+
+            load_dotenv()
+
+            assert sphinx.copy_env_var, "No copy_env_var configured"
+            dest = os.environ.get(sphinx.copy_env_var)
+            assert dest, f"Environment variable {sphinx.copy_env_var} not set"
+
+            dest_path = Path(dest)
+            assert dest_path.is_dir()
+
+            # clean destination
+            for path in dest_path.iterdir():
+                if path.is_file():
+                    path.unlink()
+                else:
+                    shutil.rmtree(path)
+
+            shutil.copytree(_paths.DOC_HTML_PATH, dest, dirs_exist_ok=True)
+
+            print(f"\nCopied: {_paths.DOC_HTML_PATH} -> {dest}")
+
+        @task_params(
+            [
+                {
+                    "name": "copy",
+                    "long": "copy",
+                    "type": bool,
+                    "default": False,
+                    "help": "Copy to output folder after build",
+                }
+            ]
+        )
+        def task_doc(copy: bool) -> Task:
+            args = [
+                "sphinx-build",
+                "-T",  # show full traceback upon error
+                sphinx.source_dir,
+                str(_paths.DOC_HTML_PATH),
+            ]
+
+            return Task(
+                "doc",
+                actions=[
+                    (create_folder, [_paths.DOC_HTML_PATH]),
+                    (run, (args,)),
+                    (_do_copy, (copy,)),
+                ],
+                targets=[
+                    f"{_paths.DOC_HTML_PATH}/index.html",
+                ],
+                file_dep=[],
+                clean=[(cleanup_dir, [_paths.DOC_HTML_PATH])],
+                doc="Generate documentation",
+            )
+
+        return task_doc
+
+    def create_analysis_task(self) -> TaskCreator:
+        """
+        Create `analysis` task which runs static analysis tools.
+        """
+        analysis = self._require(self._config.tools.analysis, "tools.analysis")
+        package_path = self._config.package_path
+
+        def task_analysis() -> Task:
+            actions = []
+
+            if analysis.mypy:
+                actions.append(
+                    (
+                        run,
+                        (
+                            [
+                                "mypy",
+                                "--html-report",
+                                str(_paths.MYPY_HTML_PATH),
+                                "--cobertura-xml-report",
+                                str(_paths.MYPY_XML_PATH),
+                                str(package_path),
+                            ],
+                        ),
+                    )
+                )
+
+            if analysis.pyright:
+                actions.append((run, (["pyright", str(package_path)],)))
+
+            return Task(
+                "analysis",
+                actions=actions,
+                targets=[],
+                file_dep=[],
+                doc="Run static analysis tools",
+            )
+
+        return task_analysis
+
+    def create_all_tasks(self) -> dict[str, TaskCreator]:
+        """
+        Create all tasks enabled by the configuration, keyed by `task_<name>` suitable
+        for `globals().update(...)` in `dodo.py`.
+        """
+        tools = self._config.tools
+
+        creators: dict[str, TaskCreator] = {
+            "task_sync": self.create_sync_task(),
+            "task_format": self.create_format_task(),
+            "task_publish": self.create_publish_task(),
+        }
+
+        if tools.test:
+            creators["task_test"] = self.create_test_task()
+            creators["task_badges"] = self.create_badges_task()
+
+        if tools.doc.mkinit:
+            creators["task_init"] = self.create_init_task()
+
+        if tools.doc.sphinx:
+            creators["task_doc"] = self.create_doc_task()
+
+        if tools.analysis:
+            creators["task_analysis"] = self.create_analysis_task()
+
+        return creators
+
+    def _require[T](self, value: T | None, name: str) -> T:
+        if value is None:
+            raise ConfigError(f"Configuration does not set `{name}`")
+        return value