API Reference

This page documents the public API exported by alternative.

Decorator

alternative.reference(implementation=<alternative._Undefined object>, *, default=False)
Parameters:
Return type:

object

Alternatives

class alternative.Alternatives(implementation, *, default=False)
Parameters:

  • implementation (Callable[..., R] | _TypedDescriptor[P, R])

  • default (bool)

property callable: Callable[[...], R] | _TypedDescriptor[P, R]

Return the active implementation.

Setting the default implementation is disabled after this is accessed.

__call__(*args, **kwargs)

Call self as a function.

Parameters:
Return type:

R

measure(operator, *args, **kwargs)

Invoke each implementation with the given parameters, then evaluate their results with the operator.

This is useful when comparing implementations that have different results, which can be compared by some cost. For example, this can be used to compare the complexity of quantum circuits that implement the same function.

The results are sorted by the operator’s result if the result is sortable (i.e. does not raise TypeError when __lt__(a,b) is called); otherwise they are returned in the order of the implementations.

Parameters:
Return type:

dict[Implementation[S, ~P, R], M]

pytest_parametrize(test=<alternative._Undefined object>, *, only_default=False)

Decorator to parametrise a test function with implementations - always includes the reference implementation.

Parameters:

  • test (F | _Undefined) – Test function to wrap - this is elided if using the decorator syntax.

  • only_default (bool) – Only include the reference and default implementations. If False, include all implementations.

  • only_default

Return type:

F | Callable[[F], F]

pytest_parametrize_pairs(test=<alternative._Undefined object>, *, n_cache=0, double_reference=False, only_default=False)

Decorator to parametrise a test function with the reference and alternative implementations.

Parameters:

  • test (F | _Undefined) – Inner pytest function to parameterise with reference and alternative implementations - this is elided if using the decorator syntax.

  • n_cache (int | None) – Passed to lru_cache which wraps the reference implementation. Set to non-0 values for it to actually cache.

  • double_reference (bool) – If True, the reference implementation will be included in the implementations. This can be used for sanity-checking equivalence tests.

  • only_default (bool) – If True, only the default implementation will be used as the other implementation. If double_reference is True, the reference implementation will be included as well.

  • test

  • n_cache

  • double_reference

  • only_default

Return type:

F | Callable[[F], F]

Implementation

class alternative.Implementation(alternatives: 'Alternatives[S, P, R]', implementation: 'Callable[..., R] | _TypedDescriptor[P, R]', label: 'str | None' = None)
Parameters:

  • alternatives (Alternatives[S, ~P, R])

  • implementation (Callable[[...], R] | _TypedDescriptor[~P, R])

  • label (str | None)

__call__(*args, **kwargs)

Call self as a function.

Parameters:
Return type:

R

add(implementation=<alternative._Undefined object>, *, default=False)

Add an alternative implementation.

Parameters:
Return type:

object

Exceptions

exception alternative.AlternativeError

Base class for all alternative errors.

exception alternative.AddTooLateError

Cannot add implementations after the alternatives have been invoked.

exception alternative.MultipleDefaultsError

Cannot set the default implementation more than once.

exception alternative.CrossAlternativesImplementationError

Cannot add an Implementation object that belongs to a different Alternatives set.