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: Enum

Which restorable-unit kind a Node/RestorableUnit is — 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 TeamsChatProvider container’s leaf_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: Enum

A disk-fs file’s cloud-sync/encryption state, carried as Node.file_state — produced other than NORMAL only by units/content/ disk_fs/’s NTFS/APFS backends. CLOUD_ONLY marks 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 listed CLOUD_ONLY; opening it raises ContentUnavailableError with 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: Protocol

The one content-reading contract every RestorableUnit.content satisfies — a DedupFile/ByteRangeView satisfies this shape already, as does assembled content (.eml, .ics, …), so CLI/TUI never need to tell them apart.

property size: int | None

Synchronous; None when the size isn’t known up front (e.g. LazyArtifact before its artifact is assembled). A @property because Protocol attributes are invariant, so a plain field would reject a narrower int.

async read(offset=0, length=None)

Read length bytes starting at offset (default: from offset to the end). A request extending past the content’s own end — including offset starting at or past it — returns only the bytes that exist (possibly none), never an error. A bytearray result belongs to the caller (dedup-backed content returns the buffer it filled rather than copying it into bytes).

Raises:
  • ValueError – offset or length is negative.

  • ResourceLimitExceededError – For a DedupFile-backed implementation, the resolved read size exceeds MAX_SINGLE_READ_SIZE (1 GiB); use stream() for a large read.

stream(block=8388608)

Yield (offset, data) blocks of at most block bytes that cover the content in order.

async export_range(writer, start, end, /, *, sparse=True, progress=None, tuning=None)

Writes the content’s [start, end) into writer, which the caller has already opened and will commit or abort itself (api.run_export does all of it), at offsets relative to start. sparse=True may leave ZERO/HOLE ranges unwritten. progress receives each newly written byte count as it is handed to writer (the counts add up to planned_bytes over the range); tuning is 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_range over [start, end) reports as progress: the real DATA bytes for dedup-backed content, the whole range for content without holes.

class synology_apm_repo.sdk.units.base.NodeRole(*values)

Bases: Enum

How 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: object

The per-kind fields of a listed item a frontend lays out as list columns; each is None where 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.

sender: str | None
email: str | None
event_start: datetime | None
event_end: datetime | None
recurrence: str | None
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: object

One 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 a RestorableUnit it means the content itself is incomplete (a PC/PS disk with missing fragments, known only once unit() 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); None when name already is the file name.

ref: NodeRef
name: str
is_leaf: bool
kind: UnitKind | None
size: int | None
mtime: datetime | None
file_state: FileState
leaf_kind: UnitKind | None
diagnostic: str | None
role: NodeRole
degraded: str | None
columns: ItemColumns
details: Mapping[str, object]
export_name: str | None
handle: object

What the provider that built this node needs to find its children or content again (a tree key, a disk’s fragments, …). Opaque to every other caller and never displayed; only that provider reads it.

property is_diagnostic: bool

Whether this node is a placeholder rather than real content.

synology_apm_repo.sdk.units.base.node_kind_label(node)

node.kind.value, or a generic "folder"/"item" fallback for a Node whose kind isn’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: Node

A leaf Node plus a way to actually read its content.

content is already constructed; building one does no I/O until the first read.

content: ContentSource
classmethod of(node, content, **changes)

The unit for leaf node: every Node field copied (handle included), then changes applied, with content.

class synology_apm_repo.sdk.units.base.UnitProvider(*args, **kwargs)

Bases: Protocol

One workload version’s browsable tree.

root is sync and does no I/O; children and unit are async in every implementation. Closing is ClosableUnitProvider’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: limit entries from offset, or all remaining when limit is None. A leaf has none.

async unit(node)

Open node as a restorable unit.

Raises:

NotRestorableError – node has no restorable content.

class synology_apm_repo.sdk.units.base.ClosableUnitProvider(*args, **kwargs)

Bases: UnitProvider, Protocol

A UnitProvider that owns open resources (SQLite sources, dedup files) and must be closed once done — with async with, or by awaiting close directly.

async close()

Release what this provider opened.

class synology_apm_repo.sdk.units.base.SupportsDirectRefLookup(*args, **kwargs)

Bases: Protocol

Implemented only by a provider whose tree addresses every node by a single, depth-independent key (Drive’s item_id — see tree_strategy.RecursiveTree), for which find_node/ find_path_with_children cannot use their usual prefix-guided descent.

resolve_extra looks a node up directly, without visiting any other node in the tree (None when absent). parent_of walks one step toward the root (None at the version root), for rebuilding the ancestor chain.

async resolve_extra(extra_segments)
async parent_of(node)