# pibootctl.store

The `pibootctl.store` module defines classes which control a store of Raspberry Pi boot configurations, or the active boot configuration.

The main class of interest is `Store`. From an instance of this, one can access derivatives of `BootConfiguration` for the purposes of manipulating the store of configurations, or the active boot configuration itself. Each `BootConfiguration` contains an instance of `Settings` which maps setting names to `Setting` instances.

See `pibootctl.main` for information on obtaining an instance of `Store`.

`pibootctl.store.``Current`

  The key of the active boot configuration in instances of `Store`.

`pibootctl.store.``Default`

  The key of the default (empty) boot configuration in instances of `Store`.

class `pibootctl.store.``Store`(boot_path, store_path, config_root='config.txt', mutable_files=frozenset({'config.txt'}), comment_lines=False)

  A mapping representing all boot configurations (current, default, and stored).

  Acts as a mapping keyed by the name of the stored configuration, or the special values `Current` for the current boot configuration, or `Default` for the default (empty) configuration. The values of the mapping are derivatives of `BootConfiguration` which provide the parsed `Settings`, along with some other attributes.

  The mapping is mutable and this can be used to manipulate stored boot configurations. For instance, to store the current boot configuration under the name “foo”:

      >>> store = Store('/boot', 'pibootctl')
      >>> store["foo"] = store[Current]

  Setting the item with the key `Current` overwrites the current boot configuration:

      >>> store[Current] = store["serial"]

  Note that items retrieved from the store are effectively immutable; modifying them (even internally) does not modify the content of the store. To modify the content of the store, you must request a `mutable()` copy of a configuration, modify it, and assign it back:

      >>> foo = store["foo"].mutable()
      >>> foo.update({"serial.enabled": True})
      >>> store["serial"] = foo

  The same applies to the current boot configuration item:

      >>> current = store[Current].mutable()
      >>> current.update({"camera.enabled": True, "gpu.mem": 128})
      >>> store[Current] = current

  Items can be deleted to remove them from the store, with the obvious exception of the items with the keys `Current` and `Default` which cannot be removed (attempting to do so will raise a `KeyError`). Furthermore, the item with the key `Default` cannot be modified either.

  Parameters

    - boot_path (str) – The path on which the boot partition is mounted.

    - store_path (str) – The path (relative to boot_path) under which stored configurations will be saved.

    - config_root (str) – The filename of the “root” of the configuration, i.e. the first file read by the parser, and the file in which certain commands (e.g. start_x) must be placed. Currently, this should always be “config.txt”, the default.

    - mutable_files (set) – The set of filenames which `MutableConfiguration` instances are permitted to change. By default this is just “config.txt”.

    - comment_lines (bool) – If `True`, then `MutableConfiguration` will comment out lines no longer required with a # prefix. When `False` (the default), such lines will be deleted instead. When adding lines, regardless of this setting, the utility will search for, and uncomment, commented out lines which match the required output.

  property `active`

    Returns the key of the active configuration, if any. If no configuration is currently active, returns `None`.

class `pibootctl.store.``BootConfiguration`(path, config_root='config.txt', mutable_files=frozenset({'config.txt'}), comment_lines=False)

  Represents a boot configuration, as parsed from config_root (default “config.txt”) on the boot partition (presumably mounted at path, a `Path` instance).

  `mutable`()

    Return a `MutableConfiguration` based on the parsed content of this configuration.

    Note that mutable configurations are not backed by any files on disk, so nothing is actually re-written until the updated mutable configuration is assigned back to something in the `Store`.

  property `config_root`

    The root file of the boot configuration. This is currently always “config.txt”.

  property `files`

    A mapping of filenames to `BootFile` instances representing all the files that make up the boot configuration.

  property `hash`

    The SHA1 hash that identifies the boot configuration. This is obtained by hashing the files of the boot configuration in parsing order.

  property `path`

    The path (or archive or entity) containing all the files that make up the boot configuration.

  property `settings`

    A `Settings` instance containing all the settings extracted from the boot configuration.

  property `timestamp`

    The last modified timestamp of the boot configuration, as a `datetime`.

class `pibootctl.store.``StoredConfiguration`(path, config_root='config.txt', mutable_files=frozenset({'config.txt'}), comment_lines=False)

  Represents a boot configuration stored in a `ZipFile` specified by path. The starting file of the configuration is given by config_root. All other parameters are as in `BootConfiguration`.

class `pibootctl.store.``MutableConfiguration`(path, config_root='config.txt', mutable_files=frozenset({'config.txt'}), comment_lines=False)

  Represents a changeable boot configuration.

  Do not construct instances of this class directly; they are typically constructed from a base `BootConfiguration`, by calling `mutable()`.

  Mutable configurations can be changed with the `update()` method which will also validate the new configuration, and check that the settings were not overridden by later files. No link is maintained between the original `BootConfiguration` and the mutable copy. This implies that nothing is re-written on disk when the mutable configuration is updated. The resulting configuration must be assigned back to something in the `Store` in order to re-write disk files.

  `update`(values, context)

    Given a mapping of setting names to new values, updates the values of the corresponding settings in this configuration. If a value is `None`, the setting is reset to its default value.

class `pibootctl.store.``Settings`(items=None)

  Represents all settings in a boot configuration; acts like an ordered mapping of names to `Setting` objects.

  `copy`()

    Returns a distinct copy of the configuration that can be updated without affecting the original.

  `diff`(other)

    Returns a set of (self, other) setting tuples for all settings that differ between self and other (another `Settings` instance). If a particular setting is missing from either side, its entry will be given as `None`.

  `filter`(pattern)

    Returns a copy of the configuration which only contains settings with names matching pattern, which may contain regular shell globbing patterns.

  `modified`()

    Returns a copy of the configuration which only contains modified settings.