Concepts

The following concepts are one’s you’ll encounter when using Sybil or writing parsers for it:

Sybil

As well as being the name of the project, this is an object that contains configuration of parsers and provides test runner integration for discovering examples in documents and evaluating them in the document’s namespace.

Its API is defined by sybil.Sybil.

See Usage and Test runner integration for more information.

Sybil Collection

When more than one set of configuration is required, Sybils can be combined using the addition operator to form a single object with a test runner integration.

The API is defined by sybil.sybil.SybilCollection and sybil.Sybil.__add__.

See Patterns of Use.

Document

An object representing a file in the project containing examples that need to be evaluated.

Its API is defined by sybil.Document.

See Usage for more information.

Region

An object representing a region in a document containing exactly one example that needs to be evaluated.

Within a single Sybil, no region may overlap with another. This is to ensure that examples can be executed in a consistent order, and also helps to highlight parsing errors, which often result in overlapping regions.

The API is defined by sybil.Region.

See Usage and Developing your own parsers for more information.

Test Runner

Sybil works by integrating with the test runner used by your project. This is done by using the appropriate integration method on the Sybil or Sybil Collection.

See test runner integration for more information.

Lexer

Different documentation and source formats often result in the same type of examples. However, they have their own concepts such as directives in ReST and fenced code blocks in Markdown.

A lexer is a callable that takes a document and yields a sequence of regions that do not have the parsed or evaluator attributes set.

These allow parsers and evaluators to have simpler implementations that are common across different source formats and can make life easier when writing new parsers for an existing source format.

Its API is defined by sybil.typing.Lexer.

See Developing your own parsers for more information.

Parser

A callable that takes a document and yields a sequence of regions. Parsers may user lexers to turn text in specific text formats into abstract primitives such as blocks.

Its API is defined by sybil.typing.Parser.

See Usage and Developing your own parsers for more information.

Example

An objecting representing an example in a document. It collects information from both the document and the region and knows how to evaluate itself using any applicable evaluators from either the region or document it came from.

Its API is defined by sybil.example.Example.

See Usage and Developing your own parsers for more information.

Namespace

This is a dict in which all examples in a document will be evaluated. Namespaces are not shared between documents.

For python or doctest evaluation, this is used for globals, and for other evaluators it can be used to store state or provide named objects for use in the evaluation of other examples.

Its API is defined by sybil.Document.namespace

See Usage and Developing your own parsers for more information.

Evaluator

A callable that takes an example and can raise an Exception or return a str to indicate that the example was not successfully evaluated.

It will often use or modify the namespace.

Its API is defined by sybil.typing.Evaluator.

See Usage and Developing your own parsers for more information.