models.images

Module Contents

Classes

Image() An image on the server.
RegistryData(self,image_name,*args,**kwargs) Image metadata stored on the registry, including available platforms.
ImageCollection()

Functions

normalize_platform(platform,engine_info)
class Image

An image on the server.

__repr__()
labels()

The labels of an image as dictionary.

short_id()

The ID of the image truncated to 10 characters, plus the sha256: prefix.

tags()

The image’s tags.

history()

Show the history of an image.

Returns:
(str): The history of the image.
Raises:
docker.errors.APIError
If the server returns an error.
save(chunk_size=DEFAULT_DATA_CHUNK_SIZE)

Get a tarball of an image. Similar to the docker save command.

Args:
chunk_size (int): The number of bytes returned by each iteration
of the generator. If None, data will be streamed as it is received. Default: 2 MB
Returns:
(generator): A stream of raw archive data.
Raises:
docker.errors.APIError
If the server returns an error.

Example:

>>> image = cli.get_image("busybox:latest")
>>> f = open('/tmp/busybox-latest.tar', 'w')
>>> for chunk in image:
>>>   f.write(chunk)
>>> f.close()
tag(repository, tag=None, **kwargs)

Tag this image into a repository. Similar to the docker tag command.

Args:
repository (str): The repository to set for the tag tag (str): The tag name force (bool): Force
Raises:
docker.errors.APIError
If the server returns an error.
Returns:
(bool): True if successful
class RegistryData(image_name, *args, **kwargs)

Image metadata stored on the registry, including available platforms.

__init__(image_name, *args, **kwargs)
id()

The ID of the object.

short_id()

The ID of the image truncated to 10 characters, plus the sha256: prefix.

pull(platform=None)

Pull the image digest.

Args:
platform (str): The platform to pull the image for. Default: None
Returns:
(Image): A reference to the pulled image.
has_platform(platform)

Check whether the given platform identifier is available for this digest.

Args:
platform (str or dict): A string using the os[/arch[/variant]]
format, or a platform dictionary.
Returns:
(bool): True if the platform is recognized as available, False otherwise.
Raises:
docker.errors.InvalidArgument
If the platform argument is not a valid descriptor.
reload()
class ImageCollection
build(**kwargs)

Build an image and return it. Similar to the docker build command. Either path or fileobj must be set.

If you have a tar file for the Docker build context (including a Dockerfile) already, pass a readable file-like object to fileobj and also pass custom_context=True. If the stream is compressed also, set encoding to the correct value (e.g gzip).

If you want to get the raw output of the build, use the build() method in the low-level API.

Args:

path (str): Path to the directory containing the Dockerfile fileobj: A file object to use as the Dockerfile. (Or a file-like

object)

tag (str): A tag to add to the final image quiet (bool): Whether to return the status nocache (bool): Don’t use the cache when set to True rm (bool): Remove intermediate containers. The docker build

command now defaults to --rm=true, but we have kept the old default of False to preserve backward compatibility

timeout (int): HTTP timeout custom_context (bool): Optional if using fileobj encoding (str): The encoding for a stream. Set to gzip for

compressing

pull (bool): Downloads any updates to the FROM image in Dockerfiles forcerm (bool): Always remove intermediate containers, even after

unsuccessful builds

dockerfile (str): path within the build context to the Dockerfile buildargs (dict): A dictionary of build arguments container_limits (dict): A dictionary of limits applied to each

container created by the build process. Valid keys:

  • memory (int): set memory limit for build
  • memswap (int): Total memory (memory + swap), -1 to disable
    swap
  • cpushares (int): CPU shares (relative weight)
  • cpusetcpus (str): CPUs in which to allow execution, e.g.,
    "0-3", "0,1"
shmsize (int): Size of /dev/shm in bytes. The size must be
greater than 0. If omitted the system uses 64MB

labels (dict): A dictionary of labels to set on the image cache_from (list): A list of images used for build cache

resolution
target (str): Name of the build-stage to build in a multi-stage
Dockerfile
network_mode (str): networking mode for the run commands during
build
squash (bool): Squash the resulting images layers into a
single layer.
extra_hosts (dict): Extra hosts to add to /etc/hosts in building
containers, as a mapping of hostname to IP address.

platform (str): Platform in the format os[/arch[/variant]]. isolation (str): Isolation technology used during build.

Default: None.
Returns:
(tuple): The first item is the Image object for the
image that was build. The second item is a generator of the build logs as JSON-decoded objects.
Raises:
docker.errors.BuildError
If there is an error during the build.
docker.errors.APIError
If the server returns any other error.
TypeError
If neither path nor fileobj is specified.
get(name)

Gets an image.

Args:
name (str): The name of the image.
Returns:
(Image): The image.
Raises:
docker.errors.ImageNotFound
If the image does not exist.
docker.errors.APIError
If the server returns an error.
get_registry_data(name)

Gets the registry data for an image.

Args:
name (str): The name of the image.
Returns:
(RegistryData): The data object.
Raises:
docker.errors.APIError
If the server returns an error.
list(name=None, all=False, filters=None)

List images on the server.

Args:

name (str): Only show images belonging to the repository name all (bool): Show intermediate image layers. By default, these are

filtered out.
filters (dict): Filters to be processed on the image list.
Available filters: - dangling (bool) - label (str): format either key or key=value
Returns:
(list of Image): The images.
Raises:
docker.errors.APIError
If the server returns an error.
load(data)

Load an image that was previously saved using save() (or docker save). Similar to docker load.

Args:
data (binary): Image data to be loaded.
Returns:
(list of Image): The images.
Raises:
docker.errors.APIError
If the server returns an error.
pull(repository, tag=None, **kwargs)

Pull an image of the given name and return it. Similar to the docker pull command. If no tag is specified, all tags from that repository will be pulled.

If you want to get the raw pull output, use the pull() method in the low-level API.

Args:

repository (str): The repository to pull tag (str): The tag to pull auth_config (dict): Override the credentials that

login() has set for this request. auth_config should contain the username and password keys to be valid.

platform (str): Platform in the format os[/arch[/variant]]

Returns:
(Image or list): The image that has been pulled.
If no tag was specified, the method will return a list of Image objects belonging to this repository.
Raises:
docker.errors.APIError
If the server returns an error.

Example:

>>> # Pull the image tagged `latest` in the busybox repo
>>> image = client.images.pull('busybox:latest')
>>> # Pull all tags in the busybox repo
>>> images = client.images.pull('busybox')
push(repository, tag=None, **kwargs)
remove(*args, **kwargs)
search(*args, **kwargs)
prune(filters=None)
prune_builds(*args, **kwargs)
normalize_platform(platform, engine_info)