synology_apm_repo.sdk.units.base module¶
Shared restorable-unit vocabulary. Every workload provider (Device, FS,
SaaS, …) implements UnitProvider against these same three types, so
the CLI/TUI never need to know which workload they’re looking at.
- class synology_apm_repo.sdk.units.base.UnitKind(*values)¶
Bases:
EnumWhich restorable-unit kind a
Node/RestorableUnitis — drives the CLI/TUI’s default icon/preview routing.- DISK_IMAGE = 'disk_image'¶
- DISK_FILESYSTEM = 'disk_filesystem'¶
- DISK_FILE = 'disk_file'¶
- FILE = 'file'¶
- MAIL = 'mail'¶
- CONTACT = 'contact'¶
- CALENDAR_EVENT = 'calendar_event'¶
- DRIVE_ITEM = 'drive_item'¶
- SITE_ITEM = 'site_item'¶
- RAW_OBJECT = 'raw_object'¶
- TEAMS_CHAT_MESSAGE = 'teams_chat_message'¶
A Teams channel or Chat conversation’s rendered transcript page — both a leaf’s own kind and every
TeamsChatProvidercontainer’sleaf_kind(root, each channel category).
- CATEGORY_GROUP = 'category_group'¶
A container whose children are always further containers, never a leaf — a SharePoint site’s “List” category and a Calendar’s “My”/”Other Calendars” category.
- class synology_apm_repo.sdk.units.base.FileState(*values)¶
Bases:
EnumA disk-fs file’s cloud-sync/encryption state, carried as
Node.file_state— produced other thanNORMALonly byunits/content/ disk_fs/’s NTFS/APFS backends.CLOUD_ONLYmarks a cloud-sync file whose content may be missing: on APFS a dataless one, on NTFS any cloud-tagged one, downloaded or not. A file both cloud-sync and EFS-encrypted is listedCLOUD_ONLY; opening it raisesContentUnavailableErrorwith the cloud-sync reason when it lacks its complete data, else with the EFS reason.- NORMAL = 'normal'¶
- ENCRYPTED = 'encrypted'¶
- CLOUD_ONLY = 'cloud_only'¶
- class synology_apm_repo.sdk.units.base.ContentSource(*args, **kwargs)¶
Bases:
ProtocolThe one content-reading contract every
RestorableUnit.contentsatisfies — aDedupFile/ByteRangeViewsatisfies this shape already, as does assembled content (.eml,.ics, …), so CLI/TUI never need to tell them apart.- property size: int | None¶
Synchronous;
Nonewhen the size isn’t known up front (e.g.LazyArtifactbefore its artifact is assembled). A@propertybecause Protocol attributes are invariant, so a plain field would reject a narrowerint.
- async read(offset=0, length=None)¶
Read
lengthbytes starting atoffset(default: fromoffsetto the end). A request extending past the content’s own end — includingoffsetstarting at or past it — returns only the bytes that exist (possibly none), never an error. Abytearrayresult belongs to the caller (dedup-backed content returns the buffer it filled rather than copying it intobytes).- Raises:
ValueError –
offsetorlengthis negative.ResourceLimitExceededError – For a
DedupFile-backed implementation, the resolved read size exceedsMAX_SINGLE_READ_SIZE(1 GiB); usestream()for a large read.
- stream(block=8388608)¶
Yield
(offset, data)blocks of at mostblockbytes that cover the content in order.
- async export_range(writer, start, end, /, *, sparse=True, progress=None, tuning=None)¶
Writes the content’s
[start, end)intowriter, which the caller has already opened and will commit or abort itself (api.run_exportdoes all of it), at offsets relative tostart.sparse=Truemay leaveZERO/HOLEranges unwritten.progressreceives each newly written byte count as it is handed towriter(the counts add up toplanned_bytesover the range);tuningis for implementations backed by the dedup layer and ignored by the others.- Raises:
ValueError – The range is not inside
[0, size].
- async planned_bytes(start, end, /)¶
The bytes
export_rangeover[start, end)reports as progress: the realDATAbytes for dedup-backed content, the whole range for content without holes.
- class synology_apm_repo.sdk.units.base.NodeRole(*values)¶
Bases:
EnumHow a frontend presents a container node beyond listing its children.
- ORDINARY = 'ordinary'¶
- LIST_OVERVIEW = 'list_overview'¶
A plain SharePoint List’s own group node, shown as a non-expandable tree leaf whose items read as one spreadsheet-style overview (
read_site_list_items).
- FLAT_CATEGORY = 'flat_category'¶
A site’s “List” category node, whose Lists are listed as ordinary rows but kept out of a folder tree.
- class synology_apm_repo.sdk.units.base.ItemColumns(sender=None, email=None, event_start=None, event_end=None, recurrence=None)¶
Bases:
objectThe per-kind fields of a listed item a frontend lays out as list columns; each is
Nonewhere it doesn’t apply or isn’t known.- Variables:
sender (str | None) – A mail’s sender, as a display name.
email (str | None) – A contact’s primary email address.
event_start (datetime.datetime | None) – A calendar event’s start (timezone-aware).
event_end (datetime.datetime | None) – A calendar event’s end (timezone-aware).
recurrence (str | None) – A calendar event’s recurrence, as a short label.
- class synology_apm_repo.sdk.units.base.Node(ref, name, is_leaf, kind=None, size=None, mtime=None, file_state=FileState.NORMAL, leaf_kind=None, diagnostic=None, role=NodeRole.ORDINARY, degraded=None, columns=<factory>, details=<factory>, export_name=None, handle=None)¶
Bases:
objectOne entry in a provider’s browsable tree; leaves additionally carry
kind/size.- Variables:
ref (synology_apm_repo.sdk.units.node_ref.NodeRef) – This node’s canonical reference.
name (str) – Display name.
is_leaf (bool) – Whether this node is a restorable unit rather than a container.
kind (synology_apm_repo.sdk.units.base.UnitKind | None) – The kind of restorable unit, when known.
size (int | None) – Byte size, when known.
mtime (datetime.datetime | None) – Last-modified time (timezone-aware), when known.
file_state (synology_apm_repo.sdk.units.base.FileState) – A disk-filesystem file’s cloud-sync/encryption state.
leaf_kind (synology_apm_repo.sdk.units.base.UnitKind | None) – For a container, the kind of the restorable units below it, when the provider knows it without listing them.
diagnostic (str | None) – Set on a placeholder standing in for content that could not be read: the user-facing reason. Such a node is not real content (
is_diagnostic).role (synology_apm_repo.sdk.units.base.NodeRole) – How a frontend presents this container.
degraded (str | None) – Set on real content that could only be partly resolved: a short, user-facing reason. Unlike
diagnostic, the node is still real content. On a listed node it means the listing is partial (a Teams chat shown by its raw id, whose unit leaves it unset); on aRestorableUnitit means the content itself is incomplete (a PC/PS disk with missing fragments, known only onceunit()assembles it), which an export reports.columns (synology_apm_repo.sdk.units.base.ItemColumns) – Per-kind fields a frontend lays out as list columns.
details (collections.abc.Mapping[str, object]) – Further display-only metadata (path, ids, …), shown in a frontend’s verbose view and never read for behaviour.
export_name (str | None) – The file name the SDK synthesizes for a leaf with no file name of its own in the backup (a mail’s subject plus
.eml);Nonewhennamealready is the file name.
- columns: ItemColumns¶
- synology_apm_repo.sdk.units.base.node_kind_label(node)¶
node.kind.value, or a generic"folder"/"item"fallback for aNodewhosekindisn’t known.
- class synology_apm_repo.sdk.units.base.RestorableUnit(ref, name, is_leaf, kind=None, size=None, mtime=None, file_state=FileState.NORMAL, leaf_kind=None, diagnostic=None, role=NodeRole.ORDINARY, degraded=None, columns=<factory>, details=<factory>, export_name=None, handle=None, *, content)¶
Bases:
NodeA leaf
Nodeplus a way to actually read its content.contentis already constructed; building one does no I/O until the first read.- content: ContentSource¶
- classmethod of(node, content, **changes)¶
The unit for leaf
node: everyNodefield copied (handleincluded), thenchangesapplied, withcontent.
- class synology_apm_repo.sdk.units.base.UnitProvider(*args, **kwargs)¶
Bases:
ProtocolOne workload version’s browsable tree.
rootis sync and does no I/O;childrenandunitare async in every implementation. Closing isClosableUnitProvider’s contract.- root()¶
The tree’s root node.
- async children(node, offset=0, limit=None)¶
One page of
node’s children in a stable order:limitentries fromoffset, or all remaining whenlimitisNone. A leaf has none.
- async unit(node)¶
Open
nodeas a restorable unit.- Raises:
NotRestorableError –
nodehas no restorable content.
- class synology_apm_repo.sdk.units.base.ClosableUnitProvider(*args, **kwargs)¶
Bases:
UnitProvider,ProtocolA
UnitProviderthat owns open resources (SQLite sources, dedup files) and must be closed once done — withasync with, or by awaitingclosedirectly.- async close()¶
Release what this provider opened.
- class synology_apm_repo.sdk.units.base.SupportsDirectRefLookup(*args, **kwargs)¶
Bases:
ProtocolImplemented only by a provider whose tree addresses every node by a single, depth-independent key (Drive’s
item_id— seetree_strategy.RecursiveTree), for whichfind_node/find_path_with_childrencannot use their usual prefix-guided descent.resolve_extralooks a node up directly, without visiting any other node in the tree (Nonewhen absent).parent_ofwalks one step toward the root (Noneat the version root), for rebuilding the ancestor chain.- async resolve_extra(extra_segments)¶
- async parent_of(node)¶