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.
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
generator- Raises:
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.