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