alternative =========== ``alternative`` is a 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 ------- .. code-block:: console $ pip install alternative ``alternative`` supports Python 3.10 and newer. The runtime has no dependencies. Install ``pytest`` to use the test helpers and ``pytest-benchmark`` for the benchmark fixture: .. code-block:: console $ pip install alternative pytest pytest-benchmark For async tests, also install ``pytest-asyncio`` or another async pytest plugin; see :ref:`async-tests`. Decorated functions retain their typed call signatures and return types, so callers keep normal type checking and code completion while you register and select implementations. No extra typing configuration is needed. A First Example --------------- .. code-block:: python import alternative @alternative.reference def total(values: list[int]) -> int: """Sum integers with a straightforward reference loop.""" result = 0 for value in values: result += value return result @total.add(default=True) def total_builtin(values: list[int]) -> int: """Use the built-in sum with the same integer contract.""" 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. This shows a selected default; choose it after checking correctness and measuring representative inputs. Start with :doc:`quickstart` to add tests and benchmarks. If your implementations live in separate modules, follow :doc:`tutorial` for startup imports and a complete runnable package. Contents -------- .. toctree:: :maxdepth: 2 :caption: Start Here quickstart tutorial .. toctree:: :maxdepth: 2 :caption: Guides applications pytest testing-contracts workflow methods performance .. toctree:: :maxdepth: 2 :caption: Reference and Development api contributing Project Links ------------- * `PyPI package `__ * `Source repository `__ Indices ------- * :ref:`genindex` * :ref:`modindex` * :ref:`search`