Client¶
Creating a client¶
To communicate with the Docker daemon, you first need to instantiate a client. The easiest way to do that is by calling the function from_env()
. It can also be configured manually by instantiating a DockerClient
class.
-
from_env
()¶ Return a client configured from environment variables.
The environment variables used are the same as those used by the Docker command-line client. They are:
-
DOCKER_HOST
¶ The URL to the Docker host.
-
DOCKER_TLS_VERIFY
¶ Verify the host against a CA certificate.
-
DOCKER_CERT_PATH
¶ A path to a directory containing TLS certificates to use when connecting to the Docker host.
Parameters: - version (str) – The version of the API to use. Set to
auto
to automatically detect the server’s version. Default:auto
- timeout (int) – Default timeout for API calls, in seconds.
- max_pool_size (int) – The maximum number of connections to save in the pool.
- ssl_version (int) – A valid SSL version.
- assert_hostname (bool) – Verify the hostname of the server.
- environment (dict) – The environment to read environment variables
from. Default: the value of
os.environ
- credstore_env (dict) – Override environment variables when calling the credential store process.
- use_ssh_client (bool) – If set to True, an ssh connection is made via shelling out to the ssh client. Ensure the ssh client is installed and configured on the host.
Example
>>> import docker >>> client = docker.from_env()
-
Client reference¶
-
class
DockerClient
¶ A client for communicating with a Docker server.
Example
>>> import docker >>> client = docker.DockerClient(base_url='unix://var/run/docker.sock')
Parameters: - base_url (str) – URL to the Docker server. For example,
unix:///var/run/docker.sock
ortcp://127.0.0.1:1234
. - version (str) – The version of the API to use. Set to
auto
to automatically detect the server’s version. Default:1.35
- timeout (int) – Default timeout for API calls, in seconds.
- tls (bool or
TLSConfig
) – Enable TLS. PassTrue
to enable it with default options, or pass aTLSConfig
object to use custom configuration. - user_agent (str) – Set a custom user agent for requests to the server.
- credstore_env (dict) – Override environment variables when calling the credential store process.
- use_ssh_client (bool) – If set to True, an ssh connection is made via shelling out to the ssh client. Ensure the ssh client is installed and configured on the host.
- max_pool_size (int) – The maximum number of connections to save in the pool.
-
configs
¶ An object for managing configs on the server. See the configs documentation for full details.
-
containers
¶ An object for managing containers on the server. See the containers documentation for full details.
-
images
¶ An object for managing images on the server. See the images documentation for full details.
-
networks
¶ An object for managing networks on the server. See the networks documentation for full details.
-
nodes
¶ An object for managing nodes on the server. See the nodes documentation for full details.
-
plugins
¶ An object for managing plugins on the server. See the plugins documentation for full details.
-
secrets
¶ An object for managing secrets on the server. See the secrets documentation for full details.
-
services
¶ An object for managing services on the server. See the services documentation for full details.
-
swarm
¶ An object for managing a swarm on the server. See the swarm documentation for full details.
-
volumes
¶ An object for managing volumes on the server. See the volumes documentation for full details.
-
close
()¶ Closes all adapters and as such the session
-
df
()¶ Get data usage information.
Returns: A dictionary representing different resource categories and their respective data usage. Return type: (dict) Raises: docker.errors.APIError
– If the server returns an error.
-
events
()¶ Get real-time events from the server. Similar to the
docker events
command.Parameters: - since (UTC datetime or int) – Get events from this point
- until (UTC datetime or int) – Get events until this point
- filters (dict) – Filter the events by event time, container or image
- decode (bool) – If set to true, stream will be decoded into dicts on the fly. False by default.
Returns: A
docker.types.daemon.CancellableStream
generatorRaises: docker.errors.APIError
– If the server returns an error.Example
>>> for event in client.events(decode=True) ... print(event) {u'from': u'image/with:tag', u'id': u'container-id', u'status': u'start', u'time': 1423339459} ...
or
>>> events = client.events() >>> for event in events: ... print(event) >>> # and cancel from another thread >>> events.close()
-
info
()¶ Display system-wide information. Identical to the
docker info
command.Returns: The info as a dict Return type: (dict) Raises: docker.errors.APIError
– If the server returns an error.
-
login
()¶ Authenticate with a registry. Similar to the
docker login
command.Parameters: - username (str) – The registry username
- password (str) – The plaintext password
- email (str) – The email for the registry account
- registry (str) – URL to the registry. E.g.
https://index.docker.io/v1/
- reauth (bool) – Whether or not to refresh existing authentication on the Docker server.
- dockercfg_path (str) – Use a custom path for the Docker config file
(default
$HOME/.docker/config.json
if present, otherwise$HOME/.dockercfg
)
Returns: The response from the login request
Return type: (dict)
Raises: docker.errors.APIError
– If the server returns an error.
-
ping
()¶ Checks the server is responsive. An exception will be raised if it isn’t responding.
Returns: (bool) The response from the server. Raises: docker.errors.APIError
– If the server returns an error.
-
version
()¶ Returns version information from the server. Similar to the
docker version
command.Returns: The server version information Return type: (dict) Raises: docker.errors.APIError
– If the server returns an error.
- base_url (str) – URL to the Docker server. For example,