1 files changed, 50 insertions, 0 deletions
diff --git a/libs/plugin_python/src/pybind11-utils/README.md b/libs/plugin_python/src/pybind11-utils/README.md
new file mode 100644
index 0000000..46a9256
--- /dev/null
+++ b/libs/plugin_python/src/pybind11-utils/README.md
@@ -0,0 +1,50 @@
+# pybind11-utils
+
+This library contains some utility stuff for `pybind11`
+
+## smart_variant_wrapper.h
+
+Expose a function `mo2::python::wrap_arguments` and a template
+`mo2::python::smart_variant` that can be used to expose more interesting types Python
+than the C++ one, e.g., accept `os.PathLike` and `QFileInfo` when a simple `QString` is
+expected.
+
+A toy example can be found in the test folder at
+[`tests/python/test_argument_wrapper.cpp`](../../tests/python/test_argument_wrapper.cpp).
+
+More concrete examples can be found in
+[`mobase/pybind11_all.h`](../mobase/pybind11_all.h) for `FileWrapper` and
+`DirectoryWrapper`.
+
+## functional.h
+
+TODO: updated version of `<pybind11/functional.h>` that should check the signature
+a bit more when creating `std::function` (similar to previous implementation).
+
+## shared_cpp_owner.h
+
+Expose a macro `MO2_PYBIND11_SHARED_CPP_HOLDER` that can be used to declare that
+`std::shared_ptr<...>` must hold-on their associate Python object.
+
+```cpp
+// use the macro on the type to be exposed (with a trampoline class)
+MO2_PYBIND11_SHARED_CPP_HOLDER(ISaveGame)
+
+// use std::shared_ptr<> as the holder for the class
+py::class_<ISaveGame, PySaveGame, std::shared_ptr<ISaveGame>>(...);
+```
+
+Using the `MO2_PYBIND11_SHARED_CPP_HOLDER` (must be present in all files manipulating
+`ISaveGame` between C++ and Python) ensure that the Python instance remains alive
+alongside the C++ one.
+
+The `MO2_PYBIND11_SHARED_CPP_HOLDER` declares a specialization of `type_caster<>` that
+alters the `std::shared_ptr` by return a `std::shared_ptr<>` that owns the Python
+object (via a `pybind11::object`) but does not release the C++ one - The C++ object is
+owned by the Python one, so the relation is as follows:
+
+- The `std::shared_ptr<X>` manipulated in C++ maintains the `pybind11::object` alive
+  through a custom deleter but DOES NOT release the C++ object when the reference count
+  reaches 0.
+- The Python object holds a standard `std::shared_ptr<X>` that will release the object
+  when the reference count reaches 0.