Skip to main content

Exhaustively enumerate a combinatorial space represented by a function

Project description


A Python library to exhaustively enumerate a combinatorial space represented by a function.

The API is modelled after Python's random module and should feel familiar. An additional convenience function maybe() was added to cover a common case.

If you're missing a function and the corresponding space can be enumerated feel free to open an issue. Any functions that generate real-valued distributions cannot be supported.


import exhaust

def generate_character(state: exhaust.State):
    eyes = []
    for _ in range(state.randint(1, 3)):
            'color': state.choice(['brown', 'blue']),
            'glowing': state.maybe()
    size = 'giant' if len(eyes) == 1 else 'normal'
    accessories = []
    if len(eyes) == 2:
        if state.maybe():
        if state.maybe():
    character = {
        'size': size,
        'eyes': eyes,
        'accessories': accessories
    return character

# iterates over a space of 132 characters
for character in

As you can see, navigating the space works fine within loops as well. Each time a function from the State object is called (like maybe()), you can think of it as forking the current path into multiple branches, leading to a tree that gets explored. While exploring, the user-defined function is called for each path of the tree.

See the examples/ folder for further examples that can be run on the command line.

See the API Documentation for all available State functions.


pip install exhaust


Requires pip >= 21.3

Editable install:

pip install -e .

Run tests:

pip install -r requirements-test.txt

Build docs:

pip install -r requirements-docs.txt
sphinx-build -b html docs dist-docs

Build wheel:

pip install build
python -m build --wheel


This package is inspired by KerasTuner's method of defining hyperparameter search spaces.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

No source distribution files available for this release.See tutorial on generating distribution archives.

Built Distribution

exhaust-1.1.0-py3-none-any.whl (5.0 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page