synology_apm_repo.sdk.api.export_tree module¶
Exporting a folder: plan_tree_export maps each item below it to a
destination, preflight_tree checks those destinations against the disk,
and run_tree_export writes the items.
Names come from the backup (possibly from a file inside a guest), so every
destination goes through safe_export_join, which rejects rather than
renames: an item whose name cannot be one safe path component, or whose
destination another item already takes, is skipped and reported, never
written somewhere else. Only a name the SDK synthesizes
(Node.export_name) is sanitized and numbered instead, since the backup
never promised it as a file name.
- class synology_apm_repo.sdk.api.export_tree.SkipReason(*values)¶
Bases:
StrEnumWhy an item is not exported;
descriptionis how the CLI and the Browser both word it.- MISSING_DATA = 'missing_data'¶
The backup refers to data it could not find (a diagnostic placeholder).
- UNSAFE_NAME = 'unsafe_name'¶
The item’s name is not one safe path component on this system.
- PATH_TAKEN = 'path_taken'¶
Another item already takes the destination path.
- NO_CONTENT = 'no_content'¶
The item has no content to export.
- class synology_apm_repo.sdk.api.export_tree.TreeItem(node, path, relative)¶
Bases:
objectOne item to export:
nodetopath, shown to the user asrelative.
- class synology_apm_repo.sdk.api.export_tree.SkippedItem(relative, reason)¶
Bases:
objectAn item that will not be exported, and why.
- reason: SkipReason¶
- class synology_apm_repo.sdk.api.export_tree.TreePlan(items, skipped)¶
Bases:
objectThe items to export, and the ones skipped while planning.
- skipped: list[SkippedItem]¶
- async synology_apm_repo.sdk.api.export_tree.plan_tree_export(provider, folder, output)¶
Every exportable item below
folder, depth-first in provider order, with its destination underoutput.A
DISK_FILESYSTEMcontainer (a disk image’s “(filesystem)” browse view) is left out without a note: its files are the same bytes as the disk image exported beside it. A diagnostic placeholder (data the backup refers to but could not find) is skipped and reported. Same-named sibling folders merge into one; files that then share a path are skipped and reported, except under a synthesizedexport_name, which takes the first free `` (2)``, `` (3)``, … variant — compared case-insensitively, since the destination’s filesystem may be.
- class synology_apm_repo.sdk.api.export_tree.TreeProblemKind(*values)¶
Bases:
EnumWhat stops a folder export before it writes anything.
- DIRECTORY_IN_THE_WAY = 'directory_in_the_way'¶
- FILE_IN_THE_WAY = 'file_in_the_way'¶
- EXISTS = 'exists'¶
- class synology_apm_repo.sdk.api.export_tree.TreeProblem(kind, path, blocker=None, existing=0, total=0)¶
Bases:
objectThe first reason a folder export cannot start.
- Variables:
path (pathlib.Path) – The destination that cannot be written, or for
EXISTSthe first of theexistingdestinations.blocker (pathlib.Path | None) – For
FILE_IN_THE_WAY, the file standing where a parent folder ofpathhas to be.existing (int) – For
EXISTS, how many destinations are already taken.total (int) – For
EXISTS, how many items the plan has.
- kind: TreeProblemKind¶
- message(*, force_hint=False)¶
This problem as one sentence;
force_hintadds the--forceadvice where the surface has that option.
- class synology_apm_repo.sdk.api.export_tree.TreePreflight(problem, preexisting=frozenset({}), directories=frozenset({}))¶
Bases:
objectThe outcome of
preflight_tree.- Variables:
problem (synology_apm_repo.sdk.api.export_tree.TreeProblem | None) – Why the export cannot start, or
Nonewhen it can.preexisting (frozenset[pathlib.Path]) – The destinations that were already on disk, which a run with
forcereplaces.directories (frozenset[pathlib.Path]) – Folders found to exist, so
run_tree_exportneed not look again.
- problem: TreeProblem | None¶
- synology_apm_repo.sdk.api.export_tree.preflight_tree(plan, output, *, force)¶
Checks every destination of
planagainst the disk, before the first write.A directory where an item goes, or a file where one of its parent folders goes, is a problem even with
force, which only replaces files. Otherwise an existing destination is a problem unlessforceis set.Synchronous, with a few
stat()calls per item: call it throughasyncio.to_threadfrom a UI that must stay responsive on a large plan.
- class synology_apm_repo.sdk.api.export_tree.IncompleteItem(relative, reason)¶
Bases:
objectAn exported item whose content could only be partly resolved, and why (its unit’s
degraded).
- class synology_apm_repo.sdk.api.export_tree.TreeExport(exported, skipped, incomplete=<factory>)¶
Bases:
objectWhat
run_tree_exportdid: the items written with their results, everything skipped, and which written items are incomplete.- exported: list[tuple[TreeItem, ExportResult]]¶
- skipped: list[SkippedItem]¶
- incomplete: list[IncompleteItem]¶
- property totals: ExportResult¶
Every exported item’s result, summed.
- type _tree.ExportProgressCallback = Callable[[int, int], Awaitable[None]]¶
Receives an export’s
(done, total)byte counts as data is written.
- async synology_apm_repo.sdk.api.export_tree.run_tree_export(provider, plan, output, *, preflight, sparse=True, keep_partial=False, tuning=None, on_item_start=None, on_item_done=None)¶
Exports
plan’s items one at a time, each through its own stagedLocalFileSink.Names differing only in case are one path on a case-insensitive filesystem, which the plan cannot see, so an item whose destination appeared during this run (or is a file this run already wrote) is skipped rather than overwritten. The first failure stops the run and propagates; items already written stay.
- Parameters:
preflight (TreePreflight) – What
preflight_treereturned forplan.sparse (bool) – Leave
ZERO/HOLEranges unwritten where the sink allows it.keep_partial (bool) – Keep an item’s
.partfile when its export fails or is cancelled.tuning (ExportTuning | None) – Each item’s
run_exporttuning; withworkerseach item starts and stops its own pool of worker processes.on_item_start (Callable[[int, TreeItem, LocalFileSink], ExportProgressCallback | None] | None) – Called with the item’s index in
plan.items, the item, and its sink beforeprovider.unit()opens it, so a caller can say what is in flight while that runs; the item may still turn out to have no content and be skipped. May return this item’sprogresscallback forrun_export.on_item_done (Callable[[TreeItem, ExportResult], None] | None) – Called after each item is written.
- Returns:
The items written, the items skipped (the plan’s included), and the written items that are incomplete.
- Return type: