capture

docs/source/console.rst

@@ -42,48 +42,6 @@ You can set ``color_system`` to one of the following values:
     Be careful when setting a color system, if you set a higher color system than your terminal supports, your text may be unreadable.
 
 
-File output
------------
-
-The Console object will write to standard output (i.e. the terminal). You can also tell the Console object to write to another file by setting the ``file`` argument on the constructor -- which should be a file-like object opened for writing text. One use of this capability is to create a Console for writing to standard error by setting file to ``sys.stderr``. Here's an example::
-
-    import sys
-    from rich.console import Console
-    error_console = Console(file=sys.stderr)
-    error_console.print("[bold red]This is an error!")
-
-
-Capturing output
-----------------
-
-There may be situations where you want to capture the output from a Console rather than writing it directly to the terminal. You can do this by setting the ``file`` argument to a :py:class:`io.StringIO` instance. Here's an example::
-
-    from io import StringIO
-    from rich.console import Console
-    console = Console(file=StringIO())
-    console.print("[bold red]Hello[/] World")
-    str_output = console.file.getvalue()
-
-You may also want to set ``force_terminal=True`` on the Console constructor if you want control codes for colour and style in the resulting string.
-
-Terminal detection
-------------------
-
-If Rich detects that it is not writing to a terminal it will strip control codes from the output. If you want to write control codes to a regular file then set ``force_terminal=True`` on the constructor.
-
-Letting Rich auto-detect terminals is useful as it will write plain text when you pipe output to a file or other application.
-
-
-Environment variables
----------------------
-
-Rich respects some standard environment variables.
-
-Setting the environment variable ``TERM`` to ``"dumb"`` or ``"unknown"`` will disable color/style and some features that require moving the cursor, such as progress bars.
-
-If the environment variable ``NO_COLOR`` is set, Rich will disable all color in the output.
-
-
 Printing
 --------
 
@@ -220,3 +178,52 @@ The Console class can export anything written to it as either text or html. To e
 After you have written content, you can call :meth:`~rich.console.Console.export_text` or :meth:`~rich.console.Console.export_html` to get the console output as a string. You can also call :meth:`~rich.console.Console.save_text` or :meth:`~rich.console.Console.save_html` to write the contents directly to disk.
 
 For examples of the html output generated by Rich Console, see :ref:`appendix-colors`.
+
+
+File output
+-----------
+
+The Console object will write to standard output (i.e. the terminal). You can also tell the Console object to write to another file by setting the ``file`` argument on the constructor -- which should be a file-like object opened for writing text. One use of this capability is to create a Console for writing to standard error by setting file to ``sys.stderr``. Here's an example::
+
+    import sys
+    from rich.console import Console
+    error_console = Console(file=sys.stderr)
+    error_console.print("[bold red]This is an error!")
+
+
+Capturing output
+----------------
+
+There may be situations where you want to *capture* the output from a Console rather than writing it directly to the terminal. You can do this with the :meth:`~rich.console.Console.capture` method which returns a context manager. On exit from this context manager, call :meth:`~rich.console.Capture.get` to return the string that would have been written to the terminal. Here's an example::
+
+    from rich.console import Console
+    console = Console()
+    with console.capture() as capture:
+        console.print("[bold red]Hello[/] World")
+    str_output = capture.get()
+
+An alternative way of capturing output is to set the Console file to a :py:class:`io.StringIO`. This is the recommended method if you are testing console output in unit tests. Here's an example::
+
+    from io import StringIO
+    from rich.console import Console
+    console = Console(file=StringIO())
+    console.print("[bold red]Hello[/] World")
+    str_output = console.file.getvalue()
+
+
+Terminal detection
+------------------
+
+If Rich detects that it is not writing to a terminal it will strip control codes from the output. If you want to write control codes to a regular file then set ``force_terminal=True`` on the constructor.
+
+Letting Rich auto-detect terminals is useful as it will write plain text when you pipe output to a file or other application.
+
+
+Environment variables
+---------------------
+
+Rich respects some standard environment variables.
+
+Setting the environment variable ``TERM`` to ``"dumb"`` or ``"unknown"`` will disable color/style and some features that require moving the cursor, such as progress bars.
+
+If the environment variable ``NO_COLOR`` is set, Rich will disable all color in the output.