synology_apm_repo.sdk.units.node_ref module

NodeRef — a stable, round-trippable string address for any browsable node, shared by CLI arguments, TUI breadcrumbs/bookmarks and error messages.

Three shapes share the same <repo-path>#<seg>/<seg>/... structure. The machine-made ones start their fragment with @, so which shape a ref is never depends on what a display name looks like:

shape

example

canonical (@cat:/wl:/ver: prefixed)

repository#@cat:1/wl:2/ver:abc-uid/Inbox/Subject

raw (file_map fallback axis, diagnostic-mode only)

repository#@raw/VM-uid/.../disk.img

human (display names, everything else)

repository#Test-Workload-01/CORP-PC-001/2026-08-07 09:00

A human ref whose first name starts with @ writes it as %40.

Canonical refs are stable across display-name changes — the right form for scripts and bookmarks. Human refs are what breadcrumbs and ls show; disambiguate appends a hash suffix when two same-level nodes would otherwise show the same name.

Escaping: a segment may itself contain #, /, %, or control characters — each is percent-encoded before segments join with /, decoded back on split, so round-tripping through str(ref) / NodeRef.parse is always safe. repo_path itself is never encoded (split off at the first #), so a literal # inside it can’t round-trip. A lone empty-string segment (NodeRef(path, ("",))) isn’t representable either: it encodes identically to no segments at all.

class synology_apm_repo.sdk.units.node_ref.RefKind(*values)

Bases: Enum

Which of the module docstring’s three shapes a NodeRef is.

CANONICAL = 'canonical'
RAW = 'raw'
HUMAN = 'human'
class synology_apm_repo.sdk.units.node_ref.NodeRef(repo_path, segments=(), kind=RefKind.HUMAN)

Bases: object

repo_path is a store-relative or filesystem path to the repository root (unencoded — it is a path, not ref content); segments are the decoded logical path components after the # (a canonical ref’s first three keep their cat:/wl:/ver:, a raw ref’s first is raw); kind is which shape it is.

repo_path: str
segments: tuple[str, ...]
kind: RefKind
classmethod parse(text)

Inverse of __str__.

Raises:

ValueError – text has no # at all (not a ref), its @ form is neither @cat: nor @raw, or a segment’s percent-encoding is not valid UTF-8.

classmethod coerce(ref)

ref itself, or parse(ref) for its string form.

Raises:

ValueError – ref is a string that is not a ref.

property canonical_ids: tuple[CatalogId, WorkloadId, VersionUid] | None

(catalog_id, workload_id, version_uid) if this is a canonical ref with a well-formed prefix, else None. catalog_id is a plain string, never parsed as an int here — an object-storage CatalogId is a repo-id string, not always an integer the way a vault’s connection_config_id is.

property extra_segments: tuple[str, ...]

Segments beyond the fixed prefix — the provider-internal path (mail folder, mail subject, …) for canonical refs; the file_map path’s own components (one per path segment — join with "/" to recover the literal path) for raw; everything, for human refs.

classmethod canonical(repo_path, *, catalog_id, workload_id, version_uid, extra=())
classmethod raw(repo_path, file_map_path)
classmethod human(repo_path, *names)
child(*extra)

Extends this ref’s segments by extra — for a provider appending segments to an already-resolved node’s ref (a diagnostic leaf, synthetic entry, …), not the version root (canonical_ref_for covers that).

synology_apm_repo.sdk.units.node_ref.canonical_ref_for(repo, version, extra=())

NodeRef.canonical for version, within repo.

catalog_id is repo.layout.repo_id when set (unique per bucket), else version.connection_config_id — unique within a vault, and an object-storage repo with no derivable repo-id is the only catalog reachable from its root.

synology_apm_repo.sdk.units.node_ref.catalog_pairs(catalogs)

(display_name, catalog_id) pairs, in catalogs’ own order — feeds disambiguate()/match_display_name().

synology_apm_repo.sdk.units.node_ref.workload_pairs(workloads)

Same shape as catalog_pairs, for Workload, plus each workload’s type_hint — feeds disambiguate()’s hints alongside its pairs.

synology_apm_repo.sdk.units.node_ref.version_pairs(versions)

Same shape as catalog_pairs, for Version.

synology_apm_repo.sdk.units.node_ref.disambiguate(names_and_ids, *, hints=None)

Append a disambiguating suffix to every name that collides with another at the same tree level (the same call’s list); names with no collision are returned unchanged. names_and_ids is (display_name, canonical_id) — the stable id, never the display name, is what the hash fallback is derived from, so a suffix stays the same across renames.

hints (parallel, None where inapplicable) is a human differentiator such as sub_type: one GWS/M365 account can produce several Workload rows sharing one display_name (the account’s name/email), so a hash alone reads as duplicates. A hint that resolves the collision is used instead ("Alice Example <...> · MAIL"); the hash still applies, appended after the hint, to whatever the hint doesn’t resolve.

synology_apm_repo.sdk.units.node_ref.disambiguate_catalogs(catalogs)

Disambiguated display names for catalogs, in the same order.

synology_apm_repo.sdk.units.node_ref.disambiguate_workloads(workloads, *, use_type_hint=True)

Same idea as disambiguate_catalogs, for Workload, folding in workload_pairs()’s type_hint disambiguation hint by default. use_type_hint=False skips it, for workloads already grouped by type_hint.

synology_apm_repo.sdk.units.node_ref.disambiguate_versions(versions)

Same idea as disambiguate_catalogs, for Version.

synology_apm_repo.sdk.units.node_ref.match_display_name(target, pairs, objects, *, hints=None)

Match target against the displayed form of pairs ((display_name, stable_id)) after running the collision suffix through disambiguate — the same transform ls/tree apply, so a name copied straight out of their output resolves back exactly.

hints must match whatever the display side passed to its own disambiguate call for these same pairs.

synology_apm_repo.sdk.units.node_ref.ambiguous_matches(target, pairs, *, hints=None)

The disambiguated names among pairs whose pre-suffix display name equals target. Meant to be called only after match_display_name returned None for the same target/pairs/hints — under that precondition, a non-empty result means target collided at this level (real ambiguity); empty means it doesn’t exist here at all.