snaphelpers

Helpers for interacting with the Snap system within a Snap.

exception snaphelpers.InvalidKey(key)

The specified key is invalid.

key: str

The invalid key

class snaphelpers.Snap(environ=None)

Top-level wrapper for a Snap.

config: SnapConfig

Access to snap configuration

environ: SnapEnviron

Access to snap environment variables

health: SnapHealth

Access to snap health status

instance_name

Wrapper to get properties from a SnapEnviron instance.

metadata_files: SnapMetadataFiles

Access to snap metadata files

name

The snap name

paths: SnapPaths

Access to snap-specific paths

revision

The snap revision

services: SnapServices

Access to snap services

version

The snap version

class snaphelpers.SnapConfig(snapctl=None)

Interact with the snap configuration.

It allows getting and setting configuration options.

get(key)

Return value for a single key.

Parameters:

key (str) – key to get config for, possibly with dotted notation.

Raises:

UnknownConfigKey – if the option doesn’t exist.

Return type:

Any

get_options(*keys)

Return a SnapConfigOptions for the specified keys.

Parameters:

keys (str) – keys to read configuration for.

Return type:

SnapConfigOptions

set(options)

Set config options.

Parameters:

options (Dict[str, Any]) – a dict with configs. Keys can use dotted notation.

Return type:

None

unset(options)

Unset snap configuration keys.

Parameters:

options (List[str]) – A list of keys to unset. Keys can use dotted notation.

Return type:

None

class snaphelpers.SnapConfigOptions(keys, snapctl=None)

Allow accessing a set of Snap config options with a dict-like interface.

Nested keys can be accessed using dotted notation:

config['foo.bar.baz']
Parameters:

keys (Sequence[str]) – the top-level configuration keys.

as_dict()

Return the configuration as a dict.

Return type:

Dict[str, Any]

fetch()

Fetch (or refresh) configuration for the set of keys.

Return type:

None

get(key, default=None)

Return value for a key, with a default.

Parameters:
  • key (str) – name of the key to return.

  • default (Optional[Any]) – value to return if the key is not found.

Return type:

Any

class snaphelpers.SnapCtl(executable='/usr/bin/snapctl', env=None)

Run the snapctl command.

config_get(*keys)

Return the snap configuration.

Parameters:

keys (str) – a list of config keys to return.

Return type:

dict[str, Any]

config_set(configs)

Set snap configuration.

Parameters:

configs (dict[str, Any]) – a dict with configs. Keys can use dotted notation.

Return type:

None

config_unset(*keys)

Unset snap configuration keys.

Parameters:

keys (str) – config keys to unset.

Return type:

None

connection_set(name, configs)

Set plug or slot configuration.

Parameters:
  • name (str) – the plug/slot name.

  • configs (dict[str, Any]) – a dict with configs. Keys can use dotted notation.

Return type:

None

connection_unset(name, *keys)

Unset plug or slot configuration.

Parameters:
  • name (str) – the plug/slot name.

  • keys (str) – keys to unset. Dotted notation can be used.

Return type:

None

is_connected(name)

Return whether a plug or slot is connected.

Parameters:

name (str) – the plug or slot name.

Return type:

bool

plug_get(name, *keys, remote=False)

Return plug configuration.

Parameters:
  • name (str) – the plug name.

  • keys (str) – a list of config keys to return.

  • remote (bool) – if True, return configs from the remote end.

Return type:

dict[str, Any]

refresh(action=None)

Return refresh state of the snap, optionally requesting an action.

To perform actions, the snap must have the snap-refresh-control interface.

Parameters:

action (Optional[str]) – Optional refresh action to perform, either proceed or hold.

Return type:

dict[str, Any]

restart(*services, reload=False)

Restart all or specified services in the snap.

Parameters:
  • services (str) – a list of services defined in the snap to restart. If not specified, all services will be restarted.

  • reload (bool) – whether to reload services if supported.

Return type:

None

run(*args)

Execute the command and return its output.

Parameters:

args (str) – command args.

Return type:

str

services(*services)

Return info about services in the snap.

Parameters:

services (str) – a list of services to return info for. If not specified, all services are returned.

Return type:

list[ServiceInfo]

set_health(status, message=None, code=None)

Set snap health.

Parameters:
  • status (SnapHealthStatus) – the status to set

  • message (Optional[str]) – an optional message string

  • code (Optional[str]) – an optional code string

Return type:

None

slot_get(name, *keys, remote=False)

Return slot configuration.

Parameters:
  • name (str) – the slot name.

  • keys (str) – a list of config keys to return.

  • remote (bool) – if True, return configs from the remote end.

Return type:

dict[str, Any]

start(*services, enable=False)

Start all or specified services in the snap.

Parameters:
  • services (str) – a list of services defined in the snap to start. If not specified, all services will be started.

  • enable (bool) – whether to also enable services at startup.

Return type:

None

stop(*services, disable=False)

Stop all or specified services in the snap.

Parameters:
  • services (str) – a list of services defined in the snap to stop. If not specified, all services will be stopped.

  • disable (bool) – whether to also disable services at startup.

Return type:

None

system_mode()

Return info on the device current system mode.

Return type:

dict[str, Any]

exception snaphelpers.SnapCtlError(process)

A snapctl command failed.

error: str

The error message

returncode: int

The process return code

class snaphelpers.SnapEnviron(environ=None)

Environment variables related to the Snap.

This provides read-only access to environment variables starting with SNAP_.

These can be accessed either as a dict or as attributes, without the SNAP_ prefix. E.g.:

env = SnapEnviron()
env.NAME     # -> 'mysnap'
env['NAME']  # -> 'mysnap'

Note: The SNAP environment variable is also included.

class snaphelpers.SnapHealth(snapctl=None)

Snap health.

This provides an interfaces for setting health for the snap.

blocked(message, code=None)

Set the status of the snap to “blocked”.

Parameters:
  • message (str) – a message string for the status

  • code (Optional[str]) – an optional code string

Return type:

None

error(message, code=None)

Set the status of the snap to “error”.

Parameters:
  • message (str) – a message string for the status

  • code (Optional[str]) – an optional code string

Return type:

None

okay()

Set the status of the snap to “okay”.

Return type:

None

waiting(message, code=None)

Set the status of the snap to “waiting”.

Parameters:
  • message (str) – a message string for the status

  • code (Optional[str]) – an optional code string

Return type:

None

class snaphelpers.SnapPaths(env=None)

Paths related to the snap.

common: Path

the SNAP_COMMON path

data: Path

the SNAP_DATA path

real_home: Path

the SNAP_REAL_HOME path

snap: Path

the SNAP path

user_common: Path

the SNAP_USER_COMMON path

user_data: Path

the SNAP_USER_DATA path

class snaphelpers.SnapServices(snapctl=None)

Manage services in the snap.

list()

Return services by name.

Return type:

Dict[str, SnapService]

restart(reload=False)

Restart all services.

Parameters:

reload (bool) – whether to reload services if supported.

Return type:

None

start(enable=False)

Start all services.

Parameters:

enable (bool) – whether to also enable services at startup.

Return type:

None

stop(disable=False)

Stop all services.

Parameters:

disable (bool) – whether to also disable services at startup.

Return type:

None

exception snaphelpers.UnknownConfigKey(key)

The specified config key is unknown.

key: str

The unknown key

snaphelpers.is_snap(environ=None)

Return whether running in a Snap.

Parameters:

environ (Optional[Mapping[str, str]]) – optionally, the mapping with environment variables.

Return type:

bool