api: add `status` parameter to services list (#3093)

Signed-off-by: Lorin Bucher <lorin@lbtec.dev>

3 files changed, 25 insertions, 1 deletions

diff --git a/docker/api/service.py b/docker/api/service.py
index 371f541..652b7c2 100644
--- a/docker/api/service.py
+++ b/docker/api/service.py
@@ -262,7 +262,7 @@ class ServiceApiMixin:
         return True
 
     @utils.minimum_version('1.24')
-    def services(self, filters=None):
+    def services(self, filters=None, status=None):
         """
         List services.
 
@@ -270,6 +270,8 @@ class ServiceApiMixin:
             filters (dict): Filters to process on the nodes list. Valid
                 filters: ``id``, ``name`` , ``label`` and ``mode``.
                 Default: ``None``.
+            status (bool): Include the service task count of running and
+                desired tasks. Default: ``None``.
 
         Returns:
             A list of dictionaries containing data about each service.
@@ -281,6 +283,12 @@ class ServiceApiMixin:
         params = {
             'filters': utils.convert_filters(filters) if filters else None
         }
+        if status is not None:
+            if utils.version_lt(self._version, '1.41'):
+                raise errors.InvalidVersion(
+                    'status is not supported in API version < 1.41'
+                )
+            params['status'] = status
         url = self._url('/services')
         return self._result(self._get(url, params=params), True)
 
diff --git a/docker/models/services.py b/docker/models/services.py
index 0643874..7003704 100644
--- a/docker/models/services.py
+++ b/docker/models/services.py
@@ -266,6 +266,8 @@ class ServiceCollection(Collection):
             filters (dict): Filters to process on the nodes list. Valid
                 filters: ``id``, ``name`` , ``label`` and ``mode``.
                 Default: ``None``.
+            status (bool): Include the service task count of running and
+                desired tasks. Default: ``None``.
 
         Returns:
             list of :py:class:`Service`: The services.
diff --git a/tests/integration/api_service_test.py b/tests/integration/api_service_test.py
index 8ce7c9d..dec3fa0 100644
--- a/tests/integration/api_service_test.py
+++ b/tests/integration/api_service_test.py
@@ -85,6 +85,20 @@ class ServiceTest(BaseAPIIntegrationTest):
         assert len(test_services) == 1
         assert test_services[0]['Spec']['Labels']['test_label'] == 'testing'
 
+    @requires_api_version('1.41')
+    def test_list_services_with_status(self):
+        test_services = self.client.services()
+        assert len(test_services) == 0
+        self.create_simple_service()
+        test_services = self.client.services(
+            filters={'name': 'dockerpytest_'}, status=False
+        )
+        assert 'ServiceStatus' not in test_services[0]
+        test_services = self.client.services(
+            filters={'name': 'dockerpytest_'}, status=True
+        )
+        assert 'ServiceStatus' in test_services[0]
+
     def test_inspect_service_by_id(self):
         svc_name, svc_id = self.create_simple_service()
         svc_info = self.client.inspect_service(svc_id)