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

Why an item is not exported; description is 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.

property description: str

How a skipped-item line words this reason, after the item’s name.

class synology_apm_repo.sdk.api.export_tree.TreeItem(node, path, relative)

Bases: object

One item to export: node to path, shown to the user as relative.

node: Node
path: Path
relative: str
class synology_apm_repo.sdk.api.export_tree.SkippedItem(relative, reason)

Bases: object

An item that will not be exported, and why.

relative: str
reason: SkipReason
class synology_apm_repo.sdk.api.export_tree.TreePlan(items, skipped)

Bases: object

The items to export, and the ones skipped while planning.

items: list[TreeItem]
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 under output.

A DISK_FILESYSTEM container (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 synthesized export_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: Enum

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

The first reason a folder export cannot start.

Variables:
  • path (pathlib.Path) – The destination that cannot be written, or for EXISTS the first of the existing destinations.

  • blocker (pathlib.Path | None) – For FILE_IN_THE_WAY, the file standing where a parent folder of path has to be.

  • existing (int) – For EXISTS, how many destinations are already taken.

  • total (int) – For EXISTS, how many items the plan has.

kind: TreeProblemKind
path: Path
blocker: Path | None
existing: int
total: int
message(*, force_hint=False)

This problem as one sentence; force_hint adds the --force advice where the surface has that option.

class synology_apm_repo.sdk.api.export_tree.TreePreflight(problem, preexisting=frozenset({}), directories=frozenset({}))

Bases: object

The outcome of preflight_tree.

Variables:
problem: TreeProblem | None
preexisting: frozenset[Path]
directories: frozenset[Path]
synology_apm_repo.sdk.api.export_tree.preflight_tree(plan, output, *, force)

Checks every destination of plan against 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 unless force is set.

Synchronous, with a few stat() calls per item: call it through asyncio.to_thread from a UI that must stay responsive on a large plan.

class synology_apm_repo.sdk.api.export_tree.IncompleteItem(relative, reason)

Bases: object

An exported item whose content could only be partly resolved, and why (its unit’s degraded).

relative: str
reason: str
class synology_apm_repo.sdk.api.export_tree.TreeExport(exported, skipped, incomplete=<factory>)

Bases: object

What run_tree_export did: 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 staged LocalFileSink.

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_tree returned for plan.

  • sparse (bool) – Leave ZERO/HOLE ranges unwritten where the sink allows it.

  • keep_partial (bool) – Keep an item’s .part file when its export fails or is cancelled.

  • tuning (ExportTuning | None) – Each item’s run_export tuning; with workers each 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 before provider.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’s progress callback for run_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:

TreeExport