Skip to content

Docstring parser

docstring_parser

Structured docstring parser for axm-ast.

Parses raw docstring strings into structured sections without requiring external dependencies. Supports Google, NumPy, and Sphinx styles.

Only non-redundant sections are extracted:

  • summary — first paragraph (unique value vs signature)
  • raises — exception types + descriptions (absent from signature)
  • examples — usage examples (pedagogical, not in signature)

Args and Returns are intentionally skipped: the information they contain is already present in the function signature field.

Example

from axm_ast.docstring_parser import parse_docstring parsed = parse_docstring('Do thing.\n\nRaises:\n ValueError: bad.') parsed.summary 'Do thing.' parsed.raises [('ValueError', 'bad.')]

ParsedDocstring dataclass

Structured representation of a parsed docstring.

Attributes:

Name Type Description
summary str | None

First paragraph of the docstring (may be multi-line).
raises list[tuple[str, str]]

List of (exception_type, description) tuples.
examples list[str]

List of example blocks as raw strings.
Source code in packages/axm-ast/src/axm_ast/docstring_parser.py 
67
68
69
70
71
72
73
74
75
76
77
78
79
@dataclass
class ParsedDocstring:
    """Structured representation of a parsed docstring.

    Attributes:
        summary: First paragraph of the docstring (may be multi-line).
        raises: List of (exception_type, description) tuples.
        examples: List of example blocks as raw strings.
    """

    summary: str | None = None
    raises: list[tuple[str, str]] = field(default_factory=list)
    examples: list[str] = field(default_factory=list)

parse_docstring(raw)

Parse a raw docstring string into structured sections.

Supports Google, NumPy, and Sphinx docstring styles. Args/Returns sections are deliberately ignored (redundant with the function signature field).

Parameters:

Name Type Description Default
raw str | None

Raw docstring content, or None.

 required

Returns:

Type Description
ParsedDocstring

ParsedDocstring with summary, raises, and examples.
Example

p = parse_docstring('Summary.\n\nRaises:\n ValueError: bad input.') p.summary 'Summary.' p.raises [('ValueError', 'bad input.')]

Source code in packages/axm-ast/src/axm_ast/docstring_parser.py 
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
def parse_docstring(raw: str | None) -> ParsedDocstring:
    """Parse a raw docstring string into structured sections.

    Supports Google, NumPy, and Sphinx docstring styles.
    ``Args``/``Returns`` sections are deliberately ignored (redundant
    with the function ``signature`` field).

    Args:
        raw: Raw docstring content, or ``None``.

    Returns:
        ``ParsedDocstring`` with ``summary``, ``raises``, and ``examples``.

    Example:
        >>> p = parse_docstring('Summary.\\n\\nRaises:\\n    ValueError: bad input.')
        >>> p.summary
        'Summary.'
        >>> p.raises
        [('ValueError', 'bad input.')]
    """
    if not raw:
        return ParsedDocstring()

    # Normalise indentation (strip common leading whitespace)
    lines = raw.expandtabs().splitlines()
    lines = _strip_indent(lines)
    text = "\n".join(lines).strip()

    style = _detect_style(text)

    summary = _extract_summary(text)

    if style == "sphinx":
        raises = _extract_raises_sphinx(text)
        examples: list[str] = []
    elif style == "numpy":
        raises = _extract_raises_numpy(text)
        examples = _extract_examples_numpy(text)
    else:  # google (default)
        raises = _extract_raises_google(text)
        examples = _extract_examples_google(text)

    return ParsedDocstring(summary=summary, raises=raises, examples=examples)