alternative
alternative is a dependency-free Python library for managing multiple
implementations of the same function.
It is designed for a common optimisation workflow:
keep a trusted reference implementation;
register faster, clearer, or more specialised candidate implementations;
run equivalence tests across every implementation;
select the implementation that normal callers should use.
The library keeps those choices explicit. The selected implementation cannot be changed after it has been used, and the implementation list cannot be extended after it has been inspected by test helpers.
Install
$ pip install alternative
alternative supports Python 3.10 and newer.
The runtime has no dependencies. Install pytest to use the test helpers
and pytest-benchmark for the benchmark fixture:
$ pip install alternative pytest pytest-benchmark
For async tests, also install pytest-asyncio or another async pytest plugin;
see Async Tests.
Decorated functions retain their typed call signatures and return types, so callers keep normal type checking and code completion while you register and select implementations. No extra typing configuration is needed.
A First Example
import alternative
@alternative.reference
def total(values: list[int]) -> int:
"""Sum integers with a straightforward reference loop."""
result = 0
for value in values:
result += value
return result
@total.add(default=True)
def total_builtin(values: list[int]) -> int:
"""Use the built-in sum with the same integer contract."""
return sum(values)
assert total([1, 2, 3]) == 6
assert total_builtin([1, 2, 3]) == 6
Calling total uses the selected default implementation. Calling
total_builtin directly still calls that implementation by itself, which is
useful in tests and benchmarks. This shows a selected default; choose it after
checking correctness and measuring representative inputs.
Start with Quickstart to add tests and benchmarks. If your implementations live in separate modules, follow An Optimization Workflow for startup imports and a complete runnable package.
Contents
Start Here