Skip to content

catalog

List the concrete circuit backends for the builder page.

ListedField

Bases: TypedDict

One constructor setting the builder page can edit.

Source code in shadowsim/backends/catalog.py
class ListedField(TypedDict):
    """One constructor setting the builder page can edit."""

    name: str
    label: str
    default: str
    allow_inf: bool
    kind: NotRequired[str]
    choices: NotRequired[list[str]]

ListedBackend

Bases: TypedDict

Display record for one concrete circuit backend.

Source code in shadowsim/backends/catalog.py
class ListedBackend(TypedDict):
    """Display record for one concrete circuit backend."""

    id: str
    title: str
    detail: str
    phrase: str
    setup: str
    shots: bool
    fields: list[ListedField]

listed_backends

listed_backends() -> list[ListedBackend]

Return the concrete circuit backends in export order.

Each exported backend module is imported on its own. A missing extra skips that module. CircuitBackend is a protocol, so it is omitted. Each record uses the class name and the first line of its docstring. Required constructor arguments appear in setup. A shots parameter is written as {shots} so the page can fill the shot budget. basis_gates, when its default is None, is a gate list written as {basis_gates}. Its choices are the class attribute BASIS_GATE_NAMES. Any other parameter with a default is a numeric field the page can edit, written as {name}.

Returns:

Raises:

  • ImportError –

    No circuit backend module could be imported. The first failure is re-raised.

Source code in shadowsim/backends/catalog.py
def listed_backends() -> list[ListedBackend]:
    """Return the concrete circuit backends in export order.

    Each exported backend module is imported on its own. A missing extra skips
    that module. ``CircuitBackend`` is a protocol, so it is omitted. Each
    record uses the class name and the first line of its docstring. Required
    constructor arguments appear in ``setup``. A ``shots`` parameter is written
    as ``{shots}`` so the page can fill the shot budget. ``basis_gates``, when
    its default is ``None``, is a gate list written as ``{basis_gates}``. Its
    choices are the class attribute ``BASIS_GATE_NAMES``. Any other parameter
    with a default is a numeric field the page can edit, written as ``{name}``.

    Returns:
        Backends the builder page can offer.

    Raises:
        ImportError: No circuit backend module could be imported. The first
            failure is re-raised.
    """
    listed: list[ListedBackend] = []
    first_error: ImportError | None = None
    seen: set[str] = set()
    for module_name, extra in _EXPORTS.values():
        if module_name in seen:
            continue
        seen.add(module_name)
        try:
            if extra is None:
                module = importlib.import_module(module_name)
            else:
                module = import_optional(module_name, extra=extra)
        except ImportError as exc:
            if first_error is None:
                first_error = exc
            continue
        listed.extend(_describe_backends(module))
    if listed:
        return listed
    if first_error is not None:
        raise first_error
    raise ImportError("no circuit backends could be imported")