scverse_backends.BackendDispatcher

class scverse_backends.BackendDispatcher(*, entrypoint_group, host_name, trusted_backends=None, reserved_backends=None)

Bases: object

Per-host dispatch surface.

Each host library instantiates one BackendDispatcher and re-exports its attributes as the host’s public dispatch API.

Parameters:

entrypoint_group str

Entrypoint group that backend packages register against (e.g. "example_host.backends"). Entrypoints may load a backend module, class, or object.

host_name str

Name of the host library, used in error messages.

trusted_backends dict[str, dict[str, Any]] | None, default: None

Mapping of canonical backend name to {"aliases": [...], "package": "pip-name"}. Backends not in this list still work but emit a warning on first use. For trusted backends, package is also used as the expected Python distribution name during entrypoint discovery. Use distributions for backends that can be provided by multiple distribution names, and optionally entrypoints, object_refs, or module_prefixes for stricter provider verification.

reserved_backends dict[str, str] | None, default: None

Host-owned backend names or aliases that no backend may claim. Values are human-readable reasons shown when users request a reserved name.

Examples

>>> from scverse_backends import BackendDispatcher
>>> _dispatcher = BackendDispatcher(
...     entrypoint_group="example_host.backends",
...     host_name="example_host",
...     trusted_backends={
...         "example_accel": {
...             "aliases": ["example", "accelerated"],
...             "package": "example-host-accel",
...         },
...     },
... )
>>> backend_dispatch = _dispatcher.backend_dispatch
>>> settings = _dispatcher.settings

__init__(*, entrypoint_group, host_name, trusted_backends=None, reserved_backends=None)

Parameters:

entrypoint_group str

host_name str

trusted_backends dict[str, dict[str, Any]] | None, default: None

reserved_backends dict[str, str] | None, default: None

Return type:

None

Methods

__init__(*, entrypoint_group, host_name[, ...])
available_backend_names()	All registered backend names and aliases.
discover()	Eagerly load backends and merge their params into host signatures.
get_backend(name)	Look up a backend by name or alias.

Attributes

backend_dispatch	The @backend_dispatch decorator for host functions.
settings	Settings object exposing .backend and .use_backend().

property backend_dispatch: Callable

The @backend_dispatch decorator for host functions.

property settings: Settings

Settings object exposing .backend and .use_backend().

get_backend(name)

Look up a backend by name or alias. Returns None for "cpu".

Parameters:

name str

Return type:

Any | None

available_backend_names()

All registered backend names and aliases.

Return type:

list[str]

discover()

Eagerly load backends and merge their params into host signatures.

Discovery is normally lazy — entrypoints are loaded the first time anything in the dispatcher is queried (settings setter, get_backend, a non-CPU dispatched call). Call discover() when you want that to happen on a schedule you control:

• In a host’s Sphinx conf.py, so autodoc sees the merged signatures with backend-specific params and their docstrings.

• In tests that introspect help(fn) / inspect.signature(fn).

• Anywhere else IDE/LSP integrations would otherwise see the un-merged signature.

Idempotent — safe to call multiple times.

Return type:

None