# pibootctl.setting

The `pibootctl.setting` module defines all the classes used to represent boot configuration settings:

The base of the hierarchy is `Setting` but this is effectively an abstract class and it is rare that anyone will need to use it directly. Rather you should derive from one of the concrete implementations below it like `OverlayParam`, `Command`, or one of the type-specializations like `CommandBool`, `CommandInt`, etc.

Note

For the sake of brevity, only the generic classes defined in `pibootctl.setting` are documented here. There are also specialization classes specific to individual settings defined (for cases of complex inter-dependencies, e.g. how the Bluetooth enabled status affects the default serial UART).

Developers are advised to familiarize themselves with the full range of classes in this module before defining additional ones.

class `pibootctl.setting.``Setting`(name, *, default=None, doc='')

  Represents a configuration setting.

  Each setting has a name which uniquely identifies the setting, a default value, and an optional doc string. The life-cycle of a typical setting in the scenario where the active boot configuration is being changed is:

  - `extract()` the value of a setting from parsed configuration lines

  - `update()` the value of a setting from user-provided values

  - `validate()` a setting in the wider context of a configuration

  - generate `output()` to represent the setting in a new config.txt

  Optionally:

  - `hint` may be queried to describe a value in human-readable terms

  `extract`(config)

    Given a config which must be a sequence of `BootLine` items, yields each line that potentially affects the setting’s value (including those currently disabled by conditionals), and the new value that the line produces (or `None` indicating that the value is now, or is still, the default state).

    Note

    This method is not influenced by conditionals that disable a line. In this case the method must still yield the line and the value it would produce (were it enabled). The caller will deal with the fact the line is currently disabled (but needs to be aware of such lines for the configuration mutator).

    For this reason (and others) this method must not affect `value` directly; the caller will handle mutating the value when required.

  `output`()

    Yields lines of configuration to represent the current state of the setting (taking in account the context of other `Settings`).

  `update`(value)

    Given a value, returns it transformed to the setting’s native type (typically an `int` or `bool` but can be whatever type is appropriate).

    The value may be a regular type (`str`, `int`, `None`, etc.) as deserialized from one of the input formats (JSON or YAML). Alternatively, it may be a `UserStr`, indicating that the value is a string given by the user on the command line and should be interpreted by the setting accordingly.

    Note

    Note to implementers: the method must not affect `value` directly; the caller will handle this.

  `validate`()

    Validates the setting within the context of the other `Settings`. Raises `ValueError` in the event that the current value is invalid. May optionally use `ValueWarning` to warn about dangerous or inappropriate configurations.

  property `default`

    The default value of this setting. The default may be sensitive to the wider context of `Settings` (i.e. the default of one setting can change depending on the current value of other settings).

  property `doc`

    A description of the setting, used as help-text on the command line.

  property `hint`

    Provides a human-readable interpretation of the state of the setting. Used by the “dump” and “show” commands to provide translations of default and current values.

    Must return `None` if no explanation is available or necessary. Otherwise, must return a `str`.

  property `key`

    Returns a tuple of strings which will be used to order the output of `output()` in the generated configuration.

    Note

    The output of this property must be unique for each setting, unless a setting delegates all its output to another setting.

  property `lines`

    Returns the `BootLine` items which (if enabled by conditionals) affected the value of the setting, in the reverse order they were encountered while parsing (so the first enabled item holds the current value).

  property `modified`

    Returns `True` when the setting has been modified. Note that it is not sufficient to simply compare `value` to `default` as some defaults are context- or platform-specific.

  property `name`

    The name of the setting. This is a dot-delimited list of strings; note that the individual components do not have to be valid identifiers. For example, “boot.kernel.64bit”.

  property `value`

    Returns the current value of the setting (or the `default` if the setting has not been `modified`).

class `pibootctl.setting.``Overlay`(name, *, overlay, default=False, doc='')

  Represents a boolean setting that is “on” if the represented overlay is present, and “off” otherwise.

  property `overlay`

    The name of the overlay this parameter affects.

class `pibootctl.setting.``OverlayParam`(name, *, overlay='base', param, default=None, doc='')

  Represents a param to a device-tree overlay. Like `Setting`, this is effectively an abstract base class to be derived from.

  property `param`

    The name of the parameter within the base overlay that this setting represents.

class `pibootctl.setting.``OverlayParamInt`(name, *, overlay='base', param, default=0, doc='', valid=None)

  Represents an integer parameter to a device-tree overlay.

  The valid parameter may optionally provide a dictionary mapping valid integer values for the command to string explanations, to be provided by the basic `hint` implementation.

class `pibootctl.setting.``OverlayParamBool`(name, *, overlay='base', param, default=False, doc='')

  Represents a boolean parameter to the base device-tree overlay.

class `pibootctl.setting.``Command`(name, *, command=None, commands=None, default=None, doc='', index=None)

  Represents a string-valued configuration command or commmands (one of these must be specified, but not both). If multiple commands are represented, only the first will be generated by `output()` in this base class.

  This is also the base class for most simple-valued configuration commands (integer, boolean, etc).

  property `commands`

    The configuration commands that this setting represents.

  property `index`

    The index of this setting for multi-valued settings (e.g. settings which apply to HDMI outputs).

class `pibootctl.setting.``CommandInt`(name, *, command=None, commands=None, default=0, doc='', index=0, valid=None)

  Represents an integer-valued configuration command or commands.

  The valid parameter may optionally provide a dictionary mapping valid integer values for the command to string explanations, to be provided by the basic `hint` implementation.

class `pibootctl.setting.``CommandIntHex`(name, *, command=None, commands=None, default=0, doc='', index=0, valid=None)

  An integer-valued configuration command or commands that are typically represented in hexi-decimal (like memory addresses).

class `pibootctl.setting.``CommandBool`(name, *, command=None, commands=None, default=False, doc='', index=0)

  Represents a boolean-valued configuration command or commands.

class `pibootctl.setting.``CommandBoolInv`(name, *, command=None, commands=None, default=False, doc='', index=0)

  Represents a boolean-valued configuration command or commands with inverted logic, e.g. video.overscan.enabled represents the `disable_overscan` setting and therefore its value is always the opposite of the actual written value.

class `pibootctl.setting.``CommandForceIgnore`(name, *, force, ignore, doc='', index=0)

  Represents the tri-valued configuration values with force and ignore commands, e.g. `hdmi_force_hotplug` and `hdmi_ignore_hotplug`.

  For these cases, when both commands are “0” the setting is considered to have the value `None` (which in most cases means “determine automatically”). When the force command is “1”, the setting is `True` and thus when the ignore command is “1”, the setting is `False`. When both are “1” (a contradictory setting) the final setting encountered takes precedence.

  property `force`

    The boolean command that forces this setting on.

  property `ignore`

    The boolean command that forces this setting off.

class `pibootctl.setting.``CommandMaskMaster`(name, *, mask, command=None, commands=None, default=0, doc='', index=0, valid=None, dummies=())

  Represents an integer bit-mask setting as several settings. The “master” setting is the only one that produces any output. It defines the suffixes of its dummies (instances of `CommandMaskDummy` which parse the same setting but produce no output of their own).

  The mask specifies the integer bit-mask to be applied to the underlying value for this setting. The right-shift will be calculated from this. Single-bit masks will be represented as boolean values rather than integers.

class `pibootctl.setting.``CommandMaskDummy`(name, *, mask, command=None, commands=None, default=0, doc='', index=0, valid=None, dummies=())

  Represents portions of integer bit-masks which are subordinate to a `CommandMaskMaster` setting.

class `pibootctl.setting.``CommandFilename`(name, *, command=None, commands=None, default=None, doc='', index=None)

  Represents settings that contain a filename affected by the os_prefix command. The `filename` returns the full filename incorporating the value of “boot.prefix” (if set), and `hint` outputs a suitable message including the full path.

  property `filename`

    The full filename represented by the value, after concatenating it with the value of “boot.prefix”.

class `pibootctl.setting.``CommandIncludedFile`(name, *, command=None, commands=None, default=None, doc='', index=None)

  Represents settings that reference a file which should be included in any stored boot configuration.

exception `pibootctl.setting.``ParseWarning`

  Warning class used by `Setting.extract()` to warn about invalid values while parsing.

exception `pibootctl.setting.``ValueWarning`

  Warning class used by `Setting.validate()` to warn about dangerous or inappropriate configurations.