Libraries

Libraries using spatch need to create a backend and mark all their functions as dispatchable.

You will also wish to re-expose the BackendSystem.backend_opts context manager to users.

Please also see the example code at this time.

API to create dispatchable functions

class spatch.backend_system.BackendSystem(group, environ_prefix, default_primary_types=None, backends=None)

Create a backend system that provides a @dispatchable decorator.

The backend system also has provides the backend_opts context manager which can be re-exposed by the library.

Note

Currently, there is a lot of public methods here, these should be hidden away.

Parameters:

• group (str or None) – The group of the backend entry points. All backends are entry points that are immediately loaded. If None, no entry points will be loaded (this is mainly for testing).

• environ_prefix (str) –

  Prefix for environment variables to modify the dispatching behavior. spatch currently queries the following variables (see User API).

  • f"{environ_prefix}_SET_ORDER"

  • f"{environ_prefix}_PRIORITIZE"

  • f"{environ_prefix}_BLOCK"

• default_primary_types (frozenset or None) – The set of types that are considered primary by default. Types listed here must be added as “secondary” types to backends if they wish to support them. If not provided, a “default” backend is not created!

• backends (sequence of backend namespaces) – Register a set of backends explicitly. This exists largely for testing but may be used for a library to add internal backends. (The order of backends passed is used and should be consistent between runs.)

property backend_opts

Property returning a BackendOpts class specific to this library (tied to this backend system).

dispatchable(relevant_args=None, *, module=None, qualname=None)

Decorator to mark functions as dispatchable.

Decorate a Python function with information on how to extract the “relevant” arguments, i.e. arguments we wish to dispatch for.

Parameters:

• relevant_args (str, list, tuple, or None) – The names of parameters to extract (we use inspect to map these correctly). If None all parameters will be considered relevant.

• module (str) – Override the module of the function (actually modifies it) to ensure a well defined and stable public API.

• qualname (str) – Override the qualname of the function (actually modifies it) to ensure a well defined and stable public API.

Note

The module/qualname overrides are useful because you may not want to advertise that a function is e.g. defined in the module library._private when it is exposed at library directly. Unfortunately, changing the module can confuse some tools, so we may wish to change the behavior of actually overriding it.