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.