Updated exec API documentationexec_rework

3 files changed, 44 insertions, 17 deletions

diff --git a/docker/client.py b/docker/client.py
index e978dff..8481b78 100644
--- a/docker/client.py
+++ b/docker/client.py
@@ -526,8 +526,7 @@ class Client(requests.Session):
 
         return self.exec_start(create_res, detach, tty, stream)
 
-    def exec_create(self, container, cmd, detach=False, stdout=True,
-                    stderr=True, tty=False):
+    def exec_create(self, container, cmd, stdout=True, stderr=True, tty=False):
         if utils.compare_version('1.15', self._version) < 0:
             raise errors.InvalidVersion('Exec is not supported in API < 1.15')
         if isinstance(container, dict):
@@ -543,7 +542,6 @@ class Client(requests.Session):
             'AttachStdin': False,
             'AttachStdout': stdout,
             'AttachStderr': stderr,
-            'Detach': detach,
             'Cmd': cmd
         }
 
diff --git a/docs/api.md b/docs/api.md
index 5afe533..d45626c 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -256,28 +256,58 @@ function return a blocking generator you can iterate over to retrieve events as
 
 ## execute
 
-```python
-c.execute(container, cmd, detach=False, stdout=True, stderr=True,
-       stream=False, tty=False)
-```
+This command is deprecated for docker-py >= 1.2.0 ; use `exec_create` and
+`exec_start` instead.
+
+## exec_create
+
+Sets up an exec instance in a running container.
+
+**Params**:
+
+* container (str): Target container where exec instance will be created
+* cmd (str or list): Command to be executed
+* stdout (bool): Attach to stdout of the exec command if true. Default: True
+* stderr (bool): Attach to stderr of the exec command if true. Default: True
+* tty (bool): Allocate a pseudo-TTY. Default: False
+
+**Returns** (dict): A dictionary with an exec 'Id' key.
+
 
-Execute a command in a running container.
+## exec_inspect
+
+Return low-level information about an exec command.
 
 **Params**:
 
-* container (str): can be a container dictionary (result of
-running `inspect_container`), unique id or container name.
+* exec_id (str): ID of the exec instance
+
+**Returns** (dict): Dictionary of values returned by the endpoint.
+
 
+## exec_resize
 
-* cmd (str or list): representing the command and its arguments.
+Resize the tty session used by the specified exec command.
+
+**Params**:
 
-* detach (bool): flag to `True` will run the process in the background.
+* exec_id (str): ID of the exec instance
+* height (int): Height of tty session
+* width (int): Width of tty session
+
+## exec_start
+
+Start a previously set up exec instance.
+
+**Params**:
 
-* stdout (bool): indicates which output streams to read from.
-* stderr (bool): indicates which output streams to read from.
+* exec_id (str): ID of the exec instance
+* detach (bool): If true, detach from the exec command. Default: False
+* tty (bool): Allocate a pseudo-TTY. Default: False
+* stream (bool): Stream response data
 
-* stream (bool): indicates whether to return a generator which will yield
-  the streaming response in chunks.
+**Returns** (generator or str): If `stream=True`, a generator yielding response
+chunks. A string containing response data otherwise.
 
 ## export
 
diff --git a/tests/test.py b/tests/test.py
index 95a8463..3d63fee 100644
--- a/tests/test.py
+++ b/tests/test.py
@@ -1601,7 +1601,6 @@ class DockerClientTest(Cleanup, base.BaseTestCase):
                 'Tty': False,
                 'AttachStdout': True,
                 'Container': fake_api.FAKE_CONTAINER_ID,
-                'Detach': False,
                 'Cmd': ['ls', '-1'],
                 'Privileged': False,
                 'AttachStdin': False,