Skip to main content

Google Docstring Parser

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:

See the LICENSE file for complete details.

Installation

pip install google-docstring-parser

Usage

from google_docstring_parser import parse_google_docstring

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
image segmentation or object detection where you want to maintain the relative positions of
features while introducing realistic deformations.

Args:
    alpha (float): Scaling factor for the random displacement fields. Higher values result in
        more pronounced distortions. Default: 1.0
    sigma (float): Standard deviation of the Gaussian filter used to smooth the displacement
        fields. Higher values result in smoother, more global distortions. Default: 50.0

Example:
    >>> import albumentations as A
    >>> transform = A.ElasticTransform(alpha=1, sigma=50, p=0.5)

References:
    - Original paper: Simard, P. Y., et al. "Best practices for convolutional neural networks applied to visual document analysis." ICDAR 2003
    - Implementation details: https://example.com/elastic-transform
Returns:
    dict[str, Any]: Some info here
"""

parsed = parse_google_docstring(docstring)
print(parsed)

Output:

{
    "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": "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": [
        {
            "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"},
    ],
    "Returns": {"type": "dict[str, Any]", "description": "Some info here"},
}

Features

  • Parses Google-style docstrings into structured dictionaries
  • Extracts parameter names, types, and descriptions
  • Preserves other sections like Examples, Notes, etc.
  • 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:

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:

  1. Single reference format:
"""
Reference:
    Paper title: https://example.com/paper
"""
  1. Multiple references format (requires leading dashes):
"""
References:
    - First paper: https://example.com/paper1
    - Second paper: https://example.com/paper2
"""

Each reference is parsed into a dictionary with description and source keys. URLs in the source are properly handled, ensuring colons in URLs are not confused with the separator colon.

Short Description (Meta Description)

The checker extracts the short description as the first paragraph (up to the first blank line). Multi-line first paragraphs are joined with spaces. This is useful for meta descriptions on documentation sites. SEO best practice: 120-160 characters. Use min_short_description_length and max_short_description_length to enforce bounds (0 to disable).

Pre-commit Hook

This package includes a pre-commit hook that checks if Google-style docstrings in your codebase can be parsed correctly.

Usage in Other Projects

To use this hook in another project, add the following to your .pre-commit-config.yaml:

- repo: https://github.com/ternaus/google-docstring-parser
  rev: v0.0.1  # Use the latest version
  hooks:
    - id: check-google-docstrings

Configuration

The hook is configured via pyproject.toml, following modern Python tooling conventions like those used by mypy, ruff, and other tools.

Add a [tool.docstring_checker] section to your pyproject.toml:

[tool.docstring_checker]
paths = ["src", "tests"]                     # Directories or files to scan
require_param_types = true                   # Require parameter types in docstrings
check_references = true                      # Check references for proper format
check_type_consistency = true                # Compare docstring types with annotations
exclude_files = ["conftest.py", "__init__.py"] # Files to exclude from checks
min_short_description_length = 50            # Minimum short description length; 0 to disable
max_short_description_length = 160           # Maximum short description length; 0 to disable (SEO: 120-160)
verbose = false                              # Enable verbose output

Metadata

Release files for google-docstring-parser 0.0.12

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for google-docstring-parser 0.0.12
File Size Uploaded Provenance Actions
google_docstring_parser-0.0.12.tar.gz 42.1 kB Without provenance Details for google_docstring_parser-0.0.12.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for google-docstring-parser 0.0.12
File Interpreter ABI Platform Actions
google_docstring_parser-0.0.12-py3-none-any.whl Python 3 none any Details for google_docstring_parser-0.0.12-py3-none-any.whl

Total release size: 68.9 kB

Release files / google_docstring_parser-0.0.12.tar.gz

Download URL google_docstring_parser-0.0.12.tar.gz
Size 42.1 kB
Tags Source
SHA-256 checksum
How to use checksums
c331922af14cef81fbeb7f4bbb766fea4215ba350c1e6c04a5f81ce49c012f8c
BLAKE2b-256 checksum
How to use checksums
18a3efcc34218262b8f45f00f92f7dba53125cdd0c58bbff3caf1abcaf846197
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.17

Release files / google_docstring_parser-0.0.12-py3-none-any.whl

Download URL google_docstring_parser-0.0.12-py3-none-any.whl
Size 26.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
79911db924643391473f7c8a779313a3b85858bb3ca39a51bec15f1cae2829f9
BLAKE2b-256 checksum
How to use checksums
fe212b2f8fb88a909511ddf0f58389178638e4c067e2fa3db992738f787b80aa
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.17

Security for google-docstring-parser 0.0.12

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page