manuel 1.0.0a8

Parsing

Manuel operates on Documents. Each Document is created from a string containing one or more lines.

>>> source = """\
... This is our document, it has several lines.
... one: 1, 2, 3
... two: 4, 5, 7
... three: 3, 5, 1
... """
>>> document = manuel.Document(source)

For example purposes we will create a type of test that consists of a sequence of numbers so lets create a NumbersTest object to represent the parsed list.

>>> class NumbersTest(object):
...     def __init__(self, description, numbers):
...         self.description = description
...         self.numbers = numbers

The Document is divided into one or more regions. Each region is a distinct “chunk” of the document and will be acted uppon in later (post-parsing) phases. Initially the Document is made up of a single element, the source string.

>>> [region.source for region in document]
['This is our document, it has several lines.\none: 1, 2, 3\ntwo: 4, 5, 7\nthree: 3, 5, 1\n']

The Document offers a “find_regions” method to assist in locating the portions of the document a particular parser is interested in. Given a regular expression (either as a string, or compiled), it will return “region” objects that contain the matched source text, the line number (1 based) the region begins at, as well as the associated re.Match object.

>>> import re
>>> numbers_test_finder = re.compile(
...     r'^(?P<description>.*?): (?P<numbers>(\d+,?[ ]?)+)$', re.MULTILINE)
>>> regions = document.find_regions(numbers_test_finder)
>>> regions
[<manuel.Region object at 0x...>,
 <manuel.Region object at 0x...>,
 <manuel.Region object at 0x...>]
>>> regions[0].lineno
2
>>> regions[0].source
'one: 1, 2, 3\n'
>>> regions[0].start_match.group('description')
'one'
>>> regions[0].start_match.group('numbers')
'1, 2, 3'

If given two regular expressions find_regions will use the first to identify the begining of a region and the second to identify the end.

>>> region = document.find_regions(
...     re.compile('^one:.*$', re.MULTILINE),
...     re.compile('^three:.*$', re.MULTILINE),
...     )[0]
>>> region.lineno
2
>>> print region.source
one: 1, 2, 3
two: 4, 5, 7
three: 3, 5, 1

Also, instead of just a “start_match” attribute, the region will have start_match and end_match attributes.

>>> region.start_match
<_sre.SRE_Match object at 0x...>
>>> region.end_match
<_sre.SRE_Match object at 0x...>

Regions must always consist of whole lines.

>>> document.find_regions('1, 2, 3')
Traceback (most recent call last):
    ...
ValueError: Regions must start at the begining of a line.

>>> document.find_regions('three')
Traceback (most recent call last):
    ...
ValueError: Regions must end at the ending of a line.

>>> document.find_regions(
...     re.compile('ne:.*$', re.MULTILINE),
...     re.compile('^one:.*$', re.MULTILINE),
...     )
Traceback (most recent call last):
    ...
ValueError: Regions must start at the begining of a line.

>>> document.find_regions(
...     re.compile('^one:.*$', re.MULTILINE),
...     re.compile('^three:', re.MULTILINE),
...     )
Traceback (most recent call last):
    ...
ValueError: Regions must end at the ending of a line.

Now we can register a parser that will identify the regions we’re interested in and create NumbersTest objects from the source text.

>>> def parse(document):
...     for region in document.find_regions(numbers_test_finder):
...         description = region.start_match.group('description')
...         numbers = map(
...             int, region.start_match.group('numbers').split(','))
...         test = NumbersTest(description, numbers)
...         document.replace_region(region, test)

>>> parse(document)
>>> [region.source for region in document]
['This is our document, it has several lines.\n',
 'one: 1, 2, 3\n',
 'two: 4, 5, 7\n',
 'three: 3, 5, 1\n']
>>> [region.parsed for region in document]
[None,
 <NumbersTest object at 0x...>,
 <NumbersTest object at 0x...>,
 <NumbersTest object at 0x...>]

Evaluation

After a document has been parsed the resulting tests are evaluated. Unlike parsing and formatting, evaluation is done one region at a time, in the order that the regions appear in the document. Manuel provides another method to evaluate tests. Lets define a function to evaluate NumberTests. The function determines whether or not the numbers are in sorted order and records the result along with the description of the list of numbers.

>>> class NumbersResult(object):
...     def __init__(self, test, passed):
...         self.test = test
...         self.passed = passed

>>> def evaluate(region, document, globs):
...     if not isinstance(region.parsed, NumbersTest):
...         return
...     test = region.parsed
...     passed = sorted(test.numbers) == test.numbers
...     region.evaluated = NumbersResult(test, passed)

>>> for region in document:
...     evaluate(region, document, {})
>>> [region.evaluated for region in document]
[None,
 <NumbersResult object at 0x...>,
 <NumbersResult object at 0x...>,
 <NumbersResult object at 0x...>]

Formatting

Once the evaluation phase is completed the results are formatted. You guessed it: manuel provides a method for formatting results. We’ll build one to format a message about whether or not our lists of numbers are sorted properly. A formatting function returns None when it has no output, or a string otherwise.

>>> def format(document):
...     for region in document:
...         if not isinstance(region.evaluated, NumbersResult):
...             continue
...         result = region.evaluated
...         if not result.passed:
...             region.formatted = (
...                 "the numbers aren't in sorted order: "
...                 + ', '.join(map(str, result.test.numbers)))

Since our test case passed we don’t get anything out of the report function.

>>> format(document)
>>> [region.formatted for region in document]
[None, None, None, "the numbers aren't in sorted order: 3, 5, 1"]

Manuel Objects

We’ll want to use these parse, evaluate, and format functions later, so we bundle them together into a Manuel object.

>>> sorted_numbers_manuel = manuel.Manuel(
...     parsers=[parse], evaluaters=[evaluate], formatters=[format])

Globals

Even though each region is parsed into its own object, state is still shared between them. Each region of the document is executed in order so state changes made by earlier evaluaters are available to the current evaluator.

>>> document = manuel.Document("""
...     >>> x = 1
...
... A little prose to separate the examples.
...
...     >>> x
...     1
... """)
>>> document.process_with(m, globs={})
>>> print document.formatted()

Imported modules are added to the global namespace as well.

>>> document = manuel.Document("""
...     >>> import string
...
... A little prose to separate the examples.
...
...     >>> string.digits
...     '0123456789'
...
... """)
>>> document.process_with(m, globs={})
>>> print document.formatted()

1.0.0a8 (2009-05-01)

• add a larger example of using Manuel (table-example.txt)

• make the test suite factory function try harder to find the calling module

• fix a bug in the order regions are evaluated

• add a Manuel object that can evaluate Python code in “.. code-block:: python” regions of a reST document

1.0.0a4 (2009-05-01)

• make the global state (“globs”) shared between all evaluators, not just doctest

1.0.0a3 (2009-05-01)

• make zope.testing’s testrunner recognized the enhanced, doctest-style errors generated by Manuel

• rework the evaluaters to work region-by-region instead of on the entire document

• switch to using regular Python classes for Manuel objects instead of previous prototype-y style

1.0.0a2 (2008-10-17)

• first public release