docwrap 0.2.0__tar.gz → 0.3.0__tar.gz

{docwrap-0.2.0 → docwrap-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: docwrap
-Version: 0.2.0
+Version: 0.3.0
 Summary: Wrap Python docstrings with support for Google, NumPy, and Sphinx styles
 Project-URL: Documentation, https://github.com/dactylo/docwrap/tree/main/docs
 Project-URL: Homepage, https://github.com/dactylo/docwrap
@@ -25,12 +25,12 @@ Google, NumPy, and Sphinx/reST conventions.
 
 Run `docwrap` to see which docstrings would change across your project:
 
-![docwrap summary of six Python files, with 10 of 32 docstrings requiring wrapping](https://raw.githubusercontent.com/dactylo/docwrap/v0.2.0/images/docwrap-summary.png)
+![docwrap summary of six Python files, with 10 of 32 docstrings requiring wrapping](https://raw.githubusercontent.com/dactylo/docwrap/v0.3.0/images/docwrap-summary.png)
 
 Then use `docwrap --preview` to compare the original and proposed formatting. For example, using
 the default 79-column limit:
 
-![docwrap preview showing prose and an argument description before and after reflow](https://raw.githubusercontent.com/dactylo/docwrap/v0.2.0/images/docwrap-preview.png)
+![docwrap preview showing prose and an argument description before and after reflow](https://raw.githubusercontent.com/dactylo/docwrap/v0.3.0/images/docwrap-preview.png)
 
 ## Installation
 
@@ -76,17 +76,17 @@ line-length = 88
 ```
 
 Configuration is discovered from each file's `pyproject.toml`. The
-[wrapping policy guide](https://github.com/dactylo/docwrap/blob/v0.2.0/docs/design.md#choosing-a-wrapping-policy) explains the tradeoffs between
-reflowing prose and preserving authored layout. See the [CLI reference](https://github.com/dactylo/docwrap/blob/v0.2.0/docs/cli.md) for output
+[wrapping policy guide](https://github.com/dactylo/docwrap/blob/v0.3.0/docs/design.md#choosing-a-wrapping-policy) explains the tradeoffs between
+reflowing prose and preserving authored layout. See the [CLI reference](https://github.com/dactylo/docwrap/blob/v0.3.0/docs/cli.md) for output
 modes, configuration precedence, and advanced options.
 
 ## Integrations and library use
 
 A local [pre-commit](https://pre-commit.com/) hook can run docwrap when you commit. See the
-[pre-commit setup](https://github.com/dactylo/docwrap/blob/v0.2.0/docs/hook.md#pre-commit) for a writing hook and its report-only variant. Agent
+[pre-commit setup](https://github.com/dactylo/docwrap/blob/v0.3.0/docs/hook.md#pre-commit) for a writing hook and its report-only variant. Agent
 hooks for Claude Code, Codex, and Antigravity can run before commits or after edits. Their
 installation, host settings, commit behavior, and composition limits are in the
-[agent hook guide](https://github.com/dactylo/docwrap/blob/v0.2.0/docs/hook.md).
+[agent hook guide](https://github.com/dactylo/docwrap/blob/v0.3.0/docs/hook.md).
 
 For Python callers, `wrap_source()` returns rewritten source, `check()` reports whether it would
 change, and `wrap_source_report()` supplies structured results:
@@ -99,28 +99,33 @@ result = docwrap.check(source)
 wrapped = docwrap.wrap_source(source)
 ```
 
-See the [library reference](https://github.com/dactylo/docwrap/blob/v0.2.0/docs/library.md) for file operations, configuration, result types, and
+See the [library reference](https://github.com/dactylo/docwrap/blob/v0.3.0/docs/library.md) for file operations, configuration, result types, and
 safety skips.
 
 ## Documentation
 
 | If you want to...                                      | Read                                       |
 | ------------------------------------------------------ | ------------------------------------------ |
-| Look up commands, output, configuration, or exit codes | [CLI reference](https://github.com/dactylo/docwrap/blob/v0.2.0/docs/cli.md)               |
-| Set up agent hooks, commit handling, or host responses | [Agent hook guide](https://github.com/dactylo/docwrap/blob/v0.2.0/docs/hook.md)           |
-| Wrap only changed files or definitions                 | [Incremental mode](https://github.com/dactylo/docwrap/blob/v0.2.0/docs/incremental.md)    |
-| Call docwrap from Python                               | [Library reference](https://github.com/dactylo/docwrap/blob/v0.2.0/docs/library.md)       |
-| Choose a style and understand what docwrap preserves   | [Concepts and safety](https://github.com/dactylo/docwrap/blob/v0.2.0/docs/design.md)      |
-| Check supported environments and file behavior         | [Platform compatibility](https://github.com/dactylo/docwrap/blob/v0.2.0/docs/platform.md) |
+| Look up commands, output, configuration, or exit codes | [CLI reference](https://github.com/dactylo/docwrap/blob/v0.3.0/docs/cli.md)               |
+| Set up agent hooks, commit handling, or host responses | [Agent hook guide](https://github.com/dactylo/docwrap/blob/v0.3.0/docs/hook.md)           |
+| Wrap only changed files or definitions                 | [Incremental mode](https://github.com/dactylo/docwrap/blob/v0.3.0/docs/incremental.md)    |
+| Call docwrap from Python                               | [Library reference](https://github.com/dactylo/docwrap/blob/v0.3.0/docs/library.md)       |
+| Choose a style and understand what docwrap preserves   | [Concepts and safety](https://github.com/dactylo/docwrap/blob/v0.3.0/docs/design.md)      |
+| Check supported environments and file behavior         | [Platform compatibility](https://github.com/dactylo/docwrap/blob/v0.3.0/docs/platform.md) |
 
 ## Development
 
-See the [development guide](https://github.com/dactylo/docwrap/blob/v0.2.0/docs/development.md) for pinned CI dependencies and lock updates.
+See the [development guide](https://github.com/dactylo/docwrap/blob/v0.3.0/docs/development.md) for pinned CI dependencies and lock updates.
 
-From the checkout, run `make check` for repository checks. Run `make format` to apply the
-repository's formatters. The Makefile also provides `make install`, `make reinstall`, and
-`make test`; install targets use uv.
+Run `make setup` with uv 0.13.6 to create the pinned `.venv` before project commands.
+`make install` and `make reinstall` install only the CLI through uv.
+
+```bash
+make quality # read-only quality checks
+make check   # quality checks and one full test run
+make format  # apply repository formatters
+```
 
 ## License
 
-docwrap is available under the [MIT License](https://github.com/dactylo/docwrap/blob/v0.2.0/LICENSE).
+docwrap is available under the [MIT License](https://github.com/dactylo/docwrap/blob/v0.3.0/LICENSE).

{docwrap-0.2.0 → docwrap-0.3.0}/README.md

@@ -98,9 +98,14 @@ safety skips.
 
 See the [development guide](docs/development.md) for pinned CI dependencies and lock updates.
 
-From the checkout, run `make check` for repository checks. Run `make format` to apply the
-repository's formatters. The Makefile also provides `make install`, `make reinstall`, and
-`make test`; install targets use uv.
+Run `make setup` with uv 0.13.6 to create the pinned `.venv` before project commands.
+`make install` and `make reinstall` install only the CLI through uv.
+
+```bash
+make quality # read-only quality checks
+make check   # quality checks and one full test run
+make format  # apply repository formatters
+```
 
 ## License
 

{docwrap-0.2.0 → docwrap-0.3.0}/_build.py

@@ -12,6 +12,17 @@ class PluginMetadataHook(MetadataHookInterface):
 
     @override
     def update(self, metadata: dict[str, object]) -> None:
+        """Replace distribution entry points with the bundled plugin registrations.
+
+        Args:
+            metadata: Distribution metadata to update in place.
+
+        Raises:
+            OSError: If a plugin manifest cannot be read.
+            tomllib.TOMLDecodeError: If a plugin manifest is invalid TOML.
+            ValueError: If two plugins register the same entry-point group and
+                name.
+        """
         metadata['entry-points'] = _plugin_entry_points(Path(self.root))
 
 

docwrap-0.3.0/plugins/agy/_docwrap/_adapter.py

@@ -0,0 +1,5 @@
+"""Translate Antigravity hook events for docwrap."""
+
+from docwrap._vendor.hookfront._agy import AntigravityAdapter
+
+__all__ = ['AntigravityAdapter']

docwrap-0.3.0/plugins/agy/tests/test_agy_adapter.py

@@ -0,0 +1,50 @@
+# pyright: reportPrivateUsage=false
+
+import json
+import shlex
+from pathlib import Path
+
+import pytest
+
+from docwrap._hook_front import _TOOL, _build_hook_parser
+from docwrap._vendor.hookfront._loader import load_adapter
+
+_ROOT = Path(__file__).resolve().parents[3]
+
+
+@pytest.mark.usefixtures('registered_hosts')
+def test_native_manifest_command_loads_this_adapter() -> None:
+    argv = shlex.split('docwrap hook --agent agy --event PreToolUse')
+    args = _build_hook_parser().parse_args(argv[2:])
+    adapter = load_adapter(_TOOL, args.agent)
+    assert adapter.name == 'agy'
+    assert args.event == 'PreToolUse'
+    assert adapter.requires_event
+
+
+def test_native_manifest_is_unchanged() -> None:
+    assert json.loads((_ROOT / 'plugins' / 'agy' / 'hooks.json').read_text(encoding='utf-8')) == {
+        'docwrap': {
+            'PreToolUse': [
+                {
+                    'matcher': 'run_command',
+                    'hooks': [
+                        {
+                            'type': 'command',
+                            'command': 'docwrap hook --agent agy --event PreToolUse',
+                        }
+                    ],
+                }
+            ]
+        }
+    }
+
+
+def test_native_plugin_identity_and_layout() -> None:
+    plugin = json.loads((_ROOT / 'plugins' / 'agy' / 'plugin.json').read_text(encoding='utf-8'))
+    assert set(plugin) == {'$schema', 'name', 'description'}
+    assert plugin['$schema'] == 'https://antigravity.google/schemas/v1/plugin.json'
+    assert plugin['name'] == 'docwrap-agy'
+    assert isinstance(plugin['description'], str)
+    assert plugin['description'].strip()
+    assert not (_ROOT / 'plugins' / 'agy' / 'hooks').exists()

{docwrap-0.2.0 → docwrap-0.3.0}/plugins/claude/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "docwrap",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Install the docwrap commit-time docstring wrapping hook for Claude Code.",
   "author": {
     "name": "docwrap contributors"

docwrap-0.3.0/plugins/claude/_docwrap/_adapter.py

@@ -0,0 +1,5 @@
+"""Translate Claude Code hook events for docwrap."""
+
+from docwrap._vendor.hookfront._claude import ClaudeAdapter
+
+__all__ = ['ClaudeAdapter']

docwrap-0.3.0/plugins/claude/tests/test_claude_adapter.py

@@ -0,0 +1,129 @@
+# pyright: reportPrivateUsage=false
+
+import json
+import shlex
+from pathlib import Path
+from typing import Literal
+
+import pytest
+
+from docwrap._hook_front import _TOOL, _build_hook_parser
+from docwrap._hook_front import _run_hook as run_hook
+from docwrap._vendor.hookfront._loader import load_adapter
+from tests.helpers import decode_text, git_commit_all, run_setup
+
+_ROOT = Path(__file__).resolve().parents[3]
+
+
+class TestClaudeAdapter:
+    @pytest.mark.usefixtures('example_hosts')
+    @pytest.mark.parametrize('host', ['claude', 'example'])
+    @pytest.mark.parametrize(
+        ('command', 'outcome'),
+        [
+            pytest.param('ls', 'unrelated', id='unrelated'),
+            pytest.param('git commit --future-option -m x', 'denied', id='denied'),
+            pytest.param('git commit -m x', 'wrapped', id='supported'),
+        ],
+    )
+    def test_hook_decisions_preserve_adapter_independence(
+        self,
+        tmp_path: Path,
+        capsys: pytest.CaptureFixture[str],
+        host: str,
+        command: str,
+        outcome: Literal['unrelated', 'denied', 'wrapped'],
+    ) -> None:
+        run_setup(['git', 'init'], cwd=tmp_path)
+        run_setup(['git', 'config', 'docwrap.hook', 'true'], cwd=tmp_path)
+        (tmp_path / 'pyproject.toml').write_text(
+            '[tool.docwrap]\nline-length = 40\nfill-style = "greedy"\n', encoding='utf-8'
+        )
+        target = tmp_path / 'sample.py'
+        target.write_text('pass\n', encoding='utf-8')
+        git_commit_all(tmp_path)
+        source = (
+            'def f():\n    """Summary.\n\n'
+            '    one two three four five six seven eight nine ten eleven twelve\n'
+            '    """\n'
+        )
+        target.write_text(source, encoding='utf-8')
+        run_setup(['git', 'add', 'sample.py'], cwd=tmp_path)
+        payload = json.dumps(
+            _payload('PreToolUse', 'Bash', {'command': command}) | {'cwd': str(tmp_path)}
+        )
+
+        status = run_hook(payload, host=host)
+
+        captured = capsys.readouterr()
+        expected_decision = 'deny' if outcome == 'denied' else None
+        assert (status, _decision(captured.out)) == (0, expected_decision)
+        if expected_decision == 'deny':
+            assert 'unsupported commit command' in captured.err
+        else:
+            assert captured.err == ''
+        expected = (
+            'def f():\n    """Summary.\n\n'
+            '    one two three four five six seven\n'
+            '    eight nine ten eleven twelve\n'
+            '    """\n'
+            if outcome == 'wrapped'
+            else source
+        )
+        staged = run_setup(['git', 'show', ':sample.py'], cwd=tmp_path)
+        assert decode_text(staged.stdout) == expected
+        assert target.read_text(encoding='utf-8') == expected
+
+
+def _decision(stdout: str) -> str | None:
+    if not stdout:
+        return None
+    data = json.loads(stdout)
+    if 'systemMessage' in data:
+        return None
+    if 'hookSpecificOutput' in data:
+        return str(data['hookSpecificOutput']['permissionDecision'])
+    return str(data['example']['decision'])
+
+
+def _payload(event: str, tool: str, tool_input: dict[str, object]) -> dict[str, object]:
+    return {'hook_event_name': event, 'tool_name': tool, 'tool_input': tool_input, 'cwd': '/r'}
+
+
+@pytest.mark.usefixtures('registered_hosts')
+def test_native_manifest_command_loads_this_adapter() -> None:
+    argv = shlex.split('docwrap hook --agent claude')
+    args = _build_hook_parser().parse_args(argv[2:])
+    adapter = load_adapter(_TOOL, args.agent)
+    assert adapter.name == 'claude'
+    assert args.event is None
+    assert not adapter.requires_event
+
+
+def test_native_manifest_is_unchanged() -> None:
+    manifest = _ROOT / 'plugins' / 'claude' / 'hooks' / 'hooks.json'
+    assert json.loads(manifest.read_text(encoding='utf-8')) == {
+        'hooks': {
+            'PreToolUse': [
+                {
+                    'matcher': '^Bash$',
+                    'hooks': [{'type': 'command', 'command': 'docwrap hook --agent claude'}],
+                }
+            ]
+        }
+    }
+
+
+def test_native_plugin_identity_and_marketplace_source() -> None:
+    plugin = json.loads(
+        (_ROOT / 'plugins' / 'claude' / '.claude-plugin' / 'plugin.json').read_text(
+            encoding='utf-8'
+        )
+    )
+    marketplace = json.loads(
+        (_ROOT / '.claude-plugin' / 'marketplace.json').read_text(encoding='utf-8')
+    )
+    assert plugin['name'] == 'docwrap'
+    assert marketplace['plugins'][0]['source'] == './plugins/claude'
+    assert not (_ROOT / 'plugins' / 'claude' / 'hooks.json').exists()
+    assert not (_ROOT / 'plugins' / 'claude' / '.codex-plugin').exists()

{docwrap-0.2.0 → docwrap-0.3.0}/plugins/codex/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "docwrap",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Install the docwrap commit-time docstring wrapping hook for Codex.",
   "author": {
     "name": "docwrap contributors"

docwrap-0.3.0/plugins/codex/_docwrap/_adapter.py

@@ -0,0 +1,5 @@
+"""Translate Codex hook events for docwrap."""
+
+from docwrap._vendor.hookfront._codex import CodexAdapter
+
+__all__ = ['CodexAdapter']

docwrap-0.3.0/plugins/codex/tests/test_codex_adapter.py

@@ -0,0 +1,50 @@
+# pyright: reportPrivateUsage=false
+
+import json
+import shlex
+from pathlib import Path
+
+import pytest
+
+from docwrap._hook_front import _TOOL, _build_hook_parser
+from docwrap._vendor.hookfront._loader import load_adapter
+
+_ROOT = Path(__file__).resolve().parents[3]
+
+
+@pytest.mark.usefixtures('registered_hosts')
+def test_native_manifest_command_loads_this_adapter() -> None:
+    argv = shlex.split('docwrap hook --agent codex')
+    args = _build_hook_parser().parse_args(argv[2:])
+    adapter = load_adapter(_TOOL, args.agent)
+    assert adapter.name == 'codex'
+    assert args.event is None
+    assert not adapter.requires_event
+
+
+def test_native_manifest_is_unchanged() -> None:
+    manifest = _ROOT / 'plugins' / 'codex' / 'hooks' / 'hooks.json'
+    assert json.loads(manifest.read_text(encoding='utf-8')) == {
+        'hooks': {
+            'PreToolUse': [
+                {
+                    'matcher': '^Bash$',
+                    'hooks': [{'type': 'command', 'command': 'docwrap hook --agent codex'}],
+                }
+            ]
+        }
+    }
+
+
+def test_native_plugin_identity_and_marketplace_source() -> None:
+    plugin = json.loads(
+        (_ROOT / 'plugins' / 'codex' / '.codex-plugin' / 'plugin.json').read_text(encoding='utf-8')
+    )
+    marketplace = json.loads(
+        (_ROOT / '.agents' / 'plugins' / 'marketplace.json').read_text(encoding='utf-8')
+    )
+    assert plugin['name'] == 'docwrap'
+    assert 'hooks' not in plugin
+    assert marketplace['plugins'][0]['source'] == {'source': 'local', 'path': './plugins/codex'}
+    assert not (_ROOT / 'plugins' / 'codex' / 'hooks.json').exists()
+    assert not (_ROOT / 'plugins' / 'codex' / '.claude-plugin').exists()

{docwrap-0.2.0 → docwrap-0.3.0}/pyproject.toml

@@ -10,7 +10,7 @@ requires = [ "editables~=0.3", "hatch-fancy-pypi-readme>=25.1", "hatchling>=1.27
 # ==========================================================
 [project]
 name = "docwrap"
-version = "0.2.0"
+version = "0.3.0"
 description = "Wrap Python docstrings with support for Google, NumPy, and Sphinx styles"
 keywords = [ "docstring", "formatter", "google", "numpy", "sphinx", "wrap" ]
 license = "MIT"
@@ -44,6 +44,7 @@ dev = [
   "pyright",
   "ruff",
   "vulture",
+  "zizmor",
   { include-group = "test" },
 ]
 test = [
@@ -103,9 +104,6 @@ lint.ignore = [
   "T201",   # print() found
   "TRY003", # Avoid specifying long messages outside exception class
 ]
-# Same-file private-member collaboration follows the module privacy boundary.
-lint.per-file-ignores."src/docwrap/_vendor/hookshell/_grammar.py" = [ "SLF001" ]
-lint.per-file-ignores."src/docwrap/_vendor/hookshell/_shellparse.py" = [ "SLF001" ]
 lint.per-file-ignores."{tests,plugins/*/tests}/**/*.py" = [
   "D",       # No docstrings required in tests
   "PLR2004", # Allow magic values in tests
@@ -139,6 +137,8 @@ max_supported_python = "3.15"
 # ==========================================================
 [tool.pyright]
 pythonVersion = "3.13"  # Keep in sync with tool.ruff.target-version
+venv = ".venv"  # Created by make setup
+venvPath = "."
 typeCheckingMode = "strict"
 extraPaths = [ ".", "src" ]
 executionEnvironments = [

{docwrap-0.2.0 → docwrap-0.3.0}/src/docwrap/__init__.py

@@ -18,6 +18,7 @@ if TYPE_CHECKING:
         DocwrapConfig,
         DocwrapConfigWarning,
         DocwrapSkipWarning,
+        FileChangedError,
         FillStyle,
         InvalidLineLengthError,
         ReflowMode,
@@ -45,6 +46,7 @@ __all__ = [
     'DocwrapConfig',
     'DocwrapConfigWarning',
     'DocwrapSkipWarning',
+    'FileChangedError',
     'FillStyle',
     'InvalidLineLengthError',
     'ReflowMode',

docwrap-0.3.0/src/docwrap/_canonical.py

@@ -0,0 +1,56 @@
+"""Canonical section registry for docstring roles."""
+
+from dataclasses import dataclass
+
+from docwrap._types import CanonicalRole
+
+
+@dataclass(frozen=True, slots=True)
+class _CanonicalSection:
+    """Registry entry whose tuple position determines canonical section order."""
+
+    role: CanonicalRole
+    google_header: str | None = None
+    numpy_header: str | None = None
+    return_like: bool = False
+
+
+CANONICAL_SECTIONS: tuple[_CanonicalSection, ...] = (
+    _CanonicalSection('param', google_header='Args', numpy_header='Parameters'),
+    _CanonicalSection('keyword_param', google_header='Keyword Args'),
+    _CanonicalSection('other_param', numpy_header='Other Parameters'),
+    _CanonicalSection(
+        'returns',
+        google_header='Returns',
+        numpy_header='Returns',
+        return_like=True,
+    ),
+    _CanonicalSection(
+        'yields',
+        google_header='Yields',
+        numpy_header='Yields',
+        return_like=True,
+    ),
+    _CanonicalSection('raises', google_header='Raises', numpy_header='Raises'),
+    _CanonicalSection('warns', google_header='Warns', numpy_header='Warns'),
+    _CanonicalSection(
+        'attributes',
+        google_header='Attributes',
+        numpy_header='Attributes',
+    ),
+    _CanonicalSection('methods', google_header='Methods', numpy_header='Methods'),
+    _CanonicalSection('see_also', google_header='See Also', numpy_header='See Also'),
+    _CanonicalSection('notes', google_header='Notes', numpy_header='Notes'),
+    _CanonicalSection('references', google_header='References', numpy_header='References'),
+    _CanonicalSection('examples', google_header='Examples', numpy_header='Examples'),
+    _CanonicalSection('todo', google_header='Todo', numpy_header='Todo'),
+    _CanonicalSection('warnings', google_header='Warnings', numpy_header='Warnings'),
+)
+
+CANONICAL_ORDER: tuple[CanonicalRole, ...] = tuple(section.role for section in CANONICAL_SECTIONS)
+
+CANONICAL_ORDER_SET: frozenset[CanonicalRole] = frozenset(CANONICAL_ORDER)
+
+RETURN_LIKE_ROLES: frozenset[CanonicalRole] = frozenset(
+    s.role for s in CANONICAL_SECTIONS if s.return_like
+)