pibootctl.parser

The pibootctl.parser module provides the BootParser class for parsing the boot configuration of the Raspberry Pi.

The output of this class consists of derivatives of BootLine (BootSection, BootCommand, etc.) and BootFile instances, which in turn reference BootConditions instances to indicate the context in which they were found.

class pibootctl.parser.BootParser(path)

Parser for the files used to configure the Raspberry Pi’s bootloader.

The path specifies the container of all files that make up the configuration. It be one of:

• a str or a Path in which case the path specified must be a directory

• a ZipFile

• a dict mapping filenames to BootFile instances; effectively the output of files after parsing

add(filename, encoding=None, errors=None)

Adds the auxilliary filename under path to the configuration. This is used to update the hash and files of the parsed configuration to include files which are referenced by the boot configuration but aren’t themselves configuration files (e.g. EDID data, and the kernel cmdline.txt).

If specified, encoding and errors are as for open(). If encoding is None, the data is assumed to be binary and the method will return the content of the file as a bytes string. Otherwise, the content of the file is assumed to be text and will be returned as a list of str.

parse(filename='config.txt')

Parse the boot configuration on path. The optional filename specifies the “root” of the configuration, and defaults to config.txt.

If parsing is successful, this will update the files, hash, timestamp, and config attributes.

property config

The parsed configuration; a sequence of BootLine instances (or derivatives of BootLine), after parse() has been successfully called.

property files

The content of all parsed files; a mapping of filename to BootFile objects.

property hash

After parse() is successfully called, this is the SHA1 hash of the complete configuration in parsed order (i.e. starting at “config.txt” and proceeding through all included files).

property path

The path under which all configuration files can be found. This may be a Path instance, or a ZipFile, or a dict.

property timestamp

The latest modified timestamp on all files that were read as a result of calling parse().

class pibootctl.parser.BootLine(filename, linenum, conditions, comment=None)

Represents a line in a boot configuration. This is effectively an abstract base class and should never appear in output itself. Provides four attributes:

filename

A str indicating the path (relative to the configuration’s root) of the file containing the line.

linenum

The 1-based line number of the line.

conditions

A BootConditions specifying the filters in effect for this configuration line.

comment

Any comment that appears after other content on the line, or None if no comment was present

class pibootctl.parser.BootSection(filename, linenum, conditions, section, comment=None)

A derivative of BootLine for [conditional sections] in a boot configuration. Adds a single attribute:

section

The criteria of the section (everything between the square brackets).

Note

The conditions for a BootSection instance includes the filters defined by that section.

class pibootctl.parser.BootCommand(filename, linenum, conditions, command, params, hdmi=None, comment=None)

A derivative of BootLine which represents a command in a boot configuration, e.g. “disable_overscan=1”. Adds several attributes:

command

The title of the command; characters before the first “=” in the line.

params

The value of the command; characters after the first “=” in the line. As a special case, the “initramfs” command has two values and thus if command is “initramfs” then this attribute will be a 2-tuple.

hdmi

The HDMI display that the command applies to. This is usually None unless the command has an explicit hdmi suffix (“:” separated after the command title but before the “=”), or the command appears in an [HDMI:1] section.

class pibootctl.parser.BootInclude(filename, linenum, conditions, include, comment=None)

A derivative of BootLine representing an “include” command in a boot configuration. Adds a single attribute:

include

The name of the file to be included.

class pibootctl.parser.BootFile(filename, timestamp, content, encoding=None, errors=None)

Represents a file in a boot configuration.

filename

A str representing the file’s path relative to the boot configuration’s container (whatever that may be: a path, a zip archive, etc.)

timestamp

A datetime containing the last modification timestamp of the file.

Note

This is rounded down to a 2-second precision as that is all that PKZIP archives support.

content

A bytes string containing the complete content of the file.

encoding

None if the file is a binary file. Otherwise, specifies the name of the character encoding to be used when reading the file.

errors

None if the file is a binary file. Otherwise, specifies the character replacement strategy to be used with erroneous characters encountered when reading the file.

class pibootctl.parser.BootConditions(pi=None, hdmi=None, edid=None, serial=None, gpio=None, none=False, suppress_count=0)

Represents the set of conditional filters that apply to a given BootLine. The class implements methods necessary to compare instances as if they were sets.

For example:

>>> cond_all = BootConditions()
>>> cond_pi3 = BootConditions(pi='pi3')
>>> cond_pi3p = BootConditions(pi='pi3p')
>>> cond_serial = BootConditions(pi='pi3', serial=0x12345678)
>>> cond_all == cond_pi3
False
>>> cond_all >= cond_pi3
True
>>> cond_pi3 > cond_pi3p
True
>>> cond_serial < cond_pi3
True
>>> cond_serial < cond_pi3p
False

pi

The model of pi that the section applies to. See conditional filters for details of valid values. This represents sections like [pi3].

hdmi

The index of the HDMI port (0 or 1) that settings within this section will apply to, if no index-suffix is provided by the setting itself. This represents sections like [HDMI:0].

edid

The EDID of the display that the section applies to. This represents sections like [EDID=VSC-TD2220].

serial

The serial number of the Pi that settings within this section will apply to, stored as an int. This represents sections like [0x12345678].

gpio

The GPIO number and state that must be matched for settings in this section to apply, stored as a (gpio, state) tuple. This represents sections like [gpio2=0].

none

If this is True then a [none] section has been encountered and no settings apply.

suppress_count

This is a “suppression count” used to track sections within included files that are currently disabled (because the include occurred within a section that itself is disabled).

evaluate(section)

Calculates a new conditional state (based upon the current conditional state) from the specified section criteria. Returns a new BootConditions instance.

generate(context=None)

Given context, a BootConditions instance representing the currently active conditional sections, this method yields the conditional secitons required to set the conditions to this instance. If context is not specified, it defaults to conditions equivalent to [any], which is the default in the Pi bootloader.

For example:

>>> current = BootConditions(pi='pi2', gpio=(4, True))
>>> wanted = BootConditions()
>>> print('\n'.join(wanted.generate(current)))
[all]
>>> wanted = BootConditions(pi='pi4')
>>> print('\n'.join(wanted.generate(current)))
[all]
[pi4]
>>> current = BootConditions(pi='pi2')
>>> print('\n'.join(wanted.generate(current)))
[pi4]
>>> current = BootConditions(none=True)
>>> print('\n'.join(wanted.generate(current)))
[all]
[pi3]

Note

The yielded strings do not end with a line terminator.

suppress()

If the current boot conditions are not enabled, returns a new BootConditions instance with the suppression count incremented by one. This is used during parsing to disable all conditionals in suppressed includes.

property enabled

Returns True if parsed items are currently effective. If this is False, parsed items are ignored.