Doctest w/ docutils#
Built on doctest
.
Note
Before you begin, acquaint yourself with:
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:
-
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)[source]#
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)[source]#
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?
- class doctest_docutils.TestsetupDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)[source]#
Bases:
TestDirective
- class doctest_docutils.TestcleanupDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)[source]#
Bases:
TestDirective
- 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.
-
option_spec:
- class doctest_docutils.MockTabDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)[source]#
Bases:
TestDirective
- 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.
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)[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 {}.
- 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