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

Latest Version Snap Package Build Status Coverage Status Documentation

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.

Table of contents

Indices and tables