diff options
Diffstat (limited to 'docker/api/service.py')
| -rw-r--r-- | docker/api/service.py | 131 |
1 files changed, 127 insertions, 4 deletions
diff --git a/docker/api/service.py b/docker/api/service.py index 2e41b7c..7708b75 100644 --- a/docker/api/service.py +++ b/docker/api/service.py @@ -1,8 +1,5 @@ import warnings - -from .. import errors -from .. import utils -from ..auth import auth +from .. import auth, errors, utils class ServiceApiMixin(object): @@ -12,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.', @@ -46,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) @@ -65,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 } @@ -73,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 } @@ -85,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.', |