Low-level tools

Building blocks for custom generators that need finer control over how the engine draws, and so how it shrinks, than composite() and the standard generators give. Most tests never need them.

class hegel.Collection

A low-level helper for custom collection generators: the engine decides how many elements to draw, within [min_size, max_size] (max_size=None for no fixed limit), so the shrinker can remove elements cleanly. Call more() before drawing each element:

collection = hegel.Collection(tc, min_size, max_size)
result = []
while collection.more():
    result.append(tc.draw_silent(elements))
more() → bool

Whether to draw another element.

reject(why: str | None = None) → None

Discard the element just drawn (a duplicate, say) so it does not count toward the size.

hegel.generators.weighted_booleans(p: float) → Generator[bool]

Generate True with probability p, and False otherwise, shrinking toward False. p outside [0, 1] is an InvalidArgument.

TestCase.draw_and_print(generator: Generator[T], printer: PrettyPrinter) → T

Draw a value, printing its representation through printer. This is how a printable generator’s do_draw_and_print draws its components, so they print as part of its own value: generator must be printable, or this raises NotPrintable. When the enclosing generator is itself being drawn silently, so is generator.

TestCase.start_span(label: int) → None

Open a span labelled label grouping the draws until the matching stop_span(). Spans tell the shrinker which choices belong together; draw() and draw_silent() open one per draw, so only a low-level custom generator needs this. Nesting so deep that Python’s recursion limit (sys.getrecursionlimit()) is in sight abandons the test case as too large, rather than failing it with a RecursionError.

TestCase.stop_span(discard: bool = False) → None

Close the span opened by the matching start_span(). With discard=True the shrinker treats the span’s draws as thrown away (a filtered-out attempt, say).