Source code for backends

# SPDX-FileCopyrightText: 2026 Brad Barnett
#
# SPDX-License-Identifier: MIT

"""A registry of backends, so ``AutoDisplay`` and ``audiodev.auto`` can pick one you wrote.

A backend registers a name and a lazy ``"module:Class"`` string, so
registering imports nothing::

    import backends
    backends.register("display", "hls", "castdisplay.hls_display:HlsDisplay", probe=have_ffmpeg)

A board config says which registered backends it wants, in order::

    backends.require("display", "hls", module="castdisplay.hls_display")
    display_drv = AutoDisplay(1280, 720, tv=TV)   # extra keywords go to the winner

A display backend's constructor takes ``width`` and ``height``, optionally
``rotation`` (passed only when the caller asks for one), and any keywords of
its own. ``AutoDisplay``'s window hints (``scale``, ``title``, ``quiet``,
``maximized``) stay with the built-in window backends.

``kind`` is ``"display"`` or ``"audio"``. The search order is:

1. the environment variable (``OMNIPYTHON_DISPLAY`` or ``OMNIPYTHON_AUDIO``),
   if set. It names one backend and nothing else is tried;
2. the backends a config ``require``d, in order, skipping any whose
   ``probe()`` says no;
3. the backends that ship in the box, in their fixed order, on the host
   that can run them.

A backend registered by someone else is never picked in step 3. Something has
to ``require`` it, or the user has to name it, so a backend that streams to a
TV never chooses itself.

There is no scanning. On MicroPython, ``require`` imports the module by name and
importing registers it; a frozen module imports like any other.
"""

import sys

__all__ = ["Decline", "register", "require", "names", "spec", "candidates", "load"]


[docs] class Decline(Exception): """Raised by a backend's factory to say "not on this machine"; the next one is tried."""
# kind -> list of [name, spec, probe, builtin]; a list because order matters and # MicroPython dicts do not promise it _entries = {} # kind -> names a config required, in the order it asked _required = {} def _find(kind, name): for entry in _entries.get(kind, ()): if entry[0] == name: return entry return None
[docs] def register(kind, name, spec, probe=None, _builtin=False): """Make *name* a backend of *kind*; imports nothing. *spec* is ``"module:Class"`` (``"module"`` alone for an audio backend, which is a module with ``pcm_out`` and ``pcm_in``). *probe*, if given, is called with no arguments and returns false when this machine can't run the backend. Registering a name again replaces it in place. *_builtin* is for the backends that ship in the box; the underscore says it isn't yours to pass. A backend with it is picked unasked by the third step of the search order, and a display backend with it is called with positional arguments instead of keywords. """ entry = [name, spec, probe, bool(_builtin)] entries = _entries.setdefault(kind, []) for i in range(len(entries)): if entries[i][0] == name: entries[i] = entry return entries.append(entry)
[docs] def names(kind): """The registered backend names of *kind*, in registration order.""" return [entry[0] for entry in _entries.get(kind, ())]
[docs] def spec(kind, name): """The spec string *name* was registered with, or ``None``.""" entry = _find(kind, name) return entry[1] if entry else None
def _env(name): """An environment variable's value or ``None``, through ``boarddev`` when it is there.""" try: from boarddev import env_get except ImportError: import os return os.getenv(name) return env_get(name)
[docs] def require(kind, name, module=None): """Ask for backend *name* to be tried by ``auto``, ahead of the built-in ones. If *name* isn't registered yet, imports *module* (default: *name*), which registers it. Raises ``ImportError`` that names the module when it isn't installed, or when importing it didn't register the backend. """ if _find(kind, name) is None: _import_registering(kind, name, module or name) required = _required.setdefault(kind, []) if name not in required: required.append(name)
def _import_registering(kind, name, module): try: __import__(module) except ImportError as exc: raise ImportError( "%s backend %r needs the module %r, which could not be imported (%s). " "Install the package that provides it." % (kind, name, module, exc) ) if _find(kind, name) is None: raise ImportError( "importing %r did not register a %s backend named %r" % (module, kind, name) ) def _usable(entry): probe = entry[2] if probe is None: return True try: return bool(probe()) except Exception: # a probe that blows up has no business stopping auto from trying the next one return False
[docs] def candidates(kind, override=None): """Yield ``(name, spec, builtin)`` for each backend to try, in search order. *name* and *spec* are what the backend registered with. *builtin* is true for a backend that ships in the box. A consumer ``auto`` module unpacks all three, so the tuple keeps this shape. *override* is a name the user gave (usually from the environment). It is the only candidate, its probe is not consulted, and an unregistered name is imported as a module, the way ``require`` would. """ if override: entry = _find(kind, override) if entry is None: _import_registering(kind, override, override) entry = _find(kind, override) yield entry[0], entry[1], entry[3] return tried = [] for name in _required.get(kind, ()): entry = _find(kind, name) tried.append(name) if entry is not None and _usable(entry): yield entry[0], entry[1], entry[3] for entry in list(_entries.get(kind, ())): if entry[3] and entry[0] not in tried and _usable(entry): yield entry[0], entry[1], entry[3]
[docs] def load(spec): """Import and return what *spec* names: ``"module:Class"``, or a module.""" module, _, attr = spec.partition(":") __import__(module) obj = sys.modules[module] if attr: for part in attr.split("."): obj = getattr(obj, part) return obj