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_docutils.is_allowed_version(version, spec)

Check spec satisfies version or not. This obeys PEP-440 specifiers: :rtype: bool

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

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

Return type:

List[Node]

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

Bases: TestDirective

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

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

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.MockTabDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

Bases: TestDirective

run()

Parse a mock-tabs directive.

Return type:

List[Node]

doctest_docutils.setup()

Return type:

Dict[str, Any]

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

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.

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

_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

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

Return a DocTest for the given string, if it defines a docstring; otherwise, return None.

Return type:

DocTest

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

Changes from standard library at 3.10 :rtype: int

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