utilities.rst revision 12391:ceeca8b41e4b 
1Utilities
2#########
3
4Using Python's print function in C++
5====================================
6
7The usual way to write output in C++ is using ``std::cout`` while in Python one
8would use ``print``. Since these methods use different buffers, mixing them can
9lead to output order issues. To resolve this, pybind11 modules can use the
10:func:`py::print` function which writes to Python's ``sys.stdout`` for consistency.
11
12Python's ``print`` function is replicated in the C++ API including optional
13keyword arguments ``sep``, ``end``, ``file``, ``flush``. Everything works as
14expected in Python:
15
16.. code-block:: cpp
17
18    py::print(1, 2.0, "three"); // 1 2.0 three
19    py::print(1, 2.0, "three", "sep"_a="-"); // 1-2.0-three
20
21    auto args = py::make_tuple("unpacked", true);
22    py::print("->", *args, "end"_a="<-"); // -> unpacked True <-
23
24.. _ostream_redirect:
25
26Capturing standard output from ostream
27======================================
28
29Often, a library will use the streams ``std::cout`` and ``std::cerr`` to print,
30but this does not play well with Python's standard ``sys.stdout`` and ``sys.stderr``
31redirection. Replacing a library's printing with `py::print <print>` may not
32be feasible. This can be fixed using a guard around the library function that
33redirects output to the corresponding Python streams:
34
35.. code-block:: cpp
36
37    #include <pybind11/iostream.h>
38
39    ...
40
41    // Add a scoped redirect for your noisy code
42    m.def("noisy_func", []() {
43        py::scoped_ostream_redirect stream(
44            std::cout,                               // std::ostream&
45            py::module::import("sys").attr("stdout") // Python output
46        );
47        call_noisy_func();
48    });
49
50This method respects flushes on the output streams and will flush if needed
51when the scoped guard is destroyed. This allows the output to be redirected in
52real time, such as to a Jupyter notebook. The two arguments, the C++ stream and
53the Python output, are optional, and default to standard output if not given. An
54extra type, `py::scoped_estream_redirect <scoped_estream_redirect>`, is identical
55except for defaulting to ``std::cerr`` and ``sys.stderr``; this can be useful with
56`py::call_guard`, which allows multiple items, but uses the default constructor:
57
58.. code-block:: py
59
60    // Alternative: Call single function using call guard
61    m.def("noisy_func", &call_noisy_function,
62          py::call_guard<py::scoped_ostream_redirect,
63                         py::scoped_estream_redirect>());
64
65The redirection can also be done in Python with the addition of a context
66manager, using the `py::add_ostream_redirect() <add_ostream_redirect>` function:
67
68.. code-block:: cpp
69
70    py::add_ostream_redirect(m, "ostream_redirect");
71
72The name in Python defaults to ``ostream_redirect`` if no name is passed.  This
73creates the following context manager in Python:
74
75.. code-block:: python
76
77    with ostream_redirect(stdout=True, stderr=True):
78        noisy_function()
79
80It defaults to redirecting both streams, though you can use the keyword
81arguments to disable one of the streams if needed.
82
83.. note::
84
85    The above methods will not redirect C-level output to file descriptors, such
86    as ``fprintf``. For those cases, you'll need to redirect the file
87    descriptors either directly in C or with Python's ``os.dup2`` function
88    in an operating-system dependent way.
89
90.. _eval:
91
92Evaluating Python expressions from strings and files
93====================================================
94
95pybind11 provides the `eval`, `exec` and `eval_file` functions to evaluate
96Python expressions and statements. The following example illustrates how they
97can be used.
98
99.. code-block:: cpp
100
101    // At beginning of file
102    #include <pybind11/eval.h>
103
104    ...
105
106    // Evaluate in scope of main module
107    py::object scope = py::module::import("__main__").attr("__dict__");
108
109    // Evaluate an isolated expression
110    int result = py::eval("my_variable + 10", scope).cast<int>();
111
112    // Evaluate a sequence of statements
113    py::exec(
114        "print('Hello')\n"
115        "print('world!');",
116        scope);
117
118    // Evaluate the statements in an separate Python file on disk
119    py::eval_file("script.py", scope);
120
121C++11 raw string literals are also supported and quite handy for this purpose.
122The only requirement is that the first statement must be on a new line following
123the raw string delimiter ``R"(``, ensuring all lines have common leading indent:
124
125.. code-block:: cpp
126
127    py::exec(R"(
128        x = get_answer()
129        if x == 42:
130            print('Hello World!')
131        else:
132            print('Bye!')
133        )", scope
134    );
135
136.. note::
137
138    `eval` and `eval_file` accept a template parameter that describes how the
139    string/file should be interpreted. Possible choices include ``eval_expr``
140    (isolated expression), ``eval_single_statement`` (a single statement, return
141    value is always ``none``), and ``eval_statements`` (sequence of statements,
142    return value is always ``none``). `eval` defaults to  ``eval_expr``,
143    `eval_file` defaults to ``eval_statements`` and `exec` is just a shortcut
144    for ``eval<eval_statements>``.
145