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:
objectWhat a
SaasWorkloadConfighook adds to a node the provider builds.- Variables:
mtime (datetime.datetime | None) – The node’s
Node.mtime.columns (synology_apm_repo.sdk.units.base.ItemColumns) – The node’s
Node.columns.details (collections.abc.Mapping[str, object]) – The node’s
Node.details.role (synology_apm_repo.sdk.units.base.NodeRole) – The node’s
Node.role.leaf_kind (synology_apm_repo.sdk.units.base.UnitKind | None) – A group’s own
Node.leaf_kind, instead of the config’sleaf_kind.
- columns: ItemColumns¶
- 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:
GenericWhat one workload needs beyond the shared skeleton: which
tablesto open (resolved viaobject_names), atree_factorythat builds theTreeStrategyonce every table is open, and acontent()callback giving one leaf row’sContentSource; the provider builds the leaf’sRestorableUnitaround it.tree_factory/contentmay do I/O and areasync;leaf_extras/group_extras/leaf_sizeonly reshape data already fetched and stay synchronous.- 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
tablesentry (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 onsub_type("mail_table"is"mail_db"forUSER_EXCHANGEbut"group_mail_db"forGROUP_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, raisesUnsupportedDataFormatError.
- leaf_extras: Callable[[SaasWorkloadProvider, dict[str, object | None]], NodeExtras]¶
A leaf’s
mtime,columnsanddetailsfrom its own row (Drive’shashcolumn; GWS Mail’s label names and GWS Contact’s group names, read fromprovider.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’ssizefrom its row,Nonewhen 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); itsRestorableUnitis 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:
objectNode.handleof every container node aTreeBackedProviderbuilds, and of everySaasWorkloadProviderleaf: its treekey(()for the root) and therowthe tree listed it from (TreeEntry.row), whichunit()builds the leaf from. Compared and hashed bykeyalone.
- synology_apm_repo.sdk.units.saas.provider.tree_key(node)¶
The tree key a
TreeBackedProviderstored innode.handle(()for the root), orNonewhennode.handleis not aSaasHandle.
- synology_apm_repo.sdk.units.saas.provider.tree_row(node)¶
The row
nodewas listed from, orNone(a synthetic group, the root, or a node aTreeBackedProviderdidn’t build).
- class synology_apm_repo.sdk.units.saas.provider.TreeBackedProvider¶
Bases:
objectchildren()for a provider whose tree is aTreeStrategy: subclasses set_treeand build each listed entry’sNodein_node_for. Every container node carries aSaasHandle(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,GenericUnitProvidershared by every config-driven SaaS workload, driven by theSaasWorkloadConfiga workload (Mail, Drive, …) supplies. Build one withcreate, not the constructor.- state: StateT¶
What the config’s
tree_factoryprefetched for its hooks.
- async classmethod create(repo, version, config, saas_streams, *, shared=None)¶
Open the version’s
saas_objand every configured table, then build the tree.- Parameters:
repo (DedupRepo) – The repository
versionbelongs to.version (Version) – The SaaS version to open.
config (SaasWorkloadConfig[StateT]) – The workload’s configuration.
saas_streams (SaasStreamCache) – Borrowed, not owned; the
saas_objis opened through it and stays cached there.shared (SharedSaasContext | None) – The version’s context, resolved once by
units/dispatch.py’ssaas_provider_forfor every candidate; resolved here when omitted.
- Raises:
UnsupportedDataFormatError – A configured table can’t be resolved, or building the tree hits a schema mismatch.
NotFoundError –
sharedis omitted and the version’ssaas_objcan’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 aconfig.tablesentry throughobject_names[table_name]. Once open,table(table_name)returns it andclose()releases it.- Returns:
The table’s connection, or
Nonewhen 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_objectthroughtable’s ObjectDB.
- async object_view(table, object_id, key)¶
A lazy view of
object_id’s bytes, located throughtable’s ObjectDB. A stale index entry makes only the item atkeyunrestorable (NotRestorableError).
- async read_id_to_name_map(object_names, table, *, id_column, name_column)¶
object_name_index.read_id_to_name_mapover 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_namesover this version’s index, reusing the provider’s index ObjectDB, and the membership DB itself when a configured table already opened it (GWS’smail_dbandcontact_db), rather than materializing it a second time.
- property is_m365: bool¶
Whether this version is M365 rather than GWS (Google Workspace), the only two SaaS target types.
- ref_for(key)¶
The canonical ref for tree
key— the same one this provider gives the listedNode.
- root()¶
- async unit(node)¶
- class synology_apm_repo.sdk.units.saas.provider.RecursiveTreeSaasProvider(repo, version, config)¶
Bases:
SaasWorkloadProvider,GenericA
SaasWorkloadProviderthat implementsSupportsDirectRefLookup, for a config whosetree_factoryreturns aRecursiveTree(Drive’s depth-independentitem_idrefs). Kept a subclass so theisinstancecheck 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)¶
-
The calling convention of every SaaS provider factory
units/ dispatch.pytries (make_saas_provider’s factories,TeamsChatProvider.create):await factory(repo, version, saas_streams, shared=...). AProtocolbecause aCallablealias 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
SaasProviderFactoryoverconfig, forwarding toprovider_cls.create.namebecomes the factory’s__name__/__qualname__, so a traceback names the specific provider.provider_clsisRecursiveTreeSaasProviderfor aRecursiveTreeconfig.