API reference

Doctest module for docutils.

doctest_docutils.is_allowed_version(version, spec)

function

function

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

Parameters:

• version (str)

• spec (str)

Return type:

bool

class doctest_docutils.TestDirective

class

class

class doctest_docutils.TestDirective

Bases: Directive

Base class for doctest-related directives.

has_content = True

attribute

attribute

has_content = True

May the directive have content?

required_arguments = 0

attribute

attribute

required_arguments = 0

Number of required directive arguments.

optional_arguments = 1

attribute

attribute

optional_arguments = 1

Number of optional arguments after the required arguments.

final_argument_whitespace = True

attribute

attribute

final_argument_whitespace = True

May the final argument contain whitespace?

get_source_info()

method

method

get_source_info()

Get source and line number.

Return type:

tuple[str, int]

set_source_info(node)

method

method

set_source_info(node)

Set source and line number to the node.

Parameters:

node (Node)

Return type:

None

run()

method

method

run()

Run docutils test directive.

Return type:

list[Node]

class doctest_docutils.TestsetupDirective

class

class

class doctest_docutils.TestsetupDirective

Bases: TestDirective

Test setup directive.

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

attribute

attribute

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

Mapping of option names to validator functions.

class doctest_docutils.TestcleanupDirective

class

class

class doctest_docutils.TestcleanupDirective

Bases: TestDirective

Test cleanup directive.

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

attribute

attribute

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

Mapping of option names to validator functions.

class doctest_docutils.DoctestDirective

class

class

class doctest_docutils.DoctestDirective

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

attribute

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

Mapping of option names to validator functions.

class doctest_docutils.MockTabDirective

class

class

class doctest_docutils.MockTabDirective

Bases: TestDirective

Mock tab directive.

run()

method

method

run()

Parse a mock-tabs directive.

Return type:

list[Node]

doctest_docutils.setup()

function

function

doctest_docutils.setup()

Configure doctest for doctest_docutils.

Return type:

dict[str, Any]

doctest_docutils._directive_registry()

function

function

doctest_docutils._directive_registry()

Return docutils directive registry with typing info.

Return type:

dict[str, Any]

doctest_docutils._ensure_directives_registered()

function

function

doctest_docutils._ensure_directives_registered()

Register doctest-related directives once per interpreter.

Return type:

None

exception doctest_docutils.DocTestFinderNameDoesNotExist

exception

exception

exception doctest_docutils.DocTestFinderNameDoesNotExist

Bases: ValueError

Raised with doctest lookup name not provided.

__init__(string)

method

method

__init__(string)

Parameters:

string (str)

Return type:

None

class doctest_docutils.DocutilsDocTestFinder

class

class

class doctest_docutils.DocutilsDocTestFinder

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=parser)

method

method

__init__(verbose=False, parser=parser)

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

method

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

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

method

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

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

method

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

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

exception

exception doctest_docutils.TestDocutilsPackageRelativeError

Bases: Exception

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

__init__()

method

method

__init__()

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=parser, encoding=None)

function

function

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=parser, encoding=None)

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

function

doctest_docutils._test()

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