synology_apm.sdk.config module

Configuration file read/write — $XDG_CONFIG_HOME/synology-apm/config.toml.

Shared by synology-apm-cli and synology-apm-mcp so both consumers resolve connection settings from the same profile store and keyring entries.

Priority (high → low):

  1. Caller-supplied values (CLI options / explicit arguments)

  2. Environment variables (APM_PROFILE, APM_HOST, APM_USERNAME, APM_PASSWORD, APM_NO_VERIFY_SSL)

  3. Config file ($XDG_CONFIG_HOME/synology-apm/config.toml, default ~/.config/synology-apm/config.toml)

class synology_apm.sdk.config.PasswordStorage(*values)

Bases: Enum

Where a profile’s password is persisted, if at all.

NONE = 'none'
PLAINTEXT = 'plaintext'
KEYRING = 'keyring'
synology_apm.sdk.config.set_keyring_password(profile, username, password)

Store a profile’s password in the OS keyring.

Raises:

KeyringUnavailableError – When the OS keyring backend is unavailable or the write fails.

synology_apm.sdk.config.get_keyring_password(profile, username)

Read a profile’s password from the OS keyring.

Raises:

KeyringUnavailableError – When the OS keyring backend is unavailable or the read fails.

synology_apm.sdk.config.delete_keyring_password(profile, username)

Delete the profile’s OS keyring entry.

Returns True when the entry is gone afterwards (deleted, or it did not exist); False when the keyring backend failed and a stored credential may remain.

class synology_apm.sdk.config.ProfileConfig(host='', username='', password='', no_verify_ssl=False, password_storage=PasswordStorage.NONE, device_id='')

Bases: object

Settings for a single profile.

host: str = ''
username: str = ''
password: str = ''
no_verify_ssl: bool = False
password_storage: PasswordStorage = 'none'
device_id: str = ''
is_complete()

Returns True when both host and username are set.

class synology_apm.sdk.config.AppConfig(profiles=<factory>)

Bases: object

Container for all profile settings.

profiles: dict[str, ProfileConfig]
get_profile(name)

Return the specified profile; returns an empty ProfileConfig if it does not exist.

set_profile(name, profile)

Store a profile (in-memory only; call save_config to persist).

remove_profile(name)

Remove a profile; returns True if a profile was actually removed.

synology_apm.sdk.config.load_config()

Load all profile settings from config.toml.

synology_apm.sdk.config.save_config(config)

Write all profile settings to config.toml.

The config file may hold a plaintext password, so it is written with owner-only permissions (directory 0700, file 0600) and replaced atomically: a failed write never leaves a truncated config.toml behind.

class synology_apm.sdk.config.ResolvedConnection(host, username, password, verify_ssl, profile='default', device_id='')

Bases: object

Connection settings resolved by resolve_connection().

Variables:

  • host (str) – Resolved host (hostname or host:port, no scheme); empty string if unresolved.

  • username (str) – Resolved username; empty string if unresolved.

  • password (str) – Resolved password; may be an empty string (caller must handle this separately).

  • verify_ssl (bool) – Whether to verify the server’s TLS certificate.

  • profile (str) – Name of the profile consulted to resolve these settings (the caller-supplied or environment-selected profile, or DEFAULT_PROFILE).

  • device_id (str) – The profile’s registered trusted-device id, if any (empty string otherwise). Read directly from the resolved profile — unlike host/username/password/ no_verify_ssl, there is no environment-variable or caller-argument override tier for it; see synology-apm-cli’s config set for how a profile registers one.

host: str
username: str
password: str
verify_ssl: bool
profile: str = 'default'
device_id: str = ''
is_complete()

Returns True when both host and username are set.

synology_apm.sdk.config.resolve_connection(*, host=None, username=None, password=None, profile=None, no_verify_ssl=None)

Resolve connection settings by priority.

Priority: caller-supplied values > environment variables > config file (where a config-file profile’s password may itself be stored in plaintext or looked up from the OS keyring).

Parameters:

  • host (str | None) – APM host[:port]. Falls back to APM_HOST, then the resolved profile’s stored host.

  • username (str | None) – APM username. Falls back to APM_USERNAME, then the resolved profile’s stored username.

  • password (str | None) – APM password. Falls back to APM_PASSWORD, then the resolved profile’s stored password (plaintext or OS keyring).

  • profile (str | None) – Config profile name to resolve the other settings against. Falls back to the APM_PROFILE environment variable, then DEFAULT_PROFILE. Resolved independently of the other parameters, before they are.

  • no_verify_ssl (bool | None) – Whether to skip TLS certificate verification. Falls back to APM_NO_VERIFY_SSL, then the resolved profile’s stored setting.

The returned device_id (a registered trusted-device token, if any) is read from the resolved profile — there is no caller-argument or environment-variable override tier for it, unlike every other field above — but only when host/username did not end up overridden away from that profile’s own stored host/username; a device token registered for one host/account is never carried over to a different one just because a profile was consulted for other settings.

Raises:

KeyringUnavailableError – When the profile’s password is stored in the OS keyring and the backend is unavailable or the lookup fails; the caller handles the error message.

Returns:

A ResolvedConnection. Its password may be an empty string (caller must handle this separately).

Return type:

ResolvedConnection

synology_apm.sdk.config.save_profile_device_token(profile, device_id)

Persist a trusted-device id into the given profile.

Creates the profile section if it doesn’t exist yet. Pass an empty string to clear a previously-registered device token. Not a secret (unlike a password), so this always writes directly into the profile section — no keyring involvement.