- class sybil.Sybil(parsers: Sequence[Callable[[Document], Iterable[Region]]], pattern: str = None, patterns: Sequence[str] = (), exclude: str = None, excludes: Sequence[str] = (), filenames: Collection[str] = (), path: str = '.', setup: Callable[[dict], None] = None, teardown: Callable[[dict], None] = None, fixtures: Sequence[str] = (), encoding: str = 'utf-8', document_types: Mapping[Optional[str], Type[sybil.document.Document]] = None)#
An object to provide test runner integration for discovering examples in documentation and ensuring they are correct.
parsers – A sequence of callables. See Parsers.
The path in which source files are found, relative to the path of the Python source file in which this class is instantiated. Absolute paths can also be passed.
This is ignored when using the pytest integration.
pattern – An optional
patternused to match source files that will be parsed for examples.
patterns – An optional sequence of
patternsused to match source paths that will be parsed for examples.
exclude – An optional
patternsfor source file names that will excluded when looking for examples.
excludes – An optional sequence of
patternsfor source paths that will be excluded when looking for examples.
filenames – An optional collection of file names that, if found anywhere within the root
pathor its sub-directories, will be parsed for examples.
setup – An optional callable that will be called once before any examples from a
Documentare evaluated. If provided, it is called with the document’s
teardown – An optional callable that will be called after all the examples from a
Documenthave been evaluated. If provided, it is called with the document’s
fixtures – An optional sequence of strings specifying the names of fixtures to be requested when using the pytest integration. The fixtures will be inserted into the document’s
namespacebefore any examples for that document are evaluated. All scopes of fixture are supported.
encoding – An optional string specifying the encoding to be used when decoding documentation source files.
document_types – A mapping of file extension to
Documentsubclass such that custom evaluation can be performed per document type.
- class sybil.Region(start: int, end: int, parsed: sybil.typing.Parsed, evaluator: Callable[[Example], Optional[str]])#
Parsers should yield instances of this class for each example they discover in a documentation source file.
- class sybil.Example(document: Document, line: int, column: int, region: sybil.region.Region, namespace: dict)#
- parsed: sybil.typing.Parsed#
The version of this example provided by the parser that yielded the
- class sybil.Document(text: str, path: str)#
This is Sybil’s representation of a documentation source file. It will be instantiated by Sybil and provided to each parser in turn.
- evaluator: Callable[[sybil.example.Example], Optional[str]] = None#
This can be set by evaluators or
subclassesto affect the evaluation of future examples. It can be set to a callable that takes an
Example. This callable can then do whatever it needs to do, including not executing the example at all, modifying it, or the
Documentor calling the original evaluator on the example. This last case should always take the form of
- namespace: dict#
This dictionary is the namespace in which all examples parsed from this document will be evaluated.
- classmethod parse(path: str, *parsers: Callable[[sybil.document.Document], Iterable[sybil.region.Region]], encoding: str = 'utf-8') sybil.document.Document #
Read the text from the supplied path and parse it into a document using the supplied parsers.
- line_column(position: int) str #
Return a line and column location in this document based on a byte position.
- find_region_sources(start_pattern: Pattern[str], end_pattern: Pattern[str]) Tuple[Match, Match, str] #
This helper method can be called used to extract source text for regions based on the two regular expressions provided.
It will yield a tuple of
(start_match, end_match, source)for each occurrence of
start_patternin the document’s
textthat is followed by an occurrence of
end_pattern. The matches will be provided as match objects, while the source is provided as a string.
- class sybil.parsers.codeblock.CodeBlockParser(language: Optional[str] = None, evaluator: Optional[Callable[[sybil.example.Example], Optional[str]]] = None)#
A class to instantiate and include when your documentation makes use of codeblock examples.
language – The language that this parser should look for.
evaluator – The evaluator to use for evaluating code blocks in the specified language. You can also override the
- class sybil.parsers.codeblock.PythonCodeBlockParser(future_imports=())#
A class to instantiate and include when your documentation makes use of Python codeblock examples.
future_imports – An optional list of strings that will be turned into
from __future__ import ...statements and prepended to the code in each of the examples found by this parser.