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.