Final cleanups for iostream, call guard usage

Squashed commit of the following:

commit 4cdbdd3809cae488107c33838eb4dd2346de73f8
Author: Henry Fredrick Schreiner <[email protected]>
Date:   Tue Aug 22 10:12:23 2017 -0700

    Linting fix

commit 4ff64ce2ebf9b26c60575f8edb93b488f4677431
Author: Henry Fredrick Schreiner <[email protected]>
Date:   Tue Aug 22 08:34:38 2017 -0700

    Docs cleanup, changelog update

commit 00cc177c2e1148b71000e9564f8fcf4947f0b8f5
Author: Henry Fredrick Schreiner <[email protected]>
Date:   Tue Aug 22 08:21:35 2017 -0700

    Adding scoped_estream_redirect, for call_guard and simplification

commit 30899eaeba30ff453338040c93a221879351efb7
Author: Henry Fredrick Schreiner <[email protected]>
Date:   Tue Aug 22 07:33:47 2017 -0700

    Docs cleanup and update

commit fe1a63a125330a01684ed8a26d77523195c90735
Author: Henry Fredrick Schreiner <[email protected]>
Date:   Mon Aug 21 17:36:17 2017 -0700

    Fix linter issues

commit e2b8f8ad6abcac4864f78c93f8b89e85215aa0a0
Author: Henry Fredrick Schreiner <[email protected]>
Date:   Mon Aug 21 16:47:44 2017 -0700

    Dropping some extra unneeded thises and unused default

commit 2e8bec13e94dcba71693788200e4ed7c40e2ac60
Author: Henry Fredrick Schreiner <[email protected]>
Date:   Mon Aug 21 16:43:41 2017 -0700

    Sync on destuction, and add tests to check flush behavior

commit 314d4514685a3f17a13da5864c1f055d66688458
Author: Henry Fredrick Schreiner <[email protected]>
Date:   Mon Aug 21 16:11:52 2017 -0700

    Testing and documenting simple call with call_guard

Author: henryiii

docs/advanced/pycpp/utilities.rst

@@ -26,9 +26,12 @@ expected in Python:
 Capturing standard output from ostream
 ======================================
 
-Often, a library may 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.
-This can be fixed using a guard around the library function that has output:
+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:
 
 .. code-block:: cpp
 
@@ -37,38 +40,54 @@ This can be fixed using a guard around the library function that has output:
 
     ...
 
-    // Add a scoped redirect for your noisy function
+    // 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 descriptor to output to
+            py::module::import("sys").attr("stdout") // Python output
         );
         call_noisy_func();
     });
 
-This method respects flushes on the output streams. This allows the output to be redirected
-in realtime, 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.
+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:
 
-The redirection can also be done in python with the addition of a context manager, using the `py::add_ostream_redirect()` function:
+.. 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()` 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:
+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()
 
-This defaults redirecting ``stdout`` if neither keyword argument is given.
+The added context manager 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 direct 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.
+    The above methods will not redirect direct 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
+    in an operating-system dependent way.
 
 .. _eval:
 

docs/changelog.rst

@@ -9,7 +9,6 @@ Starting with version 1.8.0, pybind11 releases use a `semantic versioning
 v2.2.0 (Not yet released)
 -----------------------------------------------------
 
-<<<<<<< HEAD
 * Support for embedding the Python interpreter. See the
   :doc:`documentation page </advanced/embedding>` for a
   full overview of the new features.
@@ -128,8 +127,8 @@ v2.2.0 (Not yet released)
   See :ref:`call_policies` for details.
   `#740 <https://github.com/pybind/pybind11/pull/740>`_.
 
-* Utility for redirecting `std::cout` and `std::cerr` added,
-  `py::scoped_stl_redirect`, RAII in C++;
+* 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>`_.
 
@@ -290,7 +289,6 @@ v2.2.0 (Not yet released)
   `#923 <https://github.com/pybind/pybind11/pull/923>`_,
   `#963 <https://github.com/pybind/pybind11/pull/963>`_.
 
-
 v2.1.1 (April 7, 2017)
 -----------------------------------------------------
 

include/pybind11/iostream.h

@@ -31,29 +31,33 @@ class pythonbuf : public std::streambuf {
 
     int overflow(int c) {
         if (!traits_type::eq_int_type(c, traits_type::eof())) {
-            *this->pptr() = traits_type::to_char_type(c);
-            this->pbump(1);
+            *pptr() = traits_type::to_char_type(c);
+            pbump(1);
         }
-        return this->sync() ? traits_type::not_eof(c) : traits_type::eof();
+        return sync() ? traits_type::not_eof(c) : traits_type::eof();
     }
 
     int sync() {
-        if (this->pbase() != this->pptr()) {
+        if (pbase() != pptr()) {
             // This subtraction cannot be negative, so dropping the sign
-            str line(this->pbase(), static_cast<size_t>(this->pptr() - this->pbase()));
+            str line(pbase(), static_cast<size_t>(pptr() - pbase()));
 
             pywrite(line);
             pyflush();
 
-            this->setp(this->pbase(), this->epptr());
+            setp(pbase(), epptr());
         }
         return 0;
     }
 public:
     pythonbuf(object pyostream)
         : pywrite(pyostream.attr("write")),
           pyflush(pyostream.attr("flush")) {
-        this->setp(this->d_buffer, this->d_buffer + sizeof(this->d_buffer) - 1);
+        setp(d_buffer, d_buffer + sizeof(d_buffer) - 1);
+    }
+    /// Sync before destroy
+    ~pythonbuf() {
+        sync();
     }
 };
 
@@ -83,21 +87,22 @@ NAMESPACE_END(detail)
  \endrst */
 
 class scoped_ostream_redirect {
-    std::streambuf * old {nullptr};
+protected:
+    std::streambuf * old;
     std::ostream& costream;
     detail::pythonbuf buffer;
 
 public:
+
     scoped_ostream_redirect(
             std::ostream& costream = std::cout,
-            object pyostream = module::import("sys").attr("stdout") )
+            object pyostream = module::import("sys").attr("stdout"))
         : costream(costream), buffer(pyostream) {
         old = costream.rdbuf(&buffer);
     }
 
     ~scoped_ostream_redirect() {
         costream.rdbuf(old);
-        
     }
 
     scoped_ostream_redirect(const scoped_ostream_redirect &) = delete;
@@ -106,39 +111,52 @@ class scoped_ostream_redirect {
     scoped_ostream_redirect &operator=(scoped_ostream_redirect &&) = delete;
 };
 
+
+/** \rst
+    Scoped ostream output redirect with cerr defaults
+
+    This class is provided primary to make call_guards easier to make.
+
+    .. code_block:: cpp
+
+     m.def("noisy_func", &noisy_func,
+           py::call_guard<scoped_ostream_redirect,
+                          scoped_estream_redirect>());
+
+\endrst */
+class scoped_estream_redirect : public scoped_ostream_redirect {
+public:
+    scoped_estream_redirect(
+            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;
+};
+
+
 NAMESPACE_BEGIN(detail)
 
 // Class to redirect output as a context manager. C++ backend.
 class OstreamRedirect {
     bool do_stdout_;
     bool do_stderr_;
     std::unique_ptr<scoped_ostream_redirect> redirect_stdout;
-    std::unique_ptr<scoped_ostream_redirect> redirect_stderr;
+    std::unique_ptr<scoped_estream_redirect> redirect_stderr;
 
 public:
 
-    OstreamRedirect(bool do_stdout = false, bool do_stderr = false)
+    OstreamRedirect(bool do_stdout = true, bool do_stderr = true)
         : do_stdout_(do_stdout), do_stderr_(do_stderr) {}
 
     void enter() {
-        // If stdout is true, or if both are false
-        if (do_stdout_ || (!do_stdout_ && !do_stderr_)) {
-            redirect_stdout.reset(
-                new scoped_ostream_redirect(
-                    std::cout,
-                    module::import("sys").attr("stdout")
-                )
-            );
-        }
-
-        if (do_stderr_) {
-            redirect_stderr.reset(
-                new scoped_ostream_redirect(
-                    std::cerr,
-                    module::import("sys").attr("stderr")
-                )
-            );
-        }
+        if (do_stdout_)
+            redirect_stdout.reset(new scoped_ostream_redirect());
+        if (do_stderr_)
+            redirect_stderr.reset(new scoped_estream_redirect());
     }
 
     void exit() {
@@ -179,7 +197,7 @@ NAMESPACE_END(detail)
 
 class_<detail::OstreamRedirect> add_ostream_redirect(module m, std::string name = "ostream_redirect") {
     return class_<detail::OstreamRedirect>(m, name.c_str())
-        .def(init<bool,bool>(), arg("stdout")=false, arg("stderr")=false)
+        .def(init<bool,bool>(), arg("stdout")=true, arg("stderr")=true)
         .def("__enter__", [](detail::OstreamRedirect &self) {
             self.enter();
         })

tests/test_iostream.cpp

@@ -13,6 +13,18 @@
 #include <iostream>
 
 
+void noisy_function(std::string msg, bool flush) {
+
+    std::cout << msg;
+    if (flush)
+        std::cout << std::flush;
+}
+
+void noisy_funct_dual(std::string msg, std::string emsg) {
+    std::cout << msg;
+    std::cerr << emsg;
+}
+
 TEST_SUBMODULE(iostream, m) {
 
     add_ostream_redirect(m);
@@ -29,11 +41,21 @@ TEST_SUBMODULE(iostream, m) {
         std::cout << msg << std::flush;
     });
 
+    m.def("guard_output", &noisy_function,
+            py::call_guard<py::scoped_ostream_redirect>(),
+            py::arg("msg"), py::arg("flush")=true);
+
     m.def("captured_err", [](std::string msg) {
         py::scoped_ostream_redirect redir(std::cerr, py::module::import("sys").attr("stderr"));
         std::cerr << msg << std::flush;
     });
 
+    m.def("noisy_function", &noisy_function, py::arg("msg"), py::arg("flush") = true);
+
+    m.def("dual_guard", &noisy_funct_dual,
+            py::call_guard<py::scoped_ostream_redirect, py::scoped_estream_redirect>(),
+            py::arg("msg"), py::arg("emsg"));
+
     m.def("raw_output", [](std::string msg) {
         std::cout << msg << std::flush;
     });

tests/test_iostream.py

@@ -54,13 +54,40 @@ def test_captured(capsys):
     assert stderr == msg
 
 
+def test_guard_capture(capsys):
+    msg = "I've been redirected to Python, I hope!"
+    m.guard_output(msg)
+    stdout, stderr = capsys.readouterr()
+    assert stdout == msg
+    assert stderr == ''
+
+
 def test_series_captured(capture):
     with capture:
         m.captured_output("a")
         m.captured_output("b")
     assert capture == "ab"
 
 
+def test_flush(capfd):
+    msg = "(not flushed)"
+    msg2 = "(flushed)"
+
+    with m.ostream_redirect():
+        m.noisy_function(msg, flush=False)
+        stdout, stderr = capfd.readouterr()
+        assert stdout == ''
+
+        m.noisy_function(msg2, flush=True)
+        stdout, stderr = capfd.readouterr()
+        assert stdout == msg + msg2
+
+        m.noisy_function(msg, flush=False)
+
+    stdout, stderr = capfd.readouterr()
+    assert stdout == msg
+
+
 def test_not_captured(capfd):
     msg = "Something that should not show up in log"
     stream = StringIO()
@@ -149,7 +176,7 @@ def test_redirect_err(capfd):
 
     stream = StringIO()
     with redirect_stderr(stream):
-        with m.ostream_redirect(stderr=True):
+        with m.ostream_redirect(stdout=False):
             m.raw_output(msg)
             m.raw_err(msg2)
     stdout, stderr = capfd.readouterr()
@@ -166,7 +193,7 @@ def test_redirect_both(capfd):
     stream2 = StringIO()
     with redirect_stdout(stream):
         with redirect_stderr(stream2):
-            with m.ostream_redirect(stdout=True, stderr=True):
+            with m.ostream_redirect():
                 m.raw_output(msg)
                 m.raw_err(msg2)
     stdout, stderr = capfd.readouterr()