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 ( |
|
raw ( |
|
human (display names, everything else) |
|
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:
EnumWhich of the module docstring’s three shapes a
NodeRefis.- CANONICAL = 'canonical'¶
- RAW = 'raw'¶
- HUMAN = 'human'¶
- class synology_apm_repo.sdk.units.node_ref.NodeRef(repo_path, segments=(), kind=RefKind.HUMAN)¶
Bases:
objectrepo_pathis a store-relative or filesystem path to the repository root (unencoded — it is a path, not ref content);segmentsare the decoded logical path components after the#(a canonical ref’s first three keep theircat:/wl:/ver:, a raw ref’s first israw);kindis which shape it is.- classmethod parse(text)¶
Inverse of
__str__.- Raises:
ValueError –
texthas 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)¶
refitself, orparse(ref)for its string form.- Raises:
ValueError –
refis 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, elseNone.catalog_idis a plain string, never parsed as an int here — an object-storageCatalogIdis a repo-id string, not always an integer the way a vault’sconnection_config_idis.
- property extra_segments: tuple[str, ...]¶
Segments beyond the fixed prefix — the provider-internal path (mail folder, mail subject, …) for canonical refs; the
file_mappath’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_forcovers that).
- synology_apm_repo.sdk.units.node_ref.canonical_ref_for(repo, version, extra=())¶
NodeRef.canonicalforversion, withinrepo.catalog_idisrepo.layout.repo_idwhen set (unique per bucket), elseversion.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, incatalogs’ own order — feedsdisambiguate()/match_display_name().
- synology_apm_repo.sdk.units.node_ref.workload_pairs(workloads)¶
Same shape as
catalog_pairs, forWorkload, plus each workload’stype_hint— feedsdisambiguate()’shintsalongside itspairs.
- synology_apm_repo.sdk.units.node_ref.version_pairs(versions)¶
Same shape as
catalog_pairs, forVersion.
- 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_idsis(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,Nonewhere inapplicable) is a human differentiator such assub_type: one GWS/M365 account can produce severalWorkloadrows sharing onedisplay_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, forWorkload, folding inworkload_pairs()’stype_hintdisambiguation hint by default.use_type_hint=Falseskips it, forworkloadsalready grouped bytype_hint.
- synology_apm_repo.sdk.units.node_ref.disambiguate_versions(versions)¶
Same idea as
disambiguate_catalogs, forVersion.
- synology_apm_repo.sdk.units.node_ref.match_display_name(target, pairs, objects, *, hints=None)¶
Match
targetagainst the displayed form ofpairs((display_name, stable_id)) after running the collision suffix throughdisambiguate— the same transformls/treeapply, so a name copied straight out of their output resolves back exactly.hintsmust match whatever the display side passed to its owndisambiguatecall for these samepairs.
- synology_apm_repo.sdk.units.node_ref.ambiguous_matches(target, pairs, *, hints=None)¶
The disambiguated names among
pairswhose pre-suffix display name equalstarget. Meant to be called only aftermatch_display_namereturnedNonefor the sametarget/pairs/hints— under that precondition, a non-empty result meanstargetcollided at this level (real ambiguity); empty means it doesn’t exist here at all.