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#

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

Bases: TestDirective

option_spec: 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.DocutilsDocTestFinder(verbose=False, parser=<doctest.DocTestParser object>)[source]#

Bases: object

A class used to extract the DocTests that are relevant to a given docutils file. Doctests can be extracted from the followwing directive types: doctest_block (doctest), DocTestDirective. Myst-parser is also supported for parsing markdown files.

find(string, name=None, globs=None, extraglobs=None)[source]#

Return a list of the DocTests that are defined by the 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]

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

Bases: Directive

Base class for doctest-related directives.

final_argument_whitespace = True#

May the final argument contain whitespace?

get_source_info()[source]#

Get source and line number.

Return type:

Tuple[str, int]

has_content = True#

May the directive have content?

optional_arguments = 1#

Number of optional arguments after the required arguments.

required_arguments = 0#

Number of required directive arguments.

run()[source]#
Return type:

List[Node]

set_source_info(node)[source]#

Set source and line number to the node.

Return type:

None

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

Bases: TestDirective

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

Mapping of option names to validator functions.

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

Bases: TestDirective

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

Mapping of option names to validator functions.

doctest_docutils.is_allowed_version(version, spec)[source]#

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
>>> is_allowed_version('3.3', '>3.2, <4.0')
True
Return type:

bool

doctest_docutils.setup()[source]#
Return type:

Dict[str, Any]

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)[source]#

Docutils-based test entrypoint.

Based on doctest.testfile at python 3.10

Return type:

TestResults