pyHDLC Reference

Functions

pyHDLC.BuildImage(image: Union[str, List[str]], registry: str = 'gcr.io/hdl-containers', collection: str = 'debian/bullseye', architecture: str = 'amd64', dockerfile: str = None, target: str = None, argimg: str = None, pkg: bool = False, dry: bool = False, default: bool = False, test: bool = False) → None

Build and optionally test container image(s).

Parameters:

  • image – Bare image name(s), without registry, collection or architecture. The supported syntax for each image name is name[#location], where the optional location is ignored during the build if provided (it’s used for testing only, see TestImage()).

  • registry – Optionally, set the prefix of the registry.

  • collection – Optionally, set the collection to build the image from.

  • architecture – Optionally, set the architecture to build the image for.

  • dockerfile – Optionally, set the Dockerfile to build the image with.

  • target – Optionally, set the target stage in the dockerfile.

  • argimg – Optionally, set the build argument IMAGE.

  • pkg – Optionally, specify explicitly whether the image to be built is a package image.

  • dry – Do not build the image, just print the command(s) that would be executed.

  • default – Instead of providing all of the parameters, get them from the YAML configuration file.

  • test – Test the image(s) after building.

pyHDLC.GenerateJobList(name: str, fmt: str = 'gha', dry: bool = False) → None

Generate list of jobs for a named task.

Parameters:

  • name – Identifier to extract jobs from the YAML configuration file.

  • fmt – Output format (by default, print to GITHUB_OUTPUT).

  • dry – Do not set the output, just print the list of jobs.

pyHDLC.PullImage(image: Union[str, List[str]], registry: str = 'gcr.io/hdl-containers', collection: str = 'debian/bullseye', architecture: str = 'amd64', dry: bool = False) → None

Pull container image(s) from registry.

Parameters:

  • image – Bare image name(s), without registry, collection or architecture. The supported syntax for each image name is name[#location], where the optional location is ignored if provided (it’s used in TestImage() only).

  • registry – Optionally, set the prefix of the registry.

  • collection – Optionally, set the collection to pull the image for.

  • architecture – Optionally, set the architecture to pull the image for.

  • dry – Do not pull the image, just print the command that would be executed.

pyHDLC.PushImage(image: Union[str, List[str]], registry: str = 'gcr.io/hdl-containers', collection: str = 'debian/bullseye', architecture: str = 'amd64', dry: bool = False, mirror: Union[str, List[str]] = None) → None

Push container image(s) to registry/registries.

Parameters:

  • image – Bare image name(s), without registry, collection or architecture. The supported syntax for each image name is name[#location], where the optional location is ignored if provided (it’s used in TestImage() only).

  • registry – Optionally, set the prefix of the registry.

  • collection – Optionally, set the collection to push the image from.

  • architecture – Optionally, set the architecture to push the image for.

  • dry – Do not push the image, just print the command(s) that would be executed.

  • mirror –

    List of additional registry/registries to push to. Supported placeholders:

    • #A: architecture

    • #C: collection

pyHDLC.TestImage(image: Union[str, List[str]], registry: str = 'gcr.io/hdl-containers', collection: str = 'debian/bullseye', architecture: str = 'amd64', dry: bool = False) → None

Test container image(s).

Parameters:

  • image – Bare image name(s), without registry, collection or architecture. The supported syntax for each image name is name[#<DirName>], where the optional <DirName> is used as the location in package images to copy the content from.

  • registry – Optionally, set the prefix of the registry.

  • collection – Optionally, set the collection to test the image from.

  • architecture – Optionally, set the architecture to test the image for.

  • dry – Do not test the image, just print the command(s) that would be executed.

Dataclasses

class pyHDLC.Config(HDLC: int = None, anchors: ~typing.Dict = <factory>, defaults: ~pyHDLC.ConfigDefaults = <factory>, jobs: ~pyHDLC.ConfigJobs = <factory>)

Configuration containing global defaults, image building argument overrides and job/task list declarations. See YAML Configuration File.

HDLC: int = None

Version of the configuration file syntax.

anchors: Dict

Placeholder for anchors used to reduce verbosity. This field is resolved by the loader and ignored by the analyzer.

defaults: ConfigDefaults

Default global parameters and images which need explicitly overriding build argument defaults.

jobs: ConfigJobs

List of jobs/tasks to be used in CI to dynamically spawn jobs.

class pyHDLC.ConfigDefaultImageItem(dockerfile: str = None, target: str = None, argimg: str = None)

Optionally overridable fields for image build argument defaults.

argimg: str = None

The base IMAGE to pass as a build-arg to docker build.

dockerfile: str = None

The dockerfile to pass to docker build.

target: str = None

The target stage to pass to docker build.

class pyHDLC.ConfigDefaults(registry: str = 'gcr.io/hdl-containers', collection: str = 'debian/bullseye', architecture: str = 'amd64', images: Dict[str, ConfigDefaultImageItem] = None)

Default global parameters and images which need explicitly overriding build argument defaults. See Defaults.

architecture: str = 'amd64'

Default architecture.

collection: str = 'debian/bullseye'

Default collection.

images: Dict[str, ConfigDefaultImageItem] = None

Allows override default image build arguments.

registry: str = 'gcr.io/hdl-containers'

Default registry prefix.

class pyHDLC.ConfigJobs(default: ~typing.Dict[str, ~typing.Dict[str, ~typing.List[str]]] = <factory>, pkgonly: ~typing.Dict[str, ~typing.Dict[str, ~typing.List[str]]] = <factory>, runonly: ~typing.Dict[str, ~typing.Dict[str, ~typing.List[str]]] = <factory>, custom: ~typing.Dict[str, ~pyHDLC.ConfigJobsCustomItem] = <factory>)

List of jobs/tasks to be used in CI to dynamically spawn jobs. See Jobs.

custom: Dict[str, ConfigJobsCustomItem]

Declare the lists of jobs/tasks as cross-products (exclude is supported).

default: Dict[str, Dict[str, List[str]]]

Build two images for each collection and architecture, a regular image and a package image.

pkgonly: Dict[str, Dict[str, List[str]]]

Build a package image for each collection and architecture.

runonly: Dict[str, Dict[str, List[str]]]

Build a regular image for each collection and architecture.

class pyHDLC.ConfigJobsCustomExcludeItem(sys: Dict[str, List[str]], params: Dict[str, str])

An exclusion rule for a list of taks generated through a cross-product.

params: Dict[str, str]

Combination of argument values to exclude.

sys: Dict[str, List[str]]

Collection(s) and architecture(s).

class pyHDLC.ConfigJobsCustomItem(images: ~typing.List[~typing.Any], sys: ~typing.Dict[str, ~typing.List[str]], exclude: ~typing.List[~pyHDLC.ConfigJobsCustomExcludeItem] = <factory>)

A custom list of jobs/tasks defined by combining lists of images and system, optionally applying exclusion rules.

exclude: List[ConfigJobsCustomExcludeItem]

Optionally, declare combinations of sys and images which should be excluded from the produced cross-products.

images: List[Any]

Either a list or a list of lists of image names. Argument substitution is supported through ${arg}.

sys: Dict[str, List[str]]

Collection(s) and architecture(s).