lbhelper package

Subpackages

Submodules

lbhelper.build_image module

lbhelper.build_image.build_image(targets: list, iso_build_dir: Path = PosixPath('/tmp/iso'), fresh_build: bool = True, distribution: str = 'trixie', image_name: str = 'myos', skip_build: bool = False)

Build image from targets.

Parameters:

  • targets (List) – Targets to process. Elements can be Target or List[Target].

  • iso_build_dir (pathlib.Path,Optional) – Image build directory.

  • fresh_build (bool) – If True, remove build directory before performing any operations for fresh build.

  • distribution (str) – Base Debian distribution for image. trixie by default.

  • image_name (str) – Name of image. myos by default.

  • skip_build (bool) – If True, lb build won’t run.

lbhelper.defaults module

lbhelper.defaults.AUTO_SCRIPT_DIR = PosixPath('auto')

Auto script directory under the image build directory.

lbhelper.defaults.BUILD_SCRIPT_PATH = PosixPath('auto/build')

build script path under the auto script directory.

lbhelper.defaults.CLEAN_SCRIPT_PATH = PosixPath('auto/clean')

clean script path under the auto script directory.

lbhelper.defaults.CONFIG_SCRIPT_PATH = PosixPath('auto/config')

config script path under the auto script directory.

lbhelper.defaults.CONFIG_DIR = PosixPath('config')

Configuration directory under the image build directory.

lbhelper.defaults.CHROOT_INCLUDE_DIR = PosixPath('config/includes.chroot')

Files presents in live/installed system See https://live-team.pages.debian.net/live-manual/html/live-manual/customizing-contents.en.html#live-chroot-local-includes .

lbhelper.defaults.BINARY_INCLUDE_DIR = PosixPath('config/includes.binary')

Files presents in iso and system. Similar to CHROOT_INCLUDE_DIR

lbhelper.defaults.PACKAGE_LIST_DIR = PosixPath('config/package-lists')

Upstream package lists See https://live-team.pages.debian.net/live-manual/html/live-manual/customizing-package-installation.en.html

lbhelper.defaults.CHROOT_DEB_DIR = PosixPath('config/packages.chroot')

Custom deb directory See https://live-team.pages.debian.net/live-manual/html/live-manual/customizing-package-installation.en.html#456

lbhelper.defaults.BUILD_TIME_APT_PREFERENCE_FILE = PosixPath('config/apt/preferences')

Build time apt preference file

lbhelper.defaults.RUN_TIME_APT_PREFERENCE_FILE = PosixPath('config/includes.chroot/etc/apt/preferences')

Run time apt preference file

lbhelper.defaults.HOOKS_DIR = PosixPath('config/hooks')

Hooks base directory See https://live-team.pages.debian.net/live-manual/html/live-manual/customizing-contents.en.html#539

lbhelper.defaults.LIVE_HOOKS_DIR = PosixPath('config/hooks/live')

Live hooks directory

lbhelper.defaults.NORMAL_HOOKS_DIR = PosixPath('config/hooks/normal')

Normal hooks directory

lbhelper.defaults.BOOTLOADER_DIR = PosixPath('config/bootloaders')

Live build image bootloader directory

lbhelper.defaults.BUILTIN_BOOTLOADER_DIR = PosixPath('/usr/share/live/build/bootloaders')

Default builtin bootloader directory on host. Copied as default bootloaders for live system. See https://live-team.pages.debian.net/live-manual/html/live-manual/customizing-binary.en.html#640

lbhelper.defaults.DEFAULT_LOGGER = <Logger lbhelper (INFO)>

Default logger

lbhelper.defaults.DEFAULT_ISO_BUILD_DIR = PosixPath('/tmp/iso')

Default image build directory. All configs and files will be copied to here.

lbhelper.defaults.DEFAULT_LIVE_BUILD_BINARY = PosixPath('/usr/bin/lb')

Default live build executable path

lbhelper.defaults.DEFAULT_DPKG_NAME_BINARY = PosixPath('/usr/bin/dpkg-name')

Default dpkg-name executable path

lbhelper.defaults.DEFAULT_IMAGE_NAME = 'myos'

Defaul built image name.

lbhelper.defaults.DEFAULT_DISTRIBUTION = 'trixie'

Default debian distribution.

lbhelper.extensions module

lbhelper.extensions.copy_bootloaders(source_bootloader_dir: Path = PosixPath('/usr/share/live/build/bootloaders')) → DirectConfig

Copying bootloaders to image build directory. Each subdirectory under the source directory represents a bootloader. See https://live-team.pages.debian.net/live-manual/html/live-manual/customizing-binary.en.html#641

Parameters:

source_bootloader_dir – Source bootloaders directory. It should contain 1 to multiple bootloaders.

Returns:

bootloader copying target

Return type:

DirectConfig

lbhelper.file_helpers module

lbhelper.file_helpers.render_template_to_file(template_path: Path, target_path: Path = None, **kwargs) → Path

Render template to a temp file and returns path of it. Generally used with pathlib.Path fields in Targets.

Parameters:

  • template_path (pathlib.Path) – Template path.

  • target_path (pathlib.Path,Optional) – Target path. If not given, then writing to a temporary file.

  • kwargs – Additional kwargs for template.

Returns:

Path of rendered file.

Return type:

pathlib.Path

lbhelper.file_helpers.render_template_to_string(template_path: Path, **kwargs) → str

Render template to string. Generally used as input as other templates. For example, when defining a HooKScript to write a config file, the config file itself can be defined in another template and passed to the HookScript, which decouples the HookScript and the config file.

Parameters:

  • template_path (pathlib.Path) – Template path.

  • kwargs – Additional kwargs for template.

Returns:

Rendered string.

Return type:

str

lbhelper.file_helpers.escape_string_for_shell_script(s: str) → str

Escape “” and “$”. Useful when writing string to file via shell scripts. For instance, when writing strings via: ` cat > file<<EOL $SOME_STRING EOL ` The “” and “$” of $SOME_STRING need to be escaped. Otherwise, they’ll be treated as special characters from source script and cause unexpected results.

Parameters:

s (str) – String to escape.

Returns:

Escaped string.

Return type:

str

lbhelper.file_helpers.download_file(url: str) → Path

Download file from url as temporary file and return path of it. Generally used with pathlib.Path fields in Targets.

Parameters:

url (str) – URL to download.

Returns:

Path of downloaded file.

Return type:

pathlib.Path

lbhelper.live_build module

lbhelper.live_build.remove_build_dir(iso_build_dir: Path)

Remove iso_build_dir. Usually used before start fresh build.

Parameters:

iso_build_dir (pathlib.Path) – Path to image build directory.

class lbhelper.live_build.LBOperation(*values)

Bases: StrEnum

BUILD = 'build'
CLEAN = 'clean'
CONFIG = 'config'
lbhelper.live_build.run_lb_operation(operation: LBOperation, iso_build_dir: Path, live_build_binary: Path = PosixPath('/usr/bin/lb'))

Run given live build operation in iso_build_dir.

Parameters:

  • operation (LBOperation) – A live build operation.

  • iso_build_dir (pathlib.Path) – Image build directory.

  • live_build_binary (pathlib.Path,Optional) – Live build binary path. Default to defaults.DEFAULT_LIVE_BUILD_BINARY.

lbhelper.logger module

class lbhelper.logger.SimpleFormatter(color=True, *args, **kwargs)

Bases: Formatter

grey = '\x1b[248m'
blue = '\x1b[36m'
green = '\x1b[32m'
brown = '\x1b[96m'
red = '\x1b[90m'
bold_red = '\x1b[196m'
reset = '\x1b[0m'
metadata_format = '[%(asctime)s] [%(levelname)s] [%(name)s] [%(filename)s:%(lineno)d] '
message_format = '%(message)s'
time_format = '%Y-%m-%dT%H:%M:%S'
FORMATS = {10: '\x1b[36m[%(asctime)s] [%(levelname)s] [%(name)s] [%(filename)s:%(lineno)d] \x1b[0m\x1b[248m%(message)s\x1b[0m', 20: '\x1b[32m[%(asctime)s] [%(levelname)s] [%(name)s] [%(filename)s:%(lineno)d] \x1b[0m\x1b[248m%(message)s\x1b[0m', 30: '\x1b[96m[%(asctime)s] [%(levelname)s] [%(name)s] [%(filename)s:%(lineno)d] \x1b[0m\x1b[248m%(message)s\x1b[0m', 40: '\x1b[90m[%(asctime)s] [%(levelname)s] [%(name)s] [%(filename)s:%(lineno)d] \x1b[0m\x1b[248m%(message)s\x1b[0m', 50: '\x1b[196m[%(asctime)s] [%(levelname)s] [%(name)s] [%(filename)s:%(lineno)d] \x1b[0m\x1b[248m%(message)s\x1b[0m'}
format(record)

Format the specified record as text.

The record’s attribute dictionary is used as the operand to a string formatting operation which yields the returned string. Before formatting the dictionary, a couple of preparatory steps are carried out. The message attribute of the record is computed using LogRecord.getMessage(). If the formatting string uses the time (as determined by a call to usesTime(), formatTime() is called to format the event time. If there is exception information, it is formatted using formatException() and appended to the message.

class lbhelper.logger.ConsoleHandler

Bases: StreamHandler

lbhelper.run_command module

lbhelper.run_command.run_command(command: List[str], cwd: Path = None)
lbhelper.run_command.write_command_to_logger(process: Popen)

lbhelper.target_writer module

class lbhelper.target_writer.TargetHandler

Bases: object

Abstract class for target handlers. Must implement the execute method which called by the TargetWriter.

abstractmethod execute(targets: List[Target])

Called by the TargetWriter as the entrypoint for running main target logic. See target_handlers parameter of TargetWriter.

Parameters:

targets (List[Target]) – List of target to process.

class lbhelper.target_writer.TargetWriter(target_handlers: Dict[ABCMeta, execute], targets: List)

Bases: object

Process given targets based on corresponding handler.

Parameters:

  • target_handlers (Dict[type(Target)]) – Map of target type to target handlers.

  • targets (List) – Targets to process. Elements can be Target or List[Target].

execute()

Process given targets based on corresponding handler.

class lbhelper.target_writer.UpstreamPackagesWriter(iso_build_dir: Path)

Bases: TargetHandler

Write upstream packages to lbhelper.defaults.PACKAGE_LIST_DIR.

Parameters:

iso_build_dir (pathlib.Path,Optional) – Image build directory.

execute(targets: List[UpstreamPackages])

Called by the TargetWriter as the entrypoint for running main target logic. See target_handlers parameter of TargetWriter.

Parameters:

targets (List[Target]) – List of target to process.

class lbhelper.target_writer.CustomDebWriter(iso_build_dir: Path, dpkg_name_binary: Path = PosixPath('/usr/bin/dpkg-name'))

Bases: TargetHandler

Save custom debs to lbhelper.defaults.CHROOT_DEB_DIR.

Parameters:

  • iso_build_dir (pathlib.Path,Optional) – Image build directory.

  • dpkg_name_binary (pathlib.Path,Optional) – dpkg-name binary path. Used to correct .deb file name.

execute(targets: List[CustomDeb])

Called by the TargetWriter as the entrypoint for running main target logic. See target_handlers parameter of TargetWriter.

Parameters:

targets (List[Target]) – List of target to process.

class lbhelper.target_writer.AptPreferencesWriter(iso_build_dir: Path)

Bases: TargetHandler

Add time apt preferences to lbhelper.defaults.BUILD_TIME_APT_PREFERENCE_FILE / lbhelper.defaults.RUN_TIME_APT_PREFERENCE_FILE depends on preference type.

Parameters:

iso_build_dir (pathlib.Path,Optional) – Image build directory.

execute(targets: List[AptPreference])

Called by the TargetWriter as the entrypoint for running main target logic. See target_handlers parameter of TargetWriter.

Parameters:

targets (List[Target]) – List of target to process.

class lbhelper.target_writer.HookScriptWriter(iso_build_dir: Path)

Bases: TargetHandler

Add hook scripts to lbhelper.defaults.LIVE_HOOKS_DIR (for live system) and lbhelper.defaults.NORMAL_HOOKS_DIR (for live/installed system).

Parameters:

iso_build_dir (pathlib.Path,Optional) – Image build directory.

execute(targets: List[HookScript])

Called by the TargetWriter as the entrypoint for running main target logic. See target_handlers parameter of TargetWriter.

Parameters:

targets (List[Target]) – List of target to process.

class lbhelper.target_writer.StaticFileWriter(iso_build_dir: Path)

Bases: TargetHandler

Add static file to lbhelper.defaults.CHROOT_INCLUDE_DIR (for live/installed system) and lbhelper.defaults.BINARY_INCLUDE_DIR (as part of iso).

Parameters:

iso_build_dir (pathlib.Path,Optional) – Image build directory.

execute(targets: List[StaticFile])

Called by the TargetWriter as the entrypoint for running main target logic. See target_handlers parameter of TargetWriter.

Parameters:

targets (List[Target]) – List of target to process.

class lbhelper.target_writer.DirectConfigWriter(iso_build_dir: Path)

Bases: TargetHandler

Add files to image build directory.

Parameters:

iso_build_dir (pathlib.Path,Optional) – Image build directory.

execute(targets: List[DirectConfig])

Called by the TargetWriter as the entrypoint for running main target logic. See target_handlers parameter of TargetWriter.

Parameters:

targets (List[Target]) – List of target to process.

lbhelper.targets module

class lbhelper.targets.Target

Bases: object

Abstract class for all Targets.

class lbhelper.targets.PackagePriority(*values)

Bases: StrEnum

Package priority. Used as value of UpstreamPackages.priority. For more details about each value, see https://www.debian.org/doc/debian-policy/ch-archive.html#priorities . Note that NOTSET denotes not adding priority to result package set file.

REQUIRED = 'required'
IMPORTANT = 'important'
STANDARD = 'standard'
OPTIONAL = 'optional'
NOTSET = 'NOTSET'
class lbhelper.targets.UpstreamPackages(packages: List[str], package_set_code: str, live_only: bool = False, priority: PackagePriority = PackagePriority.NOTSET)

Bases: Target

A set of upstream packages.

Parameters:

  • packages (List[str]) – List of package names

  • package_set_code (str) – A unique identifier for the package set.

  • live_only (bool,Optional) – Only install in live image. Default is False (install in both live and installed system)

  • priority (PackagePriority,Optional) – Package priority. NOTSET by default.

packages: List[str]
package_set_code: str
live_only: bool = False
priority: PackagePriority = 'NOTSET'
class lbhelper.targets.CustomDeb(get_deb: Callable[[], Path])

Bases: Target

A custom deb package.

Parameters:

get_deb (Callable[[], pathlib.Path]) – Callback function to get source deb package.

get_deb: Callable[[], Path]
class lbhelper.targets.HookScript(get_script_file: Callable[[], Path], hook_name: str, live_only: bool = False)

Bases: Target

A hook runs in chroot time. See https://live-team.pages.debian.net/live-manual/html/live-manual/customizing-contents.en.html#539 .

Parameters:

  • get_script_file (Callable[[], pathlib.Path]) – Callback function to get hook shell script.

  • live_only (bool,Optional) – Only run in live image. Default is False (install in both live and installed system).

get_script_file: Callable[[], Path]
hook_name: str
live_only: bool = False
class lbhelper.targets.StaticFile(target_filepath: Path, get_source_file: Callable[[], Path], binary_file: bool = False)

Bases: Target

A static file.

Parameters:

  • target_filepath (pathlib.Path) – Expected path on built iso/system.

  • get_source_file (Callable[[], pathlib.Path]) – Callback function to get source file.

  • binary_file (bool,Optional) – Save file in chroot (False) to access via live/installed system. or as binary (True) to access in iso without booting system. False by default.

target_filepath: Path
get_source_file: Callable[[], Path]
binary_file: bool = False
class lbhelper.targets.AptPreferenceType(*values)

Bases: StrEnum

Apt preference type. Used as value of AptPreference.preference_type. See https://live-team.pages.debian.net/live-manual/html/live-manual/customizing-package-installation.en.html#514

BUILD_TIME = 'build_time'
RUN_TIME = 'run_time'
class lbhelper.targets.AptPreference(package: str, pin: str, pin_priority: int, preference_type: AptPreferenceType)

Bases: Target

An apt preference. See https://live-team.pages.debian.net/live-manual/html/live-manual/customizing-package-installation.en.html#514 and https://linux.die.net/man/5/apt_preferences .

Parameters:

  • package (str) – Package selector.

  • pin (str) – Pin preference.

  • pin_priority (int) – Priority.

  • preference_type (AptPreferenceType) – Apt preference type. Refer to AptPreferenceType.

package: str
pin: str
pin_priority: int
preference_type: AptPreferenceType
class lbhelper.targets.DirectConfig(target_filepath: Path, get_source_file: Callable[[], Path])

Bases: Target

Directly copying files/directories to arbitrary destinations under an image build directory. Avoid directly using this target unless you have special requirements on customizing build process, which should be supported by extensions or new targets(PRs welcomed).

Parameters:

  • target_filepath (pathlib.Path) – Expected path under the image build directory.

  • get_source_file (Callable[[], pathlib.Path]) – Callback function to get source file.

target_filepath: Path
get_source_file: Callable[[], Path]

Module contents

class lbhelper.PackagePriority(*values)

Bases: StrEnum

Package priority. Used as value of UpstreamPackages.priority. For more details about each value, see https://www.debian.org/doc/debian-policy/ch-archive.html#priorities . Note that NOTSET denotes not adding priority to result package set file.

REQUIRED = 'required'
IMPORTANT = 'important'
STANDARD = 'standard'
OPTIONAL = 'optional'
NOTSET = 'NOTSET'
class lbhelper.UpstreamPackages(packages: List[str], package_set_code: str, live_only: bool = False, priority: PackagePriority = PackagePriority.NOTSET)

Bases: Target

A set of upstream packages.

Parameters:

  • packages (List[str]) – List of package names

  • package_set_code (str) – A unique identifier for the package set.

  • live_only (bool,Optional) – Only install in live image. Default is False (install in both live and installed system)

  • priority (PackagePriority,Optional) – Package priority. NOTSET by default.

packages: List[str]
package_set_code: str
live_only: bool = False
priority: PackagePriority = 'NOTSET'
class lbhelper.CustomDeb(get_deb: Callable[[], Path])

Bases: Target

A custom deb package.

Parameters:

get_deb (Callable[[], pathlib.Path]) – Callback function to get source deb package.

get_deb: Callable[[], Path]
class lbhelper.HookScript(get_script_file: Callable[[], Path], hook_name: str, live_only: bool = False)

Bases: Target

A hook runs in chroot time. See https://live-team.pages.debian.net/live-manual/html/live-manual/customizing-contents.en.html#539 .

Parameters:

  • get_script_file (Callable[[], pathlib.Path]) – Callback function to get hook shell script.

  • live_only (bool,Optional) – Only run in live image. Default is False (install in both live and installed system).

get_script_file: Callable[[], Path]
hook_name: str
live_only: bool = False
class lbhelper.StaticFile(target_filepath: Path, get_source_file: Callable[[], Path], binary_file: bool = False)

Bases: Target

A static file.

Parameters:

  • target_filepath (pathlib.Path) – Expected path on built iso/system.

  • get_source_file (Callable[[], pathlib.Path]) – Callback function to get source file.

  • binary_file (bool,Optional) – Save file in chroot (False) to access via live/installed system. or as binary (True) to access in iso without booting system. False by default.

target_filepath: Path
get_source_file: Callable[[], Path]
binary_file: bool = False
class lbhelper.AptPreference(package: str, pin: str, pin_priority: int, preference_type: AptPreferenceType)

Bases: Target

An apt preference. See https://live-team.pages.debian.net/live-manual/html/live-manual/customizing-package-installation.en.html#514 and https://linux.die.net/man/5/apt_preferences .

Parameters:

  • package (str) – Package selector.

  • pin (str) – Pin preference.

  • pin_priority (int) – Priority.

  • preference_type (AptPreferenceType) – Apt preference type. Refer to AptPreferenceType.

package: str
pin: str
pin_priority: int
preference_type: AptPreferenceType
class lbhelper.AptPreferenceType(*values)

Bases: StrEnum

Apt preference type. Used as value of AptPreference.preference_type. See https://live-team.pages.debian.net/live-manual/html/live-manual/customizing-package-installation.en.html#514

BUILD_TIME = 'build_time'
RUN_TIME = 'run_time'
class lbhelper.DirectConfig(target_filepath: Path, get_source_file: Callable[[], Path])

Bases: Target

Directly copying files/directories to arbitrary destinations under an image build directory. Avoid directly using this target unless you have special requirements on customizing build process, which should be supported by extensions or new targets(PRs welcomed).

Parameters:

  • target_filepath (pathlib.Path) – Expected path under the image build directory.

  • get_source_file (Callable[[], pathlib.Path]) – Callback function to get source file.

target_filepath: Path
get_source_file: Callable[[], Path]
lbhelper.render_template_to_file(template_path: Path, target_path: Path = None, **kwargs) → Path

Render template to a temp file and returns path of it. Generally used with pathlib.Path fields in Targets.

Parameters:

  • template_path (pathlib.Path) – Template path.

  • target_path (pathlib.Path,Optional) – Target path. If not given, then writing to a temporary file.

  • kwargs – Additional kwargs for template.

Returns:

Path of rendered file.

Return type:

pathlib.Path

lbhelper.render_template_to_string(template_path: Path, **kwargs) → str

Render template to string. Generally used as input as other templates. For example, when defining a HooKScript to write a config file, the config file itself can be defined in another template and passed to the HookScript, which decouples the HookScript and the config file.

Parameters:

  • template_path (pathlib.Path) – Template path.

  • kwargs – Additional kwargs for template.

Returns:

Rendered string.

Return type:

str

lbhelper.escape_string_for_shell_script(s: str) → str

Escape “” and “$”. Useful when writing string to file via shell scripts. For instance, when writing strings via: ` cat > file<<EOL $SOME_STRING EOL ` The “” and “$” of $SOME_STRING need to be escaped. Otherwise, they’ll be treated as special characters from source script and cause unexpected results.

Parameters:

s (str) – String to escape.

Returns:

Escaped string.

Return type:

str

lbhelper.download_file(url: str) → Path

Download file from url as temporary file and return path of it. Generally used with pathlib.Path fields in Targets.

Parameters:

url (str) – URL to download.

Returns:

Path of downloaded file.

Return type:

pathlib.Path

lbhelper.build_image(targets: list, iso_build_dir: Path = PosixPath('/tmp/iso'), fresh_build: bool = True, distribution: str = 'trixie', image_name: str = 'myos', skip_build: bool = False)

Build image from targets.

Parameters:

  • targets (List) – Targets to process. Elements can be Target or List[Target].

  • iso_build_dir (pathlib.Path,Optional) – Image build directory.

  • fresh_build (bool) – If True, remove build directory before performing any operations for fresh build.

  • distribution (str) – Base Debian distribution for image. trixie by default.

  • image_name (str) – Name of image. myos by default.

  • skip_build (bool) – If True, lb build won’t run.