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

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

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

@@ -1,6 +1,6 @@
 [project]
 name = "docstring-format-checker"
-version = "v0.9.0"
+version = "v0.11.0"
 description = "A CLI tool to check and validate Python docstring formatting and completeness"
 readme = "README.md"
 license = "MIT"
@@ -154,63 +154,19 @@ files = [
 ]
 
 [tool.dfc]
-# Default configuration for docstring format checker
-
-[[tool.dfc.sections]]
-order = 1
-name = "summary"
-type = "free_text"
-admonition = "note"
-prefix = "!!!"
-required = true
-
-[[tool.dfc.sections]]
-order = 2
-name = "details"
-type = "free_text"
-admonition = "info"
-prefix = "???+"
-required = false
-
-[[tool.dfc.sections]]
-order = 3
-name = "params"
-type = "list_name_and_type"
-required = true
-
-[[tool.dfc.sections]]
-order = 4
-name = "returns"
-type = "list_name_and_type"
-required = false
-
-[[tool.dfc.sections]]
-order = 5
-name = "yields"
-type = "list_type"
-required = false
-
-[[tool.dfc.sections]]
-order = 6
-name = "raises"
-type = "list_type"
-required = false
-
-[[tool.dfc.sections]]
-order = 7
-name = "examples"
-type = "free_text"
-admonition = "example"
-prefix = "???+"
-required = false
-
-[[tool.dfc.sections]]
-order = 8
-name = "notes"
-type = "free_text"
-admonition = "note"
-prefix = "???"
-required = false
+allow_undefined_sections = false
+require_docstrings = true
+check_private = true
+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 = "???+" },
+    { order = 3, name = "params",   type = "list_name_and_type", required = false },
+    { order = 4, name = "raises",   type = "list_type",          required = false },
+    { order = 5, name = "returns",  type = "list_name_and_type", required = false },
+    { order = 6, name = "yields",   type = "list_type",          required = false },
+    { order = 7, name = "examples", type = "free_text",          required = false, admonition = "example", prefix = "???+" },
+    { order = 8, name = "notes",    type = "free_text",          required = false, admonition = "note", prefix = "???" },
+]
 
 [build-system]
 requires = ["uv_build>=0.7.19,<0.8.0"]

{docstring_format_checker-0.9.0 → docstring_format_checker-0.11.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.9.0"
+__version__ = "v0.11.0"
 __author__ = "Chris Mahoney"
 __email__ = "docstring-format-checker@data-science-extensions.com"
 

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

@@ -72,6 +72,7 @@ from docstring_format_checker.core import DocstringChecker, DocstringError
 __all__: list[str] = [
     "main",
     "entry_point",
+    "check_docstrings",
 ]
 
 
@@ -90,6 +91,20 @@ NEW_LINE = "\n"
 
 ### Colours ----
 def _colour(text: str, colour: str) -> str:
+    """
+    !!! note "Summary"
+        Apply Rich colour markup to text.
+
+    Params:
+        text (str):
+            The text to colour.
+        colour (str):
+            The colour to apply, e.g., 'red', 'green', 'blue'.
+
+    Returns:
+        (str):
+            The text wrapped in Rich colour markup.
+    """
     return f"[{colour}]{text}[/{colour}]"
 
 

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

@@ -107,7 +107,8 @@ VALID_TYPES: tuple[str, ...] = (
 @dataclass
 class GlobalConfig:
     """
-    Global configuration for docstring checking behavior.
+    !!! note "Summary"
+        Global configuration for docstring checking behavior.
     """
 
     allow_undefined_sections: bool = False
@@ -123,7 +124,8 @@ class GlobalConfig:
 @dataclass
 class SectionConfig:
     """
-    Configuration for a docstring section.
+    !!! note "Summary"
+        Configuration for a docstring section.
     """
 
     order: int
@@ -135,17 +137,26 @@ class SectionConfig:
     message: str = ""  # Optional message for validation errors
 
     def __post_init__(self) -> None:
-        """Validate configuration after initialization."""
+        """
+        !!! note "Summary"
+            Validate configuration after initialization.
+        """
         self._validate_types()
         self._validate_admonition_prefix_combination()
 
     def _validate_types(self) -> None:
-        """Validate the 'type' field."""
+        """
+        !!! note "Summary"
+            Validate the 'type' field.
+        """
         if self.type not in VALID_TYPES:
             raise InvalidTypeValuesError(f"Invalid section type: {self.type}. Valid types: {VALID_TYPES}")
 
     def _validate_admonition_prefix_combination(self) -> None:
-        """Validate admonition and prefix combination rules."""
+        """
+        !!! note "Summary"
+            Validate admonition and prefix combination rules.
+        """
 
         if isinstance(self.admonition, bool):
             # Rule: admonition cannot be True (only False or string)
@@ -173,6 +184,22 @@ class SectionConfig:
 
 
 def _validate_config_order(config_sections: list[SectionConfig]) -> None:
+    """
+    !!! note "Summary"
+        Validate that section order values are unique.
+
+    Params:
+        config_sections (list[SectionConfig]):
+            List of section configurations to validate.
+
+    Raises:
+        (InvalidConfigError_DuplicateOrderValues):
+            If duplicate order values are found.
+
+    Returns:
+        (None):
+            Nothing is returned.
+    """
 
     # Validate no duplicate order values
     order_values: list[int] = [section.order for section in config_sections]
@@ -202,7 +229,8 @@ def _validate_config_order(config_sections: list[SectionConfig]) -> None:
 @dataclass
 class Config:
     """
-    Complete configuration containing global settings and section definitions.
+    !!! note "Summary"
+        Complete configuration containing global settings and section definitions.
     """
 
     global_config: GlobalConfig
@@ -293,15 +321,15 @@ def load_config(config_path: Optional[Union[str, Path]] = None) -> Config:
             If `None`, looks for `pyproject.toml` in current directory.
             Default: `None`.
 
-    Returns:
-        (Config):
-            Configuration object containing global settings and section definitions.
-
     Raises:
         (FileNotFoundError):
             If the specified config file doesn't exist.
         (InvalidConfigError):
             If the configuration is invalid.
+
+    Returns:
+        (Config):
+            Configuration object containing global settings and section definitions.
     """
 
     if config_path is None:

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

@@ -80,7 +80,8 @@ __all__: list[str] = [
 
 class FunctionAndClassDetails(NamedTuple):
     """
-    Details about a function or class found in the AST.
+    !!! note "Summary"
+        Details about a function or class found in the AST.
     """
 
     item_type: Literal["function", "class", "method"]
@@ -92,7 +93,8 @@ class FunctionAndClassDetails(NamedTuple):
 
 class DocstringChecker:
     """
-    Main class for checking docstring format and completeness.
+    !!! note "Summary"
+        Main class for checking docstring format and completeness.
     """
 
     def __init__(self, config: Config) -> None:
@@ -118,10 +120,6 @@ class DocstringChecker:
             file_path (Union[str, Path]):
                 Path to the Python file to check.
 
-        Returns:
-            (list[DocstringError]):
-                List of DocstringError objects for any validation failures.
-
         Raises:
             (FileNotFoundError):
                 If the file doesn't exist.
@@ -131,6 +129,10 @@ class DocstringChecker:
                 If the file can't be decoded.
             (SyntaxError):
                 If the file contains invalid Python syntax.
+
+        Returns:
+            (list[DocstringError]):
+                List of DocstringError objects for any validation failures.
         """
 
         file_path = Path(file_path)
@@ -274,12 +276,24 @@ class DocstringChecker:
         items: list[FunctionAndClassDetails] = []
 
         class ItemVisitor(ast.NodeVisitor):
+            """
+            !!! note "Summary"
+                AST visitor to extract function and class definitions
+            """
 
             def __init__(self, checker: DocstringChecker) -> None:
+                """
+                !!! note "Summary"
+                    Initialize the AST visitor.
+                """
                 self.class_stack: list[str] = []
                 self.checker: DocstringChecker = checker
 
             def visit_ClassDef(self, node: ast.ClassDef) -> None:
+                """
+                !!! note "Summary"
+                    Visit class definition node.
+                """
                 # 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:
@@ -299,13 +313,24 @@ class DocstringChecker:
                 self.class_stack.pop()
 
             def visit_FunctionDef(self, node: ast.FunctionDef) -> None:
+                """
+                !!! note "Summary"
+                    Visit function definition node.
+                """
                 self._visit_function(node)
 
             def visit_AsyncFunctionDef(self, node: ast.AsyncFunctionDef) -> None:
+                """
+                !!! note "Summary"
+                    Visit async function definition node.
+                """
                 self._visit_function(node)
 
             def _visit_function(self, node: Union[ast.FunctionDef, ast.AsyncFunctionDef]) -> None:
-                """Visit function definition node (sync or async)."""
+                """
+                !!! note "Summary"
+                    Visit function definition node (sync or async).
+                """
 
                 # Skip private functions unless check_private is enabled
                 should_check: bool = self.checker.config.global_config.check_private or not node.name.startswith("_")
@@ -835,7 +860,8 @@ class DocstringChecker:
 
     def _check_colon_usage(self, docstring: str) -> list[str]:
         """
-        Check that colons are used correctly for admonition vs non-admonition sections.
+        !!! note "Summary"
+            Check that colons are used correctly for admonition vs non-admonition sections.
         """
 
         errors: list[str] = []
@@ -882,7 +908,8 @@ class DocstringChecker:
 
     def _check_title_case_sections(self, docstring: str) -> list[str]:
         """
-        Check that non-admonition sections are single word, title case, and match config name.
+        !!! note "Summary"
+            Check that non-admonition sections are single word, title case, and match config name.
         """
 
         errors: list[str] = []
@@ -914,7 +941,8 @@ class DocstringChecker:
 
     def _check_parentheses_validation(self, docstring: str) -> list[str]:
         """
-        Check that list_type and list_name_and_type sections have proper parentheses.
+        !!! note "Summary"
+            Check that list_type and list_name_and_type sections have proper parentheses.
         """
 
         errors: list[str] = []

{docstring_format_checker-0.9.0 → docstring_format_checker-0.11.0}/src/docstring_format_checker/utils/exceptions.py

@@ -1,6 +1,7 @@
 class DocstringError(Exception):
     """
-    Exception raised when a docstring validation error occurs.
+    !!! note "Summary"
+        Exception raised when a docstring validation error occurs.
     """
 
     def __init__(
@@ -11,6 +12,10 @@ class DocstringError(Exception):
         item_name: str,
         item_type: str,
     ) -> None:
+        """
+        !!! note "Summary"
+            Initialize a DocstringError.
+        """
         self.message = message
         self.file_path = file_path
         self.line_number = line_number
@@ -20,20 +25,45 @@ class DocstringError(Exception):
 
 
 class InvalidConfigError(Exception):
+    """
+    !!! note "Summary"
+        Exception raised for invalid configuration errors.
+    """
+
     pass
 
 
 class InvalidConfigError_DuplicateOrderValues(Exception):
+    """
+    !!! note "Summary"
+        Exception raised for duplicate order values in configuration.
+    """
+
     pass
 
 
 class InvalidTypeValuesError(Exception):
+    """
+    !!! note "Summary"
+        Exception raised for invalid type values in configuration.
+    """
+
     pass
 
 
 class InvalidFileError(OSError):
+    """
+    !!! note "Summary"
+        Exception raised for invalid file errors.
+    """
+
     pass
 
 
 class DirectoryNotFoundError(OSError):
+    """
+    !!! note "Summary"
+        Exception raised for directory not found errors.
+    """
+
     pass