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)

Bases: object

One backend metadata issue found by the registry audit.

backend_id

field

message

severity

class uniqc.backend_adapter.backend_registry.FetchResult(backends, fetch_failures=<factory>)

Bases: object

Result of fetching backends from all platforms.

Variables:

• backends (dict[uniqc.backend_adapter.backend_info.Platform, list[uniqc.backend_adapter.backend_info.BackendInfo]]) – Per-platform backend descriptors.

• fetch_failures (dict[uniqc.backend_adapter.backend_info.Platform, str]) – Platforms that had credentials but failed to fetch, mapped to the error message.

backends

fetch_failures

uniqc.backend_adapter.backend_registry.audit_backend_info(backend)

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.

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

Validate normalized backend descriptors returned by the registry.

Parameters:

• backends – Backend descriptors (flat list or per-platform dict).

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

uniqc.backend_adapter.backend_registry.fetch_all_backends(force_refresh=False)

Fetch backends from all configured platforms.

Parameters:

force_refresh – 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.

uniqc.backend_adapter.backend_registry.fetch_all_backends_with_status(force_refresh=False)

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.

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

Fetch and normalise backends for one platform.

Parameters:

• platform – The platform to fetch backends for.

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

uniqc.backend_adapter.backend_registry.find_backend(identifier)

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 – Backend identifier.

Returns:

The matching BackendInfo object.

Raises:

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