Hide navigation sidebar
Hide table of contents sidebar
Skip to content
Back to top
View this page
Toggle table of contents sidebar

# 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.