Using generators

A generator describes the values a test can draw: which values are possible, and how they shrink. Hegel provides generators for the built-in types and many standard-library ones, and ways to combine them into generators for your own data. They all live in hegel.generators, which this documentation always imports as gs:

from hegel import generators as gs

This page tours the most common ones. Generators lists every generator and all of its arguments.

Primitive values

@hegel.test
def test_primitives(tc):
    n = tc.draw(gs.integers(min_value=0))
    x = tc.draw(gs.floats(allow_nan=False))
    flag = tc.draw(gs.booleans())
    s = tc.draw(gs.text())
    b = tc.draw(gs.binary(max_size=10))

Most generators take arguments that narrow what they produce. Integers can be bounded on either side or both, floats can exclude NaN and the infinities, and text can be limited to an alphabet or to some Unicode categories:

digits = gs.text(alphabet="0123456789", min_size=1)
letters = gs.text(categories=["Lu", "Ll"])
probability = gs.floats(min_value=0.0, max_value=1.0)

There are also generators for dates and times, in the gs.temporal namespace (gs.temporal.dates, gs.temporal.datetimes, gs.temporal.durations, …), UUIDs, IP addresses, email addresses, URLs and domain names, strings matching a regular expression (from_regex()), and strings of a grammar written in Lark’s syntax (from_lark()).

Collections

Collection generators take a generator for their elements:

@hegel.test
def test_collections(tc):
    xs = tc.draw(gs.lists(gs.integers(), max_size=10))
    unique = tc.draw(gs.lists(gs.integers(), unique=True))
    tags = tc.draw(gs.sets(gs.text(min_size=1)))
    ages = tc.draw(gs.dicts(gs.text(), gs.integers(min_value=0)))
    point = tc.draw(gs.tuples(gs.floats(), gs.floats()))

fixed_dicts() generates dictionaries with a known set of keys, each with its own generator, and is a good fit for JSON-like records:

user = gs.fixed_dicts(
    {"name": gs.text(min_size=1), "age": gs.integers(0, 120)},
    optional={"email": gs.emails()},
)

Choosing between values

sampled_from() picks one of a fixed collection of values, or one member of an Enum. just() always produces the same value, and none() always produces None:

colour = gs.sampled_from(["red", "green", "blue"])

one_of(), or the | operator, draws from one of several generators. optional() is shorthand for a generator or None:

number = gs.integers() | gs.floats()
maybe_name = gs.optional(gs.text())

Transforming generators

Every generator has three methods that build new generators from it.

map() transforms each value:

even = gs.integers().map(lambda n: n * 2)

filter() keeps only the values satisfying a condition:

odd = gs.integers().filter(lambda n: n % 2 == 1)

A filter that rejects most values makes the test slow, because Hegel has to throw away and redraw what it generates. Prefer map, or an argument of the generator, when one expresses the same thing: `gs.integers().map(lambda n: 2 * n

  • 1)` generates odd numbers without ever rejecting one.

flat_map() draws a value and then uses it to choose the next generator:

@hegel.test
def test_flat_map(tc):
    xs = tc.draw(
        gs.integers(min_value=1, max_value=10).flat_map(
            lambda n: gs.lists(gs.integers(), min_size=n, max_size=n)
        )
    )
    assert 1 <= len(xs) <= 10

In a Hegel test you rarely need flat_map: drawing one value and then drawing from a generator built with it, as in Your first test, does the same thing and is easier to read.

Generating your own types

builds() calls a class or function with arguments drawn from generators. Required arguments you don’t give a generator for are inferred from their type annotations; arguments with defaults keep them:

from dataclasses import dataclass


@dataclass
class Point:
    x: float
    y: float
    label: str = ""


points = gs.builds(Point, x=gs.floats(-1, 1))

from_type() goes further and builds a generator from a type alone, covering built-in and standard-library types, typing constructs such as list[int] and int | None, enums, dataclasses and annotated classes:

points = gs.from_type(Point)
pairs = gs.from_type(tuple[int, list[str]])

When your types need more control than builds gives, write a generator with @hegel.composite, the subject of the next page.