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

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

@@ -6,6 +6,13 @@ 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.2] - 2024-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.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: format-docstring
-Version: 0.2.1
+Version: 0.2.2
 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>

{format_docstring-0.2.1 → format_docstring-0.2.2}/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.

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

@@ -221,6 +221,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,7 +302,7 @@ 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)
 
     replacements: list[tuple[int, int, str]] = []
@@ -387,10 +434,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 +457,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)
@@ -521,6 +579,7 @@ def wrap_docstring(
         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 +603,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
     -------
@@ -565,6 +627,7 @@ def wrap_docstring(
             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(
@@ -573,5 +636,6 @@ def wrap_docstring(
         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.1 → format_docstring-0.2.2}/format_docstring/line_wrap_google.py

@@ -8,6 +8,7 @@ def wrap_docstring_google(
         fix_rst_backticks: bool = True,
         parameter_metadata: ParameterMetadata | None = None,
         return_annotation: str | None = None,
+        attribute_metadata: ParameterMetadata | None = None,
 ) -> str:
     """A placeholder for now."""  # noqa: D401
     return ''

{format_docstring-0.2.1 → format_docstring-0.2.2}/format_docstring/line_wrap_numpy.py

@@ -19,6 +19,7 @@ def wrap_docstring_numpy(
         leading_indent: int | None = None,
         fix_rst_backticks: bool = False,
         parameter_metadata: ParameterMetadata | None = None,
+        attribute_metadata: ParameterMetadata | None = None,
         return_annotation: str | None = None,
 ) -> str:
     """
@@ -66,11 +67,14 @@ def wrap_docstring_numpy(
         'other parameters:',
         'other parameter',  # tolerate typo
         'other parameter:',
+    }
+    SECTION_ATTRIBUTES = {
         'attributes',
         'attributes:',
         'attribute',  # tolerate typo
         'attribute:',
     }
+    SECTION_SIGNABLE = SECTION_PARAMS | SECTION_ATTRIBUTES
     SECTION_RETURNS_YIELDS = {
         'returns',
         'returns:',
@@ -156,7 +160,11 @@ def wrap_docstring_numpy(
 
         # Parameters-like sections
         section_lower_case: str = current_section.lower()
-        if section_lower_case in SECTION_PARAMS:
+        if section_lower_case in SECTION_SIGNABLE:
+            metadata_for_section = parameter_metadata
+            if section_lower_case in SECTION_ATTRIBUTES:
+                metadata_for_section = attribute_metadata or parameter_metadata
+
             if line.strip() == '':
                 temp_out.append(line)
                 i += 1
@@ -172,7 +180,7 @@ def wrap_docstring_numpy(
                 fixed_line = _fix_colon_spacing(line)
                 fixed_line = _standardize_default_value(fixed_line)
                 fixed_line = _rewrite_parameter_signature(
-                    fixed_line, parameter_metadata
+                    fixed_line, metadata_for_section
                 )
                 fixed_line = _standardize_default_value(fixed_line)
                 temp_out.append(fixed_line)

{format_docstring-0.2.1 → format_docstring-0.2.2}/format_docstring.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: format-docstring
-Version: 0.2.1
+Version: 0.2.2
 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>

{format_docstring-0.2.1 → format_docstring-0.2.2}/format_docstring.egg-info/SOURCES.txt

@@ -65,6 +65,7 @@ tests/test_data/end_to_end/numpy/section_title_fixed.txt
 tests/test_data/end_to_end/numpy/sections_notes_examples.txt
 tests/test_data/end_to_end/numpy/signature_dont_sync_raises.txt
 tests/test_data/end_to_end/numpy/signature_line_is_not_wrapped.txt
+tests/test_data/end_to_end/numpy/signature_sync_class_docstrings.txt
 tests/test_data/end_to_end/numpy/signature_sync_parameters.txt
 tests/test_data/end_to_end/numpy/signature_sync_returns.txt
 tests/test_data/end_to_end/numpy/signature_sync_yields.txt

{format_docstring-0.2.1 → format_docstring-0.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "format-docstring"
-version = "0.2.1"
+version = "0.2.2"
 description = "A Python formatter to wrap/adjust docstring lines"
 readme = "README.md"
 license = {text = "MIT"}

{format_docstring-0.2.1 → format_docstring-0.2.2}/tests/test_data/end_to_end/numpy/fix_rst_backticks.txt

@@ -162,7 +162,7 @@ class DataProcessor:
 
     Attributes
     ----------
-    mode : str
+    mode : str, default='standard'
         Processing mode, one of ``'simple'``, ``'standard'``, or
         ``'advanced'``.
     pipelines : list

format_docstring-0.2.2/tests/test_data/end_to_end/numpy/signature_sync_class_docstrings.txt

@@ -0,0 +1,203 @@
+LINE_LENGTH: 79
+
+**********
+from typing import Callable, Mapping
+
+
+class Widget:
+    """
+    Widget docstring.
+
+    Parameters
+    ----------
+    foo : str
+        Primary value.
+    bar : int
+        Secondary value.
+    options : tuple
+        Additional options payload.
+    callback : Callable
+        Callback invoked after processing.
+    arg_not_in_init_signature    :"MyCustomClassThatHasVeryVeryVeryVeryVeryVeryVeryVeryLongName"
+        Arg
+
+    Attributes
+    ----------
+    qux : dict
+        Class attribute.
+    count : tuple
+        Count attribute.
+    settings : Mapping
+        Settings payload.
+    threshold : float
+        Threshold attribute.
+    prefix : str | None, default='x'
+        Prefix attribute.
+    """
+
+    qux: dict[str, list[int]] = {'alpha': [1, 2]}
+    count: tuple[int, ...]
+    settings: Mapping[str, tuple[int, ...]]
+    threshold: float = 0.75
+    prefix = 'x'  # type: str | None
+
+    def __init__(
+            self,
+            foo: dict[str, list[int]],
+            bar: 'PathLike[str]' | None = None,
+            *,
+            options: tuple[list[int], dict[str, float]] = (
+                [1, 2], {'scale': 0.5}
+            ),
+            callback: Callable[[str, int], bool] | None = None,
+    ) -> None:
+        """Init."""
+        self.foo = foo
+        self.bar = bar
+        self.options = options
+        self.callback = callback
+
+
+class Both:
+    """
+    Both class docstring and __init__
+    docstring will have a Parameters section,
+    and this tool will
+    format the type hints and default values in both
+    docstrings. Even
+    though this is not best
+    practice (and some linters will
+    report an error), it
+    is out of the scope
+    of this
+    formatter
+    to
+    fix
+    this.
+
+    Parameters
+    ----------
+    data:
+        The input data
+    metadata:
+        The metadata
+
+    Attributes
+    ----------
+    something:
+        Something
+    important:
+        Important
+    """
+
+    something: tuple[str, ...] = ['a', 'b', "c", "d"]
+    important: bool = False
+
+    def __init__(self, data: np.ndarray, metadata: dict[str, Any]) -> None:
+        """
+        Initialize the class.
+
+        Parameters
+        ----------
+        data: np.ndarray
+            The input data
+        metadata:
+            The metadata
+        """
+        pass
+
+**********
+from typing import Callable, Mapping
+
+
+class Widget:
+    """
+    Widget docstring.
+
+    Parameters
+    ----------
+    foo : dict[str, list[int]]
+        Primary value.
+    bar : 'PathLike[str]' | None, default=None
+        Secondary value.
+    options : tuple[list[int], dict[str, float]], default=([1, 2], {'scale': 0.5})
+        Additional options payload.
+    callback : Callable[[str, int], bool] | None, default=None
+        Callback invoked after processing.
+    arg_not_in_init_signature : "MyCustomClassThatHasVeryVeryVeryVeryVeryVeryVeryVeryLongName"
+        Arg
+
+    Attributes
+    ----------
+    qux : dict[str, list[int]], default={'alpha': [1, 2]}
+        Class attribute.
+    count : tuple[int, ...]
+        Count attribute.
+    settings : Mapping[str, tuple[int, ...]]
+        Settings payload.
+    threshold : float, default=0.75
+        Threshold attribute.
+    prefix :
+        Prefix attribute.
+    """
+
+    qux: dict[str, list[int]] = {'alpha': [1, 2]}
+    count: tuple[int, ...]
+    settings: Mapping[str, tuple[int, ...]]
+    threshold: float = 0.75
+    prefix = 'x'  # type: str | None
+
+    def __init__(
+            self,
+            foo: dict[str, list[int]],
+            bar: 'PathLike[str]' | None = None,
+            *,
+            options: tuple[list[int], dict[str, float]] = (
+                [1, 2], {'scale': 0.5}
+            ),
+            callback: Callable[[str, int], bool] | None = None,
+    ) -> None:
+        """Init."""
+        self.foo = foo
+        self.bar = bar
+        self.options = options
+        self.callback = callback
+
+
+class Both:
+    """
+    Both class docstring and __init__ docstring will have a Parameters section,
+    and this tool will format the type hints and default values in both
+    docstrings. Even though this is not best practice (and some linters will
+    report an error), it is out of the scope of this formatter to fix this.
+
+    Parameters
+    ----------
+    data : np.ndarray
+        The input data
+    metadata : dict[str, Any]
+        The metadata
+
+    Attributes
+    ----------
+    something : tuple[str, ...], default=['a', 'b', "c", "d"]
+        Something
+    important : bool, default=False
+        Important
+    """
+
+    something: tuple[str, ...] = ['a', 'b', "c", "d"]
+    important: bool = False
+
+    def __init__(self, data: np.ndarray, metadata: dict[str, Any]) -> None:
+        """
+        Initialize the class.
+
+        Parameters
+        ----------
+        data : np.ndarray
+            The input data
+        metadata : dict[str, Any]
+            The metadata
+        """
+        pass

{format_docstring-0.2.1 → format_docstring-0.2.2}/tests/test_data/end_to_end/numpy/signature_sync_parameters.txt

@@ -98,6 +98,37 @@ class Example:
         """
         return flag
 
+
+def docstring_has_inconsistent_args_than_signature(
+        a: int,
+        b: str,
+        c: bool,
+        d: float,
+) -> None:
+    """
+    This
+    docstring has
+    inconsistent arguments
+    than the function signature.
+    This tool will only format the "common
+    args" (args that are in both the docstring
+    and the function signature). Some docstring linters
+    will report an error, but it is out of scope for this tool to deal with this issue.
+
+    Parameters
+    ----------
+    b                   :
+        B
+    d  :
+        D
+    e:
+        E
+    f:
+        F
+    """
+    pass
+
+
 **********
 from typing import List, Optional
 
@@ -195,3 +226,29 @@ class Example:
             Result.
         """
         return flag
+
+
+def docstring_has_inconsistent_args_than_signature(
+        a: int,
+        b: str,
+        c: bool,
+        d: float,
+) -> None:
+    """
+    This docstring has inconsistent arguments than the function signature. This
+    tool will only format the "common args" (args that are in both the
+    docstring and the function signature). Some docstring linters will report
+    an error, but it is out of scope for this tool to deal with this issue.
+
+    Parameters
+    ----------
+    b : str
+        B
+    d : float
+        D
+    e :
+        E
+    f :
+        F
+    """
+    pass