Performance and When to Use It

Use alternative to keep a trusted reference, test candidate implementations consistently, and choose a default without changing application callers. Each call through the alternatives object adds some dispatch work. Include that cost when deciding whether a candidate improves performance.

A Rough Overhead Budget

Functions doing tens of microseconds or more of work per call are a useful starting point: dispatch is usually a small part of their total time. For functions taking only a few microseconds, compare the full application call before adopting a rewrite. The savings may be smaller than the added dispatch.

The following rounded costs illustrate the scale, based on warmed calls to a trivial integer function in one CPython run:

Approximate added cost per call

Application call pattern

Added cost

Work per call for roughly 5% overhead

Function, or a bound method saved before a loop

0.4 microseconds

10 microseconds

Method looked up on the instance for every call

2–3 microseconds

50 microseconds

These are planning estimates, not guarantees for another interpreter, machine, or workload. The example measurements include the environment and raw timings. They exclude registration and first-use setup. Measure startup separately if it matters to your application.

For a 5% overhead budget, aim for the implementation’s own work to take at least 20 times the extra call cost. For a speed improvement, the candidate’s time plus dispatch must be less than the original call’s time. For example, reducing 50 microseconds of work to 40 microseconds leaves room for 0.4 microseconds of dispatch. Reducing 1 microsecond to 0.8 microseconds does not.

The registration and test helpers can still be useful for comparing very small functions. Choose the production call path separately if every fraction of a microsecond matters.

Benchmark Your Application

Use realistic inputs and benchmark both the underlying implementations and the public decorated callable. The pytest helpers supply underlying implementations, so their timings compare algorithms. A separate benchmark of the decorated entry point includes dispatch and shows what application callers experience. See An Optimization Workflow for both tests in a runnable example.

For repeated method calls, save call = instance.method before the loop and invoke call(...) inside it to avoid repeated lookup. For a module function, call = function.callable gives direct access to the selected implementation. Read it after registering all candidates: doing so freezes registration and keeps that selection stable. For methods, save the bound method so Python still supplies the receiver normally.

alternative.Alternatives.measure() scores returned results, such as compressed output sizes. Use a timing tool such as pytest-benchmark to measure elapsed time.

Measure Dispatch in Your Environment

The source checkout includes a small dispatch benchmark. With alternative installed in your Python environment, run:

$ python scripts/benchmark_call_overhead.py --number 100000 --repeat 7

Add --json for environment details and minimum and median nanoseconds per call. The script times the same integer increment through ordinary and decorated call paths, with registration and first-use setup completed before timing. It measures saved bound methods separately from method lookup on every call. These small-call measurements help estimate overhead; application benchmarks determine whether the library fits your workload.