format-docstring 0.1.8__tar.gz → 0.2.0__tar.gz

format_docstring-0.2.0/.pre-commit-config.yaml

@@ -0,0 +1,83 @@
+---
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+        exclude: \.json$|\.ipynb$
+      - id: debug-statements
+      - id: double-quote-string-fixer
+      - id: requirements-txt-fixer
+        exclude: \.ipynb$
+      - id: check-added-large-files
+        args: [--maxkb=1000]
+      - id: check-toml
+      - id: check-yaml
+      - id: name-tests-test
+        args: [--pytest-test-first]
+        exclude: ^tests/test_data/|^tests/helpers\.py$
+      - id: check-merge-conflict
+  - repo: https://github.com/asottile/pyupgrade
+    rev: v3.20.0
+    hooks:
+      - id: pyupgrade
+        args: [--py310-plus]
+  - repo: https://github.com/jsh9/muff-pre-commit
+    rev: 0.13.2
+    hooks:
+      - id: muff-format
+        args: [--config, muff.toml]
+  - repo: https://github.com/jsh9/blank-line-after-blocks
+    rev: 0.1.4
+    hooks:
+      - id: blank-line-after-blocks
+      - id: blank-line-after-blocks-jupyter
+  - repo: https://github.com/lyz-code/yamlfix
+    rev: 1.18.0
+    hooks:
+      - id: yamlfix
+  - repo: https://github.com/hukkin/mdformat
+    rev: 1.0.0
+    hooks:
+      - id: mdformat
+        args: [--wrap, '79', --number]
+        additional_dependencies: [mdformat-gfm]
+  - repo: https://github.com/jsh9/format-json
+    rev: 0.1.2
+    hooks:
+      - id: format-json
+        args:
+          - --autofix
+          - --no-ensure-ascii
+          - --indent=4
+          - --no-sort-keys
+          - --no-eof-newline
+  - repo: https://github.com/jsh9/markdown-toc-creator
+    rev: 0.0.11
+    hooks:
+      - id: markdown-toc-creator
+  - repo: local
+    hooks:
+      - id: format-docstring
+        name: Format self (python docstrings)
+        entry: python
+        args: [-m, format_docstring.main_py, --verbose, diff]
+        language: python
+        types: [python]
+        exclude: ^tests/test_data/
+        additional_dependencies:
+          - click>=8.0
+          - jupyter-notebook-parser>=0.1.4
+          - tomli>=1.1.0
+      - id: format-docstring-jupyter
+        name: Format self (docstrings in Jupyter notebooks)
+        entry: python
+        args: [-m, format_docstring.main_jupyter, --verbose, diff]
+        language: python
+        files: ^.*\.ipynb$
+        exclude: ^tests/test_data/
+        additional_dependencies:
+          - click>=8.0
+          - jupyter-notebook-parser>=0.1.4
+          - tomli>=1.1.0

format_docstring-0.2.0/AGENTS.md

@@ -0,0 +1,130 @@
+# AGENTS.md
+
+This guide briefs coding agents working on `format-docstring`. Use it to get
+oriented before making changes.
+
+## Quick Snapshot
+
+- Formats NumPy-style docstrings (with experimental Google support) in `.py`
+  files and Jupyter notebooks while preserving surrounding code.
+- Distributed as a CLI (`format-docstring`, `format-docstring-jupyter`) with
+  minimum Python 3.10, packaged via `setuptools`.
+- Core dependencies: `click`, `docstring_parser_fork`,
+  `jupyter-notebook-parser`, and `tomli/tomllib` for configuration loading.
+- Version is sourced dynamically in `format_docstring/__init__.py`.
+
+## Repository Layout
+
+- `format_docstring/main_py.py` – Click CLI for Python files; validates input
+  and delegates to `PythonFileFixer`.
+- `format_docstring/main_jupyter.py` – CLI for `.ipynb` files built on
+  `JupyterNotebookParser`/`JupyterNotebookRewriter`.
+- `format_docstring/base_fixer.py` – Shared directory traversal, exclusion
+  regex handling, and `fix_one_directory_or_one_file` orchestration.
+- `format_docstring/docstring_rewriter.py` – AST-based docstring extraction and
+  replacement that leaves non-docstring text untouched.
+- `format_docstring/line_wrap_numpy.py` / `line_wrap_google.py` –
+  Style-specific wrapping helpers; NumPy path is the production code path,
+  Google is partial.
+- `format_docstring/line_wrap_utils.py` – Shared utilities for wrapping (indent
+  management, bullet handling, preserving literal blocks, etc.).
+- `format_docstring/config.py` – `pyproject.toml` discovery, parsing, and Click
+  default injection.
+- `tests/` – Pytest suite with fixture-driven cases in `tests/test_data/`; see
+  `tests/helpers.py` for fixture loading helpers.
+
+## Implementation Notes
+
+- `docstring_rewriter.fix_src` parses with `ast.parse`, collects docstring
+  literals, and rewrites source slices using absolute offsets from
+  `calc_line_starts`; this avoids `ast.unparse` and keeps comments/spacing.
+- For functions, `_collect_param_metadata` records signature annotations and
+  default values so NumPy `Parameters` signatures in docstrings are
+  resynchronised with the real function definition. Defaulted parameters omit
+  redundant `, optional`, and forward references keep their original quoting.
+- Return annotations are likewise projected into `Returns`/`Yields` sections,
+  mirroring tuple element splits when the docstring already enumerates them.
+- Wrapping honors NumPy section heuristics, rST constructs, code fences,
+  `Examples` prompts, and literal blocks introduced by `::`.
+- `_normalize_signature_segment` flattens multiline annotations via
+  `ast.unparse` but uses token-level replay to preserve the author's quoting
+  style for forward references and string defaults.
+- CLI exposes `--docstring-style`, but the Python entry-point currently raises
+  if a non-NumPy style is requested; Jupyter flow passes style through
+  unchanged.
+- `BaseFixer` subclasses return `1` when any file changed so callers can
+  surface non-zero exit codes.
+- Notebook fixer round-trips JSON via `json.dump(..., indent=1)` and rewrites
+  cells only when content changes, preserving magics with `reconstruct_source`.
+
+## Configuration
+
+- User-facing configuration lives under `[tool.format_docstring]` inside
+  `pyproject.toml` and supports `line_length`, `docstring_style`, `exclude`,
+  `fix_rst_backticks`, and `verbose` (`default` or `diff` to print unified
+  diffs on rewrites).
+- `config.inject_config_from_file` auto-discovers the nearest `pyproject.toml`
+  (walking up from targets) and merges values into Click’s `default_map`.
+- Default exclude pattern is `\.git|\.tox|\.pytest_cache`; tests tweak it as
+  needed.
+
+## Development Workflow
+
+- Install: `pip install -e .` for the project,
+  `pip install -r requirements.dev` for tooling.
+- Tests: `pytest --tb=long`, or target modules such as
+  `pytest tests/test_docstring_rewriter.py`.
+- Lint/format: `muff check --fix --config=muff.toml format_docstring tests`,
+  `muff format --diff --config=muff.toml format_docstring tests`.
+- Type checking: `mypy format_docstring/`.
+- Tox: `tox` for the full matrix (py310–py313, mypy, lint), or focused runs
+  like `tox -e py311`, `tox -e mypy`, `tox -e muff-format`.
+- CLI smoke tests: `format-docstring --help`,
+  `format-docstring-jupyter --help`.
+- Pre-commit: `pre-commit run -a`.
+
+## Testing Notes
+
+- Fixture files under `tests/test_data/line_wrap` and
+  `tests/test_data/end_to_end` use `LINE_LENGTH: <int>` headers followed by
+  `BEFORE`/`AFTER` sections split by `**********`.
+- `tests/test_playground.py` focuses on regression snippets;
+  `tests/test_config.py` exercises config discovery and CLI overrides.
+- When modifying wrapping rules, update both the helper (`line_wrap_utils.py`)
+  and the corresponding expectation files in `tests/test_data/`.
+
+## Style Guidance
+
+- Formatting rules mirror `muff.toml` (line length 79, single quotes, NumPy
+  docstring convention). Respect these when adding code.
+- Keep docstring style tests conservative: avoid mutating non-docstring
+  content, and add regression cases whenever handling around literal sections
+  or tables changes.
+
+## What is a "signature line"?
+
+They are the lines in the docstring where input and return args are defined,
+for example, in this docstring:
+
+```python
+"""
+Do something
+
+Parameters
+----------
+arg1 : str
+    Arg 1
+arg2 : int = 2
+    Arg 2
+
+Returns
+-------
+dict[str, str]
+   The mapping
+```
+
+Signature lines are:
+
+- arg1 : str
+- arg2 : int = 2
+- dict[str, str]

{format_docstring-0.1.8 → format_docstring-0.2.0}/CHANGELOG.md

@@ -6,6 +6,29 @@ The format is based on
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
 adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.0] - 2025-10-20
+
+- Added
+  - AST-driven synchronization of NumPy `Parameters` and `Returns` signature
+    lines with the function signature, including tuple element expansion for
+    multi-line return blocks
+- Full diff
+  - https://github.com/jsh9/format-docstring/compare/0.1.9...0.2.0
+
+## [0.1.9] - 2025-10-16
+
+- Added
+  - A "`# no-format-docstring`" directive to ignore certain docstring
+  - Verbose diff output via `--verbose diff` and
+    `[tool.format_docstring] verbose`
+  - Normalize NumPy section headings that include trailing colons (e.g.,
+    `Parameters:`); also, fix Google-style "Arg" header into "Parameters"
+- Changed
+  - Added "self format" pre-commit hook to format docstrings within this repo
+    with its own formatting logic
+- Full diff
+  - https://github.com/jsh9/format-docstring/compare/0.1.8...0.1.9
+
 ## [0.1.8] - 2025-10-14
 
 - Fixed

{format_docstring-0.1.8 → format_docstring-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: format-docstring
-Version: 0.1.8
+Version: 0.2.0
 Summary: A Python formatter to wrap/adjust docstring lines
 Author-email: jsh9 <25124332+jsh9@users.noreply.github.com>
 Maintainer-email: jsh9 <25124332+jsh9@users.noreply.github.com>
@@ -27,7 +27,6 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: jupyter-notebook-parser>=0.1.4
 Requires-Dist: click>=8.0
-Requires-Dist: docstring_parser_fork>=0.0.14
 Requires-Dist: tomli>=1.1.0; python_version < "3.11"
 Dynamic: license-file
 
@@ -35,6 +34,8 @@ Dynamic: license-file
 
 A Python formatter to automatically format numpy-style docstrings.
 
+______________________________________________________________________
+
 **Table of Contents:**
 
 <!--TOC-->
@@ -46,32 +47,38 @@ A Python formatter to automatically format numpy-style docstrings.
   - [2.3. Minor typos can be automatically fixed](#23-minor-typos-can-be-automatically-fixed)
   - [2.4. Default value declarations are standardized](#24-default-value-declarations-are-standardized)
   - [2.5. Single backticks are converted to double backticks (rST syntax)](#25-single-backticks-are-converted-to-double-backticks-rst-syntax)
+  - [2.6. Docstring parameters and returns stay in sync with signatures](#26-docstring-parameters-and-returns-stay-in-sync-with-signatures)
 - [3. Installation](#3-installation)
 - [4. Usage](#4-usage)
   - [4.1. Command Line Interface](#41-command-line-interface)
   - [4.2. Pre-commit Hook](#42-pre-commit-hook)
+  - [4.3. Opting Out of Formatting](#43-opting-out-of-formatting)
 - [5. Configuration](#5-configuration)
   - [5.1. Command-Line Options](#51-command-line-options)
   - [5.2. Usage Examples](#52-usage-examples)
   - [5.3. `pyproject.toml` Configuration](#53-pyprojecttoml-configuration)
+- [6. Caveat](#6-caveat)
 
 <!--TOC-->
 
+______________________________________________________________________
+
 ## 1. Overview
 
 `format-docstring` is a tool that automatically formats and wraps docstring
 content in Python files and Jupyter notebooks.
 
-Compared with [`docformatter`](https://github.com/PyCQA/docformatter) and
-[`pydocstringformatter`](https://github.com/DanielNoord/pydocstringformatter),
-this tool (`format-docstring`) goes further by intelligently wrapping docstring
-contents, fixing common typos, etc.
+Baseline reflow corresponds to the common docstring cleanups offered by
+general-purpose formatters: splitting one-line docstrings into the canonical
+multi-line layout (triple quotes, blank line, summary), normalizing
+indentation, and wrapping text at a fixed column width without applying extra
+heuristics.
 
-The formatting that would be done by
-[docformatter](https://github.com/PyCQA/docformatter) and
-[pydocstringformatter](https://github.com/DanielNoord/pydocstringformatter) can
-be readily handled by [Ruff](https://github.com/astral-sh/ruff) or
-[Black](https://github.com/psf/black).
+| Feature                                   | `format-docstring` | [docformatter] | [pydocstringformatter] | [Ruff] | [Black] |
+| ----------------------------------------- | ------------------ | -------------- | ---------------------- | ------ | ------- |
+| Docstring wrapping                        | ✅                 | ❌             | ❌                     | ❌     | ❌      |
+| Compatible with line length linter (E501) | ✅                 | ❌             | ❌                     | N/A    | N/A     |
+| Fixes common docstring typos              | ✅                 | ❌             | ❌                     | ❌     | ❌      |
 
 ## 2. Before vs After Examples
 
@@ -187,6 +194,25 @@ def mu_function():
     pass
 ```
 
+or, Google-style section headers can be fixed:
+
+```diff
+def my_function():
+    """
+    My function
+
+-    Args:
+-    ----
++    Parameters
++    ----------
+    arg1 : str
+        Arg 1
+
+    ...
+    """
+    pass
+```
+
 ### 2.4. Default value declarations are standardized
 
 ```diff
@@ -230,9 +256,94 @@ def process_data(data):
 -        Processed data with key `result`.
 +        Processed data with key ``result``.
     """
+```
+
+### 2.6. Docstring parameters and returns stay in sync with signatures
+
+```diff
+from typing import List, Optional
+
+
+def create_user(
+        user: Optional[str] = None,
+        roles: List["Role"] | None = None,
+        retries: int = 0,
+        serializer: "Serializer" | None = None,
+        something_else: tuple[int, ...] = (
+            "1",
+            '2',
+            3,
+            4,
+            5,
+            6,
+            7,
+            8,
+            9,
+            10,
+            11,
+            12,
+        ),
+) -> None:
+    """
+    Parameters
+    ----------
+-    user : str
++    user : Optional[str], default=None
+        Login name.
+-    roles : list
++    roles : List["Role"] | None, default=None
+        Assigned roles.
+-    retries : int
++    retries : int, default=0
+        Number of retry attempts.
+-    serializer : Serializer, optional
++    serializer : "Serializer" | None, default=None
+        Custom serializer instance.
+-    something_else : tuple[int, ...]
++    something_else : tuple[int, ...], default=("1", '2', 3, 4, 5, 6, 7, 8, 9, 10, 11, 12)
+    """
     pass
 ```
 
+And return type hint:
+
+```diff
+def build_mapping() -> dict[str, str]:
+    """
+    Returns
+    -------
+-    str
++    dict[str, str]
+        Mapping of values.
+    """
+```
+
+For tuple return annotations, tuple elements are split across multiple
+signature lines only when the docstring already adopted that layout:
+
+```diff
+def compute_values() -> tuple[int, str, list[str]]:
+    """
+    Returns
+    -------
+-    float
++    int
+        First element.
+-    str
++    str
+        Second element.
+-    List[str]
++    list[str]
+        Third element.
+    """
+```
+
+Annotations and defaults are extracted from the actual function signature, so
+docstring signature lines reflect the ground truth. Defaulted parameters omit
+redundant `, optional`, forward references keep their original quoting, and
+return signatures track tuple splitting conventions already present in the
+docstring.
+
 ## 3. Installation
 
 ```bash
@@ -281,6 +392,19 @@ Then install the pre-commit hook:
 pre-commit install
 ```
 
+### 4.3. Opting Out of Formatting
+
+Add a comment containing `no-format-docstring` on the same line as the closing
+triple quotes to prevent the formatter from touching that docstring:
+`""" ... """  # no-format-docstring`.
+
+You can combine this "no-format-docstring" with other directives like "noqa".
+
+Tip: If you only want to keep specific formatter changes inside a docstring,
+first run `format-docstring`, accept the parts you like, revert the edits you
+dislike, and then add an inline `# no-format-docstring` comment so future runs
+leave that docstring untouched.
+
 ## 5. Configuration
 
 ### 5.1. Command-Line Options
@@ -291,6 +415,8 @@ pre-commit install
   default: `numpy`). Note: Currently only `numpy` style is fully supported.
 - `--fix-rst-backticks BOOL`: Automatically fix single backticks to double
   backticks per rST syntax (default: True)
+- `--verbose CHOICE`: Logging detail level (`default` keeps the existing
+  behaviour, `diff` prints unified diffs when rewrites happen)
 - `--exclude TEXT`: Regex pattern to exclude files/directories (default:
   `\.git|\.tox|\.pytest_cache`)
 - `--config PATH`: Path to a `pyproject.toml` config file. If not specified,
@@ -311,6 +437,9 @@ format-docstring --line-length 72 src/
 # Format Jupyter notebooks excluding certain directories
 format-docstring-jupyter --exclude "\.git|\.venv|__pycache__" notebooks/
 
+# Preview changes with unified diffs
+format-docstring --verbose diff src/
+
 # Use a specific config file
 format-docstring --config path/to/pyproject.toml src/
 
@@ -332,6 +461,7 @@ line_length = 79
 docstring_style = "numpy"
 fix_rst_backticks = true
 exclude = "\\.git|\\.venv|__pycache__"
+verbose = "default"  # or "diff" to print unified diffs
 ```
 
 **Available options:**
@@ -344,6 +474,21 @@ exclude = "\\.git|\\.venv|__pycache__"
   backticks per rST syntax (default: `true`)
 - `exclude` (str): Regex pattern to exclude files/directories (default:
   `"\\.git|\\.tox|\\.pytest_cache"`)
+- `verbose` (str): Logging detail level (`"default"` or `"diff"`)
 
 The tool searches for `pyproject.toml` starting from the target file/directory
 and walking up the parent directories until one is found.
+
+## 6. Caveat
+
+This tool assumes the docstrings are written in **mostly** the correct format,
+because it needs those formatting cues (such as section headers and `------`)
+to parse docstrings.
+
+If the docstrings are far from perfectly formatted, it's recommended that you
+use AI coding assistants to rewrite the docstrings first.
+
+[black]: https://github.com/psf/black
+[docformatter]: https://github.com/PyCQA/docformatter
+[pydocstringformatter]: https://github.com/DanielNoord/pydocstringformatter
+[ruff]: https://github.com/astral-sh/ruff