Merge branch 'main' into support-checkpoint-restore

docker/api/container.py

@@ -1054,7 +1054,7 @@ class ContainerApiMixin:
             container (str): The container where the file(s) will be extracted
             path (str): Path inside the container where the file(s) will be
                 extracted. Must exist.
-            data (bytes): tar data to be extracted
+            data (bytes or stream): tar data to be extracted
 
         Returns:
             (bool): True if the call succeeds.
@@ -1231,7 +1231,7 @@ class ContainerApiMixin:
         self._raise_for_status(res)
 
     @utils.check_resource('container')
-    def stats(self, container, decode=None, stream=True):
+    def stats(self, container, decode=None, stream=True, one_shot=None):
         """
         Stream statistics for a specific container. Similar to the
         ``docker stats`` command.
@@ -1243,6 +1243,9 @@ class ContainerApiMixin:
                 False by default.
             stream (bool): If set to false, only the current stats will be
                 returned instead of a stream. True by default.
+            one_shot (bool): If set to true, Only get a single stat instead of
+                waiting for 2 cycles. Must be used with stream=false. False by
+                default.
 
         Raises:
             :py:class:`docker.errors.APIError`
@@ -1250,16 +1253,29 @@ class ContainerApiMixin:
 
         """
         url = self._url("/containers/{0}/stats", container)
+        params = {
+            'stream': stream
+        }
+        if one_shot is not None:
+            if utils.version_lt(self._version, '1.41'):
+                raise errors.InvalidVersion(
+                    'one_shot is not supported for API version < 1.41'
+                )
+            params['one-shot'] = one_shot
         if stream:
-            return self._stream_helper(self._get(url, stream=True),
+            if one_shot:
+                raise errors.InvalidArgument(
+                    'one_shot is only available in conjunction with '
+                    'stream=False'
+                )
+            return self._stream_helper(self._get(url, params=params),
                                        decode=decode)
         else:
             if decode:
                 raise errors.InvalidArgument(
                     "decode is only available in conjunction with stream=True"
                 )
-            return self._result(self._get(url, params={'stream': False}),
-                                json=True)
+            return self._result(self._get(url, params=params), json=True)
 
     @utils.check_resource('container')
     def stop(self, container, timeout=None):

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)
 

docker/models/containers.py

@@ -346,7 +346,7 @@ class Container(Model):
         Args:
             path (str): Path inside the container where the file(s) will be
                 extracted. Must exist.
-            data (bytes): tar data to be extracted
+            data (bytes or stream): tar data to be extracted
 
         Returns:
             (bool): True if the call succeeds.

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.

docker/utils/socket.py

@@ -49,7 +49,7 @@ def read(socket, n=4096):
         if is_pipe_ended:
             # npipes don't support duplex sockets, so we interpret
             # a PIPE_ENDED error as a close operation (0-length read).
-            return 0
+            return ''
         raise
 
 

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)

tests/unit/api_container_test.py

@@ -1648,7 +1648,18 @@ class ContainerTest(BaseAPIClientTest):
             'GET',
             url_prefix + 'containers/' + fake_api.FAKE_CONTAINER_ID + '/stats',
             timeout=60,
-            stream=True
+            params={'stream': True}
+        )
+
+    def test_container_stats_with_one_shot(self):
+        self.client.stats(
+            fake_api.FAKE_CONTAINER_ID, stream=False, one_shot=True)
+
+        fake_request.assert_called_with(
+            'GET',
+            url_prefix + 'containers/' + fake_api.FAKE_CONTAINER_ID + '/stats',
+            timeout=60,
+            params={'stream': False, 'one-shot': True}
         )
 
     def test_container_top(self):