Library Reference

class TplBuild(base_dir: str, config: TplConfig, *, user_config: Optional[UserConfig] = None, registry_client: Optional[AsyncRegistryClient] = None)

Bases: object

Container class for all top level build operations.

Parameters:

• base_dir – The base directory of the build

• config – The build configuration

classmethod from_path(base_dir: str, *, user_config: UserConfig, registry_client: Optional[AsyncRegistryClient] = None) → TplBuild

Create a TplBuild object from just the base directory. This will attempt to load a file named “tplbuild.yml” from within base_dir to load the configuration. If not found an empty configuration will be used.

Parameters:

base_dir – The base directory of the build

jinja_render_debug(template: str, params: Dict[str, Any], *, file_template=False, file_env=False) → Tuple[str, SourceMapper]

Like jinja_render but also returns a SourceMapper object that can be used to map output text to the template line that generated it.

jinja_render(template: str, params: Dict[str, Any], *, file_template=False, file_env=False) → str

Renders a Jinja template in the appropriate jinja environment and returns the rendered result. If file_env is True this will allow other templates to be loaded using include commands. If file_template is True this will interpret template as a file path to a template rather than a template.

On Failure this will raise a TplBuildTempalteException.

get_base_image_name(base_image: BaseImage, *, use_digest: bool = False) → str

Return the base image name by rendering the base image name config template.

get_stage_config(stage_name: str, profile: str, platform: str, render_vars: Dict[str, Any]) → StageConfig

Return the StageConfig for the given stage name. This will first check TplConfig.stages to see if there is an explicit configuration for this stage.

Otherwise, if the stage name starts with “base-” or “base_” a base image StageConfig will be returned.

If the name starts with ‘anon-’ or ‘anon_’ instead the stage will be considered an “anonymous” stage. This means that it will neither be built as a base image nor will it be tagged or pushed to any image name. Such images are used for intermediate build operations and are not an output of the build themselves.

For every other image the image_names and push_names default values will be substituted where needed and the templates will be evaluated.

lookup_base_image(stage_name: str, platform: str, *, profile: str = '') → Tuple[str, BaseImage]

Returns the full image name and unrendered BaseImage image node that represents the requested base image.

Raises:

• KeyError – If the base image does not exist or has not been built

• TplBuildException – If no base image repo is configured

property default_profile: str

Returns the default configuration name. If there are no configuration profiles then this will return an empty string.

async get_default_platform() → str

Calculate the default platform.

get_render_vars(profile: str, *, extra_vars: Optional[Dict[str, Any]] = None) → Dict[str, Any]

Returns the render context to pass into Jinja to render the build file for the given profile.

async render(*, profile: str = '', platform: str = '', extra_vars: Optional[Dict[str, Any]] = None) → Dict[str, StageData]

Render all contexts and stages into StageData.

Returns:

dict mapping stage names/context names to their respective StageData.

plan(stages: List[StageData]) → List[BuildOperation]

Plan how to build the given list of stages.

Parameters:

stages – The list of stages to build in the form of StageData objects. Use render() to render all the stages for a given profile. You should also use resolve_source_images() and resolve_base_images() before calling plan.

Returns:

A list of BuildOperation objects that that define how the stages are to be built. This list is returned topologically sorted so that all dependencies of a stage appear before it. Typically this should be fed into build().

async build(build_ops: List[BuildOperation]) → None

Execute the build operations.

Parameters:

build_ops – The list of build operations to execute. This should be topologically sorted each build operation appears only after all of its dependencies have been listed. Typically this should just be the return value from plan().

async resolve_image(image: SourceImage, *, check_only=False, force_update=False) → SourceImage

Resolves a SourceImage returning a new SourceImage object with the digest field set. If digest is already set on image then this will just return image itself.

Parameters:

• image – Source image definition to resolve

• check_only – Do not attempt to fetch the image if it is not cached. This will trigger a TplBuildException if the image is not available.

• force_update – Update the image digest even if it is locally cached

Raises:

TplBuildException – if the image could not be fetched or if it has no matching platform.

async resolve_base_images(stages: List[StageData], *, dereference=False, resolve_from_registry=True) → None

Resolve all BaseImage nodes found in the image graph, setting their content_hash attribute based on cached build data.

Parameters:

• dereference –

  If True then all BaseImage nodes will be fully hashed (including their build contexts) to produce a content hash that will be set in the BaseImage node. This content hash will be available at stage.base_image for any passed stages that represent base images.

  Further, when base images are resolved, if the computed content_hash does not match the cached content_hash then the node will be replaced with the base image’s underlying build definition.

• resolve_from_registry – Modifies behavior when dereferencing to first check if the image is present in the registry before dereferencing the image. If the image is present the build data will be updated automatically.

This modifies the passed in build graph and does not return anything directly.

async resolve_source_images(stages: List[StageData], *, check_only=False, force_update=False) → None

Resolve the manifest digest for each source image in the build graph. This updates the build graph passed in to resolve_source_images and does not return anything directly.

save_build_data()

Save build data to disk.

class ContextPattern(pattern: str)

Bases: object

Represents a pattern used to control what files are availble in a build context.

ignoring

Flag indicating if matching this pattern means the matched element should be ignored or not ignored.

Type:

bool

matches(path: str) → bool

Returns True if this pattern matches the path

class BuildContext(base_dir: Optional[str], umask: Optional[int], ignore_patterns: Iterable[str])

Bases: object

Class representing and capable of writing a build context.

Parameters:

• base_dir – The base directory of the build context

• umask – If not None, the user permission bits will be copied to the ‘group’ and ‘all’ bits and then the umask will be applied. If None then the exact file permissions will be forwarded to the build context.

• ignore_patterns – An interable of ignore patterns in the order they should be tested. A path will be ignored if the last pattern it matches in the list is not negated. This is meant to mirror the behavior and semantics of https://docs.docker.com/engine/reference/builder/#dockerignore-file

ignored(path: str)

Returns True if the given path should be ignored (not present) in the build contxt. path should start with a directory separator and should be relative to self.base_dir.

walk_context(*, extra_files: Optional[Dict[str, Tuple[int, bytes]]] = None, ignore_func: Optional[Callable[[str], bool]] = None) → Iterable[TarInfo]

Generator that yields TarInfo objects for each not-ignored object in the context. Objects are yielded in a deterministic order based on the names.

write_context(io_out: BytesIO, *, extra_files: Optional[Dict[str, Tuple[int, bytes]]] = None, compress: bool = False) → None

Write the context to io_out.

Parameters:

• io_out – The file-like object to write the build context to as a tar file.

• extra_files – Extra file data to add at the root of the archive. this is of the form (file mode, file data).

• compress – If set the output stream will be gzipped.

compute_partial_hash(*, patterns: Optional[List[str]] = None) → str

Compute a partial hash of the context where all hashed files must match at least one file pattern in patterns.

property full_hash: str

The full content hash of the build context, as a hex digest

property symbolic_hash: str

The symbolic content hash of the build context, as a hex digest. This is different from full_hash in that it does not read any files from the build context and is only a hash of the parameters that define the build context instead.

class ImageDefinition

Bases: object

Base class for all image deinitions. These abstractly represent a build graph.

abstract local_hash_data(symbolic: bool) → Any

Return a JSON-able payload suitable for hashing the image node. This should not recursively include hashes of any dependencies.

get_dependencies() → List[ImageDefinition]

Returns a list of image dependencies for this image node. The first dependant is considered the “primary” dependant.

set_dependencies(deps: Iterable[ImageDefinition]) → None

Sets the dependencies for this image. This must be the correct size for the image type.

merge_into(image: ImageDefinition) → None

Called during planning during the canonicalization phase. Two images will be merged if they represent the same build step. This step allows for bookkeepping when tracking what image definitions came from where.

class StageDescriptor(name: str, profile: str, platform: str)

Bases: object

Describes a rendered stage

name: str

profile: str

platform: str

class StageDefinedImage(stage_descs: Set[StageDescriptor])

Bases: ImageDefinition

Parent class for image nodes that are defined by build stages. This is meant to help facilitate bookkeeping for display/debug purposes of where an image node was defined.

stage_descs: Set[StageDescriptor]

merge_into(image: ImageDefinition) → None

Merge the stage descriptors together.

class CommandImage(stage_descs: Set[StageDescriptor], parent: ImageDefinition, command: str, args: str)

Bases: StageDefinedImage

Image node ending in a command other than COPY.

parent: ImageDefinition

command: str

args: str

local_hash_data(symbolic: bool) → Any

Return the local hash data for this node.

get_dependencies() → List[ImageDefinition]

Returns a list of image dependencies for this image node. The first dependant is considered the “primary” dependant.

set_dependencies(deps: Iterable[ImageDefinition]) → None

Sets the dependencies for this image. This must be the correct size for the image type.

class CopyCommandImage(stage_descs: Set[StageDescriptor], parent: ImageDefinition, context: ImageDefinition, command: str)

Bases: StageDefinedImage

Image node ending in a COPY command

parent: ImageDefinition

context: ImageDefinition

command: str

local_hash_data(symbolic: bool)

Return a JSON-able payload suitable for hashing the image node. This should not recursively include hashes of any dependencies.

get_dependencies() → List[ImageDefinition]

Returns a list of image dependencies for this image node. The first dependant is considered the “primary” dependant.

set_dependencies(deps: Iterable[ImageDefinition]) → None

Sets the dependencies for this image. This must be the correct size for the image type.

class SourceImage(repo: str, tag: str, platform: str, digest: Optional[str] = None)

Bases: ImageDefinition

Image node representing a source image

repo: str

tag: str

platform: str

digest: Optional[str] = None

local_hash_data(symbolic: bool) → Any

Return a JSON-able payload suitable for hashing the image node. This should not recursively include hashes of any dependencies.

class ScratchImage(platform: str)

Bases: ImageDefinition

Represents an empty scratch image

platform: str

The platform of the scratch image. Many build systems separate image data by platform so even though scratch images do not necessarily have platform-specific data we need to handle them each like they are different.

local_hash_data(symbolic: bool) → Any

Return a JSON-able payload suitable for hashing the image node. This should not recursively include hashes of any dependencies.

class MultiPlatformImage(stage_descs: Set[StageDescriptor], images: Dict[str, ImageDefinition])

Bases: StageDefinedImage

Container image node that merges multiple other images into a single manifest list.

images: Dict[str, ImageDefinition]

Mapping of platform names to images.

get_dependencies() → List[ImageDefinition]

Returns a list of image dependencies for this image node. The first dependant is considered the “primary” dependant.

set_dependencies(deps: Iterable[ImageDefinition]) → None

Sets the dependencies for this image. This must be the correct size for the image type.

local_hash_data(symbolic: bool) → Any

Return a JSON-able payload suitable for hashing the image node. This should not recursively include hashes of any dependencies.

class BaseImage(profile: str, stage: str, platform: str, image: Optional[ImageDefinition] = None, content_hash: Optional[str] = None, digest: Optional[str] = None)

Bases: ImageDefinition

Image node representing a base image.

Attributes:

profile: str

Name of the profile this base image belongs to

stage: str

Name of the build stage

platform: str

The platform to select for this base image

image: Optional[ImageDefinition] = None

The build graph behind this base image. This can be None if the base image will not be dereferenced.

content_hash: Optional[str] = None

The conent hash of the base image. Typically this is supplied from tplbuild’s cached build data and is used to find the base image from an external repository.

digest: Optional[str] = None

The digest of the image as stored in the registry. Like content_hash this also typically comes from the cached build data.

get_dependencies() → List[ImageDefinition]

Returns a list of image dependencies for this image node. The first dependant is considered the “primary” dependant.

set_dependencies(deps: Iterable[ImageDefinition]) → None

Sets the dependencies for this image. This must be the correct size for the image type.

local_hash_data(symbolic: bool) → Any

Return a JSON-able payload suitable for hashing the image node. This should not recursively include hashes of any dependencies.

class ContextImage(stage_descs: Set[StageDescriptor], context: BuildContext, platform: str)

Bases: StageDefinedImage

Image node representing a build context

context: BuildContext

platform: str

local_hash_data(symbolic: bool) → Any

For non-symbolic hash calculations it’s actually the CopyImage nodes that calculate the hash based on file data in the context.

class StageData(name: str, image: ImageDefinition, config: StageConfig, base_image: Optional[BaseImage] = None)

Bases: object

Dataclass holding metadata about a rendered image stage.

name: str

The name of the build stage

image: ImageDefinition

The image definition

config: StageConfig

The stage config

base_image: Optional[BaseImage] = None

If this is a base image this will be set as the appropriate base image reference.