google-docstring-parser 0.0.11__tar.gz → 0.0.12__tar.gz

google_docstring_parser-0.0.12/.gitignore

@@ -0,0 +1,176 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+uv.lock

google_docstring_parser-0.0.12/.pre-commit-hooks.yaml

@@ -0,0 +1,14 @@
+- id: check-google-docstrings
+  name: Check Google-style docstrings can be parsed
+  description: >
+    Checks that Google-style docstrings in specified folders can be parsed with google_docstring_parser.
+    IMPORTANT: You MUST configure paths in pyproject.toml under [tool.docstring_checker] section,
+    otherwise no files will be checked. For example:
+    [tool.docstring_checker]
+    paths = ["your_package", "your_module"]
+  entry: python -m tools.check_docstrings
+  language: python
+  types: [python]
+  pass_filenames: false
+  require_serial: true
+  args: []  # Default empty args

{google_docstring_parser-0.0.11 → google_docstring_parser-0.0.12}/PKG-INFO

@@ -1,36 +1,34 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: google-docstring-parser
-Version: 0.0.11
+Version: 0.0.12
 Summary: A lightweight, efficient parser for Google-style Python docstrings that converts them into structured dictionaries.
 Author: Vladimir Iglovikov
 Maintainer: Vladimir Iglovikov
-License: Custom License - See LICENSE file for details
+License-Expression: LicenseRef-Proprietary
+License-File: LICENSE
 Keywords: docstring,documentation,google-style,parser,python,static-analysis,type-hints
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Developers
 Classifier: Intended Audience :: Science/Research
-Classifier: License :: Other/Proprietary License
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: 3 :: Only
-Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
 Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
 Classifier: Topic :: Software Development :: Documentation
 Classifier: Topic :: Software Development :: Libraries
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Typing :: Typed
-Requires-Python: >=3.10
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: docstring-parser>=0.16
+Requires-Python: >=3.11
+Requires-Dist: docstring-parser>=0.18
 Provides-Extra: dev
-Requires-Dist: pre-commit>=3.5; extra == "dev"
-Requires-Dist: pytest>=8.3.3; extra == "dev"
-Dynamic: license-file
+Requires-Dist: pre-commit>=4.7; extra == 'dev'
+Requires-Dist: pytest>=9.2; extra == 'dev'
+Description-Content-Type: text/markdown
 
 # Google Docstring Parser
 
@@ -40,6 +38,8 @@ Dynamic: license-file
 
 A Python package for parsing Google-style docstrings into structured dictionaries.
 
+Requires Python 3.11 or newer.
+
 ## License Information
 
 This package is available under a custom license:
@@ -59,7 +59,7 @@ pip install google-docstring-parser
 ```python
 from google_docstring_parser import parse_google_docstring
 
-docstring = '''Apply elastic deformation to images, masks, bounding boxes, and keypoints.
+docstring = """Apply elastic deformation to images, masks, bounding boxes, and keypoints.
 
 This transformation introduces random elastic distortions to the input data. It's particularly
 useful for data augmentation in training deep learning models, especially for tasks like
@@ -81,7 +81,7 @@ References:
     - Implementation details: https://example.com/elastic-transform
 Returns:
     dict[str, Any]: Some info here
-'''
+"""
 
 parsed = parse_google_docstring(docstring)
 print(parsed)
@@ -90,35 +90,28 @@ print(parsed)
 Output:
 ```python
 {
-    'Description': 'Apply elastic deformation to images, masks, bounding boxes, and keypoints.\n\nThis transformation introduces random elastic distortions to the input data. It\'s particularly\nuseful for data augmentation in training deep learning models, especially for tasks like\nimage segmentation or object detection where you want to maintain the relative positions of\nfeatures while introducing realistic deformations.',
-    'Args': [
+    "Description": "Apply elastic deformation to images, masks, bounding boxes, and keypoints.\n\nThis transformation introduces random elastic distortions to the input data. It's particularly\nuseful for data augmentation in training deep learning models, especially for tasks like\nimage segmentation or object detection where you want to maintain the relative positions of\nfeatures while introducing realistic deformations.",
+    "Args": [
         {
-            'name': 'alpha',
-            'type': 'float',
-            'description': 'Scaling factor for the random displacement fields. Higher values result in\nmore pronounced distortions. Default: 1.0'
+            "name": "alpha",
+            "type": "float",
+            "description": "Scaling factor for the random displacement fields. Higher values result in\nmore pronounced distortions. Default: 1.0",
         },
         {
-            'name': 'sigma',
-            'type': 'float',
-            'description': 'Standard deviation of the Gaussian filter used to smooth the displacement\nfields. Higher values result in smoother, more global distortions. Default: 50.0'
-        }
+            "name": "sigma",
+            "type": "float",
+            "description": "Standard deviation of the Gaussian filter used to smooth the displacement\nfields. Higher values result in smoother, more global distortions. Default: 50.0",
+        },
     ],
-    'Example': '>>> import albumentations as A\n>>> transform = A.ElasticTransform(alpha=1, sigma=50, p=0.5)',
-    'References': [
+    "Example": ">>> import albumentations as A\n>>> transform = A.ElasticTransform(alpha=1, sigma=50, p=0.5)",
+    "References": [
         {
-            'description': 'Original paper',
-            'source': 'Simard, P. Y., et al. "Best practices for convolutional neural networks applied to visual document analysis." ICDAR 2003'
+            "description": "Original paper",
+            "source": 'Simard, P. Y., et al. "Best practices for convolutional neural networks applied to visual document analysis." ICDAR 2003',
         },
-        {
-            'description': 'Implementation details',
-            'source': 'https://example.com/elastic-transform'
-        }
+        {"description": "Implementation details", "source": "https://example.com/elastic-transform"},
     ],
-    'Returns':
-        {
-            "type": "dict[str, Any]",
-            "description": "Some info here"
-        }
+    "Returns": {"type": "dict[str, Any]", "description": "Some info here"},
 }
 ```
 
@@ -130,6 +123,20 @@ Output:
 - Handles multi-line descriptions and indentation properly
 - Properly parses and validates References sections with special handling for URLs
 
+### Wrapped return annotations
+
+Long return types can span several lines. The parser accepts wrapped unions, generics, and parenthesized types:
+
+```text
+Returns:
+    dict[
+        str,
+        list[int | str],
+    ]: Results grouped by name.
+```
+
+The parsed type is `dict[str, list[int | str]]`. Quoted colons and brackets inside `Literal` values are preserved, and wrapped prose remains untyped. The checker compares type expressions while preserving spaces inside literal values.
+
 ### References
 
 The parser can handle reference sections in Google-style docstrings. References can be formatted in two ways:
@@ -170,7 +177,6 @@ To use this hook in another project, add the following to your `.pre-commit-conf
   rev: v0.0.1  # Use the latest version
   hooks:
     - id: check-google-docstrings
-      additional_dependencies: ["tomli>=2.0.0"]  # Required for pyproject.toml configuration
 ```
 
 ### Configuration

{google_docstring_parser-0.0.11 → google_docstring_parser-0.0.12}/README.md

@@ -6,6 +6,8 @@
 
 A Python package for parsing Google-style docstrings into structured dictionaries.
 
+Requires Python 3.11 or newer.
+
 ## License Information
 
 This package is available under a custom license:
@@ -25,7 +27,7 @@ pip install google-docstring-parser
 ```python
 from google_docstring_parser import parse_google_docstring
 
-docstring = '''Apply elastic deformation to images, masks, bounding boxes, and keypoints.
+docstring = """Apply elastic deformation to images, masks, bounding boxes, and keypoints.
 
 This transformation introduces random elastic distortions to the input data. It's particularly
 useful for data augmentation in training deep learning models, especially for tasks like
@@ -47,7 +49,7 @@ References:
     - Implementation details: https://example.com/elastic-transform
 Returns:
     dict[str, Any]: Some info here
-'''
+"""
 
 parsed = parse_google_docstring(docstring)
 print(parsed)
@@ -56,35 +58,28 @@ print(parsed)
 Output:
 ```python
 {
-    'Description': 'Apply elastic deformation to images, masks, bounding boxes, and keypoints.\n\nThis transformation introduces random elastic distortions to the input data. It\'s particularly\nuseful for data augmentation in training deep learning models, especially for tasks like\nimage segmentation or object detection where you want to maintain the relative positions of\nfeatures while introducing realistic deformations.',
-    'Args': [
+    "Description": "Apply elastic deformation to images, masks, bounding boxes, and keypoints.\n\nThis transformation introduces random elastic distortions to the input data. It's particularly\nuseful for data augmentation in training deep learning models, especially for tasks like\nimage segmentation or object detection where you want to maintain the relative positions of\nfeatures while introducing realistic deformations.",
+    "Args": [
         {
-            'name': 'alpha',
-            'type': 'float',
-            'description': 'Scaling factor for the random displacement fields. Higher values result in\nmore pronounced distortions. Default: 1.0'
+            "name": "alpha",
+            "type": "float",
+            "description": "Scaling factor for the random displacement fields. Higher values result in\nmore pronounced distortions. Default: 1.0",
         },
         {
-            'name': 'sigma',
-            'type': 'float',
-            'description': 'Standard deviation of the Gaussian filter used to smooth the displacement\nfields. Higher values result in smoother, more global distortions. Default: 50.0'
-        }
+            "name": "sigma",
+            "type": "float",
+            "description": "Standard deviation of the Gaussian filter used to smooth the displacement\nfields. Higher values result in smoother, more global distortions. Default: 50.0",
+        },
     ],
-    'Example': '>>> import albumentations as A\n>>> transform = A.ElasticTransform(alpha=1, sigma=50, p=0.5)',
-    'References': [
+    "Example": ">>> import albumentations as A\n>>> transform = A.ElasticTransform(alpha=1, sigma=50, p=0.5)",
+    "References": [
         {
-            'description': 'Original paper',
-            'source': 'Simard, P. Y., et al. "Best practices for convolutional neural networks applied to visual document analysis." ICDAR 2003'
+            "description": "Original paper",
+            "source": 'Simard, P. Y., et al. "Best practices for convolutional neural networks applied to visual document analysis." ICDAR 2003',
         },
-        {
-            'description': 'Implementation details',
-            'source': 'https://example.com/elastic-transform'
-        }
+        {"description": "Implementation details", "source": "https://example.com/elastic-transform"},
     ],
-    'Returns':
-        {
-            "type": "dict[str, Any]",
-            "description": "Some info here"
-        }
+    "Returns": {"type": "dict[str, Any]", "description": "Some info here"},
 }
 ```
 
@@ -96,6 +91,20 @@ Output:
 - Handles multi-line descriptions and indentation properly
 - Properly parses and validates References sections with special handling for URLs
 
+### Wrapped return annotations
+
+Long return types can span several lines. The parser accepts wrapped unions, generics, and parenthesized types:
+
+```text
+Returns:
+    dict[
+        str,
+        list[int | str],
+    ]: Results grouped by name.
+```
+
+The parsed type is `dict[str, list[int | str]]`. Quoted colons and brackets inside `Literal` values are preserved, and wrapped prose remains untyped. The checker compares type expressions while preserving spaces inside literal values.
+
 ### References
 
 The parser can handle reference sections in Google-style docstrings. References can be formatted in two ways:
@@ -136,7 +145,6 @@ To use this hook in another project, add the following to your `.pre-commit-conf
   rev: v0.0.1  # Use the latest version
   hooks:
     - id: check-google-docstrings
-      additional_dependencies: ["tomli>=2.0.0"]  # Required for pyproject.toml configuration
 ```
 
 ### Configuration

{google_docstring_parser-0.0.11 → google_docstring_parser-0.0.12}/google_docstring_parser/__init__.py

@@ -1,3 +1,4 @@
+# Copyright (c) 2025 Vladimir Iglovikov
 """Google Docstring Parser package.
 
 A lightweight, efficient parser for Google-style Python docstrings that converts them into structured dictionaries.

{google_docstring_parser-0.0.11 → google_docstring_parser-0.0.12}/google_docstring_parser/google_docstring_parser.py

@@ -18,7 +18,10 @@ This module provides functions to parse Google-style docstrings into structured
 
 from __future__ import annotations
 
+import ast
+import io
 import re
+import tokenize
 from typing import TYPE_CHECKING, Any
 
 from docstring_parser import parse
@@ -438,42 +441,86 @@ def _process_args_with_validation(
     result["Args"] = args
 
 
-def _parse_returns_section(sections: dict[str, str], *, validate_types: bool) -> dict[str, str] | str:
-    """Process the Returns section of a docstring into type and description.
+def _return_annotation_tokens(text: str) -> tuple[list[tuple[int, str]], tuple[int, int] | None]:
+    """Find the return separator outside quoted literals and nested brackets.
 
     Args:
-        sections (dict[str, str]): The sections dictionary
-        validate_types (bool): Whether to validate type annotations
+        text (str): Returns section contents.
 
     Returns:
-        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
+        tuple[list[tuple[int, str]], tuple[int, int] | None]: Prefix tokens and zero-based separator position.
     """
-    if (
-        "Returns" not in sections
-        or not (returns_lines := sections["Returns"].split("\n"))
-        or not (return_match := re.match(r"^(?:([^:]+):\s*)?(.*)$", returns_lines[0].strip()))
-    ):
-        return {}
+    prefix: list[tuple[int, str]] = []
+    depth = 0
+    ignored = {tokenize.NL, tokenize.NEWLINE, tokenize.INDENT, tokenize.DEDENT, tokenize.ENDMARKER, tokenize.COMMENT}
+    # An implicit group permits wrapping between any two annotation tokens, regardless of indentation.
+    tokens = tokenize.generate_tokens(io.StringIO(f"(\n{text}").readline)
+    next(tokens)
+    try:
+        for token in tokens:
+            if token.type == tokenize.NL and depth == 0 and not token.line.strip():
+                break
+            if token.type == tokenize.OP:
+                if token.string in "([{":
+                    depth += 1
+                elif token.string in ")]}":
+                    depth -= 1
+                elif token.string == ":" and depth == 0:
+                    return prefix, (token.start[0] - 2, token.start[1])
+            if token.type not in ignored:
+                prefix.append((token.type, token.string))
+    except (tokenize.TokenError, IndentationError):
+        return prefix, None
+    return prefix, None
+
+
+def _is_return_type(expression: ast.expr) -> bool:
+    """Distinguish Python type expressions from wrapped numeric or prose content.
 
-    return_type = return_match[1]
-    return_desc = return_match[2].strip()
+    Args:
+        expression (ast.expr): Parsed candidate return annotation.
 
-    # Special case: Returns section just contains "None"
-    if not return_type and return_desc == "None":
-        return "None"
+    Returns:
+        bool: Whether the candidate has the shape of a type expression.
+    """
+    match expression:
+        case ast.Name() | ast.Attribute() | ast.Subscript() | ast.Constant(value=str() | None):
+            return True
+        case ast.BinOp(left=left, op=ast.BitOr(), right=right):
+            return _is_return_type(left) and _is_return_type(right)
+        case _:
+            return False
 
-    # Validate type if present
-    if return_type and validate_types:
-        validate_type_annotation(return_type)
 
-        # Check for nested types
-        if "[" in return_type and "]" in return_type:
-            check_text_for_bare_collections(return_type)
+def _split_return_header(text: str) -> tuple[str | None, str]:
+    """Parse a wrapped type expression while preserving untyped prose.
 
-    return {"type": return_type, "description": return_desc.rstrip()}
+    Args:
+        text (str): Returns section contents.
+
+    Returns:
+        tuple[str | None, str]: Return annotation and its first description line.
+    """
+    lines = text.split("\n")
+    first_line = lines[0].strip()
+    prefix, separator = _return_annotation_tokens(text)
+    if separator is None:
+        return None, first_line
+    row, column = separator
+    if row == 0:
+        annotation = first_line[:column].strip()
+        if not annotation:
+            return None, first_line
+        return annotation, first_line[column + 1 :].strip()
+    candidate = tokenize.untokenize(prefix)
+    try:
+        expression = ast.parse(candidate.strip(), mode="eval").body
+        if not _is_return_type(expression):
+            return None, first_line
+        annotation = ast.unparse(expression)
+    except (SyntaxError, ValueError, RecursionError):
+        return None, first_line
+    return annotation, lines[row][column + 1 :].strip()
 
 
 def _process_returns_with_validation(
@@ -493,16 +540,13 @@ def _process_returns_with_validation(
     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
+    return_type, return_desc = _split_return_header(sections["Returns"])
+    if return_type and validate_types:
+        _validate_type_with_error_handling(return_type, result, collect_errors)
+    if not return_type and return_desc == "None":
+        result["Returns"] = "None"
+    else:
+        result["Returns"] = {"type": return_type, "description": return_desc}
 
 
 def _process_references_section(sections: dict[str, str], result: dict[str, Any]) -> None:

{google_docstring_parser-0.0.11 → google_docstring_parser-0.0.12}/google_docstring_parser/type_validation.py

@@ -112,7 +112,7 @@ class InvalidTypeAnnotationError(ValueError):
         super().__init__(message)
 
 
-class BracketValidationError(ValueError):
+class BracketValidationError(InvalidTypeAnnotationError):
     """Error raised when brackets in a type annotation are not balanced or mismatched.
 
     Contains specific error types for different bracket validation issues.
@@ -315,7 +315,7 @@ def replace_string_literals(match: Match[AnyStr], literals: list[str]) -> str:
     """
     placeholder = str(match.group(0))
     if placeholder.startswith("STR_LITERAL_"):
-        idx = int(placeholder.split("_")[-1])
+        idx = int(placeholder.rsplit("_", maxsplit=1)[-1])
         if idx < len(literals):
             return literals[idx]
     return placeholder