diff options
Diffstat (limited to 'docker')
| -rw-r--r-- | docker/__init__.py | 2 | ||||
| -rw-r--r-- | docker/api/build.py | 4 | ||||
| -rw-r--r-- | docker/api/container.py | 2 | ||||
| -rw-r--r-- | docker/api/swarm.py | 2 | ||||
| -rw-r--r-- | docker/client.py | 8 | ||||
| -rw-r--r-- | docker/models/images.py | 2 | ||||
| -rw-r--r-- | docker/types/services.py | 122 | ||||
| -rw-r--r-- | docker/utils/utils.py | 2 |
8 files changed, 133 insertions, 11 deletions
diff --git a/docker/__init__.py b/docker/__init__.py index acf4b55..96a9ef0 100644 --- a/docker/__init__.py +++ b/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 diff --git a/docker/api/build.py b/docker/api/build.py index 297c9e0..7cf4e0f 100644 --- a/docker/api/build.py +++ b/docker/api/build.py @@ -32,7 +32,7 @@ class BuildApiMixin(object): Example: >>> from io import BytesIO - >>> from docker import Client + >>> from docker import APIClient >>> dockerfile = ''' ... # Shared Volume ... FROM busybox:buildroot-2014.02 @@ -40,7 +40,7 @@ class BuildApiMixin(object): ... 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' ... )] diff --git a/docker/api/container.py b/docker/api/container.py index 72c5852..9b5ce59 100644 --- a/docker/api/container.py +++ b/docker/api/container.py @@ -215,7 +215,7 @@ class ContainerApiMixin(object): """ 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 ) diff --git a/docker/api/swarm.py b/docker/api/swarm.py index a4cb8dd..521076f 100644 --- a/docker/api/swarm.py +++ b/docker/api/swarm.py @@ -77,7 +77,7 @@ class SwarmApiMixin(object): 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: diff --git a/docker/client.py b/docker/client.py index b3b4700..b271eb7 100644 --- a/docker/client.py +++ b/docker/client.py @@ -9,14 +9,14 @@ from .models.volumes import VolumeCollection 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 @@ class Client(object): 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-py 2.0, this method is now on the object " @@ -164,4 +164,4 @@ class Client(object): raise AttributeError(' '.join(s)) -from_env = Client.from_env +from_env = DockerClient.from_env diff --git a/docker/models/images.py b/docker/models/images.py index e0ff1f4..32068e6 100644 --- a/docker/models/images.py +++ b/docker/models/images.py @@ -238,7 +238,7 @@ class ImageCollection(Collection): 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. diff --git a/docker/types/services.py b/docker/types/services.py index a95e0f2..9d5fa1b 100644 --- a/docker/types/services.py +++ b/docker/types/services.py @@ -4,6 +4,26 @@ from .. import errors 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 @@ class TaskTemplate(dict): 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 @@ -66,6 +105,28 @@ class ContainerSpec(dict): 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): @@ -120,6 +181,17 @@ class Mount(dict): 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 = {} @@ -140,6 +212,19 @@ class Resources(dict): 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: @@ -161,6 +246,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, @@ -177,6 +275,17 @@ class RestartPolicy(dict): 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: @@ -184,6 +293,19 @@ class DriverConfig(dict): 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) diff --git a/docker/utils/utils.py b/docker/utils/utils.py index b107f22..26d1bf3 100644 --- a/docker/utils/utils.py +++ b/docker/utils/utils.py @@ -697,7 +697,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 |