diff options
author | Ben Firshman <ben@firshman.co.uk> | 2016-11-07 17:56:02 -0800 |
---|---|---|
committer | Ben Firshman <ben@firshman.co.uk> | 2016-11-22 17:05:43 +0000 |
commit | 1984f68730512a1c07017118f4e229c7949ff8a8 (patch) | |
tree | 00768c0a70d67b4a221333a8566534e8e58a008f /docker/client.py | |
parent | f32c0c170917518b7e224adf8627e95b5e620a91 (diff) | |
download | docker-py-1984f68730512a1c07017118f4e229c7949ff8a8.tar.gz |
Add new user-focused API
See #1086
Signed-off-by: Ben Firshman <ben@firshman.co.uk>
Diffstat (limited to 'docker/client.py')
-rw-r--r-- | docker/client.py | 157 |
1 files changed, 157 insertions, 0 deletions
diff --git a/docker/client.py b/docker/client.py new file mode 100644 index 0000000..6c5ae40 --- /dev/null +++ b/docker/client.py @@ -0,0 +1,157 @@ +from .api.client import APIClient +from .models.containers import ContainerCollection +from .models.images import ImageCollection +from .models.networks import NetworkCollection +from .models.nodes import NodeCollection +from .models.services import ServiceCollection +from .models.swarm import Swarm +from .models.volumes import VolumeCollection +from .utils import kwargs_from_env + + +class Client(object): + """ + A client for communicating with a Docker server. + + Example: + + >>> import docker + >>> client = Client(base_url='unix://var/run/docker.sock') + + Args: + base_url (str): URL to the Docker server. For example, + ``unix:///var/run/docker.sock`` or ``tcp://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.24`` + timeout (int): Default timeout for API calls, in seconds. + tls (bool or :py:class:`~docker.tls.TLSConfig`): Enable TLS. Pass + ``True`` to enable it with default options, or pass a + :py:class:`~docker.tls.TLSConfig` object to use custom + configuration. + user_agent (str): Set a custom user agent for requests to the server. + """ + def __init__(self, *args, **kwargs): + self.api = APIClient(*args, **kwargs) + + @classmethod + def from_env(cls, **kwargs): + """ + 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: + + .. envvar:: DOCKER_HOST + + The URL to the Docker host. + + .. envvar:: DOCKER_TLS_VERIFY + + Verify the host against a CA certificate. + + .. envvar:: DOCKER_CERT_PATH + + A path to a directory containing TLS certificates to use when + connecting to the Docker host. + + Args: + version (str): The version of the API to use. Set to ``auto`` to + automatically detect the server's version. Default: ``1.24`` + timeout (int): Default timeout for API calls, in seconds. + 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`` + + Example: + + >>> import docker + >>> client = docker.from_env() + + .. _`SSL version`: + https://docs.python.org/3.5/library/ssl.html#ssl.PROTOCOL_TLSv1 + """ + timeout = kwargs.pop('timeout', None) + version = kwargs.pop('version', None) + return cls(timeout=timeout, version=version, + **kwargs_from_env(**kwargs)) + + # Resources + @property + def containers(self): + """ + An object for managing containers on the server. See the + :doc:`containers documentation <containers>` for full details. + """ + return ContainerCollection(client=self) + + @property + def images(self): + """ + An object for managing images on the server. See the + :doc:`images documentation <images>` for full details. + """ + return ImageCollection(client=self) + + @property + def networks(self): + """ + An object for managing networks on the server. See the + :doc:`networks documentation <networks>` for full details. + """ + return NetworkCollection(client=self) + + @property + def nodes(self): + """ + An object for managing nodes on the server. See the + :doc:`nodes documentation <nodes>` for full details. + """ + return NodeCollection(client=self) + + @property + def services(self): + """ + An object for managing services on the server. See the + :doc:`services documentation <services>` for full details. + """ + return ServiceCollection(client=self) + + @property + def swarm(self): + """ + An object for managing a swarm on the server. See the + :doc:`swarm documentation <swarm>` for full details. + """ + return Swarm(client=self) + + @property + def volumes(self): + """ + An object for managing volumes on the server. See the + :doc:`volumes documentation <volumes>` for full details. + """ + return VolumeCollection(client=self) + + # Top-level methods + def events(self, *args, **kwargs): + return self.api.events(*args, **kwargs) + events.__doc__ = APIClient.events.__doc__ + + def info(self, *args, **kwargs): + return self.api.info(*args, **kwargs) + info.__doc__ = APIClient.info.__doc__ + + def login(self, *args, **kwargs): + return self.api.login(*args, **kwargs) + login.__doc__ = APIClient.login.__doc__ + + def ping(self, *args, **kwargs): + return self.api.ping(*args, **kwargs) + ping.__doc__ = APIClient.ping.__doc__ + + def version(self, *args, **kwargs): + return self.api.version(*args, **kwargs) + version.__doc__ = APIClient.version.__doc__ + +from_env = Client.from_env |