Utility for redirecting C++ streams to Python (#1009)
diff --git a/docs/advanced/pycpp/utilities.rst b/docs/advanced/pycpp/utilities.rst
index 171a885..369e7c9 100644
--- a/docs/advanced/pycpp/utilities.rst
+++ b/docs/advanced/pycpp/utilities.rst
@@ -21,6 +21,72 @@
auto args = py::make_tuple("unpacked", true);
py::print("->", *args, "end"_a="<-"); // -> unpacked True <-
+.. _ostream_redirect:
+
+Capturing standard output from ostream
+======================================
+
+Often, a library will use the streams ``std::cout`` and ``std::cerr`` to print,
+but this does not play well with Python's standard ``sys.stdout`` and ``sys.stderr``
+redirection. Replacing a library's printing with `py::print <print>` may not
+be feasible. This can be fixed using a guard around the library function that
+redirects output to the corresponding Python streams:
+
+.. code-block:: cpp
+
+ #include <pybind11/iostream.h>
+
+ ...
+
+ // Add a scoped redirect for your noisy code
+ m.def("noisy_func", []() {
+ py::scoped_ostream_redirect stream(
+ std::cout, // std::ostream&
+ py::module::import("sys").attr("stdout") // Python output
+ );
+ call_noisy_func();
+ });
+
+This method respects flushes on the output streams and will flush if needed
+when the scoped guard is destroyed. This allows the output to be redirected in
+real time, such as to a Jupyter notebook. The two arguments, the C++ stream and
+the Python output, are optional, and default to standard output if not given. An
+extra type, `py::scoped_estream_redirect <scoped_estream_redirect>`, is identical
+except for defaulting to ``std::cerr`` and ``sys.stderr``; this can be useful with
+`py::call_guard`, which allows multiple items, but uses the default constructor:
+
+.. code-block:: py
+
+ // Alternative: Call single function using call guard
+ m.def("noisy_func", &call_noisy_function,
+ py::call_guard<py::scoped_ostream_redirect,
+ py::scoped_estream_redirect>());
+
+The redirection can also be done in Python with the addition of a context
+manager, using the `py::add_ostream_redirect() <add_ostream_redirect>` function:
+
+.. code-block:: cpp
+
+ py::add_ostream_redirect(m, "ostream_redirect");
+
+The name in Python defaults to ``ostream_redirect`` if no name is passed. This
+creates the following context manager in Python:
+
+.. code-block:: python
+
+ with ostream_redirect(stdout=True, stderr=True):
+ noisy_function()
+
+It defaults to redirecting both streams, though you can use the keyword
+arguments to disable one of the streams if needed.
+
+.. note::
+
+ The above methods will not redirect C-level output to file descriptors, such
+ as ``fprintf``. For those cases, you'll need to redirect the file
+ descriptors either directly in C or with Python's ``os.dup2`` function
+ in an operating-system dependent way.
+
.. _eval:
Evaluating Python expressions from strings and files
diff --git a/docs/changelog.rst b/docs/changelog.rst
index 2e585dc..49249e3 100644
--- a/docs/changelog.rst
+++ b/docs/changelog.rst
@@ -123,10 +123,15 @@
7. Fixed lifetime of temporary C++ objects created in Python-to-C++ conversions.
`#924 <https://github.com/pybind/pybind11/pull/924>`_.
-* Scope guard call policy for RAII types, e.g. ``py::call_guard<py::gil_scoped_release>()``.
- See :ref:`call_policies` for details.
+* Scope guard call policy for RAII types, e.g. ``py::call_guard<py::gil_scoped_release>()``,
+ ``py::call_guard<py::scoped_ostream_redirect>()``. See :ref:`call_policies` for details.
`#740 <https://github.com/pybind/pybind11/pull/740>`_.
+* Utility for redirecting C++ streams to Python (e.g. ``std::cout`` ->
+ ``sys.stdout``). Scope guard ``py::scoped_ostream_redirect`` in C++ and
+ a context manager in Python. See :ref:`ostream_redirect`.
+ `#1009 <https://github.com/pybind/pybind11/pull/1009>`_.
+
* Improved handling of types and exceptions across module boundaries.
`#915 <https://github.com/pybind/pybind11/pull/915>`_,
`#951 <https://github.com/pybind/pybind11/pull/951>`_,
@@ -298,7 +303,6 @@
`#923 <https://github.com/pybind/pybind11/pull/923>`_,
`#963 <https://github.com/pybind/pybind11/pull/963>`_.
-
v2.1.1 (April 7, 2017)
-----------------------------------------------------
diff --git a/docs/reference.rst b/docs/reference.rst
index 1365739..e41141b 100644
--- a/docs/reference.rst
+++ b/docs/reference.rst
@@ -71,6 +71,15 @@
.. doxygenclass:: scoped_interpreter
+Redirecting C++ streams
+=======================
+
+.. doxygenclass:: scoped_ostream_redirect
+
+.. doxygenclass:: scoped_estream_redirect
+
+.. doxygenfunction:: add_ostream_redirect
+
Python build-in functions
=========================