API Reference

Decorator

class doctestcase(globals=None, options=0, **kwargs)[source]

Class decorator that turns on evaluation of docstring doctests in subclasses of unittest.TestCase.

Parameters:

  • globals (dict | None, optional) – dictionary of globals passed to the doctest; defaults to None (no additional globals).

  • options (int, optional) – doctest options, passed to doctest.DocTestRunner; defaults to 0 (no options).

  • kwargs (dict, optional) – additional keyword arguments that will be stored under __doctestcase__.kwargs and can be used in setUp(), tearDown(), and custom test methods of TestCase.

globals

gobals passed to decorator.

Type:

dict

options

options passed to decorator.

Type:

int

kwargs

**kwargs passed to decorator.

Type:

dict

The decorator object, after being applied to the decorated class, stores its copy under attribute __doctestcase__, including options and shallow copies of original globals and kwargs.

New test method test_docstring, implementing docstring evaluation, is added to the decorated class. If the decorated class has no docstring or the docstring is blank, test_docstring does nothing.

The decorated class, as a subclass of unittest.TestCase, can define setUp(), tearDown, and its own test methods (exept test_docstring) that are executed before or after the docstring.

If decorated class already has __doctestcase__ attribute (obtained from decoration or inherited from parent classes), it is replaced with a copy; globals and kwargs are updated with values from the decorator, and options is OR’ed with decorator’s options. This allows to extend test cases with multiple decoration and inheritance. This also ensures that __doctestcase__ attributes of subsequent classes are independent, but values of globals and kwargs dictionaries reference the same objects.

The doctestcase object, after being applied to TestCase class, can be further reused to decorate other TestCase classes. The same is true for __doctestcase__ attribute.

When TestCase is inherited, the inherited class must be decorated with doctestcase again.

Example

from doctest import ELLIPSIS
from unittest import TestCase

from doctestcase import doctestcase


@doctestcase(globals={'X': 'yz'}, options=ELLIPSIS)
class SimpleCase(TestCase):
    """
    Title

    Paragraph.

    >>> X * 100
    'yzyz...'

    Another paragraph.

    >>> None
    >>> True
    True
    """

See also

Use cases documentation section contains more examples and use cases.

Formatting

to_markdown(item, title_depth=2, dedent=True, include_title=True)[source]

Convert docstring to Markdown.

The first block of non-blank lines up to first blank line represents test case title. It is joined in one line and formatted as section heading.

Every doctest block is formatted as code block.

Parameters:

  • item (object | str | None) – input to be converted. If item is str, it will be used as input, otherwise item.__doc__ will be used. If input is blank or None, empty string is returned.

  • title_depth (int | None, optional) – heading level for test case title; defaults to 2. If None, title is not matched and becomes a part of the body text.

  • dedent (bool, optional) – textwrap.dedent is applied to the docstring by default; this can be turned off by passing dedent=False.

  • include_title (bool, optional) – whether to include docstring title in the output; defaults to True.

Returns:

Markdown formatted text; may be empty.

Return type:

str

Example

For SimpleCase from doctestcase example,

>>> from doctestcase import to_markdown
>>> to_markdown(SimpleCase)

## Title

Paragraph.

```pycon
>>> X * 100
'yzyz...'
```

Another paragraph.

```pycon
>>> None
>>> True
True
```
to_rest(item, title_char='-', dedent=True, include_title=True)[source]

Convert docstring to reStructuredText.

The first block of non-blank lines up to first blank line represents test case title. It is joined in one line and formatted as section heading.

Every doctest block is formatted as code block.

Parameters:

  • item (object | str | None) – input to be converted. If item is str, it will be used as input, otherwise item.__doc__ will be used. If input is blank or None, empty string is returned.

  • title_char (str | None, optional) – heading underline character for test case title; defaults to '-'. If None, title is not matched and becomes a part of the body text.

  • dedent (bool, optional) – textwrap.dedent is applied to the docstring by default; this can be turned off by passing dedent=False.

  • include_title (bool) – whether to include docstring title in the output; defaults to True.

Returns:

reST formatted text; may be empty.

Return type:

str

Example

For SimpleCase from doctestcase example,

>>> from doctestcase import to_rest
>>> to_rest(SimpleCase)

Title
-----

Paragraph.

>>> X * 100
'yzyz...'

Another paragraph.

>>> None
>>> True
True

Docstring components

get_title(item)[source]

Get title component of the docstring.

Title is the first block of non-blank lines up to the first blank line. Title lines, if multiple, are joined.

Parameters:

item (object | str | None) – input to be converted. If item is str, it will be used as input, otherwise item.__doc__ will be used. If input is blank or None, empty string is returned.

Returns:

may be empty string.

Return type:

str

get_body(item, remove_title=True, dedent=True)[source]

Get body component of the docstring.

Body is the rest of the text after removing title, and, if not empty, always ends with newline.

Parameters:

  • item (object | str | None) – input to be converted. If item is str, it will be used as input, otherwise item.__doc__ will be used. If input is blank or None, empty string is returned.

  • remove_title (bool, optional) – whether to remove title; defaults to True.

  • dedent (bool, optional) – whether to apply textwrap.dedent first; defaults to True.

Returns:

may be empty string.

Return type:

str