Add docstrings to low-level API

Signed-off-by: Ben Firshman <ben@firshman.co.uk>

docker/api/build.py

@@ -19,6 +19,89 @@ class BuildApiMixin(object):
               forcerm=False, dockerfile=None, container_limits=None,
               decode=False, buildargs=None, gzip=False, shmsize=None,
               labels=None):
+        """
+        Similar to the ``docker build`` command. Either ``path`` or ``fileobj``
+        needs to be set. ``path`` can be a local path (to a directory
+        containing a Dockerfile) or a remote URL. ``fileobj`` must be a
+        readable file-like object to a Dockerfile.
+
+        If you have a tar file for the Docker build context (including a
+        Dockerfile) already, pass a readable file-like object to ``fileobj``
+        and also pass ``custom_context=True``. If the stream is compressed
+        also, set ``encoding`` to the correct value (e.g ``gzip``).
+
+        Example:
+            >>> from io import BytesIO
+            >>> from docker import Client
+            >>> dockerfile = '''
+            ... # Shared Volume
+            ... FROM busybox:buildroot-2014.02
+            ... VOLUME /data
+            ... CMD ["/bin/sh"]
+            ... '''
+            >>> f = BytesIO(dockerfile.encode('utf-8'))
+            >>> cli = Client(base_url='tcp://127.0.0.1:2375')
+            >>> response = [line for line in cli.build(
+            ...     fileobj=f, rm=True, tag='yourname/volume'
+            ... )]
+            >>> response
+            ['{"stream":" ---\\u003e a9eb17255234\\n"}',
+             '{"stream":"Step 1 : VOLUME /data\\n"}',
+             '{"stream":" ---\\u003e Running in abdc1e6896c6\\n"}',
+             '{"stream":" ---\\u003e 713bca62012e\\n"}',
+             '{"stream":"Removing intermediate container abdc1e6896c6\\n"}',
+             '{"stream":"Step 2 : CMD [\\"/bin/sh\\"]\\n"}',
+             '{"stream":" ---\\u003e Running in dba30f2a1a7e\\n"}',
+             '{"stream":" ---\\u003e 032b8b2855fc\\n"}',
+             '{"stream":"Removing intermediate container dba30f2a1a7e\\n"}',
+             '{"stream":"Successfully built 032b8b2855fc\\n"}']
+
+        Args:
+            path (str): Path to the directory containing the Dockerfile
+            fileobj: A file object to use as the Dockerfile. (Or a file-like
+                object)
+            tag (str): A tag to add to the final image
+            quiet (bool): Whether to return the status
+            nocache (bool): Don't use the cache when set to ``True``
+            rm (bool): Remove intermediate containers. The ``docker build``
+                command now defaults to ``--rm=true``, but we have kept the old
+                default of `False` to preserve backward compatibility
+            stream (bool): *Deprecated for API version > 1.8 (always True)*.
+                Return a blocking generator you can iterate over to retrieve
+                build output as it happens
+            timeout (int): HTTP timeout
+            custom_context (bool): Optional if using ``fileobj``
+            encoding (str): The encoding for a stream. Set to ``gzip`` for
+                compressing
+            pull (bool): Downloads any updates to the FROM image in Dockerfiles
+            forcerm (bool): Always remove intermediate containers, even after
+                unsuccessful builds
+            dockerfile (str): path within the build context to the Dockerfile
+            buildargs (dict): A dictionary of build arguments
+            container_limits (dict): A dictionary of limits applied to each
+                container created by the build process. Valid keys:
+
+                - memory (int): set memory limit for build
+                - memswap (int): Total memory (memory + swap), -1 to disable
+                    swap
+                - cpushares (int): CPU shares (relative weight)
+                - 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``.
+            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.
+
+        Returns:
+            A generator for the build output.
+
+        Raises:
+            :py:class:`docker.errors.APIError`
+                If the server returns an error.
+            ``TypeError``
+                If neither ``path`` nor ``fileobj`` is specified.
+        """
         remote = context = None
         headers = {}
         container_limits = container_limits or {}

docker/api/client.py

@@ -51,8 +51,32 @@ class APIClient(
     """
     A low-level client for the Docker Remote API.
 
-    Each method maps one-to-one with a REST API endpoint, so calling each
-    method results in a single API call.
+    Example:
+
+        >>> import docker
+        >>> client = docker.APIClient(base_url='unix://var/run/docker.sock')
+        >>> client.version()
+        {u'ApiVersion': u'1.24',
+         u'Arch': u'amd64',
+         u'BuildTime': u'2016-09-27T23:38:15.810178467+00:00',
+         u'Experimental': True,
+         u'GitCommit': u'45bed2c',
+         u'GoVersion': u'go1.6.3',
+         u'KernelVersion': u'4.4.22-moby',
+         u'Os': u'linux',
+         u'Version': u'1.12.2-rc1'}
+
+    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, base_url=None, version=None,
                  timeout=DEFAULT_TIMEOUT_SECONDS, tls=False,

docker/api/daemon.py

@@ -8,6 +8,36 @@ from ..constants import INSECURE_REGISTRY_DEPRECATION_WARNING
 
 class DaemonApiMixin(object):
     def events(self, since=None, until=None, filters=None, decode=None):
+        """
+        Get real-time events from the server. Similar to the ``docker events``
+        command.
+
+        Args:
+            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:
+            (generator): A blocking generator you can iterate over to retrieve
+                events as they happen.
+
+        Raises:
+            :py:class:`docker.errors.APIError`
+                If the server returns an error.
+
+        Example:
+
+            >>> for event in client.events()
+            ...   print event
+            {u'from': u'image/with:tag',
+             u'id': u'container-id',
+             u'status': u'start',
+             u'time': 1423339459}
+            ...
+        """
+
         if isinstance(since, datetime):
             since = utils.datetime_to_timestamp(since)
 
@@ -29,10 +59,42 @@ class DaemonApiMixin(object):
         )
 
     def info(self):
+        """
+        Display system-wide information. Identical to the ``docker info``
+        command.
+
+        Returns:
+            (dict): The info as a dict
+
+        Raises:
+            :py:class:`docker.errors.APIError`
+                If the server returns an error.
+        """
         return self._result(self._get(self._url("/info")), True)
 
     def login(self, username, password=None, email=None, registry=None,
               reauth=False, insecure_registry=False, dockercfg_path=None):
+        """
+        Authenticate with a registry. Similar to the ``docker login`` command.
+
+        Args:
+            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 refresh existing authentication on the
+                Docker server.
+            dockercfg_path (str): Use a custom path for the ``.dockercfg`` file
+        (default ``$HOME/.dockercfg``)
+
+        Returns:
+            (dict): The response from the login request
+
+        Raises:
+            :py:class:`docker.errors.APIError`
+                If the server returns an error.
+        """
         if insecure_registry:
             warnings.warn(
                 INSECURE_REGISTRY_DEPRECATION_WARNING.format('login()'),
@@ -68,8 +130,30 @@ class DaemonApiMixin(object):
         return self._result(response, json=True)
 
     def ping(self):
+        """
+        Checks the server is responsive. An exception will be raised if it
+        isn't responding.
+
+        Returns:
+            (bool) The response from the server.
+
+        Raises:
+            :py:class:`docker.errors.APIError`
+                If the server returns an error.
+        """
         return self._result(self._get(self._url('/_ping'))) == 'OK'
 
     def version(self, api_version=True):
+        """
+        Returns version information from the server. Similar to the ``docker
+        version`` command.
+
+        Returns:
+            (dict): The server version information
+
+        Raises:
+            :py:class:`docker.errors.APIError`
+                If the server returns an error.
+        """
         url = self._url("/version", versioned_api=api_version)
         return self._result(self._get(url), json=True)

docker/api/exec_api.py

@@ -9,6 +9,28 @@ class ExecApiMixin(object):
     @utils.check_resource
     def exec_create(self, container, cmd, stdout=True, stderr=True,
                     stdin=False, tty=False, privileged=False, user=''):
+        """
+        Sets up an exec instance in a running container.
+
+        Args:
+            container (str): Target container where exec instance will be
+                created
+            cmd (str or list): Command to be executed
+            stdout (bool): Attach to stdout. Default: ``True``
+            stderr (bool): Attach to stderr. Default: ``True``
+            stdin (bool): Attach to stdin. Default: ``False``
+            tty (bool): Allocate a pseudo-TTY. Default: False
+            privileged (bool): Run as privileged.
+            user (str): User to execute command as. Default: root
+
+        Returns:
+            (dict): A dictionary with an exec ``Id`` key.
+
+        Raises:
+            :py:class:`docker.errors.APIError`
+                If the server returns an error.
+        """
+
         if privileged and utils.compare_version('1.19', self._version) < 0:
             raise errors.InvalidVersion(
                 'Privileged exec is not supported in API < 1.19'
@@ -37,6 +59,19 @@ class ExecApiMixin(object):
 
     @utils.minimum_version('1.16')
     def exec_inspect(self, exec_id):
+        """
+        Return low-level information about an exec command.
+
+        Args:
+            exec_id (str): ID of the exec instance
+
+        Returns:
+            (dict): Dictionary of values returned by the endpoint.
+
+        Raises:
+            :py:class:`docker.errors.APIError`
+                If the server returns an error.
+        """
         if isinstance(exec_id, dict):
             exec_id = exec_id.get('Id')
         res = self._get(self._url("/exec/{0}/json", exec_id))
@@ -44,6 +79,15 @@ class ExecApiMixin(object):
 
     @utils.minimum_version('1.15')
     def exec_resize(self, exec_id, height=None, width=None):
+        """
+        Resize the tty session used by the specified exec command.
+
+        Args:
+            exec_id (str): ID of the exec instance
+            height (int): Height of tty session
+            width (int): Width of tty session
+        """
+
         if isinstance(exec_id, dict):
             exec_id = exec_id.get('Id')
 
@@ -55,6 +99,24 @@ class ExecApiMixin(object):
     @utils.minimum_version('1.15')
     def exec_start(self, exec_id, detach=False, tty=False, stream=False,
                    socket=False):
+        """
+        Start a previously set up exec instance.
+
+        Args:
+            exec_id (str): ID of the exec instance
+            detach (bool): If true, detach from the exec command.
+                Default: False
+            tty (bool): Allocate a pseudo-TTY. Default: False
+            stream (bool): Stream response data. Default: False
+
+        Returns:
+            (generator or str): If ``stream=True``, a generator yielding
+            response chunks. A string containing response data otherwise.
+
+        Raises:
+            :py:class:`docker.errors.APIError`
+                If the server returns an error.
+        """
         # we want opened socket if socket == True
         if isinstance(exec_id, dict):
             exec_id = exec_id.get('Id')

docker/api/network.py

@@ -8,6 +8,21 @@ from ..utils import version_lt
 class NetworkApiMixin(object):
     @minimum_version('1.21')
     def networks(self, names=None, ids=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
+
+        Returns:
+            (dict): List of network objects.
+
+        Raises:
+            :py:class:`docker.errors.APIError`
+                If the server returns an error.
+        """
+
         filters = {}
         if names:
             filters['name'] = names
@@ -24,6 +39,51 @@ class NetworkApiMixin(object):
     def create_network(self, name, driver=None, options=None, ipam=None,
                        check_duplicate=None, internal=False, labels=None,
                        enable_ipv6=False):
+        """
+        Create a network. Similar to the ``docker network create``.
+
+        Args:
+            name (str): Name of the network
+            driver (str): Name of the driver used to create the network
+            options (dict): Driver options as a key-value dictionary
+            ipam (dict): Optional custom IP scheme for the network.
+                Created with :py:meth:`~docker.utils.create_ipam_config`.
+            check_duplicate (bool): Request daemon to check for networks with
+                same name. Default: ``True``.
+            internal (bool): Restrict external access to the network. Default
+                ``False``.
+            labels (dict): Map of labels to set on the network. Default
+                ``None``.
+            enable_ipv6 (bool): Enable IPv6 on the network. Default ``False``.
+
+        Returns:
+            (dict): The created network reference object
+
+        Raises:
+            :py:class:`docker.errors.APIError`
+                If the server returns an error.
+
+        Example:
+            A network using the bridge driver:
+
+                >>> client.create_network("network1", driver="bridge")
+
+            You can also create more advanced networks with custom IPAM
+            configurations. For example, setting the subnet to
+            ``192.168.52.0/24`` and gateway address to ``192.168.52.254``.
+
+            .. code-block:: python
+
+                >>> ipam_pool = docker.utils.create_ipam_pool(
+                    subnet='192.168.52.0/24',
+                    gateway='192.168.52.254'
+                )
+                >>> ipam_config = docker.utils.create_ipam_config(
+                    pool_configs=[ipam_pool]
+                )
+                >>> docker_client.create_network("network1", driver="bridge",
+                                                 ipam=ipam_config)
+        """
         if options is not None and not isinstance(options, dict):
             raise TypeError('options must be a dictionary')
 
@@ -63,12 +123,24 @@ class NetworkApiMixin(object):
 
     @minimum_version('1.21')
     def remove_network(self, net_id):
+        """
+        Remove a network. Similar to the ``docker network rm`` command.
+
+        Args:
+            net_id (str): The network's id
+        """
         url = self._url("/networks/{0}", net_id)
         res = self._delete(url)
         self._raise_for_status(res)
 
     @minimum_version('1.21')
     def inspect_network(self, net_id):
+        """
+        Get detailed information about a network.
+
+        Args:
+            net_id (str): ID of network
+        """
         url = self._url("/networks/{0}", net_id)
         res = self._get(url)
         return self._result(res, json=True)
@@ -79,6 +151,24 @@ class NetworkApiMixin(object):
                                      ipv4_address=None, ipv6_address=None,
                                      aliases=None, links=None,
                                      link_local_ips=None):
+        """
+        Connect a container to a network.
+
+        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``.
+            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.
+        """
         data = {
             "Container": container,
             "EndpointConfig": self.create_endpoint_config(
@@ -95,6 +185,16 @@ class NetworkApiMixin(object):
     @minimum_version('1.21')
     def disconnect_container_from_network(self, container, net_id,
                                           force=False):
+        """
+        Disconnect a container from a network.
+
+        Args:
+            container (str): container ID or name to be disconnected from the
+                network
+            net_id (str): network ID
+            force (bool): Force the container to disconnect from a network.
+                Default: ``False``
+        """
         data = {"Container": container}
         if force:
             if version_lt(self._version, '1.22'):

docker/api/service.py

@@ -9,6 +9,32 @@ class ServiceApiMixin(object):
             update_config=None, networks=None, endpoint_config=None,
             endpoint_spec=None
     ):
+        """
+        Create a service.
+
+        Args:
+            task_template (dict): 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
+                access and load balance a service. Default: ``None``.
+
+        Returns:
+            A dictionary containing an ``ID`` key for the newly created
+            service.
+
+        Raises:
+            :py:class:`docker.errors.APIError`
+                If the server returns an error.
+        """
         if endpoint_config is not None:
             warnings.warn(
                 'endpoint_config has been renamed to endpoint_spec.',
@@ -43,18 +69,58 @@ class ServiceApiMixin(object):
     @utils.minimum_version('1.24')
     @utils.check_resource
     def inspect_service(self, service):
+        """
+        Return information about a service.
+
+        Args:
+            service (str): Service name or ID
+
+        Returns:
+            ``True`` if successful.
+
+        Raises:
+            :py:class:`docker.errors.APIError`
+                If the server returns an error.
+        """
         url = self._url('/services/{0}', service)
         return self._result(self._get(url), True)
 
     @utils.minimum_version('1.24')
     @utils.check_resource
     def inspect_task(self, task):
+        """
+        Retrieve information about a task.
+
+        Args:
+            task (str): Task ID
+
+        Returns:
+            (dict): Information about the task.
+
+        Raises:
+            :py:class:`docker.errors.APIError`
+                If the server returns an error.
+        """
         url = self._url('/tasks/{0}', task)
         return self._result(self._get(url), True)
 
     @utils.minimum_version('1.24')
     @utils.check_resource
     def remove_service(self, service):
+        """
+        Stop and remove a service.
+
+        Args:
+            service (str): Service name or ID
+
+        Returns:
+            ``True`` if successful.
+
+        Raises:
+            :py:class:`docker.errors.APIError`
+                If the server returns an error.
+        """
+
         url = self._url('/services/{0}', service)
         resp = self._delete(url)
         self._raise_for_status(resp)
@@ -62,6 +128,20 @@ class ServiceApiMixin(object):
 
     @utils.minimum_version('1.24')
     def services(self, filters=None):
+        """
+        List services.
+
+        Args:
+            filters (dict): Filters to process on the nodes list. Valid
+                filters: ``id`` and ``name``. Default: ``None``.
+
+        Returns:
+            A list of dictionaries containing data about each service.
+
+        Raises:
+            :py:class:`docker.errors.APIError`
+                If the server returns an error.
+        """
         params = {
             'filters': utils.convert_filters(filters) if filters else None
         }
@@ -70,6 +150,22 @@ class ServiceApiMixin(object):
 
     @utils.minimum_version('1.24')
     def tasks(self, filters=None):
+        """
+        Retrieve a list of tasks.
+
+        Args:
+            filters (dict): A map of filters to process on the tasks list.
+                Valid filters: ``id``, ``name``, ``service``, ``node``,
+                ``label`` and ``desired-state``.
+
+        Returns:
+            (list): List of task dictionaries.
+
+        Raises:
+            :py:class:`docker.errors.APIError`
+                If the server returns an error.
+        """
+
         params = {
             'filters': utils.convert_filters(filters) if filters else None
         }
@@ -82,7 +178,37 @@ class ServiceApiMixin(object):
                        labels=None, mode=None, update_config=None,
                        networks=None, endpoint_config=None,
                        endpoint_spec=None):
+        """
+        Update a service.
+
+        Args:
+            service (string): A service identifier (either its name or service
+                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.
+            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
+                access and load balance a service. Default: ``None``.
+
+        Returns:
+            ``True`` if successful.
 
+        Raises:
+            :py:class:`docker.errors.APIError`
+                If the server returns an error.
+        """
         if endpoint_config is not None:
             warnings.warn(
                 'endpoint_config has been renamed to endpoint_spec.',

docker/api/volume.py

@@ -5,6 +5,32 @@ from .. import utils
 class VolumeApiMixin(object):
     @utils.minimum_version('1.21')
     def volumes(self, filters=None):
+        """
+        List volumes currently registered by the docker daemon. Similar to the
+        ``docker volume ls`` command.
+
+        Args:
+            filters (dict): Server-side list filtering options.
+
+        Returns:
+            (dict): Dictionary with list of volume objects as value of the
+            ``Volumes`` key.
+
+        Raises:
+            :py:class:`docker.errors.APIError`
+                If the server returns an error.
+
+        Example:
+
+            >>> cli.volumes()
+            {u'Volumes': [{u'Driver': u'local',
+               u'Mountpoint': u'/var/lib/docker/volumes/foobar/_data',
+               u'Name': u'foobar'},
+              {u'Driver': u'local',
+               u'Mountpoint': u'/var/lib/docker/volumes/baz/_data',
+               u'Name': u'baz'}]}
+        """
+
         params = {
             'filters': utils.convert_filters(filters) if filters else None
         }
@@ -13,6 +39,34 @@ class VolumeApiMixin(object):
 
     @utils.minimum_version('1.21')
     def create_volume(self, name, driver=None, driver_opts=None, labels=None):
+        """
+        Create and register a named volume
+
+        Args:
+            name (str): Name of the volume
+            driver (str): Name of the driver used to create the volume
+            driver_opts (dict): Driver options as a key-value dictionary
+            labels (dict): Labels to set on the volume
+
+        Returns:
+            (dict): The created volume reference object
+
+        Raises:
+            :py:class:`docker.errors.APIError`
+                If the server returns an error.
+
+        Example:
+
+            >>> volume = cli.create_volume(name='foobar', driver='local',
+                    driver_opts={'foo': 'bar', 'baz': 'false'},
+                    labels={"key": "value"})
+            >>> print(volume)
+            {u'Driver': u'local',
+             u'Labels': {u'key': u'value'},
+             u'Mountpoint': u'/var/lib/docker/volumes/foobar/_data',
+             u'Name': u'foobar'}
+
+        """
         url = self._url('/volumes/create')
         if driver_opts is not None and not isinstance(driver_opts, dict):
             raise TypeError('driver_opts must be a dictionary')
@@ -36,11 +90,42 @@ class VolumeApiMixin(object):
 
     @utils.minimum_version('1.21')
     def inspect_volume(self, name):
+        """
+        Retrieve volume info by name.
+
+        Args:
+            name (str): volume name
+
+        Returns:
+            (dict): Volume information dictionary
+
+        Raises:
+            :py:class:`docker.errors.APIError`
+                If the server returns an error.
+
+        Example:
+
+            >>> cli.inspect_volume('foobar')
+            {u'Driver': u'local',
+             u'Mountpoint': u'/var/lib/docker/volumes/foobar/_data',
+             u'Name': u'foobar'}
+
+        """
         url = self._url('/volumes/{0}', name)
         return self._result(self._get(url), True)
 
     @utils.minimum_version('1.21')
     def remove_volume(self, name):
+        """
+        Remove a volume. Similar to the ``docker volume rm`` command.
+
+        Args:
+            name (str): The volume's name
+
+        Raises:
+
+        ``docker.errors.APIError``: If volume failed to remove.
+        """
         url = self._url('/volumes/{0}', name)
         resp = self._delete(url)
         self._raise_for_status(resp)

docker/tls.py

@@ -5,6 +5,20 @@ from . import errors, ssladapter
 
 
 class TLSConfig(object):
+    """
+    TLS configuration.
+
+    Args:
+        client_cert (tuple of str): Path to client cert, path to client key.
+        ca_cert (str): Path to CA cert file.
+        verify (bool or str): This can be ``False`` or a path to a CA cert
+            file.
+        ssl_version (int): A valid `SSL version`_.
+        assert_hostname (bool): Verify the hostname of the server.
+
+    .. _`SSL version`:
+        https://docs.python.org/3.5/library/ssl.html#ssl.PROTOCOL_TLSv1
+    """
     cert = None
     ca_cert = None
     verify = None
@@ -57,6 +71,9 @@ class TLSConfig(object):
             )
 
     def configure_client(self, client):
+        """
+        Configure a client with these TLS options.
+        """
         client.ssl_version = self.ssl_version
 
         if self.verify and self.ca_cert:

docker/utils/utils.py

@@ -39,6 +39,38 @@ BYTE_UNITS = {
 
 def create_ipam_pool(subnet=None, iprange=None, gateway=None,
                      aux_addresses=None):
+    """
+    Create an IPAM pool config dictionary to be added to the
+    ``pool_configs`` parameter of
+    :py:meth:`~docker.utils.create_ipam_config`.
+
+    Args:
+
+        subnet (str): Custom subnet for this IPAM pool using the CIDR
+            notation. Defaults to ``None``.
+        iprange (str): Custom IP range for endpoints in this IPAM pool using
+            the CIDR notation. Defaults to ``None``.
+        gateway (str): Custom IP address for the pool's gateway.
+        aux_addresses (dict): A dictionary of ``key -> ip_address``
+            relationships specifying auxiliary addresses that need to be
+            allocated by the IPAM driver.
+
+    Returns:
+        (dict) An IPAM pool config
+
+    Example:
+
+        >>> ipam_pool = docker.utils.create_ipam_pool(
+            subnet='124.42.0.0/16',
+            iprange='124.42.0.0/24',
+            gateway='124.42.0.254',
+            aux_addresses={
+                'reserved1': '124.42.1.1'
+            }
+        )
+        >>> ipam_config = docker.utils.create_ipam_config(
+                pool_configs=[ipam_pool])
+    """
     return {
         'Subnet': subnet,
         'IPRange': iprange,
@@ -48,6 +80,25 @@ def create_ipam_pool(subnet=None, iprange=None, gateway=None,
 
 
 def create_ipam_config(driver='default', pool_configs=None, options=None):
+    """
+    Create an IPAM (IP Address Management) config dictionary to be used with
+    :py:meth:`~docker.api.network.NetworkApiMixin.create_network`.
+
+    Args:
+        driver (str): The IPAM driver to use. Defaults to ``default``.
+        pool_configs (list): A list of pool configuration dictionaries as
+            created by :py:meth:`~docker.utils.create_ipam_pool`. Defaults to
+            empty list.
+
+    Returns:
+        (dict) An IPAM config.
+
+    Example:
+
+        >>> ipam_config = docker.utils.create_ipam_config(driver='default')
+        >>> network = client.create_network('network1', ipam=ipam_config)
+
+    """
     if options is not None and not isinstance(options, dict):
         raise TypeError('IPAM options must be a dictionary')