boom package

Module contents

This module provides classes and functions for creating, displaying, and manipulating boot loader entries complying with the Boot Loader Specification.

The boom package contains global definitions, functions to configure the Boom environment, logging infrastructure for the package and a Selection class used to select one or more OsProfile, HostProfile, BootEntry, or BootParams object according to specified selection criteria.

Individual sub-modules provide interfaces to the various components of Boom: operating system and host profiles, boot loader entries and boot parameters, the boom CLI and procedural API and a simple reporting module to produce tabular reports on Boom objects.

See the sub-module documentation for specific information on the classes and interfaces provided, and the boom tool help output and manual page for information on using the command line interface.

class boom.BoomConfig(boot_path=None, boom_path=None, legacy_enable=None, legacy_format=None, legacy_sync=None, cache_enable=None, cache_auto_clean=None, cache_path=None)

Bases: object

Class representing boom persistent configuration values.

__annotate_func__ = None

__annotations_cache__ = {}

__firstlineno__ = 218

__init__(boot_path=None, boom_path=None, legacy_enable=None, legacy_format=None, legacy_sync=None, cache_enable=None, cache_auto_clean=None, cache_path=None)

Initialise a new BoomConfig object with the supplied configuration values, or defaults for any unset arguments.

Parameters:

• boot_path – the path to the system /boot volume

• boom_path – the path to the boom configuration dir

• legacy_enable – enable legacy bootloader support

• legacy_format – the legacy bootlodaer format to write

• legacy_sync – the legacy sync mode

• cache_enable – enable boot image cache

• cache_auto_clean – automatically clean up unused boot images

• cache_path – the path to the boot image cache

__repr__()

Return a string representation of this BoomConfig in BoomConfig initialiser notation.

__static_attributes__ = ('boom_path', 'boot_path', 'cache_auto_clean', 'cache_enable', 'cache_path', 'legacy_enable', 'legacy_format', 'legacy_sync')

__str__()

Return a string representation of this BoomConfig in boom.conf (INI) notation.

boom_path = '/boot/boom'

boot_path = '/boot'

cache_auto_clean = True

cache_enable = True

cache_path = '/boot/boom/cache'

legacy_enable = False

legacy_format = 'grub1'

legacy_sync = True

exception boom.BoomError

Bases: Exception

Base class of all Boom exceptions.

__firstlineno__ = 143

__static_attributes__ = ()

class boom.BoomLogger

Bases: Logger

Boom logging wrapper class: wrap the Logger.debug() method to allow filtering of submodule debug messages by log mask.

This allows us to selectively control which messages are logged in the library without having to tamper with the Handler, Filter or Formatter configurations (which belong to the client application using the library).

__annotate_func__ = None

__annotations_cache__ = {}

__firstlineno__ = 149

__static_attributes__ = ('mask_bits',)

debug_masked(msg, *args, **kwargs)

Log a debug message if it passes the current debug mask.

Log the specified message if it passes the current logger debug mask.

Parameters:

msg – the message to be logged

Return type:

None

mask_bits = 0

set_debug_mask(mask_bits)

Set the debug mask for this BoomLogger.

This should normally be set to the BOOM_DEBUG_* value corresponding to the boom sub-module that this instance of BoomLogger belongs to.

Parameters:

mask_bits – The bits to set in this logger’s mask.

Return type:

None

class boom.Selection

Bases: object

Selection criteria for boom BootEntry, OsProfile HostProfile, and BootParams.

Selection criteria specified as a simple boolean AND of all criteria with a non-None value.

__annotate_func__ = None

__annotations_cache__ = {}

__firstlineno__ = 524

__init__(boot_id=None, title=None, version=None, machine_id=None, linux=None, initrd=None, efi=None, root_device=None, lvm_root_lv=None, btrfs_subvol_path=None, btrfs_subvol_id=None, os_id=None, os_name=None, os_short_name=None, os_version=None, os_version_id=None, os_options=None, os_uname_pattern=None, os_kernel_pattern=None, os_initramfs_pattern=None, allow_null=False, host_id=None, host_name=None, host_label=None, host_short_name=None, host_add_opts=None, host_del_opts=None, path=None, orig_path=None, timestamp=None, img_id=None)

Initialise a new Selection object.

Initialise a new Selection object with the specified selection criteria.

Parameters:

• boot_id – The boot_id to match

• title – The title to match

• version – The version to match

• machine_id – The machine_id to match

• linux – The BootEntry kernel image to match

• initrd – The BootEntry initrd image to match

• efi – The BootEntry efi image to match

• root_device – The root_device to match

• lvm_root_lv – The lvm_root_lv to match

• btrfs_subvol_path – The btrfs_subvol_path to match

• btrfs_subvol_id – The btrfs_subvol_id to match

• os_id – The os_id to match

• os_name – The os_name to match

• os_short_name – The os_short_name to match

• os_version – The os_version to match

• os_version_id – The os_version_id to match

• os_options – The os_options to match

• os_uname_pattern – The os_uname_pattern to match

• os_kernel_pattern – The kernel_pattern to match

• os_initramfs_pattern – The initramfs_pattern to match

• allow_null – Allow selecting the null profile

• host_id – The host identifier to match

• host_name – The host name to match

• host_label – The host label to match

• host_short_name – The host short name to match

• host_add_opts – Host add options to match

• host_del_opts – Host del options to match

• path – An cache image path to match

• orig_path – A cache origin path to match

• timestamp – A cache entry timestamp to match

• img_id – A cache image identifier to match

Returns:

A new Selection instance

Return type:

Selection

__repr__()

Format this Selection object as a machine readable string.

The returned string may be passed to the Selection initialiser to duplicate the original Selection.

Returns:

A machine readable string representation of this Selection object

Return type:

string

__static_attributes__ = ('allow_null_profile', 'boot_id', 'btrfs_subvol_id', 'btrfs_subvol_path', 'efi', 'host_add_opts', 'host_del_opts', 'host_id', 'host_label', 'host_name', 'host_short_name', 'img_id', 'initrd', 'linux', 'lvm_root_lv', 'machine_id', 'orig_path', 'os_id', 'os_initramfs_pattern', 'os_kernel_pattern', 'os_name', 'os_options', 'os_short_name', 'os_uname_pattern', 'os_version', 'os_version_id', 'path', 'root_device', 'timestamp', 'title', 'version')

__str__()

Format this Selection object as a human readable string.

Returns:

A human readable string representation of this Selection object

Return type:

string

all_attrs = ['boot_id', 'title', 'version', 'machine_id', 'linux', 'initrd', 'efi', 'options', 'devicetree', 'path', 'root_device', 'lvm_root_lv', 'btrfs_subvol_path', 'btrfs_subvol_id', 'os_id', 'os_name', 'os_short_name', 'os_version', 'os_version_id', 'os_uname_pattern', 'os_kernel_pattern', 'os_initramfs_pattern', 'os_root_opts_lvm2', 'os_root_opts_btrfs', 'os_options', 'host_id', 'host_name', 'host_label', 'host_short_name', 'host_add_opts', 'host_del_opts', 'machine_id', 'version', 'linux', 'initrd', 'path', 'orig_path', 'timestamp', 'img_id']

allow_null_profile = False

boot_id = None

btrfs_subvol_id = None

btrfs_subvol_path = None

cache_attrs = ['version', 'linux', 'initrd', 'path', 'orig_path', 'timestamp', 'img_id']

Cache selection supports a subset of entry_attrs

check_valid_selection(entry=False, params=False, profile=False, host=False, cache=False)

Check a Selection for valid criteria.

Check this Selection object to ensure it contains only criteria that are valid for the specified object type(s).

Returns None if the object passes the check, or raise ValueError if invalid criteria exist.

Parameters:

• entry – Selection may include BootEntry data

• params – Selection may include BootParams data

• profile – Selection may include OsProfile data

• host – Selection may include Host data

• cache – Selection may include Cache data

Returns:

None on success

Return type:

NoneType

Raises:

ValueError if excluded criteria are present

devicetree = None

efi = None

entry_attrs = ['boot_id', 'title', 'version', 'machine_id', 'linux', 'initrd', 'efi', 'options', 'devicetree', 'path']

Selection criteria applying to BootEntry objects

classmethod from_cmd_args(args)

Initialise Selection from command line arguments.

Construct a new Selection object from the command line arguments in cmd_args. Each set selection attribute from cmd_args is copied into the Selection. The resulting object may be passed to either the BootEntry, OsProfile, or HostProfile search functions (find_entries, find_profiles, and find_host_profiles), as well as the boom.command calls that accept a selection argument.

Parameters:

args – The command line selection arguments.

Returns:

A new Selection instance

Return type:

Selection

host_add_opts = None

host_attrs = ['host_id', 'host_name', 'host_label', 'host_short_name', 'host_add_opts', 'host_del_opts', 'machine_id']

Selection criteria applying to HostProfile objects

host_del_opts = None

host_id = None

host_label = None

host_name = None

host_short_name = None

img_id = None

initrd = None

is_null()

Test this Selection object for null selection criteria.

Return True if this Selection object matches all objects, or False otherwise.

Returns:

True if this Selection is null

Return type:

bool

linux = None

lvm_root_lv = None

machine_id = None

options = None

orig_path = None

os_id = None

os_initramfs_pattern = None

os_kernel_pattern = None

os_name = None

os_options = None

os_root_opts_btrfs = None

os_root_opts_lvm2 = None

os_short_name = None

os_uname_pattern = None

os_version = None

os_version_id = None

params_attrs = ['root_device', 'lvm_root_lv', 'btrfs_subvol_path', 'btrfs_subvol_id']

Selection criteria applying to BootParams objects

path = None

profile_attrs = ['os_id', 'os_name', 'os_short_name', 'os_version', 'os_version_id', 'os_uname_pattern', 'os_kernel_pattern', 'os_initramfs_pattern', 'os_root_opts_lvm2', 'os_root_opts_btrfs', 'os_options']

Selection criteria applying to OsProfile objects

root_device = None

title = None

version = None

boom.blank_or_comment(line)

Test whether line is empty of contains a comment.

Test whether the line argument is either blank, or a whole-line comment.

Parameters:

line – the line of text to be checked.

Returns:

True if the line is blank or a comment, and False otherwise.

Return type:

bool

boom.find_minimum_sha_prefix(shas, min_prefix)

Find the minimum SHA prefix length guaranteeing uniqueness.

Find the minimum unique prefix for the set of SHA IDs in the set shas.

Parameters:

• shas – A set of SHA IDs

• min_prefix – Initial minimum prefix value

Returns:

The minimum unique prefix length for the set

Return type:

int

boom.get_boom_config()

Return the active BoomConfig object.

Return type:

BoomConfig

Returns:

the active configuration object

boom.get_boom_config_path()

Return the currently configured boom configuration file path.

Return type:

str

Returns:

the current boom configuration file path

boom.get_boom_path()

Return the currently configured boom configuration path.

Returns:

the path to the BOOT/boom directory.

Return type:

str

boom.get_boot_path()

Return the currently configured boot file system path.

Returns:

the path to the /boot file system.

Return type:

str

boom.get_cache_path()

Return the currently configured boot file system path.

Returns:

the path to the /boot file system.

Return type:

str

boom.get_debug_mask()

Return the current debug mask for the boom package.

Returns:

The current debug mask value

Return type:

int

boom.load_profiles_for_class(profile_class, profile_type, profiles_path, profile_ext)

Load profiles from disk.

Load the set of profiles found at the path profiles_path into the list profiles. The list should be cleared before calling this function if the prior contents are no longer required.

The profile class to be instantiated is specified by the profile_class argument. An optional type may be specified to describe the profile type in error messages. If type is unset the class name is used instead.

This function is intended for use by profile implementations that share common on-disk profile handling.

Parameters:

• profile_class – The profile class to instantiate.

• profile_type – A string description of the profile type.

• profiles_path – Path to the on-disk profile directory.

• profile_ext – Extension of profile files.

Returns:

None

boom.min_id_width(min_prefix, objs, attr)

Calculate the minimum unique width for id values.

Calculate the minimum width to ensure uniqueness when displaying id values.

Parameters:

• min_prefix – The minimum allowed unique prefix.

• objs – An interrable containing objects to check.

• attr – The attribute to compare.

Returns:

the minimum id width.

Return type:

int

boom.parse_btrfs_subvol(subvol)

Parse a BTRFS subvolume string.

Parse a BTRFS subvolume specification into either a subvolume path string, or a string containing a subvolume identifier.

Parameters:

subvol – The subvolume parameter to parse

Returns:

A string containing the subvolume path or ID

Return type:

str

Raises:

ValueError if no valid subvolume was found

boom.parse_name_value(nvp, separator='=', allow_empty=False)

Parse a name value pair string.

Parse a name='value' style string into its component parts, stripping quotes from the value if necessary, and return the result as a (name, value) tuple.

Parameters:

• nvp – A name value pair optionally with an in-line comment.

• separator – The separator character used in this name value pair, or None to splir on white space.

Returns:

A (name, value) tuple.

Return type:

(string, string) tuple.

boom.set_boom_config(config)

Set the active configuration to the object config (which may be any class that includes the BoomConfig attributes).

Parameters:

config – a configuration object

Returns:

None

Raises:

TypeError if config does not appear to have the correct attributes.

boom.set_boom_config_path(path)

Set the boom configuration file path.

boom.set_boom_path(boom_path)

Set the location of the boom configuration directory.

Set the location of the boom configuration path stored in the active configuration to boom_path. This defaults to the ‘boom/’ sub-directory in the boot file system specified by config.boot_path: this may be overridden by calling this function with a different path.

Parameters:

boom_path – the path to the ‘boom/’ directory containing boom profiles and configuration.

Returns:

None

Raises:

ValueError if boom_path does not exist.

boom.set_boot_path(boot_path)

Sets the location of the boot file system to boot_path.

The path defaults to the ‘/boot/’ mount directory in the root file system: this may be overridden by calling this function with a different path.

Calling set_boom_root_path() will re-set the value returned by get_boom_path() to the default boom configuration sub- directory within the new boot file system. The location of the boom configuration path may be configured separately by calling set_boom_root_path() after setting the boot path.

Parameters:

boot_path – the path to the ‘boom/’ directory containing boom profiles and configuration.

ReturnsNone:

None

Raises:

ValueError if boot_path does not exist.

boom.set_cache_path(cache_path)

Set the location of the boom image cache directory.

Set the location of the boom image cache path stored in the active configuration to cache_path. This defaults to the ‘cache/’ sub-directory in the boom configuration directory config.boom_path: this may be overridden by calling this function with a different path.

Parameters:

cache_path – the path to the ‘cache/’ directory containing cached boot images.

Returns:

None

Raises:

ValueError if cache_path does not exist.

boom.set_debug_mask(mask)

Set the debug mask for the boom package.

Parameters:

mask – the logical OR of the BOOM_DEBUG_* values to log.

Return type:

None

Submodules

boom.bootloader module

The boom.bootloader module defines classes for working with on-disk boot loader entries: the BootEntry class represents an individual boot loader entry, and the BootParams class encapsulates the parameters needed to boot an instance of the operating system. The kernel version and root device configuration of an existing BootEntry may be changed by modifying or substituting its BootParams object (this may also be used to ‘clone’ configuration from one entry to another).

Functions are provided to read and write boot loader entries from an on-disk store (normally located at /boot/loader/entries), and to retrieve particular BootEntry objects based on a variety of selection criteria.

The BootEntry class includes named properties for each boot entry attribute (“entry key”). In addition, the class serves as a container type, allowing attributes to be accessed via dictionary-style indexing. This simplifies iteration over a profile’s key / value pairs and allows straightforward access to all members in scripts and the Python shell.

All entry key names are made available as named members of the module: BOOT_ENTRY_*, and the ENTRY_KEYS list. A map of Boom key names to BLS keys is available in the KEY_MAP dictionary (a reverse map is also provided in the MAP_KEY member).

boom.bootloader.BOOM_ENTRY_DEVICETREE = 'BOOM_ENTRY_DEVICETREE'

The BootEntry device tree key.

boom.bootloader.BOOM_ENTRY_EFI = 'BOOM_ENTRY_EFI'

The BootEntry efi key.

boom.bootloader.BOOM_ENTRY_GRUB_ARG = 'BOOM_ENTRY_GRUB_ARG'

The Red Hat BootEntry grub_arg key.

boom.bootloader.BOOM_ENTRY_GRUB_CLASS = 'BOOM_ENTRY_GRUB_CLASS'

The Red Hat BootEntry grub_class key.

boom.bootloader.BOOM_ENTRY_GRUB_ID = 'BOOM_ENTRY_GRUB_ID'

The Red Hat BootEntry id key.

boom.bootloader.BOOM_ENTRY_GRUB_USERS = 'BOOM_ENTRY_GRUB_USERS'

The Red Hat BootEntry grub_users key.

boom.bootloader.BOOM_ENTRY_INITRD = 'BOOM_ENTRY_INITRD'

The BootEntry initrd key.

boom.bootloader.BOOM_ENTRY_LINUX = 'BOOM_ENTRY_LINUX'

The BootEntry linux key.

boom.bootloader.BOOM_ENTRY_MACHINE_ID = 'BOOM_ENTRY_MACHINE_ID'

The BootEntry machine_id key.

boom.bootloader.BOOM_ENTRY_OPTIONS = 'BOOM_ENTRY_OPTIONS'

The BootEntry options key.

boom.bootloader.BOOM_ENTRY_TITLE = 'BOOM_ENTRY_TITLE'

The BootEntry title key.

boom.bootloader.BOOM_ENTRY_VERSION = 'BOOM_ENTRY_VERSION'

The BootEntry version key.

boom.bootloader.BOOT_ENTRIES_FORMAT = '%s-%s-%s.conf'

The format used to construct entry file names.

boom.bootloader.BOOT_ENTRY_MODE = 420

The file mode with which BLS entries should be created.

exception boom.bootloader.BoomRootDeviceError

Bases: BoomError

Boom exception indicating an invalid root device.

__firstlineno__ = 217

__static_attributes__ = ()

class boom.bootloader.BootEntry(title=None, machine_id=None, osprofile=None, boot_params=None, entry_file=None, entry_data=None, architecture=None, allow_no_dev=False)

Bases: object

A class representing a BLS compliant boot entry.

A BootEntry exposes two sets of properties that are the keys of a BootLoader Specification boot entry.

The properties of a BootEntry that is not associated with an OsProfile (for e.g. one read from disk) are the literal values read from a file or set through the API.

When an OSProfile is attached to a BootEntry, it is used as a template to fill out the values of keys for properties including the kernel and initramfs file name. This is used to create new BootEntry objects to be written to disk.

An OsProfile can be attached to a BootEntry when it is created, or at a later time by calling the set_os_profile() method.

__annotations_cache__ = {}

__boot_id = None

__eq__(other)

Test for equality between this BootEntry and another object.

Equality for BootEntry objects is true if the both boot_id values match.

Parameters:

other – The object against which to test.

Returns:

True if the objects are equal and False otherwise.

Return type:

bool

__firstlineno__ = 992

__from_data(entry_data, boot_params)

Initialise a new BootEntry from in-memory data.

Initialise a new BootEntry object with data from the dictionary entry_data (and optionally the supplied BootParams object). The supplied dictionary should be indexed by Boom entry key names (BOOM_ENTRY_*).

Raises ValueError if required keys are missing (BOOM_ENTRY_TITLE, and either BOOM_ENTRY_LINUX or BOOM_ENTRY_EFI).

This method should not be called directly: to build a new BootEntry object from in-memory data, use the class initialiser with the entry_data argument.

Parameters:

• entry_data – A dictionary mapping Boom boot entry key names to values

• boot_params – Optional BootParams to attach to the new BootEntry object

Returns:

None

Return type:

None

Raises:

ValueError

__from_file(entry_file, boot_params)

Initialise a new BootEntry from on-disk data.

Initialise a new BootEntry using the entry data in entry_file (and optionally the supplied BootParams object).

Raises ValueError if required keys are missing (BOOM_ENTRY_TITLE, and either BOOM_ENTRY_LINUX or BOOM_ENTRY_EFI).

This method should not be called directly: to build a new BootEntry object from entry file data, use the class initialiser with the entry_file argument.

Parameters:

• entry_file – The path to a file containing a BLS boot entry

• boot_params – Optional BootParams to attach to the new BootEntry object

Returns:

None

Return type:

None

Raises:

ValueError

__generate_boot_id()

Generate a new boot_id value.

Generate a new sha1 profile identifier for this entry, using the title, version, root_device and any defined LVM2 or BTRFS snapshot parameters.

Returns:

A boot_id string

Return type:

str

__getitem__(key)

Return an item from this BootEntry.

Returns:

the item corresponding to the key requested.

Return type:

the corresponding type of the requested key.

Raises:

TypeError if key is of an invalid type. KeyError if key is valid but not present.

__hash__ = None

__init__(title=None, machine_id=None, osprofile=None, boot_params=None, entry_file=None, entry_data=None, architecture=None, allow_no_dev=False)

Initialise new BootEntry.

Initialise a new BootEntry object from the specified file or using the supplied values.

If osprofile is specified the profile is attached to the new BootEntry and will be used to supply templates for BootEntry values.

A BootParams object may be supplied using the boot_params keyword argument. The object will be used to provide values for substitution using the patterns defined by the configured OsProfile.

If entry_file is specified the BootEntry will be initialised from the values found in the file, which should contain a valid BLS snippet in UTF-8 encoding. The file may contain blank lines and comments (lines beginning with ‘#’), and these will be preserved if the entry is re-written.

If entry_file is not specified, both title and machine_id must be given.

The entry_data keyword argument is an optional argument used to initialise a BootEntry from a dictionary mapping BOOM_ENTRY_* keys to BootEntry values. It may be used to initialised a new BootEntry using the strings obtained from a call to BootEntry.__repr__().

Parameters:

• title – The title for this BootEntry.

• machine_id – The machine_id of this BootEntry.

• osprofile – An optional OsProfile to attach to this BootEntry.

• boot_params – An optional BootParams object to initialise this BooyEntry.

• entry_file – An optional path to a file in the file system containing a boot entry in BLS notation.

• entry_data – An optional dictionary of BootEntry key to value mappings to initialise this BootEntry from.

• architecture – An optional BLS architecture string.

Returns:

A new BootEntry object.

Return type:

BootEntry

__len__()

Return the length (key count) of this BootEntry.

Returns:

the BootEntry length as an integer.

Return type:

int

__match_host_profile()

Attempt to find a matching HostProfile for this BootEntry.

Try to find a HostProfile with a matching machine_id, and if one is found, wrap this BootEntry’s operating system profile with the host.

This method must be called with a valid BootParams object attached.

__match_os_profile()

Attempt to find a matching OsProfile for this BootEntry.

Attempt to guess the correct OsProfile to use with this BootEntry by probing each loaded OsProfile in turn until a profile recognises the entry. If no match is found the entry’s OsProfile is set to None.

Probing is only used in the case that a loaded entry has no embedded OsIdentifier string. All entries written by Boom include the OsIdentifier value: probing is primarily useful for entries that have been manually written or edited.

__os_id_from_comment(comment)

Retrieve OsProfile from BootEntry comment.

Attempt to set this BootEntry’s OsProfile using a comment string stored in the entry file. The comment must be of the form “OsIdentifier: <os_id>”. If found the value is treated as authoritative and a reference to the corresponding OsProfile is stored in the object’s _osp member.

Any comment lines that do not contain an OsIdentifier tag are returned as a multi-line string.

Parameters:

comment – The comment to attempt to parse

Returns:

Comment lines not containing an OsIdentifier

Return type:

str

__repr__()

Format BootEntry as a machine-readable string.

Return a machine readable representation of this BootEntry, in constructor notation.

Returns:

A string in BootEntry constructor syntax.

Return type:

str

__setitem__(key, value)

Set the specified BootEntry key to the given value.

Parameters:

• key – the BootEntry key to be set.

• value – the value to set for the specified key.

__static_attributes__ = ('__boot_id', '_bp', '_bp_generation', '_comments', '_entry_data', '_last_path', '_osp', '_suppress_machine_id', '_unwritten', 'architecture', 'bp', 'machine_id', 'read_only', 'sort_key', 'title')

__str(quote=False, prefix='', suffix='', tail='\n', sep=' ', bls=True, no_boot_id=False, expand=False)

Format BootEntry as a string.

Return a human or machine readable representation of this BootEntry.

Parameters:

quote – True if values should be quoted or False otherwise.

:param prefix:An optional prefix string to be concatenated with

with the start of the formatted string.

Parameters:

• suffix – An optional suffix string to be concatenated with the end of the formatted string.

• tail – A string to be concatenated between subsequent records in the formatted string.

• sep – A separator to be inserted between each name and value. Normally either ‘ ‘ or ‘=’.

• bls – Generate output using BootLoader Specification syntax and key names.

• no_boot_id – Do not include the BOOM_ENTRY_BOOT_ID key in the returned string. Used internally in order to avoid recursion when calculating the BOOM_ENTRY_BOOT_ID checksum.

Returns:

A string representation.

Return type:

string

__str__()

Format BootEntry as a human-readable string in BLS notation.

Format this BootEntry as a string containing a BLS configuration snippet.

Returns:

a BLS configuration snippet corresponding to this entry.

Return type:

string

_apply_format(fmt)

Apply key format string substitution.

Apply format key substitution to format string fmt, using values provided by an attached BootParams object, and string patterns from either an associated OsProfile object, or values set directly in this BootEntry.

If the source of data for a key is empty or None, the string is returned unchanged.

The currently defined format keys are:

• %{version} The kernel version string.

• %{lvm_root_lv} The LVM2 logical volume containing the root file system.

• %{btrfs_subvolume} The root flags specifying the BTRFS subvolume containing the root file system.

• %{root_device} The device containing the root file system.

• %{root_opts} The command line options required for the root file system.

• %{linux} The linux image to boot

• %{os_name} The OS Profile name

• %{os_short_name The OS Profile short name

• %{os_version} The OS Profile version

• %{os_version id The OS Profile version ID

Parameters:

fmt – The string to be formatted.

Returns:

The formatted string

Return type:

str

_bp = None

_bp_generation = None

_comments = None

_dirty()

Mark this BootEntry as needing to be written to disk.

A newly created BootEntry object is always dirty and a call to its write_entry() method will always write a new boot entry file. Writes may be avoided for entries that are not marked as dirty.

A clean BootEntry is marked as dirty if a new value is written to any of its writable properties.

Return type:

None

_entry_data = None

_entry_data_property(name)

Return property value from entry data.

Parameters:

name – The boom key name of the property to return

Returns:

The property value from the entry data dictionary

property _entry_path

_have_optional_key(key)

Return True if optional BLS key key is permitted by the attached OsProfile, or False otherwise.

_initrd(expand=False)

Return the initrd string with or without variable expansion.

Since some distributions use bootloader environment variables to define auxiliary initramfs images, the initrd property is optionally subject to the same variable expansion as the options property.

Parameters:

expand – True if variables should be expanded or False otherwise.

Returns:

An initrd string

Return type:

string

_last_path = None

_options(expand=False)

The command line options for this BootEntry, optionally expanding any bootloader environment variables to their current values.

Parameters:

expand – Whether or not to expand bootloader environment variable references.

Return type:

string

_osp = None

_suppress_machine_id = False

_unwritten = False

property architecture

The EFI machine type string for this BootEntry.

Getter:

returns the configured architecture.

Setter:

sets the architecture for this entry.

Type:

string

property boot_id

A SHA1 digest that uniquely identifies this BootEntry.

Getter:

return this BootEntry’s boot_id.

Type:

string

property bp

The BootParams object associated with this BootEntry.

delete_entry()

Remove on-disk BootEntry file.

Remove the on-disk entry corresponding to this BootEntry object. This will permanently erase the current file (although the current data may be re-written at any time by calling write_entry()).

Return type:

NoneType

Raises:

OsError if an error occurs removing the file or ValueError if the entry does not exist.

property devicetree

The devicetree archive for this BootEntry.

Getter:

returns the configured device tree archive.

Getter:

sets the configured device tree archive.

Type:

string

property disp_boot_id

The display boot_id of this entry.

Return the shortest prefix of this BootEntry’s boot_id that is unique within the current set of loaded entries.

Getter:

return this BootEntry’s boot_id.

Type:

str

property efi

The loadable EFI image for this BootEntry.

Getter:

returns the configured EFI application image.

Getter:

sets the configured EFI application image.

Type:

string

property entry_path

The path to the on-disk file containing this BootEntry.

property expand_initrd

The loadable initramfs image for this BootEntry with any embedded bootloader variable references expanded.

Getter:

returns the configured initrd image.

Getter:

sets the configured initrd image.

Type:

string

property expand_options

The command line options for this BootEntry, with any bootloader environment variables expanded to their current values.

Return the command line options for this BootEntry, expanding any Boom or Grub2 substitution notation found.

Getter:

returns the command line for this BootEntry.

Setter:

sets the command line for this BootEntry.

Type:

string

expanded()

Return a string representation of this BootEntry, with any bootloader environment variables expanded to their current values.

Returns:

A string representation of this BootEntry.

Return type:

string

property grub_arg

The current grub_arg key for this entry.

Getter:

Return the current grub_arg value.

Setter:

Store a new grub_arg value.

Type:

string

property grub_class

The current grub_class key for this entry.

Getter:

Return the current grub_class value.

Setter:

Store a new grub_class value.

Type:

string

property grub_users

The current grub_users key for this entry.

Getter:

Return the current grub_users value.

Setter:

Store a new grub_users value.

Type:

string

property id

The value of the id key for this entry.

Getter:

Return the current id value.

Setter:

Store a new id value.

Type:

string

property initrd

The loadable initramfs image for this BootEntry.

Getter:

returns the configured initrd image.

Getter:

sets the configured initrd image.

Type:

string

items()

Return the items list for this BootEntry.

Return a copy of this BootEntry’s (key, value) pairs as a list.

Returns:

the current list of BotoEntry items.

Return type:

list of (key, value) tuples.

keys()

Return the list of keys for this BootEntry.

Return a copy of this BootEntry’s keys as a list of key name strings.

Returns:

the current list of BotoEntry keys.

Return type:

list of str

property linux

The bootable Linux image for this BootEntry.

Getter:

returns the configured linux image.

Setter:

sets the configured linux image.

Type:

string

property machine_id

The machine_id of this BootEntry.

Getter:

returns this BootEntry object’s machine_id.

Setter:

sets this BootEntry object’s machine_id.

Type:

string

property options

The command line options for this BootEntry, including any bootloader environment variable references as they appear.

Getter:

returns the command line for this BootEntry.

Setter:

sets the command line for this BootEntry.

Type:

string

read_only = False

property root_opts

The root options that should be used for this BootEntry.

Getter:

Returns the root options string for this BootEntry.

Type:

string

property sort_key

The sort-key value for this ``BootEntry.

Getter:

returns the configured sort key.

Setter:

sets the configured sort key.

Type:

string

property title

The title of this BootEntry.

Getter:

returns the BootEntry title.

Setter:

sets this BootEntry object’s title.

Type:

string

update_entry(force=False, expand=False)

Update on-disk entry.

Update this BootEntry’s on-disk data.

The file will be named according to the entry’s key values, and the value of the BOOT_ENTRIES_FORMAT constant. Currently the machine_id and version keys are used to construct the file name.

If this BootEntry previously existed on-disk, and the boot_id has changed due to a change in entry key values, the old BootEntry file will be unlinked once the new data has been successfully written. If the entry does not already exist then calling this method is the equivalent of calling BootEntry.write_entry().

If the value of force is False and the BootEntry is not currently marked as dirty (either new, or modified since the last load operation) the write will be skipped.

Parameters:

• force – Force this entry to be written to disk even if the entry is unmodified.

• expand – Expand bootloader environment variables in on-disk entry.

Raises:

OSError if the temporary entry file cannot be renamed, or if setting file permissions on the new entry file fails.

Return type:

None

values()

Return the list of values for this BootEntry.

Return a copy of this BootEntry’s values as a list.

Returns:

the current list of BootEntry values.

Return type:

list

property version

The version string associated with this BootEntry.

Getter:

returns this BootEntry object’s version.

Setter:

sets this BootEntry object’s version.

Type:

string

write_entry(force=False, expand=False)

Write out entry to disk.

Write out this BootEntry’s data to a file in BLS format to the path specified by boom_entries_path().

The file will be named according to the entry’s key values, and the value of the BOOT_ENTRIES_FORMAT constant. Currently the machine_id and version keys are used to construct the file name.

If the value of force is False and the OsProfile is not currently marked as dirty (either new, or modified since the last load operation) the write will be skipped.

Parameters:

• force – Force this entry to be written to disk even if the entry is unmodified.

• expand – Expand bootloader environment variables in on-disk entry.

Raises:

OSError if the temporary entry file cannot be renamed, or if setting file permissions on the new entry file fails.

Return type:

None

class boom.bootloader.BootParams(version, root_device=None, lvm_root_lv=None, btrfs_subvol_path=None, btrfs_subvol_id=None, stratis_pool_uuid=None, add_opts=None, del_opts=None)

Bases: object

The BootParams class encapsulates the information needed to boot an instance of the operating system: the kernel version, root device, and root device options.

A BootParams object is used to configure a BootEntry and to generate configuration keys for the entry based on an attached OsProfile.

__annotate_func__ = None

__annotations_cache__ = {}

__firstlineno__ = 310

__init__(version, root_device=None, lvm_root_lv=None, btrfs_subvol_path=None, btrfs_subvol_id=None, stratis_pool_uuid=None, add_opts=None, del_opts=None)

Initialise a new BootParams object.

The root device is specified via the root_device argument as a path relative to the root file system.

The LVM2 logical volume containing the root file system is specified using lvm_root_lv if LVM2 is used.

For instances using LVM2, if the lvm_root_lv argument is set and root_device is unset, root_device is assumed to be the normal path of the logical volume specified by the lvm_root_lv argument.

For instances using BTRFS, the root_device argument is always required.

Instances using BTRFS may select a subvolume to be mounted as the root file system by specifying either the subvolume path or id via btrfs_subvol_path and btrfs_subvol_id.

BootParams() raises ValueError if a required argument is missing, or if conflicting arguments are present.

Parameters:

• version – The version string for this BootParams object.

• root_device – The root device for this BootParams object.

• lvm_root_lv – The LVM2 logical volume containing the root file system, for systems that use LVM.

• btrfs_subvol_path – The BTRFS subvolume path containing the root file system, for systems using BTRFS.

• btrfs_subvol_id – The BTRFS subvolume ID containing the root file system, for systems using BTRFS.

• stratis_pool_uuid – The UUID of the Stratis pool that contains root_device.

• add_opts – A list containing additional kernel options to be appended to the command line.

• del_opts – A list containing kernel options to be dropped from the command line.

Returns:

a newly initialised BootParams object.

Return type:

class BootParams

Raises:

ValueError

__repr__()

Format BootParams as a machine-readable string.

Format this BootParams object as a machine-readable string. The string returned is in the form of a call to the BootParams constructor.

Returns:

a machine readable string representation of this BootParams object.

__static_attributes__ = ('_add_opts', '_btrfs_subvol_id', '_btrfs_subvol_path', '_del_opts', '_lvm_root_lv', '_root_device', '_stratis_pool_uuid', '_version', 'add_opts', 'btrfs_subvol_id', 'btrfs_subvol_path', 'del_opts', 'lvm_root_lv', 'root_device', 'version')

__str(quote=False, prefix='', suffix='')

Format BootParams as a string.

Format this BootParams object as a string, with optional prefix, suffix, and value quoting.

Parameters:

• quote – A bool indicating whether to quote values.

• prefix – An optional prefix string to be concatenated with the start of the formatted string.

• suffix – An optional suffix string to be concatenated with the end of the formatted string.

Returns:

a formatted representation of this BootParams.

Return type:

string

__str__()

Format BootParams as a human-readable string.

Format this BootParams object as a human-readable string.

Returns:

A human readable string representation of this BootParams object.

Return type:

string

_add_opts = []

A list of additional kernel options to append

_btrfs_subvol_id = None

The ID of the BTRFS subvolume to be used as the root file system.

_btrfs_subvol_path = None

The BTRFS subvolume path to be used as the root file system.

_del_opts = []

A list of kernel options to drop

_lvm_root_lv = None

The LVM2 logical volume containing the root file system

_root_device = None

The path to the root device

_stratis_pool_uuid = None

The UUID of the Stratis pool containing the root_device.

_version = None

The kernel version of the instance.

property add_opts

Return this BootParams object’s add_opts.

property btrfs_subvol_id

Return this BootParams object’s btrfs_subvol_id.

property btrfs_subvol_path

Return this BootParams object’s btrfs_subvol_path.

property del_opts

Return this BootParams object’s del_opts.

classmethod from_entry(be, expand=False)

Recover BootParams from BootEntry.

Recover BootParams values from a templated BootEntry: each key subject to template substitution is transformed into a regular expression, matching the element and capturing the corresponding BootParams value.

A BootEntry object that has no attached OsProfile cannot be reversed since no templates exist to match the entry against: in this case None is returned but no exception is raised. The entry may be modified and re-written, but no templating is possible unless a new, valid, OsProfile is attached.

Parameters:

• be – The BootEntry to recover BootParams from.

• expand – Expand bootloader environment variables.

Returns:

A newly initialised BootParams object.

Return type:

BootParams

Raises:

ValueError if expected values cannot be matched.

generation = 0

Generation counter for dirty detection

has_btrfs()

Return True if this BootParams object is configured to use BTRFS.

Returns:

True if BTRFS is in use, or False otherwise

Return type:

bool

has_lvm2()

Return True if this BootParams object is configured to use LVM2.

Returns:

True if LVM2 is in use, or False otherwise

Return type:

bool

has_stratis()

Return True if this BootParams object is configured to use a Stratis root file system.

Returns:

True if Stratis is in use, or False otherwise.

Return type:

bool

property lvm_root_lv

Return this BootParams object’s lvm_root_lv.

property root_device

Return this BootParams object’s root_device.

property stratis_pool_uuid

Return this BootParams object’s stratis_pool_uuid.

property version

Return this BootParams object’s version.

boom.bootloader.DEV_PATTERN = '/dev/%s'

Pattern for forming root device paths from LVM2 names.

boom.bootloader.ENTRY_KEYS = ['BOOM_ENTRY_TITLE', 'BOOM_ENTRY_MACHINE_ID', 'BOOM_ENTRY_VERSION', 'BOOM_ENTRY_LINUX', 'BOOM_ENTRY_EFI', 'BOOM_ENTRY_INITRD', 'BOOM_ENTRY_OPTIONS', 'BOOM_ENTRY_DEVICETREE', 'BOOM_ENTRY_ARCHITECTURE', 'BOOM_ENTRY_SORT_KEY', 'BOOM_ENTRY_GRUB_ID', 'BOOM_ENTRY_GRUB_USERS', 'BOOM_ENTRY_GRUB_ARG', 'BOOM_ENTRY_GRUB_CLASS']

An ordered list of all possible BootEntry keys.

boom.bootloader.OPTIONAL_KEYS = ['BOOM_ENTRY_GRUB_USERS', 'BOOM_ENTRY_GRUB_ARG', 'BOOM_ENTRY_GRUB_CLASS', 'BOOM_ENTRY_GRUB_ID']

Optional keys not defined by the upstream BLS specification.

boom.bootloader.boom_entries_path()

Return the path to the boom profiles directory.

Returns:

The boom profiles path.

Return type:

str

boom.bootloader.drop_entries()

Drop all in-memory entries.

Clear the list of in-memory entries and reset the BootEntry list to the default state.

Returns:

None

boom.bootloader.find_entries(selection=None)

Find boot entries matching selection criteria.

Return a list of BootEntry objects matching the specified criteria. Matching proceeds as the logical ‘and’ of all criteria. Criteria that are unset (None) are ignored.

If no BootEntry matches the specified criteria the empty list is returned.

Boot entries will be automatically loaded from disk if they are not already in memory.

Parameters:

selection – A Selection object specifying the match criteria for the operation.

Returns:

a list of BootEntry objects.

Return type:

list

boom.bootloader.key_to_bls_name(key)

Return the BLS key name for the corresponding Boom entry key.

Parameters:

key – A Boom entry key.

Returns:

A string representing the BLS key name.

Return type:

str

boom.bootloader.load_entries(machine_id=None)

Load boot entries into memory.

Load boot entries from boom.bootloader.boom_entries_path().

If machine_id is specified only matching entries will be considered.

Parameters:

machine_id – A machine_id value to match.

boom.bootloader.min_boot_id_width()

Calculate the minimum unique width for boot_id values.

Calculate the minimum width to ensure uniqueness when displaying boot_id values.

Returns:

the minimum boot_id width.

Return type:

int

boom.bootloader.optional_key_default(key)

Return the default value for the optional key key.

Parameters:

key – A Boom optional entry key.

Returns:

The default value for optional key key.

Return type:

str

boom.bootloader.write_entries()

Write out boot entries.

Write all currently loaded boot entries to boom.bootloader.boom_entries_path().

boom.osprofile module

The boom.osprofile module defines the OsProfile class that represents an operating system profile. An OsProfile defines the identity of a profile and includes template values used to generate boot loader entries.

Functions are provided to read and write operating system profiles from an on-disk store, and to retrieve OsProfile instances using various selection criteria.

The OsProfile class includes named properties for each profile attribute (“profile key”). In addition, the class serves as a container type, allowing attributes to be accessed via dictionary-style indexing. This simplifies iteration over a profile’s key / value pairs and allows straightforward access to all members in scripts and the Python shell.

All profile key names are made available as named members of the module: BOOM_OS_*, and the OS_PROFILE_KEYS list. Human-readable names for all the profile keys are stored in the OS_KEY_NAMES dictionary: these are suitable for display use and are used by default by the OsProfile string formatting routines.

boom.osprofile.BOOM_OS_ID = 'BOOM_OS_ID'

Constant for the Boom OS identifier profile key.

boom.osprofile.BOOM_OS_INITRAMFS_PATTERN = 'BOOM_OS_INITRAMFS_PATTERN'

Constant for the Boom OS initramfs pattern profile key.

boom.osprofile.BOOM_OS_KERNEL_PATTERN = 'BOOM_OS_KERNEL_PATTERN'

Constant for the Boom OS kernel pattern profile key.

boom.osprofile.BOOM_OS_NAME = 'BOOM_OS_NAME'

Constant for the Boom OS name profile key.

boom.osprofile.BOOM_OS_OPTIONAL_KEYS = 'BOOM_OS_OPTIONAL_KEYS'

Constant for the Boom OS optional keys key.

boom.osprofile.BOOM_OS_OPTIONS = 'BOOM_OS_OPTIONS'

Constant for the Boom OS command line options key.

boom.osprofile.BOOM_OS_PROFILE_FORMAT = '%s-%s%s.profile'

File name format for Boom profiles.

boom.osprofile.BOOM_OS_ROOT_OPTS_BTRFS = 'BOOM_OS_ROOT_OPTS_BTRFS'

Constant for the Boom OS BTRFS root options key.

boom.osprofile.BOOM_OS_ROOT_OPTS_LVM2 = 'BOOM_OS_ROOT_OPTS_LVM2'

Constant for the Boom OS LVM2 root options key.

boom.osprofile.BOOM_OS_SHORT_NAME = 'BOOM_OS_SHORT_NAME'

Constant for the Boom OS short name profile key.

boom.osprofile.BOOM_OS_TITLE = 'BOOM_OS_TITLE'

Constant for the Boom OS title template key.

boom.osprofile.BOOM_OS_UNAME_PATTERN = 'BOOM_OS_UNAME_PATTERN'

Constant for the Boom OS uname pattern profile key.

boom.osprofile.BOOM_OS_VERSION = 'BOOM_OS_VERSION'

Constant for the Boom OS version string profile key.

boom.osprofile.BOOM_OS_VERSION_ID = 'BOOM_OS_VERSION_ID'

Constant for the Boom OS version ID string profile key.

boom.osprofile.BOOM_PROFILES = 'profiles'

Boom profiles directory name.

boom.osprofile.BOOM_PROFILE_MODE = 420

The file mode with which to create Boom profiles.

class boom.osprofile.BoomProfile(profile_keys, required_keys, identity_key)

Bases: object

Class BoomProfile is the abstract base class for Boom template profiles. The BoomProfile class cannot be instantiated by itself but serves as the base class for both OsProfile and HostProfile instances.

__annotate_func__ = None

__annotations_cache__ = {}

__firstlineno__ = 483

__getitem__(key)

Return an item from this profile.

Returns:

the item corresponding to the key requested.

Return type:

the corresponding type of the requested key.

Raises:

TypeError if key is of an invalid type. KeyError if key is valid but not present.

__init__(profile_keys, required_keys, identity_key)

Initialise a new BoomProfile object.

This method should be called by all subclasses of BoomProfile in order to initialise the base class state.

Subclasses must provide the set of allowed keys for this profile type, a list of keys that are mandatory for profile creation, and the name of the identity key that will return this profile’s unique identifier.

Parameters:

• profile_keys – The set of keys used by this profile.

• required_keys – Mandatory keys for this profile.

• identity_key – The key containing the profile id.

Returns:

A new BoomProfile object.

Return type:

class BoomProfile

__len__()

Return the length (key count) of this profile.

Returns:

the profile length as an integer.

Return type:

int

__repr__()

Format this BoomProfile as a machine readable string.

This method must be implemented by concrete profile classes.

Returns:

a string representation of this BoomProfile.

Return type:

string

__setitem__(key, value)

Set the specified Profile key to the given value.

Parameters:

• key – the Profile key to be set.

• value – the value to set for the specified key.

__static_attributes__ = ('_comments', '_identity_key', '_profile_keys', '_required_keys', '_unwritten', 'optional_keys')

__str__()

Format this profile as a human readable string.

This method must be implemented by concrete profile classes.

Returns:

A human readable string representation of this BoomProfile.

Return type:

string

_append_profile()

Append a BoomProfile to the appropriate global profile list

This method must be overridden by classes that extend BoomProfile.

Returns:

None

Raises:

NotImplementedError

_check_optional_key(optional_key)

Check that they optional key key is a valid, known BLS optional key and raise ValueError if it is not.

_comments = None

Comment descriptors read from on-disk store

_delete_profile(profile_id)

Deletion helper for profile classes.

Remove the on-disk profile corresponding to this BoomProfile object. This will permanently erase the current file (although the current data may be re-written at any time by calling write_profile() before the object is disposed of).

The method will call the profile class’s _profile_path() method in order to determine the location of the on-disk profile store.

Return type:

NoneType

Raises:

OsError if an error occurs removing the file or ValueError if the profile does not exist.

_dirty()

Mark this BoomProfile as needing to be written to disk.

A newly created BoomProfile object is always dirty and a call to its write_profile() method will always write a new profile file. Writes may be avoided for profiles that are not marked as dirty.

A clean BoomProfile is marked as dirty if a new value is written to any of its writable properties.

Returns None:

_from_data(profile_data, dirty=True)

This method must be implemented by concrete profile classes.

_from_file(profile_file)

Initialise a new profile from data stored in a file.

Initialise a new profile object using the profile data in profile_file.

This method should not be called directly: to build a new Boomprofile object from in-memory data, use the class initialiser with the profile_file argument.

Returns:

None

_generate_id()

Generate a new profile identifier.

Generate a new sha1 profile identifier for this profile.

Subclasses of BoomProfile must override this method to generate an appropriate hash value, using the corresponding identity keys for the profile type.

Returns:

None

Raises:

NotImplementedError

_identity_key = None

The identity key for this profile class

_profile_data = None

Profile data dictionary

_profile_keys = None

Key set for this profile class

_profile_path()

Return the path to this profile’s on-disk data.

Return the full path to this Profile in the appropriate Boom profile directory. Subclasses of BoomProfile must override this method to return the correct path for the specific profile type.

Return type:

str

Returns:

The absolute path for this BoomProfile file

Raises:

NotImplementedError

_required_keys = None

Mandatory keys for this profile class

_unwritten = False

Dirty flag

_write_profile(profile_id, profile_dir, mode, force=False)

Write helper for profile classes.

Write out this profile’s data to a file in Boom format to the paths specified by the current configuration.

The pathname to write is obtained from self._profile_path().

If the value of force is False and the profile is not currently marked as dirty (either new, or modified since the last load operation) the write will be skipped.

Parameters:

• profile_id – The os_id or host_id of this profile.

• profile_dir – The directory containing this type.

• mode – The mode with which files are created.

• force – Force this profile to be written to disk even if the entry is unmodified.

Raises:

OsError if the temporary entry file cannot be renamed, or if setting file permissions on the new entry file fails.

add_optional_key(key)

Add the BLS key key to the allowed set of optional keys for this profile.

del_optional_key(key)

Remove the BLS key key from the allowed set of optional keys for this profile.

delete_profile()

Delete on-disk data for this profile.

Remove the on-disk profile corresponding to this BoomProfile object. This will permanently erase the current file (although the current data may be re-written at any time by calling write_profile() before the object is disposed of).

Subclasses of BoomProfile that implement an on-disk store must override this method to perform any unlinking of the profile from in-memory data structures, and to call the generic _delete_profile() method to remove the profile file.

Return type:

NoneType

Raises:

OsError if an error occurs removing the file or ValueError if the profile does not exist.

property initramfs_pattern

The current initramfs_pattern setting of this profile.

Getter:

returns the initramfs_pattern as a string.

Setter:

store a new initramfs_pattern setting.

Type:

string

items()

Return the items list for this BoomProfile.

Return a list of (key, value) tuples representing the key items in this BoomProfile.

Return type:

list

Returns:

A list of BoomProfile key item tuples

property kernel_pattern

The current kernel_pattern setting of this profile.

Getter:

returns the kernel_pattern as a string.

Setter:

stores a new kernel_pattern setting.

Type:

string

keys()

Return the list of keys for this BoomProfile.

Return type:

list

Returns:

A list of BoomProfile key names

make_format_regexes(fmt)

Generate regexes matching format string

Generate a list of (key, expr) tuples containing key and regular expression pairs capturing the format key values contained in the format string. Any non-format key words contained in the string are returned as a ('', expr) tuple containing no capture groups.

The resulting list may be matched against the words of a BootEntry object’s value strings in order to extract the parameters used to create them.

Parameters:

fmt – The format string to build a regex list from.

Returns:

A list of key and word regex tuples.

Return type:

list of (str, str)

match_options(entry)

Test BoomProfile for options template match.

Test the supplied BootEntry to determine whether it matches the options template defined by this BoomProfile.

Used as a match of last resort when no uname pattern match exists.

Parameters:

entry – A BootEntry to match against this profile.

Returns:

True if this entry matches this profile, or False otherwise.

Return type:

bool

match_uname_version(version)

Test BoomProfile for version string match.

Test the supplied version string to determine whether it matches the uname_pattern of this BoomProfile.

Parameters:

version – A uname release version string to match.

Returns:

True if this version matches this profile, or False otherwise.

Return type:

bool

property optional_keys

The set of optional BLS keys allowed by this profile.

Getter:

returns a string containing optional BLS key names.

Setter:

store a new set of optional BLS keys.

Type:

string

property options

The current kernel command line options setting for this profile.

Getter:

returns the options value as a string.

Setter:

store a new options value.

Type:

string

property os_name

The os_name of this profile.

Getter:

returns the os_name as a string.

Type:

string

property os_short_name

The os_short_name of this profile.

Getter:

returns the os_short_name as a string.

Type:

string

property os_version

The os_version of this profile.

Getter:

returns the os_version as a string.

Type:

string

property os_version_id

The version_id of this profile.

Getter:

returns the os_version_id as a string.

Type:

string

property root_opts_btrfs

The current BTRFS root options setting of this profile.

Getter:

returns the root_opts_btrfs value as a string.

Setter:

store a new root_opts_btrfs value.

Type:

string

property root_opts_lvm2

The current LVM2 root options setting of this profile.

Getter:

returns the root_opts_lvm2 value as a string.

Setter:

store a new root_opts_lvm2 value.

Type:

string

property title

The current title template for this profile.

Getter:

returns the title value as a string.

Setter:

store a new title value.

Type:

string

property uname_pattern

The current uname_pattern setting of this profile.

Getter:

returns the uname_pattern as a string.

Setter:

stores a new uname_pattern setting.

Type:

string

values()

Return the list of key values for this BoomProfile.

Return type:

list

Returns:

A list of BoomProfile key values

write_profile(force=False)

Write out profile data to disk.

Write out this BoomProfile’s data to a file in Boom format to the paths specified by the current configuration.

This method must be overridden by BoomProfile subclasses.

Raises:

OsError if the temporary entry file cannot be renamed, or if setting file permissions on the new entry file fails. NotImplementedError if the method is called on the BoomProfile base class.

boom.osprofile.OS_KEY_NAMES = {'BOOM_OS_ID': 'OS ID', 'BOOM_OS_INITRAMFS_PATTERN': 'Initramfs pattern', 'BOOM_OS_KERNEL_PATTERN': 'Kernel pattern', 'BOOM_OS_NAME': 'Name', 'BOOM_OS_OPTIONAL_KEYS': 'Optional keys', 'BOOM_OS_OPTIONS': 'Options', 'BOOM_OS_ROOT_OPTS_BTRFS': 'Root options (BTRFS)', 'BOOM_OS_ROOT_OPTS_LVM2': 'Root options (LVM2)', 'BOOM_OS_SHORT_NAME': 'Short name', 'BOOM_OS_TITLE': 'Title', 'BOOM_OS_UNAME_PATTERN': 'UTS release pattern', 'BOOM_OS_VERSION': 'Version', 'BOOM_OS_VERSION_ID': 'Version ID'}

A map of Boom profile keys to human readable key names suitable for use in formatted output. These key names are used to format a OsProfile object as a human readable string.

boom.osprofile.OS_PROFILE_KEYS = ['BOOM_OS_ID', 'BOOM_OS_NAME', 'BOOM_OS_SHORT_NAME', 'BOOM_OS_VERSION', 'BOOM_OS_VERSION_ID', 'BOOM_OS_KERNEL_PATTERN', 'BOOM_OS_INITRAMFS_PATTERN', 'BOOM_OS_ROOT_OPTS_LVM2', 'BOOM_OS_ROOT_OPTS_BTRFS', 'BOOM_OS_OPTIONS', 'BOOM_OS_TITLE', 'BOOM_OS_OPTIONAL_KEYS', 'BOOM_OS_UNAME_PATTERN']

Ordered list of possible profile keys, partitioned into mandatory keys, root option keys, and optional keys (currently the Linux kernel command line).

boom.osprofile.OS_REQUIRED_KEYS = ['BOOM_OS_ID', 'BOOM_OS_NAME', 'BOOM_OS_SHORT_NAME', 'BOOM_OS_VERSION', 'BOOM_OS_VERSION_ID', 'BOOM_OS_KERNEL_PATTERN', 'BOOM_OS_INITRAMFS_PATTERN']

Boom profile keys that must exist in a valid profile.

boom.osprofile.OS_ROOT_KEYS = ['BOOM_OS_ROOT_OPTS_BTRFS']

Boom profile keys for different forms of root device specification.

class boom.osprofile.OsProfile(name=None, short_name=None, version=None, version_id=None, profile_file=None, profile_data=None, uname_pattern=None, kernel_pattern=None, initramfs_pattern=None, root_opts_lvm2=None, root_opts_btrfs=None, options=None, optional_keys=None)

Bases: BoomProfile

Class OsProfile implements Boom operating system profiles. Objects of type OsProfile define the paths, kernel command line options, root device flags and file name patterns needed to boot an instance of that operating system.

__annotate_func__ = None

__annotations_cache__ = {}

__firstlineno__ = 1265

__init__(name=None, short_name=None, version=None, version_id=None, profile_file=None, profile_data=None, uname_pattern=None, kernel_pattern=None, initramfs_pattern=None, root_opts_lvm2=None, root_opts_btrfs=None, options=None, optional_keys=None)

Initialise a new OsProfile object.

If neither profile_file nor profile_data is given, all of name, short_name, version, and version_id must be given.

These values form the profile identity and are used to generate the profile unique identifier.

Parameters:

• name – The name of the operating system.

• short_name – A short name for the operating system, suitable for use in file names.

• version – A string describing the version of the operating system.

• version_id – A short alphanumeric string representing the operating system version and suitable for use in generating file names.

• profile_data – An optional dictionary mapping from BOOM_OS_* keys to profile values.

• profile_file – An optional path to a file from which profile data should be loaded. The file should be in Boom profile format, with BOOM_OS_* key=value pairs.

• uname_pattern – Optional uname pattern.

• kernel_pattern – Optional kernel pattern.

• initramfs_pattern – Optional initramfs pattern.

• root_opts_lvm2 – Optional LVM2 root options template.

• root_opts_btrfs – Optional BTRFS options template.

• options – Optional options template.

Returns:

A new OsProfile object.

Return type:

class OsProfile

__repr__()

Format this OsProfile as a machine readable string.

Return a machine-readable representation of this OsProfile object. The string is formatted as a call to the OsProfile constructor, with values passed as a dictionary to the profile_data keyword argument.

Returns:

a string representation of this OsProfile.

Return type:

string

__static_attributes__ = ('_comments', '_profile_data', 'optional_keys')

__str__()

Format this OsProfile as a human readable string.

Profile attributes are printed as “Name: value, “ pairs, with like attributes grouped together onto lines.

Returns:

A human readable string representation of this OsProfile.

Return type:

string

_append_profile()

Append an OsProfile to the global profile list

Check whether this OsProfile already exists, and add it to the global profile list if not. If the profile is already present ValueError is raised.

Raises:

ValueError

_comments = None

Comment descriptors read from on-disk store

_from_data(profile_data, dirty=True)

Initialise an OsProfile from in-memory data.

Initialise a new OsProfile object using the profile data in the profile_data dictionary.

This method should not be called directly: to build a new Osprofile object from in-memory data, use the class initialiser with the profile_data argument.

Returns:

None

_from_file(profile_file)

Initialise a new profile from data stored in a file.

Initialise a new profil object using the profile data in profile_file.

This method should not be called directly: to build a new Osprofile object from in-memory data, use the class initialiser with the profile_file argument.

Returns:

None

_generate_id()

Generate a new OS identifier.

Generate a new sha1 profile identifier for this profile, using the os_short_name, version, and version_id values and store it in _profile_data.

Returns:

None

_identity_key = 'BOOM_OS_ID'

The identity key for this profile class

_profile_data = None

Profile data dictionary

_profile_keys = ['BOOM_OS_ID', 'BOOM_OS_NAME', 'BOOM_OS_SHORT_NAME', 'BOOM_OS_VERSION', 'BOOM_OS_VERSION_ID', 'BOOM_OS_KERNEL_PATTERN', 'BOOM_OS_INITRAMFS_PATTERN', 'BOOM_OS_ROOT_OPTS_LVM2', 'BOOM_OS_ROOT_OPTS_BTRFS', 'BOOM_OS_OPTIONS', 'BOOM_OS_TITLE', 'BOOM_OS_OPTIONAL_KEYS', 'BOOM_OS_UNAME_PATTERN']

Key set for this profile class

_profile_path()

Return the path to this profile’s on-disk data.

Return the full path to this OsProfile in the Boom profiles directory (or the location to which it will be written, if it has not yet been written).

Return type:

str

Returns:

The absolute path for this OsProfile’s file

_required_keys = ['BOOM_OS_ID', 'BOOM_OS_NAME', 'BOOM_OS_SHORT_NAME', 'BOOM_OS_VERSION', 'BOOM_OS_VERSION_ID', 'BOOM_OS_KERNEL_PATTERN', 'BOOM_OS_INITRAMFS_PATTERN']

Mandatory keys for this profile class

_unwritten = False

Dirty flag

delete_profile()

Delete on-disk data for this profile.

Remove the on-disk profile corresponding to this OsProfile object. This will permanently erase the current file (although the current data may be re-written at any time by calling write_profile() before the object is disposed of).

Return type:

NoneType

Raises:

OsError if an error occurs removing the file or ValueError if the profile does not exist.

property disp_os_id

The display os_id of this profile.

Return the shortest prefix of this OsProfile’s os_id that is unique within the current set of loaded profiles.

Getter:

return this OsProfile’s os_id.

Type:

str

classmethod from_host_os_release(profile_data={})

Build an OsProfile from the current hosts’s os-release.

Construct a new OsProfile object using data obtained from the running hosts’s /etc/os-release file.

Parameters:

profile_data – an optional dictionary of profile data overriding default values.

Returns:

A new OsProfile for the current host

Return type:

OsProfile

classmethod from_os_release(os_release, profile_data=None)

Build an OsProfile from os-release file data.

Construct a new OsProfile object using data obtained from a file in os-release(5) format.

Parameters:

• os_release – String data in os-release(5) format

• profile_data – an optional dictionary of profile data overriding default values.

Returns:

A new OsProfile for the specified os-release data

Return type:

OsProfile

classmethod from_os_release_file(path, profile_data={})

Build an OsProfile from an on-disk os-release file.

Construct a new OsProfile object using data obtained from the file specified by ‘path’.

Parameters:

• path – Path to a file in os-release(5) format

• profile_data – an optional dictionary of profile data overriding default values.

Returns:

A new OsProfile for the specified os-release file

Return type:

OsProfile

property os_id

The os_id of this profile.

Getter:

returns the os_id as a string.

Type:

string

write_profile(force=False)

Write out profile data to disk.

Write out this OsProfile’s data to a file in Boom format to the paths specified by the current configuration.

Currently the os_id, short_name and version_id keys are used to construct the file name.

If the value of force is False and the OsProfile is not currently marked as dirty (either new, or modified since the last load operation) the write will be skipped.

Parameters:

force – Force this profile to be written to disk even if the entry is unmodified.

Raises:

OsError if the temporary entry file cannot be renamed, or if setting file permissions on the new entry file fails.

boom.osprofile.boom_profiles_path()

Return the path to the boom profiles directory.

Returns:

The boom profiles path.

Return type:

str

boom.osprofile.drop_profiles()

Drop all in-memory profiles.

Clear the list of in-memory profiles and reset the OsProfile list to the default state.

Returns:

None

boom.osprofile.find_profiles(selection=None, match_fn=<function select_profile>)

Find profiles matching selection criteria.

Return a list of OsProfile objects matching the specified criteria. Matching proceeds as the logical ‘and’ of all criteria. Criteria that are unset (None) are ignored.

If the optional match_fn parameter is specified, the match criteria parameters are ignored and each OsProfile is tested in turn by calling match_fn. If the matching function returns True the OsProfile will be included in the results.

If no OsProfile matches the specified criteria the empty list is returned.

OS profiles will be automatically loaded from disk if they are not already in memory.

Parameters:

• selection – A Selection object specifying the match criteria for the operation.

• match_fn – An optional match function to test profiles.

Returns:

a list of OsProfile objects.

Return type:

list

boom.osprofile.get_os_profile_by_id(os_id)

Find an OsProfile by its os_id.

Return the OsProfile object corresponding to os_id, or None if it is not found.

Return type:

OsProfile

Returns:

An OsProfile matching os_id or None if no match was found

boom.osprofile.key_from_key_name(key_name)

boom.osprofile.load_profiles()

Load OsProfile data from disk.

Load the set of profiles found at the path boom.osprofile.boom_profiles_path() into the global profile list.

This function may be called to explicitly load, or reload the set of profiles on-disk. Profiles are also loaded implicitly if an API function or method that requires access to profiles is invoked (for example, boom.bootloader.load_entries().

Returns:

None

boom.osprofile.match_os_profile(entry)

Attempt to match a BootEntry to a corresponding OsProfile.

Probe all loaded OsProfile objects with the supplied BootEntry in turn, until an OsProfile reports a match. Checking terminates on the first matching OsProfile.

Parameters:

entry – A BootEntry object with no attached OsProfile.

Returns:

The corresponding OsProfile for the supplied BootEntry or None if no match is found.

Return type:

OsProfile

boom.osprofile.match_os_profile_by_version(version)

Attempt to match a version string to an OsProfile.

Attempt to find a profile with a uname pattern that matches version. The first OsProfile with a match is returned.

Parameters:

version – A uname release version string to match.

Return type:

OsProfile

Returns:

An OsProfile matching version or None if not match was found

boom.osprofile.profiles_loaded()

Test whether profiles have been loaded from disk.

Return type:

bool

Returns:

True if profiles are loaded in memory or False otherwise

boom.osprofile.select_profile(s, osp)

Test the supplied profile against selection criteria.

Test the supplied OsProfile against the selection criteria in s and return True if it passes, or False otherwise.

Parameters:

• s – The selection criteria

• osp – The OsProfile to test

Return type:

bool

Returns:

True if osp passes selection or False otherwise.

boom.osprofile.write_profiles(force=False)

Write all OsProfile data to disk.

Write the current list of profiles to the directory located at boom.osprofile.boom_profiles_path().

Return type:

None

boom.hostprofile module

The boom.hostprofile module defines the HostProfile class that represents a host system profile. A HostProfile defines the identity of a host and includes template values that override the corresponding OsProfile defaults for the respective host.

Functions are provided to read and write host system profiles from an on-disk store, and to retrieve HostProfile instances using various selection criteria.

The HostProfile class includes named properties for each profile attribute (“profile key”). In addition, the class serves as a container type, allowing attributes to be accessed via dictionary-style indexing. This simplifies iteration over a profile’s key / value pairs and allows straightforward access to all members in scripts and the Python shell.

The keys used to access HostProfile members (and their corresponding property names) are identical to those used by the OsProfile class.

boom.hostprofile.BOOM_HOST_ADD_OPTS = 'BOOM_HOST_ADD_OPTS'

Constant for the Boom host add options key.

boom.hostprofile.BOOM_HOST_DEL_OPTS = 'BOOM_HOST_DEL_OPTS'

Constant for the Boom host del options key.

boom.hostprofile.BOOM_HOST_ID = 'BOOM_HOST_ID'

Constant for the Boom host identifier profile key.

boom.hostprofile.BOOM_HOST_LABEL = 'BOOM_HOST_LABEL'

Constant for the Boom host label key.

boom.hostprofile.BOOM_HOST_NAME = 'BOOM_HOST_NAME'

Constant for the Boom host name profile key.

boom.hostprofile.HOST_OPTIONAL_KEYS = ['BOOM_HOST_LABEL', 'BOOM_HOST_ADD_OPTS', 'BOOM_HOST_DEL_OPTS', 'BOOM_OS_NAME', 'BOOM_OS_SHORT_NAME', 'BOOM_OS_VERSION', 'BOOM_OS_VERSION_ID', 'BOOM_OS_UNAME_PATTERN', 'BOOM_OS_KERNEL_PATTERN', 'BOOM_OS_INITRAMFS_PATTERN', 'BOOM_OS_ROOT_OPTS_LVM2', 'BOOM_OS_ROOT_OPTS_BTRFS', 'BOOM_OS_OPTIONS']

Boom optional host profile configuration keys.

boom.hostprofile.HOST_PROFILE_KEYS = ['BOOM_HOST_ID', 'BOOM_HOST_NAME', 'BOOM_ENTRY_MACHINE_ID', 'BOOM_OS_ID', 'BOOM_HOST_LABEL', 'BOOM_HOST_ADD_OPTS', 'BOOM_HOST_DEL_OPTS', 'BOOM_OS_NAME', 'BOOM_OS_SHORT_NAME', 'BOOM_OS_VERSION', 'BOOM_OS_VERSION_ID', 'BOOM_OS_UNAME_PATTERN', 'BOOM_OS_KERNEL_PATTERN', 'BOOM_OS_INITRAMFS_PATTERN', 'BOOM_OS_ROOT_OPTS_LVM2', 'BOOM_OS_ROOT_OPTS_BTRFS', 'BOOM_OS_OPTIONS']

Ordered list of possible host profile keys, partitioned into mandatory keys, optional host profile keys, keys mapping to embedded OsProfile identity data, and OsProfile pattern keys that may be overridden in the HostProfile.

boom.hostprofile.HOST_REQUIRED_KEYS = ['BOOM_HOST_ID', 'BOOM_HOST_NAME', 'BOOM_ENTRY_MACHINE_ID', 'BOOM_OS_ID']

Boom host profile keys that must exist in a valid profile.

class boom.hostprofile.HostProfile(machine_id=None, host_name=None, label=None, os_id=None, kernel_pattern=None, initramfs_pattern=None, root_opts_lvm2=None, root_opts_btrfs=None, add_opts='', del_opts='', options=None, profile_file=None, profile_data=None)

Bases: BoomProfile

Class HostProfile implements Boom host system profiles.

Objects of type HostProfile define a host identiry, and optional fields or BootParams modifications to be applied to the specified host.

Host profiles may modify any non-identity OsProfile key, either adding to or replacing the value defined by an embedded OsProfile instance.

__annotate_func__ = None

__annotations_cache__ = {}

__firstlineno__ = 413

__init__(machine_id=None, host_name=None, label=None, os_id=None, kernel_pattern=None, initramfs_pattern=None, root_opts_lvm2=None, root_opts_btrfs=None, add_opts='', del_opts='', options=None, profile_file=None, profile_data=None)

Initialise a new HostProfile object.

If neither profile_file nor profile_data is given, all of machine_id, name, and os_id must be given.

These values form the host profile identity and are used to generate the profile unique identifier.

Parameters:

• host_name – The hostname of this system

• os_id – An OS identifier specifying the OsProfile to use with this host profile.

• profile_data – An optional dictionary mapping from BOOM_* keys to profile values.

• profile_file – An optional path to a file from which profile data should be loaded. The file should be in Boom host profile format, with BOOM_* key=value pairs.

Returns:

A new HostProfile object.

Return type:

class HostProfile

__repr__()

Format this HostProfile as a machine readable string.

Return a machine-readable representation of this HostProfile object. The string is formatted as a call to the HostProfile constructor, with values passed as a dictionary to the profile_data keyword argument.

Returns:

a string representation of this HostProfile.

Return type:

string

__set_os_profile()

Set this HostProfile’s osp member to the corresponding profile for the set os_id.

__setitem__(key, value)

Set the specified HostProfile key to the given value.

Parameters:

• key – the HostProfile key to be set.

• value – the value to set for the specified key.

__static_attributes__ = ('_osp', '_profile_data', 'osp')

__str__()

Format this HostProfile as a human readable string.

Profile attributes are printed as “Name: value, “ pairs, with like attributes grouped together onto lines.

Returns:

A human readable string representation of this HostProfile.

Return type:

string

_append_profile()

Append a HostProfile to the global profile list

_comments = None

Comment descriptors read from on-disk store

_from_data(host_data, dirty=True)

Initialise a HostProfile from in-memory data.

Initialise a new HostProfile object using the profile data in the host_data dictionary.

This method should not be called directly: to build a new Hostprofile` object from in-memory data, use the class initialiser with the host_data argument.

Returns:

None

_generate_id()

Generate a new host identifier.

Generate a new sha1 profile identifier for this profile, using the name, machine_id, and os_id and store it in _profile_data.

Returns:

None

_have_key(key)

Test for presence of a Host or Os profile key.

_identity_key = 'BOOM_HOST_ID'

The identity key for this profile class

_key_data(key)

_osp = None

_profile_data = None

Profile data dictionary

_profile_keys = ['BOOM_HOST_ID', 'BOOM_HOST_NAME', 'BOOM_ENTRY_MACHINE_ID', 'BOOM_OS_ID', 'BOOM_HOST_LABEL', 'BOOM_HOST_ADD_OPTS', 'BOOM_HOST_DEL_OPTS', 'BOOM_OS_NAME', 'BOOM_OS_SHORT_NAME', 'BOOM_OS_VERSION', 'BOOM_OS_VERSION_ID', 'BOOM_OS_UNAME_PATTERN', 'BOOM_OS_KERNEL_PATTERN', 'BOOM_OS_INITRAMFS_PATTERN', 'BOOM_OS_ROOT_OPTS_LVM2', 'BOOM_OS_ROOT_OPTS_BTRFS', 'BOOM_OS_OPTIONS']

Key set for this profile class

_profile_path()

Return the path to this profile’s on-disk data.

Return the full path to this HostProfile in the Boom profiles directory (or the location to which it will be written, if it has not yet been written).

Return type:

str

Returns:

The absolute path for this HostProfile’s file

_required_keys = ['BOOM_HOST_ID', 'BOOM_HOST_NAME', 'BOOM_ENTRY_MACHINE_ID', 'BOOM_OS_ID']

Mandatory keys for this profile class

_unwritten = False

Dirty flag

property add_opts

property del_opts

delete_profile()

Delete on-disk data for this profile.

Remove the on-disk profile corresponding to this HostProfile object. This will permanently erase the current file (although the current data may be re-written at any time by calling write_profile() before the object is disposed of).

Return type:

NoneType

Raises:

OsError if an error occurs removing the file or ValueError if the profile does not exist.

property disp_host_id

The display host_id of this profile

Return the shortest prefix of this HostProfile’s os_id that is unique within the current set of loaded profiles.

Getter:

return this HostProfile’s display host_id.

Type:

str

property disp_machine_id

The machine_id of this host profile. Return the shortest prefix of this HostProfile’s os_id that is unique within the current set of loaded profiles.

Getter:

return this HostProfile’s display host_id.

Type:

str

property disp_os_id

The display os_id of this profile.

Return the shortest prefix of this OsProfile’s os_id that is unique within the current set of loaded profiles.

Getter:

return this OsProfile’s os_id.

Type:

str

property host_id

property host_name

The host_name of this profile.

Normally set to the hostname of the system corresponding to this HostProfile.

Getter:

returns the host_name as a string.

Type:

string

property initramfs_pattern

The current initramfs_pattern setting of this profile.

Getter:

returns the initramfs_pattern as a string.

Setter:

store a new initramfs_pattern setting.

Type:

string

property kernel_pattern

The current kernel_pattern setting of this profile.

Getter:

returns the kernel_pattern as a string.

Setter:

stores a new kernel_pattern setting.

Type:

string

property label

property machine_id

The machine_id of this host profile. Return the shortest prefix of this HostProfile’s os_id that is unique within the current set of loaded profiles.

Getter:

return this HostProfile’s display host_id.

Setter:

change this HostProfile’s machine_id. This will change the host_id.

Type:

str

property optional_keys

The set of optional BLS keys allowed by this profile.

Getter:

returns a string containing optional BLS key names.

Setter:

store a new set of optional BLS keys.

Type:

string

property options

The current kernel command line options setting for this profile.

Getter:

returns the options value as a string.

Setter:

store a new options value.

Type:

string

property os_id

The os_id of this profile.

Getter:

returns the os_id as a string.

Type:

string

property os_name

The os_name of this profile.

Getter:

returns the os_name as a string.

Type:

string

property os_short_name

The os_short_name of this profile.

Getter:

returns the os_short_name as a string.

Type:

string

property os_version

The os_version of this profile.

Getter:

returns the os_version as a string.

Type:

string

property os_version_id

The os_version_id of this profile.

Getter:

returns the os_version_id as a string.

Type:

string

property osp

The OsProfile used by this HostProfile.

Getter:

returns the OsProfile object used by this HostProfile.

Setter:

stores a new OsProfile for use by this HostProfile and updates the stored os_id value in the host profile.

property root_opts_btrfs

The current BTRFS root options setting of this profile.

Getter:

returns the root_opts_btrfs value as a string.

Setter:

store a new root_opts_btrfs value.

Type:

string

property root_opts_lvm2

The current LVM2 root options setting of this profile.

Getter:

returns the root_opts_lvm2 value as a string.

Setter:

store a new root_opts_lvm2 value.

Type:

string

property short_name

The short_name of this profile.

If HostProfile.host_name appears to contain a DNS-style name, return only the host portion.

Getter:

returns the short_name as a string.

Type:

string

property title

The current title template for this profile.

Getter:

returns the title value as a string.

Setter:

store a new title value.

Type:

string

property uname_pattern

The current uname_pattern setting of this profile.

Getter:

returns the uname_pattern as a string.

Setter:

stores a new uname_pattern setting.

Type:

string

write_profile(force=False)

Write out profile data to disk.

Write out this HostProfile’s data to a file in Boom format to the paths specified by the current configuration.

Currently the machine_id and name keys are used to construct the file name.

If the value of force is False and the HostProfile is not currently marked as dirty (either new, or modified since the last load operation) the write will be skipped.

Parameters:

force – Force this profile to be written to disk even if the entry is unmodified.

Raises:

OsError if the temporary entry file cannot be renamed, or if setting file permissions on the new entry file fails.

boom.hostprofile.boom_host_profiles_path()

Return the path to the boom host profiles directory.

Returns:

The boom host profiles path.

Return type:

str

boom.hostprofile.drop_host_profiles()

Drop all in-memory host profiles.

boom.hostprofile.find_host_profiles(selection=None, match_fn=<function select_host_profile>)

Find host profiles matching selection criteria.

Return a list of HostProfile objects matching the specified criteria. Matching proceeds as the logical ‘and’ of all criteria. Criteria that are unset (None) are ignored.

If the optional match_fn parameter is specified, the match criteria parameters are ignored and each HostProfile is tested in turn by calling match_fn. If the matching function returns True the HostProfile will be included in the results.

If no HostProfile matches the specified criteria the empty list is returned.

Host profiles will be automatically loaded from disk if they are not already in memory.

Parameters:

• selection – A Selection object specifying the match criteria for the operation.

• match_fn – An optional match function to test profiles.

Returns:

a list of HostProfile objects.

Return type:

list

boom.hostprofile.get_host_profile_by_id(machine_id, label='')

Find a HostProfile by its machine_id.

Return the HostProfile object corresponding to machine_id, or None if it is not found.

Return type:

HostProfile

Returns:

An HostProfile matching machine_id or None if no match was found.

boom.hostprofile.host_profiles_loaded()

Test whether profiles have been loaded from disk.

Return type:

bool

Returns:

True if profiles are loaded in memory or False otherwise

boom.hostprofile.load_host_profiles()

Load HostProfile data from disk.

Load the set of host profiles found at the path boom.hostprofile.boom_profiles_path() into the global host profile list.

This function may be called to explicitly load, or reload the set of profiles on-disk. Profiles are also loaded implicitly if an API function or method that requires access to profiles is invoked (for example, boom.bootloader.load_entries().

Returns:

None

boom.hostprofile.match_host_profile(entry)

Attempt to match a BootEntry to a corresponding HostProfile.

Attempt to find a loaded HostProfile object with the a machine_id that matches the supplied BootEntry. Checking terminates on the first matching HostProfile.

Parameters:

entry – A BootEntry object with no attached HostProfile.

Returns:

The corresponding HostProfile for the supplied BootEntry or None if no match is found.

Return type:

BootEntry or NoneType.

boom.hostprofile.select_host_profile(s, hp)

Test the supplied host profile against selection criteria.

Test the supplied HostProfile against the selection criteria in s and return True if it passes, or False otherwise.

Parameters:

• s – The selection criteria

• hp – The HostProfile to test

Return type:

bool

Returns:

True if hp passes selection or False otherwise.

boom.hostprofile.write_host_profiles(force=False)

Write all HostProfile data to disk.

Write the current list of host profiles to the directory located at boom.osprofile.boom_profiles_path().

Return type:

None

boom.command module

The boom.command module provides both the Boom command line interface infrastructure, and a simple procedural interface to the boom library modules.

The procedural interface is used by the boom command line tool, and may be used by application programs, or interactively in the Python shell by users who do not require all the features present in the Boom object API.

In addition the module contains definitions for Report object types and fields that may be of use in implementing custom reports using the boom.report module.

boom.command.I_NONE = None

Use original image (no caching)

boom.command.clone_entry(selection=None, title=None, version=None, machine_id=None, root_device=None, lvm_root_lv=None, btrfs_subvol_path=None, btrfs_subvol_id=None, profile=None, architecture=None, add_opts=None, del_opts=None, write=True, expand=False, allow_no_dev=False, images=None, no_fstab=False, mounts=None, swaps=None)

Clone an existing boot loader entry.

Create the specified boot entry in the configured loader directory by cloning all un-set parameters from the boot entry selected by the selection argument.

An error is raised if a matching entry already exists.

Parameters:

• selection – criteria matching the entry to clone.

• title – the title of the new entry.

• version – the version string for the new entry.

• machine_id – the machine id for the new entry.

• root_device – the root device path for the new entry.

• lvm_root_lv – an optional LVM2 root logical volume.

• btrfs_subvol_path – an optional BTRFS subvolume path.

• btrfs_subvol_id – an optional BTRFS subvolume id.

• profile – A profile to use for this entry.

• architecture – An optional BLS architecture string.

• add_opts – A list of additional kernel options to append.

• del_opts – A list of template-supplied options to drop.

• write – True if the entry should be written to disk, or False otherwise.

• expand – Expand bootloader environment variables.

• allow_no_dev – Allow the block device to not exist.

• images – Whether to cache or backup boot images in the new entry.

• no_fstab – Disable parsing of the fstab for the new entry.

• mounts – A list of colon separated command-line mount specifications for the new entry.

Returns:

a BootEntry object corresponding to the new entry.

Return type:

BootEntry

Raises:

ValueError if either required values are missing or a duplicate entry exists, or OsError if an error occurs while writing the entry file.

boom.command.clone_host(selection=None, machine_id=None, host_name=None, label=None, os_id=None, kernel_pattern=None, initramfs_pattern=None, root_opts_lvm2=None, root_opts_btrfs=None, add_opts=None, del_opts=None, options=None)

Clone an existing host profile.

Create the specified profile in the configured profile directory by cloning all un-set parameters from the profile selected by the selection argument.

An error is raised if a matching profile already exists, or if the selection criteria match more than one profile.

Parameters:

• selection – criteria matching the profile to clone.

• machine_id – the machine_id of the new host profile.

• host_name – the hostname of the new host profile.

• label – an optional host label.

• os_id – the operating system identifier for the host.

• kernel_pattern – The kernel pattern for the host.

• initramfs_pattern – The initramfs pattern for the host.

• root_opts_lvm2 – LVM2 root options template.

• root_opts_btrfs – BTRFS root options template.

• add_opts – Additional boot options for this profile.

• del_opts – Boot options to delete for this profile.

• options – Kernel options template.

Returns:

a new HostProfile object.

Return type:

HostProfile

Raises:

ValueError if either required values are missing or a duplicate profile exists, or OsError if an error occurs while writing the profile file.

boom.command.clone_profile(selection=None, name=None, short_name=None, version=None, version_id=None, uname_pattern=None, kernel_pattern=None, initramfs_pattern=None, root_opts_lvm2=None, root_opts_btrfs=None, options=None)

Clone an existing operating system profile.

Create the specified profile in the configured profile directory by cloning all un-set parameters from the profile selected by the selection argument.

An error is raised if a matching profile already exists, or if the selection criteria match more than one profile.

Parameters:

• selection – criteria matching the profile to clone.

• name – the name of the new profile.

• short_name – the short name of the new profile.

• version – the version string for the new profile.

• version_id – the version ID string for the new profile.

• uname_pattern – a uname pattern to match this profile.

• kernel_pattern – a kernel pattern to match this profile.

• initramfs_pattern – a initramfs pattern to match this profile.

• root_opts_lvm2 – LVM2 root options template.

• root_opts_btrfs – BTRFS root options template.

• options – Kernel options template.

Returns:

a new OsProfile object.

Return type:

OsProfile

Raises:

ValueError if either required values are missing or a duplicate profile exists, or OsError if an error occurs while writing the profile file.

boom.command.create_entry(title, version, machine_id, root_device, lvm_root_lv=None, btrfs_subvol_path=None, btrfs_subvol_id=None, profile=None, add_opts=None, del_opts=None, write=True, architecture=None, expand=False, allow_no_dev=False, images=None, update=False, no_fstab=False, mounts=None, swaps=None)

Create new boot loader entry.

Create the specified boot entry in the configured loader directory. An error is raised if a matching entry already exists.

Parameters:

• title – the title of the new entry.

• version – the version string for the new entry.

• machine_id – the machine id for the new entry.

• root_device – the root device path for the new entry.

• lvm_root_lv – an optional LVM2 root logical volume.

• btrfs_subvol_path – an optional BTRFS subvolume path.

• btrfs_subvol_id – an optional BTRFS subvolume id.

• profile – A profile to use for this entry.

• add_opts – A list of additional kernel options to append.

• del_opts – A list of template-supplied options to drop.

• write – True if the entry should be written to disk, or False otherwise.

• architecture – An optional BLS architecture string.

• expand – Expand bootloader environment variables.

• allow_no_dev – Accept a non-existent or invalid root dev.

• images – Whether to cache or backup boot images in the new entry.

• update – Whether to update or re-use an existing cached boot image.

• no_fstab – Disable parsing of the fstab for the new entry.

• mounts – A list of colon separated command-line mount specifications for the new entry.

• swaps – A list of colon separated command-line swap specifications for the new entry.

Returns:

a BootEntry object corresponding to the new entry.

Return type:

BootEntry

Raises:

ValueError if either required values are missing or a duplicate entry exists, or OsError if an error occurs while writing the entry file.

boom.command.create_host(machine_id=None, host_name=None, os_id=None, label=None, kernel_pattern=None, initramfs_pattern=None, root_opts_lvm2=None, root_opts_btrfs=None, options=None, add_opts=None, del_opts=None, host_data=None)

Create new host profile.

Create the specified HostProfile in the configured profiles directory.

HostProfile key values may be specified either by passing individual keyword arguments, or by passing a dictionary of HostProfile key name to value pairs as the host_data argument. If a key is present as both a keyword argument and in the host_data dictionary, the argument will take precedence.

An error is raised if a matching profile already exists.

Parameters:

• machine_id – The machine_id of the host

• host_name – The full name of the new HostProfile

• label – An optional host label

• os_id – The os_id for the new host

• kernel_pattern – Pattern to generate kernel paths

• initramfs_pattern – Pattern to generate initramfs paths

• root_opts_lvm2 – Template options for LVM2 entries

• root_opts_btrfs – Template options for BTRFS entries

• options – Template kernel command line options

• add_opts – Additional boot options for this profile

• del_opts – Boot options to delete for this profile

• host_data – Dictionary of profile key:value pairs

Returns:

a HostProfile object for the new profile

Return type:

HostProfile

Raises:

ValueError if either required values are missing or a duplicate profile exists, or OsError if an error occurs while writing the profile file.

boom.command.create_profile(name, short_name, version, version_id, uname_pattern=None, kernel_pattern=None, initramfs_pattern=None, root_opts_lvm2=None, root_opts_btrfs=None, options=None, optional_keys=None, profile_data=None, profile_file=None)

Create new operating system profile.

Create the specified OsProfile in the configured profiles directory.

OsProfile key values may be specified either by passing individual keyword arguments, or by passing a dictionary of OsProfile key name to value pairs as the profile_data argument. If a key is present as both a keyword argument and in the profile_data dictionary, the argument will take precedence.

An error is raised if a matching profile already exists.

Parameters:

• name – The name of the new OsProfile

• short_name – The short name of the new OsProfile

• version – The version string of the new OsProfile

• version_id – The version ID string of the new OsProfile

• uname_pattern – A uname pattern to match for this profile

• kernel_pattern – Pattern to generate kernel paths

• initramfs_pattern – Pattern to generate initramfs paths

• root_opts_lvm2 – Template options for LVM2 entries

• root_opts_btrfs – Template options for BTRFS entries

• options – Template kernel command line options

• profile_data – Dictionary of profile key:value pairs

• profile_file – File to be used for profile

Returns:

an OsProfile object for the new profile

Return type:

OsProfile

Raises:

ValueError if either required values are missing or a duplicate profile exists, or OsError if an error occurs while writing the profile file.

boom.command.delete_entries(selection=None)

Delete entries matching selection criteria.

Delete the specified boot entry or entries from the configured loader directory. If boot_id is used, or if the criteria specified match exactly one entry, a single entry is removed. If boot_id is not used, and more than one matching entry is present, all matching entries will be removed.

Selection criteria may also be expressed via a Selection object passed to the call using the selection parameter.

On success the number of entries removed is returned.

Parameters:

selection – A Selection object giving selection criteria for the operation.

Returns:

the number of entries removed.

Return type:

int

boom.command.delete_hosts(selection=None)

Delete host profiles matching selection criteria.

Delete the specified HostProfile or profiles from the configured profile directory. If os_id is used, or if the criteria specified match exactly one profile, a single entry is removed. If host_id is not used, and more than one matching profile is present, all matching profiles will be removed.

Selection criteria are expressed via a Selection object passed to the call using the selection parameter.

On success the number of profiles removed is returned.

Parameters:

selection – A Selection object giving selection criteria for the operation.

Returns:

the number of entries removed.

Return type:

int

boom.command.delete_profiles(selection=None)

Delete profiles matching selection criteria.

Delete the specified OsProfile or profiles from the configured profile directory. If os_id is used, or if the criteria specified match exactly one profile, a single entry is removed. If os_id is not used, and more than one matching profile is present, all matching profiles will be removed.

Selection criteria are expressed via a Selection object passed to the call using the selection parameter.

On success the number of profiles removed is returned.

Parameters:

selection – A Selection object giving selection criteria for the operation.

Returns:

the number of entries removed.

Return type:

int

boom.command.edit_entry(selection=None, title=None, version=None, machine_id=None, root_device=None, lvm_root_lv=None, btrfs_subvol_path=None, btrfs_subvol_id=None, profile=None, architecture=None, add_opts=None, del_opts=None, expand=False, images=None)

Edit an existing boot loader entry.

Modify an existing BootEntry by changing one or more of the entry values or boot parameters.

The modified BootEntry is written to disk and returned on success.

Modifying a BootEntry causes the entry’s boot_id to change, since the ID is based on the values of all configured boot keys.

Parameters:

• selection – A Selection specifying the boot_id to edit

• title – The new entry title

• version – The new entry version

• machine_id – The new machine_id

• root_device – The new root device

• lvm_root_lv – The new LVM root LV

• btrfs_subvol_path – The new BTRFS subvolume path

• btrfs_subvol_id – The new BTRFS subvolme ID

• profile – The host or OS profile for the edited entry

• architecture – An optional BLS architecture string.

• add_opts – A list of additional kernel options to append.

• del_opts – A list of template-supplied options to drop.

• expand – Expand bootloader environment variables.

Returns:

The modified BootEntry

Return type:

BootEntry

boom.command.edit_host(selection=None, machine_id=None, os_id=None, host_name=None, label=None, kernel_pattern=None, initramfs_pattern=None, root_opts_lvm2=None, root_opts_btrfs=None, add_opts=None, del_opts=None, options=None)

Edit an existing host profile.

Modify an existing HostProfile by changing one or more of the profile values.

The modified HostProfile is written to disk and returned on success.

Parameters:

• selection – A Selection specifying the boot_id to edit

• machine_id – The machine id for the edited host profile

• os_id – The OS id for the edited host profile

• host_name – The host name for the edited host profile

• label – an optional host label

• kernel_pattern – The new kernel pattern

• initramfs_pattern – The new initramfs pattern

• root_opts_lvm2 – The new LVM2 root options

• root_opts_btrfs – The new BTRFS root options

• add_opts – Additional boot options for this profile.

• del_opts – Boot options to delete for this profile.

• options – The new kernel options template

Returns:

The modified HostProfile

Return type:

HostProfile

boom.command.edit_profile(selection=None, uname_pattern=None, kernel_pattern=None, initramfs_pattern=None, root_opts_lvm2=None, root_opts_btrfs=None, options=None, optional_keys=None)

Edit an existing operating system profile.

Modify an existing OsProfile by changing one or more of the profile values.

The modified OsProfile is written to disk and returned on success.

Parameters:

• selection – A Selection specifying the boot_id to edit

• uname_pattern – The new uname pattern

• kernel_pattern – The new kernel pattern

• initramfs_pattern – The new initramfs pattern

• root_opts_lvm2 – The new LVM2 root options

• root_opts_btrfs – The new BTRFS root options

• options – The new kernel options template

Returns:

The modified OsProfile

Return type:

OsProfile

boom.command.list_entries(selection=None)

List entries matching selection criteria.

Return a list of boom.bootloader.BootEntry objects matching the given criteria.

Selection criteria may be expressed via a Selection object passed to the call using the selection parameter.

Parameters:

selection – A Selection object giving selection criteria for the operation.

Returns:

A list of matching BootEntry objects.

Return type:

list

boom.command.list_hosts(selection=None)

List host profiles matching selection criteria.

Return a list of boom.hostprofile.HostProfile objects matching the given criteria.

Selection criteria may be expressed via a Selection object passed to the call using the selection parameter.

Parameters:

selection – A Selection object giving selection criteria for the operation.

Returns:

a list of HostProfile objects.

Return type:

list

boom.command.list_profiles(selection=None)

List operating system profiles matching selection criteria.

Return a list of boom.osprofile.OsProfile objects matching the given criteria.

Selection criteria may be expressed via a Selection object passed to the call using the selection parameter.

Parameters:

selection – A Selection object giving selection criteria for the operation.

Returns:

a list of OsProfile objects.

Return type:

list

boom.command.os_options_from_cmdline()

Generate an os-options template from the running system.

boom.command.print_cache(selection=None, opts=None, output_fields=None, sort_keys=None, expand=False)

Print cache entries matching selection criteria.

Selection criteria may be expressed via a Selection object passed to the call using the Selection parameter.

Parameters:

• selection – A Selection object giving selection criteria for the operation

• output_fields – a comma-separated list of output fields

• opts – output formatting and control options

• sort_keys – a comma-separated list of sort keys

• expand – unused

Returns:

the number of matching profiles output

Return type:

int

boom.command.print_cache_images(selection=None, opts=None, output_fields=None, sort_keys=None, expand=False)

Print cache entries and images matching selection criteria.

Selection criteria may be expressed via a Selection object passed to the call using the Selection parameter.

Parameters:

• selection – A Selection object giving selection criteria for the operation

• output_fields – a comma-separated list of output fields

• opts – output formatting and control options

• sort_keys – a comma-separated list of sort keys

• expand – unused

Returns:

the number of matching profiles output

Return type:

int

boom.command.print_entries(selection=None, output_fields=None, opts=None, sort_keys=None, expand=None)

Print boot loader entries matching selection criteria.

Format a set of boom.bootloader.BootEntry objects matching the given criteria, and output them as a report to the file given in out_file, or sys.stdout if out_file is unset.

Selection criteria may be expressed via a Selection object passed to the call using the selection parameter.

Parameters:

• selection – A Selection object giving selection criteria for the operation

• output_fields – a comma-separated list of output fields

• opts – output formatting and control options

• sort_keys – a comma-separated list of sort keys

• expand – Expand bootloader environment variables

Returns:

the boot_id of the new entry

Return type:

str

boom.command.print_hosts(selection=None, opts=None, output_fields=None, sort_keys=None, expand=False)

Print host profiles matching selection criteria.

Selection criteria may be expressed via a Selection object passed to the call using the selection parameter.

Parameters:

• selection – A Selection object giving selection criteria for the operation

• output_fields – a comma-separated list of output fields

• opts – output formatting and control options

• sort_keys – a comma-separated list of sort keys

• expand – unused

Returns:

the number of matching profiles output

Return type:

int

boom.command.print_profiles(selection=None, opts=None, output_fields=None, sort_keys=None, expand=False)

Print operating system profiles matching selection criteria.

Selection criteria may be expressed via a Selection object passed to the call using the selection parameter.

Parameters:

• selection – A Selection object giving selection criteria for the operation

• output_fields – a comma-separated list of output fields

• opts – output formatting and control options

• sort_keys – a comma-separated list of sort keys

• expand – unused

Returns:

the number of matching profiles output.

Return type:

int

boom.cache module

The boom.cache module defines classes, constants and functions for maintaining an on-disk cache of kernel, initramfs and auxiliary images required to load boom-defined boot entries.

boom.cache.CACHE_BROKEN = 'BROKEN'

Path is cached but image missing or damaged

boom.cache.CACHE_CACHED = 'CACHED'

Path is cached

boom.cache.CACHE_MISSING = 'MISSING'

Path is cached and missing from /boot

boom.cache.CACHE_RESTORED = 'RESTORED'

Path is cached and has been restored to /boot

boom.cache.backup_path(img_path, update=False)

Back up an image to the boom boot image cache.

Parameters:

• img_path – The path to the on-disk boot image relative to the configured /boot directory.

• backup_path – The path where the backup image will be created.

Returns:

None

boom.cache.cache_path(img_path, update=False)

Add an image to the boom boot image cache.

Parameters:

img_path – The path to the on-disk boot image relative to the configured /boot directory.

Returns:

None

boom.cache.clean_cache()

Remove unused cache entries.

Iterate over the set of cache entries and remove any paths that are not referenced by any BootEntry, and remove all images that are not referenced by a path.

boom.cache.drop_cache()

Discard the in-memory cache state. Calling this function has no effect on the persistent cache state but will free all in-memory representations and clear the cache index.

boom.cache.find_cache_images(selection=None)

Find cache entries matching selection criteria.

Return a list of CacheEntry objects matching the supplied selection criteria, one for each image that exists in the cache. Each CacheEntry object is returned with a list containing a single image.

;param selection: cache entry selection criteria. :returns: A list of matching CacheEntry objects.

boom.cache.find_cache_paths(selection=None)

Find cache entries matching selection criteria.

Return a list of CacheEntry objects matching the supplied selection criteria, one for each path that exists in the cache. For each cached path a CacheEntry object is returned with a list of images that are cached for that path. The image list is sorted by timestamp with the most recent entry first.

;param selection: cache entry selection criteria. :returns: A list of matching CacheEntry objects.

boom.cache.load_cache(verify=True, digests=False)

Read the state of the on-disk boot image cache into memory.

boom.cache.uncache_path(img_path, force=False)

Remove paths from the boot image cache.

Remove img_path from the boot image cache and discard any unused images referenced by the cache entry. Images that are shared with other cached paths are not removed.

Parameters:

img_path – The cached path to remove

boom.cache.write_cache()

Write the current in-memory state of the cache to disk.

boom.report module

The boom reporting module contains a set of classes for creating simple text based tabular reports for a user-defined set of object types and fields. No restrictions are placed on the types of object that can be reported: users of the Report classes may define additional object types outside the boom package and include these types in reports generated by the module.

The fields displayed in a specific report may be selected from the available set of fields by specifying a simple comma-separated string list of field names (in display order). In addition, custom multi-column sorting is possible using a similar string notation.

The Report module is closely based on the device-mapper reporting engine and shares many features and behaviours with device mapper reports.

class boom.report.Field

Bases: object

A Field represents an instance of a FieldType including its associated data values.

__annotate_func__ = None

__annotations_cache__ = {}

__firstlineno__ = 300

__init__(report, props)

Initialise a new Field object.

Initialise a Field object and configure the supplied report and props attributes.

Parameters:

• report – The Report that owns this field

• props – The FieldProperties object for this field

__static_attributes__ = ('props', 'report', 'report_string', 'sort_value')

report_num(value)

Report a numeric value for this Field object.

Set the value for this field to the supplied value.

Parameters:

value – The numeric value to set

Return type:

None

report_sha(value)

Report a SHA value for this Field object.

Set the value for this field to the supplied value.

Parameters:

value – The SHA value to set

Return type:

None

report_size(value)

Report a size value for this Field object.

Set the value for this field to the supplied value, converted to a human readable string.

Parameters:

value – The size value to set in bytes.

Return type:

None

report_str(value)

Report a string value for this Field object.

Set the value for this field to the supplied value.

Parameters:

value – The string value to set

Return type:

None

report_str_list(value)

Report a string list value for this Field object.

Set the value for this field to the strings contained in value.

Parameters:

value – A list of strings

Return type:

None

report_time(value)

Report a time value for this Field object.

Set the value for this field to the supplied value.

Parameters:

value – The time value to set

Return type:

None

report_uuid(value)

Report a uuid value for this Field object.

Set the value for this field to the supplied value.

Parameters:

value – The uuid value to set

Return type:

None

set_value(report_string, sort_value=None)

Report an arbitrary value for this Field object.

Set the value for this field to the supplied value, and set the field’s sort_value to the supplied sort_value.

Parameters:

• report_string – The string value to set

• sort_value – The sort value

Return type:

None

class boom.report.FieldProperties(field_num=None, initial_width=0, width=0, objtype=None, dtype=None, align=None, hidden=False, implicit=False, sort_key=False, sort_dir=None, compact_one=False, compacted=False, sort_posn=None)

Bases: object

Properties of a field instance.

__annotate_func__ = None

__annotations_cache__ = {}

__firstlineno__ = 261

__init__(field_num=None, initial_width=0, width=0, objtype=None, dtype=None, align=None, hidden=False, implicit=False, sort_key=False, sort_dir=None, compact_one=False, compacted=False, sort_posn=None)

__static_attributes__ = ('align', 'compact_one', 'compacted', 'dtype', 'field_num', 'hidden', 'implicit', 'initial_width', 'objtype', 'sort_dir', 'sort_key', 'sort_posn', 'width')

class boom.report.FieldType

Bases: object

The FieldType class describes the properties of a field available in a Report instance.

__annotate_func__ = None

__annotations_cache__ = {}

__firstlineno__ = 204

__init__(objtype, name, head, desc, width, dtype, report_fn, align=None)

Initialise new FieldType object.

Initialise a new FieldType object with the specified properties.

Parameters:

• objtype – The numeric object type ID (power of two)

• name – The field name used to select display fields

• desc – A human-readable description of the field

• width – The default (initial) field width

• dtype – The Report data type of the field

• report_fn – The field reporting function

• align – The field alignment value

Returns:

A new ReportFieldType object

Return type:

ReportFieldType

__static_attributes__ = ('align', 'desc', 'dtype', 'head', 'name', 'objtype', 'report_fn', 'width')

class boom.report.Report

Bases: object

A class representing a configurable text report with multiple caller-defined fields. An optional title may be provided and the fields argument must contain a list of Field objects describing the required report.

__add_field(field_num, implicit)

Add a field to this Report.

Add the specified FieldType to this Report and configure FieldProperties for it.

Parameters:

• field_num – The number of this field (fields order)

• implicit – True if this field is implicit, else False

__add_sort_key(field_num, sort, implicit, type_only)

Add a new sort key to this Report

Add the sort key identified by field_num to this list of sort keys for this Report.

Parameters:

• field_num – The field number of the key to add

• sort – The sort direction for this key

• implicit – True if field_num is implicit, else False

• type_only – True if this call should only update types

__annotate_func__ = None

__annotations_cache__ = {}

__copy_field(field_num, implicit)

Copy field definition to FieldProperties

Copy values from a FieldType to FieldProperties.

Parameters:

• field_num – The number of this field (fields order)

• implicit – True if this field is implicit, else False

__display_fields(display_field_types)

Display report fields help message.

Display a list of valid fields for this Report.

Parameters:

• fields – The list of fields to display

• display_field_types – A boolean controlling whether field types (str, SHA, num) are included in help output

__field_match(field_name, type_only)

Attempt to match a field and optionally update report type.

Look up the named field and, if type_only is True, update this Report’s report_types mask to include the field’s type identifier. If type_only is False the field is also added to this Report’s field list.

Parameters:

• field_name – A string identifying the field

• type_only – True if this call should only update types

__find_type(report_type)

Resolve numeric type to corresponding ReportObjType.

Parameters:

report_type – The numeric report type to look up

Returns:

The requested ReportObjType.

Raises:

ValueError if no matching type was found.

__firstlineno__ = 510

__get_field(field_name)

Look up a field by name.

Attempt to find the field named in field_name in this Report’s tables of implicit and user-defined fields, returning a (field, implicit) tuple, where field contains the requested FieldType, and implicit is a boolean indicating whether this field is implicit or not.

Parameters:

• field_num – The number of this field (fields order)

• implicit – True if this field is implicit, else False

__get_longest_field_name_len(fields)

Find the longest field name length.

Returns:

the length of the longest configured field name

__help_requested()

Check for presence of ‘help’ fields in output selection.

Check the fields making up this Report and return True if any valid ‘help’ field synonym is present.

Returns:

True if help was requested or False otherwise

__init__(types, fields, output_fields, opts, sort_keys, title)

Initialise Report.

Initialise a new Report object with the specified fields and output control options.

Parameters:

• types – List of ReportObjType used in this report.

• fields – A list of Field field descriptions.

• output_fields – An optional list of output fields to be rendered by this report.

• opts – An instance of ReportOpts or None.

Returns:

A new report object.

Return type:

Report.

__key_match(key_name, type_only)

Attempt to match a sort key and update report type.

Look up the named sort key and, if type_only is True, update this Report’s report_types mask to include the field’s type identifier. If type_only is False the field is also added to this Report’s field list.

Parameters:

• field_name – A string identifying the sort key

• type_only – True if this call should only update types

__parse_fields(field_format, type_only)

Parse report field list.

Parse field_format and attempt to match the names of field names found to registered FieldType fields.

If type_only is True only the report_types field is updated: otherwise the parsed fields are added to the Report’s field list.

Parameters:

• field_format – The list of fields to parse

• type_only – True if this call should only update types

__parse_keys(keys, type_only)

Parse report sort key list.

Parse keys and attempt to match the names of sort keys found to registered FieldType fields.

If type_only is True only the report_types field is updated: otherwise the parsed fields are added to the Report’s sort key list.

Parameters:

• field_format – The list of fields to parse

• type_only – True if this call should only update types

__recalculate_fields()

Recalculate field widths.

For each field, recalculate the minimum field width by finding the longest report_string value for that field and updating the dynamic width stored in the corresponding FieldProperties object.

Return type:

None

__recalculate_sha_width()

Recalculate minimum SHA field widths.

For each REP_SHA field present, recalculate the minimum field width required to ensure uniqueness of the displayed values.

Return type:

None

__report_headings()

Output report headings.

Output the column headings for this Report.

Return type:

None

__row_key_fn()

Return a Python key function to compare report rows.

The cmp argument of sorting functions has been removed in Python 3.x: to maintain similarity with the device-mapper report library we keep a traditional “cmp”-style function (that is structured identically to the version in the device mapper library), and dynamically wrap it in a RowKey object to conform to the Python sort key model.

Returns:

A RowKey object wrapping _row_cmp()

Return type:

RowKey

__static_attributes__ = ('_already_reported', '_data', '_field_calc_needed', '_field_properties', '_fields', '_header_written', '_rows', '_sort_required', '_title', '_types', 'keys_count', 'opts', 'report_types')

_implicit_fields = [<boom.report.FieldType object>]

_implicit_types = [<boom.report.ReportObjType object>]

_output_as_columns()

Output this report in column format.

Output the data contained in this Report in column format, one row per line. If column headings have not been printed already they will be automatically displayed by this call.

Returns:

None

_output_as_json()

Output this report in JSON format.

Output the data contained in this Report in JSON notation. Column names are used as the keys for the JSON report. :returns: None

_output_as_rows()

Output this report in column format.

Output the data contained in this Report in column format, one row per line. If column headings have not been printed already they will be automatically displayed by this call.

Returns:

None

_output_field(field)

Output field data.

Generate string data for one field in a report row.

Field:

The field to be output

Returns:

The output report string for this field

Return type:

str

_output_field_json(field)

Output field data as a JSON dictionary element.

Field:

The field to be output

Returns:

A (key, value) tuple for this field

Return type:

Tuple

_sort_rows()

Sort the rows of this Report.

Sort this report’s rows, according to the configured sort keys.

Returns:

None

opts = None

report_object(obj)

Report data for object.

Add a row of data to this Report. The data argument should be an object of the type understood by this report’s fields. It will be passed in turn to each field to obtain data for the current row.

Parameters:

obj – the object to report on for this row.

report_output()

Output report data.

Output this report’s data to the configured report file, using the configured output controls and fields.

On success the number of rows output is returned. On error an exception is raised.

Returns:

the number of rows of output written.

Return type:

int

class boom.report.ReportObjType

Bases: object

Class representing a type of object to be reported on. Instances of ReportObjType must specify an identifier, a description, and a data function that will return the correct type of object from a compound object containing data objects of different types. For reports that use only a single object type the data_fn member may be simply lambda x: x.

__annotate_func__ = None

__annotations_cache__ = {}

__firstlineno__ = 166

__init__(objtype, desc, prefix, data_fn)

Initialise ReportObjType.

Initialise a new ReportObjType object with the specified objtype, desc, optional prefix and data_fn. The objtype must be an integer power of two that is unique within a given report. The data_fn should accept an object as its only argument and return an object of the requested type.

__static_attributes__ = ('data_fn', 'desc', 'objtype', 'prefix')

class boom.report.ReportOpts

Bases: object

Options controlling the formatting and output of a report.

__annotate_func__ = None

__annotations_cache__ = {}

__eq__(other)

Return self==value.

__firstlineno__ = 87

__hash__ = None

__init__(columns=80, headings=True, buffered=True, separator=' ', field_name_prefix='', unquoted=True, aligned=True, json=False, columns_as_rows=False, report_file=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>)

Initialise ReportOpts object.

Initialise a ReportOpts object to control output of a Report.

Parameters:

• columns – the number of columns to use for output.

• headings – a boolean indicating whether to output column headings for this report.

• buffered – a boolean indicating whether to buffer output from this report.

• report_file – a file to which output will be sent.

Returns:

a new ReportOpts object.

Return type:

<class ReportOpts>

__static_attributes__ = ('aligned', 'buffered', 'columns', 'columns_as_rows', 'field_name_prefix', 'headings', 'json', 'report_file', 'separator', 'unquoted')

__str__()

Return str(self).