snap-helpers - Interact with the Snap system within a Snap

A Python library to interact with snap configuration and properties from inside a snap.

It exposes a top-level snaphelpers.Snap object which provides access to:

snap details:

>>> snap = snaphelpers.Snap()
>>> snap.name
'snap-helpers'
>>> snap.instance_name
'snap-helpers'
>>> snap.version
'0.3.0+git5.5794660'
>>> snap.revision
'138'

paths:

>>> snap.paths.common
PosixPath('/var/snap/snap-helpers/common')
>>> snap.paths.data
PosixPath('/var/snap/snap-helpers/138')
>>> snap.paths.real_home
PosixPath('/home/ack')
>>> snap.paths.snap
PosixPath('/snap/snap-helpers/138')
>>> snap.paths.user_common
PosixPath('/home/ack/snap/snap-helpers/common')
>>> snap.paths.user_data
PosixPath('/home/ack/snap/snap-helpers/138')

snap-related environment variables:

>>> pprint.pprint(dict(snap.environ))
{'ARCH': 'amd64',
 'COMMON': '/var/snap/snap-helpers/common',
 'CONTEXT': 'XbhAD8QBMDwJiEi5LcN-5fCrVeAG7qBGojWiWA0vXkx0hX-JxyqX',
 'COOKIE': 'XbhAD8QBMDwJiEi5LcN-5fCrVeAG7qBGojWiWA0vXkx0hX-JxyqX',
 'DATA': '/var/snap/snap-helpers/138',
 'INSTANCE_KEY': '',
 'INSTANCE_NAME': 'snap-helpers',
 'LIBRARY_PATH': '/var/lib/snapd/lib/gl:/var/lib/snapd/lib/gl32:/var/lib/snapd/void',
 'NAME': 'snap-helpers',
 'REAL_HOME': '/home/ack',
 'REEXEC': '',
 'REVISION': '138',
 'SNAP': '/snap/snap-helpers/138',
 'USER_COMMON': '/home/ack/snap/snap-helpers/common',
 'USER_DATA': '/home/ack/snap/snap-helpers/138',
 'VERSION': '0.3.0+git5.5794660'}
>>> snap.environ.ARCH
'amd64'

configuration options:

>>> snap.config.set({'foo.bar': 'baz', 'asdf': 3})  # this needs to be run as root
>>> options = snap.config.get_options('foo', 'asdf')
>>> options['foo']
{'bar': 'baz'}
>>> options['foo.bar']
'baz'
>>> options['asdf']
3
>>> options.as_dict()
{'asdf': 3, 'foo': {'bar': 'baz'}}

setting snap health status, along with message and optional status code:

>>> snap.health.okay()
>>> snap.health.waiting('foo must happen first', code='wait-foo')

Health status (when different from okay) is visible from the snap CLI:

$ snap info snap-helpers
name:    snap-helpers
summary: Test snap for snap-helpers
health:
  status:  waiting
  message: foo must happen first
  code:    wait-foo
  checked: today at 16:23 CEST

content of snap metadata files such as:

snap/metadata.yaml
meta/snap.yaml
snap/snapcraft.yaml

These can be accessed as follows:

>>> snap.metadata_files.snap
SnapMetadataFile('/snap/snap-helpers/138/meta/snap.yaml')
>>> snap.metadata_files.snap.path
PosixPath('/snap/snap-helpers/138/meta/snap.yaml')
>>> snap.metadata_files.snap["name"]
'snap-helpers'
>>> snap.metadata_files.snap["base"]
'core22'
>>> pprint.pprint(dict(snap.metadata_files.snap))
{'apps': {'python': {'command': 'bin/python3',
                     'plugs': ['home', 'network', 'network-bind']},
          'snap-helpers': {'command': 'bin/snap-helpers-shell',
                           'plugs': ['home', 'network', 'network-bind']}},
 'architectures': ['amd64'],
 'base': 'core22',
 'confinement': 'strict',
 'description': 'Test snap for the snap-helpers Python library.\n'
                '\n'
                'It provides python and ipython shells to interact and test '
                'the `snaphelpers`\n'
                'library.\n'
                '\n'
                'See the https://github.com/albertodonato/snap-helpers for '
                'more details.\n',
 'environment': {'LD_LIBRARY_PATH': '${SNAP_LIBRARY_PATH}${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}:$SNAP/lib',
                 'PATH': '$SNAP/usr/sbin:$SNAP/usr/bin:$SNAP/sbin:$SNAP/bin:$PATH'},
 'grade': 'stable',
 'license': 'LGPL-3.0',
 'name': 'snap-helpers',
 'slots': {'snap-helpers-lib': {'content': 'snap-helpers-lib',
                                'interface': 'content',
                                'read': ['$SNAP/lib/python3.10/site-packages/snaphelpers']}},
 'summary': 'Test snap for the snap-helpers Python library.',
 'version': '0.3.0+git5.5794660'}

Hook helpers

The library provides helpers to reduce boilerplate when setting up hooks for the snap, by using entry-points in the package metadata.

This can be done in setup.py:

setup(
    # ...
    entry_points={
        "snaphelpers.hooks": [
            "configure = testapp:configure_hook",
            "install = testapp:install_hook",
        ]
    }
)

or in setup.cfg:

[options.entry_points]
snaphelpers.hooks =
    configure = testapp:configure_hook
    install = testapp:install_hook

or in pyproject.toml:

[project.entry-points."snaphelpers.hooks"]
configure = "testapp:configure_hook"
install = "testapp:install_hook"

Hook functions are called with a Snap object as argument:

def install_hook(snap: snaphelpers.Snap):
    # ...


def configure_hook(snap: snaphelpers.Snap):
    # ...

snap-helpers will take care of the hooks plumbing (i.e. creating hook files in $SNAP/snap/hooks).

Supported snap bases

Currently supported snap bases are:

core20 (Python 3.8)
core22 (Python 3.10)

The core18 base (with Python 3.6) is supported until the 0.3.2 release.

Testing with the snap

The snap-helpers snap provides a way to easily test code using the library in a real snap environment with strict confinement.

It provides an IPython shell which automatically imports the snaphelpers module and provides a Snap instance for the current snap.

$ snap-helpers
Python 3.10.4 (main, Jun 29 2022, 12:14:53) [GCC 11.2.0]
Type 'copyright', 'credits' or 'license' for more information
IPython 8.7.0 -- An enhanced Interactive Python. Type '?' for help.


Use the "snap" variable for an instance for the current snap.

In [1]: import pprint

In [2]: pprint.pprint(dict(snap.environ))
{'ARCH': 'amd64',
 'COMMON': '/var/snap/snap-helpers/common',
 'CONTEXT': 'XbhAD8QBMDwJiEi5LcN-5fCrVeAG7qBGojWiWA0vXkx0hX-JxyqX',
 'COOKIE': 'XbhAD8QBMDwJiEi5LcN-5fCrVeAG7qBGojWiWA0vXkx0hX-JxyqX',
 'DATA': '/var/snap/snap-helpers/138',
 'INSTANCE_KEY': '',
 'INSTANCE_NAME': 'snap-helpers',
 'LIBRARY_PATH': '/var/lib/snapd/lib/gl:/var/lib/snapd/lib/gl32:/var/lib/snapd/void',
 'NAME': 'snap-helpers',
 'REAL_HOME': '/home/ack',
 'REEXEC': '',
 'REVISION': '138',
 'SNAP': '/snap/snap-helpers/138',
 'USER_COMMON': '/home/ack/snap/snap-helpers/common',
 'USER_DATA': '/home/ack/snap/snap-helpers/138',
 'VERSION': '0.3.0+git5.5794660'}

The snap can be built and installed as follows:

$ snapcraft -v
$ sudo snap install --dangerous snap-helpers_*.snap

Installation

snap-helpers can be installed from PyPI.

Run:

$ pip install snap-helpers

Documentation

Full documentation is available on ReadTheDocs.