synology_apm_repo.sdk.profiles package

Saved S3/Azure/SMB connection profiles, shared by the CLI and TUI: the non-secret half in profiles.json, secrets in the OS keyring. Outside the layer stack: it builds ObjectStore instances and lists a backend’s buckets/containers through storage, but reads no repository.

The I/O functions are async, running file and keyring access off the event loop (a keyring prompt must not freeze the TUI). config_dir overrides the per-user config directory. get_profile and the listing functions never touch the keyring, so they can’t leak a secret; profile_fields_with_secrets and store_from_profile read it.

class synology_apm_repo.sdk.profiles.AzureProfileConfig(container, account_url=None, verify_tls=True)

Bases: object

Non-secret AzureStore constructor inputs. credential is not a field here — see secrets.py.

kind: ClassVar[BackendKind] = 'azure'
container: str
account_url: str | None
verify_tls: bool
open_store(**client_kwargs)

The AzureStore for this container; see S3ProfileConfig.open_store.

Raises:

ProfileFieldError – Azure rejected account_url (missing or malformed).

property client_kwargs: dict[str, Any]

AzureStore kwargs for everything but container and the secret (TLS verification is connection_verify there).

property display_fields: dict[str, str | None]

Same role as S3ProfileConfig.display_fields.

property label: str

azure://<container>; see S3ProfileConfig.label.

class synology_apm_repo.sdk.profiles.BackendKind(*values)

Bases: StrEnum

Which backend a profile targets; the value is also its CLI/TUI name.

S3 = 's3'
AZURE = 'azure'
SMB = 'smb'
class synology_apm_repo.sdk.profiles.Profile(name, config)

Bases: object

One saved profile, keyed by its user-chosen name (unique across every backend kind). Never carries secret values.

name: str
config: S3ProfileConfig | AzureProfileConfig | SmbProfileConfig
property kind: BackendKind

The backend this profile targets, its config’s kind.

exception synology_apm_repo.sdk.profiles.ProfileConfigCorruptError(message, *, ref=None, spec=None)

Bases: ApmRepoError

profiles.json failed to parse, or failed schema validation (bad schema_version, unknown kind, missing/malformed field). Not a DataCorruptError: the file is local configuration, not repository data.

exception synology_apm_repo.sdk.profiles.ProfileFieldError(field, message)

Bases: ValueError

A connection-profile field is missing or malformed (a blank required field, a non-numeric port): a user-input problem, hence a ValueError rather than part of the on-disk-data hierarchy.

Variables:

field – The canonical field name ("bucket", "port", …).

class synology_apm_repo.sdk.profiles.ProfileFieldSpec(name, strip=True, is_checkbox=False, is_port=False, required=False, secret=False, prompt='')

Bases: object

One profile field, in canonical collection/display order for its backend: what a connection form binds and how config_from_fields reads it.

Variables:
  • name (str) – The canonical field name.

  • strip (bool) – Whether leading/trailing whitespace is dropped; False where it might be significant (secret_key/credential/password).

  • is_checkbox (bool) – A boolean field, true when absent.

  • is_port (bool) – A port number, DEFAULT_SMB_PORT when blank.

  • required (bool) – Must be non-blank.

  • secret (bool) – Kept in the OS keyring, never in profiles.json.

  • prompt (str) – The interactive prompt for a secret field.

name: str
strip: bool
is_checkbox: bool
is_port: bool
required: bool
secret: bool
prompt: str
exception synology_apm_repo.sdk.profiles.ProfileNotFoundError(message, *, ref=None, spec=None)

Bases: NotFoundError

The named S3/Azure/SMB connection profile does not exist in profiles.json.

exception synology_apm_repo.sdk.profiles.ProfileSecretBackendUnavailableError(message, *, ref=None, spec=None)

Bases: ApmRepoError

No usable OS keyring backend can store or retrieve a profile’s secret fields: keyring failed to import or resolved no real backend (e.g. headless Linux without Secret Service).

class synology_apm_repo.sdk.profiles.S3ProfileConfig(bucket, endpoint=None, region=None, verify_tls=True)

Bases: object

Non-secret S3Store constructor inputs. access_key/ secret_key are not fields here — see secrets.py.

kind: ClassVar[BackendKind] = 's3'
bucket: str
endpoint: str | None
region: str | None
verify_tls: bool
open_store(**client_kwargs)

The S3Store for this bucket, built with client_kwargs (client_kwargs_with_secrets’s result).

property client_kwargs: dict[str, Any]

S3Store kwargs for everything but bucket and the secrets.

property display_fields: dict[str, str | None]

Ordered field name -> value pairs the CLI and TUI display.

property label: str

s3://<bucket>, how CLI/TUI name the store this config opens.

class synology_apm_repo.sdk.profiles.SmbProfileConfig(server, share, port=445, username=None)

Bases: object

Non-secret SmbStore constructor inputs. password is not a field here — see secrets.py. username may carry a domain as DOMAIN\username or user@domain; a profile names a whole share.

kind: ClassVar[BackendKind] = 'smb'
server: str
share: str
port: int
username: str | None
open_store(**client_kwargs)

The SmbStore for this share; see S3ProfileConfig.open_store.

property client_kwargs: dict[str, Any]

SmbStore kwargs for everything but share and the secret.

property display_fields: dict[str, str | int | None]

Same role as S3ProfileConfig.display_fields.

property label: str

smb://<server>/<share>; see S3ProfileConfig.label.

synology_apm_repo.sdk.profiles.account_client_kwargs(kind, fields)

The account-level client kwargs (no bucket/container chosen yet) that list_remote_items takes, from a connection form’s raw fields.

synology_apm_repo.sdk.profiles.config_from_fields(kind, fields, *, check_required=True)

fields (canonical names, as a connection form or the CLI collects them; extra keys, secrets included, are ignored) turned into kind’s config. A blank optional field means “not set”; a blank port means DEFAULT_SMB_PORT. check_required=False accepts blank required fields, for an account-level operation (listing buckets) that has none chosen yet.

Raises:

ProfileFieldError – A required field is blank, or the port is not a number.

async synology_apm_repo.sdk.profiles.delete_profile(name, *, config_dir=None)

Remove profile name and its keyring secrets; the profiles.json entry goes first.

Raises:
synology_apm_repo.sdk.profiles.form_fields_for(kind)

kind’s full field list, in canonical order — every field a connection form binds, secrets included.

async synology_apm_repo.sdk.profiles.get_profile(name, *, config_dir=None)

The non-secret half of profile name, safe to display or log.

Raises:
async synology_apm_repo.sdk.profiles.list_profiles(*, config_dir=None)

Every saved profile’s non-secret half, sorted by name, from one read of profiles.json.

Raises:

ProfileConfigCorruptError – profiles.json is unreadable or invalid.

async synology_apm_repo.sdk.profiles.list_remote_items(kind, **client_kwargs)

Every bucket (S3) or container (Azure) reachable with the resolved client_kwargs (see account_client_kwargs).

Raises:

ValueError – kind is SMB, which has no account-level listing.

async synology_apm_repo.sdk.profiles.profile_fields_with_secrets(name, *, config_dir=None)

Every field of profile name, secrets included and unmasked, under the canonical field names, for refilling a connection form; use get_profile for anything displayed or logged.

Raises:
async synology_apm_repo.sdk.profiles.save_profile(name, kind, fields, *, config_dir=None)

Save profile name, replacing an existing one’s non-secret half; secrets are merged into those already stored (an empty one is left as stored). fields uses profile_fields_with_secrets’s canonical names. The fields and the existing profiles.json are checked before anything is written, and secrets are written before profiles.json, so a listed profile never lacks its secrets.

Raises:
async synology_apm_repo.sdk.profiles.store_from_config(config, secret_source)

The ObjectStore for config with credentials from secret_source (see client_kwargs_with_secrets), saved as a profile or not.

Raises:

ProfileFieldError – Azure rejected account_url (missing or malformed); S3 and SMB check their settings on first use.

async synology_apm_repo.sdk.profiles.store_from_fields(kind, fields)

store_from_config for a not-yet-saved connection form’s raw fields (secrets included, canonical names).

Raises:

ProfileFieldError – A required field is blank or malformed, or (see store_from_config) Azure rejected account_url.

async synology_apm_repo.sdk.profiles.store_from_profile(name, *, config_dir=None)

Profile name with its keyring secrets, as a store for Session.discover()/open(); the session then owns and closes it.

Raises:

Submodules