From 16c28093b965e13ef8a394799f7a9aa1bd08307c Mon Sep 17 00:00:00 2001 From: Joffrey F Date: Fri, 30 Nov 2018 15:26:51 -0800 Subject: [PATCH] Move exec_run example to user guides section of docs Signed-off-by: Joffrey F --- docker/models/containers.py | 64 ----------------------------- docs/index.rst | 1 + docs/user_guides/index.rst | 8 ++++ docs/user_guides/multiplex.rst | 66 ++++++++++++++++++++++++++++++ docs/user_guides/swarm_services.md | 4 ++ 5 files changed, 79 insertions(+), 64 deletions(-) create mode 100644 docs/user_guides/index.rst create mode 100644 docs/user_guides/multiplex.rst diff --git a/docker/models/containers.py b/docker/models/containers.py index 75d8c2eb..41bc4da8 100644 --- a/docker/models/containers.py +++ b/docker/models/containers.py @@ -181,70 +181,6 @@ class Container(Model): Raises: :py:class:`docker.errors.APIError` If the server returns an error. - - Example: - - Create a container that runs in the background - - >>> client = docker.from_env() - >>> container = client.containers.run( - ... 'bfirsh/reticulate-splines', detach=True) - - Prepare the command we are going to use. It prints "hello stdout" - in `stdout`, followed by "hello stderr" in `stderr`: - - >>> cmd = '/bin/sh -c "echo hello stdout ; echo hello stderr >&2"' - - We'll run this command with all four the combinations of ``stream`` - and ``demux``. - - With ``stream=False`` and ``demux=False``, the output is a string - that contains both the `stdout` and the `stderr` output: - - >>> res = container.exec_run(cmd, stream=False, demux=False) - >>> res.output - b'hello stderr\nhello stdout\n' - - With ``stream=True``, and ``demux=False``, the output is a - generator that yields strings containing the output of both - `stdout` and `stderr`: - - >>> res = container.exec_run(cmd, stream=True, demux=False) - >>> next(res.output) - b'hello stdout\n' - >>> next(res.output) - b'hello stderr\n' - >>> next(res.output) - Traceback (most recent call last): - File "", line 1, in - StopIteration - - With ``stream=True`` and ``demux=True``, the generator now - separates the streams, and yield tuples - ``(stdout, stderr)``: - - >>> res = container.exec_run(cmd, stream=True, demux=True) - >>> next(res.output) - (b'hello stdout\n', None) - >>> next(res.output) - (None, b'hello stderr\n') - >>> next(res.output) - Traceback (most recent call last): - File "", line 1, in - StopIteration - - Finally, with ``stream=False`` and ``demux=True``, the whole output - is returned, but the streams are still separated: - - >>> res = container.exec_run(cmd, stream=True, demux=True) - >>> next(res.output) - (b'hello stdout\n', None) - >>> next(res.output) - (None, b'hello stderr\n') - >>> next(res.output) - Traceback (most recent call last): - File "", line 1, in - StopIteration """ resp = self.client.api.exec_create( self.id, cmd, stdout=stdout, stderr=stderr, stdin=stdin, tty=tty, diff --git a/docs/index.rst b/docs/index.rst index 39426b68..63e85d36 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -92,4 +92,5 @@ That's just a taste of what you can do with the Docker SDK for Python. For more, volumes api tls + user_guides/index change-log diff --git a/docs/user_guides/index.rst b/docs/user_guides/index.rst new file mode 100644 index 00000000..79b3a909 --- /dev/null +++ b/docs/user_guides/index.rst @@ -0,0 +1,8 @@ +User guides and tutorials +========================= + +.. toctree:: + :maxdepth: 2 + + multiplex + swarm_services \ No newline at end of file diff --git a/docs/user_guides/multiplex.rst b/docs/user_guides/multiplex.rst new file mode 100644 index 00000000..78d7e372 --- /dev/null +++ b/docs/user_guides/multiplex.rst @@ -0,0 +1,66 @@ +Handling multiplexed streams +============================ + +.. note:: + The following instruction assume you're interested in getting output from + an ``exec`` command. These instruction are similarly applicable to the + output of ``attach``. + +First create a container that runs in the background: + +>>> client = docker.from_env() +>>> container = client.containers.run( +... 'bfirsh/reticulate-splines', detach=True) + +Prepare the command we are going to use. It prints "hello stdout" +in `stdout`, followed by "hello stderr" in `stderr`: + +>>> cmd = '/bin/sh -c "echo hello stdout ; echo hello stderr >&2"' +We'll run this command with all four the combinations of ``stream`` +and ``demux``. +With ``stream=False`` and ``demux=False``, the output is a string +that contains both the `stdout` and the `stderr` output: +>>> res = container.exec_run(cmd, stream=False, demux=False) +>>> res.output +b'hello stderr\nhello stdout\n' + +With ``stream=True``, and ``demux=False``, the output is a +generator that yields strings containing the output of both +`stdout` and `stderr`: + +>>> res = container.exec_run(cmd, stream=True, demux=False) +>>> next(res.output) +b'hello stdout\n' +>>> next(res.output) +b'hello stderr\n' +>>> next(res.output) +Traceback (most recent call last): + File "", line 1, in +StopIteration + +With ``stream=True`` and ``demux=True``, the generator now +separates the streams, and yield tuples +``(stdout, stderr)``: + +>>> res = container.exec_run(cmd, stream=True, demux=True) +>>> next(res.output) +(b'hello stdout\n', None) +>>> next(res.output) +(None, b'hello stderr\n') +>>> next(res.output) +Traceback (most recent call last): + File "", line 1, in +StopIteration + +Finally, with ``stream=False`` and ``demux=True``, the whole output +is returned, but the streams are still separated: + +>>> res = container.exec_run(cmd, stream=True, demux=True) +>>> next(res.output) +(b'hello stdout\n', None) +>>> next(res.output) +(None, b'hello stderr\n') +>>> next(res.output) +Traceback (most recent call last): + File "", line 1, in +StopIteration diff --git a/docs/user_guides/swarm_services.md b/docs/user_guides/swarm_services.md index 9bd4dca3..369fbed0 100644 --- a/docs/user_guides/swarm_services.md +++ b/docs/user_guides/swarm_services.md @@ -1,5 +1,9 @@ # Swarm services +> Warning: +> This is a stale document and may contain outdated information. +> Refer to the API docs for updated classes and method signatures. + Starting with Engine version 1.12 (API 1.24), it is possible to manage services using the Docker Engine API. Note that the engine needs to be part of a [Swarm cluster](../swarm.rst) before you can use the service-related methods.