Merge pull request #1890 from docker/wait_return

Update wait to always return a dict

9 files changed, 74 insertions, 35 deletions

diff --git a/docker/api/container.py b/docker/api/container.py
index 152a08b..962d8cb 100644
--- a/docker/api/container.py
+++ b/docker/api/container.py
@@ -1207,8 +1207,8 @@ class ContainerApiMixin(object):
                 or ``removed``
 
         Returns:
-            (int or dict): The exit code of the container. Returns the full API
-                response if no ``StatusCode`` field is included.
+            (dict): The API's response as a Python dictionary, including
+                the container's exit code under the ``StatusCode`` attribute.
 
         Raises:
             :py:class:`requests.exceptions.ReadTimeout`
@@ -1226,8 +1226,4 @@ class ContainerApiMixin(object):
             params['condition'] = condition
 
         res = self._post(url, timeout=timeout, params=params)
-        self._raise_for_status(res)
-        json_ = res.json()
-        if 'StatusCode' in json_:
-            return json_['StatusCode']
-        return json_
+        return self._result(res, True)
diff --git a/docker/models/containers.py b/docker/models/containers.py
index e05aa62..963fca4 100644
--- a/docker/models/containers.py
+++ b/docker/models/containers.py
@@ -448,8 +448,8 @@ class Container(Model):
                 or ``removed``
 
         Returns:
-            (int): The exit code of the container. Returns ``-1`` if the API
-            responds without a ``StatusCode`` attribute.
+            (dict): The API's response as a Python dictionary, including
+                the container's exit code under the ``StatusCode`` attribute.
 
         Raises:
             :py:class:`requests.exceptions.ReadTimeout`
@@ -758,7 +758,7 @@ class ContainerCollection(Collection):
                 stdout=stdout, stderr=stderr, stream=True, follow=True
             )
 
-        exit_status = container.wait()
+        exit_status = container.wait()['StatusCode']
         if exit_status != 0:
             out = None
             if not kwargs.get('auto_remove'):
diff --git a/docker/version.py b/docker/version.py
index 5b76748..f141747 100644
--- a/docker/version.py
+++ b/docker/version.py
@@ -1,2 +1,2 @@
-version = "2.8.0-dev"
+version = "3.0.0"
 version_info = tuple([int(d) for d in version.split("-")[0].split(".")])
diff --git a/docs/change-log.md b/docs/change-log.md
index b8298a7..7531ad4 100644
--- a/docs/change-log.md
+++ b/docs/change-log.md
@@ -1,6 +1,47 @@
 Change log
 ==========
 
+3.0.0
+-----
+
+[List of PRs / issues for this release](https://github.com/docker/docker-py/milestone/39?closed=1)
+
+### Breaking changes
+
+* Support for API version < 1.21 has been removed.
+* The following methods have been removed:
+  * `APIClient.copy` has been removed. Users should use `APIClient.get_archive`
+    instead.
+  * `APIClient.insert` has been removed. Users may use `APIClient.put_archive`
+    combined with `APIClient.commit` to replicate the method's behavior.
+  * `utils.ping_registry` and `utils.ping` have been removed.
+* The following parameters have been removed:
+  * `stream` in `APIClient.build`
+  * `cpu_shares`, `cpuset`, `dns`, `mem_limit`, `memswap_limit`,
+    `volume_driver`, `volumes_from` in `APIClient.create_container`. These are
+    all replaced by their equivalent in `create_host_config`
+  * `insecure_registry` in `APIClient.login`, `APIClient.pull`,
+    `APIClient.push`, `DockerClient.images.push` and `DockerClient.images.pull`
+  * `viz` in `APIClient.images`
+* The following parameters have been renamed:
+  * `endpoint_config` in `APIClient.create_service` and
+    `APIClient.update_service` is now `endpoint_spec`
+  * `name` in `DockerClient.images.pull` is now `repository`
+* The return value for the following methods has changed:
+  * `APIClient.wait` and `Container.wait` now return a ``dict`` representing
+    the API's response instead of returning the status code directly.
+  * `DockerClient.images.load` now returns a list of `Image` objects that have
+    for the images that were loaded, instead of a log stream.
+  * `Container.exec_run` now returns a tuple of (exit_code, output) instead of
+    just the output.
+  * `DockerClient.images.build` now returns a tuple of (image, build_logs)
+    instead of just the image object.
+  * `APIClient.export`, `APIClient.get_archive` and `APIClient.get_image` now
+    return generators streaming the raw binary data from the server's response.
+  * When no tag is provided, `DockerClient.images.pull` now returns a list of
+    `Image`s associated to the pulled repository instead of just the `latest`
+    image.
+
 2.7.0
 -----
 
diff --git a/tests/integration/api_container_test.py b/tests/integration/api_container_test.py
index 0925352..01780a7 100644
--- a/tests/integration/api_container_test.py
+++ b/tests/integration/api_container_test.py
@@ -102,7 +102,7 @@ class CreateContainerTest(BaseAPIIntegrationTest):
         container3_id = res2['Id']
         self.tmp_containers.append(container3_id)
         self.client.start(container3_id)
-        assert self.client.wait(container3_id) == 0
+        assert self.client.wait(container3_id)['StatusCode'] == 0
 
         logs = self.client.logs(container3_id)
         if six.PY3:
@@ -169,7 +169,7 @@ class CreateContainerTest(BaseAPIIntegrationTest):
         assert 'Id' in ctnr
         self.tmp_containers.append(ctnr['Id'])
         self.client.start(ctnr)
-        res = self.client.wait(ctnr)
+        res = self.client.wait(ctnr)['StatusCode']
         assert res != 0
 
     def create_container_with_name(self):
@@ -771,7 +771,7 @@ class StartContainerTest(BaseAPIIntegrationTest):
             id = container['Id']
             self.client.start(id)
             self.tmp_containers.append(id)
-            exitcode = self.client.wait(id)
+            exitcode = self.client.wait(id)['StatusCode']
             assert exitcode == 0, cmd
 
 
@@ -781,7 +781,7 @@ class WaitTest(BaseAPIIntegrationTest):
         id = res['Id']
         self.tmp_containers.append(id)
         self.client.start(id)
-        exitcode = self.client.wait(id)
+        exitcode = self.client.wait(id)['StatusCode']
         assert exitcode == 0
         inspect = self.client.inspect_container(id)
         assert 'Running' in inspect['State']
@@ -794,7 +794,7 @@ class WaitTest(BaseAPIIntegrationTest):
         id = res['Id']
         self.tmp_containers.append(id)
         self.client.start(res)
-        exitcode = self.client.wait(res)
+        exitcode = self.client.wait(res)['StatusCode']
         assert exitcode == 0
         inspect = self.client.inspect_container(res)
         assert 'Running' in inspect['State']
@@ -815,7 +815,9 @@ class WaitTest(BaseAPIIntegrationTest):
         )
         self.tmp_containers.append(ctnr)
         self.client.start(ctnr)
-        assert self.client.wait(ctnr, condition='removed', timeout=5) == 0
+        assert self.client.wait(
+            ctnr, condition='removed', timeout=5
+        )['StatusCode'] == 0
 
 
 class LogsTest(BaseAPIIntegrationTest):
@@ -827,7 +829,7 @@ class LogsTest(BaseAPIIntegrationTest):
         id = container['Id']
         self.tmp_containers.append(id)
         self.client.start(id)
-        exitcode = self.client.wait(id)
+        exitcode = self.client.wait(id)['StatusCode']
         assert exitcode == 0
         logs = self.client.logs(id)
         assert logs == (snippet + '\n').encode(encoding='ascii')
@@ -841,7 +843,7 @@ Line2'''
         id = container['Id']
         self.tmp_containers.append(id)
         self.client.start(id)
-        exitcode = self.client.wait(id)
+        exitcode = self.client.wait(id)['StatusCode']
         assert exitcode == 0
         logs = self.client.logs(id, tail=1)
         assert logs == 'Line2\n'.encode(encoding='ascii')
@@ -858,7 +860,7 @@ Line2'''
         for chunk in self.client.logs(id, stream=True, follow=True):
             logs += chunk
 
-        exitcode = self.client.wait(id)
+        exitcode = self.client.wait(id)['StatusCode']
         assert exitcode == 0
 
         assert logs == (snippet + '\n').encode(encoding='ascii')
@@ -871,7 +873,7 @@ Line2'''
         id = container['Id']
         self.tmp_containers.append(id)
         self.client.start(id)
-        exitcode = self.client.wait(id)
+        exitcode = self.client.wait(id)['StatusCode']
         assert exitcode == 0
         logs = self.client.logs(container)
         assert logs == (snippet + '\n').encode(encoding='ascii')
@@ -884,7 +886,7 @@ Line2'''
         id = container['Id']
         self.tmp_containers.append(id)
         self.client.start(id)
-        exitcode = self.client.wait(id)
+        exitcode = self.client.wait(id)['StatusCode']
         assert exitcode == 0
         logs = self.client.logs(id, tail=0)
         assert logs == ''.encode(encoding='ascii')
@@ -898,7 +900,7 @@ Line2'''
 
         self.tmp_containers.append(container)
         self.client.start(container)
-        exitcode = self.client.wait(container)
+        exitcode = self.client.wait(container)['StatusCode']
         assert exitcode == 0
         logs_until_1 = self.client.logs(container, until=1)
         assert logs_until_1 == b''
@@ -912,7 +914,7 @@ class DiffTest(BaseAPIIntegrationTest):
         id = container['Id']
         self.client.start(id)
         self.tmp_containers.append(id)
-        exitcode = self.client.wait(id)
+        exitcode = self.client.wait(id)['StatusCode']
         assert exitcode == 0
         diff = self.client.diff(id)
         test_diff = [x for x in diff if x.get('Path', None) == '/test']
@@ -925,7 +927,7 @@ class DiffTest(BaseAPIIntegrationTest):
         id = container['Id']
         self.client.start(id)
         self.tmp_containers.append(id)
-        exitcode = self.client.wait(id)
+        exitcode = self.client.wait(id)['StatusCode']
         assert exitcode == 0
         diff = self.client.diff(container)
         test_diff = [x for x in diff if x.get('Path', None) == '/test']
@@ -997,7 +999,7 @@ class KillTest(BaseAPIIntegrationTest):
         self.client.kill(
             id, signal=signal.SIGKILL if not IS_WINDOWS_PLATFORM else 9
         )
-        exitcode = self.client.wait(id)
+        exitcode = self.client.wait(id)['StatusCode']
         assert exitcode != 0
         container_info = self.client.inspect_container(id)
         assert 'State' in container_info
@@ -1012,7 +1014,7 @@ class KillTest(BaseAPIIntegrationTest):
         self.client.start(id)
         self.tmp_containers.append(id)
         self.client.kill(id, signal='SIGKILL')
-        exitcode = self.client.wait(id)
+        exitcode = self.client.wait(id)['StatusCode']
         assert exitcode != 0
         container_info = self.client.inspect_container(id)
         assert 'State' in container_info
@@ -1027,7 +1029,7 @@ class KillTest(BaseAPIIntegrationTest):
         self.client.start(id)
         self.tmp_containers.append(id)
         self.client.kill(id, signal=9)
-        exitcode = self.client.wait(id)
+        exitcode = self.client.wait(id)['StatusCode']
         assert exitcode != 0
         container_info = self.client.inspect_container(id)
         assert 'State' in container_info
diff --git a/tests/integration/base.py b/tests/integration/base.py
index 04d9afd..c22126d 100644
--- a/tests/integration/base.py
+++ b/tests/integration/base.py
@@ -96,7 +96,7 @@ class BaseAPIIntegrationTest(BaseIntegrationTest):
         container = self.client.create_container(*args, **kwargs)
         self.tmp_containers.append(container)
         self.client.start(container)
-        exitcode = self.client.wait(container)
+        exitcode = self.client.wait(container)['StatusCode']
 
         if exitcode != 0:
             output = self.client.logs(container)
diff --git a/tests/integration/models_containers_test.py b/tests/integration/models_containers_test.py
index 2d01f22..a4d9f9c 100644
--- a/tests/integration/models_containers_test.py
+++ b/tests/integration/models_containers_test.py
@@ -309,8 +309,8 @@ class ContainerTest(BaseIntegrationTest):
         container = client.containers.run("alpine", "sh -c 'exit 0'",
                                           detach=True)
         self.tmp_containers.append(container.id)
-        assert container.wait() == 0
+        assert container.wait()['StatusCode'] == 0
         container = client.containers.run("alpine", "sh -c 'exit 1'",
                                           detach=True)
         self.tmp_containers.append(container.id)
-        assert container.wait() == 1
+        assert container.wait()['StatusCode'] == 1
diff --git a/tests/unit/fake_api_client.py b/tests/unit/fake_api_client.py
index f908355..15b60ea 100644
--- a/tests/unit/fake_api_client.py
+++ b/tests/unit/fake_api_client.py
@@ -46,7 +46,7 @@ def make_fake_api_client():
         'logs.return_value': [b'hello world\n'],
         'networks.return_value': fake_api.get_fake_network_list()[1],
         'start.return_value': None,
-        'wait.return_value': 0,
+        'wait.return_value': {'StatusCode': 0},
     })
     mock_client._version = docker.constants.DEFAULT_DOCKER_API_VERSION
     return mock_client
diff --git a/tests/unit/models_containers_test.py b/tests/unit/models_containers_test.py
index cdc9318..f79f5d5 100644
--- a/tests/unit/models_containers_test.py
+++ b/tests/unit/models_containers_test.py
@@ -234,7 +234,7 @@ class ContainerCollectionTest(unittest.TestCase):
     def test_run_with_error(self):
         client = make_fake_client()
         client.api.logs.return_value = "some error"
-        client.api.wait.return_value = 1
+        client.api.wait.return_value = {'StatusCode': 1}
 
         with pytest.raises(docker.errors.ContainerError) as cm:
             client.containers.run('alpine', 'echo hello world')
@@ -260,7 +260,7 @@ class ContainerCollectionTest(unittest.TestCase):
         client.api.remove_container.assert_not_called()
 
         client = make_fake_client()
-        client.api.wait.return_value = 1
+        client.api.wait.return_value = {'StatusCode': 1}
         with pytest.raises(docker.errors.ContainerError):
             client.containers.run("alpine")
         client.api.remove_container.assert_not_called()
@@ -270,7 +270,7 @@ class ContainerCollectionTest(unittest.TestCase):
         client.api.remove_container.assert_called_with(FAKE_CONTAINER_ID)
 
         client = make_fake_client()
-        client.api.wait.return_value = 1
+        client.api.wait.return_value = {'StatusCode': 1}
         with pytest.raises(docker.errors.ContainerError):
             client.containers.run("alpine", remove=True)
         client.api.remove_container.assert_called_with(FAKE_CONTAINER_ID)