# API Reference

class `sybil.``Sybil`(parsers, pattern='', path='.', setup=None, teardown=None, fixtures=(), filenames=(), excludes=())

  An object to provide test runner integration for discovering examples in documentation and ensuring they are correct.

  Parameters:

  - parsers – A sequence of callables. See Parsers.
  - path –

    The path in which documentation source files are found, relative to the path of the Python source file in which this class is instantiated.

    Note

    This is ignored when using the pytest integration.

  - pattern – An optional `pattern` used to match documentation source files that will be parsed for examples.
  - filenames – An optional `set` of source file names that will be parsed for examples.
  - excludes – An optional sequence of `patterns` of source file names that will excluded when looking for examples.
  - setup – An optional callable that will be called once before any examples from a `Document` are evaluated. If provided, it is called with the document’s `namespace`.
  - teardown – An optional callable that will be called after all the examples from a `Document` have been evaluated. If provided, it is called with the document’s `namespace`.
  - 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 `namespace`. All scopes of fixture are supported.

  `pytest`()

    The helper method for when you use pytest.

  `unittest`()

    The helper method for when you use either unittest or nose.

  `nose`()

    The helper method for when you use either unittest or nose.

class `sybil.``Region`(start, end, parsed, evaluator)

  Parsers should yield instances of this class for each example they discover in a documentation source file.

  Parameters:

  - start – The character position at which the example starts in the `Document`.
  - end – The character position at which the example ends in the `Document`.
  - parsed – The parsed version of the example.
  - evaluator – The callable to use to evaluate this example and check if it is as it should be.

class `sybil.document.``Document`(text, path)

  This is Sybil’s representation of a documentation source file. It will be instantiated by Sybil and provided to each parser in turn.

  `evaluator` = None

    This can be set by evaluators to 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 `Document` or calling the original evaluator on the example. This last case should always take the form of `example.region.evaluator(example)`.

  `text` = None

    This is the text of the documentation source file.

  `path` = None

    This is the absolute path of the documentation source file.

  `namespace` = None

    This dictionary is the namespace in which all example parsed from this document will be evaluated.

  classmethod `parse`(path, *parsers)

    Read the text from the supplied path and parse it into a document using the supplied parsers.

  `line_column`(position)

    Return a line and column location in this document based on a byte position.

  `find_region_sources`(start_pattern, end_pattern)

    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_pattern` in the document’s `text` that is followed by an occurrence of `end_pattern`. The matches will be provided as match objects, while the source is provided as a string.

exception `sybil.example.``SybilFailure`(example, result)

class `sybil.example.``Example`(document, line, column, region, namespace)

  This represents a particular example from a documentation source file. It is assembled from the `Document` and `Region` the example comes from and is passed to the region’s evaluator.

  `document` = None

    The `Document` from which this example came.

  `path` = None

    The absolute path of the `Document`.

  `line` = None

    The line number at which this example occurs in the `Document`.

  `column` = None

    The column number at which this example occurs in the `Document`.

  `region` = None

    The `Region` from which this example came.

  `start` = None

    The character position at which this example starts in the `Document`.

  `end` = None

    The character position at which this example ends in the `Document`.

  `parsed` = None

    The version of this example provided by the parser that yielded the `Region` containing it.

  `namespace` = None

    The `namespace` of the document from which this example came.

`sybil.parsers.doctest.``FIX_BYTE_UNICODE_REPR` = 2048

  A doctest option flag that causes byte and unicode literals in doctest expected output to be rewritten such that they are compatible with the version of Python with which the tests are executed.

class `sybil.parsers.doctest.``DocTest`(examples, globs, name, filename, lineno, docstring)

class `sybil.parsers.doctest.``DocTestRunner`(optionflags=0)

class `sybil.parsers.doctest.``DocTestParser`(optionflags=0)

  A class to instantiate and include when your documentation makes use of doctest examples.

  Parameters: | optionflags – doctest option flags to use when evaluating the examples found by this parser.

class `sybil.parsers.codeblock.``CodeBlockParser`(future_imports=())

  A class to instantiate and include when your documentation makes use of codeblock examples.

  Parameters: | 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.

class `sybil.parsers.capture.``DocumentReverseIterator`(document)

`sybil.parsers.capture.``parse_captures`(document)

  A parser function to be included when your documentation makes use of capture examples.

`sybil.parsers.skip.``skip`(document)

  A parser function to be included when your documentation makes use of skipping examples in a document.