genvid.toolbox.DockerTool

class genvid.toolbox.DockerTool

Bases: NetworkTool

Handle manipulation of Docker image archives.

RE_IMAGE_IMAGEID = re.compile('(?P<image>.+)_(?P<version>[^_]*)_(?P<imageid>[0-9a-f]{12})\\.(?P<archfmt>[^.]*)')

Decompose an image filename into <image>_<version>_<id>.<archfmt>

RE_SUCCESSFUL_BUILD = re.compile('(Successfully built |sha256:)([0-9a-f]+)')

Regular expression matching docker build message when successful.

RE_DIRTY_VERSION = re.compile('^(latest|dev|.*[.+]dirty|\\d+\\.\\d+\\.\\d+\\.0)$')

Regex to determine if an image version is dirty.

Dirty versions are those whose build number is 0. For backward compatibility, we also match on version matching:

  • latest.

  • dev.

  • Anything that ends in .dirty.

Changed in version 1.20.0: Updated the regex to follow the new convention for dirty builds introduced in the new release model.

IMAGE_TEMPLATE = '{image}_{version}_{imageid}.{archfmt}'

Template of an image filename. Must match RE_IMAGE_IMAGEID.

__init__(**kwargs)

Initialize DockerTool.

Changed in version 1.46.0: Add kwargs to pass to subclasses.

DOCKER_MACHINE_NAME

A mirror of DOCKER_MACHINE_NAME, giving the name of the Docker machine.

GENVID_DOCKER_API_TIMEOUT

A mirror of GENVID_DOCKER_API_TIMEOUT, which defined the timeout of the docker API. Must be set before the first call to docker.

New in version 1.34.0.

property docker

Retrieve the docker client.

Will be lazily initialized on the first call.

set_docker_env(timeout=120)

Set up the Docker environment using Docker machine.

Changed in version 1.20.1: DOCKER_MACHINE_NAME no longer default to default. If not set, the environment will not be changed.

build_docker(tag, path=None, rm=True, forcerm=True, **kwargs)

Build a Docker image.

Returns the image build.

static version_to_imagetag(image, version)

Return a tag suitable for Docker.

get_images_config_from_folder(baseurl, basedir: Optional[Union[Path, str]] = None)

Return the configuration for all images under basedir.

Parameters:

  • baseurl – The baseurl for all images.

  • basedir – The folder under which the images are found.

Changed in version 1.20.0:

update_image(image: str, version: str = 'latest', clean: bool = False, compress: bool = False, basedir: Optional[Union[Path, str]] = None)

Update a docker image under the specified directory.

More specifically, this method will compare the latest available version of an image known to docker and compare that to whatever is available under basedir. If there is no docker image under basedir matching the image ID and the version requested, the latest version of the image will be fetched using the docker client.

Parameters:

  • image – Name of the image.

  • version – Version of the image.

  • clean – If True, images with matching name that have a different version or image ID will be removed.

  • compress – If True, the docker image will be compressed into a ZIP file. This applies whether or not the image was updated.

  • basedir – The directory under which the image is saved. Default to GENVID_SDK_FOLDER/images.

Raises:

RuntimeError – If we find a matching image name under basedir which is neither a docker image or a ZIP archive.

:raises ValueError : When the image list is empty for image:tag.

Changed in version 1.12.0:

  • Added the compress parameter.

Changed in version 1.20.0:

  • Added the basedir parameter.

Changed in version 1.21.0:

  • Augmented documentation.

  • Fixed some linting errors.

  • Reduced the complexity of the method.

get_image_path(image, version, imageid, archfmt='docker', basedir: Optional[Union[Path, str]] = None) → str

Return the path for the specified image.

Parameters:

basedir – The base path of the images. Default to GENVID_SDK_FOLDER/images.

Changed in version 1.20.0: Added the basedir parameter.

get_image_filename(image, version, imageid, archfmt='docker') → str

Return the filename for the specified image.

New in version 1.20.0.

get_images(basedir: Optional[Union[Path, str]] = None)

Get list of images formatted to match RE_IMAGE_IMAGEID.

Parameters:

basedir – Directory where to find the images. Default to GENVID_SDK_FOLDER/images.

Returns:

a generated list of tuples containing the image, version, imageid and archfmt.

Changed in version 1.20.0: Added parameter basedir.

get_latest_images(basedir: Optional[Union[Path, str]] = None)

Retun a dictionary of all the latest images in basedir.

Parameters:

basedir – Directory where to find the images. Default to GENVID_SDK_FOLDER/images.

Returns:

dictionary of tuple of version, imageid and archfmt keyed with the image name.

Changed in version 1.20.0: Added parameter basedir.

class docker.DockerTool

Implementation of genvid.toolbox.DockerTool