pyprojkit 0.2.0__tar.gz → 0.3.1__tar.gz

{pyprojkit-0.2.0 → pyprojkit-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyprojkit
-Version: 0.2.0
+Version: 0.3.1
 Summary: Development workflow toolkit for Python projects: pyproject.toml sync, doit tasks, nox sessions
 Author: mm21
 Author-email: mm21 <mm21.dev@gmail.com>
@@ -27,7 +27,7 @@ Requires-Dist: pyright>=1.1.329,<2 ; extra == 'analysis'
 Requires-Dist: mkinit ; extra == 'doc'
 Requires-Dist: autoflake>=2.3.1,<3 ; extra == 'format'
 Requires-Dist: black>=25.1.0,<26 ; extra == 'format'
-Requires-Dist: docformatter>=1.7.7,<2 ; extra == 'format'
+Requires-Dist: docfmt>=0.2.0,<0.3.0 ; extra == 'format'
 Requires-Dist: isort>=6.0.1,<7 ; extra == 'format'
 Requires-Dist: genbadge[tests,coverage]>=1.1.0,<2 ; extra == 'test'
 Requires-Dist: pytest>=8.4.2,<9 ; extra == 'test'
@@ -160,7 +160,7 @@ python = PythonVersions(3, (12, 14), patch_overrides={(3, 14): "3.14.7"})
 
 Tool configurations are grouped by category under `ToolsConfig`, whose defaults constitute the default *profile*:
 
-- `formatting`: ordered chain of formatters; by default autoflake &rarr; isort &rarr; black &rarr; docformatter &rarr; toml-sort
+- `formatting`: ordered chain of formatters; by default autoflake &rarr; isort &rarr; docfmt &rarr; black &rarr; toml-sort
 - `test`: pytest + coverage settings
 - `doit`, `nox`: cache locations and backends
 - `doc`: documentation tools — mkinit (enabled by default) and sphinx (opt-in)

{pyprojkit-0.2.0 → pyprojkit-0.3.1}/README.md

@@ -117,7 +117,7 @@ python = PythonVersions(3, (12, 14), patch_overrides={(3, 14): "3.14.7"})
 
 Tool configurations are grouped by category under `ToolsConfig`, whose defaults constitute the default *profile*:
 
-- `formatting`: ordered chain of formatters; by default autoflake → isort → black → docformatter → toml-sort
+- `formatting`: ordered chain of formatters; by default autoflake → isort → docfmt → black → toml-sort
 - `test`: pytest + coverage settings
 - `doit`, `nox`: cache locations and backends
 - `doc`: documentation tools — mkinit (enabled by default) and sphinx (opt-in)

{pyprojkit-0.2.0 → pyprojkit-0.3.1}/pyproject.toml

@@ -27,7 +27,7 @@ license-files = ["LICENSE"]
 name = "pyprojkit"
 readme = "README.md"
 requires-python = ">=3.12,<3.15"  # managed by pyprojkit
-version = "0.2.0"
+version = "0.3.1"
 
 [project.optional-dependencies]
 all = [
@@ -43,7 +43,7 @@ doc = [
 format = [
   "autoflake>=2.3.1,<3",
   "black>=25.1.0,<26",
-  "docformatter>=1.7.7,<2",
+  "docfmt>=0.2.0,<0.3.0",
   "isort>=6.0.1,<7"
 ]
 test = [
@@ -90,13 +90,11 @@ exclude_lines = [
 [tool.coverage.run]  # managed by pyprojkit
 data_file = "__cache__/.coverage"
 
-[tool.docformatter]  # managed by pyprojkit
-black = true
+[tool.docfmt]  # managed by pyprojkit
+force-reflow = true
 in-place = true
-make-summary-multi-line = true
-non-strict = true
-pre-summary-newline = true
 recursive = true
+summary-on-own-line = true
 
 [tool.doit]  # managed by pyprojkit
 dep_file = "__cache__/.doit.db"
@@ -116,7 +114,7 @@ managed = [
   "tool.black",
   "tool.coverage.report",
   "tool.coverage.run",
-  "tool.docformatter",
+  "tool.docfmt",
   "tool.doit",
   "tool.isort",
   "tool.nox",
@@ -139,5 +137,4 @@ sort_table_keys = true
 spaces_before_inline_comment = 2
 
 [tool.uv.sources]
-docformatter = {git = "https://github.com/mm21/docformatter.git"}
 mkinit = {git = "https://github.com/mm21/mkinit.git"}

{pyprojkit-0.2.0 → pyprojkit-0.3.1}/src/pyprojkit/__init__.py

@@ -27,7 +27,7 @@ from .config import (
     AutoflakeConfig,
     IsortConfig,
     BlackConfig,
-    DocformatterConfig,
+    DocfmtConfig,
     TomlSortConfig,
     PytestConfig,
     CoverageRunConfig,
@@ -74,7 +74,7 @@ __all__ = [
     "AutoflakeConfig",
     "IsortConfig",
     "BlackConfig",
-    "DocformatterConfig",
+    "DocfmtConfig",
     "TomlSortConfig",
     "PytestConfig",
     "CoverageRunConfig",

{pyprojkit-0.2.0 → pyprojkit-0.3.1}/src/pyprojkit/config/__init__.py

@@ -20,7 +20,7 @@ from .tools import (
     AutoflakeConfig,
     IsortConfig,
     BlackConfig,
-    DocformatterConfig,
+    DocfmtConfig,
     TomlSortConfig,
     PytestConfig,
     CoverageRunConfig,
@@ -54,7 +54,7 @@ __all__ = [
     "AutoflakeConfig",
     "IsortConfig",
     "BlackConfig",
-    "DocformatterConfig",
+    "DocfmtConfig",
     "TomlSortConfig",
     "PytestConfig",
     "CoverageRunConfig",

{pyprojkit-0.2.0 → pyprojkit-0.3.1}/src/pyprojkit/config/base.py

@@ -27,13 +27,13 @@ class ConfigError(Exception):
 @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]`.
+    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()`.
+    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]

{pyprojkit-0.2.0 → pyprojkit-0.3.1}/src/pyprojkit/config/profiles.py

@@ -1,9 +1,9 @@
 """
 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:
+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
@@ -21,7 +21,7 @@ from .project import FormattingConfig, ToolsConfig
 from .tools import (
     AutoflakeConfig,
     BlackConfig,
-    DocformatterConfig,
+    DocfmtConfig,
     IsortConfig,
     TomlSortConfig,
 )
@@ -39,7 +39,7 @@ def _default_formatting() -> FormattingConfig:
         formatters=(
             AutoflakeConfig(),
             IsortConfig(),
-            DocformatterConfig(),
+            DocfmtConfig(),
             BlackConfig(),
             TomlSortConfig(),
         )

{pyprojkit-0.2.0 → pyprojkit-0.3.1}/src/pyprojkit/config/project.py

@@ -189,19 +189,23 @@ class ProjectConfig:
     """
     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.

{pyprojkit-0.2.0 → pyprojkit-0.3.1}/src/pyprojkit/config/tools.py

@@ -19,7 +19,7 @@ __all__ = [
     "AutoflakeConfig",
     "IsortConfig",
     "BlackConfig",
-    "DocformatterConfig",
+    "DocfmtConfig",
     "TomlSortConfig",
     "PytestConfig",
     "CoverageRunConfig",
@@ -75,25 +75,23 @@ class BlackConfig(BaseFormatterConfig):
 
 
 @dataclass(kw_only=True)
-class DocformatterConfig(BaseFormatterConfig):
-    table_path: ClassVar[str] = "tool.docformatter"
+class DocfmtConfig(BaseFormatterConfig):
+    table_path: ClassVar[str] = "tool.docfmt"
 
-    # docformatter returns 3 when files were changed
-    expect_rc: ClassVar[frozenset[int]] = frozenset({0, 3})
+    # 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})
 
-    black: bool | None = True
+    # line length is left unset: docfmt picks it up from `[tool.black]`
     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
+    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 ["docformatter"] + py_paths
+        return ["docfmt"] + py_paths
 
 
 @dataclass(kw_only=True)

{pyprojkit-0.2.0 → pyprojkit-0.3.1}/src/pyprojkit/sync.py

@@ -5,16 +5,16 @@ Managed content:
 
 - `project.requires-python`
 - Python version classifiers (`Programming Language :: Python :: 3[.X]`);
-  other classifiers are left untouched
+  other classifiers are left untouched, as are comments in the list
 - 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.
+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
@@ -22,11 +22,11 @@ from __future__ import annotations
 import difflib
 import re
 from pathlib import Path
-from typing import Any, cast
+from typing import Any
 
 import tomlkit
 from tomlkit import TOMLDocument
-from tomlkit.items import Table
+from tomlkit.items import Null, Table
 
 from .config.base import ConfigError
 from .config.project import ProjectConfig
@@ -140,22 +140,74 @@ 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.
+
+    Comments in the existing list are preserved: an inline comment stays with its entry,
+    and a standalone comment stays with the entry it precedes (or is emitted at the end
+    of the list if it precedes none).
     """
-    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)
+    existing = project.get("classifiers", [])
+    kept = [str(c) for c in existing if not _CLASSIFIER_RE.match(str(c))]
+    leading, inline, trailing = _collect_classifier_comments(
+        existing, set(kept) | managed
+    )
 
     array = tomlkit.array()
     for entry in sorted(set(kept) | managed):
+        for comment in leading.get(entry, []):
+            array.add_line(comment=comment, indent="  ")
         array.add_line(
             entry,
             indent="  ",
-            comment=_MANAGED_COMMENT if entry in managed else None,
+            comment=_MANAGED_COMMENT if entry in managed else inline.get(entry),
         )
+    for comment in trailing:
+        array.add_line(comment=comment, indent="  ")
     array.add_line(indent="")
     project["classifiers"] = array
 
 
+def _collect_classifier_comments(
+    array: Any, surviving: set[str]
+) -> tuple[dict[str, list[str]], dict[str, str], list[str]]:
+    """
+    Extract comments from an existing classifiers array, anchored to the entries they
+    accompany. Comments attached to entries which don't survive the sync are carried
+    forward to the next surviving entry.
+    """
+    leading: dict[str, list[str]] = {}
+    inline: dict[str, str] = {}
+    pending: list[str] = []
+
+    for group in getattr(array, "_value", []):
+        comment = _comment_text(group)
+        if group.value is None or isinstance(group.value, Null):
+            # standalone comment line
+            if comment:
+                pending.append(comment)
+            continue
+
+        entry = str(group.value)
+        if entry in surviving:
+            if pending:
+                leading.setdefault(entry, []).extend(pending)
+                pending = []
+            if comment and comment != _MANAGED_COMMENT:
+                inline[entry] = comment
+        elif comment and comment != _MANAGED_COMMENT:
+            # entry is going away; keep its comment as a standalone one
+            pending.append(comment)
+
+    return leading, inline, pending
+
+
+def _comment_text(group: Any) -> str | None:
+    comment = getattr(group, "comment", None)
+    if comment is None:
+        return None
+    return comment.trivia.comment.lstrip("#").strip() or None
+
+
 def _get_managed_list(doc: TOMLDocument) -> list[str]:
     try:
         return list(doc["tool"]["pyprojkit"]["managed"])  # type: ignore[index]