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='')[source]¶ 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 linesupdate()
the value of a setting from user-provided valuesvalidate()
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)[source]¶ 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 (orNone
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
()[source]¶ Yields lines of configuration to represent the current state of the setting (taking in account the context of other
Settings
).
-
update
(value)[source]¶ Given a value, returns it transformed to the setting’s native type (typically an
int
orbool
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 aUserStr
, 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
()[source]¶ Validates the setting within the context of the other
Settings
. RaisesValueError
in the event that the current value is invalid. May optionally useValueWarning
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 astr
.
-
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 comparevalue
todefault
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”.
-
class
pibootctl.setting.
Overlay
(name, *, overlay, default=False, doc='')[source]¶ 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='')[source]¶ 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)[source]¶ 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='')[source]¶ Represents a boolean parameter to the base device-tree overlay.
-
class
pibootctl.setting.
Command
(name, *, command=None, commands=None, default=None, doc='', index=None)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ Represents a boolean-valued configuration command or commands.
-
class
pibootctl.setting.
CommandBoolInv
(name, *, command=None, commands=None, default=False, doc='', index=0)[source]¶ 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)[source]¶ Represents the tri-valued configuration values with force and ignore commands, e.g.
hdmi_force_hotplug
andhdmi_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 isTrue
and thus when the ignore command is “1”, the setting isFalse
. 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=())[source]¶ 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=())[source]¶ 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)[source]¶ 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), andhint
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)[source]¶ Represents settings that reference a file which should be included in any stored boot configuration.
-
exception
pibootctl.setting.
ParseWarning
[source]¶ Warning class used by
Setting.extract()
to warn about invalid values while parsing.
-
exception
pibootctl.setting.
ValueWarning
[source]¶ Warning class used by
Setting.validate()
to warn about dangerous or inappropriate configurations.