docstring_parser

package documentation

Parse docstrings as per Sphinx notation.

Module	`attrdoc`	Attribute docstrings parsing.
Module	`common`	Common methods for parsing.
Module	`epydoc`	Epyoc-style docstring parsing.
Module	`google`	Google-style docstring parsing.
Module	`numpydoc`	Numpydoc-style docstring parsing.
Module	`parser`	The main parsing routine.
Module	`rest`	ReST-style docstring parsing.
Module	`util`	Utility functions for working with docstrings.

From __init__.py:

Class	`Docstring`	Docstring object representation.
Class	`DocstringDeprecated`	DocstringMeta symbolizing deprecation metadata.
Class	`DocstringMeta`	Docstring meta information.
Class	`DocstringParam`	DocstringMeta symbolizing :param metadata.
Class	`DocstringRaises`	DocstringMeta symbolizing :raises metadata.
Class	`DocstringReturns`	DocstringMeta symbolizing :returns or :yields metadata.
Class	`DocstringStyle`	Docstring style.
Class	`RenderingStyle`	Rendering style when unparsing parsed docstrings.
Exception	`ParseError`	Base class for all parsing related errors.
Function	`combine_docstrings`	A function decorator that parses the docstrings from `others`, programmatically combines them with the parsed docstring of the decorated function, and replaces the docstring of the decorated function with the composed result...
Function	`compose`	Render a parsed docstring into docstring text.
Function	`parse`	Parse the docstring into its components.
Function	`parse_from_object`	Parse the object's docstring(s) into its components.

def combine_docstrings(*others: _Func, exclude: T.Iterable[type[DocstringMeta]] = (), style: DocstringStyle = DocstringStyle.AUTO, rendering_style: RenderingStyle = RenderingStyle.COMPACT) -> _Func: (source) ¶

A function decorator that parses the docstrings from others, programmatically combines them with the parsed docstring of the decorated function, and replaces the docstring of the decorated function with the composed result. Only parameters that are part of the decorated functions signature are included in the combined docstring. When multiple sources for a parameter or docstring metadata exists then the decorator will first default to the wrapped function's value (when available) and otherwise use the rightmost definition from others.

The following example illustrates its usage:

>>> def fun1(a, b, c, d):
...    '''short_description: fun1
...
...    :param a: fun1
...    :param b: fun1
...    :return: fun1
...    '''
>>> def fun2(b, c, d, e):
...    '''short_description: fun2
...
...    long_description: fun2
...
...    :param b: fun2
...    :param c: fun2
...    :param e: fun2
...    '''
>>> @combine_docstrings(fun1, fun2)
>>> def decorated(a, b, c, d, e, f):
...     '''
...     :param e: decorated
...     :param f: decorated
...     '''
>>> print(decorated.__doc__)
short_description: fun2
<BLANKLINE>
long_description: fun2
<BLANKLINE>
:param a: fun1
:param b: fun1
:param c: fun2
:param e: fun2
:param f: decorated
:returns: fun1
>>> @combine_docstrings(fun1, fun2, exclude=[DocstringReturns])
>>> def decorated(a, b, c, d, e, f): pass
>>> print(decorated.__doc__)
short_description: fun2
<BLANKLINE>
long_description: fun2
<BLANKLINE>
:param a: fun1
:param b: fun1
:param c: fun2
:param e: fun2

Parameters
*others:`_Func`	callables from which to parse docstrings.
exclude:`T.Iterable[type[DocstringMeta]]`	an iterable of `DocstringMeta` subclasses to exclude when combining docstrings.
style:`DocstringStyle`	style composed docstring. The default will infer the style from the decorated function.
rendering_style:`RenderingStyle`	The rendering style used to compose a docstring.

Returns
`_Func`	the decorated function with a modified docstring.

def compose(docstring: Docstring, style: DocstringStyle = DocstringStyle.AUTO, rendering_style: RenderingStyle = RenderingStyle.COMPACT, indent: str = ' ') -> str: (source) ¶

Render a parsed docstring into docstring text.

Parameters
docstring:`Docstring`	parsed docstring representation
style:`DocstringStyle`	docstring style to render
rendering_style:`RenderingStyle`	Undocumented
indent:`str`	the characters used as indentation in the docstring string

Returns
`str`	docstring text

def parse(text: str | None, style: DocstringStyle = DocstringStyle.AUTO) -> Docstring: (source) ¶

Parse the docstring into its components.

Parameters
text:`str \| None`	docstring text to parse
style:`DocstringStyle`	docstring style

Returns
`Docstring`	parsed docstring representation

def parse_from_object(obj: T.Any, style: DocstringStyle = DocstringStyle.AUTO) -> Docstring: (source) ¶

Parse the object's docstring(s) into its components.

The object can be anything that has a __doc__ attribute. In contrast to the parse function, parse_from_object is able to parse attribute docstrings which are defined in the source code instead of __doc__.

Currently only attribute docstrings defined at class and module levels are supported. Attribute docstrings defined in __init__ methods are not supported.

When given a class, only the attribute docstrings of that class are parsed, not its inherited classes. This is a design decision. Separate calls to this function should be performed to get attribute docstrings of parent classes.

Parameters
obj:`T.Any`	object from which to parse the docstring(s)
style:`DocstringStyle`	docstring style

Returns
`Docstring`	parsed docstring representation