xd.docker.client module¶

Module containing DockerClient and associated exceptions.

class xd.docker.client.DockerClient(host=None)[source]¶

Bases: object

Docker client.

A DockerClient instance is used to communicate with Docker daemon (or something else that is speaking Docker Remote API).

Parameters:	host (`Optional`[`str`]) – URL to Docker daemon socket to connect to.
Example:

Connect to docker daemon on localhost TCP socket:

>>> docker = DockerClient('tcp://127.0.0.1:2375')

Connect to docker daemon on UNIX domain socket:

>>> docker = DockerClient('unix:///var/run/docker.sock')

version()[source]¶

Get Docker Remote API version.

Raises:	`ServerError` – Server error.
Return type:	`Tuple`[`int`, `int`]
Returns:	Major/minor version number of Docker daemon (Docker Remote API).

ping()[source]¶

Ping the docker server.

Raises:	`ServerError` – Server error.
Return type:	None

containers(only_running=True)[source]¶

Get list of containers.

By default, only running containers are returned.

Keyword Arguments:
	only_running – List only running containers (if True), or all containers (if False).
Raises:	`ClientError` – Bad parameter. `ServerError` – Server error.
Return type:	`List`[`Container`]
Returns:	List of containers.

images()[source]¶

Get list of images.

Images returned does only contain partial information. To obtain detailed information, use image_inspect or Image.inspect on the Image in question.

Raises:	`ServerError` – Server error.
Return type:	`List`[`Image`]
Returns:	List of images.

image_inspect(name)[source]¶

Get image with low-level information.

Get low-level information of a named image. Returns Image instance with the information.

Parameters:	name (`str`) – name of image.
Return type:	`Image`

image_build(context, output=('error', 'stream', 'status'), dockerfile=None, tag=None, cache=True, pull=None, rm=None, force_rm=None, host_config=None, registry_config=None, buildargs=None)[source]¶

Build an image from a Dockerfile.

Build image from a given context or stand-alone Dockerfile.

Parameters:

context (str) – path to directory containing build context, or path to a stand-alone Dockerfile.
output – tuple/list of with type of output information to allow (Default: (‘stream’, ‘status’, ‘error’)).
dockerfile (Optional[str]) – path to dockerfile in build context.
tag (Union[Repository, str, None]) – repository name and tag to be applied to the resulting image.
cache (bool) – use the cache when building the image (default: True).
pull (Optional[bool]) – attempt to pull the image even if an older image exists locally (default: False).
rm (Optional[bool]) – False/True. Remove intermediate containers after a successful build (default: True).
force_rm (Optional[bool]) – False/True. Always remove intermediate containers after build (default: False).
host_config (Optional[HostConfig]) – HostConfig instance.
registry_config (Optional[RegistryAuthConfig]) – RegistryAuthConfig instance.
buildargs (Optional[Dict[str, str]]) – build-time environment variables.

image_pull(name, registry_auth=None, output=('error', 'stream', 'status'))[source]¶

Pull image.

Create an image by pulling it from a registry.

Parameters:	name – name of the image to pull. output – tuple/list of with type of output information to allow (Default: (‘stream’, ‘status’, ‘error’)).

image_remove(name)[source]¶

Remove an image.

Remove the image name from the filesystem.

Parameters:	name – name of the image to remove.

image_tag(image, tag=None, force=None)[source]¶

Tag an image.

Add tag to an existing image.

Parameters:	image – image to add tag to. tag (`Union`[`Repository`, `str`, `None`]) – repository name and optionally tag. force (`Optional`[`bool`]) – force creation of tag.

container_create(config, name=None, mounts=None, host_config=None, pull=True)[source]¶

Create a new container.

Create a new container based on existing image.

Parameters:	config (`ContainerConfig`) – ContainerConfig instance. name (`Union`[`ContainerName`, `str`, `None`]) – name to assign to container. mounts (`Optional`[`Sequence`[`VolumeMount`]]) – mount points in the container (list of strings). host_config (`Optional`[`HostConfig`]) – HostConfig instance. pull (`bool`) – Pull image if needed.

container_remove(container, force=None, volumes=None)[source]¶

Remove a container.

Remove a container and (optionally) the associated volumes.

Parameters:	container (`Union`[`Container`, `ContainerName`, `str`]) – The container to remove (id or name). force (`Optional`[`bool`]) – Kill then remove the container. volumes (`Optional`[`bool`]) – Remove the volumes associated to the container.

container_start(container)[source]¶

Start a container.

Parameters:	container (`Union`[`Container`, `ContainerName`, `str`]) – The container to start (id or name).
Returns:	True if container was started. False if container was already started.

container_wait(container)[source]¶

Block until container stops.

Block until container stops, then returns the exit code.

Parameters:	container (`Union`[`Container`, `ContainerName`, `str`]) – The container to remove (id or name).
Return type:	`int`
Returns:	Container exit code.

container_stop(container, timeout=None)[source]¶

Stop container.

Stop the container, and optionally killing the container after a timeout.

Parameters:	container (`Union`[`Container`, `ContainerName`, `str`]) – The container to remove (id or name). timeout (`Optional`[`int`]) – Number of seconds to wait before killing the container.
Returns:	True if container was stopped. False if container was already stopped.

container_restart(container, timeout=None)[source]¶

Restart container.

Restart the container, and optionally killing the container after a timeout waiting for the container to stop.

Parameters:	container (`Union`[`Container`, `ContainerName`, `str`]) – The container to remove (id or name). timeout (`Optional`[`int`]) – Number of seconds to wait before killing the container.

container_kill(container, signal=None)[source]¶

Kill container.

Send signal to container, and (maybe) wait for the container to exit.

Note: Prior to Docker version 1.8, kill succeeds (without actually doing anything) when run on existing but stopped containers. Docker 1.8 and newer fails out with a ServerError exception.

Parameters:	container (`Union`[`Container`, `ContainerName`, `str`]) – The container to remove (id or name). signal (`Union`[`int`, `str`, `None`]) – Signal to send to container.