synology_apm_repo.sdk.api.export_paths module

File-name safety for an export into a local directory: refusing a backed-up name that would escape the destination or be invalid on the platform, and sanitizing one into a safe file name.

synology_apm_repo.sdk.api.export_paths.WINDOWS_FORBIDDEN_NAME_CHARS: frozenset[str] = frozenset({'\x00', '\x01', '\x02', '\x03', '\x04', '\x05', '\x06', '\x07', '\x08', '\t', '\n', '\x0b', '\x0c', '\r', '\x0e', '\x0f', '\x10', '\x11', '\x12', '\x13', '\x14', '\x15', '\x16', '\x17', '\x18', '\x19', '\x1a', '\x1b', '\x1c', '\x1d', '\x1e', '\x1f', '"', '*', ':', '<', '>', '?', '|'})

Characters Windows rejects in a file name, besides the path separators.

synology_apm_repo.sdk.api.export_paths.windows_reserved_basename(name)

Whether name is a Windows reserved device name (CON, NUL, COM1, …), with or without an extension after it.

synology_apm_repo.sdk.api.export_paths.safe_export_join(root, *segments)

Joins segments onto root, rejecting any segment that could escape it — for building a local export destination path from Node.name values collected while walking a tree (outermost container first). A name is display text, possibly from a file inside a backed-up guest, not necessarily a single safe path component.

Rejects rather than sanitizes, so a bulk export never silently collides or misleads; the caller decides from the raised exception whether to skip, log or rename.

root itself is never validated: it is the caller’s own trusted output directory.

Parameters:
  • root (Path) – The trusted local directory every joined path stays under.

  • segments (str) – One path component per tree level, outermost first.

Raises:

ValueError – a segment is empty, "."/"..", or contains a path separator (/ or a backslash, which also rules out absolute paths) or a NUL byte; on Windows also one that is not a plain file name there (a :, another forbidden character, a trailing . or space, or a reserved device name).

synology_apm_repo.sdk.api.export_paths.safe_file_name(name)

name made into one safe path component on this system — for a file name the SDK synthesizes (Node.export_name) or only suggests, never for a name from the backup, which safe_export_join rejects rather than alters.

Replaces each path separator and NUL (on Windows, each forbidden character too) with _; on Windows also strips a trailing ./space and prefixes a reserved device name with _. A result that is empty, . or .. becomes _.