google-docstring-parser 0.0.6__tar.gz → 0.0.8__tar.gz

{google_docstring_parser-0.0.6 → google_docstring_parser-0.0.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: google-docstring-parser
-Version: 0.0.6
+Version: 0.0.8
 Summary: A lightweight, efficient parser for Google-style Python docstrings that converts them into structured dictionaries.
 Author: Vladimir Iglovikov
 Maintainer: Vladimir Iglovikov

{google_docstring_parser-0.0.6 → google_docstring_parser-0.0.8}/google_docstring_parser/google_docstring_parser.py

@@ -19,10 +19,13 @@ This module provides functions to parse Google-style docstrings into structured
 from __future__ import annotations
 
 import re
-from typing import Any
+from typing import TYPE_CHECKING, Any
 
 from docstring_parser import parse
 
+if TYPE_CHECKING:
+    from docstring_parser.common import Docstring
+
 from google_docstring_parser.type_validation import (
     InvalidTypeAnnotationError,
     check_text_for_bare_collections,
@@ -369,60 +372,84 @@ def _parse_references(reference_content: str) -> list[dict[str, str]]:
     return references
 
 
-def _is_continuation_line(line: str, all_lines: list[str]) -> bool:
-    """Check if a line is a continuation of a previous line.
+def _validate_type_with_error_handling(type_str: str, result: dict[str, Any], collect_errors: bool) -> None:
+    """Validate a type annotation and handle any errors.
+
+    This function validates type annotations and handles errors differently based on the collect_errors flag:
+    - When collect_errors is True: Errors are added to result["errors"] list instead of being raised
+    - When collect_errors is False: Errors are raised immediately as InvalidTypeAnnotationError
 
     Args:
-        line (str): The line to check
-        all_lines (list[str]): All lines in the section
+        type_str (str): The type annotation to validate
+        result (dict[str, Any]): The result dictionary to add errors to when collect_errors is True
+        collect_errors (bool): Whether to collect errors in result["errors"] (True) or raise them (False)
 
     Returns:
-        bool: True if the line is a continuation line, False otherwise
-    """
-    line_index = all_lines.index(line)
-    if line_index == 0:
-        return False
-
-    current_indent = len(line) - len(line.lstrip())
-    prev_line = all_lines[line_index - 1]
-    prev_indent = len(prev_line) - len(prev_line.lstrip())
+        None
 
-    return current_indent > prev_indent and not line.lstrip().startswith("-")
+    Raises:
+        InvalidTypeAnnotationError: If type validation fails and collect_errors is False
+    """
+    try:
+        validate_type_annotation(type_str)
+        if "[" in type_str and "]" in type_str:
+            check_text_for_bare_collections(type_str)
+    except InvalidTypeAnnotationError as e:
+        if collect_errors:
+            result["errors"].append(str(e))
+        else:
+            raise
 
 
-def _process_args_section(args: list[dict[str, str | None]], *, validate_types: bool) -> None:
-    """Process the Args section of a docstring.
+def _process_args_with_validation(
+    sections: dict[str, str],
+    parsed: Docstring,
+    result: dict[str, Any],
+    validate_types: bool,
+    collect_errors: bool,
+) -> None:
+    """Process the Args section with type validation.
 
     Args:
-        args (list[dict[str, str | None]]): List of argument dictionaries
+        sections (dict[str, str]): The sections dictionary
+        parsed (Docstring): The parsed docstring object
+        result (dict[str, Any]): The result dictionary to update
         validate_types (bool): Whether to validate type annotations
-
-    Returns:
-        None
+        collect_errors (bool): Whether to collect errors or raise them
     """
-    if not validate_types:
+    if "Args" not in sections:
+        return
+
+    args = [
+        {
+            "name": arg.arg_name.rstrip() if arg.arg_name is not None else None,
+            "type": arg.type_name.rstrip() if arg.type_name is not None else None,
+            "description": arg.description.rstrip() if arg.description is not None else None,
+        }
+        for arg in parsed.params
+    ]
+
+    if not args:
         return
 
-    # Validate type annotations and check for bare nested collections
     for arg in args:
         if arg["type"] and validate_types:
-            validate_type_annotation(arg["type"])
-
-            # Check for nested types - if this is a complex type like Dict[str, List],
-            # the bare 'List' would be caught here
-            if "[" in arg["type"] and "]" in arg["type"]:
-                check_text_for_bare_collections(arg["type"])
+            _validate_type_with_error_handling(arg["type"], result, collect_errors)
+    result["Args"] = args
 
 
-def _process_returns_section(sections: dict[str, str], *, validate_types: bool) -> dict[str, str]:
+def _parse_returns_section(sections: dict[str, str], *, validate_types: bool) -> dict[str, str] | str:
     """Process the Returns section of a docstring.
 
     Args:
-        sections (dict[str, str]): Dictionary of docstring sections
+        sections (dict[str, str]): The sections dictionary
         validate_types (bool): Whether to validate type annotations
 
     Returns:
-        dict[str, str]: Dictionary containing 'type' and 'description' keys for the return value
+        dict[str, str] | str: Either:
+            - A dictionary with 'type' and 'description' keys
+            - The string 'None' if the section only contains 'None'
+            - An empty dict if no return information is found
     """
     if (
         "Returns" not in sections
@@ -434,28 +461,78 @@ def _process_returns_section(sections: dict[str, str], *, validate_types: bool)
     return_type = return_match[1]
     return_desc = return_match[2].strip()
 
-    # If type exists -> description must exist
-    # If type is None -> description must be empty
-    if (return_type and not return_desc) or (not return_type and return_desc):
-        return {}
+    # Special case: Returns section just contains "None"
+    if not return_type and return_desc == "None":
+        return "None"
 
+    # Validate type if present
     if return_type and validate_types:
-        # Validate the return type
         validate_type_annotation(return_type)
 
-        # Check for nested types in return type
+        # Check for nested types
         if "[" in return_type and "]" in return_type:
             check_text_for_bare_collections(return_type)
 
     return {"type": return_type, "description": return_desc.rstrip()}
 
 
-def parse_google_docstring(docstring: str, *, validate_types: bool = True) -> dict[str, Any]:
+def _process_returns_with_validation(
+    sections: dict[str, str],
+    result: dict[str, Any],
+    validate_types: bool,
+    collect_errors: bool,
+) -> None:
+    """Process the Returns section with type validation.
+
+    Args:
+        sections (dict[str, str]): The sections dictionary
+        result (dict[str, Any]): The result dictionary to update
+        validate_types (bool): Whether to validate type annotations
+        collect_errors (bool): Whether to collect errors or raise them
+    """
+    if "Returns" not in sections:
+        return
+
+    try:
+        returns = _parse_returns_section(sections, validate_types=validate_types)
+        if isinstance(returns, dict) and returns.get("type") and validate_types:
+            _validate_type_with_error_handling(returns["type"], result, collect_errors)
+        result["Returns"] = returns
+    except InvalidTypeAnnotationError as e:
+        if collect_errors:
+            result["errors"].append(str(e))
+        else:
+            raise
+
+
+def _process_references_section(sections: dict[str, str], result: dict[str, Any]) -> None:
+    """Process the References section.
+
+    Args:
+        sections (dict[str, str]): The sections dictionary
+        result (dict[str, Any]): The result dictionary to update
+    """
+    for ref_section in ["References", "Reference"]:
+        if ref_section in sections:
+            # Reference errors should always be raised
+            result[ref_section] = _parse_references(sections[ref_section])
+            # Don't add this section to the general sections mapping later
+            sections.pop(ref_section, None)
+            break
+
+
+def parse_google_docstring(
+    docstring: str,
+    *,
+    validate_types: bool = True,
+    collect_errors: bool = True,
+) -> dict[str, Any]:
     """Parse a Google-style docstring.
 
     Args:
         docstring (str): The docstring to parse
         validate_types (bool): Whether to validate type annotations
+        collect_errors (bool): Whether to collect errors in the result dictionary instead of raising them
 
     Returns:
         dict[str, Any]: Dictionary containing the parsed docstring information with the following keys:
@@ -463,17 +540,27 @@ def parse_google_docstring(docstring: str, *, validate_types: bool = True) -> di
             - Args (list[dict[str, str | None]], optional): List of argument dictionaries
             - Returns (dict[str, str], optional): Return type and description
             - References/Reference (list[dict[str, str]], optional): List of references
+            - errors (list[str], optional): List of validation errors if any (only if collect_errors is True)
             - Other sections are included as is
+
+    Raises:
+        InvalidTypeAnnotationError: If type validation is enabled and an invalid type is found
+            (only if collect_errors is False)
+        ReferenceFormatError: If a reference format is invalid
     """
     if not docstring:
         return {}
 
+    # Initialize result dictionary with description and errors if needed
+    result: dict[str, Any] = {
+        "Description": "",
+    }
+    if collect_errors:
+        result["errors"] = []
+
     # Clean up the docstring
     docstring = docstring.strip()
 
-    # Initialize result dictionary with only description
-    result: dict[str, Any] = {"Description": ""}
-
     # Extract sections and parse docstring
     sections = _extract_sections(docstring)
     parsed = parse(docstring)
@@ -482,35 +569,26 @@ def parse_google_docstring(docstring: str, *, validate_types: bool = True) -> di
     if parsed.description:
         result["Description"] = parsed.description.rstrip()
 
-    # Process args (only if present)
-    if "Args" in sections and (
-        args := [
-            {
-                "name": arg.arg_name.rstrip() if arg.arg_name is not None else None,
-                "type": arg.type_name.rstrip() if arg.type_name is not None else None,
-                "description": arg.description.rstrip() if arg.description is not None else None,
-            }
-            for arg in parsed.params
-        ]
-    ):
-        _process_args_section(args, validate_types=validate_types)
-        result["Args"] = args
+    # Process args with validation
+    _process_args_with_validation(sections, parsed, result, validate_types, collect_errors)
 
-    # Process returns only if present
-    if "Returns" in sections:
-        result["Returns"] = _process_returns_section(sections, validate_types=validate_types)
+    # Process returns with validation
+    _process_returns_with_validation(sections, result, validate_types, collect_errors)
 
     # Process references section
-    for ref_section in ["References", "Reference"]:
-        if ref_section in sections:
-            result[ref_section] = _parse_references(sections[ref_section])
-            # Don't add this section to the general sections mapping later
-            sections.pop(ref_section, None)
-            break
+    _process_references_section(sections, result)
 
     # Add other sections directly using dict union
-    return result | {
-        section: content.rstrip()
-        for section, content in sections.items()
-        if section not in ["Description", "Args", "Returns"]
-    }
+    result.update(
+        {
+            section: content.rstrip()
+            for section, content in sections.items()
+            if section not in ["Description", "Args", "Returns"]
+        },
+    )
+
+    # Remove errors key if no errors
+    if collect_errors and not result["errors"]:
+        del result["errors"]
+
+    return result

{google_docstring_parser-0.0.6 → google_docstring_parser-0.0.8}/google_docstring_parser/type_validation.py

@@ -177,7 +177,7 @@ def validate_type_annotation(type_annotation: str) -> None:
 
     # Check for bare collection types without arguments - exact match only
     if is_bare_collection(type_annotation):
-        error_msg = f"Collection type '{type_annotation}' must include element types (e.g., {type_annotation}[str])"
+        error_msg = f"Collection '{type_annotation}' must include element types (e.g., {type_annotation}[str])"
         raise InvalidTypeAnnotationError(error_msg)
 
     # Check for nested types in complex type annotations
@@ -466,6 +466,26 @@ def _check_for_bare_collection(tokens: list[str], i: int, token: str) -> None:
         raise InvalidTypeAnnotationError(error_msg)
 
 
+def _is_bare_collection_in_nested_type(token: str, tokens: list[str], i: int, bracket_stack: list[str]) -> bool:
+    """Check if a collection type is used without type arguments in a nested type.
+
+    Args:
+        token (str): The current token
+        tokens (list[str]): The list of all tokens
+        i (int): The current token index
+        bracket_stack (list[str]): The stack of open brackets
+
+    Returns:
+        bool: True if the collection is used without type arguments in a nested type
+    """
+    is_collection: bool = token in COLLECTIONS_REQUIRING_ARGS
+    has_brackets: bool = bool(bracket_stack)
+    has_next_token: bool = i < len(tokens) - 1
+    next_token_not_bracket: bool = tokens[i + 1] != OPEN_BRACKET if has_next_token else False
+
+    return is_collection and has_brackets and has_next_token and next_token_not_bracket
+
+
 def _check_tokens_for_collection_type_usage(tokens: list[str]) -> None:
     """Check tokens for proper collection type usage.
 
@@ -492,6 +512,11 @@ def _check_tokens_for_collection_type_usage(tokens: list[str]) -> None:
         elif token in (CLOSE_BRACKET, CLOSE_PAREN, CLOSE_BRACE):
             _check_for_closing_bracket(token, bracket_stack, collection_stack)
 
+        # Check for bare collections in nested types
+        elif _is_bare_collection_in_nested_type(token, tokens, i, bracket_stack):
+            error_msg = f"Invalid nested type: collection type '{token}' requires element types"
+            raise InvalidTypeAnnotationError(error_msg)
+
     # Check for unclosed brackets at the end
     if bracket_stack:
         raise BracketValidationError(BracketValidationError.UNCLOSED_BRACKETS)

{google_docstring_parser-0.0.6 → google_docstring_parser-0.0.8}/google_docstring_parser.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: google-docstring-parser
-Version: 0.0.6
+Version: 0.0.8
 Summary: A lightweight, efficient parser for Google-style Python docstrings that converts them into structured dictionaries.
 Author: Vladimir Iglovikov
 Maintainer: Vladimir Iglovikov

{google_docstring_parser-0.0.6 → google_docstring_parser-0.0.8}/pyproject.toml

@@ -5,7 +5,7 @@ requires = [ "setuptools>=45", "wheel" ]
 
 [project]
 name = "google-docstring-parser"
-version = "0.0.6"
+version = "0.0.8"
 
 description = "A lightweight, efficient parser for Google-style Python docstrings that converts them into structured dictionaries."
 readme = "README.md"
@@ -107,6 +107,7 @@ lint.ignore = [
   "D107",
   "EM101",
   "EM102",
+  "FBT001",
 ]
 
 # Allow fix for all enabled rules (when `--fix`) is provided.
@@ -117,7 +118,6 @@ lint.per-file-ignores = { "__init__.py" = [
 ], "tools/*.py" = [
   "T201",
   "BLE001",
-  "FBT001",
   "FBT002",
   "ANN201",
 ] }

{google_docstring_parser-0.0.6 → google_docstring_parser-0.0.8}/tools/check_docstrings.py

@@ -22,7 +22,7 @@ from google_docstring_parser.google_docstring_parser import (
 
 # Default configuration
 DEFAULT_CONFIG = {
-    "paths": ["."],
+    "paths": [],  # Empty by default, so no directories are scanned unless explicitly specified
     "require_param_types": False,
     "check_references": True,
     "exclude_files": [],
@@ -268,23 +268,20 @@ def check_returns_section_name(docstring: str) -> list[str]:
 
 
 def check_returns_type(docstring_dict: dict[str, Any]) -> list[str]:
-    """Check Returns type in a docstring.
-
-    Args:
-        docstring_dict (dict[str, Any]): Parsed docstring dictionary
-
-    Returns:
-        list[str]: List of error messages for invalid return types
-    """
+    """Check Returns type in a docstring."""
     errors = []
-    if docstring_dict.get("Returns"):
-        returns = docstring_dict["Returns"]
+    if returns := docstring_dict.get("Returns"):
         # Special case: Returns section just contains "None"
         if isinstance(returns, str) and returns.strip() == "None":
             return errors
 
-        if isinstance(returns, dict) and not returns.get("type"):
+        if not isinstance(returns, dict):
+            errors.append("Returns section must be either 'None' or have a type annotation")
+            return errors
+
+        if not returns.get("type"):
             errors.append("Returns section is missing type annotation")
+
     return errors
 
 
@@ -706,6 +703,14 @@ def main() -> None:
         print(f"  Check references: {check_references}")
         print(f"  Exclude files: {exclude_files}")
 
+    # Check if paths is empty
+    if not paths:
+        print(
+            "No paths specified for checking. Please specify paths as command line "
+            "arguments or configure them in pyproject.toml under [tool.docstring_checker] section.",
+        )
+        sys.exit(0)
+
     if all_errors := _process_paths(
         paths,
         exclude_files,