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.