Generators¶

Generators are the foundation of property-based testing in python-proptest. They are responsible for creating the diverse range of random (or sometimes specific) input data that is fed into your properties during testing. By defining how data should be generated – its type, constraints, and structure – generators allow python-proptest to explore the input space of your functions effectively, searching for edge cases and potential bugs that manually chosen examples might miss. Generators can range from simple primitives like booleans and numbers to complex, nested data structures built by combining other generators.

Generator Summary Table¶

Generator	Description	Key Parameters	Example Usage
Primitives
`Gen.bool()`	Generates `True` or `False` with configurable probability.	`true_prob` (def: 0.5)	`Gen.bool(true_prob=0.8)`
`Gen.float()`	Generates floating-point numbers. By default generates only finite values. Can optionally generate `inf`, `-inf`, `nan` with specified probabilities.	`min_value`, `max_value`, `nan_prob`, `posinf_prob`, `neginf_prob`	`Gen.float(min_value=0.0, max_value=1.0, nan_prob=0.01)`
`Gen.int()`	Generates integers in the range `[min_value, max_value]`.	`min_value`, `max_value`	`Gen.int(min_value=0, max_value=10)`
`Gen.str()`	Generates strings with customizable charset.	`min_length` (def: 0), `max_length` (def: 20), `charset` (def: lowercase letters)	`Gen.str(min_length=0, max_length=5, charset="abc")`
`Gen.ascii_string(...)`	Generates strings containing only ASCII chars (0-127).	`min_length` (def: 0), `max_length` (def: 10)	`Gen.ascii_string(min_length=1, max_length=8)`
`Gen.unicode_string(...)`	Generates strings containing Unicode chars.	`min_length` (def: 0), `max_length` (def: 10)	`Gen.unicode_string(min_length=1, max_length=8)`
`Gen.printable_ascii_string(...)`	Generates strings containing only printable ASCII chars.	`min_length` (def: 0), `max_length` (def: 10)	`Gen.printable_ascii_string(min_length=5, max_length=5)`
`Gen.ascii_char()`	Generates ASCII character codes (0-127).	None	`Gen.ascii_char()`
`Gen.unicode_char()`	Generates Unicode character codes (avoiding surrogate pairs).	None	`Gen.unicode_char()`
`Gen.printable_ascii_char()`	Generates printable ASCII character codes (32-126).	None	`Gen.printable_ascii_char()`
`Gen.in_range(min, max)`	Generates integers in range [min, max) (exclusive).	`min_value`, `max_value`	`Gen.in_range(0, 10)`
`Gen.interval(min, max)`	Generates integers in range [min, max] (inclusive).	`min_value`, `max_value`	`Gen.interval(0, 10)`
`Gen.integers(start, count)`	Generates integers in range [start, start+count).	`start`, `count`	`Gen.integers(0, 100)`
`Gen.natural(max)`	Generates positive integers [1, max].	`max_value`	`Gen.natural(100)`
`Gen.non_negative(max)`	Generates non-negative integers [0, max].	`max_value`	`Gen.non_negative(100)`
`Gen.unique_list(elem, ...)`	Generates lists with unique elements, sorted.	`element_gen`, `min_length` (def: 0), `max_length` (def: 10)	`Gen.unique_list(Gen.int(min_value=1, max_value=5), min_length=1, max_length=3)`
Containers
`Gen.list(elem, ...)`	Generates lists with elements from `elem`.	`element_gen`, `min_length` (def: 0), `max_length` (def: 10)	`Gen.list(Gen.bool(), min_length=2, max_length=4)`
`Gen.set(elem, ...)`	Generates `set` objects with elements from `elem`.	`element_gen`, `min_size` (def: 0), `max_size` (def: 10)	`Gen.set(Gen.int(min_value=1, max_value=3), min_size=1, max_size=3)`
`Gen.dict(key_gen, val_gen, ...)`	Generates dictionaries with keys from `key_gen` and values from `val_gen`.	`key_gen`, `value_gen`, `min_size` (def: 0), `max_size` (def: 10)	`Gen.dict(Gen.str(min_length=1, max_length=2), Gen.int(min_value=0, max_value=5), min_size=2, max_size=5)`
`Gen.tuple(...gens)`	Generates fixed-size tuples from `gens`.	`...element_gens`	`Gen.tuple(Gen.float(), Gen.str())`
Special
`Gen.just(value)`	Always generates the provided `value`.	`value`	`Gen.just(None)`
`Gen.lazy(value_factory)`	Defers execution of a function to produce `value` until needed.	`value_factory: Callable[[], T]`	`Gen.lazy(lambda: expensive_calculation())`

(Defaults for length/size are typically 0 and 10, but check implementation for specifics)

Primitive Generators¶

`Gen.int(min_value, max_value)`¶

Generates random integers within the specified range (inclusive).

Parameters: - min_value (int, optional): Minimum integer value to generate. If not specified, uses -sys.maxsize - 1 (full integer range) - max_value (int, optional): Maximum integer value to generate. If not specified, uses sys.maxsize (full integer range)

Examples:

# Generate integers from 0 to 100
Gen.int(min_value=0, max_value=100)

# Generate negative integers
Gen.int(min_value=-50, max_value=-1)

# Generate single value (when min_value == max_value)
Gen.int(min_value=42, max_value=42)

Use Cases: - Testing mathematical operations - Generating array indices - Creating test IDs or counts

`Gen.float(min_value, max_value, nan_prob, posinf_prob, neginf_prob)`¶

Generates random floating-point numbers within the specified range. By default, generates only finite values. Can optionally generate special values (NaN, +inf, -inf) with specified probabilities.

Parameters: - min_value (float, optional): Minimum float value to generate. If not specified, uses -sys.float_info.max (full finite float range) - max_value (float, optional): Maximum float value to generate. If not specified, uses sys.float_info.max (full finite float range) - nan_prob (float, default: 0.0): Probability of generating NaN. Must be between 0.0 and 1.0 - posinf_prob (float, default: 0.0): Probability of generating +inf. Must be between 0.0 and 1.0 - neginf_prob (float, default: 0.0): Probability of generating -inf. Must be between 0.0 and 1.0

Constraints: - The sum of nan_prob, posinf_prob, and neginf_prob must be <= 1.0 - The remaining probability (1.0 - sum) is used for finite values - Each probability must be between 0.0 and 1.0 (inclusive)

Examples:

# Generate finite floats only (default)
Gen.float()

# Generate floats from 0.0 to 1.0 (finite only)
Gen.float(min_value=0.0, max_value=1.0)

# Generate with 1% NaN probability, 99% finite
Gen.float(nan_prob=0.01)

# Generate with 1% each inf, 98% finite
Gen.float(posinf_prob=0.01, neginf_prob=0.01)

# Custom mix: 10% NaN, 5% each inf, 80% finite
Gen.float(nan_prob=0.1, posinf_prob=0.05, neginf_prob=0.05)

# Generate negative floats (finite only)
Gen.float(min_value=-10.0, max_value=-0.1)

# Generate very small floats with some NaN
Gen.float(min_value=0.0, max_value=0.001, nan_prob=0.05)

Use Cases: - Testing floating-point arithmetic (finite values) - Testing edge cases with NaN and infinity - Generating probabilities or percentages - Creating test measurements or coordinates - Testing error handling for special float values

Notes: - By default, generates only finite values for practical testing - Finite value generation uses bit interpretation with rejection loop, covering the full finite float space including denormals - Special values (inf, NaN) are generated explicitly when probabilities are specified, providing predictable test coverage - When using explicit min_value/max_value, finite values are generated in that range

See Also: Gen.int(), Gen.bool()

`Gen.bool(true_prob)`¶

Generates random boolean values (True or False) with configurable probability.

Parameters: - true_prob (float, default: 0.5): Probability of generating True (0.0 to 1.0)

Examples:

# Generate random booleans (50% True, 50% False)
Gen.bool()

# Generate mostly True values (80% True, 20% False)
Gen.bool(true_prob=0.8)

# Generate mostly False values (10% True, 90% False)
Gen.bool(true_prob=0.1)

# Always generate True
Gen.bool(true_prob=1.0)

# Always generate False
Gen.bool(true_prob=0.0)

# Use with other generators
Gen.tuple(Gen.bool(true_prob=0.7), Gen.int())

# Generate lists of biased booleans
Gen.list(Gen.bool(true_prob=0.3), min_length=1, max_length=5)

Use Cases: - Testing conditional logic with biased inputs - Generating feature flags with realistic distributions - Creating binary choices with weighted probabilities - Testing boolean operations with edge cases - Simulating real-world boolean distributions

See Also: Gen.just() for constant values, Gen.list() for lists of booleans

`Gen.str(min_length, max_length, charset)`¶

Generates random strings with customizable character sets.

Parameters: - min_length (int, default: 0): Minimum string length - max_length (int, default: 20): Maximum string length - charset (str or Generator[int], default: "abcdefghijklmnopqrstuvwxyz"): Character set to use. Can be: - A string of characters: "abc" generates strings using only 'a', 'b', 'c' - Special string "ascii": Uses all ASCII characters (0-127) - Special string "printable_ascii": Uses printable ASCII characters (32-126) - A codepoint generator: Gen.int(65, 90) generates strings using codepoints in range [65, 90] (A-Z)

Examples:

# Generate strings of length 5 to 10 (default: lowercase letters)
Gen.str(min_length=5, max_length=10)

# Generate single character strings
Gen.str(min_length=1, max_length=1)

# Generate empty strings (min_length=0)
Gen.str(min_length=0, max_length=0)

# Use custom character set
Gen.str(charset="abc")  # Only 'a', 'b', 'c'

# Use ASCII character set
Gen.str(charset="ascii")

# Use printable ASCII character set
Gen.str(charset="printable_ascii")

# Use codepoint generator for A-Z
Gen.str(charset=Gen.int(65, 90))  # A-Z via codepoints [65, 90]

Use Cases: - Testing string operations - Generating usernames or identifiers - Creating test data for text processing - Testing with specific character sets (e.g., only digits, only uppercase)

`Gen.ascii_string(min_length, max_length)`¶

Generates random strings containing only ASCII characters (0-127).

Parameters: - min_length (int, default: 0): Minimum string length - max_length (int, default: 20): Maximum string length

Examples:

# Generate ASCII strings of length 1 to 8
Gen.ascii_string(min_length=1, max_length=8)

# Generate fixed-length ASCII strings
Gen.ascii_string(min_length=5, max_length=5)

Use Cases: - Testing ASCII-only systems - Generating legacy-compatible strings - Creating test data for systems with ASCII restrictions

`Gen.printable_ascii_string(min_length, max_length)`¶

Generates random strings containing only printable ASCII characters (32-126).

Parameters: - min_length (int, default: 0): Minimum string length - max_length (int, default: 20): Maximum string length

Examples:

# Generate printable ASCII strings
Gen.printable_ascii_string(min_length=1, max_length=10)

# Generate fixed-length printable strings
Gen.printable_ascii_string(min_length=5, max_length=5)

Use Cases: - Testing user input validation - Generating displayable text - Creating test data for human-readable strings

`Gen.unicode_string(min_length, max_length)`¶

Generates random strings containing Unicode characters.

Parameters: - min_length (int, default: 0): Minimum string length - max_length (int, default: 20): Maximum string length

Examples:

# Generate Unicode strings
Gen.unicode_string(min_length=1, max_length=10)

# Generate short Unicode strings
Gen.unicode_string(min_length=1, max_length=3)

Use Cases: - Testing internationalization - Generating multi-language text - Creating test data for Unicode-aware systems

See Also: Gen.str(), Gen.unicode_char()

`Gen.ascii_char()`¶

Generates single ASCII character codes (0-127).

Parameters: - None

Examples:

# Generate ASCII character codes
Gen.ascii_char()

# Use with map to get actual characters
Gen.ascii_char().map(chr)

Use Cases: - Testing character processing - Generating single character inputs - Creating test data for character-based operations

`Gen.unicode_char()`¶

Generates single Unicode character codes (avoiding surrogate pairs).

Parameters: - None

Examples:

# Generate Unicode character codes
Gen.unicode_char()

# Use with map to get actual characters
Gen.unicode_char().map(chr)

Use Cases: - Testing Unicode character handling - Generating international characters - Creating test data for Unicode-aware systems

`Gen.printable_ascii_char()`¶

Generates single printable ASCII character codes (32-126).

Parameters: - None

Examples:

# Generate printable ASCII character codes
Gen.printable_ascii_char()

# Use with map to get actual characters
Gen.printable_ascii_char().map(chr)

Use Cases: - Testing printable character processing - Generating displayable characters - Creating test data for user-visible text

`Gen.in_range(min_value, max_value)`¶

Generates random integers in range [min_value, max_value) (exclusive of max_value).

Parameters: - min_value (int): Minimum integer value (inclusive) - max_value (int): Maximum integer value (exclusive)

Examples:

# Generate integers from 0 to 9 (exclusive of 10)
Gen.in_range(0, 10)

# Generate array indices
Gen.in_range(0, len(my_array))

Use Cases: - Generating array indices - Creating ranges for iteration - Testing boundary conditions

See Also: Gen.int(), Gen.interval()

`Gen.interval(min_value, max_value)`¶

Generates random integers in range [min_value, max_value] (inclusive of both bounds).

Parameters: - min_value (int): Minimum integer value (inclusive) - max_value (int): Maximum integer value (inclusive)

Examples:

# Generate integers from 0 to 10 (inclusive)
Gen.interval(0, 10)

# Generate dice rolls (1 to 6)
Gen.interval(1, 6)

Use Cases: - Testing inclusive ranges - Generating dice rolls or random selections - Creating bounded integer values

`Gen.integers(start, count)`¶

Generates integers in the range [start, start+count). The second parameter is the count of values to generate, not the maximum value.

Parameters: - start (int): Starting value (inclusive) - count (int): Number of values to generate (must be positive)

Examples:

# Generate integers from 0 to 99 (100 values)
Gen.integers(0, 100)   # generates {0, 1, ..., 99}

# Generate A-Z codepoints (26 values)
Gen.integers(65, 26)   # generates {65, 66, ..., 90} (A-Z)

# Generate integers from -10 to 10 (21 values)
Gen.integers(-10, 21)  # generates {-10, -9, ..., 10}

Use Cases: - Generating sequences with a specific count - Creating character code ranges (like A-Z) - Testing with exact number of values

`Gen.natural(max_value)`¶

Generates positive integers in range [1, max_value] (inclusive).

Parameters: - max_value (int): Maximum value (inclusive, must be at least 1)

Examples:

# Generate natural numbers from 1 to 100
Gen.natural(100)  # generates {1, 2, ..., 100}

# Generate dice rolls (1 to 6)
Gen.natural(6)    # generates {1, 2, 3, 4, 5, 6}

Use Cases: - Generating positive counts or indices - Creating dice rolls or random selections from 1 - Testing with strictly positive values

See Also: Gen.int(), Gen.non_negative()

`Gen.non_negative(max_value)`¶

Generates non-negative integers in range [0, max_value] (inclusive).

Parameters: - max_value (int): Maximum value (inclusive, must be non-negative)

Examples:

# Generate non-negative integers from 0 to 100
Gen.non_negative(100)  # generates {0, 1, 2, ..., 100}

# Generate array indices
Gen.non_negative(len(my_array) - 1)

Use Cases: - Generating array indices - Creating counts that can be zero - Testing with non-negative values

See Also: Gen.int(), Gen.natural()

Container Generators¶

`Gen.list(element_gen, min_length, max_length)`¶

Generates random lists with elements from the specified generator.

Parameters: - element_gen (Generator): Generator for list elements - min_length (int, default: 0): Minimum list length - max_length (int, default: 10): Maximum list length

Examples:

# Generate lists of 2 to 5 booleans
Gen.list(Gen.bool(), min_length=2, max_length=5)

# Generate lists of integers
Gen.list(Gen.int(min_value=1, max_value=100), min_length=0, max_length=10)

# Generate lists of strings
Gen.list(Gen.str(min_length=1, max_length=5), min_length=1, max_length=3)

Use Cases: - Testing list operations - Generating test data collections - Creating sequences for processing

`Gen.unique_list(element_gen, min_length, max_length)`¶

Generates random lists with unique elements, sorted.

Parameters: - element_gen (Generator): Generator for list elements - min_length (int, default: 0): Minimum list length - max_length (int, default: 10): Maximum list length

Examples:

# Generate unique integer lists
Gen.unique_list(Gen.int(min_value=1, max_value=10), min_length=1, max_length=5)

# Generate unique string lists
Gen.unique_list(Gen.str(min_length=1, max_length=3), min_length=2, max_length=4)

Use Cases: - Testing unique value processing - Generating sorted test data - Creating sets represented as lists

See Also: Gen.list(), Gen.set()

`Gen.set(element_gen, min_size, max_size)`¶

Generates random sets with elements from the specified generator.

Parameters: - element_gen (Generator): Generator for set elements - min_size (int, default: 0): Minimum set size - max_size (int, default: 10): Maximum set size

Examples:

# Generate sets of integers
Gen.set(Gen.int(min_value=1, max_value=10), min_size=1, max_size=5)

# Generate sets of strings
Gen.set(Gen.str(min_length=1, max_length=3), min_size=2, max_size=4)

Use Cases: - Testing set operations - Generating unique collections - Creating test data for set-based algorithms

See Also: Gen.list(), Gen.unique_list()

`Gen.dict(key_gen, value_gen, min_size, max_size)`¶

Generates random dictionaries with keys and values from specified generators.

Parameters: - key_gen (Generator): Generator for dictionary keys - value_gen (Generator): Generator for dictionary values - min_size (int, default: 0): Minimum dictionary size - max_size (int, default: 10): Maximum dictionary size

Examples:

# Generate string-to-int dictionaries
Gen.dict(Gen.str(min_length=1, max_length=3), Gen.int(), min_size=1, max_size=5)

# Generate int-to-string dictionaries
Gen.dict(Gen.int(min_value=1, max_value=10), Gen.str(min_length=1, max_length=5))

Use Cases: - Testing dictionary operations - Generating configuration data - Creating test data for key-value processing

See Also: Gen.list(), Gen.set(), Gen.tuple()

`Gen.tuple(*generators)`¶

Generates fixed-size tuples with elements from the specified generators.

Parameters: - *generators (Generator): Variable number of generators for tuple elements

Examples:

# Generate pairs of (bool, int)
Gen.tuple(Gen.bool(), Gen.int())

# Generate triples of (str, int, float)
Gen.tuple(Gen.str(), Gen.int(), Gen.float())

# Generate single-element tuples
Gen.tuple(Gen.str())

Use Cases: - Testing tuple operations - Generating coordinate pairs - Creating structured test data

Special Generators¶

`Gen.just(value)`¶

Always generates the exact value provided.

Parameters: - value (Any): The value to always generate

Examples:

# Always generate 42
Gen.just(42)

# Always generate None
Gen.just(None)

# Always generate a specific string
Gen.just("hello")

Use Cases: - Including specific edge cases - Creating constants in test data - Combining with Gen.one_of() for mixed generation

See Also: Gen.one_of(), Gen.element_of()

`Gen.lazy(func)`¶

Defers execution of a function until generation time.

Parameters: - func (Callable[[], T]): Function that returns a value when called

Examples:

# Defer expensive calculation
def expensive_calculation():
    return complex_computation()

Gen.lazy(expensive_calculation)

# Defer current time
Gen.lazy(lambda: datetime.now())

Use Cases: - Delaying expensive computations - Breaking circular dependencies - Generating time-sensitive values

See Also: Gen.construct(), recursive generation patterns in Combinators

`Gen.construct(Type, *generators)`¶

Creates instances of a class using the specified generators for constructor arguments.

Parameters: - Type (type): Class to instantiate - *generators (Generator): Generators for constructor arguments

Examples:

class Point:
    def __init__(self, x: int, y: int):
        self.x = x
        self.y = y

# Generate Point instances
Gen.construct(Point, Gen.int(), Gen.int())

class Person:
    def __init__(self, name: str, age: int):
        self.name = name
        self.age = age

# Generate Person instances
Gen.construct(Person, Gen.str(min_length=1, max_length=10), Gen.int(min_value=0, max_value=120))

Use Cases: - Testing custom classes - Generating domain objects - Creating structured test data

Dependent Generation¶

For generators where values depend on each other, python-proptest provides powerful combinators like chain, aggregate, and accumulate. These are covered in detail in the Combinators documentation under "Dependent Generation Combinators".

Quick Examples:

# Chain: Create dependent tuple (month, day)
Gen.chain(Gen.int(1, 12), lambda month: Gen.int(1, days_in_month(month)))

# Aggregate: Create list where each element depends on previous
Gen.aggregate(Gen.int(0, 10), lambda n: Gen.int(n, n + 5), min_size=3, max_size=10)

# Accumulate: Get final value after dependent steps
Gen.accumulate(Gen.int(50, 50), lambda p: Gen.int(max(0, p-10), min(100, p+10)), min_size=10)

See Also: Combinators documentation for transformation combinators (map, filter, flat_map) and Decorators documentation for using generators in tests with @for_all and @run_for_all.

Beyond the built-in generators, python-proptest provides combinators: functions that transform or combine existing generators to create new, more complex ones. This is how you build generators for your specific data types and constraints.

These combinators are essential tools for tailoring data generation precisely to your testing needs. For a comprehensive guide on how to use them, see the Combinators documentation.

Generators¶

Generator Summary Table¶

Primitive Generators¶

Gen.int(min_value, max_value)¶

Gen.float(min_value, max_value, nan_prob, posinf_prob, neginf_prob)¶

Gen.bool(true_prob)¶

Gen.str(min_length, max_length, charset)¶

Gen.ascii_string(min_length, max_length)¶

Gen.printable_ascii_string(min_length, max_length)¶

Gen.unicode_string(min_length, max_length)¶

Gen.ascii_char()¶

Gen.unicode_char()¶

Gen.printable_ascii_char()¶

Gen.in_range(min_value, max_value)¶

Gen.interval(min_value, max_value)¶

Gen.integers(start, count)¶

Gen.natural(max_value)¶

Gen.non_negative(max_value)¶

Container Generators¶

Gen.list(element_gen, min_length, max_length)¶

Gen.unique_list(element_gen, min_length, max_length)¶

Gen.set(element_gen, min_size, max_size)¶

Gen.dict(key_gen, value_gen, min_size, max_size)¶

Gen.tuple(*generators)¶

Special Generators¶

Gen.just(value)¶

Gen.lazy(func)¶

Gen.construct(Type, *generators)¶

Dependent Generation¶

`Gen.int(min_value, max_value)`¶

`Gen.float(min_value, max_value, nan_prob, posinf_prob, neginf_prob)`¶

`Gen.bool(true_prob)`¶

`Gen.str(min_length, max_length, charset)`¶

`Gen.ascii_string(min_length, max_length)`¶

`Gen.printable_ascii_string(min_length, max_length)`¶

`Gen.unicode_string(min_length, max_length)`¶

`Gen.ascii_char()`¶

`Gen.unicode_char()`¶

`Gen.printable_ascii_char()`¶

`Gen.in_range(min_value, max_value)`¶

`Gen.interval(min_value, max_value)`¶

`Gen.integers(start, count)`¶

`Gen.natural(max_value)`¶

`Gen.non_negative(max_value)`¶

`Gen.list(element_gen, min_length, max_length)`¶

`Gen.unique_list(element_gen, min_length, max_length)`¶

`Gen.set(element_gen, min_size, max_size)`¶

`Gen.dict(key_gen, value_gen, min_size, max_size)`¶

`Gen.tuple(*generators)`¶

`Gen.just(value)`¶

`Gen.lazy(func)`¶

`Gen.construct(Type, *generators)`¶