Merge tag 'upstream/4.1.0'

Upstream version 4.1.0

11 files changed, 356 insertions, 152 deletions

diff --git a/docker/api/build.py b/docker/api/build.py
index 419255f..365129a 100644
--- a/docker/api/build.py
+++ b/docker/api/build.py
@@ -19,7 +19,8 @@ class BuildApiMixin(object):
               forcerm=False, dockerfile=None, container_limits=None,
               decode=False, buildargs=None, gzip=False, shmsize=None,
               labels=None, cache_from=None, target=None, network_mode=None,
-              squash=None, extra_hosts=None, platform=None, isolation=None):
+              squash=None, extra_hosts=None, platform=None, isolation=None,
+              use_config_proxy=True):
         """
         Similar to the ``docker build`` command. Either ``path`` or ``fileobj``
         needs to be set. ``path`` can be a local path (to a directory
@@ -103,6 +104,10 @@ class BuildApiMixin(object):
             platform (str): Platform in the format ``os[/arch[/variant]]``
             isolation (str): Isolation technology used during build.
                 Default: `None`.
+            use_config_proxy (bool): If ``True``, and if the docker client
+                configuration file (``~/.docker/config.json`` by default)
+                contains a proxy configuration, the corresponding environment
+                variables will be set in the container being built.
 
         Returns:
             A generator for the build output.
@@ -116,6 +121,7 @@ class BuildApiMixin(object):
         remote = context = None
         headers = {}
         container_limits = container_limits or {}
+        buildargs = buildargs or {}
         if path is None and fileobj is None:
             raise TypeError("Either path or fileobj needs to be provided.")
         if gzip and encoding is not None:
@@ -168,6 +174,10 @@ class BuildApiMixin(object):
         }
         params.update(container_limits)
 
+        if use_config_proxy:
+            proxy_args = self._proxy_configs.get_environment()
+            for k, v in proxy_args.items():
+                buildargs.setdefault(k, v)
         if buildargs:
             params.update({'buildargs': json.dumps(buildargs)})
 
@@ -286,30 +296,21 @@ class BuildApiMixin(object):
 
         # If we don't have any auth data so far, try reloading the config
         # file one more time in case anything showed up in there.
-        if not self._auth_configs:
+        if not self._auth_configs or self._auth_configs.is_empty:
             log.debug("No auth config in memory - loading from filesystem")
-            self._auth_configs = auth.load_config()
+            self._auth_configs = auth.load_config(
+                credstore_env=self.credstore_env
+            )
 
         # Send the full auth configuration (if any exists), since the build
         # could use any (or all) of the registries.
         if self._auth_configs:
-            auth_data = {}
-            if self._auth_configs.get('credsStore'):
-                # Using a credentials store, we need to retrieve the
-                # credentials for each registry listed in the config.json file
-                # Matches CLI behavior: https://github.com/docker/docker/blob/
-                # 67b85f9d26f1b0b2b240f2d794748fac0f45243c/cliconfig/
-                # credentials/native_store.go#L68-L83
-                for registry in self._auth_configs.get('auths', {}).keys():
-                    auth_data[registry] = auth.resolve_authconfig(
-                        self._auth_configs, registry,
-                        credstore_env=self.credstore_env,
-                    )
-            else:
-                auth_data = self._auth_configs.get('auths', {}).copy()
-                # See https://github.com/docker/docker-py/issues/1683
-                if auth.INDEX_NAME in auth_data:
-                    auth_data[auth.INDEX_URL] = auth_data[auth.INDEX_NAME]
+            auth_data = self._auth_configs.get_all_credentials()
+
+            # See https://github.com/docker/docker-py/issues/1683
+            if (auth.INDEX_URL not in auth_data and
+                    auth.INDEX_NAME in auth_data):
+                auth_data[auth.INDEX_URL] = auth_data.get(auth.INDEX_NAME, {})
 
             log.debug(
                 'Sending auth config ({0})'.format(
@@ -317,9 +318,10 @@ class BuildApiMixin(object):
                 )
             )
 
-            headers['X-Registry-Config'] = auth.encode_header(
-                auth_data
-            )
+            if auth_data:
+                headers['X-Registry-Config'] = auth.encode_header(
+                    auth_data
+                )
         else:
             log.debug('No auth config found')
 
@@ -331,7 +333,14 @@ def process_dockerfile(dockerfile, path):
     abs_dockerfile = dockerfile
     if not os.path.isabs(dockerfile):
         abs_dockerfile = os.path.join(path, dockerfile)
-
+        if constants.IS_WINDOWS_PLATFORM and path.startswith(
+                constants.WINDOWS_LONGPATH_PREFIX):
+            abs_dockerfile = '{}{}'.format(
+                constants.WINDOWS_LONGPATH_PREFIX,
+                os.path.normpath(
+                    abs_dockerfile[len(constants.WINDOWS_LONGPATH_PREFIX):]
+                )
+            )
     if (os.path.splitdrive(path)[0] != os.path.splitdrive(abs_dockerfile)[0] or
             os.path.relpath(abs_dockerfile, path).startswith('..')):
         # Dockerfile not in context - read data to insert into tar later
diff --git a/docker/api/client.py b/docker/api/client.py
index 91da1c8..35dc84e 100644
--- a/docker/api/client.py
+++ b/docker/api/client.py
@@ -22,20 +22,26 @@ from .volume import VolumeApiMixin
 from .. import auth
 from ..constants import (
     DEFAULT_TIMEOUT_SECONDS, DEFAULT_USER_AGENT, IS_WINDOWS_PLATFORM,
-    DEFAULT_DOCKER_API_VERSION, STREAM_HEADER_SIZE_BYTES, DEFAULT_NUM_POOLS,
-    MINIMUM_DOCKER_API_VERSION
+    DEFAULT_DOCKER_API_VERSION, MINIMUM_DOCKER_API_VERSION,
+    STREAM_HEADER_SIZE_BYTES, DEFAULT_NUM_POOLS_SSH, DEFAULT_NUM_POOLS
 )
 from ..errors import (
     DockerException, InvalidVersion, TLSParameterError,
     create_api_error_from_http_exception
 )
 from ..tls import TLSConfig
-from ..transport import SSLAdapter, UnixAdapter
+from ..transport import SSLHTTPAdapter, UnixHTTPAdapter
 from ..utils import utils, check_resource, update_headers, config
-from ..utils.socket import frames_iter, socket_raw_iter
+from ..utils.socket import frames_iter, consume_socket_output, demux_adaptor
 from ..utils.json_stream import json_stream
+from ..utils.proxy import ProxyConfig
 try:
-    from ..transport import NpipeAdapter
+    from ..transport import NpipeHTTPAdapter
+except ImportError:
+    pass
+
+try:
+    from ..transport import SSHHTTPAdapter
 except ImportError:
     pass
 
@@ -76,7 +82,7 @@ class APIClient(
         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.30``
+            automatically detect the server's version. Default: ``1.35``
         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
@@ -95,7 +101,7 @@ class APIClient(
 
     def __init__(self, base_url=None, version=None,
                  timeout=DEFAULT_TIMEOUT_SECONDS, tls=False,
-                 user_agent=DEFAULT_USER_AGENT, num_pools=DEFAULT_NUM_POOLS,
+                 user_agent=DEFAULT_USER_AGENT, num_pools=None,
                  credstore_env=None):
         super(APIClient, self).__init__()
 
@@ -109,16 +115,29 @@ class APIClient(
         self.headers['User-Agent'] = user_agent
 
         self._general_configs = config.load_general_config()
+
+        proxy_config = self._general_configs.get('proxies', {})
+        try:
+            proxies = proxy_config[base_url]
+        except KeyError:
+            proxies = proxy_config.get('default', {})
+
+        self._proxy_configs = ProxyConfig.from_dict(proxies)
+
         self._auth_configs = auth.load_config(
-            config_dict=self._general_configs
+            config_dict=self._general_configs, credstore_env=credstore_env,
         )
         self.credstore_env = credstore_env
 
         base_url = utils.parse_host(
             base_url, IS_WINDOWS_PLATFORM, tls=bool(tls)
         )
+        # SSH has a different default for num_pools to all other adapters
+        num_pools = num_pools or DEFAULT_NUM_POOLS_SSH if \
+            base_url.startswith('ssh://') else DEFAULT_NUM_POOLS
+
         if base_url.startswith('http+unix://'):
-            self._custom_adapter = UnixAdapter(
+            self._custom_adapter = UnixHTTPAdapter(
                 base_url, timeout, pool_connections=num_pools
             )
             self.mount('http+docker://', self._custom_adapter)
@@ -132,7 +151,7 @@ class APIClient(
                     'The npipe:// protocol is only supported on Windows'
                 )
             try:
-                self._custom_adapter = NpipeAdapter(
+                self._custom_adapter = NpipeHTTPAdapter(
                     base_url, timeout, pool_connections=num_pools
                 )
             except NameError:
@@ -141,12 +160,25 @@ class APIClient(
                 )
             self.mount('http+docker://', self._custom_adapter)
             self.base_url = 'http+docker://localnpipe'
+        elif base_url.startswith('ssh://'):
+            try:
+                self._custom_adapter = SSHHTTPAdapter(
+                    base_url, timeout, pool_connections=num_pools
+                )
+            except NameError:
+                raise DockerException(
+                    'Install paramiko package to enable ssh:// support'
+                )
+            self.mount('http+docker://ssh', self._custom_adapter)
+            self._unmount('http://', 'https://')
+            self.base_url = 'http+docker://ssh'
         else:
             # Use SSLAdapter for the ability to specify SSL version
             if isinstance(tls, TLSConfig):
                 tls.configure_client(self)
             elif tls:
-                self._custom_adapter = SSLAdapter(pool_connections=num_pools)
+                self._custom_adapter = SSLHTTPAdapter(
+                    pool_connections=num_pools)
                 self.mount('https://', self._custom_adapter)
             self.base_url = base_url
 
@@ -279,6 +311,8 @@ class APIClient(
         self._raise_for_status(response)
         if self.base_url == "http+docker://localnpipe":
             sock = response.raw._fp.fp.raw.sock
+        elif self.base_url.startswith('http+docker://ssh'):
+            sock = response.raw._fp.fp.channel
         elif six.PY3:
             sock = response.raw._fp.fp.raw
             if self.base_url.startswith("https://"):
@@ -362,19 +396,23 @@ class APIClient(
         for out in response.iter_content(chunk_size, decode):
             yield out
 
-    def _read_from_socket(self, response, stream, tty=False):
+    def _read_from_socket(self, response, stream, tty=True, demux=False):
         socket = self._get_raw_response_socket(response)
 
-        gen = None
-        if tty is False:
-            gen = frames_iter(socket)
+        gen = frames_iter(socket, tty)
+
+        if demux:
+            # The generator will output tuples (stdout, stderr)
+            gen = (demux_adaptor(*frame) for frame in gen)
         else:
-            gen = socket_raw_iter(socket)
+            # The generator will output strings
+            gen = (data for (_, data) in gen)
 
         if stream:
             return gen
         else:
-            return six.binary_type().join(gen)
+            # Wait for all the frames, concatenate them, and return the result
+            return consume_socket_output(gen, demux=demux)
 
     def _disable_socket_timeout(self, socket):
         """ Depending on the combination of python version and whether we're
@@ -457,4 +495,6 @@ class APIClient(
         Returns:
             None
         """
-        self._auth_configs = auth.load_config(dockercfg_path)
+        self._auth_configs = auth.load_config(
+            dockercfg_path, credstore_env=self.credstore_env
+        )
diff --git a/docker/api/config.py b/docker/api/config.py
index 767bef2..93e5168 100644
--- a/docker/api/config.py
+++ b/docker/api/config.py
@@ -42,7 +42,7 @@ class ConfigApiMixin(object):
             Retrieve config metadata
 
             Args:
-                id (string): Full ID of the config to remove
+                id (string): Full ID of the config to inspect
 
             Returns (dict): A dictionary of metadata
 
diff --git a/docker/api/container.py b/docker/api/container.py
index d4f75f5..45bd352 100644
--- a/docker/api/container.py
+++ b/docker/api/container.py
@@ -1,19 +1,21 @@
-import six
 from datetime import datetime
 
+import six
+
 from .. import errors
 from .. import utils
 from ..constants import DEFAULT_DATA_CHUNK_SIZE
-from ..types import (
-    CancellableStream, ContainerConfig, EndpointConfig, HostConfig,
-    NetworkingConfig
-)
+from ..types import CancellableStream
+from ..types import ContainerConfig
+from ..types import EndpointConfig
+from ..types import HostConfig
+from ..types import NetworkingConfig
 
 
 class ContainerApiMixin(object):
     @utils.check_resource('container')
     def attach(self, container, stdout=True, stderr=True,
-               stream=False, logs=False):
+               stream=False, logs=False, demux=False):
         """
         Attach to a container.
 
@@ -28,11 +30,15 @@ class ContainerApiMixin(object):
             stream (bool): Return container output progressively as an iterator
                 of strings, rather than a single string.
             logs (bool): Include the container's previous output.
+            demux (bool): Keep stdout and stderr separate.
 
         Returns:
-            By default, the container's output as a single string.
+            By default, the container's output as a single string (two if
+            ``demux=True``: one for stdout and one for stderr).
 
-            If ``stream=True``, an iterator of output strings.
+            If ``stream=True``, an iterator of output strings. If
+            ``demux=True``, two iterators are returned: one for stdout and one
+            for stderr.
 
         Raises:
             :py:class:`docker.errors.APIError`
@@ -54,8 +60,7 @@ class ContainerApiMixin(object):
         response = self._post(u, headers=headers, params=params, stream=True)
 
         output = self._read_from_socket(
-            response, stream, self._check_is_tty(container)
-        )
+            response, stream, self._check_is_tty(container), demux=demux)
 
         if stream:
             return CancellableStream(output, response)
@@ -169,7 +174,8 @@ class ContainerApiMixin(object):
                 - `exited` (int): Only containers with specified exit code
                 - `status` (str): One of ``restarting``, ``running``,
                     ``paused``, ``exited``
-                - `label` (str): format either ``"key"`` or ``"key=value"``
+                - `label` (str|list): format either ``"key"``, ``"key=value"``
+                    or a list of such.
                 - `id` (str): The id of the container.
                 - `name` (str): The name of the container.
                 - `ancestor` (str): Filter by container ancestor. Format of
@@ -218,7 +224,8 @@ class ContainerApiMixin(object):
                          working_dir=None, domainname=None, host_config=None,
                          mac_address=None, labels=None, stop_signal=None,
                          networking_config=None, healthcheck=None,
-                         stop_timeout=None, runtime=None):
+                         stop_timeout=None, runtime=None,
+                         use_config_proxy=True):
         """
         Creates a container. Parameters are similar to those for the ``docker
         run`` command except it doesn't support the attach options (``-a``).
@@ -387,6 +394,10 @@ class ContainerApiMixin(object):
             runtime (str): Runtime to use with this container.
             healthcheck (dict): Specify a test to perform to check that the
                 container is healthy.
+            use_config_proxy (bool): If ``True``, and if the docker client
+                configuration file (``~/.docker/config.json`` by default)
+                contains a proxy configuration, the corresponding environment
+                variables will be set in the container being created.
 
         Returns:
             A dictionary with an image 'Id' key and a 'Warnings' key.
@@ -400,6 +411,14 @@ class ContainerApiMixin(object):
         if isinstance(volumes, six.string_types):
             volumes = [volumes, ]
 
+        if isinstance(environment, dict):
+            environment = utils.utils.format_environment(environment)
+
+        if use_config_proxy:
+            environment = self._proxy_configs.inject_proxy_environment(
+                environment
+            ) or None
+
         config = self.create_container_config(
             image, command, hostname, user, detach, stdin_open, tty,
             ports, environment, volumes,
@@ -465,30 +484,26 @@ class ContainerApiMixin(object):
             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
+            extra_hosts (dict): Additional hostnames to resolve inside the
                 container, as a mapping of hostname to IP address.
             group_add (:py:class:`list`): List of additional group names and/or
                 IDs that the container process will run as.
             init (bool): Run an init inside the container that forwards
                 signals and reaps processes
-            init_path (str): Path to the docker-init binary
             ipc_mode (str): Set the IPC mode for the container.
-            isolation (str): Isolation technology to use. Default: `None`.
-            links (dict or list of tuples): Either a dictionary mapping name
-                to alias or as a list of ``(name, alias)`` tuples.
-            log_config (dict): Logging configuration, as a dictionary with
-                keys:
-
-                - ``type`` The logging driver name.
-                - ``config`` A dictionary of configuration for the logging
-                  driver.
-
+            isolation (str): Isolation technology to use. Default: ``None``.
+            links (dict): Mapping of links using the
+                ``{'container': 'alias'}`` format. The alias is optional.
+                Containers declared in this dict will be linked to the new
+                container using the provided alias. Default: ``None``.
+            log_config (LogConfig): Logging configuration
             lxc_conf (dict): LXC config.
             mem_limit (float or str): Memory limit. Accepts float values
                 (which represent the memory limit of the created container in
                 bytes) or a string with a units identification char
                 (``100000b``, ``1000k``, ``128m``, ``1g``). If a string is
                 specified without a units character, bytes are assumed as an
+            mem_reservation (int or str): Memory soft limit.
             mem_swappiness (int): Tune a container's memory swappiness
                 behavior. Accepts number between 0 and 100.
             memswap_limit (str or int): Maximum amount of memory + swap a
@@ -500,7 +515,7 @@ class ContainerApiMixin(object):
             network_mode (str): One of:
 
                 - ``bridge`` Create a new network stack for the container on
-                  on the bridge network.
+                  the bridge network.
                 - ``none`` No networking for this container.
                 - ``container:<name|id>`` Reuse another container's network
                   stack.
@@ -543,10 +558,12 @@ class ContainerApiMixin(object):
                     }
 
             ulimits (:py:class:`list`): Ulimits to set inside the container,
-                as a list of dicts.
+                as a list of :py:class:`docker.types.Ulimit` instances.
             userns_mode (str): Sets the user namespace mode for the container
                 when user namespace remapping option is enabled. Supported
                 values are: ``host``
+            uts_mode (str): Sets the UTS namespace mode for the container.
+                Supported 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.
@@ -609,9 +626,10 @@ class ContainerApiMixin(object):
             aliases (:py:class:`list`): A list of aliases for this endpoint.
                 Names in that list can be used within the network to reach the
                 container. Defaults to ``None``.
-            links (:py:class:`list`): A list of links for this endpoint.
-                Containers declared in this list will be linked to this
-                container. Defaults to ``None``.
+            links (dict): Mapping of links for this endpoint using the
+                ``{'container': 'alias'}`` format. The alias is optional.
+                Containers declared in this dict will be linked to this
+                container using the provided alias. Defaults to ``None``.
             ipv4_address (str): The IP address of this container on the
                 network, using the IPv4 protocol. Defaults to ``None``.
             ipv6_address (str): The IP address of this container on the
@@ -626,7 +644,7 @@ class ContainerApiMixin(object):
 
             >>> endpoint_config = client.create_endpoint_config(
                 aliases=['web', 'app'],
-                links=['app_db'],
+                links={'app_db': 'db', 'another': None},
                 ipv4_address='132.65.0.123'
             )
 
@@ -695,6 +713,18 @@ class ContainerApiMixin(object):
         Raises:
             :py:class:`docker.errors.APIError`
                 If the server returns an error.
+
+        Example:
+
+            >>> c = docker.APIClient()
+            >>> f = open('./sh_bin.tar', 'wb')
+            >>> bits, stat = c.get_archive(container, '/bin/sh')
+            >>> print(stat)
+            {'name': 'sh', 'size': 1075464, 'mode': 493,
+             'mtime': '2018-10-01T15:37:48-07:00', 'linkTarget': ''}
+            >>> for chunk in bits:
+            ...    f.write(chunk)
+            >>> f.close()
         """
         params = {
             'path': path
@@ -763,16 +793,16 @@ class ContainerApiMixin(object):
 
         Args:
             container (str): The container to get logs from
-            stdout (bool): Get ``STDOUT``
-            stderr (bool): Get ``STDERR``
-            stream (bool): Stream the response
-            timestamps (bool): Show timestamps
+            stdout (bool): Get ``STDOUT``. Default ``True``
+            stderr (bool): Get ``STDERR``. Default ``True``
+            stream (bool): Stream the response. Default ``False``
+            timestamps (bool): Show timestamps. Default ``False``
             tail (str or int): Output specified number of lines at the end of
                 logs. Either an integer of number of lines or the string
                 ``all``. Default ``all``
             since (datetime or int): Show logs since a given datetime or
                 integer epoch (in seconds)
-            follow (bool): Follow log output
+            follow (bool): Follow log output. Default ``False``
             until (datetime or int): Show logs that occurred before the given
                 datetime or integer epoch (in seconds)
 
@@ -888,9 +918,10 @@ class ContainerApiMixin(object):
         if '/' in private_port:
             return port_settings.get(private_port)
 
-        h_ports = port_settings.get(private_port + '/tcp')
-        if h_ports is None:
-            h_ports = port_settings.get(private_port + '/udp')
+        for protocol in ['tcp', 'udp', 'sctp']:
+            h_ports = port_settings.get(private_port + '/' + protocol)
+            if h_ports:
+                break
 
         return h_ports
 
@@ -1072,7 +1103,8 @@ class ContainerApiMixin(object):
         Args:
             container (str): The container to stream statistics from
             decode (bool): If set to true, stream will be decoded into dicts
-                on the fly. False by default.
+                on the fly. Only applicable if ``stream`` is True.
+                False by default.
             stream (bool): If set to false, only the current stats will be
                 returned instead of a stream. True by default.
 
@@ -1086,6 +1118,10 @@ class ContainerApiMixin(object):
             return self._stream_helper(self._get(url, stream=True),
                                        decode=decode)
         else:
+            if decode:
+                raise errors.InvalidArgument(
+                    "decode is only available in conjuction with stream=True"
+                )
             return self._result(self._get(url, params={'stream': False}),
                                 json=True)
 
diff --git a/docker/api/daemon.py b/docker/api/daemon.py
index 76a94cf..f715a13 100644
--- a/docker/api/daemon.py
+++ b/docker/api/daemon.py
@@ -42,8 +42,8 @@ class DaemonApiMixin(object):
 
         Example:
 
-            >>> for event in client.events()
-            ...   print event
+            >>> for event in client.events(decode=True)
+            ...   print(event)
             {u'from': u'image/with:tag',
              u'id': u'container-id',
              u'status': u'start',
@@ -54,7 +54,7 @@ class DaemonApiMixin(object):
 
             >>> events = client.events()
             >>> for event in events:
-            ...   print event
+            ...   print(event)
             >>> # and cancel from another thread
             >>> events.close()
         """
@@ -124,13 +124,15 @@ class DaemonApiMixin(object):
         # If dockercfg_path is passed check to see if the config file exists,
         # if so load that config.
         if dockercfg_path and os.path.exists(dockercfg_path):
-            self._auth_configs = auth.load_config(dockercfg_path)
-        elif not self._auth_configs:
-            self._auth_configs = auth.load_config()
-
-        authcfg = auth.resolve_authconfig(
-            self._auth_configs, registry, credstore_env=self.credstore_env,
-        )
+            self._auth_configs = auth.load_config(
+                dockercfg_path, credstore_env=self.credstore_env
+            )
+        elif not self._auth_configs or self._auth_configs.is_empty:
+            self._auth_configs = auth.load_config(
+                credstore_env=self.credstore_env
+            )
+
+        authcfg = self._auth_configs.resolve_authconfig(registry)
         # If we found an existing auth config for this registry and username
         # combination, we can return it immediately unless reauth is requested.
         if authcfg and authcfg.get('username', None) == username \
@@ -146,9 +148,7 @@ class DaemonApiMixin(object):
 
         response = self._post_json(self._url('/auth'), data=req_data)
         if response.status_code == 200:
-            if 'auths' not in self._auth_configs:
-                self._auth_configs['auths'] = {}
-            self._auth_configs['auths'][registry or auth.INDEX_NAME] = req_data
+            self._auth_configs.add_auth(registry or auth.INDEX_NAME, req_data)
         return self._result(response, json=True)
 
     def ping(self):
diff --git a/docker/api/exec_api.py b/docker/api/exec_api.py
index 986d87f..4c49ac3 100644
--- a/docker/api/exec_api.py
+++ b/docker/api/exec_api.py
@@ -118,7 +118,7 @@ class ExecApiMixin(object):
 
     @utils.check_resource('exec_id')
     def exec_start(self, exec_id, detach=False, tty=False, stream=False,
-                   socket=False):
+                   socket=False, demux=False):
         """
         Start a previously set up exec instance.
 
@@ -130,11 +130,15 @@ class ExecApiMixin(object):
             stream (bool): Stream response data. Default: False
             socket (bool): Return the connection socket to allow custom
                 read/write operations.
+            demux (bool): Return stdout and stderr separately
 
         Returns:
-            (generator or str): If ``stream=True``, a generator yielding
-            response chunks. If ``socket=True``, a socket object for the
-            connection. A string containing response data otherwise.
+
+            (generator or str or tuple): If ``stream=True``, a generator
+            yielding response chunks. If ``socket=True``, a socket object for
+            the connection. A string containing response data otherwise. If
+            ``demux=True``, a tuple with two elements of type byte: stdout and
+            stderr.
 
         Raises:
             :py:class:`docker.errors.APIError`
@@ -162,4 +166,4 @@ class ExecApiMixin(object):
             return self._result(res)
         if socket:
             return self._get_raw_response_socket(res)
-        return self._read_from_socket(res, stream, tty)
+        return self._read_from_socket(res, stream, tty=tty, demux=demux)
diff --git a/docker/api/image.py b/docker/api/image.py
index 5f05d88..11c8cf7 100644
--- a/docker/api/image.py
+++ b/docker/api/image.py
@@ -32,7 +32,7 @@ class ImageApiMixin(object):
         Example:
 
             >>> image = cli.get_image("busybox:latest")
-            >>> f = open('/tmp/busybox-latest.tar', 'w')
+            >>> f = open('/tmp/busybox-latest.tar', 'wb')
             >>> for chunk in image:
             >>>   f.write(chunk)
             >>> f.close()
@@ -70,7 +70,8 @@ class ImageApiMixin(object):
             filters (dict): Filters to be processed on the image list.
                 Available filters:
                 - ``dangling`` (bool)
-                - ``label`` (str): format either ``key`` or ``key=value``
+                - `label` (str|list): format either ``"key"``, ``"key=value"``
+                    or a list of such.
 
         Returns:
             (dict or list): A list if ``quiet=True``, otherwise a dict.
@@ -247,12 +248,15 @@ class ImageApiMixin(object):
 
     @utils.minimum_version('1.30')
     @utils.check_resource('image')
-    def inspect_distribution(self, image):
+    def inspect_distribution(self, image, auth_config=None):
         """
         Get image digest and platform information by contacting the registry.
 
         Args:
             image (str): The image name to inspect
+            auth_config (dict): Override the credentials that are found in the
+                config for this request.  ``auth_config`` should contain the
+                ``username`` and ``password`` keys to be valid.
 
         Returns:
             (dict): A dict containing distribution data
@@ -261,9 +265,21 @@ class ImageApiMixin(object):
             :py:class:`docker.errors.APIError`
                 If the server returns an error.
         """
+        registry, _ = auth.resolve_repository_name(image)
+
+        headers = {}
+        if auth_config is None:
+            header = auth.get_config_header(self, registry)
+            if header:
+                headers['X-Registry-Auth'] = header
+        else:
+            log.debug('Sending supplied auth config')
+            headers['X-Registry-Auth'] = auth.encode_header(auth_config)
+
+        url = self._url("/distribution/{0}/json", image)
 
         return self._result(
-            self._get(self._url("/distribution/{0}/json", image)), True
+            self._get(url, headers=headers), True
         )
 
     def load_image(self, data, quiet=None):
@@ -334,11 +350,11 @@ class ImageApiMixin(object):
         Args:
             repository (str): The repository to pull
             tag (str): The tag to pull
-            stream (bool): Stream the output as a generator
-            auth_config (dict): Override the credentials that
-                :py:meth:`~docker.api.daemon.DaemonApiMixin.login` has set for
-                this request. ``auth_config`` should contain the ``username``
-                and ``password`` keys to be valid.
+            stream (bool): Stream the output as a generator. Make sure to
+                consume the generator, otherwise pull might get cancelled.
+            auth_config (dict): Override the credentials that are found in the
+                config for this request.  ``auth_config`` should contain the
+                ``username`` and ``password`` keys to be valid.
             decode (bool): Decode the JSON data from the server into dicts.
                 Only applies with ``stream=True``
             platform (str): Platform in the format ``os[/arch[/variant]]``
@@ -352,8 +368,8 @@ class ImageApiMixin(object):
 
         Example:
 
-            >>> for line in cli.pull('busybox', stream=True):
-            ...     print(json.dumps(json.loads(line), indent=4))
+            >>> for line in cli.pull('busybox', stream=True, decode=True):
+            ...     print(json.dumps(line, indent=4))
             {
                 "status": "Pulling image (latest) from busybox",
                 "progressDetail": {},
@@ -413,10 +429,9 @@ class ImageApiMixin(object):
             repository (str): The repository to push to
             tag (str): An optional tag to push
             stream (bool): Stream the output as a blocking generator
-            auth_config (dict): Override the credentials that
-                :py:meth:`~docker.api.daemon.DaemonApiMixin.login` has set for
-                this request. ``auth_config`` should contain the ``username``
-                and ``password`` keys to be valid.
+            auth_config (dict): Override the credentials that are found in the
+                config for this request.  ``auth_config`` should contain the
+                ``username`` and ``password`` keys to be valid.
             decode (bool): Decode the JSON data from the server into dicts.
                 Only applies with ``stream=True``
 
@@ -428,12 +443,12 @@ class ImageApiMixin(object):
                 If the server returns an error.
 
         Example:
-            >>> for line in cli.push('yourname/app', stream=True):
-            ...   print line
-            {"status":"Pushing repository yourname/app (1 tags)"}
-            {"status":"Pushing","progressDetail":{},"id":"511136ea3c5a"}
-            {"status":"Image already pushed, skipping","progressDetail":{},
-             "id":"511136ea3c5a"}
+            >>> for line in cli.push('yourname/app', stream=True, decode=True):
+            ...   print(line)
+            {'status': 'Pushing repository yourname/app (1 tags)'}
+            {'status': 'Pushing','progressDetail': {}, 'id': '511136ea3c5a'}
+            {'status': 'Image already pushed, skipping', 'progressDetail':{},
+             'id': '511136ea3c5a'}
             ...
 
         """
diff --git a/docker/api/network.py b/docker/api/network.py
index 57ed8d3..750b91b 100644
--- a/docker/api/network.py
+++ b/docker/api/network.py
@@ -7,7 +7,7 @@ from .. import utils
 class NetworkApiMixin(object):
     def networks(self, names=None, ids=None, filters=None):
         """
-        List networks. Similar to the ``docker networks ls`` command.
+        List networks. Similar to the ``docker network ls`` command.
 
         Args:
             names (:py:class:`list`): List of names to filter by
@@ -15,7 +15,8 @@ class NetworkApiMixin(object):
             filters (dict): Filters to be processed on the network list.
                 Available filters:
                 - ``driver=[<driver-name>]`` Matches a network's driver.
-                - ``label=[<key>]`` or ``label=[<key>=<value>]``.
+                - ``label=[<key>]``, ``label=[<key>=<value>]`` or a list of
+                    such.
                 - ``type=["custom"|"builtin"]`` Filters networks by type.
 
         Returns:
diff --git a/docker/api/secret.py b/docker/api/secret.py
index fa4c2ab..e57952b 100644
--- a/docker/api/secret.py
+++ b/docker/api/secret.py
@@ -53,7 +53,7 @@ class SecretApiMixin(object):
             Retrieve secret metadata
 
             Args:
-                id (string): Full ID of the secret to remove
+                id (string): Full ID of the secret to inspect
 
             Returns (dict): A dictionary of metadata
 
diff --git a/docker/api/service.py b/docker/api/service.py
index 03b0ca6..e9027bf 100644
--- a/docker/api/service.py
+++ b/docker/api/service.py
@@ -2,7 +2,8 @@ from .. import auth, errors, utils
 from ..types import ServiceMode
 
 
-def _check_api_features(version, task_template, update_config, endpoint_spec):
+def _check_api_features(version, task_template, update_config, endpoint_spec,
+                        rollback_config):
 
     def raise_version_error(param, min_version):
         raise errors.InvalidVersion(
@@ -18,10 +19,24 @@ def _check_api_features(version, task_template, update_config, endpoint_spec):
             if 'Monitor' in update_config:
                 raise_version_error('UpdateConfig.monitor', '1.25')
 
+        if utils.version_lt(version, '1.28'):
+            if update_config.get('FailureAction') == 'rollback':
+                raise_version_error(
+                    'UpdateConfig.failure_action rollback', '1.28'
+                )
+
         if utils.version_lt(version, '1.29'):
             if 'Order' in update_config:
                 raise_version_error('UpdateConfig.order', '1.29')
 
+    if rollback_config is not None:
+        if utils.version_lt(version, '1.28'):
+            raise_version_error('rollback_config', '1.28')
+
+        if utils.version_lt(version, '1.29'):
+            if 'Order' in update_config:
+                raise_version_error('RollbackConfig.order', '1.29')
+
     if endpoint_spec is not None:
         if utils.version_lt(version, '1.32') and 'Ports' in endpoint_spec:
             if any(p.get('PublishMode') for p in endpoint_spec['Ports']):
@@ -73,6 +88,10 @@ def _check_api_features(version, task_template, update_config, endpoint_spec):
                 if container_spec.get('Isolation') is not None:
                     raise_version_error('ContainerSpec.isolation', '1.35')
 
+            if utils.version_lt(version, '1.38'):
+                if container_spec.get('Init') is not None:
+                    raise_version_error('ContainerSpec.init', '1.38')
+
         if task_template.get('Resources'):
             if utils.version_lt(version, '1.32'):
                 if task_template['Resources'].get('GenericResources'):
@@ -99,7 +118,7 @@ class ServiceApiMixin(object):
     def create_service(
             self, task_template, name=None, labels=None, mode=None,
             update_config=None, networks=None, endpoint_config=None,
-            endpoint_spec=None
+            endpoint_spec=None, rollback_config=None
     ):
         """
         Create a service.
@@ -114,8 +133,11 @@ class ServiceApiMixin(object):
                 or global). Defaults to replicated.
             update_config (UpdateConfig): Specification for the update strategy
                 of the service. Default: ``None``
-            networks (:py:class:`list`): List of network names or IDs to attach
-                the service to. Default: ``None``.
+            rollback_config (RollbackConfig): Specification for the rollback
+                strategy of the service. Default: ``None``
+            networks (:py:class:`list`): List of network names or IDs or
+                :py:class:`~docker.types.NetworkAttachmentConfig` to attach the
+                service to. Default: ``None``.
             endpoint_spec (EndpointSpec): Properties that can be configured to
                 access and load balance a service. Default: ``None``.
 
@@ -129,7 +151,8 @@ class ServiceApiMixin(object):
         """
 
         _check_api_features(
-            self._version, task_template, update_config, endpoint_spec
+            self._version, task_template, update_config, endpoint_spec,
+            rollback_config
         )
 
         url = self._url('/services/create')
@@ -160,6 +183,9 @@ class ServiceApiMixin(object):
         if update_config is not None:
             data['UpdateConfig'] = update_config
 
+        if rollback_config is not None:
+            data['RollbackConfig'] = rollback_config
+
         return self._result(
             self._post_json(url, data=data, headers=headers), True
         )
@@ -176,7 +202,8 @@ class ServiceApiMixin(object):
                 into the service inspect output.
 
         Returns:
-            ``True`` if successful.
+            (dict): A dictionary of the server-side representation of the
+                service, including all relevant properties.
 
         Raises:
             :py:class:`docker.errors.APIError`
@@ -336,7 +363,8 @@ class ServiceApiMixin(object):
     def update_service(self, service, version, task_template=None, name=None,
                        labels=None, mode=None, update_config=None,
                        networks=None, endpoint_config=None,
-                       endpoint_spec=None, fetch_current_spec=False):
+                       endpoint_spec=None, fetch_current_spec=False,
+                       rollback_config=None):
         """
         Update a service.
 
@@ -354,15 +382,18 @@ class ServiceApiMixin(object):
                 or global). Defaults to replicated.
             update_config (UpdateConfig): Specification for the update strategy
                 of the service. Default: ``None``.
-            networks (:py:class:`list`): List of network names or IDs to attach
-                the service to. Default: ``None``.
+            rollback_config (RollbackConfig): Specification for the rollback
+                strategy of the service. Default: ``None``
+            networks (:py:class:`list`): List of network names or IDs or
+                :py:class:`~docker.types.NetworkAttachmentConfig` to attach the
+                service to. Default: ``None``.
             endpoint_spec (EndpointSpec): Properties that can be configured to
                 access and load balance a service. Default: ``None``.
             fetch_current_spec (boolean): Use the undefined settings from the
                 current specification of the service. Default: ``False``
 
         Returns:
-            ``True`` if successful.
+            A dictionary containing a ``Warnings`` key.
 
         Raises:
             :py:class:`docker.errors.APIError`
@@ -370,7 +401,8 @@ class ServiceApiMixin(object):
         """
 
         _check_api_features(
-            self._version, task_template, update_config, endpoint_spec
+            self._version, task_template, update_config, endpoint_spec,
+            rollback_config
         )
 
         if fetch_current_spec:
@@ -416,6 +448,11 @@ class ServiceApiMixin(object):
         else:
             data['UpdateConfig'] = current.get('UpdateConfig')
 
+        if rollback_config is not None:
+            data['RollbackConfig'] = rollback_config
+        else:
+            data['RollbackConfig'] = current.get('RollbackConfig')
+
         if networks is not None:
             converted_networks = utils.convert_service_networks(networks)
             if utils.version_lt(self._version, '1.25'):
@@ -440,5 +477,4 @@ class ServiceApiMixin(object):
         resp = self._post_json(
             url, data=data, params={'version': version}, headers=headers
         )
-        self._raise_for_status(resp)
-        return True
+        return self._result(resp, json=True)
diff --git a/docker/api/swarm.py b/docker/api/swarm.py
index 04595da..897f08e 100644
--- a/docker/api/swarm.py
+++ b/docker/api/swarm.py
@@ -1,5 +1,6 @@
 import logging
 from six.moves import http_client
+from ..constants import DEFAULT_SWARM_ADDR_POOL, DEFAULT_SWARM_SUBNET_SIZE
 from .. import errors
 from .. import types
 from .. import utils
@@ -82,7 +83,9 @@ class SwarmApiMixin(object):
 
     @utils.minimum_version('1.24')
     def init_swarm(self, advertise_addr=None, listen_addr='0.0.0.0:2377',
-                   force_new_cluster=False, swarm_spec=None):
+                   force_new_cluster=False, swarm_spec=None,
+                   default_addr_pool=None, subnet_size=None,
+                   data_path_addr=None):
         """
         Initialize a new Swarm using the current connected engine as the first
         node.
@@ -107,9 +110,17 @@ class SwarmApiMixin(object):
             swarm_spec (dict): Configuration settings of the new Swarm. Use
                 ``APIClient.create_swarm_spec`` to generate a valid
                 configuration. Default: None
+            default_addr_pool (list of strings): Default Address Pool specifies
+                default subnet pools for global scope networks. Each pool
+                should be specified as a CIDR block, like '10.0.0.0/8'.
+                Default: None
+            subnet_size (int): SubnetSize specifies the subnet size of the
+                networks created from the default subnet pool. Default: None
+            data_path_addr (string): Address or interface to use for data path
+                traffic. For example, 192.168.1.1, or an interface, like eth0.
 
         Returns:
-            ``True`` if successful.
+            (str): The ID of the created node.
 
         Raises:
             :py:class:`docker.errors.APIError`
@@ -119,15 +130,44 @@ class SwarmApiMixin(object):
         url = self._url('/swarm/init')
         if swarm_spec is not None and not isinstance(swarm_spec, dict):
             raise TypeError('swarm_spec must be a dictionary')
+
+        if default_addr_pool is not None:
+            if utils.version_lt(self._version, '1.39'):
+                raise errors.InvalidVersion(
+                    'Address pool is only available for API version >= 1.39'
+                )
+            # subnet_size becomes 0 if not set with default_addr_pool
+            if subnet_size is None:
+                subnet_size = DEFAULT_SWARM_SUBNET_SIZE
+
+        if subnet_size is not None:
+            if utils.version_lt(self._version, '1.39'):
+                raise errors.InvalidVersion(
+                    'Subnet size is only available for API version >= 1.39'
+                )
+            # subnet_size is ignored if set without default_addr_pool
+            if default_addr_pool is None:
+                default_addr_pool = DEFAULT_SWARM_ADDR_POOL
+
         data = {
             'AdvertiseAddr': advertise_addr,
             'ListenAddr': listen_addr,
+            'DefaultAddrPool': default_addr_pool,
+            'SubnetSize': subnet_size,
             'ForceNewCluster': force_new_cluster,
             'Spec': swarm_spec,
         }
+
+        if data_path_addr is not None:
+            if utils.version_lt(self._version, '1.30'):
+                raise errors.InvalidVersion(
+                    'Data address path is only available for '
+                    'API version >= 1.30'
+                )
+            data['DataPathAddr'] = data_path_addr
+
         response = self._post_json(url, data=data)
-        self._raise_for_status(response)
-        return True
+        return self._result(response, json=True)
 
     @utils.minimum_version('1.24')
     def inspect_swarm(self):
@@ -165,7 +205,7 @@ class SwarmApiMixin(object):
 
     @utils.minimum_version('1.24')
     def join_swarm(self, remote_addrs, join_token, listen_addr='0.0.0.0:2377',
-                   advertise_addr=None):
+                   advertise_addr=None, data_path_addr=None):
         """
         Make this Engine join a swarm that has already been created.
 
@@ -176,7 +216,7 @@ class SwarmApiMixin(object):
             listen_addr (string): Listen address used for inter-manager
                 communication if the node gets promoted to manager, as well as
                 determining the networking interface used for the VXLAN Tunnel
-                Endpoint (VTEP). Default: ``None``
+                Endpoint (VTEP). Default: ``'0.0.0.0:2377``
             advertise_addr (string): Externally reachable address advertised
                 to other nodes. This can either be an address/port combination
                 in the form ``192.168.1.1:4567``, or an interface followed by a
@@ -184,6 +224,8 @@ class SwarmApiMixin(object):
                 the port number from the listen address is used. If
                 AdvertiseAddr is not specified, it will be automatically
                 detected when possible. Default: ``None``
+            data_path_addr (string): Address or interface to use for data path
+                traffic. For example, 192.168.1.1, or an interface, like eth0.
 
         Returns:
             ``True`` if the request went through.
@@ -193,11 +235,20 @@ class SwarmApiMixin(object):
                 If the server returns an error.
         """
         data = {
-            "RemoteAddrs": remote_addrs,
-            "ListenAddr": listen_addr,
-            "JoinToken": join_token,
-            "AdvertiseAddr": advertise_addr,
+            'RemoteAddrs': remote_addrs,
+            'ListenAddr': listen_addr,
+            'JoinToken': join_token,
+            'AdvertiseAddr': advertise_addr,
         }
+
+        if data_path_addr is not None:
+            if utils.version_lt(self._version, '1.30'):
+                raise errors.InvalidVersion(
+                    'Data address path is only available for '
+                    'API version >= 1.30'
+                )
+            data['DataPathAddr'] = data_path_addr
+
         url = self._url('/swarm/join')
         response = self._post_json(url, data=data)
         self._raise_for_status(response)
@@ -355,8 +406,10 @@ class SwarmApiMixin(object):
         return True
 
     @utils.minimum_version('1.24')
-    def update_swarm(self, version, swarm_spec=None, rotate_worker_token=False,
-                     rotate_manager_token=False):
+    def update_swarm(self, version, swarm_spec=None,
+                     rotate_worker_token=False,
+                     rotate_manager_token=False,
+                     rotate_manager_unlock_key=False):
         """
         Update the Swarm's configuration
 
@@ -370,6 +423,8 @@ class SwarmApiMixin(object):
                 ``False``.
             rotate_manager_token (bool): Rotate the manager join token.
                 Default: ``False``.
+            rotate_manager_unlock_key (bool): Rotate the manager unlock key.
+                Default: ``False``.
 
         Returns:
             ``True`` if the request went through.
@@ -378,12 +433,20 @@ class SwarmApiMixin(object):
             :py:class:`docker.errors.APIError`
                 If the server returns an error.
         """
-
         url = self._url('/swarm/update')
-        response = self._post_json(url, data=swarm_spec, params={
+        params = {
             'rotateWorkerToken': rotate_worker_token,
             'rotateManagerToken': rotate_manager_token,
             'version': version
-        })
+        }
+        if rotate_manager_unlock_key:
+            if utils.version_lt(self._version, '1.25'):
+                raise errors.InvalidVersion(
+                    'Rotate manager unlock key '
+                    'is only available for API version >= 1.25'
+                )
+            params['rotateManagerUnlockKey'] = rotate_manager_unlock_key
+
+        response = self._post_json(url, data=swarm_spec, params=params)
         self._raise_for_status(response)
         return True