2.4.0 release

docker/api/build.py

@@ -18,7 +18,7 @@ def build(self, path=None, tag=None, quiet=False, fileobj=None,
               custom_context=False, encoding=None, pull=False,
               forcerm=False, dockerfile=None, container_limits=None,
               decode=False, buildargs=None, gzip=False, shmsize=None,
-              labels=None, cache_from=None):
+              labels=None, cache_from=None, target=None, network_mode=None):
         """
         Similar to the ``docker build`` command. Either ``path`` or ``fileobj``
         needs to be set. ``path`` can be a local path (to a directory
@@ -88,12 +88,16 @@ def build(self, path=None, tag=None, quiet=False, fileobj=None,
                 - cpusetcpus (str): CPUs in which to allow execution, e.g.,
                     ``"0-3"``, ``"0,1"``
             decode (bool): If set to ``True``, the returned stream will be
-                decoded into dicts on the fly. Default ``False``.
+                decoded into dicts on the fly. Default ``False``
             shmsize (int): Size of `/dev/shm` in bytes. The size must be
-                greater than 0. If omitted the system uses 64MB.
-            labels (dict): A dictionary of labels to set on the image.
+                greater than 0. If omitted the system uses 64MB
+            labels (dict): A dictionary of labels to set on the image
             cache_from (list): A list of images used for build cache
-                resolution.
+                resolution
+            target (str): Name of the build-stage to build in a multi-stage
+                Dockerfile
+            network_mode (str): networking mode for the run commands during
+                build
 
         Returns:
             A generator for the build output.
@@ -198,6 +202,22 @@ def build(self, path=None, tag=None, quiet=False, fileobj=None,
                     'cache_from was only introduced in API version 1.25'
                 )
 
+        if target:
+            if utils.version_gte(self._version, '1.29'):
+                params.update({'target': target})
+            else:
+                raise errors.InvalidVersion(
+                    'target was only introduced in API version 1.29'
+                )
+
+        if network_mode:
+            if utils.version_gte(self._version, '1.25'):
+                params.update({'networkmode': network_mode})
+            else:
+                raise errors.InvalidVersion(
+                    'network_mode was only introduced in API version 1.25'
+                )
+
         if context is not None:
             headers = {'Content-Type': 'application/tar'}
             if encoding:

docker/api/client.py

@@ -83,6 +83,12 @@ class APIClient(
             configuration.
         user_agent (str): Set a custom user agent for requests to the server.
     """
+
+    __attrs__ = requests.Session.__attrs__ + ['_auth_configs',
+                                              '_version',
+                                              'base_url',
+                                              'timeout']
+
     def __init__(self, base_url=None, version=None,
                  timeout=DEFAULT_TIMEOUT_SECONDS, tls=False,
                  user_agent=DEFAULT_USER_AGENT, num_pools=DEFAULT_NUM_POOLS):
@@ -248,7 +254,7 @@ def _attach_params(self, override=None):
             'stream': 1
         }
 
-    @check_resource
+    @check_resource('container')
     def _attach_websocket(self, container, params=None):
         url = self._url("/containers/{0}/attach/ws", container)
         req = requests.Request("POST", url, params=self._attach_params(params))

docker/api/container.py

@@ -10,7 +10,7 @@
 
 
 class ContainerApiMixin(object):
-    @utils.check_resource
+    @utils.check_resource('container')
     def attach(self, container, stdout=True, stderr=True,
                stream=False, logs=False):
         """
@@ -54,7 +54,7 @@ def attach(self, container, stdout=True, stderr=True,
 
         return self._read_from_socket(response, stream)
 
-    @utils.check_resource
+    @utils.check_resource('container')
     def attach_socket(self, container, params=None, ws=False):
         """
         Like ``attach``, but returns the underlying socket-like object for the
@@ -93,7 +93,7 @@ def attach_socket(self, container, params=None, ws=False):
             )
         )
 
-    @utils.check_resource
+    @utils.check_resource('container')
     def commit(self, container, repository=None, tag=None, message=None,
                author=None, changes=None, conf=None):
         """
@@ -195,7 +195,7 @@ def containers(self, quiet=False, all=False, trunc=False, latest=False,
                 x['Id'] = x['Id'][:12]
         return res
 
-    @utils.check_resource
+    @utils.check_resource('container')
     def copy(self, container, resource):
         """
         Identical to the ``docker cp`` command. Get files/folders from the
@@ -238,7 +238,7 @@ def create_container(self, image, command=None, hostname=None, user=None,
                          memswap_limit=None, cpuset=None, host_config=None,
                          mac_address=None, labels=None, volume_driver=None,
                          stop_signal=None, networking_config=None,
-                         healthcheck=None, stop_timeout=None):
+                         healthcheck=None, stop_timeout=None, runtime=None):
         """
         Creates a container. Parameters are similar to those for the ``docker
         run`` command except it doesn't support the attach options (``-a``).
@@ -391,8 +391,6 @@ def create_container(self, image, command=None, hostname=None, user=None,
                 ``{"PASSWORD": "xxx"}``.
             dns (:py:class:`list`): DNS name servers. Deprecated since API
                 version 1.10. Use ``host_config`` instead.
-            dns_opt (:py:class:`list`): Additional options to be added to the
-                container's ``resolv.conf`` file
             volumes (str or list): List of paths inside the container to use
                 as volumes.
             volumes_from (:py:class:`list`): List of container names or Ids to
@@ -417,6 +415,9 @@ def create_container(self, image, command=None, hostname=None, user=None,
                 Default: 10
             networking_config (dict): A networking configuration generated
                 by :py:meth:`create_networking_config`.
+            runtime (str): Runtime to use with this container.
+            healthcheck (dict): Specify a test to perform to check that the
+                container is healthy.
 
         Returns:
             A dictionary with an image 'Id' key and a 'Warnings' key.
@@ -441,7 +442,7 @@ def create_container(self, image, command=None, hostname=None, user=None,
             network_disabled, entrypoint, cpu_shares, working_dir, domainname,
             memswap_limit, cpuset, host_config, mac_address, labels,
             volume_driver, stop_signal, networking_config, healthcheck,
-            stop_timeout
+            stop_timeout, runtime
         )
         return self.create_container_from_config(config, name)
 
@@ -495,6 +496,8 @@ def create_host_config(self, *args, **kwargs):
                 to have read-write access to the host's ``/dev/sda`` via a
                 node named ``/dev/xvda`` inside the container.
             dns (:py:class:`list`): Set custom DNS servers.
+            dns_opt (:py:class:`list`): Additional options to be added to the
+                container's ``resolv.conf`` file
             dns_search (:py:class:`list`): DNS search domains.
             extra_hosts (dict): Addtional hostnames to resolve inside the
                 container, as a mapping of hostname to IP address.
@@ -576,6 +579,7 @@ def create_host_config(self, *args, **kwargs):
                 values are: ``host``
             volumes_from (:py:class:`list`): List of container names or IDs to
                 get volumes from.
+            runtime (str): Runtime to use with this container.
 
 
         Returns:
@@ -659,7 +663,7 @@ def create_endpoint_config(self, *args, **kwargs):
         """
         return EndpointConfig(self._version, *args, **kwargs)
 
-    @utils.check_resource
+    @utils.check_resource('container')
     def diff(self, container):
         """
         Inspect changes on a container's filesystem.
@@ -678,7 +682,7 @@ def diff(self, container):
             self._get(self._url("/containers/{0}/changes", container)), True
         )
 
-    @utils.check_resource
+    @utils.check_resource('container')
     def export(self, container):
         """
         Export the contents of a filesystem as a tar archive.
@@ -699,7 +703,7 @@ def export(self, container):
         self._raise_for_status(res)
         return res.raw
 
-    @utils.check_resource
+    @utils.check_resource('container')
     @utils.minimum_version('1.20')
     def get_archive(self, container, path):
         """
@@ -730,7 +734,7 @@ def get_archive(self, container, path):
             utils.decode_json_header(encoded_stat) if encoded_stat else None
         )
 
-    @utils.check_resource
+    @utils.check_resource('container')
     def inspect_container(self, container):
         """
         Identical to the `docker inspect` command, but only for containers.
@@ -750,7 +754,7 @@ def inspect_container(self, container):
             self._get(self._url("/containers/{0}/json", container)), True
         )
 
-    @utils.check_resource
+    @utils.check_resource('container')
     def kill(self, container, signal=None):
         """
         Kill a container or send a signal to a container.
@@ -773,7 +777,7 @@ def kill(self, container, signal=None):
 
         self._raise_for_status(res)
 
-    @utils.check_resource
+    @utils.check_resource('container')
     def logs(self, container, stdout=True, stderr=True, stream=False,
              timestamps=False, tail='all', since=None, follow=None):
         """
@@ -825,6 +829,11 @@ def logs(self, container, stdout=True, stderr=True, stream=False,
                         params['since'] = utils.datetime_to_timestamp(since)
                     elif (isinstance(since, int) and since > 0):
                         params['since'] = since
+                    else:
+                        raise errors.InvalidArgument(
+                            'since value should be datetime or int, not {}'.
+                            format(type(since))
+                        )
             url = self._url("/containers/{0}/logs", container)
             res = self._get(url, params=params, stream=stream)
             return self._get_result(container, stream, res)
@@ -836,7 +845,7 @@ def logs(self, container, stdout=True, stderr=True, stream=False,
             logs=True
         )
 
-    @utils.check_resource
+    @utils.check_resource('container')
     def pause(self, container):
         """
         Pauses all processes within a container.
@@ -852,7 +861,7 @@ def pause(self, container):
         res = self._post(url)
         self._raise_for_status(res)
 
-    @utils.check_resource
+    @utils.check_resource('container')
     def port(self, container, private_port):
         """
         Lookup the public-facing port that is NAT-ed to ``private_port``.
@@ -901,7 +910,7 @@ def port(self, container, private_port):
 
         return h_ports
 
-    @utils.check_resource
+    @utils.check_resource('container')
     @utils.minimum_version('1.20')
     def put_archive(self, container, path, data):
         """
@@ -949,7 +958,7 @@ def prune_containers(self, filters=None):
         url = self._url('/containers/prune')
         return self._result(self._post(url, params=params), True)
 
-    @utils.check_resource
+    @utils.check_resource('container')
     def remove_container(self, container, v=False, link=False, force=False):
         """
         Remove a container. Similar to the ``docker rm`` command.
@@ -973,7 +982,7 @@ def remove_container(self, container, v=False, link=False, force=False):
         self._raise_for_status(res)
 
     @utils.minimum_version('1.17')
-    @utils.check_resource
+    @utils.check_resource('container')
     def rename(self, container, name):
         """
         Rename a container. Similar to the ``docker rename`` command.
@@ -991,7 +1000,7 @@ def rename(self, container, name):
         res = self._post(url, params=params)
         self._raise_for_status(res)
 
-    @utils.check_resource
+    @utils.check_resource('container')
     def resize(self, container, height, width):
         """
         Resize the tty session.
@@ -1010,7 +1019,7 @@ def resize(self, container, height, width):
         res = self._post(url, params=params)
         self._raise_for_status(res)
 
-    @utils.check_resource
+    @utils.check_resource('container')
     def restart(self, container, timeout=10):
         """
         Restart a container. Similar to the ``docker restart`` command.
@@ -1031,7 +1040,7 @@ def restart(self, container, timeout=10):
         res = self._post(url, params=params)
         self._raise_for_status(res)
 
-    @utils.check_resource
+    @utils.check_resource('container')
     def start(self, container, *args, **kwargs):
         """
         Start a container. Similar to the ``docker start`` command, but
@@ -1070,7 +1079,7 @@ def start(self, container, *args, **kwargs):
         self._raise_for_status(res)
 
     @utils.minimum_version('1.17')
-    @utils.check_resource
+    @utils.check_resource('container')
     def stats(self, container, decode=None, stream=True):
         """
         Stream statistics for a specific container. Similar to the
@@ -1096,7 +1105,7 @@ def stats(self, container, decode=None, stream=True):
             return self._result(self._get(url, params={'stream': False}),
                                 json=True)
 
-    @utils.check_resource
+    @utils.check_resource('container')
     def stop(self, container, timeout=10):
         """
         Stops a container. Similar to the ``docker stop`` command.
@@ -1117,7 +1126,7 @@ def stop(self, container, timeout=10):
                          timeout=(timeout + (self.timeout or 0)))
         self._raise_for_status(res)
 
-    @utils.check_resource
+    @utils.check_resource('container')
     def top(self, container, ps_args=None):
         """
         Display the running processes of a container.
@@ -1139,7 +1148,7 @@ def top(self, container, ps_args=None):
             params['ps_args'] = ps_args
         return self._result(self._get(u, params=params), True)
 
-    @utils.check_resource
+    @utils.check_resource('container')
     def unpause(self, container):
         """
         Unpause all processes within a container.
@@ -1152,7 +1161,7 @@ def unpause(self, container):
         self._raise_for_status(res)
 
     @utils.minimum_version('1.22')
-    @utils.check_resource
+    @utils.check_resource('container')
     def update_container(
         self, container, blkio_weight=None, cpu_period=None, cpu_quota=None,
         cpu_shares=None, cpuset_cpus=None, cpuset_mems=None, mem_limit=None,
@@ -1217,7 +1226,7 @@ def update_container(
         res = self._post_json(url, data=data)
         return self._result(res, True)
 
-    @utils.check_resource
+    @utils.check_resource('container')
     def wait(self, container, timeout=None):
         """
         Block until a container stops, then return its exit code. Similar to

docker/api/exec_api.py

@@ -6,7 +6,7 @@
 
 class ExecApiMixin(object):
     @utils.minimum_version('1.15')
-    @utils.check_resource
+    @utils.check_resource('container')
     def exec_create(self, container, cmd, stdout=True, stderr=True,
                     stdin=False, tty=False, privileged=False, user='',
                     environment=None):
@@ -110,7 +110,7 @@ def exec_resize(self, exec_id, height=None, width=None):
         self._raise_for_status(res)
 
     @utils.minimum_version('1.15')
-    @utils.check_resource
+    @utils.check_resource('exec_id')
     def exec_start(self, exec_id, detach=False, tty=False, stream=False,
                    socket=False):
         """