Doctest w/ docutils

Built on doctest.

Note

Before you begin, acquaint yourself with:

• doctest

  • normal usage via:

    $ python -m doctest [file]
    

• Know what docutils does: parses reStructuredText (.rst). With the helper of [myst-parser], it also parses markdown (.md)

reStructuredText

$ python -m doctest_docutils README.rst

That’s what doctest does by design. Pass -v for verbose output.

Markdown

If you install [myst-parser], doctest will run on .md files.

$ python -m doctest_docutils README.md

As with the reST example above, no output.

Internals

Note

To get a deeper understanding, dig into:

• doctest

  • All console arguments by seeing the help command:

    $ python -m doctest --help
    

  • data structures, e.g. doctest.DocTest

    • source code: https://github.com/python/cpython/blob/3.11/Lib/doctest.py

    • documentation: https://docs.python.org/3/library/doctest.html

  • typings: https://github.com/python/typeshed/blob/master/stdlib/doctest.pyi

• docutils: which parses reStructuredText (.rst) and markdown (.md, with the help of [myst-parser])

API

Doctest module for docutils.

doctest_docutils.is_allowed_version(version, spec)

Check spec satisfies version or not.

This obeys PEP-440 specifiers: https://peps.python.org/pep-0440/#version-specifiers

Some examples:

>>> is_allowed_version('3.3', '<=3.5')
True
>>> is_allowed_version('3.3', '<=3.2')
False
:rtype: :sphinx_autodoc_typehints_type:`\:py\:class\:\`bool\``

>>> is_allowed_version('3.3', '>3.2, <4.0')
True

class doctest_docutils.TestDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

Bases: Directive

Base class for doctest-related directives.

has_content = True

May the directive have content?

required_arguments = 0

Number of required directive arguments.

optional_arguments = 1

Number of optional arguments after the required arguments.

final_argument_whitespace = True

May the final argument contain whitespace?

get_source_info()

Get source and line number.

Return type:

Tuple[str, int]

set_source_info(node)

Set source and line number to the node.

Return type:

None

run()

Run docutils test directive.

Return type:

List[Node]

class doctest_docutils.TestsetupDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

Bases: TestDirective

Test setup directive.

option_spec: ClassVar[Dict[str, Callable[[str], Any]]] = {'skipif': <function unchanged_required>}

Mapping of option names to validator functions.

class doctest_docutils.TestcleanupDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

Bases: TestDirective

Test cleanup directive.

option_spec: ClassVar[Dict[str, Callable[[str], Any]]] = {'skipif': <function unchanged_required>}

Mapping of option names to validator functions.

class doctest_docutils.DoctestDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

Bases: TestDirective

Doctest directive.

option_spec: ClassVar[Dict[str, Callable[[str], Any]]] = {'hide': <function flag>, 'no-trim-doctest-flags': <function flag>, 'options': <function unchanged>, 'pyversion': <function unchanged_required>, 'skipif': <function unchanged_required>, 'trim-doctest-flags': <function flag>}

Mapping of option names to validator functions.

class doctest_docutils.MockTabDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

Bases: TestDirective

Mock tab directive.

run()

Parse a mock-tabs directive.

Return type:

List[Node]

doctest_docutils.setup()

Configure doctest for doctest_docutils.

Return type:

Dict[str, Any]

exception doctest_docutils.DocTestFinderNameDoesNotExist(string)

Bases: ValueError

Raised with doctest lookup name not provided.

class doctest_docutils.DocutilsDocTestFinder(verbose=False, parser=<doctest.DocTestParser object>)

Bases: object

DocTestFinder for doctest-docutils.

Class used to extract the DocTests relevant to a docutils file. Doctests are extracted from the following directive types: doctest_block (doctest), DocTestDirective. Myst-parser is also supported for parsing markdown files.

Create a new doctest finder.

The optional argument parser specifies a class or function that should be used to create new DocTest objects (or objects that implement the same interface as DocTest). The signature for this factory function should match the signature of the DocTest constructor.

find(string, name=None, globs=None, extraglobs=None)

Return list of the DocTests defined by given string (its parsed directives).

The globals for each DocTest is formed by combining globs and extraglobs (bindings in extraglobs override bindings in globs). A new copy of the globals dictionary is created for each DocTest. If globs is not specified, then it defaults to the module’s __dict__, if specified, or {} otherwise. If extraglobs is not specified, then it defaults to {}.

Return type:

List[DocTest]

_find(tests, string, name, source_lines, globs, seen, source_path=None)

Find tests for the given string, and add them to tests.

Return type:

None

_from_module(module, object)

Return true if the given object lives in the given module.

cached_property objects are never considered a part of the ‘current module’. As such they are skipped by doctest. Here we override _from_module to check the underlying function instead. https://github.com/python/cpython/issues/107995.

Return type:

bool

_get_test(string, name, filename, globs, source_lines)

Return a DocTest for given string, or return None.

Return type:

DocTest

exception doctest_docutils.TestDocutilsPackageRelativeError

Bases: Exception

Raise when doctest_docutils is called for package not relative to module.

doctest_docutils.testdocutils(filename, module_relative=True, name=None, package=None, globs=None, verbose=None, report=True, optionflags=0, extraglobs=None, raise_on_error=False, parser=<doctest.DocTestParser object>, encoding=None)

Docutils-based test entrypoint.

Based on doctest.testfile at python 3.10

Return type:

TestResults

doctest_docutils._test()

Execute doctest module via CLI.

Port changes from standard library at 3.10: :rtype: int

• Sets up logging.basicLogging(level=logging.DEBUG) w/ args.verbose