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(dispatch_args=None, *, module=None, qualname=None)#

Decorator to mark functions as dispatchable.

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

Parameters:

  • dispatch_args (str, sequence of str, dict, callable, or None) –

    Indicate the parameters that we should consider for dispatching. Parameters not listed here will be ignored for dispatching purposes. For example, this may be all array inputs to a function. Can be one of:

    • None: All parameters are used.

    • string: The name of the parameter to extract.

    • list or tuple of string: The names of parameters to extract.

    • dict: A dictionary of {name: position} (not checked for correctness).

    • callable: A function that matches the signature and returns an iterable of dispatch arguments.

    If one or more names, spatch uses inspect.signature to find which positional argument it refers to.

  • 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.