alternative

alternative is a tiny, 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.

A First Example

import alternative


@alternative.reference
def total(values: list[int]) -> int:
    result = 0
    for value in values:
        result += value
    return result


@total.add(default=True)
def total_builtin(values: list[int]) -> int:
    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.

Contents

Indices