docstring-format-checker 1.6.2__tar.gz → 1.7.0__tar.gz

{docstring_format_checker-1.6.2 → docstring_format_checker-1.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docstring-format-checker
-Version: 1.6.2
+Version: 1.7.0
 Summary: A CLI tool to check and validate Python docstring formatting and completeness
 Author: Chris Mahoney
 Author-email: Chris Mahoney <docstring-format-checker@data-science-extensions.com>

{docstring_format_checker-1.6.2 → docstring_format_checker-1.7.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "docstring-format-checker"
-version = "1.6.2"
+version = "1.7.0"
 description = "A CLI tool to check and validate Python docstring formatting and completeness"
 readme = "README.md"
 license = "MIT"
@@ -75,7 +75,8 @@ docs = [
     "pygithub==2.*",
 ]
 test = [
-    "mypy==1.*,!=1.17.*",
+    "ty==0.*",
+    # "mypy==1.*,!=1.17.*",
     "parameterized==0.*",
     "pytest==8.*",
     "pytest-clarity==1.*",
@@ -154,6 +155,7 @@ disable = [
     "C0103",  # invalid-name
     "C0301",  # line-too-long
     "C0302",  # too-many-lines
+    "R0912",  # too-many-branches
     "R0913",  # too-many-arguments
     "R0914",  # too-many-locals
     "R0915",  # too-many-statements
@@ -188,6 +190,7 @@ allow_undefined_sections = false
 require_docstrings = true
 check_private = true
 validate_param_types = true
+optional_style = "silent"  #<-- optional: "silent", "validate", or "strict"
 sections = [
     { order=1, name="summary",  type="free_text",          required=true,  admonition="note",     prefix="!!!" },
     { order=2, name="details",  type="free_text",          required=false, admonition="abstract", prefix="???+" },

{docstring_format_checker-1.6.2 → docstring_format_checker-1.7.0}/src/docstring_format_checker/cli.py

@@ -52,6 +52,7 @@ from typing import Optional
 # ## Python Third Party Imports ----
 import pyfiglet
 from rich.console import Console
+from rich.markup import escape
 from rich.panel import Panel
 from rich.table import Table
 from typer import Argument, CallbackParam, Context, Exit, Option, Typer, echo
@@ -270,6 +271,7 @@ def _show_config_example_callback() -> None:
         [blue]require_docstrings = true[/blue]
         [blue]check_private = true[/blue]
         [blue]validate_param_types = true[/blue]
+        [blue]optional_style = "validate"[/blue]  [green]# "silent", "validate", or "strict"[/green]
         [blue]sections = [[/blue]
             [blue]{ order = 1, name = "summary",  type = "free_text",          required = true, admonition = "note", prefix = "!!!" },[/blue]
             [blue]{ order = 2, name = "details",  type = "free_text",          required = false, admonition = "abstract", prefix = "???+" },[/blue]
@@ -485,7 +487,7 @@ def _display_table_output(results: dict[str, list[DocstringError]]) -> None:
                 str(error.line_number) if error.line_number > 0 else "",
                 error.item_name,
                 error.item_type,
-                formatted_error_message,
+                f"[red]{formatted_error_message}[/red]",
             )
     console.print(table)
 
@@ -545,10 +547,13 @@ def _format_error_output(error: DocstringError) -> list[str]:
     individual_errors: list[str] = _split_error_messages(error.message)
 
     for individual_error in individual_errors:
+        # Escape square brackets for Rich markup using Rich's escape function
+        individual_error: str = escape(individual_error)
+
         # Check if this error has multi-line content (e.g., parameter type mismatches)
         if "\n" in individual_error:
             # Split by newlines and add 4 spaces of extra indentation to each line
-            error_lines = individual_error.split("\n")
+            error_lines: list[str] = individual_error.split("\n")
             lines.append(f"    - {error_lines[0]}")  # First line gets the bullet
             for sub_line in error_lines[1:]:
                 if sub_line.strip():  # Only add non-empty lines

{docstring_format_checker-1.6.2 → docstring_format_checker-1.7.0}/src/docstring_format_checker/config.py

@@ -115,6 +115,7 @@ class GlobalConfig:
     require_docstrings: bool = True
     check_private: bool = False
     validate_param_types: bool = True
+    optional_style: Literal["silent", "validate", "strict"] = "validate"
 
 
 ## --------------------------------------------------------------------------- #
@@ -447,11 +448,20 @@ def _parse_global_config(tool_config: dict[str, Any]) -> GlobalConfig:
         (GlobalConfig):
             Parsed global configuration object.
     """
+    # Validate optional_style if provided
+    optional_style: str = tool_config.get("optional_style", "validate")
+    valid_styles: tuple[str, str, str] = ("silent", "validate", "strict")
+    if optional_style not in valid_styles:
+        raise InvalidConfigError(
+            f"Invalid optional_style: '{optional_style}'. Must be one of: {', '.join(valid_styles)}"
+        )
+
     return GlobalConfig(
         allow_undefined_sections=tool_config.get("allow_undefined_sections", False),
         require_docstrings=tool_config.get("require_docstrings", True),
         check_private=tool_config.get("check_private", False),
         validate_param_types=tool_config.get("validate_param_types", True),
+        optional_style=optional_style,  # type:ignore
     )
 
 

{docstring_format_checker-1.6.2 → docstring_format_checker-1.7.0}/src/docstring_format_checker/core.py

@@ -1124,9 +1124,14 @@ class DocstringChecker:
             (str):
                 Normalized type string.
         """
+
         # Remove whitespace
         normalized: str = re.sub(r"\s+", "", type_str)
 
+        # Normalize quotes: ast.unparse() uses single quotes but docstrings typically use double quotes
+        # Convert all quotes to single quotes for consistent comparison
+        normalized = normalized.replace('"', "'")
+
         # Make case-insensitive for basic types
         # But preserve case for complex types to avoid breaking things like Optional
         return normalized
@@ -1168,6 +1173,123 @@ class DocstringChecker:
 
         return mismatches
 
+    def _get_params_with_defaults(self, node: Union[ast.FunctionDef, ast.AsyncFunctionDef]) -> set[str]:
+        """
+        !!! note "Summary"
+            Get set of parameter names that have default values.
+
+        Params:
+            node (Union[ast.FunctionDef, ast.AsyncFunctionDef]):
+                The function node to analyse.
+
+        Returns:
+            (set[str]):
+                Set of parameter names that have default values.
+        """
+        params_with_defaults: set[str] = set()
+        args = node.args
+
+        # Regular args with defaults
+        num_defaults = len(args.defaults)
+        if num_defaults > 0:
+            # Defaults apply to the last n arguments
+            num_args = len(args.args)
+            for i in range(num_args - num_defaults, num_args):
+                if args.args[i].arg not in ("self", "cls"):
+                    params_with_defaults.add(args.args[i].arg)
+
+        # Keyword-only args with defaults
+        for i, arg in enumerate(args.kwonlyargs):
+            if args.kw_defaults[i] is not None:
+                params_with_defaults.add(arg.arg)
+
+        return params_with_defaults
+
+    def _process_optional_suffix(
+        self,
+        param_name: str,
+        doc_type: str,
+        params_with_defaults: set[str],
+        optional_style: str,
+    ) -> tuple[str, Optional[str]]:
+        """
+        !!! note "Summary"
+            Process the ', optional' suffix based on the optional_style mode.
+
+        Params:
+            param_name (str):
+                Name of the parameter.
+            doc_type (str):
+                Docstring type including potential ', optional' suffix.
+            params_with_defaults (set[str]):
+                Set of parameters that have default values.
+            optional_style (str):
+                The validation mode: 'silent', 'validate', or 'strict'.
+
+        Returns:
+            (tuple[str, Optional[str]]):
+                Tuple of (cleaned_type, error_message).
+        """
+        has_optional_suffix: bool = bool(re.search(r",\s*optional$", doc_type, flags=re.IGNORECASE))
+        clean_type: str = re.sub(r",\s*optional$", "", doc_type, flags=re.IGNORECASE).strip()
+        error_message: Optional[str] = None
+
+        if optional_style == "validate":
+            if has_optional_suffix and param_name not in params_with_defaults:
+                error_message = f"Parameter '{param_name}' has ', optional' suffix but no default value in signature"
+        elif optional_style == "strict":
+            if param_name in params_with_defaults and not has_optional_suffix:
+                error_message = (
+                    f"Parameter '{param_name}' has default value but missing ', optional' suffix in docstring"
+                )
+            elif has_optional_suffix and param_name not in params_with_defaults:
+                error_message = f"Parameter '{param_name}' has ', optional' suffix but no default value in signature"
+
+        return clean_type, error_message
+
+    def _format_optional_errors(self, errors: list[str]) -> str:
+        """
+        !!! note "Summary"
+            Format multiple optional suffix validation errors.
+
+        Params:
+            errors (list[str]):
+                List of error messages.
+
+        Returns:
+            (str):
+                Formatted error message.
+        """
+        if len(errors) == 1:
+            return errors[0]
+        formatted_errors: str = "\n  - ".join([""] + errors)
+        return f"Optional suffix validation errors:{formatted_errors}"
+
+    def _format_type_mismatches(self, mismatches: list[tuple[str, str, str]]) -> str:
+        """
+        !!! note "Summary"
+            Format parameter type mismatches for error output.
+
+        Params:
+            mismatches (list[tuple[str, str, str]]):
+                List of (param_name, sig_type, doc_type) tuples.
+
+        Returns:
+            (str):
+                Formatted error message.
+        """
+        mismatch_blocks: list[str] = []
+        for name, sig_type, doc_type in mismatches:
+            sig_type_clean: str = sig_type.replace("'", '"')
+            doc_type_clean: str = doc_type.replace("'", '"')
+            param_block: str = (
+                f"""'{name}':\n    - signature: '{sig_type_clean}'\n    - docstring: '{doc_type_clean}'"""
+            )
+            mismatch_blocks.append(param_block)
+
+        formatted_details: str = "\n  - ".join([""] + mismatch_blocks)
+        return f"Parameter type mismatch:{formatted_details}"
+
     def _validate_param_types(
         self, docstring: str, node: Union[ast.FunctionDef, ast.AsyncFunctionDef]
     ) -> Optional[str]:
@@ -1175,6 +1297,13 @@ class DocstringChecker:
         !!! note "Summary"
             Validate that parameter types in docstring match the signature.
 
+        ???+ abstract "Details"
+            Implements three validation modes based on `optional_style` configuration:
+
+            - **`"silent"`**: Strip `, optional` from docstring types before comparison.
+            - **`"validate"`**: Error if `, optional` appears on required parameters.
+            - **`"strict"`**: Require `, optional` for parameters with defaults, error if on required parameters.
+
         Params:
             docstring (str):
                 The docstring to validate.
@@ -1187,11 +1316,33 @@ class DocstringChecker:
         """
         # Extract types from both sources
         signature_types: dict[str, str] = self._extract_param_types(node)
-        docstring_types: dict[str, str] = self._extract_param_types_from_docstring(docstring)
+        docstring_types_raw: dict[str, str] = self._extract_param_types_from_docstring(docstring)
+
+        # Get parameters with default values
+        params_with_defaults: set[str] = self._get_params_with_defaults(node)
 
         # Get all parameter names (excluding self/cls)
         all_params: list[str] = [arg.arg for arg in node.args.args if arg.arg not in ("self", "cls")]
 
+        # Get the optional_style mode
+        optional_style: str = self.config.global_config.optional_style
+
+        # Process docstring types based on optional_style mode
+        docstring_types: dict[str, str] = {}
+        optional_errors: list[str] = []
+
+        for param_name, doc_type in docstring_types_raw.items():
+            clean_type, error_message = self._process_optional_suffix(
+                param_name, doc_type, params_with_defaults, optional_style
+            )
+            docstring_types[param_name] = clean_type
+            if error_message:
+                optional_errors.append(error_message)
+
+        # Return optional_style errors first if any
+        if optional_errors:
+            return self._format_optional_errors(optional_errors)
+
         # Check for parameters documented with type in docstring but missing annotation in signature
         for param_name in all_params:
             if param_name in docstring_types and param_name not in signature_types:
@@ -1208,20 +1359,7 @@ class DocstringChecker:
         mismatches: list[tuple[str, str, str]] = self._compare_param_types(signature_types, docstring_types)
 
         if mismatches:
-            # Format each mismatch with parameter name on one line, signature and docstring indented below
-            # Use 2 spaces for params, 4 for sig/doc (suitable for table output)
-            # List output will add additional indentation via CLI formatting
-            mismatch_blocks: list[str] = []
-            for name, sig_type, doc_type in mismatches:
-                sig_type: str = sig_type.replace("'", '"')
-                doc_type: str = doc_type.replace("'", '"')
-                param_block: str = f"""'{name}':\n    - signature: '{sig_type}'\n    - docstring: '{doc_type}' """
-                mismatch_blocks.append(param_block)
-
-            # Join all parameter blocks with proper indentation
-            formatted_details: str = "\n  - ".join([""] + mismatch_blocks)
-
-            return f"Parameter type mismatch:{formatted_details}"
+            return self._format_type_mismatches(mismatches)
 
         return None