docstring-format-checker 0.7.0__tar.gz → 0.9.0__tar.gz

{docstring_format_checker-0.7.0 → docstring_format_checker-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docstring-format-checker
-Version: 0.7.0
+Version: 0.9.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-0.7.0 → docstring_format_checker-0.9.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "docstring-format-checker"
-version = "v0.7.0"
+version = "v0.9.0"
 description = "A CLI tool to check and validate Python docstring formatting and completeness"
 readme = "README.md"
 license = "MIT"

{docstring_format_checker-0.7.0 → docstring_format_checker-0.9.0}/src/docstring_format_checker/__init__.py

@@ -4,7 +4,7 @@ Docstring Format Checker.
 A CLI tool to check and validate Python docstring formatting and completeness.
 """
 
-__version__ = "v0.7.0"
+__version__ = "v0.9.0"
 __author__ = "Chris Mahoney"
 __email__ = "docstring-format-checker@data-science-extensions.com"
 

{docstring_format_checker-0.7.0 → docstring_format_checker-0.9.0}/src/docstring_format_checker/cli.py

@@ -56,7 +56,11 @@ from typer import Argument, CallbackParam, Context, Exit, Option, Typer, echo
 
 # ## Local First Party Imports ----
 from docstring_format_checker import __version__
-from docstring_format_checker.config import SectionConfig, find_config_file, load_config
+from docstring_format_checker.config import (
+    Config,
+    find_config_file,
+    load_config,
+)
 from docstring_format_checker.core import DocstringChecker, DocstringError
 
 
@@ -527,21 +531,21 @@ def check_docstrings(
             if not config_path.exists():
                 console.print(_red(f"Error: Configuration file does not exist: {config}"))
                 raise Exit(1)
-            sections_config = load_config(config_path)
+            config_obj = load_config(config_path)
         else:
             # Try to find config file automatically
             found_config: Optional[Path] = find_config_file(target_path if target_path.is_dir() else target_path.parent)
             if found_config:
-                sections_config: list[SectionConfig] = load_config(found_config)
+                config_obj: Config = load_config(found_config)
             else:
-                sections_config: list[SectionConfig] = load_config()
+                config_obj: Config = load_config()
 
     except Exception as e:
         console.print(_red(f"Error loading configuration: {e}"))
         raise Exit(1)
 
     # Initialize checker
-    checker = DocstringChecker(sections_config)
+    checker = DocstringChecker(config_obj)
 
     # Check files
     try:

{docstring_format_checker-0.7.0 → docstring_format_checker-0.9.0}/src/docstring_format_checker/config.py

@@ -70,7 +70,9 @@ else:
 
 
 __all__: list[str] = [
+    "GlobalConfig",
     "SectionConfig",
+    "Config",
     "DEFAULT_CONFIG",
     "load_config",
     "find_config_file",
@@ -92,13 +94,29 @@ VALID_TYPES: tuple[str, ...] = (
 
 # ---------------------------------------------------------------------------- #
 #                                                                              #
-#     Helpers                                                               ####
+#     Config                                                                ####
 #                                                                              #
 # ---------------------------------------------------------------------------- #
 
 
 ## --------------------------------------------------------------------------- #
-##  Classes                                                                 ####
+##  GlobalConfig                                                            ####
+## --------------------------------------------------------------------------- #
+
+
+@dataclass
+class GlobalConfig:
+    """
+    Global configuration for docstring checking behavior.
+    """
+
+    allow_undefined_sections: bool = False
+    require_docstrings: bool = True
+    check_private: bool = False
+
+
+## --------------------------------------------------------------------------- #
+##  SectionConfig                                                           ####
 ## --------------------------------------------------------------------------- #
 
 
@@ -176,12 +194,29 @@ def _validate_config_order(config_sections: list[SectionConfig]) -> None:
 
 # ---------------------------------------------------------------------------- #
 #                                                                              #
-#     Main Section                                                          ####
+#     Config Container                                                      ####
 #                                                                              #
 # ---------------------------------------------------------------------------- #
 
 
-DEFAULT_CONFIG: list[SectionConfig] = [
+@dataclass
+class Config:
+    """
+    Complete configuration containing global settings and section definitions.
+    """
+
+    global_config: GlobalConfig
+    sections: list[SectionConfig]
+
+
+# ---------------------------------------------------------------------------- #
+#                                                                              #
+#     Default Configuration                                                 ####
+#                                                                              #
+# ---------------------------------------------------------------------------- #
+
+
+DEFAULT_SECTIONS: list[SectionConfig] = [
     SectionConfig(
         order=1,
         name="summary",
@@ -241,7 +276,13 @@ DEFAULT_CONFIG: list[SectionConfig] = [
 ]
 
 
-def load_config(config_path: Optional[Union[str, Path]] = None) -> list[SectionConfig]:
+DEFAULT_CONFIG: Config = Config(
+    global_config=GlobalConfig(),
+    sections=DEFAULT_SECTIONS,
+)
+
+
+def load_config(config_path: Optional[Union[str, Path]] = None) -> Config:
     """
     !!! note "Summary"
         Load configuration from a TOML file or return default configuration.
@@ -253,8 +294,8 @@ def load_config(config_path: Optional[Union[str, Path]] = None) -> list[SectionC
             Default: `None`.
 
     Returns:
-        (list[SectionConfig]):
-            List of SectionConfig objects defining the docstring sections to check.
+        (Config):
+            Configuration object containing global settings and section definitions.
 
     Raises:
         (FileNotFoundError):
@@ -271,6 +312,7 @@ def load_config(config_path: Optional[Union[str, Path]] = None) -> list[SectionC
         else:
             return DEFAULT_CONFIG
 
+    # Convert to Path object and check existence
     config_path = Path(config_path)
     if not config_path.exists():
         raise FileNotFoundError(f"Configuration file not found: {config_path}")
@@ -292,6 +334,13 @@ def load_config(config_path: Optional[Union[str, Path]] = None) -> list[SectionC
     if tool_config is None:
         return DEFAULT_CONFIG
 
+    # Parse global configuration flags
+    global_config = 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),
+    )
+
     # Parse sections configuration
     sections_config: list[SectionConfig] = []
     if "sections" in tool_config:
@@ -315,16 +364,17 @@ def load_config(config_path: Optional[Union[str, Path]] = None) -> list[SectionC
             except (KeyError, TypeError, ValueError, InvalidTypeValuesError) as e:
                 raise InvalidConfigError(f"Invalid section configuration: {section_data}. Error: {e}") from e
 
+    # Use default sections if none provided, otherwise validate and sort
     if not sections_config:
-        return DEFAULT_CONFIG
-
-    # Validate no duplicate order values
-    _validate_config_order(config_sections=sections_config)
+        sections_config = DEFAULT_SECTIONS
+    else:
+        # Validate no duplicate order values
+        _validate_config_order(config_sections=sections_config)
 
-    # Sort by order
-    sections_config.sort(key=lambda x: x.order)
+        # Sort by order
+        sections_config.sort(key=lambda x: x.order)
 
-    return sections_config
+    return Config(global_config=global_config, sections=sections_config)
 
 
 def find_config_file(start_path: Optional[Path] = None) -> Optional[Path]:

{docstring_format_checker-0.7.0 → docstring_format_checker-0.9.0}/src/docstring_format_checker/core.py

@@ -50,7 +50,7 @@ from pathlib import Path
 from typing import Iterator, Literal, NamedTuple, Optional, Union
 
 # ## Local First Party Imports ----
-from docstring_format_checker.config import SectionConfig
+from docstring_format_checker.config import Config, SectionConfig
 from docstring_format_checker.utils.exceptions import (
     DirectoryNotFoundError,
     DocstringError,
@@ -95,18 +95,19 @@ class DocstringChecker:
     Main class for checking docstring format and completeness.
     """
 
-    def __init__(self, sections_config: list[SectionConfig]) -> None:
+    def __init__(self, config: Config) -> None:
         """
         !!! note "Summary"
             Initialize the docstring checker.
 
         Params:
-            sections_config (list[SectionConfig]):
-                List of section configurations to check against.
+            config (Config):
+                Configuration object containing global settings and section definitions.
         """
-        self.sections_config: list[SectionConfig] = sections_config
-        self.required_sections: list[SectionConfig] = [s for s in sections_config if s.required]
-        self.optional_sections: list[SectionConfig] = [s for s in sections_config if not s.required]
+        self.config = config
+        self.sections_config: list[SectionConfig] = config.sections
+        self.required_sections: list[SectionConfig] = [s for s in config.sections if s.required]
+        self.optional_sections: list[SectionConfig] = [s for s in config.sections if not s.required]
 
     def check_file(self, file_path: Union[str, Path]) -> list[DocstringError]:
         """
@@ -279,7 +280,9 @@ class DocstringChecker:
                 self.checker: DocstringChecker = checker
 
             def visit_ClassDef(self, node: ast.ClassDef) -> None:
-                if not node.name.startswith("_"):  # Skip private classes
+                # Skip private classes unless check_private is enabled
+                should_check: bool = self.checker.config.global_config.check_private or not node.name.startswith("_")
+                if should_check:
                     items.append(
                         FunctionAndClassDetails(
                             item_type="class",
@@ -304,9 +307,10 @@ class DocstringChecker:
             def _visit_function(self, node: Union[ast.FunctionDef, ast.AsyncFunctionDef]) -> None:
                 """Visit function definition node (sync or async)."""
 
-                if not node.name.startswith("_"):  # Skip private functions
+                # Skip private functions unless check_private is enabled
+                should_check: bool = self.checker.config.global_config.check_private or not node.name.startswith("_")
+                if should_check:
                     # Skip @overload functions - they don't need docstrings
-
                     if not self.checker._is_overload_function(node):
                         item_type: Literal["function", "method"] = "method" if self.class_stack else "function"
                         parent_class: Optional[str] = self.class_stack[-1] if self.class_stack else None
@@ -378,7 +382,8 @@ class DocstringChecker:
                         applicable_sections.append(section)
 
         if not docstring:
-            if requires_docstring:
+            # Only require docstrings if the global flag is enabled
+            if requires_docstring and self.config.global_config.require_docstrings:
                 message: str = f"Missing docstring for {item.item_type}"
                 raise DocstringError(
                     message=message,
@@ -387,7 +392,7 @@ class DocstringChecker:
                     item_name=item.name,
                     item_type=item.item_type,
                 )
-            return  # No docstring required
+            return  # No docstring required or docstring requirement disabled
 
         # Validate docstring sections if docstring exists
         self._validate_docstring_sections(docstring, item, file_path)
@@ -452,9 +457,10 @@ class DocstringChecker:
         if self._has_both_returns_and_yields(docstring):
             errors.append("Docstring cannot have both Returns and Yields sections")
 
-        # Check for undefined sections in docstring
-        undefined_errors: list[str] = self._check_undefined_sections(docstring)
-        errors.extend(undefined_errors)
+        # Check for undefined sections in docstring (only if not allowed)
+        if not self.config.global_config.allow_undefined_sections:
+            undefined_errors: list[str] = self._check_undefined_sections(docstring)
+            errors.extend(undefined_errors)
 
         # Check admonition values match configuration
         admonition_errors: list[str] = self._check_admonition_values(docstring)
@@ -1015,19 +1021,42 @@ class DocstringChecker:
                                 )
                     # For list_name_and_type sections, check format like "name (type):" or "(type):"
                     elif current_section.type == "list_name_and_type":
-                        # Pattern: name (type): or (type):
-                        # But skip if it doesn't look like a parameter definition (e.g., has multiple words before the colon)
-                        colon_part = stripped_line.split(":")[0].strip()
-                        # Skip if it contains phrases that indicate it's a description, not a parameter
-                        if any(
-                            word in colon_part.lower() for word in ["default", "output", "format", "show", "example"]
-                        ):
+                        # Check if this line has parentheses and looks like a parameter definition
+                        if re.search(r"\([^)]+\):", stripped_line):
+                            # This is a valid parameter definition line, remember its indentation
+                            type_line_indent = current_indent
                             continue
+                        else:
+                            # Check if this is likely a description line based on various criteria
+                            colon_part = stripped_line.split(":")[0].strip()
+
+                            # Skip if it contains phrases that indicate it's a description, not a parameter
+                            if any(
+                                word in colon_part.lower()
+                                for word in ["default", "output", "format", "show", "example"]
+                            ):
+                                continue
 
-                        if not re.search(r"\([^)]+\):", stripped_line):
-                            errors.append(
-                                f"Section '{current_section.name}' (type: '{current_section.type}') requires "
-                                f"parenthesized types, see: '{stripped_line}'"
-                            )
+                            # Skip if it starts with bullet points or list markers
+                            if stripped_line.strip().startswith(("-", "*", "•", "+")):
+                                continue
+
+                            # If we have found a parameter definition, check if this is a description line
+                            if type_line_indent is not None:
+                                # Skip if this is more indented than the parameter definition (description line)
+                                if current_indent > type_line_indent:
+                                    continue
+
+                            # Skip if the line before the colon contains multiple words (likely description)
+                            words_before_colon = colon_part.split()
+                            if len(words_before_colon) > 2:  # More than "param_name (type)"
+                                continue
+
+                            # Only flag lines that could reasonably be parameter definitions
+                            if ":" in stripped_line and not stripped_line.strip().startswith("#"):
+                                errors.append(
+                                    f"Section '{current_section.name}' (type: '{current_section.type}') requires "
+                                    f"parenthesized types, see: '{stripped_line}'"
+                                )
 
         return errors