docstring_parser

You can install the package directly using pip:

pip install docstring_parser

If you are using a virtual environment, follow these steps:

python -m venv venv # create environment
source venv/bin/activate # activate environment
python -m pip install docstring_parser

To install using conda, use the conda-forge channel. You can either install it into your current environment or create a new one:

Install into current environment:

conda install -c conda-forge docstring_parser

Create a new environment with the package:

conda create -n my-new-environment -c conda-forge docstring_parser

The NumpydocParser uses specialized Section subclasses to handle different parts of the docstring. Common ones include:

• ParamSection: Handles Parameters, Args, Attributes, etc. Extracts arg_name, type_name, is_optional, and default.
• RaisesSection: Handles Raises or Warns. Extracts the exception type and description.
• ReturnsSection / YieldsSection: Handles Returns or Yields. Extracts return_name, type_name, and whether it is a generator.
• ExamplesSection: Handles Examples. Parses code snippets (lines starting with >>>) and their accompanying descriptions.
• DeprecationSection: Handles Sphinx-style .. deprecated:: blocks, extracting the version and description.

The SectionType enum tells the parser how to interpret the content following a section title. This determines whether the parser expects a single block of text or multiple individual entries (like parameters).

Members:

• SINGULAR (0): For sections containing a single block of text (e.g., Examples).
• MULTIPLE (1): For sections containing multiple distinct entries (e.g., Args, Parameters, Raises, Attributes).
• SINGULAR_OR_MULTIPLE (2): For sections that might contain either a single entry or multiple entries (e.g., Returns, Yields).

from docstring_parser import SectionType

When parsing Epydoc docstrings, the following metadata types are extracted into the Docstring.meta list as specific objects:

The Numpydoc parser attempts to extract default values for parameters in two ways:

1. In the type declaration: It looks for patterns like default True, default=True, or default: True within the type string.
   • Example: copy : bool, default True
2. In the description: If no default is found in the type declaration, it searches the parameter's description for natural language patterns like Defaults to 'value' or is 'value'.

When a default is detected, the parameter is automatically marked as is_optional=True.

The compose function allows you to take a Docstring object (the output of a parser) and convert it back into a formatted string. This is useful for docstring manipulation or re-formatting.

You can specify a rendering_style (e.g., RenderingStyle.COMPACT) and an indent string.

from docstring_parser import compose, parse, RenderingStyle

docstring_text = """
Summary.

Parameters
----------
x : int
    Description.
"""
parsed = parse(docstring_text)
new_text = compose(parsed, rendering_style=RenderingStyle.COMPACT)

To parse a docstring written in the Numpydoc format, use the NumpydocParser class or the convenience parse function. The parser breaks the docstring into a Docstring object containing a short description, long description, and various metadata sections like parameters, returns, raises, and examples.

By default, the parser recognizes standard Numpydoc sections such as Parameters, Returns, Raises, Examples, Notes, and See Also. You can extend or override these sections using add_section().

from docstring_parser import parse

docstring_text = """
Add a description.

Parameters
----------
arg1 : int
    Description of arg1.
arg2 : str, optional
    Description of arg2, defaults to 'hello'.
"""

parsed = parse(docstring_text)
print(parsed.short_description)
print(parsed.params[0].arg_name)

The AttributeDocstrings.get_attr_docs method provides a way to manually extract attribute documentation from a class or module using AST analysis.

Parameters:

• component: The class or module object to process.

Returns: A dictionary where keys are attribute names and values are tuples containing (description, type, default):

• description (str): The literal string following the attribute.
• type (Optional[str]): The type annotation string (e.g., 'int').
• default (Optional[str]): The string representation of the default value (e.g., '30').

from docstring_parser.attrdoc import AttributeDocstrings

class Example:
    """Class doc."""
    port: int = 8080
    """The network port."""

extractor = AttributeDocstrings()
docs = extractor.get_attr_docs(Example)
# docs will be: {'port': ('The network port.', 'int', '8080')}

The compose function takes a Docstring object (produced by parse) and converts it back into a formatted string. You can control the output using the rendering_style and indent parameters.

Parameters:

• docstring: The Docstring object to render.
• rendering_style: An instance of RenderingStyle (e.g., RenderingStyle.COMPACT or RenderingStyle.EXPANDED).
• indent: A string defining the indentation used for multi-line descriptions (default is " ").

from docstring_parser.epydoc import parse, compose, RenderingStyle

docstring_text = """
Summary.

@param x: description
"""
parsed = parse(docstring_text)
rendered = compose(parsed, rendering_style=RenderingStyle.EXPANDED)
print(rendered)