format-docstring 0.2.1__tar.gz → 0.2.3__tar.gz

{format_docstring-0.2.1 → format_docstring-0.2.3}/.pre-commit-config.yaml

@@ -6,10 +6,7 @@ repos:
       - 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
@@ -18,11 +15,6 @@ repos:
         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:
@@ -37,11 +29,27 @@ repos:
     rev: 1.18.0
     hooks:
       - id: yamlfix
+  - repo: https://github.com/pappasam/toml-sort
+    rev: v0.24.2
+    hooks:
+      - id: toml-sort-fix
+        args:
+          - --in-place
+          - --sort-table-keys
+          - --sort-inline-tables
+          - --sort-first=name,version,dependencies,requires-python,authors,maintainers
+          - --trailing-comma-inline-array
+          - --sort-inline-arrays
+  - repo: https://github.com/macisamuele/language-formatters-pre-commit-hooks
+    rev: v2.15.0
+    hooks:
+      - id: pretty-format-ini
+        args: [--autofix]
   - repo: https://github.com/hukkin/mdformat
     rev: 1.0.0
     hooks:
       - id: mdformat
-        args: [--wrap, '79', --number]
+        args: [--wrap=79, --number]
         additional_dependencies: [mdformat-gfm]
   - repo: https://github.com/jsh9/format-json
     rev: 0.1.2
@@ -54,9 +62,10 @@ repos:
           - --no-sort-keys
           - --no-eof-newline
   - repo: https://github.com/jsh9/markdown-toc-creator
-    rev: 0.0.11
+    rev: 0.1.0
     hooks:
       - id: markdown-toc-creator
+        exclude: ^tests/test_data/|^AGENTS\.md$|^CHANGELOG\.md$
   - repo: https://github.com/jsh9/markdown-heading-numbering
     rev: 0.1.0
     hooks:

{format_docstring-0.2.1 → format_docstring-0.2.3}/CHANGELOG.md

@@ -6,6 +6,25 @@ 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.3] - 2025-10-22
+
+- Added
+  - A lot more linters
+  - Formatters for TOML and INI config files
+- Changed
+  - A lot of code changes to pass the linter checks
+- Removed
+  - Unnecessary pre-commit hooks
+- Full diff
+  - https://github.com/jsh9/format-docstring/compare/0.2.2...0.2.3
+
+## [0.2.2] - 2025-10-20
+
+- Added
+  - Formatting support for type hints and default values in class docstrings
+- Full diff
+  - https://github.com/jsh9/format-docstring/compare/0.2.1...0.2.2
+
 ## [0.2.1] - 2025-10-20
 
 - Fixed

{format_docstring-0.2.1 → format_docstring-0.2.3}/PKG-INFO

@@ -1,32 +1,32 @@
 Metadata-Version: 2.4
 Name: format-docstring
-Version: 0.2.1
+Version: 0.2.3
 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
+Project-URL: Repository, https://github.com/your/repo.git
+Keywords: code-style,docstring,formatter,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
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python
 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: jupyter-notebook-parser>=0.1.4
 Requires-Dist: tomli>=1.1.0; python_version < "3.11"
 Dynamic: license-file
 
@@ -34,11 +34,11 @@ Dynamic: license-file
 
 A Python formatter to automatically format numpy-style docstrings.
 
-______________________________________________________________________
+<!--TOC-->
 
-**Table of Contents:**
+______________________________________________________________________
 
-<!--TOC-->
+**Table of Contents**
 
 - [1. Overview](#1-overview)
 - [2. Before vs After Examples](#2-before-vs-after-examples)
@@ -59,10 +59,10 @@ ______________________________________________________________________
   - [5.3. `pyproject.toml` Configuration](#53-pyprojecttoml-configuration)
 - [6. Caveat](#6-caveat)
 
-<!--TOC-->
-
 ______________________________________________________________________
 
+<!--TOC-->
+
 ## 1. Overview
 
 `format-docstring` is a tool that automatically formats and wraps docstring

{format_docstring-0.2.1 → format_docstring-0.2.3}/README.md

@@ -2,11 +2,11 @@
 
 A Python formatter to automatically format numpy-style docstrings.
 
-______________________________________________________________________
+<!--TOC-->
 
-**Table of Contents:**
+______________________________________________________________________
 
-<!--TOC-->
+**Table of Contents**
 
 - [1. Overview](#1-overview)
 - [2. Before vs After Examples](#2-before-vs-after-examples)
@@ -27,10 +27,10 @@ ______________________________________________________________________
   - [5.3. `pyproject.toml` Configuration](#53-pyprojecttoml-configuration)
 - [6. Caveat](#6-caveat)
 
-<!--TOC-->
-
 ______________________________________________________________________
 
+<!--TOC-->
+
 ## 1. Overview
 
 `format-docstring` is a tool that automatically formats and wraps docstring

{format_docstring-0.2.1 → format_docstring-0.2.3}/format_docstring/base_fixer.py

@@ -15,7 +15,7 @@ class BaseFixer:
     ----------
     path : str
         Target file or directory to process.
-    exclude_pattern : str, default='\.git|\.tox|\.pytest_cache'
+    exclude_pattern : str, default=r'\.git|\.tox|\.pytest_cache'
         Regular expression describing paths to skip.
     verbose : str, default='default'
         Verbosity mode; ``'diff'`` prints unified diffs for rewritten files.
@@ -42,7 +42,7 @@ class BaseFixer:
             if not should_exclude_file(f, self.exclude_pattern)
         ]
 
-    def _print_diff(self, filename: str, before: str, after: str) -> None:
+    def print_diff(self, filename: str, before: str, after: str) -> None:
         """Print a unified diff when verbose mode is enabled."""
         if self.verbose != 'diff':
             return

{format_docstring-0.2.1 → format_docstring-0.2.3}/format_docstring/config.py

@@ -4,9 +4,10 @@ from __future__ import annotations
 
 import sys
 from pathlib import Path
-from typing import Any
+from typing import TYPE_CHECKING, Any
 
-import click
+if TYPE_CHECKING:
+    import click
 
 if sys.version_info >= (3, 11):
     import tomllib
@@ -132,7 +133,7 @@ def load_config_from_file(config_file: Path) -> dict[str, Any]:
         return {}
 
     try:
-        with open(config_file, 'rb') as fp:
+        with Path(config_file).open('rb') as fp:
             raw_config = tomllib.load(fp)
 
         # Extract [tool.format_docstring] section
@@ -144,7 +145,7 @@ def load_config_from_file(config_file: Path) -> dict[str, Any]:
         return {
             k.replace('-', '_'): v for k, v in format_docstring_section.items()
         }
-    except Exception:
+    except Exception:  # noqa: BLE001
         # If there's any error reading/parsing the file, return empty config
         return {}
 

{format_docstring-0.2.1 → format_docstring-0.2.3}/format_docstring/docstring_rewriter.py

@@ -2,14 +2,18 @@ from __future__ import annotations
 
 import ast
 import io
+import operator
 import tokenize
+from typing import TYPE_CHECKING
 
 from format_docstring.line_wrap_google import wrap_docstring_google
 from format_docstring.line_wrap_numpy import (
     handle_single_line_docstring,
     wrap_docstring_numpy,
 )
-from format_docstring.line_wrap_utils import ParameterMetadata
+
+if TYPE_CHECKING:
+    from format_docstring.line_wrap_utils import ParameterMetadata
 
 ModuleClassOrFunc = (
     ast.Module | ast.ClassDef | ast.FunctionDef | ast.AsyncFunctionDef
@@ -91,11 +95,13 @@ def _normalize_signature_segment(segment: str | None) -> str | None:
         # iterator order mirrors the unparse traversal so we can reapply them.
         original_strings: list[str] = []
         try:
-            for tok in tokenize.generate_tokens(
-                io.StringIO(normalized).readline
-            ):
-                if tok.type == tokenize.STRING:
-                    original_strings.append(tok.string)
+            original_strings.extend(
+                tok.string
+                for tok in tokenize.generate_tokens(
+                    io.StringIO(normalized).readline
+                )
+                if tok.type == tokenize.STRING
+            )
         except tokenize.TokenError:
             original_strings = []
 
@@ -105,6 +111,7 @@ def _normalize_signature_segment(segment: str | None) -> str | None:
             for tok in tokenize.generate_tokens(
                 io.StringIO(canonical).readline
             ):
+                current_tok: tokenize.TokenInfo = tok
                 if tok.type == tokenize.STRING:
                     replacement = next(string_iter, None)
                     if replacement is not None:
@@ -116,12 +123,12 @@ def _normalize_signature_segment(segment: str | None) -> str | None:
                             if ast.literal_eval(
                                 replacement
                             ) == ast.literal_eval(tok.string):
-                                tok = tok._replace(string=replacement)
-                        except Exception:
+                                current_tok = tok._replace(string=replacement)
+                        except Exception:  # noqa: BLE001
                             pass
 
-                rebuilt_tokens.append(tok)
-                if tok.type == tokenize.ENDMARKER:
+                rebuilt_tokens.append(current_tok)
+                if current_tok.type == tokenize.ENDMARKER:
                     break
 
             # Untokenize the rebuilt stream while trimming the leading/trailing
@@ -221,6 +228,53 @@ def _collect_param_metadata(
     return metadata
 
 
+def _collect_class_metadata(
+        node: ast.ClassDef,
+        source_code: str,
+) -> tuple[ParameterMetadata, ParameterMetadata]:
+    """
+    Build metadata for class docstrings using ``__init__`` and class attrs.
+    """
+    init_metadata: ParameterMetadata = {}
+    attribute_metadata: ParameterMetadata = {}
+
+    init_method: ast.FunctionDef | None = None
+    for stmt in node.body:
+        if isinstance(stmt, ast.FunctionDef) and stmt.name == '__init__':
+            init_method = stmt
+            break
+
+    if init_method is not None:
+        init_metadata = _collect_param_metadata(init_method, source_code)
+        # ``self``/``cls`` rarely appear in docstrings; drop to avoid noise.
+        init_metadata.pop('self', None)
+        init_metadata.pop('cls', None)
+
+    for stmt in node.body:
+        if isinstance(stmt, ast.AnnAssign):
+            target = stmt.target
+            if not isinstance(target, ast.Name):
+                continue
+
+            annotation = _render_signature_piece(stmt.annotation, source_code)
+            default = _render_signature_piece(stmt.value, source_code)
+            attribute_metadata[target.id] = (annotation, default)
+            continue
+
+        if isinstance(stmt, ast.Assign):
+            if len(stmt.targets) != 1:
+                continue
+
+            assign_target = stmt.targets[0]
+            if not isinstance(assign_target, ast.Name):
+                continue
+
+            # Record that this attribute explicitly has no annotation/default.
+            attribute_metadata[assign_target.id] = ('', None)
+
+    return init_metadata, attribute_metadata
+
+
 def fix_src(
         source_code: str,
         *,
@@ -255,19 +309,20 @@ def fix_src(
     spans directly in the original text to preserve non-docstring formatting
     and comments.
     """
-    tree: ast.Module = ast.parse(source_code)
+    tree: ast.Module = ast.parse(source_code, type_comments=True)
     line_starts: list[int] = calc_line_starts(source_code)
 
+    # Store (start, end, replacement text) tuples
     replacements: list[tuple[int, int, str]] = []
 
     # Module-level docstring
     replacement = build_replacement_docstring(
         tree,
-        source_code,
-        line_starts,
-        line_length,
-        docstring_style,
-        fix_rst_backticks,
+        source_code=source_code,
+        line_starts=line_starts,
+        line_length=line_length,
+        docstring_style=docstring_style,
+        fix_rst_backticks=fix_rst_backticks,
     )
     if replacement is not None:
         replacements.append(replacement)
@@ -279,11 +334,11 @@ def fix_src(
         ):
             replacement = build_replacement_docstring(
                 node,
-                source_code,
-                line_starts,
-                line_length,
-                docstring_style,
-                fix_rst_backticks,
+                source_code=source_code,
+                line_starts=line_starts,
+                line_length=line_length,
+                docstring_style=docstring_style,
+                fix_rst_backticks=fix_rst_backticks,
             )
             if replacement is not None:
                 replacements.append(replacement)
@@ -292,7 +347,8 @@ def fix_src(
     if not replacements:
         return source_code
 
-    replacements.sort(key=lambda x: x[0], reverse=True)
+    # Sort by starting index descending
+    replacements.sort(key=operator.itemgetter(0), reverse=True)
     new_src = source_code
     for start, end, text in replacements:
         new_src = new_src[:start] + text + new_src[end:]
@@ -324,6 +380,7 @@ def calc_line_starts(source_code: str) -> list[int]:
 
 def build_replacement_docstring(
         node: ModuleClassOrFunc,
+        *,
         source_code: str,
         line_starts: list[int],
         line_length: int,
@@ -364,7 +421,7 @@ def build_replacement_docstring(
         return None
 
     start: int = calc_abs_pos(line_starts, val.lineno, val.col_offset)
-    end: int = calc_abs_pos(line_starts, val.end_lineno, val.end_col_offset)  # type: ignore[arg-type]  # noqa: LN002
+    end: int = calc_abs_pos(line_starts, val.end_lineno, val.end_col_offset)  # type: ignore[arg-type]
     original_literal = source_code[start:end]
 
     if _has_inline_no_format_comment(source_code, end):
@@ -387,10 +444,20 @@ def build_replacement_docstring(
     )
 
     param_metadata: ParameterMetadata | None = None
+    attribute_metadata: ParameterMetadata | None = None
     return_annotation: str | None = None
     if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
         param_metadata = _collect_param_metadata(node, source_code)
         return_annotation = _render_signature_piece(node.returns, source_code)
+    elif isinstance(node, ast.ClassDef):
+        init_metadata, class_attr_metadata = _collect_class_metadata(
+            node, source_code
+        )
+        if init_metadata:
+            param_metadata = init_metadata
+
+        if class_attr_metadata:
+            attribute_metadata = class_attr_metadata
 
     wrapped: str = wrap_docstring(
         doc,
@@ -400,6 +467,7 @@ def build_replacement_docstring(
         fix_rst_backticks=fix_rst_backticks,
         function_param_metadata=param_metadata,
         function_return_annotation=return_annotation,
+        class_attribute_metadata=attribute_metadata,
     )
 
     new_literal: str | None = rebuild_literal(original_literal, wrapped)
@@ -496,10 +564,10 @@ def rebuild_literal(original_literal: str, content: str) -> str | None:
     prefix = original_literal[:i]
 
     delim = ''
-    if original_literal[i : i + 3] in ('"""', "'''"):
+    if original_literal[i : i + 3] in {'"""', "'''"}:
         delim = original_literal[i : i + 3]
         i += 3
-    elif i < n and original_literal[i] in ('"', "'"):
+    elif i < n and original_literal[i] in {'"', "'"}:
         delim = original_literal[i]
         i += 1
     else:
@@ -518,9 +586,11 @@ def wrap_docstring(
         line_length: int = 79,
         docstring_style: str = 'numpy',
         leading_indent: int = 0,
+        *,
         fix_rst_backticks: bool = True,
         function_param_metadata: ParameterMetadata | None = None,
         function_return_annotation: str | None = None,
+        class_attribute_metadata: ParameterMetadata | None = None,
 ) -> str:
     """
     Wrap a docstring to the given line length (stub).
@@ -544,6 +614,9 @@ def wrap_docstring(
     function_return_annotation : str | None, default=None
         The function's return annotation text (normalized), used to keep
         ``Returns``/``Yields`` signature lines synchronized.
+    class_attribute_metadata : ParameterMetadata | None, default=None
+        Attribute metadata for class docstrings (names mapped to annotations
+        and default values) collected from class-level assignments.
 
     Returns
     -------
@@ -560,18 +633,20 @@ def wrap_docstring(
     if style == 'google':
         return wrap_docstring_google(
             docstring,
-            line_length,
+            line_length=line_length,
             leading_indent=leading_indent,
             fix_rst_backticks=fix_rst_backticks,
             parameter_metadata=function_param_metadata,
             return_annotation=function_return_annotation,
+            attribute_metadata=class_attribute_metadata,
         )
     # Default to NumPy-style for unknown/unspecified styles to be permissive.
     return wrap_docstring_numpy(
         docstring,
-        line_length,
+        line_length=line_length,
         leading_indent=leading_indent,
         fix_rst_backticks=fix_rst_backticks,
         parameter_metadata=function_param_metadata,
+        attribute_metadata=class_attribute_metadata,
         return_annotation=function_return_annotation,
     )

format_docstring-0.2.3/format_docstring/line_wrap_google.py

@@ -0,0 +1,15 @@
+from format_docstring.line_wrap_utils import ParameterMetadata
+
+
+def wrap_docstring_google(
+        docstring: str,  # noqa: ARG001
+        *,
+        line_length: int,  # noqa: ARG001
+        leading_indent: int | None = None,  # noqa: ARG001
+        fix_rst_backticks: bool = True,  # noqa: ARG001
+        parameter_metadata: ParameterMetadata | None = None,  # noqa: ARG001
+        return_annotation: str | None = None,  # noqa: ARG001
+        attribute_metadata: ParameterMetadata | None = None,  # noqa: ARG001
+) -> str:
+    """A placeholder for now."""  # noqa: D401
+    return ''