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)[source]¶
Bases:
object
Class representing boom persistent configuration values.
- __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)[source]¶
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__()[source]¶
Return a string representation of this
BoomConfig
in BoomConfig initialiser 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¶
- class boom.BoomLogger[source]¶
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).
- debug_masked(msg, *args, **kwargs)[source]¶
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¶
- class boom.Selection[source]¶
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.
- __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, timestamp=None, img_id=None)[source]¶
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
timestamp – A cache entry timestamp to match
img_id – A cache image identifier to match
- Returns:
A new Selection instance
- Return type:
- __repr__()[source]¶
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
- __str__()[source]¶
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', 'timestamp', 'img_id']¶
- allow_null_profile = False¶
- boot_id = None¶
- btrfs_subvol_id = None¶
- btrfs_subvol_path = None¶
- cache_attrs = ['version', 'linux', 'initrd', '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)[source]¶
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 raiseValueError
if invalid criteria exist.- Parameters:
entry –
Selection
may include BootEntry dataparams –
Selection
may include BootParams dataprofile –
Selection
may include OsProfile datahost –
Selection
may include Host datacache –
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)[source]¶
Initialise Selection from command line arguments.
Construct a new
Selection
object from the command line arguments incmd_args
. Each set selection attribute fromcmd_args
is copied into the Selection. The resulting object may be passed to either theBootEntry
,OsProfile
, orHostProfile
search functions (find_entries
,find_profiles
, andfind_host_profiles
), as well as theboom.command
calls that accept a selection argument.- Parameters:
args – The command line selection arguments.
- Returns:
A new Selection instance
- Return type:
- 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()[source]¶
Test this Selection object for null selection criteria.
Return
True
if thisSelection
object matches all objects, orFalse
otherwise.- Returns:
True
if this Selection is null- Return type:
bool
- linux = None¶
- lvm_root_lv = None¶
- machine_id = None¶
- options = 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)[source]¶
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, andFalse
otherwise.- Return type:
bool
- boom.find_minimum_sha_prefix(shas, min_prefix)[source]¶
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()[source]¶
Return the active
BoomConfig
object.- Return type:
- Returns:
the active configuration object
- boom.get_boom_config_path()[source]¶
Return the currently configured boom configuration file path.
- Return type:
str
- Returns:
the current boom configuration file path
- boom.get_boom_path()[source]¶
Return the currently configured boom configuration path.
- Returns:
the path to the BOOT/boom directory.
- Return type:
str
- boom.get_boot_path()[source]¶
Return the currently configured boot file system path.
- Returns:
the path to the /boot file system.
- Return type:
str
- boom.get_cache_path()[source]¶
Return the currently configured boot file system path.
- Returns:
the path to the /boot file system.
- Return type:
str
- boom.get_debug_mask()[source]¶
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)[source]¶
Load profiles from disk.
Load the set of profiles found at the path
profiles_path
into the listprofiles
. 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 optionaltype
may be specified to describe the profile type in error messages. Iftype
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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
Set the active configuration to the object
config
(which may be any class that includes theBoomConfig
attributes).- Parameters:
config – a configuration object
- Returns:
None
- Raises:
TypeError if
config
does not appear to have the correct attributes.
- boom.set_boom_path(boom_path)[source]¶
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 byconfig.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)[source]¶
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 byget_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 callingset_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)[source]¶
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 directoryconfig.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.
Submodules¶
boom.bootloader module¶
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)[source]¶
Bases:
object
Class
BoomProfile
is the abstract base class for Boom template profiles. TheBoomProfile
class cannot be instantiated by itself but serves as the base class for bothOsProfile
andHostProfile
instances.- __getitem__(key)[source]¶
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 ifkey
is valid but not present.
- __init__(profile_keys, required_keys, identity_key)[source]¶
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__()[source]¶
Return the length (key count) of this profile.
- Returns:
the profile length as an integer.
- Return type:
int
- __repr__()[source]¶
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)[source]¶
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.
- __str__()[source]¶
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()[source]¶
Append a
BoomProfile
to the appropriate global profile listThis method must be overridden by classes that extend
BoomProfile
.- Returns:
None
- Raises:
NotImplementedError
- _check_optional_key(optional_key)[source]¶
Check that they optional key
key
is a valid, known BLS optional key and raiseValueError
if it is not.
- _comments = None¶
Comment descriptors read from on-disk store
- _delete_profile(profile_id)[source]¶
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 callingwrite_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 orValueError
if the profile does not exist.
- _dirty()[source]¶
Mark this
BoomProfile
as needing to be written to disk.A newly created
BoomProfile
object is always dirty and a call to itswrite_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)[source]¶
This method must be implemented by concrete profile classes.
- _from_file(profile_file)[source]¶
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 theprofile_file
argument.- Returns:
None
- _generate_id()[source]¶
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()[source]¶
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)[source]¶
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
isFalse
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)[source]¶
Add the BLS key
key
to the allowed set of optional keys for this profile.
- del_optional_key(key)[source]¶
Remove the BLS key
key
from the allowed set of optional keys for this profile.
- delete_profile()[source]¶
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 callingwrite_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 orValueError
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()[source]¶
Return the items list for this
BoomProfile
.Return a list of
(key, value)
tuples representing the key items in thisBoomProfile
.- 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()[source]¶
Return the list of keys for this
BoomProfile
.- Return type:
list
- Returns:
A list of
BoomProfile
key names
- make_format_regexes(fmt)[source]¶
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)[source]¶
Test
BoomProfile
for options template match.Test the supplied
BootEntry
to determine whether it matches the options template defined by thisBoomProfile
.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, orFalse
otherwise.- Return type:
bool
- match_uname_version(version)[source]¶
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, orFalse
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()[source]¶
Return the list of key values for this
BoomProfile
.- Return type:
list
- Returns:
A list of
BoomProfile
key values
- write_profile(force=False)[source]¶
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 theBoomProfile
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)[source]¶
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.
- __annotations__ = {}¶
- __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)[source]¶
Initialise a new
OsProfile
object.If neither
profile_file
norprofile_data
is given, all ofname
,short_name
,version
, andversion_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__()[source]¶
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 theOsProfile
constructor, with values passed as a dictionary to theprofile_data
keyword argument.- Returns:
a string representation of this
OsProfile
.- Return type:
string
- __str__()[source]¶
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()[source]¶
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 presentValueError
is raised.- Raises:
ValueError
- _comments = None¶
Comment descriptors read from on-disk store
- _from_data(profile_data, dirty=True)[source]¶
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 theprofile_data
argument.- Returns:
None
- _from_file(profile_file)[source]¶
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 theprofile_file
argument.- Returns:
None
- _generate_id()[source]¶
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()[source]¶
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()[source]¶
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 callingwrite_profile()
before the object is disposed of).- Return type:
NoneType
- Raises:
OsError
if an error occurs removing the file orValueError
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={})[source]¶
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:
- classmethod from_os_release(os_release, profile_data=None)[source]¶
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:
- classmethod from_os_release_file(path, profile_data={})[source]¶
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:
- property os_id¶
The
os_id
of this profile.- Getter:
returns the
os_id
as a string.- Type:
string
- write_profile(force=False)[source]¶
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
andversion_id
keys are used to construct the file name.If the value of
force
isFalse
and theOsProfile
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()[source]¶
Return the path to the boom profiles directory.
- Returns:
The boom profiles path.
- Return type:
str
- boom.osprofile.drop_profiles()[source]¶
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>)[source]¶
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 eachOsProfile
is tested in turn by callingmatch_fn
. If the matching function returnsTrue
theOsProfile
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)[source]¶
Find an OsProfile by its os_id.
Return the OsProfile object corresponding to
os_id
, orNone
if it is not found.- Return type:
- Returns:
An OsProfile matching os_id or None if no match was found
- boom.osprofile.load_profiles()[source]¶
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)[source]¶
Attempt to match a BootEntry to a corresponding OsProfile.
Probe all loaded
OsProfile
objects with the suppliedBootEntry
in turn, until anOsProfile
reports a match. Checking terminates on the first matchingOsProfile
.- Parameters:
entry – A
BootEntry
object with no attachedOsProfile
.- Returns:
The corresponding
OsProfile
for the suppliedBootEntry
orNone
if no match is found.- Return type:
OsProfile
- boom.osprofile.match_os_profile_by_version(version)[source]¶
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:
- Returns:
An OsProfile matching version or None if not match was found
- boom.osprofile.profiles_loaded()[source]¶
Test whether profiles have been loaded from disk.
- Return type:
bool
- Returns:
True
if profiles are loaded in memory orFalse
otherwise
- boom.osprofile.select_profile(s, osp)[source]¶
Test the supplied profile against selection criteria.
Test the supplied
OsProfile
against the selection criteria ins
and returnTrue
if it passes, orFalse
otherwise.- Parameters:
s – The selection criteria
osp – The
OsProfile
to test
- Return type:
bool
- Returns:
True if
osp
passes selection orFalse
otherwise.
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, andOsProfile
pattern keys that may be overridden in theHostProfile
.
- 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)[source]¶
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 embeddedOsProfile
instance.- __annotations__ = {}¶
- __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)[source]¶
Initialise a new
HostProfile
object.If neither
profile_file
norprofile_data
is given, all ofmachine_id
,name
, andos_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__()[source]¶
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 theHostProfile
constructor, with values passed as a dictionary to theprofile_data
keyword argument.- Returns:
a string representation of this
HostProfile
.- Return type:
string
- __set_os_profile()¶
Set this
HostProfile
’sosp
member to the corresponding profile for the setos_id
.
- __setitem__(key, value)[source]¶
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.
- __str__()[source]¶
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
- _comments = None¶
Comment descriptors read from on-disk store
- _from_data(host_data, dirty=True)[source]¶
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()[source]¶
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
- _identity_key = 'BOOM_HOST_ID'¶
The identity key for this profile class
- _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()[source]¶
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()[source]¶
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 callingwrite_profile()
before the object is disposed of).- Return type:
NoneType
- Raises:
OsError
if an error occurs removing the file orValueError
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
’smachine_id
. This will change thehost_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 thisHostProfile
.- Getter:
returns the
OsProfile
object used by thisHostProfile
.- Setter:
stores a new
OsProfile
for use by thisHostProfile
and updates the storedos_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)[source]¶
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
andname
keys are used to construct the file name.If the value of
force
isFalse
and theHostProfile
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()[source]¶
Return the path to the boom host profiles directory.
- Returns:
The boom host profiles path.
- Return type:
str
- boom.hostprofile.find_host_profiles(selection=None, match_fn=<function select_host_profile>)[source]¶
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 eachHostProfile
is tested in turn by callingmatch_fn
. If the matching function returnsTrue
theHostProfile
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='')[source]¶
Find a HostProfile by its machine_id.
Return the HostProfile object corresponding to
machine_id
, orNone
if it is not found.- Return type:
- Returns:
An HostProfile matching machine_id or None if no match was found.
- boom.hostprofile.host_profiles_loaded()[source]¶
Test whether profiles have been loaded from disk.
- Return type:
bool
- Returns:
True
if profiles are loaded in memory orFalse
otherwise
- boom.hostprofile.load_host_profiles()[source]¶
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)[source]¶
Attempt to match a BootEntry to a corresponding HostProfile.
Attempt to find a loaded
HostProfile
object with the amachine_id
that matches the suppliedBootEntry
. Checking terminates on the first matchingHostProfile
.- Parameters:
entry – A
BootEntry
object with no attachedHostProfile
.- Returns:
The corresponding
HostProfile
for the suppliedBootEntry
orNone
if no match is found.- Return type:
BootEntry
orNoneType
.
- boom.hostprofile.select_host_profile(s, hp)[source]¶
Test the supplied host profile against selection criteria.
Test the supplied
HostProfile
against the selection criteria ins
and returnTrue
if it passes, orFalse
otherwise.- Parameters:
s – The selection criteria
hp – The
HostProfile
to test
- Return type:
bool
- Returns:
True if
hp
passes selection orFalse
otherwise.
boom.command module¶
boom.cache module¶
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 BoomReport
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 BoomReport
module is closely based on the device-mapper
reporting engine and shares many features and behaviours with device
mapper reports.
- class boom.report.BoomField[source]¶
Bases:
object
A
BoomField
represents an instance of aBoomFieldType
including its associated data values.- __init__(report, props)[source]¶
Initialise a new BoomField object.
Initialise a BoomField object and configure the supplied
report
andprops
attributes.- Parameters:
report – The BoomReport that owns this field
props – The BoomFieldProperties object for this field
- _props = None¶
reference to the BoomFieldProperties describing this field
- _report = None¶
reference to the containing BoomReport
- report_num(value)[source]¶
Report a numeric value for this BoomField object.
Set the value for this field to the supplied
value
.- Parameters:
value – The numeric value to set
- Return type:
None
- report_sha(value)[source]¶
Report a SHA value for this BoomField object.
Set the value for this field to the supplied
value
.- Parameters:
value – The SHA value to set
- Return type:
None
- report_str(value)[source]¶
Report a string value for this BoomField object.
Set the value for this field to the supplied
value
.- Parameters:
value – The string value to set
- Return type:
None
- report_string = None¶
The formatted string to be reported for this field.
- set_value(report_string, sort_value=None)[source]¶
Report an arbitrary value for this BoomField object.
Set the value for this field to the supplied
value
, and set the field’ssort_value
to the suppliedsort_value
.- Parameters:
report_string – The string value to set
sort_value – The sort value
- Return type:
None
- sort_value = None¶
The raw value of this field. Used for sorting.
- class boom.report.BoomFieldProperties[source]¶
Bases:
object
- align = None¶
- compact_one = False¶
- compacted = False¶
- dtype = None¶
- field_num = None¶
- implicit = False¶
- initial_width = 0¶
- objtype = None¶
- sort_dir = None¶
- sort_key = False¶
- sort_posn = None¶
- width = 0¶
- class boom.report.BoomFieldType[source]¶
Bases:
object
The
BoomFieldType
class describes the properties of a field available in aBoomReport
instance.- __init__(objtype, name, head, desc, width, dtype, report_fn, align=None)[source]¶
Initialise new BoomFieldType object.
Initialise a new
BoomFieldType
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 BoomReport data type of the field
report_fn – The field reporting function
align – The field alignment value
- Returns:
A new BoomReportFieldType object
- Return type:
BoomReportFieldType
- align = None¶
- desc = None¶
- dtype = None¶
- head = None¶
- name = None¶
- objtype = -1¶
- report_fn = None¶
- width = 8¶
- class boom.report.BoomReport[source]¶
Bases:
object
A class representing a configurable text report with multiple caller-defined fields. An optional title may be provided and he
fields
argument must contain a list ofBoomField
objects describing the required report.- __add_field(field_num, implicit)¶
Add a field to this BoomReport.
Add the specified BoomFieldType to this BoomReport and configure BoomFieldProperties 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 BoomReport
Add the sort key identified by
field_num
to this list of sort keys for this BoomReport.- 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
- __copy_field(field_num, implicit)¶
Copy field definition to BoomFieldProperties
Copy values from a BoomFieldType to BoomFieldProperties.
- 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
BoomReport
.- 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 BoomReport’sreport_types
mask to include the field’s type identifier. Iftype_only
is False the field is also added to this BoomReport’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 BoomReportObjType.
- Parameters:
report_type – The numeric report type to look up
- Returns:
The requested BoomReportObjType.
- Raises:
ValueError if no matching type was found.
- __get_field(field_name)¶
Look up a field by name.
Attempt to find the field named in
field_name
in this BoomReport’s tables of implicit and user-defined fields, returning the a(field, implicit)
tuple, where field contains the requestedBoomFieldType
, andimplicit
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 BoomReport 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, private)[source]¶
Initialise BoomReport.
Initialise a new
BoomReport
object with the specified fields and output control options.- Parameters:
types – List of BoomReportObjType used in this report.
fields – A list of
BoomField
field descriptions.output_fields – An optional list of output fields to be rendered by this report.
opts – An instance of
BoomReportOpts
or None.
- Returns:
A new report object.
- Return type:
BoomReport
.
- __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 BoomReport’sreport_types
mask to include the field’s type identifier. Iftype_only
is False the field is also added to this BoomReport’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 BoomFieldType fields.If
type_only
is True only thereport_types
field is updated: otherwise the parsed fields are added to the BoomReport’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 BoomFieldType fields.If
type_only
is True only thereport_types
field is updated: otherwise the parsed fields are added to the BoomReport’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 correspondingBoomFieldProperties
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 BoomReport.
- 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
- _already_reported = False¶
- _data = None¶
- _field_calc_needed = True¶
- _field_properties = None¶
- _fields = None¶
- _header_written = False¶
- _implicit_fields = [<boom.report.BoomFieldType object>]¶
- _implicit_types = [<boom.report.BoomReportObjType object>]¶
- _keys_count = 0¶
- _output_as_columns()[source]¶
Output this report in column format.
Output the data contained in this
BoomReport
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_rows()[source]¶
Output this report in column format.
Output the data contained in this
BoomReport
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)[source]¶
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
- _rows = None¶
- _sort_required = False¶
- _sort_rows()[source]¶
Sort the rows of this BoomReport.
Sort this report’s rows, according to the configured sort keys.
- Returns:
None
- _types = None¶
- opts = None¶
- private = None¶
- report_object(obj)[source]¶
Report data for object.
Add a row of data to this
BoomReport
. Thedata
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()[source]¶
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
- report_types = 0¶
- class boom.report.BoomReportObjType[source]¶
Bases:
object
Class representing a type of object to be reported on. Instances of
BoomReportObjType
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 thedata_fn
member may be simplylambda x: x
.- __init__(objtype, desc, prefix, data_fn)[source]¶
Initialise BoomReportObjType.
Initialise a new
BoomReportObjType
object with the specifiedobjtype
,desc
, optionalprefix
anddata_fn
. Theobjtype
must be an integer power of two that is unique within a given report. Thedata_fn
should accept an object as its only argument and return an object of the requested type.
- data_fn = None¶
- desc = ''¶
- objtype = -1¶
- prefix = ''¶
- class boom.report.BoomReportOpts[source]¶
Bases:
object
Options controlling the formatting and output of a boom report.
- __init__(columns=80, headings=True, buffered=True, separator=' ', field_name_prefix='', unquoted=True, aligned=True, report_file=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>)[source]¶
Initialise BoomReportOpts object.
Initialise a
BoomReportOpts
object to control output of aBoomReport
.- 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
BoomReportOpts
object.- Return type:
<class BoomReportOpts>
- aligned = True¶
- buffered = True¶
- columns = 0¶
- columns_as_rows = False¶
- field_name_prefix = None¶
- headings = True¶
- report_file = None¶
- separator = None¶
- unquoted = True¶