synology_apm_repo.sdk.api.repository module

Repository: one opened repository’s catalog/provider facade, and locate()/resolve()’s ref dispatch across its catalogs.

class synology_apm_repo.sdk.api.repository.SetKeyResult(verification, reopen_errors=())

Bases: object

What Repository.set_key() decided, and what it could not finish.

Variables:
  • verification (synology_apm_repo.sdk.dedup.keys.KeyVerification) – Whether the key verified. The repository’s key_status already reflects it.

  • reopen_errors (tuple[Exception, ...]) – Failures re-opening or closing an already-opened catalog while switching to a verified key. The key itself was still accepted; empty when nothing went wrong.

verification: KeyVerification
reopen_errors: tuple[Exception, ...]
property warning: str | None

A display sentence for reopen_errors, or None when there were none.

class synology_apm_repo.sdk.api.repository.Repository(store, layout, keys, key_verification, *, encrypted=None)

Bases: object

One opened repository: cheap metadata plus the catalog/provider calls that turn it into a browsable tree. Obtained from Session’s discover/open, never constructed directly; the Session closes it (Session.close_repo releases one early).

property layout: RepositoryLayout

Where and what kind of repository this is.

property is_encrypted: bool | None

Whether this repository is encrypted, or None when that couldn’t be determined.

property key_status: KeyStatus

Whether a key was supplied and accepted.

property key_verification: KeyVerification | None

The latest key verification outcome; None when no key was tried.

async set_key(key_string)

Try a key string against this repository. When it verifies, every already-opened catalog is reopened under it, and one that fails to switch is reported in reopen_errors rather than raised. When it doesn’t, open catalogs are left as they were and key_status becomes INVALID.

Parameters:

key_string (str) – "<userKeyID>@<base64 userKey>"; an empty string is malformed (Session.open reads it as no key).

Returns:

The verification outcome plus any catalog reopen failures.

Raises:
Return type:

SetKeyResult

async catalogs()

Every catalog this repository holds: a vault’s connection_config rows, or those of each object-storage sibling, opening the unopened ones concurrently.

Needs no key: these rows are plaintext, so catalog names can be shown before a key prompt. A catalog that fails to open raises rather than being skipped, so a short list is never mistaken for a repository with fewer catalogs.

async catalog_by_id(catalog_id)

The Catalog matching catalog_id, or None, opening only the catalogs that could match. A candidate’s open failure is raised, as in catalogs().

workload_is_supported(workload)

Whether workload’s type has an application-layer provider; True doesn’t guarantee every version resolves.

async file_map_tree()

The diagnostic file_map tree, browsable even when catalog metadata is missing. Always the first catalog’s: a RAW ref has no catalog segment to pick an object-storage sibling by. Tracked like any provider.

cache_names()

The names invalidate_caches accepts: every cache of every catalog opened so far, in registration order, without repeats.

cache_stats()

Counters of every cache of every catalog opened so far, keyed <catalog index>.<cache name>.

async invalidate_caches(*names)

Drop cached data so the next call re-reads the store: the named caches (see cache_names), or every cache when none is named.

Call this after the store changed; nothing else revalidates. Catalogs stay valid: only their caches are rebuilt, and the connection list is re-read when db_sources is dropped. Providers handed out earlier keep their own connections and are not closed; fetch fresh ones to see new data.

No catalog or provider call may be in flight: db connections and SaaS streams are closed and replaced. Does nothing while no catalog has been opened, since nothing is cached yet.

Parameters:

names (str) – Cache names to drop; none means all.

Raises:
  • KeyError – A name is not in cache_names(), checked once a catalog is open (nothing was dropped).

  • RuntimeError – The repository is closed.

  • ExceptionGroup – One or more resources failed to close or rebuild.

async release_provider(provider)

Close provider and stop tracking it, so the repository doesn’t keep it (and what it references) alive until its own close.

The close runs to completion even if this call is cancelled, and the repository’s close waits for it.

async locate(ref, *, raw=None)

Where ref lands. A human ref walks display names (with disambiguate() suffixes) catalog -> workload -> version -> item as far as its segments go, so it may stop above a node; a canonical or raw ref always names a node. ref.repo_path is ignored.

A NodeFrame’s provider is tracked until the repository closes; a caller done with it earlier passes it to release_provider.

Parameters:
  • ref (str | NodeRef) – A NodeRef or its string form.

  • raw (RawView | None) – Forwarded to Catalog.provider.

Returns:

The frame the ref reached.

Raises:
  • NotFoundError – A segment matches nothing, or no node matches a canonical/raw ref.

  • InvalidArgumentError – A segment matches ambiguously, or a canonical ref is malformed.

  • KeyRequiredError – The ref goes below a catalog of an encrypted repository and no key was supplied.

  • KeyMismatchError – As above, but the last key supplied was rejected.

  • ValueError – The string is not a parseable ref.

Return type:

RootFrame | CatalogFrame | WorkloadFrame | NodeFrame

async resolve(ref, *, raw=None)

locate, but ref must reach a node: a human ref names at least a catalog, workload and version. NodeFrame.unit() turns a leaf into its RestorableUnit.

Parameters:
  • ref (str | NodeRef) – A NodeRef or its string form.

  • raw (RawView | None) – Forwarded to Catalog.provider.

Returns:

The NodeFrame the ref reached.

Raises:
  • NotFoundError – No node matches the ref.

  • InvalidArgumentError – A human ref stops above a version, a canonical ref is malformed, or a segment matches ambiguously.

  • KeyRequiredError – The ref goes below a catalog of an encrypted repository and no key was supplied.

  • KeyMismatchError – As above, but the last key supplied was rejected.

  • ValueError – The string is not a parseable ref.

Return type:

NodeFrame

async version_for_ref(ref)

Resolve a canonical ref’s catalog/workload/version prefix, for a caller that wants the version’s provider rather than one node in it.

Parameters:

ref (str | NodeRef) – A canonical NodeRef or its string form.

Returns:

Where the version is; its catalog’s provider() opens it.

Raises:
Return type:

VersionLocation

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

Integrity check over every catalog, each distinct DedupRepo once (a vault’s catalogs share one). Opens every catalog first; at FULL level, catalogs over the same pool share one worker pool.

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 every catalog.

Raises:
Return type:

list[Finding]