complete rewrite of eval/exec patch
diff --git a/docs/advanced.rst b/docs/advanced.rst
index a13bc2b..2a0e268 100644
--- a/docs/advanced.rst
+++ b/docs/advanced.rst
@@ -282,7 +282,7 @@
The macro :func:`PYBIND11_OVERLOAD_PURE` should be used for pure virtual
functions, and :func:`PYBIND11_OVERLOAD` should be used for functions which have
-a default implementation.
+a default implementation.
There are also two alternate macros :func:`PYBIND11_OVERLOAD_PURE_NAME` and
:func:`PYBIND11_OVERLOAD_NAME` which take a string-valued name argument
@@ -1612,32 +1612,38 @@
.. [#f4] http://www.sphinx-doc.org
.. [#f5] http://github.com/pybind/python_example
-Calling Python from C++
-=======================
+Evaluating Python expressions from strings and files
+====================================================
-Pybind11 also allows to call python code from C++. Note that this code assumes, that the intepreter is already initialized.
+pybind11 provides the :func:`eval` and :func:`eval_file` functions to evaluate
+Python expressions and statements. The following example illustrates how they
+can be used.
+
+Both functions accept a template parameter that describes how the argument
+should be interpreted. Possible choices include ``eval_expr`` (isolated
+expression), ``eval_single_statement`` (a single statement, return value is
+always ``none``), and ``eval_statements`` (sequence of statements, return value
+is always ``none``).
.. code-block:: cpp
- // get the main module, so we can access and declare stuff
- py::module main_module = py::module::import("__main__");
-
- //get the main namespace, so I can declare variables
- py::object main_namespace = main_module.attr("__dict__");
+ // At beginning of file
+ #include <pybind11/eval.h>
- //now execute code
- py::exec(
- "print('Hello World1!')\n"
- "print('Other Data');",
- main_namespace);
+ ...
- //execute a single statement
- py::exec_statement("x=42", main_namespace);
+ // Evaluate in scope of main module
+ py::object scope = py::module::import("__main__").attr("__dict__");
- //ok, now I want to get the result of a statement, we'll use x in this example
- py::object res = py::eval("x");
- std:cout << "Yielded: " << res.cast<int>() << std::endl;
-
- //or we can execute a file within the same content
- py::exec_file("my_script.py", main_namespace);
-
+ // Evaluate an isolated expression
+ int result = py::eval("my_variable + 10", scope).cast<int>();
+
+ // Evaluate a sequence of statements
+ py::eval<py::eval_statements>(
+ "print('Hello')\n"
+ "print('world!');",
+ scope);
+
+ // Evaluate the statements in an separate Python file on disk
+ py::eval_file("script.py", scope);
+
diff --git a/docs/reference.rst b/docs/reference.rst
index e3fe018..7edc43a 100644
--- a/docs/reference.rst
+++ b/docs/reference.rst
@@ -244,26 +244,4 @@
.. function:: name::name(const char *value)
Used to specify the function name
-
-Calling Python from C++
-=======================
-
-.. function:: eval(str string, object global = object(), object local = object())
-
- Evaluate a statement, i.e. one that does not yield None.
- The return value the result of the expression. It throws pybind11::error_already_set if the commands are invalid.
-
-.. function:: exec(str string, object global = object(), object local = object())
-
- Execute a set of statements. The return value the result of the code. It throws pybind11::error_already_set if the commands are invalid.
-
-.. function:: exec_statement(str string, object global = object(), object local = object())
-
- Execute a single statement. The return value the result of the code. It throws pybind11::error_already_set if the commands are invalid.
-
-.. function:: exec_file(str filename, object global = object(), object local = object())
-
- Execute a file. The function exec_file will throw std::invalid_argument if the file cannot be opened.
- The return value the result of the code. It throws pybind11::error_already_set if the commands are invalid and
- std::invalid_argument if the file cannot be opened.