An Optimization Workflow

This complete example keeps a reference, candidates, startup imports, correctness tests, and benchmarks in separate files. Its contract is to sum an iterable of integers, including empty inputs and large integers, without changing its items.

After Quickstart, use this layout when implementations and tests need separate modules. Create an optimise_totals/ directory containing the four files below. You can also copy the example directory from the source repository. Each file is shown below, so a repository checkout is optional.

optimise_totals/
    __init__.py
    reference.py
    candidates.py
    test_totals.py

Reference and Candidate

reference.py contains the implementation that remains the correctness oracle:

"""Keep a straightforward implementation as a correctness oracle."""

from collections.abc import Iterable

import alternative


@alternative.reference
def total(values: Iterable[int]) -> int:
    """Sum integers, including empty inputs and arbitrarily large values."""
    result = 0
    for value in values:
        result += value
    return result

candidates.py registers the rewrite and selects it as the default:

"""Select a candidate while registration is still open."""

from collections.abc import Iterable

from .reference import total


@total.add(default=True)
def total_builtin(values: Iterable[int]) -> int:
    """Use Python's integer sum with the same public contract."""
    return sum(values)

Choose default=True after testing representative inputs and reviewing the benchmark results for your environment. It is shown here to demonstrate the final configuration, rather than assert a universal speed advantage for every input.

Startup Imports

The package’s __init__.py imports candidates before exposing the entry point:

"""Import all candidates before exposing the callable to application code."""

from .candidates import total_builtin as total_builtin
from .reference import total as total

Application code can now use from optimise_totals import total. Importing the package registers the candidates; import alone does not freeze registration. Applying a pytest helper or calling total freezes the set, so all candidate imports must happen first. Adding an implementation after either operation raises alternative.AddTooLateError. Reading .callable or .implementations and calling .measure() also freeze registration.

Test the Contract and Measure the Result

test_totals.py checks independent expected results as well as equivalence. Separate benchmark tests measure algorithms and the production entry point:

"""Execute the tutorial's correctness, equivalence, and timing examples."""

import pytest

from . import total

CASES = [
    ((), 0),
    ((1,), 1),
    ((1, -2, 3), 2),
    ((2, 2, 2), 6),
    ((2**100, 1, -(2**100)), 1),
]


@total.pytest_parametrize()
@pytest.mark.parametrize(("values", "expected"), CASES)
def test_expected_totals(
    implementation, values: tuple[int, ...], expected: int
) -> None:
    """Every implementation satisfies independent expected results."""
    assert implementation(values) == expected


@total.pytest_parametrize_pairs()
@pytest.mark.parametrize(("values", "expected"), CASES)
def test_equivalent_totals(
    reference, implementation, values: tuple[int, ...], expected: int
) -> None:
    """Each candidate matches the reference on the same reusable inputs."""
    assert reference(values) == implementation(values) == expected


@total.pytest_parametrize()
def test_algorithm_benchmark(benchmark, implementation) -> None:
    """Time underlying algorithms without the production dispatch wrapper."""
    values = tuple(range(1_000))
    assert benchmark(implementation, values) == 499_500


def test_production_benchmark(benchmark) -> None:
    """Include default dispatch when measuring the production entry point."""
    values = tuple(range(1_000))
    assert benchmark(total, values) == 499_500

From the directory containing optimise_totals/, install the library and test tools, then run the tests:

$ pip install alternative pytest pytest-benchmark
$ pytest optimise_totals

To promote a different candidate, move default=True to its registration in source and rerun a fresh process. Collection and measurement already freeze the current registry; they do not change its default. See Performance and When to Use It for dispatch costs and Testing Observable Behavior for mutations and errors.