feat(snap): add snap conf module

snap/src/charmlibs/snap/__init__.py

@@ -23,7 +23,7 @@
 
 - Automatic refreshes with :func:`hold` and :func:`unhold`.
 - Services with :func:`start`, :func:`stop`, and :func:`restart`.
-- Config with :func:`config_get`, :func:`config_set`, and :func:`config_unset`.
+- Config with :func:`get`, :func:`set`, and :func:`unset`.
 - Connections between snaps with :func:`connect` and :func:`disconnect`.
 - Application aliases with :func:`alias` and :func:`unalias`.
 
@@ -68,6 +68,11 @@
     start,
     stop,
 )
+from ._snapd_conf import (
+    get,
+    set,  # noqa: A004 (shadowing a Python builtin)
+    unset,
+)
 from ._snapd_logs import (
     LogEntry,
     logs,
@@ -101,14 +106,17 @@
     'TimeoutError',
     'ensure',
     'ensure_revision',
+    'get',
     'hold',
     'info',
     'install',
     'logs',
     'refresh',
     'remove',
     'restart',
+    'set',
     'start',
     'stop',
     'unhold',
+    'unset',
 ]

snap/src/charmlibs/snap/_errors.py

@@ -127,7 +127,11 @@ class AppNotFoundError(APIError):
 
 
 class NotFoundError(APIError):
-    """Raised via the API when a snap is not found in the store."""
+    """Raised via the API when a snap is not found.
+
+    Depending on the operation, this means not found in the store (for example install),
+    or not installed on the system (for example configuration operations).
+    """
 
 
 class NotInstalledError(APIError):

snap/src/charmlibs/snap/_snapd_conf.py

@@ -0,0 +1,164 @@
+# Copyright 2026 Canonical Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Snap operations implemented as direct calls to the snapd REST API."""
+
+from __future__ import annotations
+
+import logging
+import typing
+
+from . import _client, _errors
+
+if typing.TYPE_CHECKING:
+    from collections.abc import Iterable
+    from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+# /v2/snaps/{snap}/conf
+
+
+# Getting one config value looks like get(s, [k])[k]. In future we could add a get_one(s) helper.
+# Get with keys=None returns the entire config, following the CLI (get_all is unnecessary).
+def get(snap: str, keys: Iterable[str] | None = None) -> dict[str, Any]:
+    """Get snap configuration.
+
+    Args:
+        snap: The name of the snap to read configuration from.
+        keys: Configuration keys to read. Nested options may be accessed with dotted notation,
+            for example ``['server.port']``. If ``None``, the full config is returned as a
+            nested dict. If an empty iterable, an empty dict is returned if the snap is installed.
+            Must not be a bare string.
+
+    Returns:
+        A dict mapping each requested key to its configured value. If all keys are requested
+        (keys=None), the entire config is returned as a nested dict (empty if the snap has no
+        configuration). If no keys are requested (keys=[]), an empty dict is returned if the snap
+        is installed. Each dotted key queried is returned as a top-level entry.
+
+    Raises:
+        TypeError: if ``keys`` is a string (must be a non-string iterable of strings, or ``None``).
+        NotFoundError: if the snap is not installed. Never raised for ``system`` or ``core``,
+            whose configuration is served whether or not the core snap is installed.
+        OptionNotFoundError: if a requested key has no value stored in the snap's configuration.
+            Snap configuration is schemaless, so snapd does not distinguish between a key the
+            snap doesn't recognise, a key that was never set, and a key that was unset. Any
+            defaults a snap applies internally are invisible here unless its configure hook has
+            stored them with ``snapctl set``.
+
+    ::
+
+        # Full config.
+        get('foo')  # {'server': {'port': 8080}, 'client': {'timeout': 30}}
+        get('foo', keys=None)  # {'server': {'port': 8080}, 'client': {'timeout': 30}}
+        # Querying specific keys.
+        get('foo', ['client'])  # {'client': {'timeout': 30}}
+        get('foo', ['client.timeout'])  # {'client.timeout': 30}
+        get('foo', ['server', 'server.port'])  # {'server': {'port': 8080}, 'server.port': 8080}
+        # Querying no keys.
+        get('foo', keys=[])  # {}
+        # Invalid keys argument.
+        get('foo', keys='client')  # TypeError
+    """
+    if isinstance(keys, str):
+        raise TypeError('keys must be an iterable of strings, or None (not a string)')
+    if keys is not None:
+        keys = list(keys)
+    if keys == []:
+        # NOTE: snapd returns the full configuration if no keys are specified.
+        # We pass this behaviour through for keys=None, but for keys=[] we return
+        # an empty dict, since the caller explicitly requested no keys.
+        _raise_if_snap_not_installed_or_system(snap)
+        return {}
+    params = {'keys': ','.join(keys)} if keys is not None else None
+    try:
+        config = _client.get(f'/v2/snaps/{snap}/conf', query=params)
+    except _errors.OptionNotFoundError:
+        # NOTE: snapd reports option-not-found both for a missing key and for a missing snap.
+        # The CLI returns 'error: snap "foo" has no "bar" configuration' in both cases.
+        # For symmetry with PUT (set/unset), we raise NotFoundError here for a missing snap.
+        # Following PUT, NotFoundError isn't raised for system/core (installed or not).
+        _raise_if_snap_not_installed_or_system(snap)
+        raise
+    if keys is None and not config:
+        # NOTE: snapd returns {} for an installed snap with no config and for a missing snap.
+        # The CLI returns 'error: snap "foo" has no configuration' for a missing snap.
+        # For symmetry with PUT (set/unset), we raise NotFoundError here for a missing snap.
+        # Following PUT, NotFoundError isn't raised for system/core (installed or not).
+        _raise_if_snap_not_installed_or_system(snap)
+    assert isinstance(config, dict)
+    return typing.cast('dict[str, Any]', config)
+
+
+def _raise_if_snap_not_installed_or_system(snap: str) -> None:
+    """Raise NotFoundError if the snap is not installed, unless it's system/core."""
+    # NOTE: snapd's conf endpoints treat 'system' as an alias for 'core'.
+    # System configuration is served whether or not the core snap is installed.
+    # /v2/snaps/system always 404s (it's a hardcoded alias, not a real snap).
+    # /v2/snaps/core 404s when the core snap is absent (typical when no other snaps depend on it).
+    # For the purposes of this module, we can skip snap installed checks for both names.
+    if snap not in ('system', 'core'):
+        _client.get(f'/v2/snaps/{snap}')
+
+
+def unset(snap: str, keys: Iterable[str]) -> None:
+    """Unset snap configuration keys.
+
+    Unsetting a key that is not currently set is a no-op and does not raise.
+
+    Args:
+        snap: The name of the snap to unset configuration on.
+        keys: Configuration keys to unset. Nested options may be addressed with dotted
+            notation, for example ``['server.port']``. Must not be a bare string.
+            An empty iterable is passed to snapd, where it is treated as a no-op.
+
+    Raises:
+        TypeError: if ``keys`` is a string (must be a non-string iterable of strings).
+        NotFoundError: if the snap is not installed.
+        ChangeError: if the snap's configure hook fails. This includes unsetting any
+            configuration on a snap that does not define a configure hook. A failed change
+            is rolled back: no key from the request is unset.
+    """
+    if isinstance(keys, str):
+        raise TypeError('keys must be an iterable of strings (not a string)')
+    # NOTE: snap-not-found is returned for a missing snap, but not for system or core,
+    # even if the core snap isn't installed -- configuration changes are still applied.
+    # NOTE: Unset with no keys is a no-op (like set with an empty dict). We let snapd handle it.
+    _client.put(f'/v2/snaps/{snap}/conf', body=dict.fromkeys(keys))
+
+
+# Defined last to minimise the chance of meaningfully shadowing the built-in set type.
+def set(snap: str, config: dict[str, Any]) -> None:  # noqa: A001 (shadowing a Python builtin)
+    """Set snap configuration.
+
+    Args:
+        snap: The name of the snap to configure.
+        config: A mapping of configuration keys to values. Values may be any JSON-serialisable
+            type, including nested dicts and lists. Setting a key to ``None`` unsets it.
+            Nested options may be addressed with dotted keys, for example ``server.port``.
+            An empty mapping is accepted as a no-op.
+
+    Raises:
+        NotFoundError: if the snap is not installed.
+        ChangeError: if the snap's configure hook fails. This includes setting any
+            configuration on a snap that does not define a configure hook, and configuration
+            rejected by a validating configure hook. A failed change is rolled back: no key
+            from the request is applied.
+    """
+    # NOTE: snap-not-found is returned for a missing snap, but not for system or core,
+    # even if the core snap isn't installed -- configuration changes are still applied.
+    # NOTE: Set with an empty dict is a no-op. We let snapd handle it.
+    _client.put(f'/v2/snaps/{snap}/conf', body=config)

snap/tests/functional/setup.sh

@@ -3,3 +3,4 @@ SNAPS_DIR="tests/functional/snaps"
 mksquashfs "$SNAPS_DIR/test-snap-1.0" "$SNAPS_DIR/test-snap_1.0.snap" -noappend -comp xz -quiet
 mksquashfs "$SNAPS_DIR/test-snap-2.0" "$SNAPS_DIR/test-snap_2.0.snap" -noappend -comp xz -quiet
 mksquashfs "$SNAPS_DIR/test-classic-snap-1.0" "$SNAPS_DIR/test-classic-snap_1.0.snap" -noappend -comp xz -quiet
+mksquashfs "$SNAPS_DIR/test-configure-snap-1.0" "$SNAPS_DIR/test-configure-snap_1.0.snap" -noappend -comp xz -quiet

snap/tests/functional/snaps/test-configure-snap-1.0/meta/hooks/configure

@@ -0,0 +1,8 @@
+#!/bin/sh -e
+# Validating configure hook: rejects any value for 'bad-key', accepts everything else.
+# Used by functional tests to exercise how snaps reject configuration at set time.
+bad="$(snapctl get bad-key)"
+if [ -n "$bad" ]; then
+    echo "bad-key is not allowed" >&2
+    exit 1
+fi

snap/tests/functional/snaps/test-configure-snap-1.0/meta/snap.yaml

@@ -0,0 +1,5 @@
+name: test-configure-snap
+version: "1.0"
+summary: Snap with a validating configure hook for charmlibs.snap functional tests
+confinement: strict
+base: core24