Add section to reference docs and minor style changes

Also added `module_local` to `add_ostream_redirect`.

Author: dean0x7d

docs/advanced/pycpp/utilities.rst

@@ -26,16 +26,14 @@ expected in Python:
 Capturing standard output from ostream
 ======================================
 
-Often, a library will use the streams :cpp:var:`std::cout` and
-:cpp:var:`std::cerr` to print, but this does not play well with Python's
-standard :py:obj:`sys.stdout` and :py:obj:`sys.stderr` redirection. Replacing a
-library's printing with :cpp:func:`py::print` may not be feasible. This can be
-fixed using a guard around the library function that redirects output to the
-corresponding python streams:
+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
 
-    // At beginning of file
     #include <pybind11/iostream.h>
 
     ...
@@ -49,13 +47,13 @@ corresponding python streams:
         call_noisy_func();
     });
 
-This method respects flushes on the output streams, and will flush if needed
+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`, is identical execpt for
-defaulting to the error stream; this can be useful with `py::call_guard`, which
-allows multiple items, but uses the default constuctor:
+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
 
@@ -64,8 +62,8 @@ allows multiple items, but uses the default constuctor:
           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()` function:
+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
 
@@ -79,14 +77,14 @@ creates the following context manager in Python:
     with ostream_redirect(stdout=True, stderr=True):
         noisy_function()
 
-The added context manager defaults to redirecting both streams, though you can
-use the keyword arguments to disable one of the streams if needed.
+It defaults to redirecting both streams, though you can use the keyword
+arguments to disable one of the streams if needed.
 
-.. note:
+.. note::
 
-    The above methods will not redirect direct output to file descriptors, such
+    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 :py:obj:`os.dup2` function
+    descriptors either directly in C or with Python's ``os.dup2`` function
     in an operating-system dependent way.
 
 .. _eval:

docs/changelog.rst

@@ -123,14 +123,14 @@ v2.2.0 (Not yet released)
   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 like `std::cout`,
-  `py::scoped_ostream_redirect`, RAII in C++;
-  and a context manager in python. See :ref:`ostream_redirect` or
-  `#1005 <https://github.com/pybind/pybind11/pull/1009>`_.
+* 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>`_,

docs/reference.rst

@@ -71,6 +71,15 @@ Embedding the interpreter
 
 .. doxygenclass:: scoped_interpreter
 
+Redirecting C++ streams
+=======================
+
+.. doxygenclass:: scoped_ostream_redirect
+
+.. doxygenclass:: scoped_estream_redirect
+
+.. doxygenfunction:: add_ostream_redirect
+
 Python build-in functions
 =========================
 

include/pybind11/iostream.h

@@ -1,14 +1,14 @@
-#pragma once
-
 /*
-    pybind11/iostream -- Tools to assist with redirecting cout and cerr to Python
+    pybind11/iostream.h -- Tools to assist with redirecting cout and cerr to Python
 
     Copyright (c) 2017 Henry F. Schreiner
 
     All rights reserved. Use of this source code is governed by a
     BSD-style license that can be found in the LICENSE file.
 */
 
+#pragma once
+
 #include "pybind11.h"
 
 #include <streambuf>
@@ -24,8 +24,8 @@ NAMESPACE_BEGIN(detail)
 class pythonbuf : public std::streambuf {
 private:
     using traits_type = std::streambuf::traits_type;
-    char          d_buffer[1024];
 
+    char d_buffer[1024];
     object pywrite;
     object pyflush;
 
@@ -49,12 +49,14 @@ class pythonbuf : public std::streambuf {
         }
         return 0;
     }
+
 public:
     pythonbuf(object pyostream)
         : pywrite(pyostream.attr("write")),
           pyflush(pyostream.attr("flush")) {
         setp(d_buffer, d_buffer + sizeof(d_buffer) - 1);
     }
+
     /// Sync before destroy
     ~pythonbuf() {
         sync();
@@ -65,37 +67,38 @@ NAMESPACE_END(detail)
 
 
 /** \rst
-    Scoped ostream output redirect
     This a move-only guard that redirects output.
 
     .. code-block:: cpp
 
         #include <pybind11/iostream.h>
 
-        int main() {
+        ...
+
+        {
             py::scoped_ostream_redirect output;
             std::cout << "Hello, World!"; // Python stdout
         } // <-- return std::cout to normal
 
-    You can explicitly pass the c++ stream and the python object, for example to gaurd stderr instead.
+    You can explicitly pass the c++ stream and the python object,
+    for example to guard stderr instead.
 
     .. code-block:: cpp
-        int main() {
+
+        {
             py::scoped_ostream_redirect output{std::cerr, py::module::import("sys").attr("stderr")};
             std::cerr << "Hello, World!";
         }
  \endrst */
-
 class scoped_ostream_redirect {
 protected:
-    std::streambuf * old;
-    std::ostream& costream;
+    std::streambuf *old;
+    std::ostream &costream;
     detail::pythonbuf buffer;
 
 public:
-
     scoped_ostream_redirect(
-            std::ostream& costream = std::cout,
+            std::ostream &costream = std::cout,
             object pyostream = module::import("sys").attr("stdout"))
         : costream(costream), buffer(pyostream) {
         old = costream.rdbuf(&buffer);
@@ -113,11 +116,10 @@ class scoped_ostream_redirect {
 
 
 /** \rst
-    Scoped ostream output redirect with cerr defaults
-
-    This class is provided primary to make call_guards easier to make.
+    Like `scoped_ostream_redirect`, but redirects cerr by default. This class
+    is provided primary to make ``py::call_guard`` easier to make.
 
-    .. code_block:: cpp
+    .. code-block:: cpp
 
      m.def("noisy_func", &noisy_func,
            py::call_guard<scoped_ostream_redirect,
@@ -127,14 +129,9 @@ class scoped_ostream_redirect {
 class scoped_estream_redirect : public scoped_ostream_redirect {
 public:
     scoped_estream_redirect(
-            std::ostream& costream = std::cerr,
+            std::ostream &costream = std::cerr,
             object pyostream = module::import("sys").attr("stderr"))
         : scoped_ostream_redirect(costream,pyostream) {}
-
-    scoped_estream_redirect(const scoped_estream_redirect &) = delete;
-    scoped_estream_redirect(scoped_estream_redirect &&other) = default;
-    scoped_estream_redirect &operator=(const scoped_estream_redirect &) = delete;
-    scoped_estream_redirect &operator=(scoped_estream_redirect &&) = delete;
 };
 
 
@@ -148,7 +145,6 @@ class OstreamRedirect {
     std::unique_ptr<scoped_estream_redirect> redirect_stderr;
 
 public:
-
     OstreamRedirect(bool do_stdout = true, bool do_stderr = true)
         : do_stdout_(do_stdout), do_stderr_(do_stderr) {}
 
@@ -168,8 +164,8 @@ class OstreamRedirect {
 NAMESPACE_END(detail)
 
 /** \rst
-    This is a helper function to add a C++ redirect context manager to Python instead of using a C++ guard.
-    To use it, add the following to your binding code:
+    This is a helper function to add a C++ redirect context manager to Python
+    instead of using a C++ guard. To use it, add the following to your binding code:
 
     .. code-block:: cpp
 
@@ -179,7 +175,7 @@ NAMESPACE_END(detail)
 
         py::add_ostream_redirect(m, "ostream_redirect");
 
-    You now have a python context manager that redirects your output:
+    You now have a Python context manager that redirects your output:
 
     .. code-block:: python
 
@@ -194,16 +190,11 @@ NAMESPACE_END(detail)
             m.noisy_function_with_error_printing()
 
  \endrst */
-
 inline class_<detail::OstreamRedirect> add_ostream_redirect(module m, std::string name = "ostream_redirect") {
-    return class_<detail::OstreamRedirect>(m, name.c_str())
+    return class_<detail::OstreamRedirect>(m, name.c_str(), module_local())
         .def(init<bool,bool>(), arg("stdout")=true, arg("stderr")=true)
-        .def("__enter__", [](detail::OstreamRedirect &self) {
-            self.enter();
-        })
-        .def("__exit__", [](detail::OstreamRedirect &self, args) {
-            self.exit();
-        });
+        .def("__enter__", &detail::OstreamRedirect::enter)
+        .def("__exit__", [](detail::OstreamRedirect &self, args) { self.exit(); });
 }
 
 NAMESPACE_END(PYBIND11_NAMESPACE)