xdoctest.docstr package

Submodules

• xdoctest.docstr.docscrape_google module
  • DocBlock
    • DocBlock.offset
    • DocBlock.text
  • split_google_docblocks()
  • parse_google_args()
  • parse_google_returns()
  • parse_google_retblock()
  • parse_google_argblock()
• xdoctest.docstr.docscrape_numpy module

Module contents

xdoctest.docstr.parse_google_argblock(lines, clean_desc=True)

Parse out individual items from google-style args blocks.

Parameters:

• lines (str) – the unindented lines from an Args docstring section

• clean_desc (bool) – if True, will strip the description of newlines and indents. Defaults to True.

Yields:

Dict[str, str | None] – A dictionary containing keys, “name”, “type”, and “desc” corresponding to an argument in the Args block.

Example

>>> # Test various ways that arglines can be written
>>> line_list = [
...     '',
...     'foo1 (int): a description',
...     'foo2: a description\n    with a newline',
...     'foo3 (int or str): a description',
...     'foo4 (int or threading.Thread): a description',
...     #
...     # this is sphynx-like typing style
...     'param1 (:obj:`str`, optional): ',
...     'param2 (:obj:`list` of :obj:`str`):',
...     #
...     # the Type[type] syntax is defined by the python typeing module
...     'attr1 (Optional[int]): Description of `attr1`.',
...     'attr2 (List[str]): Description of `attr2`.',
...     'attr3 (Dict[str, str]): Description of `attr3`.',
...     '*args : variable positional args description',
...     '**kwargs : keyword arguments description',
...     'malformed and unparseable',
...     'param_no_desc1',  # todo: this should be parseable
...     'param_no_desc2:',
...     'param_no_desc3 ()',  # todo: this should be parseable
...     'param_no_desc4 ():',
...     'param_no_desc5 (str)',  # todo: this should be parseable
...     'param_no_desc6 (str):',
... ]
>>> lines = '\n'.join(line_list)
>>> argdict_list = list(parse_google_argblock(lines))
>>> # All lines except the first should be accepted
>>> assert len(argdict_list) == len(line_list) - 5
>>> assert argdict_list[1]['desc'] == 'a description with a newline'

xdoctest.docstr.parse_google_args(docstr)

Generates dictionaries of argument hints based on a google docstring

Parameters:

docstr (str) – a google-style docstring

Yields:

Dict[str, str] – dictionaries of parameter hints

Example

>>> docstr = parse_google_args.__doc__
>>> argdict_list = list(parse_google_args(docstr))
>>> print([sorted(d.items()) for d in argdict_list])
[[('desc', 'a google-style docstring'), ('name', 'docstr'), ('type', 'str')]]

xdoctest.docstr.parse_google_retblock(lines, return_annot=None)

Parse information out of a returns or yeilds block.

A returns or yeids block should be formatted as one or more '{type}:{description}' strings. The description can occupy multiple lines, but the indentation should increase.

Parameters:

• lines (str) – unindented lines from a Returns or Yields section

• return_annot (str | None) – the return type annotation (if one exists)

Yields:

Dict[str, str] – each dict specifies the return type and its description

Example

>>> # Test various ways that retlines can be written
>>> assert len(list(parse_google_retblock('list: a desc'))) == 1
>>> # ---
>>> hints = list(parse_google_retblock('\n'.join([
...     'entire line can be desc',
...     ' ',
...     ' if a return type annotation is given',
... ]), return_annot='int'))
>>> assert len(hints) == 1
>>> # ---
>>> hints = list(parse_google_retblock('\n'.join([
...     'bool: a description',
...     ' with a newline',
... ])))
>>> assert len(hints) == 1
>>> # ---
>>> hints = list(parse_google_retblock('\n'.join([
...     'int or bool: a description',
...     ' ',
...     ' with a separated newline',
...     ' ',
... ])))
>>> assert len(hints) == 1
>>> # ---
>>> hints = list(parse_google_retblock('\n'.join([
...     # Multiple types can be specified
...     'threading.Thread: a description',
...     '(int, str): a tuple of int and str',
...     'tuple: a tuple of int and str',
...     'Tuple[int, str]: a tuple of int and str',
... ])))
>>> assert len(hints) == 4
>>> # ---
>>> # If the colon is not specified nothing will be parsed
>>> # according to the "official" spec, but lets try and do it anyway
>>> hints = list(parse_google_retblock('\n'.join([
...     'list',
...     'Tuple[int, str]',
... ])))
>>> assert len(hints) == 2
>>> assert len(list(parse_google_retblock('no type, just desc'))) == 1
...

xdoctest.docstr.parse_google_returns(docstr, return_annot=None)

Generates dictionaries of possible return hints based on a google docstring

Parameters:

• docstr (str) – a google-style docstring

• return_annot (str | None) – the return type annotation (if one exists)

Yields:

Dict[str, str] – dictionaries of return value hints

Example

>>> docstr = parse_google_returns.__doc__
>>> retdict_list = list(parse_google_returns(docstr))
>>> print([sorted(d.items()) for d in retdict_list])
[[('desc', 'dictionaries of return value hints'), ('type', 'Dict[str, str]')]]

Example

>>> docstr = split_google_docblocks.__doc__
>>> retdict_list = list(parse_google_returns(docstr))
>>> print([sorted(d.items())[1] for d in retdict_list])
[('type', 'List[Tuple[str, DocBlock]]')]

xdoctest.docstr.split_google_docblocks(docstr)

Breaks a docstring into parts defined by google style

Parameters:

docstr (str) – a docstring

Returns:

list of 2-tuples where the first item is a google style docstring tag and the second item is the bock corresponding to that tag. The block itself is a 2-tuple where the first item is the unindented text and the second item is the line offset indicating that blocks location in the docstring.

Return type:

List[Tuple[str, DocBlock]]

Note

Unknown or “freeform” sections are given a generic “__DOC__” tag. A section tag may be specified multiple times.

CommandLine

xdoctest xdoctest.docstr.docscrape_google split_google_docblocks:2

Example

>>> from xdoctest.docstr.docscrape_google import *  # NOQA
>>> from xdoctest import utils
>>> docstr = utils.codeblock(
...     '''
...     one line description
...
...     multiline
...     description
...
...     Args:
...         foo: bar
...
...     Returns:
...         None
...
...     Example:
...         >>> print('eg1')
...         eg1
...
...     Example:
...         >>> print('eg2')
...         eg2
...     ''')
>>> groups = split_google_docblocks(docstr)
>>> assert len(groups) == 5
>>> [g[0] for g in groups]
['__DOC__', 'Args', 'Returns', 'Example', 'Example']

Example

>>> from xdoctest.docstr.docscrape_google import *  # NOQA
>>> docstr = split_google_docblocks.__doc__
>>> groups = split_google_docblocks(docstr)

Example

>>> from xdoctest.docstr.docscrape_google import *  # NOQA
>>> from xdoctest import utils
>>> docstr = utils.codeblock(
...     '''
...      a description with a leading space
...
...     Example:
...         >>> foobar
...     ''')
>>> groups = split_google_docblocks(docstr)
>>> print('groups = {!r}'.format(groups))

Example

>>> from xdoctest.docstr.docscrape_google import *  # NOQA
>>> from xdoctest import utils
>>> docstr = utils.codeblock(
...     '''
...     Example:
...         >>> foobar
...     ''')
>>> # Check that line offsets are valid if the first line is not blank
>>> groups = split_google_docblocks(docstr)
>>> offset = groups[0][1][1]
>>> print('offset = {!r}'.format(offset))
>>> assert offset == 0
>>> # Check that line offsets are valid if the first line is blank
>>> groups = split_google_docblocks(chr(10) + docstr)
>>> offset = groups[0][1][1]
>>> print('offset = {!r}'.format(offset))
>>> assert offset == 1