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:
- Free for Albumentations Team projects (https://github.com/albumentations-team)
- Paid license required for all other users (individuals, companies, and other open-source projects)
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:
- Single reference format:
"""
Reference:
Paper title: https://example.com/paper
"""
- 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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.