snap-helpers 0.4.2

Helpers for interacting 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.