api.image

Module Contents

Classes

ImageApiMixin()

Functions

is_file(src)
_import_image_params(repo,tag,image=None,src=None,changes=None)
class ImageApiMixin
get_image(image, chunk_size=DEFAULT_DATA_CHUNK_SIZE)

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

Args:

image (str): Image name to get 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()
history(image)

Show the history of an image.

Args:
image (str): The image to show history for
Returns:
(str): The history of the image
Raises:
docker.errors.APIError
If the server returns an error.
images(name=None, quiet=False, all=False, filters=None)

List images. Similar to the docker images command.

Args:

name (str): Only show images belonging to the repository name quiet (bool): Only return numeric IDs as a list. 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:
(dict or list): A list if quiet=True, otherwise a dict.
Raises:
docker.errors.APIError
If the server returns an error.
import_image(src=None, repository=None, tag=None, image=None, changes=None, stream_src=False)

Import an image. Similar to the docker import command.

If src is a string or unicode string, it will first be treated as a path to a tarball on the local system. If there is an error reading from that file, src will be treated as a URL instead to fetch the image from. You can also pass an open file handle as src, in which case the data will be read from that file.

If src is unset but image is set, the image parameter will be taken as the name of an existing image to import from.

Args:

src (str or file): Path to tarfile, URL, or file-like object repository (str): The repository to create tag (str): The tag to apply image (str): Use another image like the FROM Dockerfile

parameter
import_image_from_data(data, repository=None, tag=None, changes=None)

Like import_image(), but allows importing in-memory bytes data.

Args:
data (bytes collection): Bytes collection containing valid tar data repository (str): The repository to create tag (str): The tag to apply
import_image_from_file(filename, repository=None, tag=None, changes=None)

Like import_image(), but only supports importing from a tar file on disk.

Args:
filename (str): Full path to a tar file. repository (str): The repository to create tag (str): The tag to apply
Raises:
IOError: File does not exist.
import_image_from_stream(stream, repository=None, tag=None, changes=None)
import_image_from_url(url, repository=None, tag=None, changes=None)

Like import_image(), but only supports importing from a URL.

Args:
url (str): A URL pointing to a tar file. repository (str): The repository to create tag (str): The tag to apply
import_image_from_image(image, repository=None, tag=None, changes=None)

Like import_image(), but only supports importing from another image, like the FROM Dockerfile parameter.

Args:
image (str): Image name to import from repository (str): The repository to create tag (str): The tag to apply
inspect_image(image)

Get detailed information about an image. Similar to the docker inspect command, but only for images.

Args:
image (str): The image to inspect
Returns:
(dict): Similar to the output of docker inspect, but as a

single dict

Raises:
docker.errors.APIError
If the server returns an error.
inspect_distribution(image)

Get image digest and platform information by contacting the registry.

Args:
image (str): The image name to inspect
Returns:
(dict): A dict containing distribution data
Raises:
docker.errors.APIError
If the server returns an error.
load_image(data, quiet=None)

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

Args:
data (binary): Image data to be loaded. quiet (boolean): Suppress progress details in response.
Returns:
(generator): Progress output as JSON objects. Only available for
API version >= 1.23
Raises:
docker.errors.APIError
If the server returns an error.
prune_images(filters=None)

Delete unused images

Args:
filters (dict): Filters to process on the prune list.
Available filters: - dangling (bool): When set to true (or 1), prune only unused and untagged images.
Returns:
(dict): A dict containing a list of deleted image IDs and
the amount of disk space reclaimed in bytes.
Raises:
docker.errors.APIError
If the server returns an error.
pull(repository, tag=None, stream=False, auth_config=None, decode=False, platform=None)

Pulls an image. Similar to the docker pull command.

Args:

repository (str): The repository to pull tag (str): The tag to pull stream (bool): Stream the output as a generator 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.
decode (bool): Decode the JSON data from the server into dicts.
Only applies with stream=True

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

Returns:
(generator or str): The output
Raises:
docker.errors.APIError
If the server returns an error.

Example:

>>> for line in cli.pull('busybox', stream=True):
...     print(json.dumps(json.loads(line), indent=4))
{
    "status": "Pulling image (latest) from busybox",
    "progressDetail": {},
    "id": "e72ac664f4f0"
}
{
    "status": "Pulling image (latest) from busybox, endpoint: ...",
    "progressDetail": {},
    "id": "e72ac664f4f0"
}
push(repository, tag=None, stream=False, auth_config=None, decode=False)

Push an image or a repository to the registry. Similar to the docker push command.

Args:

repository (str): The repository to push to tag (str): An optional tag to push stream (bool): Stream the output as a blocking generator 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.
decode (bool): Decode the JSON data from the server into dicts.
Only applies with stream=True
Returns:
(generator or str): The output from the server.
Raises:
docker.errors.APIError
If the server returns an error.
Example:
>>> for line in cli.push('yourname/app', stream=True):
...   print line
{"status":"Pushing repository yourname/app (1 tags)"}
{"status":"Pushing","progressDetail":{},"id":"511136ea3c5a"}
{"status":"Image already pushed, skipping","progressDetail":{},
 "id":"511136ea3c5a"}
...
remove_image(image, force=False, noprune=False)

Remove an image. Similar to the docker rmi command.

Args:
image (str): The image to remove force (bool): Force removal of the image noprune (bool): Do not delete untagged parents
search(term)

Search for images on Docker Hub. Similar to the docker search command.

Args:
term (str): A term to search for.
Returns:
(list of dicts): The response of the search.
Raises:
docker.errors.APIError
If the server returns an error.
tag(image, repository, tag=None, force=False)

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

Args:
image (str): The image to tag repository (str): The repository to set for the tag tag (str): The tag name force (bool): Force
Returns:
(bool): True if successful
Raises:
docker.errors.APIError
If the server returns an error.

Example:

>>> client.tag('ubuntu', 'localhost:5000/ubuntu', 'latest',
               force=True)
is_file(src)
_import_image_params(repo, tag, image=None, src=None, changes=None)