Rename Client -> DockerClient

Replace references to old Client with APIClient
Moved contents of services.md to appropriate locations

Signed-off-by: Joffrey F <[email protected]>

Author: shin-

docker/__init__.py

@@ -1,6 +1,6 @@
 # flake8: noqa
 from .api import APIClient
-from .client import Client, from_env
+from .client import DockerClient, from_env
 from .version import version, version_info
 
 __version__ = version

docker/api/build.py

@@ -32,15 +32,15 @@ def build(self, path=None, tag=None, quiet=False, fileobj=None,
 
         Example:
             >>> from io import BytesIO
-            >>> from docker import Client
+            >>> from docker import APIClient
             >>> 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')
+            >>> cli = APIClient(base_url='tcp://127.0.0.1:2375')
             >>> response = [line for line in cli.build(
             ...     fileobj=f, rm=True, tag='yourname/volume'
             ... )]

docker/api/container.py

@@ -215,7 +215,7 @@ def copy(self, container, resource):
         """
         if utils.version_gte(self._version, '1.20'):
             warnings.warn(
-                'Client.copy() is deprecated for API version >= 1.20, '
+                'APIClient.copy() is deprecated for API version >= 1.20, '
                 'please use get_archive() instead',
                 DeprecationWarning
             )

docker/api/swarm.py

@@ -77,7 +77,7 @@ def init_swarm(self, advertise_addr=None, listen_addr='0.0.0.0:2377',
             force_new_cluster (bool): Force creating a new Swarm, even if
                 already part of one. Default: False
             swarm_spec (dict): Configuration settings of the new Swarm. Use
-                ``Client.create_swarm_spec`` to generate a valid
+                ``APIClient.create_swarm_spec`` to generate a valid
                 configuration. Default: None
 
         Returns:

docker/client.py

@@ -9,14 +9,14 @@
 from .utils import kwargs_from_env
 
 
-class Client(object):
+class DockerClient(object):
     """
     A client for communicating with a Docker server.
 
     Example:
 
         >>> import docker
-        >>> client = Client(base_url='unix://var/run/docker.sock')
+        >>> client = docker.DockerClient(base_url='unix://var/run/docker.sock')
 
     Args:
         base_url (str): URL to the Docker server. For example,
@@ -155,7 +155,7 @@ def version(self, *args, **kwargs):
     version.__doc__ = APIClient.version.__doc__
 
     def __getattr__(self, name):
-        s = ["'Client' object has no attribute '{}'".format(name)]
+        s = ["'DockerClient' object has no attribute '{}'".format(name)]
         # If a user calls a method on APIClient, they
         if hasattr(APIClient, name):
             s.append("In Docker SDK for Python 2.0, this method is now on the "
@@ -164,4 +164,4 @@ def __getattr__(self, name):
         raise AttributeError(' '.join(s))
 
 
-from_env = Client.from_env
+from_env = DockerClient.from_env

docker/models/images.py

@@ -238,7 +238,7 @@ def pull(self, name, **kwargs):
             tag (str): The tag to pull
             insecure_registry (bool): Use an insecure registry
             auth_config (dict): Override the credentials that
-                :py:meth:`~docker.client.Client.login` has set for
+                :py:meth:`~docker.client.DockerClient.login` has set for
                 this request. ``auth_config`` should contain the ``username``
                 and ``password`` keys to be valid.
 

docker/types/services.py

@@ -4,6 +4,26 @@
 
 
 class TaskTemplate(dict):
+    """
+    Describe the task specification to be used when creating or updating a
+    service.
+
+    Args:
+
+    * container_spec (dict): Container settings for containers started as part
+      of this task. See the :py:class:`~docker.types.services.ContainerSpec`
+      for details.
+    * log_driver (dict): Log configuration for containers created as part of
+      the service. See the :py:class:`~docker.types.services.DriverConfig`
+      class for details.
+    * resources (dict): Resource requirements which apply to each individual
+      container created as part of the service. See the
+      :py:class:`~docker.types.services.Resources` class for details.
+    * restart_policy (dict): Specification for the restart policy which applies
+      to containers created as part of this service. See the
+      :py:class:`~docker.types.services.RestartPolicy` class for details.
+    * placement (list): A list of constraints.
+    """
     def __init__(self, container_spec, resources=None, restart_policy=None,
                  placement=None, log_driver=None):
         self['ContainerSpec'] = container_spec
@@ -36,6 +56,25 @@ def placement(self):
 
 
 class ContainerSpec(dict):
+    """
+    Describes the behavior of containers that are part of a task, and is used
+    when declaring a :py:class:`~docker.types.services.TaskTemplate`.
+
+    Args:
+
+    * image (string): The image name to use for the container.
+    * command (string or list):  The command to be run in the image.
+    * args (list): Arguments to the command.
+    * env (dict): Environment variables.
+    * dir (string): The working directory for commands to run in.
+    * user (string): The user inside the container.
+    * labels (dict): A map of labels to associate with the service.
+    * mounts (list): A list of specifications for mounts to be added to
+      containers created as part of the service. See the
+      :py:class:`~docker.types.services.Mount` class for details.
+    * stop_grace_period (int): Amount of time to wait for the container to
+      terminate before forcefully killing it.
+    """
     def __init__(self, image, command=None, args=None, env=None, workdir=None,
                  user=None, labels=None, mounts=None, stop_grace_period=None):
         from ..utils import split_command  # FIXME: circular import
@@ -70,6 +109,28 @@ def __init__(self, image, command=None, args=None, env=None, workdir=None,
 
 
 class Mount(dict):
+    """
+    Describes a mounted folder's configuration inside a container. A list of
+    ``Mount``s would be used as part of a
+    :py:class:`~docker.types.services.ContainerSpec`.
+
+    Args:
+
+    * target (string): Container path.
+    * source (string): Mount source (e.g. a volume name or a host path).
+    * type (string): The mount type (``bind`` or ``volume``).
+      Default: ``volume``.
+    * read_only (bool): Whether the mount should be read-only.
+    * propagation (string): A propagation mode with the value ``[r]private``,
+      ``[r]shared``, or ``[r]slave``. Only valid for the ``bind`` type.
+    * no_copy (bool): False if the volume should be populated with the data
+      from the target. Default: ``False``. Only valid for the ``volume`` type.
+    * labels (dict): User-defined name and labels for the volume. Only valid
+      for the ``volume`` type.
+    * driver_config (dict): Volume driver configuration.
+      See the :py:class:`~docker.types.services.DriverConfig` class for
+      details. Only valid for the ``volume`` type.
+    """
     def __init__(self, target, source, type='volume', read_only=False,
                  propagation=None, no_copy=False, labels=None,
                  driver_config=None):
@@ -124,6 +185,17 @@ def parse_mount_string(cls, string):
 
 
 class Resources(dict):
+    """
+    Configures resource allocation for containers when made part of a
+    :py:class:`~docker.types.services.ContainerSpec`.
+
+    Args:
+
+    * cpu_limit (int): CPU limit in units of 10^9 CPU shares.
+    * mem_limit (int): Memory limit in Bytes.
+    * cpu_reservation (int): CPU reservation in units of 10^9 CPU shares.
+    * mem_reservation (int): Memory reservation in Bytes.
+    """
     def __init__(self, cpu_limit=None, mem_limit=None, cpu_reservation=None,
                  mem_reservation=None):
         limits = {}
@@ -144,6 +216,19 @@ def __init__(self, cpu_limit=None, mem_limit=None, cpu_reservation=None,
 
 
 class UpdateConfig(dict):
+    """
+
+    Used to specify the way container updates should be performed by a service.
+
+    Args:
+
+    * parallelism (int): Maximum number of tasks to be updated in one iteration
+      (0 means unlimited parallelism). Default: 0.
+    * delay (int): Amount of time between updates.
+    * failure_action (string): Action to take if an updated task fails to run,
+      or stops running during the update. Acceptable values are ``continue``
+      and ``pause``. Default: ``continue``
+    """
     def __init__(self, parallelism=0, delay=None, failure_action='continue'):
         self['Parallelism'] = parallelism
         if delay is not None:
@@ -165,6 +250,19 @@ class RestartConditionTypesEnum(object):
 
 
 class RestartPolicy(dict):
+    """
+    Used when creating a :py:class:`~docker.types.services.ContainerSpec`,
+    dictates whether a container should restart after stopping or failing.
+
+    * condition (string): Condition for restart (``none``, ``on-failure``,
+      or ``any``). Default: `none`.
+    * delay (int): Delay between restart attempts. Default: 0
+    * attempts (int): Maximum attempts to restart a given container before
+      giving up. Default value is 0, which is ignored.
+    * window (int): Time window used to evaluate the restart policy. Default
+      value is 0, which is unbounded.
+    """
+
     condition_types = RestartConditionTypesEnum
 
     def __init__(self, condition=RestartConditionTypesEnum.NONE, delay=0,
@@ -181,13 +279,37 @@ def __init__(self, condition=RestartConditionTypesEnum.NONE, delay=0,
 
 
 class DriverConfig(dict):
+    """
+    Indicates which driver to use, as well as its configuration. Can be used
+    as ``log_driver`` in a :py:class:`~docker.types.services.ContainerSpec`,
+    and for the `driver_config` in a volume
+    :py:class:`~docker.types.services.Mount`.
+
+    Args:
+
+    * name (string): Name of the driver to use.
+    * options (dict): Driver-specific options. Default: ``None``.
+    """
     def __init__(self, name, options=None):
         self['Name'] = name
         if options:
             self['Options'] = options
 
 
 class EndpointSpec(dict):
+    """
+    Describes properties to access and load-balance a service.
+
+    Args:
+
+    * mode (string): The mode of resolution to use for internal load balancing
+      between tasks (``'vip'`` or ``'dnsrr'``). Defaults to ``'vip'`` if not
+      provided.
+    * ports (dict): Exposed ports that this service is accessible on from the
+      outside, in the form of ``{ target_port: published_port }`` or
+      ``{ target_port: (published_port, protocol) }``. Ports can only be
+      provided if the ``vip`` resolution mode is used.
+    """
     def __init__(self, mode=None, ports=None):
         if ports:
             self['Ports'] = convert_service_ports(ports)

docker/utils/utils.py

@@ -714,7 +714,7 @@ def create_host_config(binds=None, port_bindings=None, lxc_conf=None,
     if not version:
         warnings.warn(
             'docker.utils.create_host_config() is deprecated. Please use '
-            'Client.create_host_config() instead.'
+            'APIClient.create_host_config() instead.'
         )
         version = constants.DEFAULT_DOCKER_API_VERSION
 

docs/client.rst

@@ -6,14 +6,14 @@ Client
 Creating a client
 -----------------
 
-To communicate with the Docker daemon, you first need to instantiate a client. The easiest way to do that is by calling the function :py:func:`~docker.client.from_env`. It can also be configured manually by instantiating a :py:class:`~docker.client.Client` class.
+To communicate with the Docker daemon, you first need to instantiate a client. The easiest way to do that is by calling the function :py:func:`~docker.client.from_env`. It can also be configured manually by instantiating a :py:class:`~docker.client.DockerClient` class.
 
 .. autofunction:: from_env()
 
 Client reference
 ----------------
 
-.. autoclass:: Client()
+.. autoclass:: DockerClient()
 
   .. autoattribute:: containers
   .. autoattribute:: images