Doctest w/ docutils

Built on doctest.

pytest plugin

Run doctests in .rst and .md files via pytest.

pytest plugin

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)

function

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

Parameters:

• version (str)

• spec (str)

Return type:

bool

class doctest_docutils.TestDirective

class

Bases: Directive

Base class for doctest-related directives.

has_content = True

attribute

May the directive have content?

required_arguments = 0

attribute

Number of required directive arguments.

optional_arguments = 1

attribute

Number of optional arguments after the required arguments.

final_argument_whitespace = True

attribute

May the final argument contain whitespace?

get_source_info()

method

Get source and line number.

Return type:

tuple[str, int]

set_source_info(node)

method

Set source and line number to the node.

Parameters:

node (Node)

Return type:

None

run()

method

Run docutils test directive.

Return type:

list[Node]

class doctest_docutils.TestsetupDirective

class

Bases: TestDirective

Test setup directive.

option_spec: ClassVar = {'skipif': <function unchanged_required>}

attribute

Mapping of option names to validator functions.

class doctest_docutils.TestcleanupDirective

class

Bases: TestDirective

Test cleanup directive.

option_spec: ClassVar = {'skipif': <function unchanged_required>}

attribute

Mapping of option names to validator functions.

class doctest_docutils.DoctestDirective

class

Bases: TestDirective

Doctest directive.

option_spec: ClassVar = {'no-trim-doctest-flags': <function flag>, 'options': <function unchanged>, 'pyversion': <function unchanged_required>, 'skipif': <function unchanged_required>, 'trim-doctest-flags': <function flag>}

attribute

Mapping of option names to validator functions.

class doctest_docutils.MockTabDirective

class

Bases: TestDirective

Mock tab directive.

run()

method

Parse a mock-tabs directive.

Return type:

list[Node]

doctest_docutils.setup()

function

Configure doctest for doctest_docutils.

Return type:

dict[str, Any]

doctest_docutils._directive_registry()

function

Return docutils directive registry with typing info.

Return type:

dict[str, Any]

doctest_docutils._ensure_directives_registered()

function

Register doctest-related directives once per interpreter.

Return type:

None

exception doctest_docutils.DocTestFinderNameDoesNotExist

exception

Bases: ValueError

Raised with doctest lookup name not provided.

__init__(string)

method

Parameters:

string (str)

Return type:

None

class doctest_docutils.DocutilsDocTestFinder

class

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.

__init__(verbose=False, parser=<doctest.DocTestParser object>)

method

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.

Parameters:

• verbose (bool)

• parser (DocTestParser)

Return type:

None

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

method

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 {}.

Parameters:

• string (str)

• name (str | None)

• globs (dict[str, Any] | None)

• extraglobs (dict[str, Any] | None)

Return type:

list[DocTest]

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

method

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

Parameters:

• tests (list[DocTest])

• string (str)

• name (str)

• source_lines (list[str] | None)

• globs (dict[str, Any])

• seen (dict[int, int])

• source_path (Path | None)

Return type:

None

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

method

Return a DocTest for given string, or return None.

Parameters:

• string (str)

• name (str)

• filename (str)

• globs (dict[str, Any])

• source_lines (list[str])

Return type:

DocTest

exception doctest_docutils.TestDocutilsPackageRelativeError

exception

Bases: Exception

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

__init__()

method

Return type:

None

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)

function

Docutils-based test entrypoint.

Based on doctest.testfile at python 3.10

Parameters:

• filename (str)

• module_relative (bool)

• name (str | None)

• package (str | ModuleType | None)

• globs (dict[str, Any] | None)

• verbose (bool | None)

• report (bool)

• optionflags (int)

• extraglobs (dict[str, Any] | None)

• raise_on_error (bool)

• parser (DocTestParser)

• encoding (str | None)

Return type:

TestResults

doctest_docutils._test()

function

Execute doctest module via CLI.

Port changes from standard library at 3.10:

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

Return type:

int