format-docstring 0.1.0__py3-none-any.whl

format_docstring/main_jupyter.py

@@ -0,0 +1,165 @@
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+import click
+from jupyter_notebook_parser import (
+    JupyterNotebookParser,
+    JupyterNotebookRewriter,
+    SourceCodeContainer,
+    reconstruct_source,
+)
+
+import format_docstring.docstring_rewriter as doc_rewriter
+from format_docstring import __version__
+from format_docstring.base_fixer import BaseFixer
+from format_docstring.config import inject_config_from_file
+
+
+@click.command()
+@click.version_option(version=__version__)
+@click.argument('paths', nargs=-1, type=click.Path())
+@click.option(
+    '--config',
+    type=click.Path(exists=False, file_okay=True, dir_okay=False),
+    is_eager=True,
+    callback=inject_config_from_file,
+    default='pyproject.toml',
+    help=(
+        'Path to a pyproject.toml config file. '
+        'If not specified, searches for pyproject.toml in parent directories. '
+        'Command-line options take precedence over config file settings.'
+    ),
+)
+@click.option(
+    '--exclude',
+    type=str,
+    default=r'\.git|\.tox|\.pytest_cache',
+    help='Regex pattern to exclude files/directories',
+)
+@click.option(
+    '--line-length',
+    type=int,
+    default=79,
+    show_default=True,
+    help='Maximum line length for wrapping docstrings',
+)
+@click.option(
+    '--docstring-style',
+    type=click.Choice(['numpy', 'google'], case_sensitive=False),
+    default='numpy',
+    show_default=True,
+    help='Docstring style to target',
+)
+def main(
+        paths: tuple[str, ...],
+        config: str | None,  # noqa: ARG001 (used by Click callback)
+        exclude: str,
+        line_length: int,
+        docstring_style: str,
+) -> None:
+    """Format .ipynb files."""
+    ret = 0
+    for path in paths:
+        fixer = JupyterNotebookFixer(
+            path=path, exclude_pattern=exclude, line_length=line_length
+        )
+        fixer.docstring_style = docstring_style
+        ret |= fixer.fix_one_directory_or_one_file()
+
+    if ret != 0:
+        raise SystemExit(ret)
+
+
+class JupyterNotebookFixer(BaseFixer):
+    """Fixer for Jupyter notebook files."""
+
+    def __init__(
+            self,
+            path: str,
+            exclude_pattern: str = r'\.git|\.tox|\.pytest_cache',
+            line_length: int = 79,
+    ) -> None:
+        super().__init__(path=path, exclude_pattern=exclude_pattern)
+        self.line_length = line_length
+        self.docstring_style: str = 'numpy'
+
+    def fix_one_directory_or_one_file(self) -> int:
+        """Fix formatting in a file or all .ipynb files in a directory."""
+        from pathlib import Path
+
+        path_obj = Path(self.path)
+
+        if path_obj.is_file():
+            return self.fix_one_file(path_obj.as_posix())
+
+        # Process .ipynb files instead of .py files for Jupyter notebooks
+        filenames = self._get_files_to_process(path_obj, '*.ipynb')
+        all_status = set()
+        for filename in filenames:
+            status = self.fix_one_file(str(filename))
+            all_status.add(status)
+
+        return 0 if not all_status or all_status == {0} else 1
+
+    def fix_one_file(self, filename: str) -> int:
+        """Fix formatting in a single Jupyter notebook file."""
+        file_path = Path(filename)
+        if not file_path.is_file():
+            msg = f'{filename} is not a file (skipping)'
+            print(msg, file=sys.stderr)
+            return 0
+
+        try:
+            parsed: JupyterNotebookParser = JupyterNotebookParser(filename)
+            rewriter: JupyterNotebookRewriter = JupyterNotebookRewriter(
+                parsed_notebook=parsed
+            )
+            code_cells: list[dict[str, Any]] = parsed.get_code_cells()
+            code_cell_indices: list[int] = parsed.get_code_cell_indices()
+            code_cell_sources: list[SourceCodeContainer] = (
+                parsed.get_code_cell_sources()
+            )
+        except Exception as exc:
+            print(f'Error reading {filename}: {str(exc)}', file=sys.stderr)
+            return 1
+        else:
+            ret_val = 0
+            assert len(code_cells) == len(code_cell_indices)
+            assert len(code_cells) == len(code_cell_sources)
+
+            for i in range(len(code_cells)):
+                index: int = code_cell_indices[i]
+                source: SourceCodeContainer = code_cell_sources[i]
+                source_without_magic: str = source.source_without_magic
+                magics: dict[str, str] = source.magics
+                fixed: str = doc_rewriter.fix_src(
+                    source_code=source_without_magic,
+                    line_length=self.line_length,
+                    docstring_style=self.docstring_style,
+                )
+
+                if fixed != source_without_magic:
+                    ret_val = 1
+                    fixed_with_magics = reconstruct_source(fixed, magics)
+                    rewriter.replace_source_in_code_cell(
+                        index=index,
+                        new_source=fixed_with_magics,
+                    )
+
+            if ret_val == 1:
+                print(f'Rewriting {filename}', file=sys.stderr)
+                with open(filename, 'w') as fp:
+                    json.dump(parsed.notebook_content, fp, indent=1)
+                    # Jupyter notebooks (.ipynb) always ends with a new line
+                    # but json.dump does not.
+                    fp.write('\n')
+
+            return ret_val
+
+
+if __name__ == '__main__':
+    raise SystemExit(main())

format_docstring/main_py.py

@@ -0,0 +1,125 @@
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import click
+
+import format_docstring.docstring_rewriter as rewriter
+from format_docstring import __version__
+from format_docstring.base_fixer import BaseFixer
+from format_docstring.config import inject_config_from_file
+
+
+@click.command()
+@click.version_option(version=__version__)
+@click.argument('paths', nargs=-1, type=click.Path())
+@click.option(
+    '--config',
+    type=click.Path(exists=False, file_okay=True, dir_okay=False),
+    is_eager=True,
+    callback=inject_config_from_file,
+    default='pyproject.toml',
+    help=(
+        'Path to a pyproject.toml config file. '
+        'If not specified, searches for pyproject.toml in parent directories. '
+        'Command-line options take precedence over config file settings.'
+    ),
+)
+@click.option(
+    '--exclude',
+    type=str,
+    default=r'\.git|\.tox|\.pytest_cache',
+    help='Regex pattern to exclude files/directories',
+)
+@click.option(
+    '--line-length',
+    type=int,
+    default=79,
+    show_default=True,
+    help='Maximum line length for wrapping docstrings',
+)
+@click.option(
+    '--docstring-style',
+    type=click.Choice(['numpy', 'google'], case_sensitive=False),
+    default='numpy',
+    show_default=True,
+    help='Docstring style to target',
+)
+def main(
+        paths: tuple[str, ...],
+        config: str | None,  # noqa: ARG001 (used by Click callback)
+        exclude: str,
+        line_length: int,
+        docstring_style: str,
+) -> None:
+    """Format .py files."""
+    ret = 0
+
+    if docstring_style.lower() != 'numpy':
+        raise ValueError('Only "numpy" style is supported for now.')
+
+    for path in paths:
+        fixer = PythonFileFixer(
+            path=path, exclude_pattern=exclude, line_length=line_length
+        )
+        fixer.docstring_style = docstring_style
+        ret |= fixer.fix_one_directory_or_one_file()
+
+    if ret != 0:
+        raise SystemExit(ret)
+
+
+class PythonFileFixer(BaseFixer):
+    """Fixer for Python source files."""
+
+    def __init__(
+            self,
+            path: str,
+            exclude_pattern: str = r'\.git|\.tox|\.pytest_cache',
+            line_length: int = 79,
+    ) -> None:
+        super().__init__(path=path, exclude_pattern=exclude_pattern)
+        self.line_length = line_length
+        self.docstring_style: str = 'numpy'
+
+    def fix_one_file(self, filename: str) -> int:
+        """Fix formatting in a single Python file."""
+        if filename == '-':
+            source_bytes: bytes = sys.stdin.buffer.read()
+        else:
+            file_path: Path = Path(filename)
+            if not file_path.is_file():
+                msg: str = f'{filename} is not a file (skipping)'
+                print(msg, file=sys.stderr)
+                return 0
+
+            with open(filename, 'rb') as fb:
+                source_bytes = fb.read()
+
+        try:
+            source_text: str = source_bytes.decode()
+            source_text_orig: str = source_text
+        except UnicodeDecodeError:
+            error_msg: str = f'{filename} is non-utf-8 (not supported)'
+            print(error_msg, file=sys.stderr)
+            return 1
+
+        source_text = rewriter.fix_src(
+            source_text,
+            line_length=self.line_length,
+            docstring_style=self.docstring_style,
+        )
+
+        if filename == '-':
+            print(source_text, end='')
+        elif source_text != source_text_orig:
+            print(f'Rewriting {filename}', file=sys.stderr)
+            with open(filename, 'wb') as f:
+                f.write(source_text.encode())
+
+        return int(source_text != source_text_orig)
+
+
+if __name__ == '__main__':
+    raise SystemExit(main())

format_docstring-0.1.0.dist-info/METADATA

@@ -0,0 +1,311 @@
+Metadata-Version: 2.4
+Name: format-docstring
+Version: 0.1.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>
+License: MIT
+Project-URL: Homepage, https://github.com/your/repo
+Project-URL: Repository, https://github.com/your/repo.git
+Project-URL: Issues, https://github.com/your/repo/issues
+Keywords: formatter,code-style,docstring,python
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.10
+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
+
+# format-docstring
+
+A Python formatter to automatically format numpy-style docstrings.
+
+**Table of Contents:**
+
+<!--TOC-->
+
+- [1. Overview](#1-overview)
+- [2. Before vs After Examples](#2-before-vs-after-examples)
+  - [2.1. Long lines are wrapped to fit line length limit](#21-long-lines-are-wrapped-to-fit-line-length-limit)
+  - [2.2. One-line summaries are formatted to fit line length limit](#22-one-line-summaries-are-formatted-to-fit-line-length-limit)
+  - [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)
+- [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)
+- [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)
+
+<!--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.
+
+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).
+
+## 2. Before vs After Examples
+
+### 2.1. Long lines are wrapped to fit line length limit
+
+```diff
+def example_function(param1, param2, option='default'):
+-    """This summary line is intentionally very long and exceeds the line length limit to demonstrate that format-docstring will automatically wrap it across multiple lines while preserving code structure.
++    """
++    This summary line is intentionally very long and exceeds the line length
++    limit to demonstrate that format-docstring will automatically wrap it
++    across multiple lines while preserving code structure.
+
+    Parameters
+    ----------
+-    param1 : str
+-        This parameter description is also intentionally long to show how parameter descriptions get wrapped when they exceed the configured line length limit
+-    param2 : int
+-        Another long parameter description that demonstrates the wrapping behavior for parameter documentation in NumPy-style docstrings
++    param1 : str
++        This parameter description is also intentionally long to show how
++        parameter descriptions get wrapped when they exceed the configured
++        line length limit
++    param2 : int
++        Another long parameter description that demonstrates the wrapping
++        behavior for parameter documentation in NumPy-style docstrings
+    option : str, optional
+        Short description (not wrapped)
+
+    Returns
+    -------
+    dict
+-        The return value wrapped, because it is a very long line that exceeds line length limit by a lot.
++        The return value wrapped, because it is a very long line that exceeds
++        line length limit by a lot.
+
+    Examples
+    --------
+    Code examples with >>> prompts are preserved without wrapping:
+
+    >>> result = example_function('test', 42, option='custom_value_with_a_very_long_name_that_exceeds_line_length')
+    >>> print(result)
+    {'status': 'success'}
+
+    rST tables are preserved without wrapping:
+
+    ===========  ==================  ===============================
+    Format       Wrapped             Preserved
+    ===========  ==================  ===============================
+    Text         Yes                 No (in tables, code, lists)
+    Params       Yes                 Signature lines preserved
+    ===========  ==================  ===============================
+
+    Content following double colons (::) is preserved::
+
+        - This indented block after :: is not wrapped
+        - Even if lines are very long they stay intact
+        - Useful for code blocks or literal content
+
+    Regular bullet lists are also preserved:
+
+    - First bullet point that is intentionally long but not wrapped
+    - Second point also stays on one line regardless of length
+    """
+```
+
+### 2.2. One-line summaries are formatted to fit line length limit
+
+```diff
+def my_function():
+-    """Contents are short, but with quotation marks this exceeds length limit."""
++    """
++    Contents are short, but with quotation marks this exceeds length limit.
++    """
+    pass
+```
+
+### 2.3. Minor typos can be automatically fixed
+
+```diff
+def mu_function():
+    """
+    Minor typos in section titles or "signatures" can be fixed.
+
+-    Parameter
+-    ----
++    Parameters
++    ----------
+    arg1 : str
+        Arg 1
+    arg2 : bool
+        Arg 2
+-    arg3: int
++    arg3 : int
+        Arg 3
+-    arg4    : int
++    arg4 : int
+        Arg 4
+
+-    ReTurn
+-    ----------
++    Returns
++    -------
+    int
+        The return value
+    """
+    pass
+```
+
+### 2.4. Default value declarations are standardized
+
+```diff
+def example_function(arg1, arg2, arg3, arg4):
+    """
+    Parameters
+    ----------
+-    arg1 : int default 10
++    arg1 : int, default=10
+        First argument
+-    arg2 : str, default "hello"
++    arg2 : str, default="hello"
+        Second argument
+-    arg3 : bool, default is True
++    arg3 : bool, default=True
+        Third argument
+-    arg4 : float default: 3.14
++    arg4 : float, default=3.14
+        Fourth argument
+    """
+    pass
+```
+
+## 3. Installation
+
+```bash
+pip install format-docstring
+```
+
+## 4. Usage
+
+### 4.1. Command Line Interface
+
+**For Python files:**
+
+```bash
+format-docstring path/to/file.py
+format-docstring path/to/directory/
+```
+
+**For Jupyter notebooks:**
+
+```bash
+format-docstring-jupyter path/to/notebook.ipynb
+format-docstring-jupyter path/to/directory/
+```
+
+### 4.2. Pre-commit Hook
+
+To use `format-docstring` as a pre-commit hook, add this to your
+`.pre-commit-config.yaml`:
+
+```yaml
+repos:
+  - repo: https://github.com/jsh9/format-docstring
+    rev: <LATEST_VERSION>
+    hooks:
+      - id: format-docstring
+        name: Format docstrings in .py files
+        args: [--line-length=79]
+      - id: format-docstring-jupyter
+        name: Format docstrings in .ipynb files
+        args: [--line-length=79]
+```
+
+Then install the pre-commit hook:
+
+```bash
+pre-commit install
+```
+
+## 5. Configuration
+
+### 5.1. Command-Line Options
+
+- `--line-length INTEGER`: Maximum line length for wrapping docstrings
+  (default: 79)
+- `--docstring-style CHOICE`: Docstring style to target (`numpy` or `google`,
+  default: `numpy`). Note: Currently only `numpy` style is fully supported.
+- `--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,
+  the tool automatically searches for `pyproject.toml` in parent directories.
+  Command-line options take precedence over config file settings.
+- `--version`: Show version information
+- `--help`: Show help message
+
+### 5.2. Usage Examples
+
+```bash
+# Format a single file with default settings
+format-docstring my_module.py
+
+# Format all Python files in a directory with custom line length
+format-docstring --line-length 72 src/
+
+# Format Jupyter notebooks excluding certain directories
+format-docstring-jupyter --exclude "\.git|\.venv|__pycache__" notebooks/
+
+# Use a specific config file
+format-docstring --config path/to/pyproject.toml src/
+
+# CLI options override config file settings
+format-docstring --config pyproject.toml --line-length 100 src/
+```
+
+### 5.3. `pyproject.toml` Configuration
+
+You can configure default values in your `pyproject.toml`. CLI arguments will
+override these settings:
+
+```toml
+[tool.format_docstring]
+line_length = 79
+docstring_style = "numpy"
+exclude = "\\.git|\\.venv|__pycache__"
+```
+
+**Available options:**
+
+- `line_length` (int): Maximum line length for wrapping docstrings (default:
+  79\)
+- `docstring_style` (str): Docstring style, either `"numpy"` or `"google"`
+  (default: `"numpy"`)
+- `exclude` (str): Regex pattern to exclude files/directories (default:
+  `"\\.git|\\.tox|\\.pytest_cache"`)
+
+The tool searches for `pyproject.toml` starting from the target file/directory
+and walking up the parent directories until one is found.

format_docstring-0.1.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+format_docstring/__init__.py,sha256=3bPK0B7mVsgqXVtcJYGKBO8JAM5gYWmdQPaRrI2tpsI,146
+format_docstring/base_fixer.py,sha256=bXbIa9v6LUQXcHYLU5byuB1xo614hGoRKdnR9T3q4oc,2121
+format_docstring/config.py,sha256=2VvOL1AaYM-ODCZf-U3R3ptePR_DMZXnOVItbpp6yns,5528
+format_docstring/docstring_rewriter.py,sha256=bhLWep_-5Qe5XgWI8cBdpZSZPbVurrUGx1IzNob-5zE,9068
+format_docstring/line_wrap_google.py,sha256=arwHkcDybu2K8TCq7UtIiZF8gq4nlcWy0KzDf3bEcZc,191
+format_docstring/line_wrap_numpy.py,sha256=e0QvPeyf4pVl_1KKbVoKuuxGWGyLxJkMsqUu2q814FY,12924
+format_docstring/line_wrap_utils.py,sha256=NCx8JA6GZdVvvudh5u_YbLrDte7R5lMXQ681N22043w,24389
+format_docstring/main_jupyter.py,sha256=7WrbQhuoONHn3W4hOECPSXyXWr8BnJBK96KlNBORrLI,5458
+format_docstring/main_py.py,sha256=l3Rzd1h02erBqpTMtaqDfr9HFtXjxiUATEfsK8-3804,3690
+format_docstring-0.1.0.dist-info/licenses/LICENSE,sha256=UNm_-hqU-1dAB3bLytP6wvGtUeitoJde2xzb5wgVYn0,1061
+format_docstring-0.1.0.dist-info/METADATA,sha256=iZofojbHoJgmTcrXz2CV2fhFFii-EA-U4HdHksVwUf4,9970
+format_docstring-0.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+format_docstring-0.1.0.dist-info/entry_points.txt,sha256=Re2iHTzfgKJgeXDga5Z4bGNPtWGmxupOdzTolwn52sk,129
+format_docstring-0.1.0.dist-info/top_level.txt,sha256=NXPwfHm_1YwwGuetwtK3pJv0jXwXelqPTNCFpm5LQyE,17
+format_docstring-0.1.0.dist-info/RECORD,,

format_docstring-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

format_docstring-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+format-docstring = format_docstring.main_py:main
+format-docstring-jupyter = format_docstring.main_jupyter:main

format_docstring-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 jsh9
+
+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.

format_docstring-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+format_docstring