docstring_parser

docstring_parser parses Python docstrings written in any of the four major community conventions — ReST/Sphinx, Google-style, Numpydoc, and Epydoc — into a single unified Docstring object, regardless of which style the original author used. The parsed result exposes structured access to the short and long descriptions, parameters (with types and descriptions), return values, raised exceptions, and other docstring metadata as typed Python objects rather than raw strings.

This normalization is what makes it valuable to documentation generators, IDE tooling, and schema-generation libraries: instead of writing separate parsers for each docstring convention a codebase might use, consumers call parse() once and get a consistent object model back, with auto-detection of which style a given docstring uses.

What You Get

• A single parse() function that auto-detects and parses ReST, Google, Numpydoc, and Epydoc docstring styles
• A unified Docstring object exposing short_description, long_description, params, returns, and raises as typed attributes
• Per-format parser modules (rest.py, google.py, numpydoc.py, epydoc.py) usable directly when the format is already known
• An attrdoc module for parsing attribute-level docstrings on class fields
• Full type hints (py.typed marker) for editor and static-analysis support

Common Use Cases

• Extracting parameter types and descriptions from docstrings to auto-generate JSON schemas or CLI help text
• Building documentation generators that need a normalized model regardless of the source docstring convention
• Powering IDE/language-server features like parameter hints derived from docstring content
• Feeding structured function/parameter descriptions into other tools (e.g. schema or code generators) from existing docstrings

Under The Hood

Architecture — docstring_parser/parser.py implements format auto-detection and dispatches to the appropriate style-specific parser; each of rest.py, google.py, numpydoc.py, and epydoc.py implements its own tokenizer/parser tailored to that convention’s section syntax, but all normalize their output into the shared data classes defined in common.py (Docstring, DocstringParam, DocstringReturns, DocstringRaises, etc.). attrdoc.py layers attribute-docstring extraction (using the AST module) on top of the same common model, and util.py provides shared helpers like description-combining logic.

Tech Stack — Pure Python with zero runtime dependencies beyond the standard library, using dataclasses/typed classes for its result model and Python’s ast module for attribute-docstring extraction. Packaged with a py.typed marker for full static-typing support in consumers.

Code Quality — The project maintains a GitHub Actions build pipeline (badge in the README) running its test suite, and the codebase is organized with one file per docstring style, keeping each parser’s grammar isolated and independently testable. Development is currently maintenance-mode (moderate commit frequency, infrequent releases per the health-score data) but the project has a decade of production use across major Python doc-tooling.

API Design — A single top-level parse() call is the entire API surface most users need, immediately returning a typed object with attribute access (docstring.params[1].arg_name) rather than requiring users to walk a raw AST or dictionary. The README leads directly with a runnable REPL example demonstrating this, keeping the learning curve minimal for the common case while the per-format modules remain available for advanced, format-specific use.