format-docstring 0.2.0__py3-none-any.whl → 0.2.2__py3-none-any.whl

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/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/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/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,12 +67,15 @@ def wrap_docstring_numpy(
         'other parameters:',
         'other parameter',  # tolerate typo
         'other parameter:',
+    }
+    SECTION_ATTRIBUTES = {
         'attributes',
         'attributes:',
         'attribute',  # tolerate typo
         'attribute:',
     }
-    SECTION_RETURNS = {
+    SECTION_SIGNABLE = SECTION_PARAMS | SECTION_ATTRIBUTES
+    SECTION_RETURNS_YIELDS = {
         'returns',
         'returns:',
         'return',  # tolerate typo
@@ -80,6 +84,8 @@ def wrap_docstring_numpy(
         'yields:',
         'yield',  # tolerate typo
         'yield:',
+    }
+    SECTION_RAISES = {
         'raises',
         'raises:',
         'raise',  # tolerate typo
@@ -154,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
@@ -170,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)
@@ -183,7 +193,7 @@ def wrap_docstring_numpy(
             continue
 
         # Returns/Yields sections
-        if section_lower_case in SECTION_RETURNS:
+        if section_lower_case in SECTION_RETURNS_YIELDS:
             if line.strip() == '':
                 temp_out.append(line)
                 i += 1
@@ -234,6 +244,19 @@ def wrap_docstring_numpy(
             i += 1
             continue
 
+        # Raises section
+        if section_lower_case in SECTION_RAISES:
+            if line.strip() == '':
+                temp_out.append(line)
+                i += 1
+                continue
+
+            # Treat top-level lines as signatures
+            if indent_length <= leading_indent:  # type: ignore[operator]
+                temp_out.append(line)
+                i += 1
+                continue
+
         # Examples or any other section
         collect_to_temp_output(temp_out, line)
         i += 1

{format_docstring-0.2.0.dist-info → format_docstring-0.2.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: format-docstring
-Version: 0.2.0
+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.2.dist-info/RECORD

@@ -0,0 +1,15 @@
+format_docstring/__init__.py,sha256=3bPK0B7mVsgqXVtcJYGKBO8JAM5gYWmdQPaRrI2tpsI,146
+format_docstring/base_fixer.py,sha256=PtTn-bMqlaQAJsNCzMbAxBC5_mjTl1pmC16iLZf_v2w,3118
+format_docstring/config.py,sha256=2VvOL1AaYM-ODCZf-U3R3ptePR_DMZXnOVItbpp6yns,5528
+format_docstring/docstring_rewriter.py,sha256=17tjHWqgptWeJZlFrJN7jqV3326IUgjEB4F3RKHmb-E,20848
+format_docstring/line_wrap_google.py,sha256=PiWeEIJnbyEoxt3nxpzvOyxOMmBaQvcDKEPLbuyB4FM,464
+format_docstring/line_wrap_numpy.py,sha256=8SBSSU47FR1enKxLSBX2tyX09f_cdDfg7FABKR49JeA,28932
+format_docstring/line_wrap_utils.py,sha256=cXHTFMLefUFVZgUzC-UU6FrNCzh4kAOH7E_AMwm-bz0,27988
+format_docstring/main_jupyter.py,sha256=rkNjk0XwCukxCrWsr8PNDCywxYH8Jpj5XCxql_3GPOI,6309
+format_docstring/main_py.py,sha256=aYVOEtH15UpXugqkBdiYFzyR9QCnP7FXZ6PFt7fwvdk,4562
+format_docstring-0.2.2.dist-info/licenses/LICENSE,sha256=UNm_-hqU-1dAB3bLytP6wvGtUeitoJde2xzb5wgVYn0,1061
+format_docstring-0.2.2.dist-info/METADATA,sha256=6ff2qlTJdvJnMRWddv9fJimTyjKljCFqqoay-tT7bNI,15454
+format_docstring-0.2.2.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+format_docstring-0.2.2.dist-info/entry_points.txt,sha256=Re2iHTzfgKJgeXDga5Z4bGNPtWGmxupOdzTolwn52sk,129
+format_docstring-0.2.2.dist-info/top_level.txt,sha256=NXPwfHm_1YwwGuetwtK3pJv0jXwXelqPTNCFpm5LQyE,17
+format_docstring-0.2.2.dist-info/RECORD,,

format_docstring-0.2.0.dist-info/RECORD

@@ -1,15 +0,0 @@
-format_docstring/__init__.py,sha256=3bPK0B7mVsgqXVtcJYGKBO8JAM5gYWmdQPaRrI2tpsI,146
-format_docstring/base_fixer.py,sha256=O-8FYKRvKg1BQJFcT23Ju85o-m3341PFulbeBM-UJss,3117
-format_docstring/config.py,sha256=2VvOL1AaYM-ODCZf-U3R3ptePR_DMZXnOVItbpp6yns,5528
-format_docstring/docstring_rewriter.py,sha256=-WFPBCfOw08Xd1utrTG8gVPi0P-Cn5ookCzK-nSUj7A,18407
-format_docstring/line_wrap_google.py,sha256=ECfXjKMOADXClqXStvtdvvYi_C3LcUZ5rrigNvyOxUo,403
-format_docstring/line_wrap_numpy.py,sha256=8J5_AWY2bPuilyk6OEKPqgbT0Zv2p70SG2wYXJ2gABs,28133
-format_docstring/line_wrap_utils.py,sha256=cXHTFMLefUFVZgUzC-UU6FrNCzh4kAOH7E_AMwm-bz0,27988
-format_docstring/main_jupyter.py,sha256=rkNjk0XwCukxCrWsr8PNDCywxYH8Jpj5XCxql_3GPOI,6309
-format_docstring/main_py.py,sha256=aYVOEtH15UpXugqkBdiYFzyR9QCnP7FXZ6PFt7fwvdk,4562
-format_docstring-0.2.0.dist-info/licenses/LICENSE,sha256=UNm_-hqU-1dAB3bLytP6wvGtUeitoJde2xzb5wgVYn0,1061
-format_docstring-0.2.0.dist-info/METADATA,sha256=p5wNL7yKCipSr-WhZ2yZFQxMk4sxeJsjcHEQ4EuP8F4,15454
-format_docstring-0.2.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-format_docstring-0.2.0.dist-info/entry_points.txt,sha256=Re2iHTzfgKJgeXDga5Z4bGNPtWGmxupOdzTolwn52sk,129
-format_docstring-0.2.0.dist-info/top_level.txt,sha256=NXPwfHm_1YwwGuetwtK3pJv0jXwXelqPTNCFpm5LQyE,17
-format_docstring-0.2.0.dist-info/RECORD,,