Writing your own generators¶
map, filter and builds cover a lot of ground, but some data is easier to
describe as a sequence of draws, each one depending on the ones before. The
@hegel.composite decorator turns a function that
draws values into a generator.
Composite generators¶
A composite function takes a test case as its first argument, draws whatever it needs from it, and returns the value to generate:
import hegel
from hegel import generators as gs
@hegel.composite
def people(tc):
age = tc.draw(gs.integers(min_value=0, max_value=120))
name = tc.draw(gs.text(min_size=1))
return {"name": name, "age": age}
@hegel.test
def test_people(tc):
person = tc.draw(people())
assert person["age"] < 100
Calling people() returns a generator, which the test draws from like any
other. When the test fails, Hegel shrinks the person as a whole and reports the
value the composite returned:
E assert 100 < 100
E person = {'name': '0', 'age': 100}
The draws inside the composite are not reported separately, only its result.
Any arguments after the test case become arguments of the generator, so a composite can be parameterised:
@hegel.composite
def people(tc, max_age=120):
age = tc.draw(gs.integers(min_value=0, max_value=max_age))
name = tc.draw(gs.text(min_size=1))
return {"name": name, "age": age}
children = people(max_age=17)
Dependent draws¶
Because the body of a composite is ordinary Python, later draws can depend on earlier ones. Here only adults may have a driving licence:
@hegel.composite
def drivers(tc):
age = tc.draw(gs.integers(min_value=0, max_value=120))
licensed = tc.draw(gs.booleans()) if age >= 18 else False
return {"age": age, "licensed": licensed}
And here the second value is always at least the first:
@hegel.composite
def ordered_pairs(tc):
low = tc.draw(gs.integers())
high = tc.draw(gs.integers(min_value=low))
return (low, high)
Generating values that satisfy a constraint by construction, like this, is much better than generating any pair and filtering out the ones in the wrong order: no work is wasted, and the values shrink well.
A composite can also call assume() to discard a test case,
just as a test can.
Recursive data¶
Trees, nested lists, JSON documents and other recursive data need a generator
that refers to itself. recursive() takes a generator
for the leaves and a function that, given a generator for sub-values, returns a
generator for one level of structure:
json = gs.recursive(
gs.none() | gs.booleans() | gs.floats(allow_nan=False) | gs.text(),
lambda children: gs.lists(children) | gs.dicts(gs.text(), children),
max_leaves=50,
)
max_leaves bounds the size of each value, so drawing one always terminates.
For data that is more naturally written as mutually recursive definitions, use
deferred(), which delays building a generator until it
is first drawn from, so it can refer to generators defined after it:
trees = gs.deferred(lambda: gs.just("leaf") | gs.tuples(trees, trees))
A deferred generator has no size limit of its own, so give it base cases that
are common enough for its values to stay small, as just("leaf") is here.
Making from_type know your types¶
register_type_generator() tells
from_type() (and the argument inference of
builds()) which generator to use for a type:
class Temperature(float):
pass
gs.register_type_generator(Temperature, gs.floats(-273.15, 1000).map(Temperature))
Generator subclasses¶
The generators on this page cover almost every need. For the rare case they
don’t, generators are subclasses of Generator. A
subclass implements do_draw_and_print, which draws the value and prints it
in the failure report as it goes, drawing its components with
tc.draw_and_print:
class Coords(gs.Generator[tuple[int, int]]):
def do_draw_and_print(self, tc, printer):
with printer.group("Coord(", ")"):
x = tc.draw_and_print(gs.integers(0, 9), printer)
printer.separator()
y = tc.draw_and_print(gs.integers(0, 9), printer)
return (x, y)
A failing test that draws one reports it as coords = Coord(0, 0).
Printing values explains how printing works, and
Generators describes the interface.