Quickstart
This guide assumes you know Python decorators and basic pytest tests. It uses a name-formatting function to show the full cycle: register a candidate, check its contract, benchmark it, and select the default used by application code.
Install the library and test tools:
$ pip install alternative pytest pytest-benchmark
Register Implementations
Save the following in test_names.py. Use alternative.reference() on the
implementation you trust most, then register a candidate with .add:
import alternative
import pytest
@alternative.reference
def normalise_name(name: str) -> str:
"""Collapse whitespace and capitalize each word."""
return " ".join(part.capitalize() for part in name.split())
@normalise_name.add
def normalise_name_mapped(name: str) -> str:
"""Apply the same word transformation with map."""
return " ".join(map(str.capitalize, name.split()))
normalise_name is an alternative.Alternatives object. Calling it
uses the reference unless you select another default. normalise_name_mapped
is an alternative.Implementation object; calling it always runs that
candidate directly. Both retain their Python call signatures.
Test the Contract
Add expected results to check every implementation, including the reference. Then compare candidates against the reference on the same inputs:
CASES = [
("", ""),
(" ada lovelace ", "Ada Lovelace"),
("o'neill", "O'neill"),
("élise müller", "Élise Müller"),
]
@normalise_name.pytest_parametrize()
@pytest.mark.parametrize(("value", "expected"), CASES)
def test_expected_names(implementation, value, expected):
"""Check independent expected results for every implementation."""
assert implementation(value) == expected
@normalise_name.pytest_parametrize_pairs()
@pytest.mark.parametrize(("value", "expected"), CASES)
def test_equivalent_names(reference, implementation, value, expected):
"""Compare each candidate with the reference."""
assert implementation(value) == reference(value)
The helpers supply the callable parameters named implementation and
reference. You do not need to define fixtures with these names. Run the tests:
$ pytest test_names.py
The contract here includes whitespace normalization and apostrophe handling.
Using name.title() would change those rules. Agreement with the reference
also needs independent expected results: two implementations can share a bug.
Benchmark Representative Inputs
Add a benchmark using the benchmark fixture from pytest-benchmark:
@normalise_name.pytest_parametrize()
def test_name_benchmark(benchmark, implementation):
"""Time each algorithm on the same name."""
assert benchmark(implementation, " ada lovelace ") == "Ada Lovelace"
Run pytest test_names.py again to see timing results for both implementations.
Try inputs representative of your application before deciding that a candidate
is faster. The helper times underlying implementations; also time the decorated
entry point to account for dispatch cost, as shown in An Optimization Workflow and
Performance and When to Use It.
Choose a Default
After reviewing correctness and timing results, edit the candidate’s decorator
in test_names.py to @normalise_name.add(default=True) and run a fresh
process. Calls such as normalise_name("ada lovelace") will then use that
candidate. Direct calls to normalise_name_mapped still use the candidate.
Only one explicit default can be registered, including an explicitly selected reference. The library does not choose the fastest implementation automatically.
Register all candidates before applying test decorators, calling the alternatives
object, reading .callable or .implementations, or calling .measure().
Each operation freezes registration. Choosing the default is a source change
made before those operations in the next run, rather than an update to the
already tested alternatives object.
Use Methods
The same workflow supports instance, class, and static methods. See Methods and Descriptors for decorator order, receiver binding, and imported static candidates.
Next Steps
See An Optimization Workflow to split this workflow across application and test files. Use Pytest Integration for helper options and Testing Observable Behavior for mutation and errors. Runtime Workflow covers direct-call registration, chained registration, and runtime inspection.