uniqc.backend_adapter.backend_registry module

Backend registry: fetches, normalises, and caches platform backends.

This module is the central orchestrator for the uniqc backend command. It: 1. Calls each platform’s list_backends() adapter method (or cache). 2. Normalises the raw platform data into BackendInfo objects. 3. Persists the normalised list to the disk cache. 4. Provides query helpers (get_backend_info, find_backend).

class uniqc.backend_adapter.backend_registry.BackendAuditIssue(backend_id, severity, field, message)[source]

Bases: object

One backend metadata issue found by the registry audit.

Parameters:
backend_id: str
field: str
message: str
severity: str
class uniqc.backend_adapter.backend_registry.FetchResult(backends, fetch_failures=<factory>)[source]

Bases: object

Result of fetching backends from all platforms.

Variables:
Parameters:
backends: dict[Platform, list[BackendInfo]]
fetch_failures: dict[Platform, str]
uniqc.backend_adapter.backend_registry.audit_backend_info(backend)[source]

Validate one normalized backend descriptor.

The audit is intentionally provider-neutral. It checks only the fields UnifiedQuantum relies on internally, so adapters can expose provider-specific metadata in BackendInfo.extra without being rejected.

Parameters:

backend (BackendInfo)

Return type:

list[BackendAuditIssue]

uniqc.backend_adapter.backend_registry.audit_backends(backends, *, fetch_failures=None)[source]

Validate normalized backend descriptors returned by the registry.

Parameters:

  • backends (list[BackendInfo] | dict[Platform, list[BackendInfo]]) – Backend descriptors (flat list or per-platform dict).

  • fetch_failures (dict[Platform, str] | None) – Optional mapping of platforms that had credentials but failed to fetch, with the error message. Each entry is emitted as a BackendAuditIssue(severity="warning") so the caller can see which platforms were not audited.

Return type:

list[BackendAuditIssue]

uniqc.backend_adapter.backend_registry.fetch_all_backends(force_refresh=False)[source]

Fetch backends from all configured platforms.

Parameters:

force_refresh (bool) – Bypass the cache TTL for all platforms.

Returns:

Dict mapping Platform to its list of BackendInfo objects. Platforms with no credentials are silently omitted. Platforms with credentials but fetch failures are omitted with a warning.

Return type:

dict[Platform, list[BackendInfo]]

uniqc.backend_adapter.backend_registry.fetch_all_backends_with_status(force_refresh=False)[source]

Fetch backends from all platforms, returning fetch failures too.

Like fetch_all_backends() but also returns information about platforms that had credentials but failed to fetch, so callers can surface these as audit issues.

Parameters:

force_refresh (bool)

Return type:

FetchResult

uniqc.backend_adapter.backend_registry.fetch_platform_backends(platform, force_refresh=False)[source]

Fetch and normalise backends for one platform.

Parameters:

  • platform (Platform) – The platform to fetch backends for.

  • force_refresh (bool) – If True, bypass the cache TTL check.

Returns:

A tuple of (backends, fetched_newly) where fetched_newly is True if the data was fetched from the network (vs. served from cache).

Raises:

BackendError – If the platform has credentials configured but the fetch fails (network error, API error, etc.) and no stale cache is available as fallback.

Return type:

tuple[list[BackendInfo], bool]

uniqc.backend_adapter.backend_registry.find_backend(identifier)[source]

Find a backend by its identifier.

Supports two forms:

  • platform:name (e.g. originq:WK_C180)

  • bare name (searches all platforms)

Matching is case-insensitive and treats - and _ as equivalent so originq:wk_c180 and originq:WK_C180 both succeed. For OriginQ a small alias table also maps short names like wk180 to WK_C180.

Parameters:

identifier (str) – Backend identifier.

Returns:

The matching BackendInfo object.

Raises:

ValueError – If the backend is not found or the identifier format is invalid.

Return type:

BackendInfo