API Reference

libcnb is a Python language binding of the Cloud Native Buildpacks API.

It is a non-opinionated implementation adding language constructs and convenience methods for working with the API.

Main Entrypoint

The primary entrypoint for the build and detect phases.

run(detector: Callable[[libcnb._detect.DetectContext], libcnb._detect.DetectResult], builder: Callable[[libcnb._build.BuildContext], libcnb._build.BuildResult]) -> None

Combines the invocation of both build and detect into a single entry point.

Calling run from an executable with a name matching "detect" or "builder" will result in the matching detector or builder being called respectively.

Parameters:

Name	Type	Description	Default
detector	Callable[[libcnb._detect.DetectContext], libcnb._detect.DetectResult]	The definition of a callback that can be invoked when the detect function is executed. Buildpack authors should implement a detector that performs the specific detect phase operations for a buildpack. It should be a callable that takes in a DetectContext and returns a DetectResult.	required
builder	Callable[[libcnb._build.BuildContext], libcnb._build.BuildResult]	The definition of a callback that can be invoked when the build function is executed. Buildpack authors should implement a builder that performs the specific detect phase operations for a buildpack. It should be a callable that takes in a BuildContext and returns a BuildResult.	required

Detection API

Classes and functions related to the detect phase.

DetectContext pydantic-model

DetectContext contains the inputs to detection.

Attributes:

Name	Type	Description
application_dir	Path	The location of the application source code as provided by the lifecycle.
buildpack	Buildpack	Metadata about the buildpack, from buildpack.toml.
platform	Platform	The contents of the platform.
stack_id	str	The ID of the stack.

DetectResult pydantic-model

DetectResult contains the results of detection.

Attributes:

Name	Type	Description
passed	bool	Indicates whether detection has passed.
plans	List[libcnb._plan.BuildPlan]	The build plans contributed by the buildpack.

detect(detector: Callable[[libcnb._detect.DetectContext], libcnb._detect.DetectResult]) -> None

An implementation of the detect phase according to the Cloud Native Buildpacks specification.

Parameters:

Name	Type	Description	Default
detector	Callable[[libcnb._detect.DetectContext], libcnb._detect.DetectResult]	The definition of a callback that can be invoked when the detect function is executed. Buildpack authors should implement a detector that performs the specific detect phase operations for a buildpack. It should be a callable that takes in a DetectContext and returns a DetectResult.	required

Build API

Classes and functions related to the build phase.

BuildContext pydantic-model

BuildContext contains the inputs to build.

Attributes:

Name	Type	Description
application_dir	Path	The location of the application source code as provided by the lifecycle.
buildpack	Buildpack	Metadata about the buildpack, from buildpack.toml.
layers	Layers	The layers available to the buildpack. Also exposes a convinience function get to create or load a layer in the appropriate layers directory.
store	Store	The metadata that is persisted even across cache cleaning.
plan	BuildpackPlan	The buildpack plan provided to the buildpack.
platform	Platform	The contents of the platform.
stack_id	str	The ID of the stack.

BuildResult pydantic-model

BuildResult contains the results of build phase.

Attributes:

Name	Type	Description
layers	List[libcnb._layers.Layer]	The collection of LayerCreators contributed by the buildpack.
store	Store	The metadata that is persisted even across cache cleaning.
launch_metadata	LaunchMetadata	The metadata that will be exported to launch.toml. Allows configuring labels, processes, slices and BOM for the app image.
build_metadata	BuildMetadata	The metadata that will be exported to build.toml. Allows exporting the build BOM and unmet dependencies.

to_path(self, path: Union[str, pathlib.Path]) -> None

Exports the build result to the filesystem.

Parameters:

Name	Type	Description	Default
path	Union[str, pathlib.Path]	Path to the layers directory.	required

build(builder: Callable[[libcnb._build.BuildContext], libcnb._build.BuildResult]) -> None

An implementation of the build phase according to the Cloud Native Buildpacks specification.

Parameters:

Name	Type	Description	Default
builder	Callable[[libcnb._build.BuildContext], libcnb._build.BuildResult]	The definition of a callback that can be invoked when the build function is executed. Buildpack authors should implement a builder that performs the specific detect phase operations for a buildpack. It should be a callable that takes in a BuildContext and returns a BuildResult.	required

Outputs

Classes and functions binding the various buildpack outputs during the build phase to a Python API.

BOMEntry pydantic-model

BOMEntry contains a bill of materials entry.

Attributes:

Name	Type	Description
name	str	The name of the entry.
metadata	Dict[str, Any]	The optional metadata of the entry.

BuildMetadata pydantic-model

BuildMetadata represents the contents of build.toml.

Attributes:

Name	Type	Description
bom	List[libcnb._output.BOMEntry]	The collection of entries for the bill of materials.
unmet	List[libcnb._output.UnmetPlanEntry]	The collection of buildpack plan entries that should be passed through to subsequent providers.

__bool__(self) -> bool special

Returns true if there is any content to be written to the output toml file.

from_path(path: Union[str, pathlib.Path]) -> BuildMetadata classmethod

Creates a BuildMetadata from the TOML file at the given path.

to_path(self, path: Union[str, pathlib.Path]) -> None

Export LaunchMetadata to the TOML file at the given path.

Label pydantic-model

Label represents an image label.

Attributes:

Name	Type	Description
key	str	The key of the label.
value	str	The value of the label.

LaunchMetadata pydantic-model

LaunchMetadata represents the contents of launch.toml.

Attributes:

Name	Type	Description
labels	List[libcnb._output.Label]	The collection of image labels contributed by the buildpack.
processes	List[libcnb._output.Process]	The collection of process types contributed by the buildpack.
slices	List[libcnb._output.Slice]	The collection of process types contributed by the buildpack.
bom	List[libcnb._output.BOMEntry]	The collection of entries for the bill of materials.

__bool__(self) -> bool special

Returns true if there is any content to be written to the output toml file.

from_path(path: Union[str, pathlib.Path]) -> LaunchMetadata classmethod

Creates a LaunchMetadata from the TOML file at the given path.

to_path(self, path: Union[str, pathlib.Path]) -> None

Export LaunchMetadata to the TOML file at the given path.

Process pydantic-model

Process represents metadata about a type of command that can be run.

Attributes:

Name	Type	Description
type_	str	The type of the process.
command	str	The command of the process.
args	List[str]	The arguments to the command.
direct	bool	If set to True the command is exec'd directly by the os (no profile.d scripts run).
default	bool	If set to True the process type being defined should be the default process type for the app image.

Slice pydantic-model

Slice represents metadata about a slice.

Attributes:

Name	Type	Description
paths	List[str]	The contents of the slice.

Store pydantic-model

Store represents the contents of store.toml.

Attributes:

Name	Type	Description
metadata	Dict[str, Any]	Represents the persistent metadata.

__bool__(self) -> bool special

Returns true if there is any content to be written to the output toml file.

from_path(path: Union[str, pathlib.Path]) -> Store classmethod

Creates a Store from the TOML file at the given path.

to_path(self, path: Union[str, pathlib.Path]) -> None

Export Store to the TOML file at the given path.

UnmetPlanEntry pydantic-model

UnmetPlanEntry denotes an unmet buildpack plan entry.

When a buildpack returns an UnmetPlanEntry in the BuildResult, any BuildpackPlanEntry with a matching name will be provided to subsequent providers.

Attributes:

Name	Type	Description
name	str	The name of the entry.

Layers

Classes and functions related to layer metadata manipulation.

Environment

Environment provides a key-value store for declaring environment variables.

append(self, name: str, value: str, delim: str) -> None

Adds a key-value pair to the environment as an appended value.

Parameters:

Name	Type	Description	Default
name	str	Name of the environment variable.	required
value	str	Value of the environment variable to append.	required
delim	str	The delimiter to use when appending the value.	required

default(self, name: str, value: str) -> None

Adds a key-value pair to the environment as a default value.

Parameters:

Name	Type	Description	Default
name	str	Name of the environment variable.	required
value	str	The default value of the environment variable.	required

from_path(env_path: Union[pathlib.Path, str]) -> Environment classmethod

Loads the environment from the given path on disk.

override(self, name: str, value: str) -> None

Adds a key-value pair to the environment as an overridden value.

Parameters:

Name	Type	Description	Default
name	str	Name of the environment variable.	required
value	str	The overridden value of the environment variable.	required

prepend(self, name: str, value: str, delim: str) -> None

Adds a key-value pair to the environment as a prepended value.

Parameters:

Name	Type	Description	Default
name	str	Name of the environment variable.	required
value	str	Value of the environment variable to prepend.	required
delim	str	The delimiter to use when preprending the value.	required

to_path(self, path: Union[pathlib.Path, str]) -> None

Exports the environment to the given path on disk.

ExecD

Exec represents the exec.d layer location.

Attributes:

Name	Type	Description
path	Path	The path to the exec.d directory.

__init__(self, path: Union[str, pathlib.Path]) special

Initializer for exec.d.

file_path(self, name: str) -> Path

Returns the fully qualified file path for a given name.

process_file_path(self, process: str, name: str) -> Path

Returns the fully qualified file path for a given process type and name.

Layer pydantic-model

Layer provides a representation of a layer managed by a buildpack.

This representation is based on the specification described in https://github.com/buildpacks/spec/blob/main/buildpack.md#layers.

Attributes:

Name	Type	Description
path	Path	The absolute location of the layer on disk.
name	str	The descriptive name of the layer.
metadata_file	Path	The aboluste location of the layer content metadata file.
build	bool	Indicates whether the layer is available to subsequent buildpacks during their build phase according to the specification: https://github.com/buildpacks/spec/blob/main/buildpack.md#build-layers.
launch	bool	Indicates whether the layer is exported into the application image and made available during the launch phase according to the specification: https://github.com/buildpacks/spec/blob/main/buildpack.md#launch-layers.
cache	bool	Cache indicates whether the layer is persisted and made available to subsequent builds of the same application according to the specification: https://github.com/buildpacks/spec/blob/main/buildpack.md#launch-layers and https://github.com/buildpacks/spec/blob/main/buildpack.md#build-layers.
shared_env	Environment	The set of environment variables attached to the layer and made available during both the build and launch phases according to the specification: https://github.com/buildpacks/spec/blob/main/buildpack.md#provided-by-the-buildpacks.
build_env	Environment	The set of environment variables attached to the layer and made available during the build phase according to the specification: https://github.com/buildpacks/spec/blob/main/buildpack.md#provided-by-the-buildpacks.
launch_env	Environment	The set of environment variables attached to the layer and made available during the launch phase according to the specification: https://github.com/buildpacks/spec/blob/main/buildpack.md#provided-by-the-buildpacks.
process_launch_envs	Dict[str, libcnb._layers.Environment]	A dict of environment variables attached to the layer and made available to specified proccesses in the launch phase accoring to the specification: https://github.com/buildpacks/spec/blob/main/buildpack.md#provided-by-the-buildpacks.
metadata	Dict[str, Any]	An unspecified field allowing buildpacks to communicate extra details about the layer. Examples of this type of metadata might include details about what versions of software are included in the layer such that subsequent builds can inspect that metadata and choose to reuse the layer if suitable. The Metadata field ultimately fills the metadata field of the Layer Content Metadata TOML file according to the specification: https://github.com/buildpacks/spec/blob/main/buildpack.md#layer-content-metadata-toml.
profile	Profile	The collection of values to be written into profile.d.
process_profiles	Dict[str, libcnb._layers.Profile]	A dict of process types to the collection of values to be written into profile.d for specific process types.
exec_d	ExecD	The exec.d executables set in the layer.

compare_metadata(self, expected_metadata: Dict[str, Any], exact: bool = False) -> bool

Utility method to compare the layer metadata on disk with the expected metadata.

Parameters:

Name	Type	Description	Default
expected_metadata	Dict[str, Any]	A dict containing the expected metadata.	required
exact	bool	If set to true, the actual metadata must exactly match the expected metadata. If set to false, only the keys in expected metadata and their values are checked against the actual metadata. Any extra keys in actual metadata are ignored.	False

dump(self) -> None

Exports the layer metadata to disk.

load(self, load_all: bool = False) -> Layer

Loads the layer metadata from disk if it exists.

reset(self) -> Layer

Resets the layer metadata, cleans up the existing layer directory and creates an empty layer.

Layers pydantic-model

Layers represents the set of layers managed by a buildpack.

Attributes:

Name	Type	Description
path	Path	The absolute location of the set of layers managed by a buildpack on disk.

get(self, name: str, load_all: bool = False) -> Layer

Create or load a layer with the given name along with its metadata.

Parameters:

Name	Type	Description	Default
name	str	Name of the layer to create or load.	required
load_all	bool	If set to True, also loads the environment and profile.d values associated with the layer.	False

Profile

Profile is the collection of values to be written into profile.d.

add(self, name: str, value: str) -> None

Adds a profile.d script with a given name and script content.

Parameters:

Name	Type	Description	Default
name	str	Name of the profile.d script.	required
value	str	The script content.	required

from_path(profile_path: Union[pathlib.Path, str]) -> Profile classmethod

Loads a collection of profile.d scripts from disk.

to_path(self, path: Union[pathlib.Path, str]) -> None

Exports the current collection of profile.d scripts to disk.

Buildpack

Classes and functions related to the buildpack specific information and metadata.

Buildpack pydantic-model

Buildpack is the contents of the buildpack.toml file.

Attributes:

Name	Type	Description
api	str	The api version expected by the buildpack.
info	BuildpackInfo	Information about the buildpack.
path	Path	The absolute path to the buildpack.
stacks	List[libcnb._buildpack.BuildpackStack]	The collection of stacks supported by the buildpack.
metadata	Dict[str, Any]	Arbitrary metadata attached to the buildpack.
order	List[libcnb._buildpack.BuildpackOrder]	Collection of buildpack order definitions in the buildpack.

from_path(path: Union[str, pathlib.Path]) -> Buildpack classmethod

Loads the buildpack information given a path on disk.

BuildpackGroupEntry pydantic-model

BuildpackGroupEntry is a buildpack within in a buildpack order group.

Attributes:

Name	Type	Description
id	str	The id of the buildpack.
version	str	The version of the buildpack.
optional	bool	Whether the buildpack is optional within the buildpack group.

BuildpackInfo pydantic-model

BuildpackInfo is information about the buildpack.

Attributes:

Name	Type	Description
id	str	The id of the buildpack.
version	str	The version of the buildpack.
name	str	The name of the buildpack.
homepage	str	The homepage of the buildpack.
clear_env	bool	Clears user-defined environment variables when true on executions of bin/detect and bin/build.
description	str	The string describing the buildpack.
keywords	List[str]	A list of words that are associated with the buildpack.
licenses	List[libcnb._buildpack.License]	A list of buildpack licenses.

BuildpackOrder pydantic-model

BuildpackOrder is an order definition in the buildpack.

Attributes:

Name	Type	Description
group	List[libcnb._buildpack.BuildpackGroupEntry]	The collection of groups within the order.

BuildpackStack pydantic-model

BuildpackStack is a stack supported by the buildpack.

Attributes:

Name	Type	Description
id	str	The id of the stack.
mixins	List[str]	The collection of mixins associated with the stack.

License pydantic-model

License contains information about a Software License governing the use or redistribution of a buildpack.

Attributes:

Name	Type	Description
type_	str	The identifier for the license. It may use the SPDX 2.1 license expression, but is not limited to identifiers in the SPDX Licenses List.
uri	str	A string that may be specified in lieu of or in addition to type to point to the license if this buildpack is using a nonstandard license.

Build Plans

Classes and functions binding the various plan I/O during the detect/build phase to a Python API.

BuildpackPlan pydantic-model

BuildpackPlan represents a buildpack plan input during the build process.

Attributes:

Name	Type	Description
entries	List[libcnb._plan.BuildpackPlanEntry]	All the buildpack plan entries.

from_path(path: Union[pathlib.Path, str]) -> BuildpackPlan classmethod

Loads a buildpack plan from the path to a TOML file.

BuildpackPlanEntry pydantic-model

BuildpackPlanEntry represents an entry in the buildpack plan.

Attributes:

Name	Type	Description
name	str	The name of the entry.
metadata	Dict[str, Any]	The optional metadata of the entry.

BuildPlan pydantic-model

BuildPlan represents the provisions and requirements of a buildpack during detection.

Attributes:

Name	Type	Description
provides	List[libcnb._plan.BuildPlanProvide]	The dependencies provided by the buildpack.
requires	List[libcnb._plan.BuildPlanRequire]	The dependencies required by the buildpack.

BuildPlanProvide pydantic-model

BuildPlanProvide represents a dependency provided by a buildpack.

Attributes:

Name	Type	Description
name	str	The name of the dependency.

BuildPlanRequire pydantic-model

BuildPlanRequire represents a dependency required by a buildpack.

Attributes:

Name	Type	Description
name	str	The name of the dependency.
metadata	Dict[str, Any]	The optional metadata for the dependency.

Platform

Classes and functions binding the Platform metadata.

Platform pydantic-model

Platform is the contents of the platform directory.

Attributes:

Name	Type	Description
path	Path	The path to the platform directory.
env	Mapping[str, str]	The environment exposed by the platform.

from_path(path: Union[str, pathlib.Path]) -> Platform classmethod

Construct a Platform object from a given path.