docwrap 0.1.0__tar.gz

docwrap-0.1.0/.gitignore

@@ -0,0 +1,46 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+dist/
+.eggs/
+*.egg-info/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage*
+.pytest_cache/
+.cache/
+
+# Type checker / linter caches
+.pyright/
+.mypy_cache/
+.ruff_cache/
+pyrightconfig.json
+
+# Editors
+.vscode/
+.idea/
+
+# OS
+.DS_Store
+Thumbs.db

docwrap-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 the docwrap authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

docwrap-0.1.0/PKG-INFO

@@ -0,0 +1,126 @@
+Metadata-Version: 2.5
+Name: docwrap
+Version: 0.1.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
+Project-URL: Issues, https://github.com/dactylo/docwrap/issues
+Project-URL: Repository, https://github.com/dactylo/docwrap
+License-Expression: MIT
+License-File: LICENSE
+Keywords: docstring,formatter,google,numpy,sphinx,wrap
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Typing :: Typed
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+
+# docwrap
+
+[![CI](https://github.com/dactylo/docwrap/actions/workflows/ci.yml/badge.svg)](https://github.com/dactylo/docwrap/actions/workflows/ci.yml)
+
+Docwrap applies configurable formatting rules to Python docstrings. It makes wrapping and layout
+deterministic, with controls for line length, paragraph reflow, and summary placement. It supports
+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](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](images/docwrap-preview.png)
+
+## Installation
+
+Docwrap requires CPython 3.13 or later. From a checkout, install the command with
+[uv](https://docs.astral.sh/uv/):
+
+```bash
+uv tool install .
+```
+
+To update an existing installation after pulling changes:
+
+```bash
+uv tool install --reinstall .
+```
+
+Git is needed for agent hooks and incremental mode; uv is needed for these installation commands,
+not at runtime.
+
+## Quick start
+
+Start with a summary, preview individual docstrings, inspect the diff, then apply the changes:
+
+```bash
+docwrap
+docwrap --preview
+docwrap --diff
+docwrap --write
+```
+
+Paths default to the current directory. Pass a file or directory to limit the scope.
+
+Use `docwrap --stats` to inspect line-length distributions, compare wrapping targets, and see
+recommendations.
+
+Without `--write`, docwrap leaves files alone. It exits 0 when no changes are pending or a write
+succeeds, 1 when changes are pending, and 2 on an error. Start with the defaults: 79 columns,
+`smart` filling, cautious reflow, and no summary wrapping. To change the width for a project, add:
+
+```toml
+[tool.docwrap]
+line-length = 88
+```
+
+Configuration is discovered from each file's `pyproject.toml`. The
+[wrapping policy guide](docs/design.md#choosing-a-wrapping-policy) explains the tradeoffs between
+reflowing prose and preserving authored layout. See the [CLI reference](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](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](docs/hook.md).
+
+For Python callers, `wrap_source()` returns rewritten source, `check()` reports whether it would
+change, and `wrap_source_report()` supplies structured results:
+
+```python
+import docwrap
+
+source = 'def greet():\n    """Return a greeting."""\n'
+result = docwrap.check(source)
+wrapped = docwrap.wrap_source(source)
+```
+
+See the [library reference](docs/library.md) for file operations, configuration, result types, and
+safety skips.
+
+## Documentation
+
+- [CLI reference](docs/cli.md): commands, output, configuration, and exit codes.
+- [Agent hook guide](docs/hook.md): setup, commit handling, and host responses.
+- [Incremental mode](docs/incremental.md): wrap only changed files or definitions.
+- [Library reference](docs/library.md): supported Python API and result contracts.
+- [Concepts and safety](docs/design.md): styles, wrapping choices, and preservation rules.
+- [Platform compatibility](docs/platform.md): supported environments and file behavior.
+
+## Development
+
+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.
+
+## License
+
+Docwrap is available under the [MIT License](LICENSE).

docwrap-0.1.0/README.md

@@ -0,0 +1,107 @@
+# docwrap
+
+[![CI](https://github.com/dactylo/docwrap/actions/workflows/ci.yml/badge.svg)](https://github.com/dactylo/docwrap/actions/workflows/ci.yml)
+
+Docwrap applies configurable formatting rules to Python docstrings. It makes wrapping and layout
+deterministic, with controls for line length, paragraph reflow, and summary placement. It supports
+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](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](images/docwrap-preview.png)
+
+## Installation
+
+Docwrap requires CPython 3.13 or later. From a checkout, install the command with
+[uv](https://docs.astral.sh/uv/):
+
+```bash
+uv tool install .
+```
+
+To update an existing installation after pulling changes:
+
+```bash
+uv tool install --reinstall .
+```
+
+Git is needed for agent hooks and incremental mode; uv is needed for these installation commands,
+not at runtime.
+
+## Quick start
+
+Start with a summary, preview individual docstrings, inspect the diff, then apply the changes:
+
+```bash
+docwrap
+docwrap --preview
+docwrap --diff
+docwrap --write
+```
+
+Paths default to the current directory. Pass a file or directory to limit the scope.
+
+Use `docwrap --stats` to inspect line-length distributions, compare wrapping targets, and see
+recommendations.
+
+Without `--write`, docwrap leaves files alone. It exits 0 when no changes are pending or a write
+succeeds, 1 when changes are pending, and 2 on an error. Start with the defaults: 79 columns,
+`smart` filling, cautious reflow, and no summary wrapping. To change the width for a project, add:
+
+```toml
+[tool.docwrap]
+line-length = 88
+```
+
+Configuration is discovered from each file's `pyproject.toml`. The
+[wrapping policy guide](docs/design.md#choosing-a-wrapping-policy) explains the tradeoffs between
+reflowing prose and preserving authored layout. See the [CLI reference](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](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](docs/hook.md).
+
+For Python callers, `wrap_source()` returns rewritten source, `check()` reports whether it would
+change, and `wrap_source_report()` supplies structured results:
+
+```python
+import docwrap
+
+source = 'def greet():\n    """Return a greeting."""\n'
+result = docwrap.check(source)
+wrapped = docwrap.wrap_source(source)
+```
+
+See the [library reference](docs/library.md) for file operations, configuration, result types, and
+safety skips.
+
+## Documentation
+
+- [CLI reference](docs/cli.md): commands, output, configuration, and exit codes.
+- [Agent hook guide](docs/hook.md): setup, commit handling, and host responses.
+- [Incremental mode](docs/incremental.md): wrap only changed files or definitions.
+- [Library reference](docs/library.md): supported Python API and result contracts.
+- [Concepts and safety](docs/design.md): styles, wrapping choices, and preservation rules.
+- [Platform compatibility](docs/platform.md): supported environments and file behavior.
+
+## Development
+
+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.
+
+## License
+
+Docwrap is available under the [MIT License](LICENSE).

docwrap-0.1.0/_build.py

@@ -0,0 +1,30 @@
+"""Collect bundled agent entry points for distribution metadata."""
+
+import tomllib
+from pathlib import Path
+from typing import override
+
+from hatchling.metadata.plugin.interface import MetadataHookInterface
+
+
+class PluginMetadataHook(MetadataHookInterface):
+    """Include each bundled plugin's registration in the containing distribution."""
+
+    @override
+    def update(self, metadata: dict[str, object]) -> None:
+        metadata['entry-points'] = _plugin_entry_points(Path(self.root))
+
+
+def _plugin_entry_points(root: Path) -> dict[str, dict[str, str]]:
+    """Read entry points declared by the root's agent plugin directories."""
+    groups: dict[str, dict[str, str]] = {}
+    for manifest in sorted((root / 'plugins').glob('*/adapter.toml')):
+        with manifest.open('rb') as stream:
+            entries = tomllib.load(stream)['entry-points']
+        for group, targets in entries.items():
+            registered = groups.setdefault(group, {})
+            for name, target in targets.items():
+                if name in registered:
+                    raise ValueError(f'Duplicate entry point {group}:{name} in {manifest}')
+                registered[name] = target
+    return groups

docwrap-0.1.0/plugins/agy/_docwrap/__init__.py

@@ -0,0 +1 @@
+"""Provide the private Antigravity adapter implementation."""

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

@@ -0,0 +1,122 @@
+"""Translate Antigravity hook events for docwrap."""
+
+import json
+from collections.abc import Mapping
+from typing import cast
+
+from docwrap.hooks import (
+    API_VERSION,
+    HookResult,
+    HostInput,
+    HostResponse,
+    absolute_directory,
+    notes_text,
+    object_field,
+    payload_cwd,
+)
+
+_COMMAND_TOOL = 'run_command'
+_EDIT_TOOLS = frozenset({'replace_file_content', 'write_to_file'})
+_EVENTS = {'PreToolUse': 'pre_tool', 'PostToolUse': 'post_tool'}
+
+
+def _allow_response(result: HookResult) -> HostResponse:
+    """Render Antigravity allow feedback."""
+    stdout = f'{json.dumps({"systemMessage": result.reason})}\n' if result.reason else ''
+    return HostResponse(stdout, notes_text(result), 0)
+
+
+def _base_cwd(payload: Mapping[str, object], args: Mapping[str, object]) -> str:
+    """Resolve the target directory from `Cwd`, `workspacePaths`, `cwd`, or the process."""
+    cwd = args.get('Cwd')
+    if isinstance(cwd, str) and cwd:
+        return cwd
+    workspaces = payload.get('workspacePaths')
+    if isinstance(workspaces, list):
+        first = cast('list[object]', workspaces)[:1]
+        if first and isinstance(first[0], str) and first[0]:
+            return first[0]
+    return payload_cwd(payload)
+
+
+def _deny(reason: str, stderr_prefix: str = '') -> HostResponse:
+    """Render Antigravity's top-level deny object."""
+    stdout = json.dumps({'decision': 'deny', 'reason': reason})
+    return HostResponse(f'{stdout}\n', f'{stderr_prefix}{reason}\n', 0)
+
+
+class AntigravityAdapter:
+    """Translate Antigravity `toolCall` payloads, which carry no event name."""
+
+    name = 'agy'
+    api_version = API_VERSION
+    requires_event = True
+
+    def parse(self, payload: Mapping[str, object], event: str | None) -> HostInput | None:
+        """Read `toolCall.name` and `toolCall.args` under the given event.
+
+        For `run_command`, pre-tool `command_cwd` is `toolCall.args.Cwd` when
+        it is an absolute path; `workspacePaths` and the process directory are
+        never invocation evidence. Other tools report `None`.
+
+        Args:
+            payload: Decoded Antigravity hook payload.
+            event: `PreToolUse` or `PostToolUse` from `--event`.
+
+        Returns:
+            Neutral input; a tool other than `run_command` under `PreToolUse`
+            or other than the file writers under `PostToolUse` yields input
+            with nothing to act on.
+
+        Raises:
+            ValueError: If `event` is not an Antigravity hook event.
+        """
+        neutral_event = _EVENTS.get(event or '')
+        if neutral_event is None:
+            raise ValueError(
+                f'unknown Antigravity event {event!r}; expected PreToolUse or PostToolUse'
+            )
+        tool_call = object_field(payload, 'toolCall')
+        args = object_field(tool_call, 'args')
+        cwd = _base_cwd(payload, args)
+        name = tool_call.get('name')
+        if neutral_event == 'pre_tool':
+            command = args.get('CommandLine') if name == _COMMAND_TOOL else None
+            command_cwd = absolute_directory(args, 'Cwd') if name == _COMMAND_TOOL else None
+            return HostInput(
+                'pre_tool',
+                command if isinstance(command, str) else None,
+                cwd,
+                command_cwd,
+            )
+        editing = isinstance(name, str) and name in _EDIT_TOOLS
+        target = args.get('TargetFile') if editing else None
+        paths = (target,) if isinstance(target, str) and target else ()
+        return HostInput('post_tool', None, cwd, None, paths)
+
+    def render(self, result: HookResult) -> HostResponse:
+        """Render allow feedback or a denial.
+
+        Args:
+            result: Decision, reason, and notes from docwrap.
+
+        Returns:
+            Empty stdout for a silent allow, or one system message for allow
+            feedback; notes on stderr and exit 0. For deny, the deny JSON on
+            stdout, the reason on stderr, and exit 0.
+        """
+        notes = notes_text(result)
+        if result.decision == 'deny':
+            return _deny(result.reason or 'docwrap denied the operation', notes)
+        return _allow_response(result)
+
+    def render_failure(self, reason: str) -> HostResponse:
+        """Render the top-level deny object.
+
+        Args:
+            reason: Reason for the failure.
+
+        Returns:
+            The deny object on stdout, the reason on stderr, and exit 0.
+        """
+        return _deny(reason)

docwrap-0.1.0/plugins/agy/adapter.toml

@@ -0,0 +1,2 @@
+[entry-points."docwrap.hook_adapters"]
+agy = "plugins.agy._docwrap._adapter:AntigravityAdapter"

docwrap-0.1.0/plugins/agy/hooks.json

@@ -0,0 +1,15 @@
+{
+  "docwrap": {
+    "PreToolUse": [
+      {
+        "matcher": "run_command",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "docwrap hook --agent agy --event PreToolUse"
+          }
+        ]
+      }
+    ]
+  }
+}

docwrap-0.1.0/plugins/agy/plugin.json

@@ -0,0 +1,5 @@
+{
+  "$schema": "https://antigravity.google/schemas/v1/plugin.json",
+  "name": "docwrap-agy",
+  "description": "Install the docwrap commit-time docstring wrapping hook for Antigravity."
+}

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

@@ -0,0 +1,135 @@
+# pyright: reportPrivateUsage=false
+
+import json
+import shlex
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal
+
+import pytest
+
+from docwrap._cli import _build_hook_parser
+from docwrap._hosts import load_adapter
+from docwrap.hooks import API_VERSION, HookAdapter, HookResult, HostInput, HostResponse
+from plugins.agy._docwrap._adapter import AntigravityAdapter
+
+ROOT = Path(__file__).resolve().parents[3]
+
+
+@dataclass(frozen=True)
+class _Result:
+    decision: Literal['allow', 'deny']
+    reason: str | None = None
+    notes: tuple[str, ...] = ()
+
+
+def _payload(tool: str, args: dict[str, object]) -> dict[str, object]:
+    return {'toolCall': {'name': tool, 'args': args}}
+
+
+def _result(decision: str, reason: str | None = None, notes: tuple[str, ...] = ()) -> HookResult:
+    return _Result('deny' if decision == 'deny' else 'allow', reason, notes)
+
+
+class TestAntigravityAdapter:
+    def test_contract(self) -> None:
+        adapter: HookAdapter = AntigravityAdapter()
+        assert (adapter.name, adapter.api_version, adapter.requires_event) == (
+            'agy',
+            API_VERSION,
+            True,
+        )
+
+    @pytest.mark.parametrize('tool', ['write_to_file', 'replace_file_content'])
+    def test_parse_post_tool_file_writers(self, tool: str) -> None:
+        payload = _payload(tool, {'TargetFile': '/t/a.py', 'Cwd': '/t'})
+        assert AntigravityAdapter().parse(payload, 'PostToolUse') == HostInput(
+            'post_tool', None, '/t', None, ('/t/a.py',)
+        )
+
+    def test_parse_pre_tool_other_tool_has_no_command(self) -> None:
+        payload = _payload('write_to_file', {'TargetFile': 'a.py', 'Cwd': '/t'})
+        assert AntigravityAdapter().parse(payload, 'PreToolUse') == HostInput(
+            'pre_tool', None, '/t', None
+        )
+
+    def test_parse_rejects_unknown_event(self) -> None:
+        with pytest.raises(ValueError, match='unknown Antigravity event'):
+            AntigravityAdapter().parse({}, 'Stop')
+
+    @pytest.mark.parametrize('cwd', ['rel', '', 7])
+    def test_parse_run_command_non_absolute_cwd_is_unknown(self, cwd: object) -> None:
+        payload = _payload('run_command', {'CommandLine': 'git commit -m x', 'Cwd': cwd})
+        payload['workspacePaths'] = ['/ws']
+        parsed = AntigravityAdapter().parse(payload, 'PreToolUse')
+        assert parsed is not None
+        assert parsed.command_cwd is None
+
+    def test_parse_run_command_prefers_cwd_over_workspace(self, tmp_path: Path) -> None:
+        cwd = str(tmp_path / 'cwd')
+        payload = _payload('run_command', {'CommandLine': 'git commit -m x', 'Cwd': cwd})
+        payload['workspacePaths'] = [str(tmp_path / 'workspace')]
+        assert AntigravityAdapter().parse(payload, 'PreToolUse') == HostInput(
+            'pre_tool', 'git commit -m x', cwd, cwd
+        )
+
+    def test_parse_run_command_without_cwd_is_unknown(self) -> None:
+        payload = _payload('run_command', {'CommandLine': 'git commit -m x'})
+        payload['workspacePaths'] = ['/ws']
+        assert AntigravityAdapter().parse(payload, 'PreToolUse') == HostInput(
+            'pre_tool', 'git commit -m x', '/ws', None
+        )
+
+    def test_render_allow_and_failure(self) -> None:
+        assert AntigravityAdapter().render(_result('allow')) == HostResponse('', '', 0)
+        failure = AntigravityAdapter().render_failure('docwrap: reason')
+        assert json.loads(failure.stdout) == {'decision': 'deny', 'reason': 'docwrap: reason'}
+        assert (failure.stderr, failure.exit_code) == ('docwrap: reason\n', 0)
+
+    def test_render_allow_feedback_is_one_system_message(self) -> None:
+        response = AntigravityAdapter().render(_result('allow', 'first\nsecond', ('diagnostic',)))
+        assert json.loads(response.stdout) == {'systemMessage': 'first\nsecond'}
+        assert (response.stderr, response.exit_code) == ('diagnostic\n', 0)
+
+    def test_render_deny_is_top_level_json(self) -> None:
+        response = AntigravityAdapter().render(_result('deny', 'docwrap: reason', ('note',)))
+        assert json.loads(response.stdout) == {'decision': 'deny', 'reason': 'docwrap: reason'}
+        assert (response.stderr, response.exit_code) == ('note\ndocwrap: reason\n', 0)
+
+
+@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(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.1.0/plugins/claude/.claude-plugin/plugin.json

@@ -0,0 +1,10 @@
+{
+  "name": "docwrap",
+  "version": "0.1.0",
+  "description": "Install the docwrap commit-time docstring wrapping hook for Claude Code.",
+  "author": {
+    "name": "docwrap contributors"
+  },
+  "license": "MIT",
+  "keywords": ["docstrings", "formatting", "hooks", "python"]
+}

docwrap-0.1.0/plugins/claude/_docwrap/__init__.py

@@ -0,0 +1 @@
+"""Provide the private Claude Code adapter implementation."""