synology_apm_repo.sdk.units.saas.provider module

SaasWorkloadProvider + SaasWorkloadConfig: the shared skeleton Mail/Drive/Contact/Calendar/Site all reduce to. The provider opens the version’s saas_obj, opens each service DB the config names through the connector’s object-name index (object_name_index.py), builds the config’s TreeStrategy, and answers root()/ children()/unit() by delegating to it; a workload supplies only a SaasWorkloadConfig and its content() helpers.

Every table is resolved by a direct object-name-index lookup: a table the index doesn’t name is not found. Only the index’s naming tells schema-identical tables apart (Archive Mail’s mail_table and regular Mail’s).

TeamsChatProvider is not built on this base: its discovery (one shared channel/chat INDEX-object lookup) doesn’t fit the per-table object_names model.

class synology_apm_repo.sdk.units.saas.provider.NodeExtras(mtime=None, columns=<factory>, details=<factory>, role=NodeRole.ORDINARY, leaf_kind=None)

Bases: object

What a SaasWorkloadConfig hook adds to a node the provider builds.

Variables:
mtime: datetime | None
columns: ItemColumns
details: Mapping[str, object]
role: NodeRole
leaf_kind: UnitKind | None
class synology_apm_repo.sdk.units.saas.provider.SaasWorkloadConfig(root_name, leaf_kind, tables, tree_factory, content, object_names=<factory>, leaf_extras=<function SaasWorkloadConfig.<lambda>>, group_extras=<function SaasWorkloadConfig.<lambda>>, leaf_size=<function SaasWorkloadConfig.<lambda>>, leaf_export_name=None)

Bases: Generic

What one workload needs beyond the shared skeleton: which tables to open (resolved via object_names), a tree_factory that builds the TreeStrategy once every table is open, and a content() callback giving one leaf row’s ContentSource; the provider builds the leaf’s RestorableUnit around it.

tree_factory/content may do I/O and are async; leaf_extras/group_extras/leaf_size only reshape data already fetched and stay synchronous.

root_name: str
leaf_kind: UnitKind
tables: tuple[str, ...]
tree_factory: Callable[[SaasWorkloadProvider], Awaitable[tuple[TreeStrategy, StateT]]]

Builds the tree, plus whatever the hooks below need prefetched once, with I/O (GWS mail labels, GWS contact groups, Site list create times), which becomes provider.state.

content: Callable[[SaasWorkloadProvider, dict[str, object | None], tuple[str, ...]], Awaitable[ContentSource]]

A leaf’s content; raises NotRestorableError (not_restorable) for a row with nothing to restore.

object_names: dict[str, tuple[str, ...]]

Maps a tables entry (a schema table name, e.g. "mail_table") to the index’s own name(s) for the service DB defining it — plural because the name depends on sub_type ("mail_table" is "mail_db" for USER_EXCHANGE but "group_mail_db" for GROUP_EXCHANGE). Aliases are tried in order; the first the index has and that validates wins. A table with no entry here, or a version with no usable index, raises UnsupportedDataFormatError.

leaf_extras: Callable[[SaasWorkloadProvider, dict[str, object | None]], NodeExtras]

A leaf’s mtime, columns and details from its own row (Drive’s hash column; GWS Mail’s label names and GWS Contact’s group names, read from provider.state).

group_extras: Callable[[SaasWorkloadProvider, tuple[str, ...]], NodeExtras]

A group node’s extras (the root included), keyed by the group’s tree key since no row exists at group level (Site’s List roles and create times, Calendar’s category leaf_kind).

leaf_size: Callable[[dict[str, object | None]], int | None]

A leaf listing Node’s size from its row, None when not cheaply known at listing time (only Drive and Site’s document-library items have one).

leaf_export_name: Callable[[SaasWorkloadProvider, dict[str, object | None]], str] | None

A leaf’s synthesized file name (Node.export_name) from its row, for a workload whose items have none of their own (Mail, Calendar, Contact); its RestorableUnit is named the same. Without one, the unit takes the listed node’s name.

class synology_apm_repo.sdk.units.saas.provider.SaasHandle(key, row=None)

Bases: object

Node.handle of every container node a TreeBackedProvider builds, and of every SaasWorkloadProvider leaf: its tree key (() for the root) and the row the tree listed it from (TreeEntry.row), which unit() builds the leaf from. Compared and hashed by key alone.

key: tuple[str, ...]
row: dict[str, object | None] | None
synology_apm_repo.sdk.units.saas.provider.tree_key(node)

The tree key a TreeBackedProvider stored in node.handle (() for the root), or None when node.handle is not a SaasHandle.

synology_apm_repo.sdk.units.saas.provider.tree_row(node)

The row node was listed from, or None (a synthetic group, the root, or a node a TreeBackedProvider didn’t build).

class synology_apm_repo.sdk.units.saas.provider.TreeBackedProvider

Bases: object

children() for a provider whose tree is a TreeStrategy: subclasses set _tree and build each listed entry’s Node in _node_for. Every container node carries a SaasHandle (key () for the root).

async children(node, offset=0, limit=None)
class synology_apm_repo.sdk.units.saas.provider.SaasWorkloadProvider(repo, version, config)

Bases: AsyncClosing, TreeBackedProvider, Generic

UnitProvider shared by every config-driven SaaS workload, driven by the SaasWorkloadConfig a workload (Mail, Drive, …) supplies. Build one with create, not the constructor.

state: StateT

What the config’s tree_factory prefetched for its hooks.

async classmethod create(repo, version, config, saas_streams, *, shared=None)

Open the version’s saas_obj and every configured table, then build the tree.

Parameters:
  • repo (DedupRepo) – The repository version belongs to.

  • version (Version) – The SaaS version to open.

  • config (SaasWorkloadConfig[StateT]) – The workload’s configuration.

  • saas_streams (SaasStreamCache) – Borrowed, not owned; the saas_obj is opened through it and stays cached there.

  • shared (SharedSaasContext | None) – The version’s context, resolved once by units/dispatch.py’s saas_provider_for for every candidate; resolved here when omitted.

Raises:
  • UnsupportedDataFormatError – A configured table can’t be resolved, or building the tree hits a schema mismatch.

  • NotFoundError – shared is omitted and the version’s saas_obj can’t be located.

async open_optional_table_via_index(table_name)

Open an optional table that stays queryable (e.g. Mail’s mail_folder_table), resolved like a config.tables entry through object_names[table_name]. Once open, table(table_name) returns it and close() releases it.

Returns:

The table’s connection, or None when it can’t be found or validated.

Return type:

Connection | None

async close()

Close every SQLite source this provider owns and release its hold on the index ObjectDB; the borrowed stream stays open.

table(name)
async read_object(table, object_id, *, expected_size=None)

objectdb.read_object through table’s ObjectDB.

async object_view(table, object_id, key)

A lazy view of object_id’s bytes, located through table’s ObjectDB. A stale index entry makes only the item at key unrestorable (NotRestorableError).

async read_id_to_name_map(object_names, table, *, id_column, name_column)

object_name_index.read_id_to_name_map over this version’s index, reusing the provider’s index ObjectDB.

async read_grouped_names(*, definition_names, definition_table, id_column, name_column, membership_names, membership_table, item_column, group_column)

object_name_index.read_grouped_names over this version’s index, reusing the provider’s index ObjectDB, and the membership DB itself when a configured table already opened it (GWS’s mail_db and contact_db), rather than materializing it a second time.

property version: Version
property is_m365: bool

Whether this version is M365 rather than GWS (Google Workspace), the only two SaaS target types.

property repo: DedupRepo
ref_for(key)

The canonical ref for tree key — the same one this provider gives the listed Node.

root()
async unit(node)
class synology_apm_repo.sdk.units.saas.provider.RecursiveTreeSaasProvider(repo, version, config)

Bases: SaasWorkloadProvider, Generic

A SaasWorkloadProvider that implements SupportsDirectRefLookup, for a config whose tree_factory returns a RecursiveTree (Drive’s depth-independent item_id refs). Kept a subclass so the isinstance check stays false for every other SaaS provider.

async resolve_extra(extra_segments)
async parent_of(node)
class synology_apm_repo.sdk.units.saas.provider.SaasProviderFactory(*args, **kwargs)

Bases: Protocol, Generic

The calling convention of every SaaS provider factory units/ dispatch.py tries (make_saas_provider’s factories, TeamsChatProvider.create): await factory(repo, version, saas_streams, shared=...). A Protocol because a Callable alias can’t express a keyword-only parameter.

synology_apm_repo.sdk.units.saas.provider.make_saas_provider(config, *, name, provider_cls=<class 'synology_apm_repo.sdk.units.saas.provider.SaasWorkloadProvider'>)

Build an async SaasProviderFactory over config, forwarding to provider_cls.create.

name becomes the factory’s __name__/__qualname__, so a traceback names the specific provider. provider_cls is RecursiveTreeSaasProvider for a RecursiveTree config.