lot of cleaning up

Author: aoloe

README.md

@@ -1,10 +1,23 @@
-# pybind11
+# pybind11 as a scripting engine
+
+This tutorial explains in 14 steps how to use `pybind11` for creating a Python scripting engine for a Qt application.
+
+It first explains how to create a module that can be imported in Python, continues by prosenting different aspects of running inside of a C++ (Qt) application a Python script that can access (and modify) the status of the main application.
+
+Each step contains code that can be individually compiled, run, and – of course – modified.
+
+You should probably go through each step in the order presented below, since the commands are (briefly) introduced only once.
 
 ## Getting pybind11
 
-By default, the samples in this repositories use a pre-compiled version of pybind11.
+There are three ways for getting pybind11:
 
-You will have to first get pybind11, compile it, and install it:
+- _Embedding_ it in your project as a Git submodule.
+- Installing pybind11 through your package manager (or downloading binaries that are installed in the system path).
+- Compiling pybind11 in a separate directory.
+
+
+The samples in this repositories use a pre-compiled version of pybind11. If you're not getting pybind11 from your distribution repositories:
 
 - get the code from github
 - compile it:
@@ -21,43 +34,52 @@ You need:
 - a development environment for C++ (g++ or clang; cmake, ...)
 - the Python bindings (`libpython3-dev`, `python-cxx-dev`, ...)
 
-Our [first example](add/) directly uses the compiler, all other examples will need a modern version of `cmake` being installed (pybind11 should have cmake 3.4)
+Our [first example](add/) directly uses the compiler, all other examples will need a modern version of `cmake` being installed (pybind11 needs cmake 3.4)
 
 ## Sample projects
 
-- [`add/`](add/): using a c++ module to add two numbers in Python
-- [`add-cmake`](add-cmake/): the first example plus cmake
-- [`classes/`](classes/): let Python use C++ classes
+- [`add/`](add/): create a module providing a C++ `add` function that can be add two numbers.
+- [`add-cmake`](add-cmake/): the first example with CMake (all further examples use CMake).
+- [`classes/`](classes/): let Python use C++ classes.
 - [`eval-file/`](eval-file/): C++ evaluates a Python script in an external files that modifies the state of a C++ variable.
-- [`eval-set-object/`](eval-set-object/): Create two objects of type `Foo` and pass them to a Python script (defined as a string in the C++ code)
-- [`eval-set-object-module/`](eval-set-object-module/): Create a `.so` module for the `Foo` type, load it get the Python script to access it.
+- [`eval-set-object/`](eval-set-object/): Create two objects of type `Foo` and pass them by value or by reference to a Python script (defined as a string in the C++ code)
+- [`eval-set-object-module/`](eval-set-object-module/): Create a `.so` module for the `Foo` type, load it in the Python interpreter and let the Python script access it.
 - [`eval-file-pyqt5/`](eval-file-pyqt5/): The C++ code runs an external Python script that shows a PyQt5 alert.
+- [`eval-file-pyqt5-set-value/`](eval-file-pyqt5-set-value/): Setting a C++ value from a PyQt5 input dialog.
 - ...
 
 ## Links
 
-- and HN thread: <https://news.ycombinator.com/item?id=15095757>
+- an HN thread: <https://news.ycombinator.com/item?id=15095757>
 - how to use cmake with pybind11 <https://github.com/pybind/pybind11/pull/1098>
 
 ## Notes
 
 - pybind11 runs python code as if it was run in Python's `exec()` call. The visibility of the global and local variables works in the same way: <https://gist.github.com/dean0x7d/df5ce97e4a1a05be4d56d1378726ff92>
+- read https://github.com/GooFit/GooFit/blob/master/python/goofit/Variable.cpp as an example for...
 
 ## alternatives
 
 - [cppy](https://pypi.python.org/pypi/cppyy) is an automatic Python-C++ bindings generator designed for large scale programs in high performance computing that use modern C++.
 
 ## todo
 
-document all directories:
+- [ ] adapt all `CMakeLists.txt` files to require Python 3.7. (`eval-set-object-module` does somehow require it)
+- [ ] use pyside2 on top of pyqt5
+- [ ] can python use the c++ qt widgets (add an entry to the menus, add keyboard shortcuts); can we have callbacks back to python code from the c++ app?
+- [ ] in the qt5-pyqt example there is a "visibility" warning.
+- [ ] Try to add a menu entry from pyqt5
+- [ ] Try with PySide2
+
+Document all directories:
 
 - [x] add
 - [x] add-cmake
-- [ ] classes
-- [ ] eval-file
-- [ ] eval-set-object
-- [ ] eval-set-object-module
-- [ ] eval-file-pyqt5
+- [x] classes
+- [x] eval-file
+- [x] eval-set-object
+- [x] eval-set-object-module
+- [x] eval-file-pyqt5
 - [ ] eval-file-pyqt5-set-value
 - [ ] scripter-api
 - [ ] scripter-class

add-cmake/README.md

@@ -1,22 +1,49 @@
 # pybind11 and cmake
 
-This second example shows how to use cmake to simplify the compilation of the [add example](../add).
+This second example shows how to use cmake to compile the [add example](../add).
 
-Using `cmake` avoid us the use of the complex `g++` call in the [add example](../add).
-
-Like all examples in this repository we're not binding `pybind11` as a git submodule but compile it separately in `~/bin`
+All further examples, will use cmake.
 
 The `pybind11_DIR` passed to the cmake commands tells the compiler where to find the library.
 
-There is an official demo project that fetches pybind11 as a git submodule: <https://github.com/pybind/cmake_example>.
+This sample uses a "pre-compiled" version of pybind11. If you prefer using git submodules, please refer to the official demo project that fetches pybind11 as a git submodule: <https://github.com/pybind/cmake_example>.
+
+## The `CMakeLists.txt` file
+
+```cmake
+cmake_minimum_required(VERSION 3.4)
+project(maths)
+
+set(PYBIND11_PYTHON_VERSION 3.4)
+
+find_package(pybind11 CONFIG)
+
+pybind11_add_module(maths
+    src/maths.cpp
+)
+```
+
+## Compiling and running
 
-~~~.sh
+```.sh
 $ mkdir build
 $ cd build
-$ cmake -Dpybind11_DIR=~/bin/pybind11/share/cmake/pybind11 ..
+$ cmake ..
 $ make
+```
+
+If cmake is not installed in a standard path, you'll need to tell cmake where it is installed by providing `pybind11_DIR` :
+
+```.sh
+$ cmake -Dpybind11_DIR=~/bin/pybind11/share/cmake/pybind11 ..
+```
+
+You will now have a file with a name similar to `maths.cpython-37m-x86_64-linux-gnu.so` which you can import in python3:
+
+
+```sh
 $ python3
 >>> import maths
->>> maths.add(1,2)
+>>> maths.add(1, 2)
 3
-~~~
+```

add/README.md

@@ -1,16 +1,50 @@
 # Add: the first example
 
-This first example shows how to create a python module providing the `add()` function that returns the sum of the two integers given as a parameter.
+This first example shows how to program in C++ a python module providing an `add()` function.
 
-This is the compile command that works for me:
+When imported in Pyhton, `add(a, b)` returns the sum of the two integers given as a parameter.
 
-```.sh
-c++ -O3 -shared -fPIC -std=c++11 -I ~/src/pybind11/include -I /usr/include/python3.5 -L /usr/lib/python3 `python-config --cflags --ldflags` maths.cpp -o maths.so
+A very simple C++ library provides a function that returns the sum of two integer numbers:
+
+
+```cpp
+#include <pybind11/pybind11.h>
+
+namespace py = pybind11;
+
+int add(int i, int j)
+{
+    return i + j;
+}
+
+PYBIND11_MODULE(maths, m) {
+    m.doc() = "pybind11 example plugin"; // optional module docstring
+
+    m.def("add", &add, "A function which adds two numbers");
+}
 ```
 
-As a result ou will get the python library `maths.so`.
+The `PYBIND11_MODULE` macro creates a `maths` module:
+
+- it first sets the documentation string for the module, then
+- defines:
+  - a Python function called `add`,
+  - that will call the C++ `add` function passed as a reference,
+  - and finally defines a documentation string for the `add` function.
 
-You can now import the "maths" module in Python3. Start Python3 in the directory where the file is located and:
+If everything is setup _correctly_, you can compile the `maths.cpp` file with:
+
+```sh
+c++ -O3 -shared -fPIC `python-config --cflags --ldflags` src/maths.cpp -o maths.so
+```
+
+- If you're compiler does not default to (at least) C++ 11, you will need `-std=c++11`
+- If you have a _local_ version of `pybind11` you will need  `-fPIC -std=c++11 -I ~/src/pybind11/include`
+- If your system does not defaul to Python 3, `-I /usr/include/python3.7 -L /usr/lib/python3`
+
+As a result you will get the python library `maths.so`.
+
+You can now import the "maths" module in Python3. Start Python3 in the directory where the `.so` file is located and:
 
 ```.py
 >>> import maths
@@ -19,27 +53,33 @@ You can now import the "maths" module in Python3. Start Python3 in the directory
 >>>
 ```
 
-# Notes
+You can also see the documentation with
 
-the pybind11 documentation is suggesting the following:
+```.py
+>>> import maths
+>>> help(maths)
+Help on module maths:
 
-  ```.sh
-  c++ -O3 -shared -std=c++11 -I <path-to-pybind11>/include `python-config --cflags --ldflags` maths.cpp -o maths.so
-  ```
+NAME
+    maths - pybind11 example plugin
 
-but it fails for me.
+FUNCTIONS
+    add(...) method of builtins.PyCapsule instance
+        add(arg0: int, arg1: int) -> int
 
-First I need to tell the compiler to use Python3 (since Debian and many other Linux distributions still default to Python2):
+        A function which adds two numbers
 
-  ```.sh
-  c++ -O3 -shared -fPIC -std=c++11 -I ~/src/pybind11/include -I /usr/include/python3.5 -L /usr/lib/python3 `python-config --cflags --ldflags` maths.cpp -o maths.so
-  ```
+FILE
+    /home/ale/src/cpp-pybind11-playground/add/maths.so
+```
 
-  (<https://docs.python.org/3/extending/embedding.html#compiling-and-linking-under-unix-like-systems>)
+## Notes
 
-Then I need to add a `main()` function in the `.cpp` file.
+My full g++ command is:
 
-Question: (how) can I compile a pure library without any main?
+```
+g++ -O3 -shared -fPIC -std=c++11 -I ~/src/pybind11/include -I /usr/include/python3.7 -L /usr/lib/python3 `python-config --cflags --ldflags` src/maths.cpp -o maths.so
+```
 
 ## Further steps
 

add/maths.cpp

@@ -0,0 +1,14 @@
+#include <pybind11/pybind11.h>
+
+namespace py = pybind11;
+
+int add(int i, int j)
+{
+    return i + j;
+}
+
+PYBIND11_MODULE(maths, m) {
+    m.doc() = "pybind11 example plugin"; // optional module docstring
+
+    m.def("add", &add, "A function which adds two numbers");
+}

add/src/maths.cpp

@@ -2,15 +2,34 @@
 
 The `pet` module provides the `Dog` and `Cat` classes.
 
-Both classes have the `getName()` and `setName()` class functions.
+Both C++ classes have a `getName()` and a `setName()` class functions.
 
-`Dog` is added to the Python module with a getter and a setter.
+The `Dog` and `Cat` classes are exposed in a different way to the Python code:
 
-`Cat` is more _pythonic_ and can access the C++ accessor as a property.
+- `Dog` is added to the Python module with a getter and a setter.
+- `Cat` is more _pythonic_ and provides access to the C++ accessors as a property.
 
-~~~.sh
+In C++, both classes are defined in the exact same way, but:
+
+- the `get` and `set` function of the `Dog` class are bound to functions of the same name in Python
+- for the `Cat` the `name` class property on the Python side is _using_ the C++ getter and setter to read and write the `name` value.
+
+```py
+py::class_<Dog>(m, "Dog")
+.def(py::init<const std::string &>())
+.def("setName", &Dog::setName, "Setting the dog's name")
+.def("getName", &Dog::getName), "Getting the dog's name";
+
+py::class_<Cat>(m, "Cat")
+.def(py::init<const std::string &>())
+.def_property("name", &Cat::getName, &Cat::setName, "The cat name");
+```
+
+You can compile and import the `pet` module, containing a `Dog` and a `Cat` classes:
+
+```.sh
 $ mkdir build
-$ cmake -Dpybind11_DIR=~/bin/pybind11/share/cmake/pybind11 ..
+$ cmake ..
 $ make
 $ python3
 >>> import pet
@@ -28,5 +47,4 @@ $ python3
 >>> b.name = 'Fix'
 >>> b.name
 'Fix'
-~~~
-
+```

classes/README.md

@@ -35,5 +35,5 @@ PYBIND11_MODULE(pet, m) {
 
     py::class_<Cat>(m, "Cat")
     .def(py::init<const std::string &>())
-    .def_property("name", &Cat::getName, &Cat::setName);
+    .def_property("name", &Cat::getName, &Cat::setName, "The cat name");
 }

classes/src/main.cpp

@@ -1,10 +1,20 @@
 cmake_minimum_required(VERSION 3.4)
 project(scripting)
 
-set(PYBIND11_PYTHON_VERSION 3.4)
+set(PYBIND11_PYTHON_VERSION 3.7)
 
-FIND_PACKAGE(pybind11 CONFIG)
+find_package(pybind11 CONFIG)
 
-ADD_EXECUTABLE(scripting src/main.cpp)
-TARGET_LINK_LIBRARIES(scripting ${PYTHON_LIBRARIES})
-TARGET_LINK_LIBRARIES(scripting pybind11::embed)
+add_executable(scripting
+    src/main.cpp
+)
+
+target_link_libraries(scripting
+    pybind11::embed
+)
+
+configure_file(
+    ${CMAKE_CURRENT_SOURCE_DIR}/python/input-number.py
+    ${CMAKE_CURRENT_BINARY_DIR}
+    COPYONLY
+)

eval-file-pyqt5-set-value/CMakeLists.txt

@@ -1,8 +1,16 @@
-# A python script running a PyQt5 input dialog and setting a c++ variable with the value
+# Setting a C++ value from a PyQt5 input dialog
+
+The C++ program defines a `set_the_answer` lambda that can receive the new value and passes it as `local` to the `input-number.py` script.
+
+The Python script creates an (PyQt) application that is showing an input dialog. If the _Ok_ button is pressed, the `set_the_answer()` function passes the value to the C++ code.
+
+It is to be noted that `pybind11` is passing the `set_the_answer()` as a local to the _eval_ (exec, in reality) Python context: we need to explicitely pass the function to the `get_the_value()` to make it visible inside of it.  
+(This is becaue Python executes the code as if it was in a class environment... I've been told.)
 
 ~~~.sh
 $ mkdir build
-$ cmake -Dpybind11_DIR=/home/ale/bin/pybind11/share/cmake/pybind11 ..
+$ cd build
+$ cmake ..
 $ make
 $ ./scripting
 ~~~