pymend.docstring_parser package

Submodules

pymend.docstring_parser.attrdoc module

pymend.docstring_parser.common module

Common methods for parsing.

class pymend.docstring_parser.common.Docstring(style: DocstringStyle | None = None, section_titles: KeyReturnDict[str, str] | None = None)[source]

Bases: object

Docstring object representation.

property deprecation: DocstringDeprecated | None

Return a single information on function deprecation notes.

Returns:: single information on function deprecation notes.
Return type:: Optional[DocstringDeprecated]

property examples: list[DocstringExample]

Return a list of information on function examples.

Returns:: list of information on function examples.
Return type:: list[DocstringExample]

property many_returns: list[DocstringReturns]

Return a list of information on function return.

Returns:: list of information on function return.
Return type:: list[DocstringReturns]

property many_yields: list[DocstringYields]

Return a list of information on function yields.

Returns:: list of information on function yields.
Return type:: list[DocstringYields]

property params: list[DocstringParam]

Return a list of information on function params.

Returns:: list of information on function params
Return type:: list[DocstringParam]

property raises: list[DocstringRaises]

Return a list of the exceptions that the function may raise.

Returns:: list of the exceptions that the function may raise.
Return type:: list[DocstringRaises]

property returns: DocstringReturns | None

Return a single information on function return.

Takes the first return information.

Returns:: Single information on function return.
Return type:: Optional[DocstringReturns]

property yields: DocstringYields | None

Return information on function yield.

Takes the first generator information.

Returns:: Single information on function yield.
Return type:: Optional[DocstringYields]

class pymend.docstring_parser.common.DocstringDeprecated(args: list[str], description: str | None, version: str | None)[source]

Bases: DocstringMeta

DocstringMeta symbolizing deprecation metadata.

version: str | None

class pymend.docstring_parser.common.DocstringExample(args: list[str], description: str | None, snippet: str | None)[source]

Bases: DocstringMeta

DocstringMeta symbolizing example metadata.

snippet: str | None

class pymend.docstring_parser.common.DocstringMeta(args: list[str], description: str | None)[source]

Bases: object

Docstring meta information.

Symbolizes lines in form of

Parameters:

args (List[str]) – list of arguments. The exact content of this variable is dependent on the kind of docstring; it’s used to distinguish between custom docstring meta information items.
description (Optional[str]) – associated docstring description.

args: list[str]

description: str | None

class pymend.docstring_parser.common.DocstringParam(args: list[str], description: str | None, arg_name: str, type_name: str | None, is_optional: bool | None, default: str | None)[source]

Bases: DocstringMeta

DocstringMeta symbolizing :param metadata.

arg_name: str

default: str | None

is_optional: bool | None

type_name: str | None

class pymend.docstring_parser.common.DocstringRaises(args: list[str], description: str | None, type_name: str | None)[source]

Bases: DocstringMeta

DocstringMeta symbolizing :raises metadata.

type_name: str | None

class pymend.docstring_parser.common.DocstringReturns(args: list[str], description: str | None, type_name: str | None, is_generator: bool, return_name: str | None = None)[source]

Bases: DocstringMeta

DocstringMeta symbolizing :returns metadata.

is_generator: bool

return_name: str | None = None

type_name: str | None

class pymend.docstring_parser.common.DocstringStyle(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: Enum

Docstring style.

AUTO = 255

EPYDOC = 4

GOOGLE = 2

NUMPYDOC = 3

REST = 1

class pymend.docstring_parser.common.DocstringYields(args: list[str], description: str | None, type_name: str | None, is_generator: bool, yield_name: str | None = None)[source]

Bases: DocstringMeta

DocstringMeta symbolizing :yields metadata.

is_generator: bool

type_name: str | None

yield_name: str | None = None

class pymend.docstring_parser.common.KeyReturnDict(dict=None, /, **kwargs)[source]

Bases: UserDict[K, V]

Custom dict that returns the key back in missing case.

exception pymend.docstring_parser.common.ParseError[source]

Bases: RuntimeError

Base class for all parsing related errors.

class pymend.docstring_parser.common.RenderingStyle(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: Enum

Rendering style when unparsing parsed docstrings.

CLEAN = 2

COMPACT = 1

EXPANDED = 3

pymend.docstring_parser.common.append_description(docstring: Docstring, parts: list[str]) → None[source]

Append the docstrings description to the output stream.

Parameters:

docstring (Docstring) – Docstring whose information should be added.
parts (list[str]) – List of strings representing the output of compose(). Descriptions should be added to this.

pymend.docstring_parser.common.clean_str(string: str) → str | None[source]

Strip a string and return None if it is now empty.

Parameters:: string (str) – String to clean
Returns:: None of the stripped string is empty. Otherwise the stripped string.
Return type:: Optional[str]

pymend.docstring_parser.common.split_description(docstring: Docstring, desc_chunk: str) → None[source]

Break description into short and long parts.

Parameters:

docstring (Docstring) – Docstring to fill with description information.
desc_chunk (str) – Chunk of the raw docstring representing the description.

pymend.docstring_parser.epydoc module

Epyoc-style docstring parsing.

pymend.docstring_parser.google module

Google-style docstring parsing.

class pymend.docstring_parser.google.GoogleParser(sections: list[Section] | None = None, *, title_colon: bool = True)[source]

Bases: object

Parser for Google-style docstrings.

add_section(section: Section) → None[source]

Add or replace a section.

Parameters:: section (Section) – The new section.

canonical_titles() → KeyReturnDict[str, str][source]

Get the canonical title for a section key.

Parameters:: title (str) – Section key.
Returns:: Canonical title.
Return type:: KeyReturnDict[str, str]

parse(text: str | None) → Docstring[source]

Parse the Google-style docstring into its components.

Parameters:: text (Optional[str]) – docstring text
Returns:: parsed docstring
Return type:: Docstring
Raises:: ParseError – If no specification could be found for a title, chunk pair.

class pymend.docstring_parser.google.Section(title: str, key: str, type_info: SectionType)[source]

Bases: NamedTuple

A docstring section.

key: str: Alias for field number 1

title: str: Alias for field number 0

type_info: SectionType: Alias for field number 2

class pymend.docstring_parser.google.SectionType(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: IntEnum

Types of sections.

MULTIPLE = 1: For sections like params.

SINGULAR = 0: For sections like examples.

SINGULAR_OR_MULTIPLE = 2: For sections like returns or yields.

pymend.docstring_parser.google.compose(docstring: Docstring, rendering_style: RenderingStyle = RenderingStyle.COMPACT, indent: str = ' ') → str[source]

Render a parsed docstring into docstring text.

Parameters:

docstring (Docstring) – parsed docstring representation
rendering_style (RenderingStyle) – the style to render docstrings (Default value = RenderingStyle.COMPACT)
indent (str) – the characters used as indentation in the docstring string (Default value = ‘ ‘)

Returns:

docstring text

Return type:

str

pymend.docstring_parser.google.parse(text: str | None) → Docstring[source]

Parse the Google-style docstring into its components.

Parameters:: text (Optional[str]) – docstring text
Returns:: parsed docstring
Return type:: Docstring

pymend.docstring_parser.numpydoc module

Numpydoc-style docstring parsing.

See

https://numpydoc.readthedocs.io/en/latest/format.html

class pymend.docstring_parser.numpydoc.DeprecationSection(title: str, key: str)[source]

Bases: _SphinxSection

Parser for numpydoc “deprecation warning” sections.

E.g. any section that looks like this:: Deprecated since version 1.6.0: This description has multiple lines!

parse(text: str) → Iterable[DocstringDeprecated][source]

Parse DocstringDeprecated objects from the body of this section.

Parameters:: text (str) – Text of the deprecation section.
Yields:: DocstringDeprecated – Parsed representation of the deprecation item.
Raises:: ParseError – If the parsed version number was unexpectedly None. Usually a lack of version number would be represented by an empty string.

class pymend.docstring_parser.numpydoc.ExamplesSection(title: str, key: str)[source]

Bases: Section

Parser for numpydoc examples sections.

E.g. any section that looks like this:

Optional description for the following example. Always preceded and followed by an empty line. Except for the first description.

>>> import numpy.matlib
>>> np.matlib.empty((2, 2))    # filled with random data
matrix([[  6.76425276e-320,   9.79033856e-307], # random
        [  7.39337286e-309,   3.22135945e-309]])

Description for the second example.

>>> d = np.zeros((5,2))
>>> for i in range(5):
...   for j in range(2):
...     for k in range(3):
...       for n in range(4):
...         d[i,j] += a[k,n,i] * b[n,k,j]
>>> c == d
array([[ True,  True],
    [ True,  True],
    [ True,  True],
    [ True,  True],
    [ True,  True]])

parse(text: str) → Iterable[DocstringExample][source]

Parse DocstringExample objects from the body of this section.

Parameters:: text (str) – section body text. Should be cleaned with inspect.cleandoc before parsing.
Yields:: DocstringExample – Docstring example sections

class pymend.docstring_parser.numpydoc.NumpydocParser(sections: Iterable[Section] | None = None)[source]

Bases: object

Parser for numpydoc-style docstrings.

add_section(section: Section) → None[source]

Add or replace a section.

Parameters:: section (Section) – The new section.

canonical_titles() → KeyReturnDict[str, str][source]

Get the canonical title for a section key.

Parameters:: title (str) – Section key.
Returns:: Canonical title.
Return type:: KeyReturnDict[str, str]

parse(text: str | None) → Docstring[source]

Parse the numpy-style docstring into its components.

Parameters:: text (Optional[str]) – docstring text
Returns:: parsed docstring
Return type:: Docstring
Raises:: ParseError – If multiple titles are found for the same section.

class pymend.docstring_parser.numpydoc.ParamSection(title: str, key: str)[source]

Bases: _KVSection

Parser for numpydoc parameter sections.

E.g. any section that looks like this:

arg_name: arg_description
arg_2type, optional: descriptions can also span… … multiple lines

class pymend.docstring_parser.numpydoc.RaisesSection(title: str, key: str)[source]

Bases: _KVSection

Parser for numpydoc raises sections.

E.g. any section that looks like this:

ValueError: A description of what might raise ValueError

class pymend.docstring_parser.numpydoc.ReturnsSection(title: str, key: str)[source]

Bases: _KVSection

Parser for numpydoc returns sections.

E.g. any section that looks like this:

return_nametype: A description of this returned value
another_type: Return names are optional, types are required

is_generator = False

class pymend.docstring_parser.numpydoc.Section(title: str, key: str)[source]

Bases: object

Numpydoc section parser.

parse(text: str) → Iterable[DocstringMeta][source]

Parse DocstringMeta objects from the body of this section.

Parameters:: text (str) – section body text. Should be cleaned with inspect.cleandoc before parsing.
Yields:: DocstringMeta – object from this section body.

property title_pattern: str

Regular expression pattern matching this section’s header.

This pattern will match this instance’s title attribute in an anonymous group.

Returns:: Regex pattern as a string.
Return type:: str

class pymend.docstring_parser.numpydoc.YieldsSection(title: str, key: str)[source]

Bases: _KVSection

Parser for numpydoc generator “yields” sections.

is_generator = True

pymend.docstring_parser.numpydoc.compose(docstring: Docstring, rendering_style: RenderingStyle = RenderingStyle.COMPACT, indent: str = ' ') → str[source]

Render a parsed docstring into docstring text.

Parameters:

docstring (Docstring) – parsed docstring representation
rendering_style (RenderingStyle) – the style to render docstrings (Default value = RenderingStyle.COMPACT)
indent (str) – the characters used as indentation in the docstring string (Default value = ‘ ‘)

Returns:

docstring text

Return type:

str

pymend.docstring_parser.numpydoc.parse(text: str | None) → Docstring[source]

Parse the numpy-style docstring into its components.

Parameters:: text (Optional[str]) – docstring text
Returns:: parsed docstring
Return type:: Docstring

pymend.docstring_parser.numpydoc.process_examples(examples: list[DocstringExample], parts: list[str]) → None[source]

Add string representation of examples section to parts.

Parameters:

examples (list[DocstringExample]) – DocstringExamples to add to parts.
parts (list[str]) – List of strings representing the final output of compose().
indent (str) – the characters used as indentation in the docstring string (Default value = ‘ ‘)

pymend.docstring_parser.parser module

The main parsing routine.

pymend.docstring_parser.parser.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 (Default value = DocstringStyle.AUTO)
indent (str) – the characters used as indentation in the docstring string (Default value = ‘ ‘)
rendering_style (RenderingStyle) – The rendering style to use. (Default value = RenderingStyle.COMPACT)

Returns:

docstring text

Return type:

str

Raises:

ValueError – If no output style could be determined.

pymend.docstring_parser.parser.parse(text: str | None, style: DocstringStyle = DocstringStyle.AUTO) → Docstring[source]

Parse the docstring into its components.

Parameters:

text (Optional[str]) – docstring text to parse
style (DocstringStyle) – docstring style (Default value = DocstringStyle.AUTO)

Returns:

parsed docstring representation

Return type:

Docstring

Raises:

ParserError – If none of the available module an parse the docstring

pymend.docstring_parser.rest module

ReST-style docstring parsing.

pymend.docstring_parser.rest.compose(docstring: Docstring, rendering_style: RenderingStyle = RenderingStyle.COMPACT, indent: str = ' ') → str[source]

Render a parsed docstring into docstring text.

Parameters:

docstring (Docstring) – parsed docstring representation
rendering_style (RenderingStyle) – the style to render docstrings (Default value = RenderingStyle.COMPACT)
indent (str) – the characters used as indentation in the docstring string (Default value = ‘ ‘)

Returns:

docstring text

Return type:

str

pymend.docstring_parser.rest.parse(text: str | None) → Docstring[source]

Parse the ReST-style docstring into its components.

Parameters:: text (Optional[str]) – docstring to parse
Returns:: parsed docstring
Return type:: Docstring
Raises:: ParseError – If a section does not have two colons to be split on.

pymend.docstring_parser.rest.process_desc(desc: str | None, rendering_style: RenderingStyle, indent: str = ' ') → str[source]

Process the description for one element.

Parameters:

desc (Optional[str]) – Description to process
rendering_style (RenderingStyle) – Rendering style to use.
indent (str) – Indentation needed for that line (Default value = ‘ ‘)

Returns:

String representation of the docstrings description.

Return type:

str

pymend.docstring_parser.util module

Utility functions for working with docstrings.

pymend.docstring_parser.util.combine_docstrings(*others: Callable[[...], object], exclude: Iterable[type[DocstringMeta]] = (), style: DocstringStyle = DocstringStyle.AUTO, rendering_style: RenderingStyle = RenderingStyle.COMPACT) → Callable[[...], object][source]

Combine docstrings of multiple functions.

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.

Parameters:

*others (_Func) – callables from which to parse docstrings.
exclude (Iterable[type[DocstringMeta]]) – an iterable of DocstringMeta subclasses to exclude when combining docstrings. (Default value = ())
style (DocstringStyle) – Style that the docstrings are currently in. Default will infer style. (Default value = DocstringStyle.AUTO)
rendering_style (RenderingStyle) – Rendering style to use. (Default value = RenderingStyle.COMPACT)

Returns:

the decorated function with a modified docstring.

Return type:

_Func

Examples

>>> 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

long_description: fun2

: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

long_description: fun2

:param a: fun1
:param b: fun1
:param c: fun2
:param e: fun2

Module contents

Parse docstrings as per Sphinx notation.

class pymend.docstring_parser.Docstring(style: DocstringStyle | None = None, section_titles: KeyReturnDict[str, str] | None = None)[source]

Bases: object

Docstring object representation.

property deprecation: DocstringDeprecated | None

Return a single information on function deprecation notes.

Returns:: single information on function deprecation notes.
Return type:: Optional[DocstringDeprecated]

property examples: list[DocstringExample]

Return a list of information on function examples.

Returns:: list of information on function examples.
Return type:: list[DocstringExample]

property many_returns: list[DocstringReturns]

Return a list of information on function return.

Returns:: list of information on function return.
Return type:: list[DocstringReturns]

property many_yields: list[DocstringYields]

Return a list of information on function yields.

Returns:: list of information on function yields.
Return type:: list[DocstringYields]

property params: list[DocstringParam]

Return a list of information on function params.

Returns:: list of information on function params
Return type:: list[DocstringParam]

property raises: list[DocstringRaises]

Return a list of the exceptions that the function may raise.

Returns:: list of the exceptions that the function may raise.
Return type:: list[DocstringRaises]

property returns: DocstringReturns | None

Return a single information on function return.

Takes the first return information.

Returns:: Single information on function return.
Return type:: Optional[DocstringReturns]

property yields: DocstringYields | None

Return information on function yield.

Takes the first generator information.

Returns:: Single information on function yield.
Return type:: Optional[DocstringYields]

class pymend.docstring_parser.DocstringDeprecated(args: list[str], description: str | None, version: str | None)[source]

Bases: DocstringMeta

DocstringMeta symbolizing deprecation metadata.

args: list[str]

description: str | None

version: str | None

class pymend.docstring_parser.DocstringExample(args: list[str], description: str | None, snippet: str | None)[source]

Bases: DocstringMeta

DocstringMeta symbolizing example metadata.

args: list[str]

description: str | None

snippet: str | None

class pymend.docstring_parser.DocstringMeta(args: list[str], description: str | None)[source]

Bases: object

Docstring meta information.

Symbolizes lines in form of

Parameters:

args (List[str]) – list of arguments. The exact content of this variable is dependent on the kind of docstring; it’s used to distinguish between custom docstring meta information items.
description (Optional[str]) – associated docstring description.

args: list[str]

description: str | None

class pymend.docstring_parser.DocstringParam(args: list[str], description: str | None, arg_name: str, type_name: str | None, is_optional: bool | None, default: str | None)[source]

Bases: DocstringMeta

DocstringMeta symbolizing :param metadata.

arg_name: str

args: list[str]

default: str | None

description: str | None

is_optional: bool | None

type_name: str | None

class pymend.docstring_parser.DocstringRaises(args: list[str], description: str | None, type_name: str | None)[source]

Bases: DocstringMeta

DocstringMeta symbolizing :raises metadata.

args: list[str]

description: str | None

type_name: str | None

class pymend.docstring_parser.DocstringReturns(args: list[str], description: str | None, type_name: str | None, is_generator: bool, return_name: str | None = None)[source]

Bases: DocstringMeta

DocstringMeta symbolizing :returns metadata.

args: list[str]

description: str | None

is_generator: bool

return_name: str | None = None

type_name: str | None

class pymend.docstring_parser.DocstringStyle(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: Enum

Docstring style.

AUTO = 255

EPYDOC = 4

GOOGLE = 2

NUMPYDOC = 3

REST = 1

class pymend.docstring_parser.DocstringYields(args: list[str], description: str | None, type_name: str | None, is_generator: bool, yield_name: str | None = None)[source]

Bases: DocstringMeta

DocstringMeta symbolizing :yields metadata.

args: list[str]

description: str | None

is_generator: bool

type_name: str | None

yield_name: str | None = None

exception pymend.docstring_parser.ParseError[source]

Bases: RuntimeError

Base class for all parsing related errors.

class pymend.docstring_parser.RenderingStyle(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: Enum

Rendering style when unparsing parsed docstrings.

CLEAN = 2

COMPACT = 1

EXPANDED = 3

pymend.docstring_parser.Style: alias of DocstringStyle

pymend.docstring_parser.combine_docstrings(*others: Callable[[...], object], exclude: Iterable[type[DocstringMeta]] = (), style: DocstringStyle = DocstringStyle.AUTO, rendering_style: RenderingStyle = RenderingStyle.COMPACT) → Callable[[...], object][source]

Combine docstrings of multiple functions.

Parameters:

*others (_Func) – callables from which to parse docstrings.
exclude (Iterable[type[DocstringMeta]]) – an iterable of DocstringMeta subclasses to exclude when combining docstrings. (Default value = ())
style (DocstringStyle) – Style that the docstrings are currently in. Default will infer style. (Default value = DocstringStyle.AUTO)
rendering_style (RenderingStyle) – Rendering style to use. (Default value = RenderingStyle.COMPACT)

Returns:

the decorated function with a modified docstring.

Return type:

_Func

Examples

>>> 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

long_description: fun2

: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

long_description: fun2

:param a: fun1
:param b: fun1
:param c: fun2
:param e: fun2

pymend.docstring_parser.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 (Default value = DocstringStyle.AUTO)
indent (str) – the characters used as indentation in the docstring string (Default value = ‘ ‘)
rendering_style (RenderingStyle) – The rendering style to use. (Default value = RenderingStyle.COMPACT)

Returns:

docstring text

Return type:

str

Raises:

ValueError – If no output style could be determined.

pymend.docstring_parser.parse(text: str | None, style: DocstringStyle = DocstringStyle.AUTO) → Docstring[source]

Parse the docstring into its components.

Parameters:

text (Optional[str]) – docstring text to parse
style (DocstringStyle) – docstring style (Default value = DocstringStyle.AUTO)

Returns:

parsed docstring representation

Return type:

Docstring

Raises:

ParserError – If none of the available module an parse the docstring