2.0.2 release

docker/api/client.py

@@ -18,16 +18,20 @@
 from .swarm import SwarmApiMixin
 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)
-from ..errors import (DockerException, TLSParameterError,
-                      create_api_error_from_http_exception)
+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
+)
+from ..errors import (
+    DockerException, TLSParameterError,
+    create_api_error_from_http_exception
+)
 from ..tls import TLSConfig
 from ..transport import SSLAdapter, UnixAdapter
 from ..utils import utils, check_resource, update_headers
 from ..utils.socket import frames_iter
+from ..utils.json_stream import json_stream
 try:
     from ..transport import NpipeAdapter
 except ImportError:
@@ -274,27 +278,20 @@ def _get_raw_response_socket(self, response):
 
     def _stream_helper(self, response, decode=False):
         """Generator for data coming from a chunked-encoded HTTP response."""
+
         if response.raw._fp.chunked:
-            reader = response.raw
-            while not reader.closed:
-                # this read call will block until we get a chunk
-                data = reader.read(1)
-                if not data:
-                    break
-                if reader._fp.chunk_left:
-                    data += reader.read(reader._fp.chunk_left)
-                if decode:
-                    if six.PY3:
-                        data = data.decode('utf-8')
-                    # remove the trailing newline
-                    data = data.strip()
-                    # split the data at any newlines
-                    data_list = data.split("\r\n")
-                    # load and yield each line seperately
-                    for data in data_list:
-                        data = json.loads(data)
-                        yield data
-                else:
+            if decode:
+                for chunk in json_stream(self._stream_helper(response, False)):
+                    yield chunk
+            else:
+                reader = response.raw
+                while not reader.closed:
+                    # this read call will block until we get a chunk
+                    data = reader.read(1)
+                    if not data:
+                        break
+                    if reader._fp.chunk_left:
+                        data += reader.read(reader._fp.chunk_left)
                     yield data
         else:
             # Response isn't chunked, meaning we probably

docker/api/container.py

@@ -388,13 +388,13 @@ def create_container(self, image, command=None, hostname=None, user=None,
             environment (dict or list): A dictionary or a list of strings in
                 the following format ``["PASSWORD=xxx"]`` or
                 ``{"PASSWORD": "xxx"}``.
-            dns (list): DNS name servers. Deprecated since API version 1.10.
-                Use ``host_config`` instead.
-            dns_opt (list): Additional options to be added to the container's
-                ``resolv.conf`` file
+            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):
-            volumes_from (list): List of container names or Ids to get
-                volumes from.
+            volumes_from (:py:class:`list`): List of container names or Ids to
+                get volumes from.
             network_disabled (bool): Disable networking
             name (str): A name for the container
             entrypoint (str or list): An entrypoint
@@ -478,19 +478,19 @@ def create_host_config(self, *args, **kwargs):
             device_write_bps: Limit write rate (bytes per second) from a
                 device.
             device_write_iops: Limit write rate (IO per second) from a device.
-            devices (list): Expose host devices to the container, as a list
-                of strings in the form
+            devices (:py:class:`list`): Expose host devices to the container,
+                as a list of strings in the form
                 ``<path_on_host>:<path_in_container>:<cgroup_permissions>``.
 
                 For example, ``/dev/sda:/dev/xvda:rwm`` allows the container
                 to have read-write access to the host's ``/dev/sda`` via a
                 node named ``/dev/xvda`` inside the container.
-            dns (list): Set custom DNS servers.
-            dns_search (list): DNS search domains.
+            dns (:py:class:`list`): Set custom DNS servers.
+            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.
-            group_add (list): List of additional group names and/or IDs that
-                the container process will run as.
+            group_add (:py:class:`list`): List of additional group names and/or
+                IDs that the container process will run as.
             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
@@ -539,8 +539,8 @@ def create_host_config(self, *args, **kwargs):
                 - ``Name`` One of ``on-failure``, or ``always``.
                 - ``MaximumRetryCount`` Number of times to restart the
                   container on failure.
-            security_opt (list): A list of string values to customize labels
-                for MLS systems, such as SELinux.
+            security_opt (:py:class:`list`): A list of string values to
+                customize labels for MLS systems, such as SELinux.
             shm_size (str or int): Size of /dev/shm (e.g. ``1G``).
             sysctls (dict): Kernel parameters to set in the container.
             tmpfs (dict): Temporary filesystems to mount, as a dictionary
@@ -555,13 +555,13 @@ def create_host_config(self, *args, **kwargs):
                         '/mnt/vol1': 'size=3G,uid=1000'
                     }
 
-            ulimits (list): Ulimits to set inside the container, as a list of
-                dicts.
+            ulimits (:py:class:`list`): Ulimits to set inside the container,
+                as a list of dicts.
             userns_mode (str): Sets the user namespace mode for the container
                 when user namespace remapping option is enabled. Supported
                 values are: ``host``
-            volumes_from (list): List of container names or IDs to get
-                volumes from.
+            volumes_from (:py:class:`list`): List of container names or IDs to
+                get volumes from.
 
 
         Returns:
@@ -618,17 +618,17 @@ def create_endpoint_config(self, *args, **kwargs):
         :py:meth:`create_networking_config`.
 
         Args:
-            aliases (list): A list of aliases for this endpoint. Names in
-                that list can be used within the network to reach the
+            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 (list): A list of links for this endpoint. Containers
-                declared in this list will be linked to this container.
-                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
                 network, using the IPv6 protocol. Defaults to ``None``.
-            link_local_ips (list): A list of link-local (IPv4/IPv6)
+            link_local_ips (:py:class:`list`): A list of link-local (IPv4/IPv6)
                 addresses.
 
         Returns:

docker/api/network.py

@@ -1,19 +1,23 @@
-import json
-
 from ..errors import InvalidVersion
 from ..utils import check_resource, minimum_version
 from ..utils import version_lt
+from .. import utils
 
 
 class NetworkApiMixin(object):
     @minimum_version('1.21')
-    def networks(self, names=None, ids=None):
+    def networks(self, names=None, ids=None, filters=None):
         """
         List networks. Similar to the ``docker networks ls`` command.
 
         Args:
-            names (list): List of names to filter by
-            ids (list): List of ids to filter by
+            names (:py:class:`list`): List of names to filter by
+            ids (:py:class:`list`): List of ids to filter by
+            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>]``.
+                - ``type=["custom"|"builtin"]`` Filters networks by type.
 
         Returns:
             (dict): List of network objects.
@@ -23,14 +27,13 @@ def networks(self, names=None, ids=None):
                 If the server returns an error.
         """
 
-        filters = {}
+        if filters is None:
+            filters = {}
         if names:
             filters['name'] = names
         if ids:
             filters['id'] = ids
-
-        params = {'filters': json.dumps(filters)}
-
+        params = {'filters': utils.convert_filters(filters)}
         url = self._url("/networks")
         res = self._get(url, params=params)
         return self._result(res, json=True)
@@ -166,17 +169,18 @@ def connect_container_to_network(self, container, net_id,
         Args:
             container (str): container-id/name to be connected to the network
             net_id (str): network id
-            aliases (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 (list): A list of links for this endpoint. Containers
-                declared in this list will be linkedto this container.
-                Defaults to ``None``.
+            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``.
             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
                 network, using the IPv6 protocol. Defaults to ``None``.
-            link_local_ips (list): A list of link-local (IPv4/IPv6) addresses.
+            link_local_ips (:py:class:`list`): A list of link-local
+            (IPv4/IPv6) addresses.
         """
         data = {
             "Container": container,

docker/api/service.py

@@ -1,5 +1,6 @@
 import warnings
 from .. import auth, errors, utils
+from ..types import ServiceMode
 
 
 class ServiceApiMixin(object):
@@ -13,18 +14,18 @@ def create_service(
         Create a service.
 
         Args:
-            task_template (dict): Specification of the task to start as part
-                of the new service.
+            task_template (TaskTemplate): Specification of the task to start as
+                part of the new service.
             name (string): User-defined name for the service. Optional.
             labels (dict): A map of labels to associate with the service.
                 Optional.
-            mode (string): Scheduling mode for the service (``replicated`` or
-                ``global``). Defaults to ``replicated``.
-            update_config (dict): Specification for the update strategy of the
-                service. Default: ``None``
-            networks (list): List of network names or IDs to attach the
-                service to. Default: ``None``.
-            endpoint_config (dict): Properties that can be configured to
+            mode (ServiceMode): Scheduling mode for the service (replicated
+                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``.
+            endpoint_spec (EndpointSpec): Properties that can be configured to
                 access and load balance a service. Default: ``None``.
 
         Returns:
@@ -49,6 +50,9 @@ def create_service(
             raise errors.DockerException(
                 'Missing mandatory Image key in ContainerSpec'
             )
+        if mode and not isinstance(mode, dict):
+            mode = ServiceMode(mode)
+
         registry, repo_name = auth.resolve_repository_name(image)
         auth_header = auth.get_config_header(self, registry)
         if auth_header:
@@ -159,7 +163,7 @@ def tasks(self, filters=None):
                 ``label`` and ``desired-state``.
 
         Returns:
-            (list): List of task dictionaries.
+            (:py:class:`list`): List of task dictionaries.
 
         Raises:
             :py:class:`docker.errors.APIError`
@@ -186,20 +190,18 @@ def update_service(self, service, version, task_template=None, name=None,
                 ID).
             version (int): The version number of the service object being
                 updated. This is required to avoid conflicting writes.
-            task_template (dict): Specification of the updated task to start
-                as part of the service. See the [TaskTemplate
-                class](#TaskTemplate) for details.
+            task_template (TaskTemplate): Specification of the updated task to
+                start as part of the service.
             name (string): New name for the service. Optional.
             labels (dict): A map of labels to associate with the service.
                 Optional.
-            mode (string): Scheduling mode for the service (``replicated`` or
-                ``global``). Defaults to ``replicated``.
-            update_config (dict): Specification for the update strategy of the
-                service. See the [UpdateConfig class](#UpdateConfig) for
-                details. Default: ``None``.
-            networks (list): List of network names or IDs to attach the
-                service to. Default: ``None``.
-            endpoint_config (dict): Properties that can be configured to
+            mode (ServiceMode): Scheduling mode for the service (replicated
+                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``.
+            endpoint_spec (EndpointSpec): Properties that can be configured to
                 access and load balance a service. Default: ``None``.
 
         Returns:
@@ -224,6 +226,8 @@ def update_service(self, service, version, task_template=None, name=None,
         if labels is not None:
             data['Labels'] = labels
         if mode is not None:
+            if not isinstance(mode, dict):
+                mode = ServiceMode(mode)
             data['Mode'] = mode
         if task_template is not None:
             image = task_template.get('ContainerSpec', {}).get('Image', None)

docker/api/swarm.py

@@ -143,8 +143,8 @@ def join_swarm(self, remote_addrs, join_token, listen_addr=None,
         Make this Engine join a swarm that has already been created.
 
         Args:
-            remote_addrs (list): Addresses of one or more manager nodes already
-                participating in the Swarm to join.
+            remote_addrs (:py:class:`list`): Addresses of one or more manager
+                nodes already participating in the Swarm to join.
             join_token (string): Secret token for joining this Swarm.
             listen_addr (string): Listen address used for inter-manager
                 communication if the node gets promoted to manager, as well as