Usage as library

Builderer can easily be used without configuration files.

Example

The following example pipeline

from builderer import Builderer, ActionFactory

f = ActionFactory(registry="registry.example.com", prefix="project/name")
b = Builderer(simulate=True)

b.add_action_likes(*f.build_image("frontend"))
b.add_action_likes(*f.build_image("backend"))
b.add_action_likes(*f.build_image("database"))

b.run()

will print

Building image: frontend
Building image: backend
Building image: database
Pushing image: database
Pushing image: backend
Pushing image: frontend

Note that because simulate=True was passed, no commands got issued.

Hint

Pass verbose=true to see which commands would have been issued.

Reference

builderer.actions

Builderers file config is a thin wrapper around this module as well as the builderer module.

Action dataclass

A named sequence of commands.

ActionFactory

The ActionFactory class is used to create build tasks.

__init__(*, registry=None, prefix=None, push=True, cache=False, tags=['latest'], backend='docker')

Create predefined or custom actions.

Parameters:

Name	Type	Description	Default
registry	str | None	Registry URL. Defaults to None.	None
prefix	str | None	Registry folder / namespace / user. Defaults to None.	None
push	bool	Whether to allow pushing images. Defaults to True.	True
cache	bool	Allow using cached images. Defaults to False.	False
tags	list[str]	Tags to use. Defaults to ["latest"].	['latest']
backend	typing.Literal['docker', 'podman']	Overwrite backend to use. Defaults to "docker".	'docker'

action(name, commands)

Create a generic action with multiple commands.

Hint: Use this mechanism if other commands aren't sufficient for your usecase.

Parameters:

Name	Type	Description	Default
name	str	Name of the action	required
commands	list[list[str]]	List of commands. Each command is a list of strings: the executable followed by arguments.	required

build_image(directory, *, dockerfile=None, name=None, push=True, qualified=True, extra_tags=None)

Build a docker image and push it to the registry.

Parameters:

Name	Type	Description	Default
directory	str	Directory containing the build context.	required
dockerfile	str | None	Path to Dockerfile. Name of the resulting image. Defaults to /Dockerfile.	None
name	str | None	Name of the resulting image. Defaults to the name of the Dockerfiles parent directory.	None
push	bool	Whether to push the image. Defaults to True.	True
qualified	bool	Whether to add the registry path and prefix to the image name. Defaults to True.	True
extra_tags	list[str] | None	additional tags to use for this image. Defaults to None.	None

extract_from_image(image, path, *dest)

Copy a file from within a docker image.

Parameters:

Name	Type	Description	Default
image	str	Name of the image to copy from.	required
path	str	Source path inside the image.	required
dest	str	Destination paths. The file will be copied to all destinations individually.	()

forward_image(name, *, new_name=None, extra_tags=None)

Pull an image from a registry, retag it and push it using the new names.

Parameters:

Name	Type	Description	Default
name	str	image name to pull	required
new_name	str | None	Set a new name for the image. By default the basename of the pulled image without the tag is used. Defaults to None.	None
extra_tags	list[str] | None	additional tags to use for this image. Defaults to None.	None

pull_image(name)

Pull an image from a registry. This might be usefull to ensure a local image is up to date (e.g. for local builds).

Parameters:

Name	Type	Description	Default
name	str	image name to pull.	required

ActionGroup dataclass

A sequence of actions with many or may not be run in parallel.

builderer.builderer

Builderers file config is a thin wrapper around this module as well as the action module.

Builderer

The Builderer class is used to issue collected actions.

__init__(*, verbose=False, simulate=False, max_parallel=None)

Run commands inside in two queues. A action queue and a post queue.

First the main actions gets handled (FIFO) then the corresponding post actions get called in reversed order (LIFO)

Example

Building is done first, pushing is done as a post steps. This means a build is only pushed if all other main actions have been successful.

Parameters:

Name	Type	Description	Default
verbose	bool	Verbose output. Defaults to False.	False
simulate	bool	Prevent issuing commands. Defaults to False.	False
max_parallel	int	Limit the maximum number of parallel jobs per step. By default the num_parallel argument of each individual step is used.	None

add_action_likes(main, post)

Add two Actions / ActionGroups to the main and the postprocessing queues.

If None is passed for an argument it will be ignored.

Parameters:

Name	Type	Description	Default
main	Action | ActionGroup | None	A Action / ActionGroup to add to the main queue	required
post	Action | ActionGroup | None	A Action / ActionGroup to add to the postprocessing queue	required

run()

Run queue actions and action groups. Stops when done or a command fails.

Returns:

Name	Type	Description
int	int	return code. On success this will be zero. Otherwise it will be the return code of the failed command.

run_action(action)

Run a single Action.

The sequentialls runs each command of the given action. Stops if an error occurs and returns failed return code and command output. Output is only captured if not running verbosely.

Does nothing if self.simulate is True and returns (0, b"").

Parameters:

Name	Type	Description	Default
action	Action	Action to run.	required

Raises:

Type	Description
FileNotFoundError	if any executable was not found.

Returns:

Type	Description
tuple[int, bytes]	tuple[int, bytes]: status code and command output if an error occurred otherwise b"".

run_action_group(group)

Run an action group.

Contained actions get started sequentially, they might however run in parallel as specified in the group and capped by self.max_parallel. Any exception encountered as well as any failed command will stop executing new actions and wait for all running actions to complete.

Any encountered error is returned alongside the corresponding code.

Parameters:

Name	Type	Description	Default
group	ActionGroup	group to run.	required

Returns:

Type	Description
tuple[int, bytes]	tuple[int, bytes]: status code and command output if an error occurred otherwise b"".

run_cmd(command)

Run a single command.

Output is only captured and returned if not running verbosely.

Does nothing if self.simulate is True and returns (0, b"").

Parameters:

Name	Type	Description	Default
command	list[str]	Command to run.	required

Raises:

Type	Description
FileNotFoundError	if the executable was not found.

Returns:

Type	Description
tuple[int, bytes]	tuple[int, bytes]: status code and command output if captured otherwise b"".