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.

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).

doc

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

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.

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.

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).

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.

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”.

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.

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.

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).

commands

The configuration commands that this setting represents.

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.

force

The boolean command that forces this setting on.

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.

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.