utilities.rst 5.0 KB

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