Improve docs for service list filters

- add "label" and "mode" to the list of available filter keys in the high-level service API
- add "label" and "mode" to the list of available filter keys in the low-level service API
- add integration tests

Signed-off-by: Alessandro Baldo <git@baldoalessandro.net>

docker/api/service.py

@@ -201,7 +201,8 @@ class ServiceApiMixin(object):
 
         Args:
             filters (dict): Filters to process on the nodes list. Valid
-                filters: ``id`` and ``name``. Default: ``None``.
+                filters: ``id``, ``name`` , ``label`` and ``mode``.
+                Default: ``None``.
 
         Returns:
             A list of dictionaries containing data about each service.

docker/models/services.py

@@ -201,7 +201,8 @@ class ServiceCollection(Collection):
 
         Args:
             filters (dict): Filters to process on the nodes list. Valid
-                filters: ``id`` and ``name``. Default: ``None``.
+                filters: ``id``, ``name`` , ``label`` and ``mode``.
+                Default: ``None``.
 
         Returns:
             (list of :py:class:`Service`): The services.

tests/integration/api_service_test.py

@@ -52,7 +52,7 @@ class ServiceTest(BaseAPIIntegrationTest):
                 return None
             time.sleep(interval)
 
-    def create_simple_service(self, name=None):
+    def create_simple_service(self, name=None, labels=None):
         if name:
             name = 'dockerpytest_{0}'.format(name)
         else:
@@ -62,7 +62,9 @@ class ServiceTest(BaseAPIIntegrationTest):
             BUSYBOX, ['echo', 'hello']
         )
         task_tmpl = docker.types.TaskTemplate(container_spec)
-        return name, self.client.create_service(task_tmpl, name=name)
+        return name, self.client.create_service(
+            task_tmpl, name=name, labels=labels
+        )
 
     @requires_api_version('1.24')
     def test_list_services(self):
@@ -76,6 +78,15 @@ class ServiceTest(BaseAPIIntegrationTest):
         assert len(test_services) == 1
         assert 'dockerpytest_' in test_services[0]['Spec']['Name']
 
+    @requires_api_version('1.24')
+    def test_list_services_filter_by_label(self):
+        test_services = self.client.services(filters={'label': 'test_label'})
+        assert len(test_services) == 0
+        self.create_simple_service(labels={'test_label': 'testing'})
+        test_services = self.client.services(filters={'label': 'test_label'})
+        assert len(test_services) == 1
+        assert test_services[0]['Spec']['Labels']['test_label'] == 'testing'
+
     def test_inspect_service_by_id(self):
         svc_name, svc_id = self.create_simple_service()
         svc_info = self.client.inspect_service(svc_id)