synology_apm_repo.sdk.api.catalog module

Catalog: one catalog’s workload/version/provider operations, as returned by Repository.catalogs()/Repository.catalog_by_id(); and the frames a ref lands on.

class synology_apm_repo.sdk.api.catalog.RootFrame

Bases: object

A ref with no segments: the repository’s own top level.

class synology_apm_repo.sdk.api.catalog.CatalogFrame(catalog)

Bases: object

A ref that stopped at a catalog.

catalog: Catalog
class synology_apm_repo.sdk.api.catalog.WorkloadFrame(catalog, workload)

Bases: object

A ref that stopped at a workload.

catalog: Catalog
workload: Workload
class synology_apm_repo.sdk.api.catalog.NodeFrame(provider, node, catalog=None, workload=None, version=None)

Bases: object

A ref that reached a node in a version’s tree. A version always continues into its tree, so a ref naming one lands on its root node. catalog/workload/version are kept for breadcrumbs and are None for a raw ref. The owning Repository tracks provider until Repository.release_provider or the repository’s close.

provider: ClosableUnitProvider
node: Node
catalog: Catalog | None
workload: Workload | None
version: Version | None
async unit()

The restorable item this frame’s node names. It reads through provider, so release that provider only once done with the item.

Raises:

NotRestorableError – The node is a folder.

class synology_apm_repo.sdk.api.catalog.RawView(object_db_id=None)

Bases: object

Asks for a SaaS version’s raw view: its object-name index listed as-is by RawObjectProvider, with no application-layer decoding — a diagnostic view exposing internal names and object ids. A device version has no raw view and ignores it.

Variables:

object_db_id (str | None) – List this ObjectDB’s objects by id ("<streamUuid>_<offset>_<length>") instead of the index’s named entries.

object_db_id: str | None
class synology_apm_repo.sdk.api.catalog.VersionLocation(catalog, workload, version)

Bases: object

A version with the catalog and workload it belongs to.

catalog: Catalog
workload: Workload
version: Version
class synology_apm_repo.sdk.api.catalog.Catalog(dedup_repo, connection, *, saas_streams, providers, keys)

Bases: object

One catalog within an opened Repository: a single db/ connection_config row (connection) plus the workload/version/ provider operations scoped to it. Never constructed directly.

A vault’s sibling Catalog``s share one ``DedupRepo; on object storage each has its own (FORMAT-SPEC.md: Locating the repository root). workloads, versions, version_by_uid and verify raise KeyRequiredError/KeyMismatchError before any I/O while the owning repository is encrypted and not key-verified. Providers it hands out are tracked and closed by the owning Repository; Catalog itself has no close().

property connection: Connection

The db/connection_config row this catalog is.

property display_name: str

The connection’s display name.

property catalog_id: CatalogId

This catalog’s repo-id, or str(connection_config_id) for a vault (which has no repo-id), as canonical refs spell it.

property info: RepoInfo

This catalog’s own repo_info — per-catalog for object storage, vault-wide for a vault.

async workloads()

This catalog’s workloads.

async versions(workload, *, include_deleted=False)

workload’s browsable versions, newest backup first (ties by version_id descending), deleted ones only with include_deleted. A version whose content can’t be resolved fails only when opened.

async version_by_uid(workload_id, version_uid)

The version version_uid of workload workload_id, deleted or not, looked up by id. None unless that version exists, is browsable, and belongs to workload_id and to this catalog.

async provider(version, *, raw=None)

Dispatches version to the right UnitProvider by target_type/Workload.sub_type, degrading to RawObjectProvider when nothing recognizes it; raw asks for that raw view directly.

Raises:

NotFoundError – raw.object_db_id is malformed or names another stream.

async verify(level=VerifyLevel.QUICK, *, progress=None, tuning=None)

Integrity check over this catalog’s DedupRepo — on a vault, the same check as every sibling catalog’s, not one scoped to this catalog’s rows.

Parameters:
  • level (VerifyLevel) – How deep to check.

  • progress (ProgressCallback | None) – Receives a Progress snapshot as checking advances.

  • tuning (VerifyTuning | None) – How the check spreads its reads (default VerifyTuning()).

Returns:

Every Finding from the check.

Raises:

StorageBackendError – A store call failed mid-check.

Return type:

list[Finding]

async locate(segments, *, raw=None)

Walks human-ref display names below this catalog: workload -> version -> item, as far as segments go.

Parameters:
  • segments (Sequence[str]) – The ref’s segments below the catalog.

  • raw (RawView | None) – Passed to provider().

Returns:

The frame the last segment reached.

Raises:
Return type:

WorkloadFrame | NodeFrame

synology_apm_repo.sdk.api.catalog.match_or_raise(segment, pairs, objects, *, kind, hints=None)

match_display_name, raising NotFoundError on a miss, or InvalidArgumentError naming the candidates when segment is the pre-suffix name of several (see ambiguous_matches).