diff options
Diffstat (limited to '3rdparty/pybind11/docs')
30 files changed, 1903 insertions, 466 deletions
diff --git a/3rdparty/pybind11/docs/Doxyfile b/3rdparty/pybind11/docs/Doxyfile index 1b9d1297..c8562952 100644 --- a/3rdparty/pybind11/docs/Doxyfile +++ b/3rdparty/pybind11/docs/Doxyfile @@ -18,3 +18,6 @@ ALIASES += "endrst=\endverbatim" QUIET = YES WARNINGS = YES WARN_IF_UNDOCUMENTED = NO +PREDEFINED = DOXYGEN_SHOULD_SKIP_THIS \ + PY_MAJOR_VERSION=3 \ + PYBIND11_NOINLINE diff --git a/3rdparty/pybind11/docs/advanced/cast/custom.rst b/3rdparty/pybind11/docs/advanced/cast/custom.rst index e4f99ac5..a779444c 100644 --- a/3rdparty/pybind11/docs/advanced/cast/custom.rst +++ b/3rdparty/pybind11/docs/advanced/cast/custom.rst @@ -29,9 +29,9 @@ The following Python snippet demonstrates the intended usage from the Python sid from example import print print(A()) -To register the necessary conversion routines, it is necessary to add -a partial overload to the ``pybind11::detail::type_caster<T>`` template. -Although this is an implementation detail, adding partial overloads to this +To register the necessary conversion routines, it is necessary to add an +instantiation of the ``pybind11::detail::type_caster<T>`` template. +Although this is an implementation detail, adding an instantiation of this type is explicitly allowed. .. code-block:: cpp diff --git a/3rdparty/pybind11/docs/advanced/cast/eigen.rst b/3rdparty/pybind11/docs/advanced/cast/eigen.rst index 59ba08c3..e01472d5 100644 --- a/3rdparty/pybind11/docs/advanced/cast/eigen.rst +++ b/3rdparty/pybind11/docs/advanced/cast/eigen.rst @@ -274,7 +274,7 @@ Vectors versus column/row matrices Eigen and numpy have fundamentally different notions of a vector. In Eigen, a vector is simply a matrix with the number of columns or rows set to 1 at -compile time (for a column vector or row vector, respectively). Numpy, in +compile time (for a column vector or row vector, respectively). NumPy, in contrast, has comparable 2-dimensional 1xN and Nx1 arrays, but *also* has 1-dimensional arrays of size N. diff --git a/3rdparty/pybind11/docs/advanced/cast/index.rst b/3rdparty/pybind11/docs/advanced/cast/index.rst index 54c10570..3ce9ea02 100644 --- a/3rdparty/pybind11/docs/advanced/cast/index.rst +++ b/3rdparty/pybind11/docs/advanced/cast/index.rst @@ -1,3 +1,5 @@ +.. _type-conversions: + Type conversions ################ @@ -39,4 +41,3 @@ the last case of the above list. chrono eigen custom - diff --git a/3rdparty/pybind11/docs/advanced/cast/stl.rst b/3rdparty/pybind11/docs/advanced/cast/stl.rst index e48409f0..70fde0d2 100644 --- a/3rdparty/pybind11/docs/advanced/cast/stl.rst +++ b/3rdparty/pybind11/docs/advanced/cast/stl.rst @@ -5,7 +5,7 @@ Automatic conversion ==================== When including the additional header file :file:`pybind11/stl.h`, conversions -between ``std::vector<>``/``std::deque<>``/``std::list<>``/``std::array<>``, +between ``std::vector<>``/``std::deque<>``/``std::list<>``/``std::array<>``/``std::valarray<>``, ``std::set<>``/``std::unordered_set<>``, and ``std::map<>``/``std::unordered_map<>`` and the Python ``list``, ``set`` and ``dict`` data structures are automatically enabled. The types ``std::pair<>`` @@ -157,7 +157,7 @@ the declaration before any binding code (e.g. invocations to ``class_::def()``, etc.). This macro must be specified at the top level (and outside of any namespaces), since -it instantiates a partial template overload. If your binding code consists of +it adds a template instantiation of ``type_caster``. If your binding code consists of multiple compilation units, it must be present in every file (typically via a common header) preceding any usage of ``std::vector<int>``. Opaque types must also have a corresponding ``class_`` declaration to associate them with a name diff --git a/3rdparty/pybind11/docs/advanced/classes.rst b/3rdparty/pybind11/docs/advanced/classes.rst index ae5907de..49279020 100644 --- a/3rdparty/pybind11/docs/advanced/classes.rst +++ b/3rdparty/pybind11/docs/advanced/classes.rst @@ -71,7 +71,7 @@ helper class that is defined as follows: /* Trampoline (need one for each virtual function) */ std::string go(int n_times) override { - PYBIND11_OVERLOAD_PURE( + PYBIND11_OVERRIDE_PURE( std::string, /* Return type */ Animal, /* Parent class */ go, /* Name of function in C++ (must match Python name) */ @@ -80,10 +80,10 @@ helper class that is defined as follows: } }; -The macro :c:macro:`PYBIND11_OVERLOAD_PURE` should be used for pure virtual -functions, and :c:macro:`PYBIND11_OVERLOAD` should be used for functions which have -a default implementation. There are also two alternate macros -:c:macro:`PYBIND11_OVERLOAD_PURE_NAME` and :c:macro:`PYBIND11_OVERLOAD_NAME` which +The macro :c:macro:`PYBIND11_OVERRIDE_PURE` should be used for pure virtual +functions, and :c:macro:`PYBIND11_OVERRIDE` should be used for functions which have +a default implementation. There are also two alternate macros +:c:macro:`PYBIND11_OVERRIDE_PURE_NAME` and :c:macro:`PYBIND11_OVERRIDE_NAME` which take a string-valued name argument between the *Parent class* and *Name of the function* slots, which defines the name of function in Python. This is required when the C++ and Python versions of the @@ -122,7 +122,7 @@ Bindings should be made against the actual class, not the trampoline helper clas Note, however, that the above is sufficient for allowing python classes to extend ``Animal``, but not ``Dog``: see :ref:`virtual_and_inheritance` for the -necessary steps required to providing proper overload support for inherited +necessary steps required to providing proper overriding support for inherited classes. The Python session below shows how to override ``Animal::go`` and invoke it via @@ -149,13 +149,17 @@ memory for the C++ portion of the instance will be left uninitialized, which will generally leave the C++ instance in an invalid state and cause undefined behavior if the C++ instance is subsequently used. +.. versionchanged:: 2.6 + The default pybind11 metaclass will throw a ``TypeError`` when it detects + that ``__init__`` was not called by a derived class. + Here is an example: .. code-block:: python class Dachshund(Dog): def __init__(self, name): - Dog.__init__(self) # Without this, undefined behavior may occur if the C++ portions are referenced. + Dog.__init__(self) # Without this, a TypeError is raised. self.name = name def bark(self): return "yap!" @@ -177,15 +181,24 @@ Please take a look at the :ref:`macro_notes` before using this feature. - because in these cases there is no C++ variable to reference (the value is stored in the referenced Python variable), pybind11 provides one in - the PYBIND11_OVERLOAD macros (when needed) with static storage duration. - Note that this means that invoking the overloaded method on *any* + the PYBIND11_OVERRIDE macros (when needed) with static storage duration. + Note that this means that invoking the overridden method on *any* instance will change the referenced value stored in *all* instances of that type. - Attempts to modify a non-const reference will not have the desired effect: it will change only the static cache variable, but this change will not propagate to underlying Python instance, and the change will be - replaced the next time the overload is invoked. + replaced the next time the override is invoked. + +.. warning:: + + The :c:macro:`PYBIND11_OVERRIDE` and accompanying macros used to be called + ``PYBIND11_OVERLOAD`` up until pybind11 v2.5.0, and :func:`get_override` + used to be called ``get_overload``. This naming was corrected and the older + macro and function names may soon be deprecated, in order to reduce + confusion with overloaded functions and methods and ``py::overload_cast`` + (see :ref:`classes`). .. seealso:: @@ -233,20 +246,20 @@ override the ``name()`` method): class PyAnimal : public Animal { public: using Animal::Animal; // Inherit constructors - std::string go(int n_times) override { PYBIND11_OVERLOAD_PURE(std::string, Animal, go, n_times); } - std::string name() override { PYBIND11_OVERLOAD(std::string, Animal, name, ); } + std::string go(int n_times) override { PYBIND11_OVERRIDE_PURE(std::string, Animal, go, n_times); } + std::string name() override { PYBIND11_OVERRIDE(std::string, Animal, name, ); } }; class PyDog : public Dog { public: using Dog::Dog; // Inherit constructors - std::string go(int n_times) override { PYBIND11_OVERLOAD(std::string, Dog, go, n_times); } - std::string name() override { PYBIND11_OVERLOAD(std::string, Dog, name, ); } - std::string bark() override { PYBIND11_OVERLOAD(std::string, Dog, bark, ); } + std::string go(int n_times) override { PYBIND11_OVERRIDE(std::string, Dog, go, n_times); } + std::string name() override { PYBIND11_OVERRIDE(std::string, Dog, name, ); } + std::string bark() override { PYBIND11_OVERRIDE(std::string, Dog, bark, ); } }; .. note:: - Note the trailing commas in the ``PYBIND11_OVERLOAD`` calls to ``name()`` + Note the trailing commas in the ``PYBIND11_OVERIDE`` calls to ``name()`` and ``bark()``. These are needed to portably implement a trampoline for a function that does not take any arguments. For functions that take a nonzero number of arguments, the trailing comma must be omitted. @@ -261,9 +274,9 @@ declare or override any virtual methods itself: class PyHusky : public Husky { public: using Husky::Husky; // Inherit constructors - std::string go(int n_times) override { PYBIND11_OVERLOAD_PURE(std::string, Husky, go, n_times); } - std::string name() override { PYBIND11_OVERLOAD(std::string, Husky, name, ); } - std::string bark() override { PYBIND11_OVERLOAD(std::string, Husky, bark, ); } + std::string go(int n_times) override { PYBIND11_OVERRIDE_PURE(std::string, Husky, go, n_times); } + std::string name() override { PYBIND11_OVERRIDE(std::string, Husky, name, ); } + std::string bark() override { PYBIND11_OVERRIDE(std::string, Husky, bark, ); } }; There is, however, a technique that can be used to avoid this duplication @@ -276,15 +289,15 @@ follows: template <class AnimalBase = Animal> class PyAnimal : public AnimalBase { public: using AnimalBase::AnimalBase; // Inherit constructors - std::string go(int n_times) override { PYBIND11_OVERLOAD_PURE(std::string, AnimalBase, go, n_times); } - std::string name() override { PYBIND11_OVERLOAD(std::string, AnimalBase, name, ); } + std::string go(int n_times) override { PYBIND11_OVERRIDE_PURE(std::string, AnimalBase, go, n_times); } + std::string name() override { PYBIND11_OVERRIDE(std::string, AnimalBase, name, ); } }; template <class DogBase = Dog> class PyDog : public PyAnimal<DogBase> { public: using PyAnimal<DogBase>::PyAnimal; // Inherit constructors // Override PyAnimal's pure virtual go() with a non-pure one: - std::string go(int n_times) override { PYBIND11_OVERLOAD(std::string, DogBase, go, n_times); } - std::string bark() override { PYBIND11_OVERLOAD(std::string, DogBase, bark, ); } + std::string go(int n_times) override { PYBIND11_OVERRIDE(std::string, DogBase, go, n_times); } + std::string bark() override { PYBIND11_OVERRIDE(std::string, DogBase, bark, ); } }; This technique has the advantage of requiring just one trampoline method to be @@ -298,8 +311,8 @@ The classes are then registered with pybind11 using: .. code-block:: cpp py::class_<Animal, PyAnimal<>> animal(m, "Animal"); - py::class_<Dog, PyDog<>> dog(m, "Dog"); - py::class_<Husky, PyDog<Husky>> husky(m, "Husky"); + py::class_<Dog, Animal, PyDog<>> dog(m, "Dog"); + py::class_<Husky, Dog, PyDog<Husky>> husky(m, "Husky"); // ... add animal, dog, husky definitions Note that ``Husky`` did not require a dedicated trampoline template class at @@ -337,7 +350,7 @@ valid for the trampoline class but not the registered class. This is primarily for performance reasons: when the trampoline class is not needed for anything except virtual method dispatching, not initializing the trampoline class improves performance by avoiding needing to do a run-time check to see if the -inheriting python instance has an overloaded method. +inheriting python instance has an overridden method. Sometimes, however, it is useful to always initialize a trampoline class as an intermediate class that does more than just handle virtual method dispatching. @@ -368,7 +381,7 @@ references (See also :ref:`faq_reference_arguments`). Another way of solving this is to use the method body of the trampoline class to do conversions to the input and return of the Python method. -The main building block to do so is the :func:`get_overload`, this function +The main building block to do so is the :func:`get_override`, this function allows retrieving a method implemented in Python from within the trampoline's methods. Consider for example a C++ method which has the signature ``bool myMethod(int32_t& value)``, where the return indicates whether @@ -380,10 +393,10 @@ Python side by allowing the Python function to return ``None`` or an ``int``: bool MyClass::myMethod(int32_t& value) { pybind11::gil_scoped_acquire gil; // Acquire the GIL while in this scope. - // Try to look up the overloaded method on the Python side. - pybind11::function overload = pybind11::get_overload(this, "myMethod"); - if (overload) { // method is found - auto obj = overload(value); // Call the Python function. + // Try to look up the overridden method on the Python side. + pybind11::function override = pybind11::get_override(this, "myMethod"); + if (override) { // method is found + auto obj = override(value); // Call the Python function. if (py::isinstance<py::int_>(obj)) { // check if it returned a Python integer type value = obj.cast<int32_t>(); // Cast it and assign it to the value. return true; // Return true; value should be used. @@ -554,6 +567,46 @@ crucial that instances are deallocated on the C++ side to avoid memory leaks. py::class_<MyClass, std::unique_ptr<MyClass, py::nodelete>>(m, "MyClass") .def(py::init<>()) +.. _destructors_that_call_python: + +Destructors that call Python +============================ + +If a Python function is invoked from a C++ destructor, an exception may be thrown +of type :class:`error_already_set`. If this error is thrown out of a class destructor, +``std::terminate()`` will be called, terminating the process. Class destructors +must catch all exceptions of type :class:`error_already_set` to discard the Python +exception using :func:`error_already_set::discard_as_unraisable`. + +Every Python function should be treated as *possibly throwing*. When a Python generator +stops yielding items, Python will throw a ``StopIteration`` exception, which can pass +though C++ destructors if the generator's stack frame holds the last reference to C++ +objects. + +For more information, see :ref:`the documentation on exceptions <unraisable_exceptions>`. + +.. code-block:: cpp + + class MyClass { + public: + ~MyClass() { + try { + py::print("Even printing is dangerous in a destructor"); + py::exec("raise ValueError('This is an unraisable exception')"); + } catch (py::error_already_set &e) { + // error_context should be information about where/why the occurred, + // e.g. use __func__ to get the name of the current function + e.discard_as_unraisable(__func__); + } + } + }; + +.. note:: + + pybind11 does not support C++ destructors marked ``noexcept(false)``. + +.. versionadded:: 2.6 + .. _implicit_conversions: Implicit conversions @@ -768,13 +821,17 @@ An instance can now be pickled as follows: p.setExtra(15) data = pickle.dumps(p, 2) -Note that only the cPickle module is supported on Python 2.7. The second -argument to ``dumps`` is also crucial: it selects the pickle protocol version -2, since the older version 1 is not supported. Newer versions are also fine—for -instance, specify ``-1`` to always use the latest available version. Beware: -failure to follow these instructions will cause important pybind11 memory -allocation routines to be skipped during unpickling, which will likely lead to -memory corruption and/or segmentation faults. + +.. note:: + Note that only the cPickle module is supported on Python 2.7. + + The second argument to ``dumps`` is also crucial: it selects the pickle + protocol version 2, since the older version 1 is not supported. Newer + versions are also fine—for instance, specify ``-1`` to always use the + latest available version. Beware: failure to follow these instructions + will cause important pybind11 memory allocation routines to be skipped + during unpickling, which will likely lead to memory corruption and/or + segmentation faults. .. seealso:: @@ -784,6 +841,38 @@ memory corruption and/or segmentation faults. .. [#f3] http://docs.python.org/3/library/pickle.html#pickling-class-instances +Deepcopy support +================ + +Python normally uses references in assignments. Sometimes a real copy is needed +to prevent changing all copies. The ``copy`` module [#f5]_ provides these +capabilities. + +On Python 3, a class with pickle support is automatically also (deep)copy +compatible. However, performance can be improved by adding custom +``__copy__`` and ``__deepcopy__`` methods. With Python 2.7, these custom methods +are mandatory for (deep)copy compatibility, because pybind11 only supports +cPickle. + +For simple classes (deep)copy can be enabled by using the copy constructor, +which should look as follows: + +.. code-block:: cpp + + py::class_<Copyable>(m, "Copyable") + .def("__copy__", [](const Copyable &self) { + return Copyable(self); + }) + .def("__deepcopy__", [](const Copyable &self, py::dict) { + return Copyable(self); + }, "memo"_a); + +.. note:: + + Dynamic attributes will not be copied in this example. + +.. [#f5] https://docs.python.org/3/library/copy.html + Multiple Inheritance ==================== @@ -1024,7 +1113,7 @@ described trampoline: class Trampoline : public A { public: - int foo() const override { PYBIND11_OVERLOAD(int, A, foo, ); } + int foo() const override { PYBIND11_OVERRIDE(int, A, foo, ); } }; class Publicist : public A { @@ -1042,6 +1131,34 @@ described trampoline: ``.def("foo", static_cast<int (A::*)() const>(&Publicist::foo));`` where ``int (A::*)() const`` is the type of ``A::foo``. +Binding final classes +===================== + +Some classes may not be appropriate to inherit from. In C++11, classes can +use the ``final`` specifier to ensure that a class cannot be inherited from. +The ``py::is_final`` attribute can be used to ensure that Python classes +cannot inherit from a specified type. The underlying C++ type does not need +to be declared final. + +.. code-block:: cpp + + class IsFinal final {}; + + py::class_<IsFinal>(m, "IsFinal", py::is_final()); + +When you try to inherit from such a class in Python, you will now get this +error: + +.. code-block:: pycon + + >>> class PyFinalChild(IsFinal): + ... pass + TypeError: type 'IsFinal' is not an acceptable base type + +.. note:: This attribute is currently ignored on PyPy + +.. versionadded:: 2.6 + Custom automatic downcasters ============================ @@ -1124,3 +1241,21 @@ appropriate derived-class pointer (e.g. using more complete example, including a demonstration of how to provide automatic downcasting for an entire class hierarchy without writing one get() function for each class. + +Accessing the type object +========================= + +You can get the type object from a C++ class that has already been registered using: + +.. code-block:: python + + py::type T_py = py::type::of<T>(); + +You can directly use ``py::type::of(ob)`` to get the type object from any python +object, just like ``type(ob)`` in Python. + +.. note:: + + Other types, like ``py::type::of<int>()``, do not work, see :ref:`type-conversions`. + +.. versionadded:: 2.6 diff --git a/3rdparty/pybind11/docs/advanced/embedding.rst b/3rdparty/pybind11/docs/advanced/embedding.rst index 39303160..dfdaad2d 100644 --- a/3rdparty/pybind11/docs/advanced/embedding.rst +++ b/3rdparty/pybind11/docs/advanced/embedding.rst @@ -18,7 +18,7 @@ information, see :doc:`/compiling`. .. code-block:: cmake - cmake_minimum_required(VERSION 3.0) + cmake_minimum_required(VERSION 3.4) project(example) find_package(pybind11 REQUIRED) # or `add_subdirectory(pybind11)` @@ -108,11 +108,11 @@ The two approaches can also be combined: Importing modules ================= -Python modules can be imported using `module::import()`: +Python modules can be imported using `module_::import()`: .. code-block:: cpp - py::module sys = py::module::import("sys"); + py::module_ sys = py::module_::import("sys"); py::print(sys.attr("path")); For convenience, the current working directory is included in ``sys.path`` when @@ -128,12 +128,12 @@ embedding the interpreter. This makes it easy to import local Python files: .. code-block:: cpp - py::module calc = py::module::import("calc"); + py::module_ calc = py::module_::import("calc"); py::object result = calc.attr("add")(1, 2); int n = result.cast<int>(); assert(n == 3); -Modules can be reloaded using `module::reload()` if the source is modified e.g. +Modules can be reloaded using `module_::reload()` if the source is modified e.g. by an external process. This can be useful in scenarios where the application imports a user defined data processing script which needs to be updated after changes by the user. Note that this function does not reload modules recursively. @@ -153,7 +153,7 @@ like any other module. namespace py = pybind11; PYBIND11_EMBEDDED_MODULE(fast_calc, m) { - // `m` is a `py::module` which is used to bind functions and classes + // `m` is a `py::module_` which is used to bind functions and classes m.def("add", [](int i, int j) { return i + j; }); @@ -162,7 +162,7 @@ like any other module. int main() { py::scoped_interpreter guard{}; - auto fast_calc = py::module::import("fast_calc"); + auto fast_calc = py::module_::import("fast_calc"); auto result = fast_calc.attr("add")(1, 2).cast<int>(); assert(result == 3); } @@ -196,7 +196,7 @@ naturally: int main() { py::scoped_interpreter guard{}; - auto py_module = py::module::import("py_module"); + auto py_module = py::module_::import("py_module"); auto locals = py::dict("fmt"_a="{} + {} = {}", **py_module.attr("__dict__")); assert(locals["a"].cast<int>() == 1); diff --git a/3rdparty/pybind11/docs/advanced/exceptions.rst b/3rdparty/pybind11/docs/advanced/exceptions.rst index 75ad7f7f..5eae5562 100644 --- a/3rdparty/pybind11/docs/advanced/exceptions.rst +++ b/3rdparty/pybind11/docs/advanced/exceptions.rst @@ -1,18 +1,24 @@ Exceptions ########## -Built-in exception translation -============================== +Built-in C++ to Python exception translation +============================================ + +When Python calls C++ code through pybind11, pybind11 provides a C++ exception handler +that will trap C++ exceptions, translate them to the corresponding Python exception, +and raise them so that Python code can handle them. -When C++ code invoked from Python throws an ``std::exception``, it is -automatically converted into a Python ``Exception``. pybind11 defines multiple -special exception classes that will map to different types of Python -exceptions: +pybind11 defines translations for ``std::exception`` and its standard +subclasses, and several special exception classes that translate to specific +Python exceptions. Note that these are not actually Python exceptions, so they +cannot be examined using the Python C API. Instead, they are pure C++ objects +that pybind11 will translate the corresponding Python exception when they arrive +at its exception handler. .. tabularcolumns:: |p{0.5\textwidth}|p{0.45\textwidth}| +--------------------------------------+--------------------------------------+ -| C++ exception type | Python exception type | +| Exception thrown by C++ | Translated to Python exception type | +======================================+======================================+ | :class:`std::exception` | ``RuntimeError`` | +--------------------------------------+--------------------------------------+ @@ -46,16 +52,11 @@ exceptions: | | ``__setitem__`` in dict-like | | | objects, etc.) | +--------------------------------------+--------------------------------------+ -| :class:`pybind11::error_already_set` | Indicates that the Python exception | -| | flag has already been set via Python | -| | API calls from C++ code; this C++ | -| | exception is used to propagate such | -| | a Python exception back to Python. | -+--------------------------------------+--------------------------------------+ -When a Python function invoked from C++ throws an exception, it is converted -into a C++ exception of type :class:`error_already_set` whose string payload -contains a textual summary. +Exception translation is not bidirectional. That is, *catching* the C++ +exceptions defined above above will not trap exceptions that originate from +Python. For that, catch :class:`pybind11::error_already_set`. See :ref:`below +<handling_python_exceptions_cpp>` for further details. There is also a special exception :class:`cast_error` that is thrown by :func:`handle::call` when the input arguments cannot be converted to Python @@ -78,6 +79,19 @@ This call creates a Python exception class with the name ``PyExp`` in the given module and automatically converts any encountered exceptions of type ``CppExp`` into Python exceptions of type ``PyExp``. +It is possible to specify base class for the exception using the third +parameter, a `handle`: + +.. code-block:: cpp + + py::register_exception<CppExp>(module, "PyExp", PyExc_RuntimeError); + +Then `PyExp` can be caught both as `PyExp` and `RuntimeError`. + +The class objects of the built-in Python exceptions are listed in the Python +documentation on `Standard Exceptions <https://docs.python.org/3/c-api/exceptions.html#standard-exceptions>`_. +The default base class is `PyExc_Exception`. + When more advanced exception translation is needed, the function ``py::register_exception_translator(translator)`` can be used to register functions that can translate arbitrary exception types (and which may include @@ -100,7 +114,6 @@ and use this in the associated exception translator (note: it is often useful to make this a static declaration when using it inside a lambda expression without requiring capturing). - The following example demonstrates this for a hypothetical exception classes ``MyCustomException`` and ``OtherException``: the first is translated to a custom python exception ``MyCustomError``, while the second is translated to a @@ -134,7 +147,7 @@ section. .. note:: - You must call either ``PyErr_SetString`` or a custom exception's call + Call either ``PyErr_SetString`` or a custom exception's call operator (``exc(string)``) for every exception caught in a custom exception translator. Failure to do so will cause Python to crash with ``SystemError: error return without exception set``. @@ -142,3 +155,144 @@ section. Exceptions that you do not plan to handle should simply not be caught, or may be explicitly (re-)thrown to delegate it to the other, previously-declared existing exception translators. + +.. _handling_python_exceptions_cpp: + +Handling exceptions from Python in C++ +====================================== + +When C++ calls Python functions, such as in a callback function or when +manipulating Python objects, and Python raises an ``Exception``, pybind11 +converts the Python exception into a C++ exception of type +:class:`pybind11::error_already_set` whose payload contains a C++ string textual +summary and the actual Python exception. ``error_already_set`` is used to +propagate Python exception back to Python (or possibly, handle them in C++). + +.. tabularcolumns:: |p{0.5\textwidth}|p{0.45\textwidth}| + ++--------------------------------------+--------------------------------------+ +| Exception raised in Python | Thrown as C++ exception type | ++======================================+======================================+ +| Any Python ``Exception`` | :class:`pybind11::error_already_set` | ++--------------------------------------+--------------------------------------+ + +For example: + +.. code-block:: cpp + + try { + // open("missing.txt", "r") + auto file = py::module_::import("io").attr("open")("missing.txt", "r"); + auto text = file.attr("read")(); + file.attr("close")(); + } catch (py::error_already_set &e) { + if (e.matches(PyExc_FileNotFoundError)) { + py::print("missing.txt not found"); + } else if (e.match(PyExc_PermissionError)) { + py::print("missing.txt found but not accessible"); + } else { + throw; + } + } + +Note that C++ to Python exception translation does not apply here, since that is +a method for translating C++ exceptions to Python, not vice versa. The error raised +from Python is always ``error_already_set``. + +This example illustrates this behavior: + +.. code-block:: cpp + + try { + py::eval("raise ValueError('The Ring')"); + } catch (py::value_error &boromir) { + // Boromir never gets the ring + assert(false); + } catch (py::error_already_set &frodo) { + // Frodo gets the ring + py::print("I will take the ring"); + } + + try { + // py::value_error is a request for pybind11 to raise a Python exception + throw py::value_error("The ball"); + } catch (py::error_already_set &cat) { + // cat won't catch the ball since + // py::value_error is not a Python exception + assert(false); + } catch (py::value_error &dog) { + // dog will catch the ball + py::print("Run Spot run"); + throw; // Throw it again (pybind11 will raise ValueError) + } + +Handling errors from the Python C API +===================================== + +Where possible, use :ref:`pybind11 wrappers <wrappers>` instead of calling +the Python C API directly. When calling the Python C API directly, in +addition to manually managing reference counts, one must follow the pybind11 +error protocol, which is outlined here. + +After calling the Python C API, if Python returns an error, +``throw py::error_already_set();``, which allows pybind11 to deal with the +exception and pass it back to the Python interpreter. This includes calls to +the error setting functions such as ``PyErr_SetString``. + +.. code-block:: cpp + + PyErr_SetString(PyExc_TypeError, "C API type error demo"); + throw py::error_already_set(); + + // But it would be easier to simply... + throw py::type_error("pybind11 wrapper type error"); + +Alternately, to ignore the error, call `PyErr_Clear +<https://docs.python.org/3/c-api/exceptions.html#c.PyErr_Clear>`_. + +Any Python error must be thrown or cleared, or Python/pybind11 will be left in +an invalid state. + +.. _unraisable_exceptions: + +Handling unraisable exceptions +============================== + +If a Python function invoked from a C++ destructor or any function marked +``noexcept(true)`` (collectively, "noexcept functions") throws an exception, there +is no way to propagate the exception, as such functions may not throw. +Should they throw or fail to catch any exceptions in their call graph, +the C++ runtime calls ``std::terminate()`` to abort immediately. + +Similarly, Python exceptions raised in a class's ``__del__`` method do not +propagate, but are logged by Python as an unraisable error. In Python 3.8+, a +`system hook is triggered +<https://docs.python.org/3/library/sys.html#sys.unraisablehook>`_ +and an auditing event is logged. + +Any noexcept function should have a try-catch block that traps +class:`error_already_set` (or any other exception that can occur). Note that +pybind11 wrappers around Python exceptions such as +:class:`pybind11::value_error` are *not* Python exceptions; they are C++ +exceptions that pybind11 catches and converts to Python exceptions. Noexcept +functions cannot propagate these exceptions either. A useful approach is to +convert them to Python exceptions and then ``discard_as_unraisable`` as shown +below. + +.. code-block:: cpp + + void nonthrowing_func() noexcept(true) { + try { + // ... + } catch (py::error_already_set &eas) { + // Discard the Python error using Python APIs, using the C++ magic + // variable __func__. Python already knows the type and value and of the + // exception object. + eas.discard_as_unraisable(__func__); + } catch (const std::exception &e) { + // Log and discard C++ exceptions. + third_party::log(e); + } + } + +.. versionadded:: 2.6 diff --git a/3rdparty/pybind11/docs/advanced/functions.rst b/3rdparty/pybind11/docs/advanced/functions.rst index 3e1a3ff0..ebdff9c9 100644 --- a/3rdparty/pybind11/docs/advanced/functions.rst +++ b/3rdparty/pybind11/docs/advanced/functions.rst @@ -17,7 +17,7 @@ bindings for functions that return a non-trivial type. Just by looking at the type information, it is not clear whether Python should take charge of the returned value and eventually free its resources, or if this is handled on the C++ side. For this reason, pybind11 provides a several *return value policy* -annotations that can be passed to the :func:`module::def` and +annotations that can be passed to the :func:`module_::def` and :func:`class_::def` functions. The default policy is :enum:`return_value_policy::automatic`. @@ -360,7 +360,55 @@ like so: .. code-block:: cpp py::class_<MyClass>("MyClass") - .def("myFunction", py::arg("arg") = (SomeType *) nullptr); + .def("myFunction", py::arg("arg") = static_cast<SomeType *>(nullptr)); + +Keyword-only arguments +====================== + +Python 3 introduced keyword-only arguments by specifying an unnamed ``*`` +argument in a function definition: + +.. code-block:: python + + def f(a, *, b): # a can be positional or via keyword; b must be via keyword + pass + + f(a=1, b=2) # good + f(b=2, a=1) # good + f(1, b=2) # good + f(1, 2) # TypeError: f() takes 1 positional argument but 2 were given + +Pybind11 provides a ``py::kw_only`` object that allows you to implement +the same behaviour by specifying the object between positional and keyword-only +argument annotations when registering the function: + +.. code-block:: cpp + + m.def("f", [](int a, int b) { /* ... */ }, + py::arg("a"), py::kw_only(), py::arg("b")); + +Note that you currently cannot combine this with a ``py::args`` argument. This +feature does *not* require Python 3 to work. + +.. versionadded:: 2.6 + +Positional-only arguments +========================= + +Python 3.8 introduced a new positional-only argument syntax, using ``/`` in the +function definition (note that this has been a convention for CPython +positional arguments, such as in ``pow()``, since Python 2). You can +do the same thing in any version of Python using ``py::pos_only()``: + +.. code-block:: cpp + + m.def("f", [](int a, int b) { /* ... */ }, + py::arg("a"), py::pos_only(), py::arg("b")); + +You now cannot give argument ``a`` by keyword. This can be combined with +keyword-only arguments, as well. + +.. versionadded:: 2.6 .. _nonconverting_arguments: @@ -492,11 +540,13 @@ an explicit ``py::arg().noconvert()`` attribute in the function definition). If the second pass also fails a ``TypeError`` is raised. Within each pass, overloads are tried in the order they were registered with -pybind11. +pybind11. If the ``py::prepend()`` tag is added to the definition, a function +can be placed at the beginning of the overload sequence instead, allowing user +overloads to proceed built in functions. What this means in practice is that pybind11 will prefer any overload that does -not require conversion of arguments to an overload that does, but otherwise prefers -earlier-defined overloads to later-defined ones. +not require conversion of arguments to an overload that does, but otherwise +prefers earlier-defined overloads to later-defined ones. .. note:: @@ -505,3 +555,7 @@ earlier-defined overloads to later-defined ones. requiring one conversion over one requiring three, but only prioritizes overloads requiring no conversion at all to overloads that require conversion of at least one argument. + +.. versionadded:: 2.6 + + The ``py::prepend()`` tag. diff --git a/3rdparty/pybind11/docs/advanced/misc.rst b/3rdparty/pybind11/docs/advanced/misc.rst index 5b38ec75..b3f3b226 100644 --- a/3rdparty/pybind11/docs/advanced/misc.rst +++ b/3rdparty/pybind11/docs/advanced/misc.rst @@ -7,14 +7,14 @@ General notes regarding convenience macros ========================================== pybind11 provides a few convenience macros such as -:func:`PYBIND11_DECLARE_HOLDER_TYPE` and ``PYBIND11_OVERLOAD_*``. Since these +:func:`PYBIND11_DECLARE_HOLDER_TYPE` and ``PYBIND11_OVERRIDE_*``. Since these are "just" macros that are evaluated in the preprocessor (which has no concept of types), they *will* get confused by commas in a template argument; for example, consider: .. code-block:: cpp - PYBIND11_OVERLOAD(MyReturnType<T1, T2>, Class<T3, T4>, func) + PYBIND11_OVERRIDE(MyReturnType<T1, T2>, Class<T3, T4>, func) The limitation of the C preprocessor interprets this as five arguments (with new arguments beginning after each comma) rather than three. To get around this, @@ -26,10 +26,10 @@ using the ``PYBIND11_TYPE`` macro: // Version 1: using a type alias using ReturnType = MyReturnType<T1, T2>; using ClassType = Class<T3, T4>; - PYBIND11_OVERLOAD(ReturnType, ClassType, func); + PYBIND11_OVERRIDE(ReturnType, ClassType, func); // Version 2: using the PYBIND11_TYPE macro: - PYBIND11_OVERLOAD(PYBIND11_TYPE(MyReturnType<T1, T2>), + PYBIND11_OVERRIDE(PYBIND11_TYPE(MyReturnType<T1, T2>), PYBIND11_TYPE(Class<T3, T4>), func) The ``PYBIND11_MAKE_OPAQUE`` macro does *not* require the above workarounds. @@ -59,7 +59,7 @@ could be realized as follows (important changes highlighted): /* Acquire GIL before calling Python code */ py::gil_scoped_acquire acquire; - PYBIND11_OVERLOAD_PURE( + PYBIND11_OVERRIDE_PURE( std::string, /* Return type */ Animal, /* Parent class */ go, /* Name of function */ @@ -132,7 +132,7 @@ However, it can be acquired as follows: .. code-block:: cpp - py::object pet = (py::object) py::module::import("basic").attr("Pet"); + py::object pet = (py::object) py::module_::import("basic").attr("Pet"); py::class_<Dog>(m, "Dog", pet) .def(py::init<const std::string &>()) @@ -146,7 +146,7 @@ has been executed: .. code-block:: cpp - py::module::import("basic"); + py::module_::import("basic"); py::class_<Dog, Pet>(m, "Dog") .def(py::init<const std::string &>()) @@ -176,9 +176,9 @@ pybind11 version. Consider the following example: .. code-block:: cpp - auto data = (MyData *) py::get_shared_data("mydata"); + auto data = reinterpret_cast<MyData *>(py::get_shared_data("mydata")); if (!data) - data = (MyData *) py::set_shared_data("mydata", new MyData(42)); + data = static_cast<MyData *>(py::set_shared_data("mydata", new MyData(42))); If the above snippet was used in several separately compiled extension modules, the first one to be imported would create a ``MyData`` instance and associate @@ -218,12 +218,12 @@ collected: Both approaches also expose a potentially dangerous ``_cleanup`` attribute in Python, which may be undesirable from an API standpoint (a premature explicit -call from Python might lead to undefined behavior). Yet another approach that +call from Python might lead to undefined behavior). Yet another approach that avoids this issue involves weak reference with a cleanup callback: .. code-block:: cpp - // Register a callback function that is invoked when the BaseClass object is colelcted + // Register a callback function that is invoked when the BaseClass object is collected py::cpp_function cleanup_callback( [](py::handle weakref) { // perform cleanup here -- this function is called with the GIL held @@ -237,13 +237,13 @@ avoids this issue involves weak reference with a cleanup callback: .. note:: - PyPy (at least version 5.9) does not garbage collect objects when the - interpreter exits. An alternative approach (which also works on CPython) is to use - the :py:mod:`atexit` module [#f7]_, for example: + PyPy does not garbage collect objects when the interpreter exits. An alternative + approach (which also works on CPython) is to use the :py:mod:`atexit` module [#f7]_, + for example: .. code-block:: cpp - auto atexit = py::module::import("atexit"); + auto atexit = py::module_::import("atexit"); atexit.attr("register")(py::cpp_function([]() { // perform cleanup here -- this function is called with the GIL held })); @@ -283,9 +283,9 @@ work, it is important that all lines are indented consistently, i.e.: ---------- )mydelimiter"); -By default, pybind11 automatically generates and prepends a signature to the docstring of a function -registered with ``module::def()`` and ``class_::def()``. Sometimes this -behavior is not desirable, because you want to provide your own signature or remove +By default, pybind11 automatically generates and prepends a signature to the docstring of a function +registered with ``module_::def()`` and ``class_::def()``. Sometimes this +behavior is not desirable, because you want to provide your own signature or remove the docstring completely to exclude the function from the Sphinx documentation. The class ``options`` allows you to selectively suppress auto-generated signatures: @@ -298,9 +298,40 @@ The class ``options`` allows you to selectively suppress auto-generated signatur m.def("add", [](int a, int b) { return a + b; }, "A function which adds two numbers"); } -Note that changes to the settings affect only function bindings created during the -lifetime of the ``options`` instance. When it goes out of scope at the end of the module's init function, +Note that changes to the settings affect only function bindings created during the +lifetime of the ``options`` instance. When it goes out of scope at the end of the module's init function, the default settings are restored to prevent unwanted side effects. .. [#f4] http://www.sphinx-doc.org .. [#f5] http://github.com/pybind/python_example + +.. _avoiding-cpp-types-in-docstrings: + +Avoiding C++ types in docstrings +================================ + +Docstrings are generated at the time of the declaration, e.g. when ``.def(...)`` is called. +At this point parameter and return types should be known to pybind11. +If a custom type is not exposed yet through a ``py::class_`` constructor or a custom type caster, +its C++ type name will be used instead to generate the signature in the docstring: + +.. code-block:: text + + | __init__(...) + | __init__(self: example.Foo, arg0: ns::Bar) -> None + ^^^^^^^ + + +This limitation can be circumvented by ensuring that C++ classes are registered with pybind11 +before they are used as a parameter or return type of a function: + +.. code-block:: cpp + + PYBIND11_MODULE(example, m) { + + auto pyFoo = py::class_<ns::Foo>(m, "Foo"); + auto pyBar = py::class_<ns::Bar>(m, "Bar"); + + pyFoo.def(py::init<const ns::Bar&>()); + pyBar.def(py::init<const ns::Foo&>()); + } diff --git a/3rdparty/pybind11/docs/advanced/pycpp/numpy.rst b/3rdparty/pybind11/docs/advanced/pycpp/numpy.rst index 458f99e9..19ed10b3 100644 --- a/3rdparty/pybind11/docs/advanced/pycpp/numpy.rst +++ b/3rdparty/pybind11/docs/advanced/pycpp/numpy.rst @@ -57,17 +57,17 @@ specification. struct buffer_info { void *ptr; - ssize_t itemsize; + py::ssize_t itemsize; std::string format; - ssize_t ndim; - std::vector<ssize_t> shape; - std::vector<ssize_t> strides; + py::ssize_t ndim; + std::vector<py::ssize_t> shape; + std::vector<py::ssize_t> strides; }; To create a C++ function that can take a Python buffer object as an argument, simply use the type ``py::buffer`` as one of its arguments. Buffers can exist in a great variety of configurations, hence some safety checks are usually -necessary in the function body. Below, you can see an basic example on how to +necessary in the function body. Below, you can see a basic example on how to define a custom constructor for the Eigen double precision matrix (``Eigen::MatrixXd``) type, which supports initialization from compatible buffer objects (e.g. a NumPy matrix). @@ -81,7 +81,7 @@ buffer objects (e.g. a NumPy matrix). constexpr bool rowMajor = Matrix::Flags & Eigen::RowMajorBit; py::class_<Matrix>(m, "Matrix", py::buffer_protocol()) - .def("__init__", [](Matrix &m, py::buffer b) { + .def(py::init([](py::buffer b) { typedef Eigen::Stride<Eigen::Dynamic, Eigen::Dynamic> Strides; /* Request a buffer descriptor from Python */ @@ -101,8 +101,8 @@ buffer objects (e.g. a NumPy matrix). auto map = Eigen::Map<Matrix, 0, Strides>( static_cast<Scalar *>(info.ptr), info.shape[0], info.shape[1], strides); - new (&m) Matrix(map); - }); + return Matrix(map); + })); For reference, the ``def_buffer()`` call for this Eigen data type should look as follows: @@ -274,9 +274,9 @@ simply using ``vectorize``). py::buffer_info buf3 = result.request(); - double *ptr1 = (double *) buf1.ptr, - *ptr2 = (double *) buf2.ptr, - *ptr3 = (double *) buf3.ptr; + double *ptr1 = static_cast<double *>(buf1.ptr); + double *ptr2 = static_cast<double *>(buf2.ptr); + double *ptr3 = static_cast<double *>(buf3.ptr); for (size_t idx = 0; idx < buf1.shape[0]; idx++) ptr3[idx] = ptr1[idx] + ptr2[idx]; @@ -309,17 +309,17 @@ where ``N`` gives the required dimensionality of the array: m.def("sum_3d", [](py::array_t<double> x) { auto r = x.unchecked<3>(); // x must have ndim = 3; can be non-writeable double sum = 0; - for (ssize_t i = 0; i < r.shape(0); i++) - for (ssize_t j = 0; j < r.shape(1); j++) - for (ssize_t k = 0; k < r.shape(2); k++) + for (py::ssize_t i = 0; i < r.shape(0); i++) + for (py::ssize_t j = 0; j < r.shape(1); j++) + for (py::ssize_t k = 0; k < r.shape(2); k++) sum += r(i, j, k); return sum; }); m.def("increment_3d", [](py::array_t<double> x) { auto r = x.mutable_unchecked<3>(); // Will throw if ndim != 3 or flags.writeable is false - for (ssize_t i = 0; i < r.shape(0); i++) - for (ssize_t j = 0; j < r.shape(1); j++) - for (ssize_t k = 0; k < r.shape(2); k++) + for (py::ssize_t i = 0; i < r.shape(0); i++) + for (py::ssize_t j = 0; j < r.shape(1); j++) + for (py::ssize_t k = 0; k < r.shape(2); k++) r(i, j, k) += 1.0; }, py::arg().noconvert()); @@ -371,6 +371,8 @@ Ellipsis Python 3 provides a convenient ``...`` ellipsis notation that is often used to slice multidimensional arrays. For instance, the following snippet extracts the middle dimensions of a tensor with the first and last index set to zero. +In Python 2, the syntactic sugar ``...`` is not available, but the singleton +``Ellipsis`` (of type ``ellipsis``) can still be used directly. .. code-block:: python @@ -384,3 +386,51 @@ operation on the C++ side: py::array a = /* A NumPy array */; py::array b = a[py::make_tuple(0, py::ellipsis(), 0)]; + +.. versionchanged:: 2.6 + ``py::ellipsis()`` is now also avaliable in Python 2. + +Memory view +=========== + +For a case when we simply want to provide a direct accessor to C/C++ buffer +without a concrete class object, we can return a ``memoryview`` object. Suppose +we wish to expose a ``memoryview`` for 2x4 uint8_t array, we can do the +following: + +.. code-block:: cpp + + const uint8_t buffer[] = { + 0, 1, 2, 3, + 4, 5, 6, 7 + }; + m.def("get_memoryview2d", []() { + return py::memoryview::from_buffer( + buffer, // buffer pointer + { 2, 4 }, // shape (rows, cols) + { sizeof(uint8_t) * 4, sizeof(uint8_t) } // strides in bytes + ); + }) + +This approach is meant for providing a ``memoryview`` for a C/C++ buffer not +managed by Python. The user is responsible for managing the lifetime of the +buffer. Using a ``memoryview`` created in this way after deleting the buffer in +C++ side results in undefined behavior. + +We can also use ``memoryview::from_memory`` for a simple 1D contiguous buffer: + +.. code-block:: cpp + + m.def("get_memoryview1d", []() { + return py::memoryview::from_memory( + buffer, // buffer pointer + sizeof(uint8_t) * 8 // buffer size + ); + }) + +.. note:: + + ``memoryview::from_memory`` is not available in Python 2. + +.. versionchanged:: 2.6 + ``memoryview::from_memory`` added. diff --git a/3rdparty/pybind11/docs/advanced/pycpp/object.rst b/3rdparty/pybind11/docs/advanced/pycpp/object.rst index 117131ed..6c7525ce 100644 --- a/3rdparty/pybind11/docs/advanced/pycpp/object.rst +++ b/3rdparty/pybind11/docs/advanced/pycpp/object.rst @@ -1,6 +1,8 @@ Python types ############ +.. _wrappers: + Available wrappers ================== @@ -13,6 +15,13 @@ Available types include :class:`handle`, :class:`object`, :class:`bool_`, :class:`iterable`, :class:`iterator`, :class:`function`, :class:`buffer`, :class:`array`, and :class:`array_t`. +.. warning:: + + Be sure to review the :ref:`pytypes_gotchas` before using this heavily in + your C++ API. + +.. _casting_back_and_forth: + Casting back and forth ====================== @@ -47,20 +56,21 @@ This example obtains a reference to the Python ``Decimal`` class. .. code-block:: cpp // Equivalent to "from decimal import Decimal" - py::object Decimal = py::module::import("decimal").attr("Decimal"); + py::object Decimal = py::module_::import("decimal").attr("Decimal"); .. code-block:: cpp // Try to import scipy - py::object scipy = py::module::import("scipy"); + py::object scipy = py::module_::import("scipy"); return scipy.attr("__version__"); + .. _calling_python_functions: Calling Python functions ======================== -It is also possible to call Python classes, functions and methods +It is also possible to call Python classes, functions and methods via ``operator()``. .. code-block:: cpp @@ -71,11 +81,11 @@ via ``operator()``. .. code-block:: cpp // Use Python to make our directories - py::object os = py::module::import("os"); + py::object os = py::module_::import("os"); py::object makedirs = os.attr("makedirs"); makedirs("/tmp/path/to/somewhere"); -One can convert the result obtained from Python to a pure C++ version +One can convert the result obtained from Python to a pure C++ version if a ``py::class_`` or type conversion is defined. .. code-block:: cpp @@ -99,8 +109,8 @@ Python method. py::print(py::str(exp_pi)); In the example above ``pi.attr("exp")`` is a *bound method*: it will always call -the method for that same instance of the class. Alternately one can create an -*unbound method* via the Python class (instead of instance) and pass the ``self`` +the method for that same instance of the class. Alternately one can create an +*unbound method* via the Python class (instead of instance) and pass the ``self`` object explicitly, followed by other arguments. .. code-block:: cpp @@ -168,3 +178,74 @@ Generalized unpacking according to PEP448_ is also supported: Python functions from C++, including keywords arguments and unpacking. .. _PEP448: https://www.python.org/dev/peps/pep-0448/ + +.. _implicit_casting: + +Implicit casting +================ + +When using the C++ interface for Python types, or calling Python functions, +objects of type :class:`object` are returned. It is possible to invoke implicit +conversions to subclasses like :class:`dict`. The same holds for the proxy objects +returned by ``operator[]`` or ``obj.attr()``. +Casting to subtypes improves code readability and allows values to be passed to +C++ functions that require a specific subtype rather than a generic :class:`object`. + +.. code-block:: cpp + + #include <pybind11/numpy.h> + using namespace pybind11::literals; + + py::module_ os = py::module_::import("os"); + py::module_ path = py::module_::import("os.path"); // like 'import os.path as path' + py::module_ np = py::module_::import("numpy"); // like 'import numpy as np' + + py::str curdir_abs = path.attr("abspath")(path.attr("curdir")); + py::print(py::str("Current directory: ") + curdir_abs); + py::dict environ = os.attr("environ"); + py::print(environ["HOME"]); + py::array_t<float> arr = np.attr("ones")(3, "dtype"_a="float32"); + py::print(py::repr(arr + py::int_(1))); + +These implicit conversions are available for subclasses of :class:`object`; there +is no need to call ``obj.cast()`` explicitly as for custom classes, see +:ref:`casting_back_and_forth`. + +.. note:: + If a trivial conversion via move constructor is not possible, both implicit and + explicit casting (calling ``obj.cast()``) will attempt a "rich" conversion. + For instance, ``py::list env = os.attr("environ");`` will succeed and is + equivalent to the Python code ``env = list(os.environ)`` that produces a + list of the dict keys. + +.. TODO: Adapt text once PR #2349 has landed + +Handling exceptions +=================== + +Python exceptions from wrapper classes will be thrown as a ``py::error_already_set``. +See :ref:`Handling exceptions from Python in C++ +<handling_python_exceptions_cpp>` for more information on handling exceptions +raised when calling C++ wrapper classes. + +.. _pytypes_gotchas: + +Gotchas +======= + +Default-Constructed Wrappers +---------------------------- + +When a wrapper type is default-constructed, it is **not** a valid Python object (i.e. it is not ``py::none()``). It is simply the same as +``PyObject*`` null pointer. To check for this, use +``static_cast<bool>(my_wrapper)``. + +Assigning py::none() to wrappers +-------------------------------- + +You may be tempted to use types like ``py::str`` and ``py::dict`` in C++ +signatures (either pure C++, or in bound signatures), and assign them default +values of ``py::none()``. However, in a best case scenario, it will fail fast +because ``None`` is not convertible to that type (e.g. ``py::dict``), or in a +worse case scenario, it will silently work but corrupt the types you want to +work with (e.g. ``py::str(py::none())`` will yield ``"None"`` in Python). diff --git a/3rdparty/pybind11/docs/advanced/pycpp/utilities.rst b/3rdparty/pybind11/docs/advanced/pycpp/utilities.rst index 369e7c94..c15051fb 100644 --- a/3rdparty/pybind11/docs/advanced/pycpp/utilities.rst +++ b/3rdparty/pybind11/docs/advanced/pycpp/utilities.rst @@ -42,7 +42,7 @@ redirects output to the corresponding Python streams: m.def("noisy_func", []() { py::scoped_ostream_redirect stream( std::cout, // std::ostream& - py::module::import("sys").attr("stdout") // Python output + py::module_::import("sys").attr("stdout") // Python output ); call_noisy_func(); }); @@ -104,7 +104,7 @@ can be used. ... // Evaluate in scope of main module - py::object scope = py::module::import("__main__").attr("__dict__"); + py::object scope = py::module_::import("__main__").attr("__dict__"); // Evaluate an isolated expression int result = py::eval("my_variable + 10", scope).cast<int>(); diff --git a/3rdparty/pybind11/docs/basics.rst b/3rdparty/pybind11/docs/basics.rst index 7bf4d426..b9d386c3 100644 --- a/3rdparty/pybind11/docs/basics.rst +++ b/3rdparty/pybind11/docs/basics.rst @@ -11,11 +11,11 @@ included set of test cases. Compiling the test cases ======================== -Linux/MacOS +Linux/macOS ----------- On Linux you'll need to install the **python-dev** or **python3-dev** packages as -well as **cmake**. On Mac OS, the included python version works out of the box, +well as **cmake**. On macOS, the included python version works out of the box, but **cmake** must still be installed. After installing the prerequisites, run @@ -35,6 +35,14 @@ Windows On Windows, only **Visual Studio 2015** and newer are supported since pybind11 relies on various C++11 language features that break older versions of Visual Studio. +.. Note:: + + To use the C++17 in Visual Studio 2017 (MSVC 14.1), pybind11 requires the flag + ``/permissive-`` to be passed to the compiler `to enforce standard conformance`_. When + building with Visual Studio 2019, this is not strictly necessary, but still advised. + +.. _`to enforce standard conformance`: https://docs.microsoft.com/en-us/cpp/build/reference/permissive-standards-conformance?view=vs-2017 + To compile and run the tests: .. code-block:: batch @@ -110,8 +118,8 @@ a file named :file:`example.cpp` with the following contents: The :func:`PYBIND11_MODULE` macro creates a function that will be called when an ``import`` statement is issued from within Python. The module name (``example``) is given as the first macro argument (it should not be in quotes). The second -argument (``m``) defines a variable of type :class:`py::module <module>` which -is the main interface for creating bindings. The method :func:`module::def` +argument (``m``) defines a variable of type :class:`py::module_ <module>` which +is the main interface for creating bindings. The method :func:`module_::def` generates binding code that exposes the ``add()`` function to Python. .. note:: @@ -130,7 +138,7 @@ On Linux, the above example can be compiled using the following command: $ c++ -O3 -Wall -shared -std=c++11 -fPIC `python3 -m pybind11 --includes` example.cpp -o example`python3-config --extension-suffix` -For more details on the required compiler flags on Linux and MacOS, see +For more details on the required compiler flags on Linux and macOS, see :ref:`building_manually`. For complete cross-platform compilation instructions, refer to the :ref:`compiling` page. @@ -173,7 +181,7 @@ names of the arguments ("i" and "j" in this case). py::arg("i"), py::arg("j")); :class:`arg` is one of several special tag classes which can be used to pass -metadata into :func:`module::def`. With this modified binding code, we can now +metadata into :func:`module_::def`. With this modified binding code, we can now call the function using keyword arguments, which is a more readable alternative particularly for functions taking many parameters: diff --git a/3rdparty/pybind11/docs/benchmark.py b/3rdparty/pybind11/docs/benchmark.py index 6dc0604e..33d78fb4 100644 --- a/3rdparty/pybind11/docs/benchmark.py +++ b/3rdparty/pybind11/docs/benchmark.py @@ -1,3 +1,4 @@ +# -*- coding: utf-8 -*- import random import os import time @@ -13,7 +14,7 @@ def generate_dummy_code_pybind11(nclasses=10): for cl in range(nclasses): decl += "class cl%03i;\n" % cl - decl += '\n' + decl += "\n" for cl in range(nclasses): decl += "class cl%03i {\n" % cl @@ -21,18 +22,17 @@ def generate_dummy_code_pybind11(nclasses=10): bindings += ' py::class_<cl%03i>(m, "cl%03i")\n' % (cl, cl) for fn in range(nfns): ret = random.randint(0, nclasses - 1) - params = [random.randint(0, nclasses - 1) for i in range(nargs)] + params = [random.randint(0, nclasses - 1) for i in range(nargs)] decl += " cl%03i *fn_%03i(" % (ret, fn) decl += ", ".join("cl%03i *" % p for p in params) decl += ");\n" - bindings += ' .def("fn_%03i", &cl%03i::fn_%03i)\n' % \ - (fn, cl, fn) + bindings += ' .def("fn_%03i", &cl%03i::fn_%03i)\n' % (fn, cl, fn) decl += "};\n\n" - bindings += ' ;\n' + bindings += " ;\n" result = "#include <pybind11/pybind11.h>\n\n" result += "namespace py = pybind11;\n\n" - result += decl + '\n' + result += decl + "\n" result += "PYBIND11_MODULE(example, m) {\n" result += bindings result += "}" @@ -45,7 +45,7 @@ def generate_dummy_code_boost(nclasses=10): for cl in range(nclasses): decl += "class cl%03i;\n" % cl - decl += '\n' + decl += "\n" for cl in range(nclasses): decl += "class cl%03i {\n" % cl @@ -53,18 +53,20 @@ def generate_dummy_code_boost(nclasses=10): bindings += ' py::class_<cl%03i>("cl%03i")\n' % (cl, cl) for fn in range(nfns): ret = random.randint(0, nclasses - 1) - params = [random.randint(0, nclasses - 1) for i in range(nargs)] + params = [random.randint(0, nclasses - 1) for i in range(nargs)] decl += " cl%03i *fn_%03i(" % (ret, fn) decl += ", ".join("cl%03i *" % p for p in params) decl += ");\n" - bindings += ' .def("fn_%03i", &cl%03i::fn_%03i, py::return_value_policy<py::manage_new_object>())\n' % \ - (fn, cl, fn) + bindings += ( + ' .def("fn_%03i", &cl%03i::fn_%03i, py::return_value_policy<py::manage_new_object>())\n' + % (fn, cl, fn) + ) decl += "};\n\n" - bindings += ' ;\n' + bindings += " ;\n" result = "#include <boost/python.hpp>\n\n" result += "namespace py = boost::python;\n\n" - result += decl + '\n' + result += decl + "\n" result += "BOOST_PYTHON_MODULE(example) {\n" result += bindings result += "}" @@ -72,17 +74,19 @@ def generate_dummy_code_boost(nclasses=10): for codegen in [generate_dummy_code_pybind11, generate_dummy_code_boost]: - print ("{") + print("{") for i in range(0, 10): nclasses = 2 ** i with open("test.cpp", "w") as f: f.write(codegen(nclasses)) n1 = dt.datetime.now() - os.system("g++ -Os -shared -rdynamic -undefined dynamic_lookup " + os.system( + "g++ -Os -shared -rdynamic -undefined dynamic_lookup " "-fvisibility=hidden -std=c++14 test.cpp -I include " - "-I /System/Library/Frameworks/Python.framework/Headers -o test.so") + "-I /System/Library/Frameworks/Python.framework/Headers -o test.so" + ) n2 = dt.datetime.now() elapsed = (n2 - n1).total_seconds() - size = os.stat('test.so').st_size + size = os.stat("test.so").st_size print(" {%i, %f, %i}," % (nclasses * nfns, elapsed, size)) - print ("}") + print("}") diff --git a/3rdparty/pybind11/docs/benchmark.rst b/3rdparty/pybind11/docs/benchmark.rst index 59d533df..02c2ccde 100644 --- a/3rdparty/pybind11/docs/benchmark.rst +++ b/3rdparty/pybind11/docs/benchmark.rst @@ -93,5 +93,3 @@ favor. .. only:: latex .. image:: pybind11_vs_boost_python2.png - - diff --git a/3rdparty/pybind11/docs/changelog.rst b/3rdparty/pybind11/docs/changelog.rst index 2def2b07..561baa5f 100644 --- a/3rdparty/pybind11/docs/changelog.rst +++ b/3rdparty/pybind11/docs/changelog.rst @@ -6,6 +6,278 @@ Changelog Starting with version 1.8.0, pybind11 releases use a `semantic versioning <http://semver.org>`_ policy. +v2.6.1 (Nov 11, 2020) +--------------------- + +* ``py::exec``, ``py::eval``, and ``py::eval_file`` now add the builtins module + as ``"__builtins__"`` to their ``globals`` argument, better matching ``exec`` + and ``eval`` in pure Python. + `#2616 <https://github.com/pybind/pybind11/pull/2616>`_ + +* ``setup_helpers`` will no longer set a minimum macOS version lower than the + current version. + `#2622 <https://github.com/pybind/pybind11/pull/2622>`_ + +* Allow deleting static properties. + `#2629 <https://github.com/pybind/pybind11/pull/2629>`_ + +* Seal a leak in ``def_buffer``, cleaning up the ``capture`` object after the + ``class_`` object goes out of scope. + `#2634 <https://github.com/pybind/pybind11/pull/2634>`_ + +* ``pybind11_INCLUDE_DIRS`` was incorrect, potentially causing a regression if + it was expected to include ``PYTHON_INCLUDE_DIRS`` (please use targets + instead). + `#2636 <https://github.com/pybind/pybind11/pull/2636>`_ + +* Added parameter names to the ``py::enum_`` constructor and methods, avoiding + ``arg0`` in the generated docstrings. + `#2637 <https://github.com/pybind/pybind11/pull/2637>`_ + +* Added ``needs_recompile`` optional function to the ``ParallelCompiler`` + helper, to allow a recompile to be skipped based on a user-defined function. + `#2643 <https://github.com/pybind/pybind11/pull/2643>`_ + + +v2.6.0 (Oct 21, 2020) +--------------------- + +See :ref:`upgrade-guide-2.6` for help upgrading to the new version. + +New features: + +* Keyword-only arguments supported in Python 2 or 3 with ``py::kw_only()``. + `#2100 <https://github.com/pybind/pybind11/pull/2100>`_ + +* Positional-only arguments supported in Python 2 or 3 with ``py::pos_only()``. + `#2459 <https://github.com/pybind/pybind11/pull/2459>`_ + +* ``py::is_final()`` class modifier to block subclassing (CPython only). + `#2151 <https://github.com/pybind/pybind11/pull/2151>`_ + +* Added ``py::prepend()``, allowing a function to be placed at the beginning of + the overload chain. + `#1131 <https://github.com/pybind/pybind11/pull/1131>`_ + +* Access to the type object now provided with ``py::type::of<T>()`` and + ``py::type::of(h)``. + `#2364 <https://github.com/pybind/pybind11/pull/2364>`_ + +* Perfect forwarding support for methods. + `#2048 <https://github.com/pybind/pybind11/pull/2048>`_ + +* Added ``py::error_already_set::discard_as_unraisable()``. + `#2372 <https://github.com/pybind/pybind11/pull/2372>`_ + +* ``py::hash`` is now public. + `#2217 <https://github.com/pybind/pybind11/pull/2217>`_ + +* ``py::class_<union_type>`` is now supported. Note that writing to one data + member of the union and reading another (type punning) is UB in C++. Thus + pybind11-bound enums should never be used for such conversions. + `#2320 <https://github.com/pybind/pybind11/pull/2320>`_. + +* Classes now check local scope when registering members, allowing a subclass + to have a member with the same name as a parent (such as an enum). + `#2335 <https://github.com/pybind/pybind11/pull/2335>`_ + +Code correctness features: + +* Error now thrown when ``__init__`` is forgotten on subclasses. + `#2152 <https://github.com/pybind/pybind11/pull/2152>`_ + +* Throw error if conversion to a pybind11 type if the Python object isn't a + valid instance of that type, such as ``py::bytes(o)`` when ``py::object o`` + isn't a bytes instance. + `#2349 <https://github.com/pybind/pybind11/pull/2349>`_ + +* Throw if conversion to ``str`` fails. + `#2477 <https://github.com/pybind/pybind11/pull/2477>`_ + + +API changes: + +* ``py::module`` was renamed ``py::module_`` to avoid issues with C++20 when + used unqualified, but an alias ``py::module`` is provided for backward + compatibility. + `#2489 <https://github.com/pybind/pybind11/pull/2489>`_ + +* Public constructors for ``py::module_`` have been deprecated; please use + ``pybind11::module_::create_extension_module`` if you were using the public + constructor (fairly rare after ``PYBIND11_MODULE`` was introduced). + `#2552 <https://github.com/pybind/pybind11/pull/2552>`_ + +* ``PYBIND11_OVERLOAD*`` macros and ``get_overload`` function replaced by + correctly-named ``PYBIND11_OVERRIDE*`` and ``get_override``, fixing + inconsistencies in the presence of a closing ``;`` in these macros. + ``get_type_overload`` is deprecated. + `#2325 <https://github.com/pybind/pybind11/pull/2325>`_ + +Packaging / building improvements: + +* The Python package was reworked to be more powerful and useful. + `#2433 <https://github.com/pybind/pybind11/pull/2433>`_ + + * :ref:`build-setuptools` is easier thanks to a new + ``pybind11.setup_helpers`` module, which provides utilities to use + setuptools with pybind11. It can be used via PEP 518, ``setup_requires``, + or by directly importing or copying ``setup_helpers.py`` into your project. + + * CMake configuration files are now included in the Python package. Use + ``pybind11.get_cmake_dir()`` or ``python -m pybind11 --cmakedir`` to get + the directory with the CMake configuration files, or include the + site-packages location in your ``CMAKE_MODULE_PATH``. Or you can use the + new ``pybind11[global]`` extra when you install ``pybind11``, which + installs the CMake files and headers into your base environment in the + standard location. + + * ``pybind11-config`` is another way to write ``python -m pybind11`` if you + have your PATH set up. + + * Added external typing support to the helper module, code from + ``import pybind11`` can now be type checked. + `#2588 <https://github.com/pybind/pybind11/pull/2588>`_ + +* Minimum CMake required increased to 3.4. + `#2338 <https://github.com/pybind/pybind11/pull/2338>`_ and + `#2370 <https://github.com/pybind/pybind11/pull/2370>`_ + + * Full integration with CMake’s C++ standard system and compile features + replaces ``PYBIND11_CPP_STANDARD``. + + * Generated config file is now portable to different Python/compiler/CMake + versions. + + * Virtual environments prioritized if ``PYTHON_EXECUTABLE`` is not set + (``venv``, ``virtualenv``, and ``conda``) (similar to the new FindPython + mode). + + * Other CMake features now natively supported, like + ``CMAKE_INTERPROCEDURAL_OPTIMIZATION``, ``set(CMAKE_CXX_VISIBILITY_PRESET + hidden)``. + + * ``CUDA`` as a language is now supported. + + * Helper functions ``pybind11_strip``, ``pybind11_extension``, + ``pybind11_find_import`` added, see :doc:`cmake/index`. + + * Optional :ref:`find-python-mode` and :ref:`nopython-mode` with CMake. + `#2370 <https://github.com/pybind/pybind11/pull/2370>`_ + +* Uninstall target added. + `#2265 <https://github.com/pybind/pybind11/pull/2265>`_ and + `#2346 <https://github.com/pybind/pybind11/pull/2346>`_ + +* ``pybind11_add_module()`` now accepts an optional ``OPT_SIZE`` flag that + switches the binding target to size-based optimization if the global build + type can not always be fixed to ``MinSizeRel`` (except in debug mode, where + optimizations remain disabled). ``MinSizeRel`` or this flag reduces binary + size quite substantially (~25% on some platforms). + `#2463 <https://github.com/pybind/pybind11/pull/2463>`_ + +Smaller or developer focused features and fixes: + +* Moved ``mkdoc.py`` to a new repo, `pybind11-mkdoc`_. There are no longer + submodules in the main repo. + +* ``py::memoryview`` segfault fix and update, with new + ``py::memoryview::from_memory`` in Python 3, and documentation. + `#2223 <https://github.com/pybind/pybind11/pull/2223>`_ + +* Fix for ``buffer_info`` on Python 2. + `#2503 <https://github.com/pybind/pybind11/pull/2503>`_ + +* If ``__eq__`` defined but not ``__hash__``, ``__hash__`` is now set to + ``None``. + `#2291 <https://github.com/pybind/pybind11/pull/2291>`_ + +* ``py::ellipsis`` now also works on Python 2. + `#2360 <https://github.com/pybind/pybind11/pull/2360>`_ + +* Pointer to ``std::tuple`` & ``std::pair`` supported in cast. + `#2334 <https://github.com/pybind/pybind11/pull/2334>`_ + +* Small fixes in NumPy support. ``py::array`` now uses ``py::ssize_t`` as first + argument type. + `#2293 <https://github.com/pybind/pybind11/pull/2293>`_ + +* Added missing signature for ``py::array``. + `#2363 <https://github.com/pybind/pybind11/pull/2363>`_ + +* ``unchecked_mutable_reference`` has access to operator ``()`` and ``[]`` when + const. + `#2514 <https://github.com/pybind/pybind11/pull/2514>`_ + +* ``py::vectorize`` is now supported on functions that return void. + `#1969 <https://github.com/pybind/pybind11/pull/1969>`_ + +* ``py::capsule`` supports ``get_pointer`` and ``set_pointer``. + `#1131 <https://github.com/pybind/pybind11/pull/1131>`_ + +* Fix crash when different instances share the same pointer of the same type. + `#2252 <https://github.com/pybind/pybind11/pull/2252>`_ + +* Fix for ``py::len`` not clearing Python's error state when it fails and throws. + `#2575 <https://github.com/pybind/pybind11/pull/2575>`_ + +* Bugfixes related to more extensive testing, new GitHub Actions CI. + `#2321 <https://github.com/pybind/pybind11/pull/2321>`_ + +* Bug in timezone issue in Eastern hemisphere midnight fixed. + `#2438 <https://github.com/pybind/pybind11/pull/2438>`_ + +* ``std::chrono::time_point`` now works when the resolution is not the same as + the system. + `#2481 <https://github.com/pybind/pybind11/pull/2481>`_ + +* Bug fixed where ``py::array_t`` could accept arrays that did not match the + requested ordering. + `#2484 <https://github.com/pybind/pybind11/pull/2484>`_ + +* Avoid a segfault on some compilers when types are removed in Python. + `#2564 <https://github.com/pybind/pybind11/pull/2564>`_ + +* ``py::arg::none()`` is now also respected when passing keyword arguments. + `#2611 <https://github.com/pybind/pybind11/pull/2611>`_ + +* PyPy fixes, PyPy 7.3.x now supported, including PyPy3. (Known issue with + PyPy2 and Windows `#2596 <https://github.com/pybind/pybind11/issues/2596>`_). + `#2146 <https://github.com/pybind/pybind11/pull/2146>`_ + +* CPython 3.9.0 workaround for undefined behavior (macOS segfault). + `#2576 <https://github.com/pybind/pybind11/pull/2576>`_ + +* CPython 3.9 warning fixes. + `#2253 <https://github.com/pybind/pybind11/pull/2253>`_ + +* Improved C++20 support, now tested in CI. + `#2489 <https://github.com/pybind/pybind11/pull/2489>`_ + `#2599 <https://github.com/pybind/pybind11/pull/2599>`_ + +* Improved but still incomplete debug Python interpreter support. + `#2025 <https://github.com/pybind/pybind11/pull/2025>`_ + +* NVCC (CUDA 11) now supported and tested in CI. + `#2461 <https://github.com/pybind/pybind11/pull/2461>`_ + +* NVIDIA PGI compilers now supported and tested in CI. + `#2475 <https://github.com/pybind/pybind11/pull/2475>`_ + +* At least Intel 18 now explicitly required when compiling with Intel. + `#2577 <https://github.com/pybind/pybind11/pull/2577>`_ + +* Extensive style checking in CI, with `pre-commit`_ support. Code + modernization, checked by clang-tidy. + +* Expanded docs, including new main page, new installing section, and CMake + helpers page, along with over a dozen new sections on existing pages. + +* In GitHub, new docs for contributing and new issue templates. + +.. _pre-commit: https://pre-commit.com + +.. _pybind11-mkdoc: https://github.com/pybind/pybind11-mkdoc + v2.5.0 (Mar 31, 2020) ----------------------------------------------------- @@ -361,7 +633,7 @@ v2.2.2 (February 7, 2018) v2.2.1 (September 14, 2017) ----------------------------------------------------- -* Added ``py::module::reload()`` member function for reloading a module. +* Added ``py::module_::reload()`` member function for reloading a module. `#1040 <https://github.com/pybind/pybind11/pull/1040>`_. * Fixed a reference leak in the number converter. @@ -536,7 +808,7 @@ v2.2.0 (August 31, 2017) in reference cycles. `#856 <https://github.com/pybind/pybind11/pull/856>`_. -* Numpy and buffer protocol related improvements: +* NumPy and buffer protocol related improvements: 1. Support for negative strides in Python buffer objects/numpy arrays. This required changing integers from unsigned to signed for the related C++ APIs. @@ -1267,7 +1539,7 @@ Happy Christmas! * Improved support for ``std::shared_ptr<>`` conversions * Initial support for ``std::set<>`` conversions * Fixed type resolution issue for types defined in a separate plugin module -* Cmake build system improvements +* CMake build system improvements * Factored out generic functionality to non-templated code (smaller code size) * Added a code size / compile time benchmark vs Boost.Python * Added an appveyor CI script diff --git a/3rdparty/pybind11/docs/classes.rst b/3rdparty/pybind11/docs/classes.rst index a63f6a19..f3610ef3 100644 --- a/3rdparty/pybind11/docs/classes.rst +++ b/3rdparty/pybind11/docs/classes.rst @@ -74,7 +74,7 @@ Note how ``print(p)`` produced a rather useless summary of our data structure in >>> print(p) <example.Pet object at 0x10cd98060> -To address this, we could bind an utility function that returns a human-readable +To address this, we could bind a utility function that returns a human-readable summary to the special method slot named ``__repr__``. Unfortunately, there is no suitable functionality in the ``Pet`` data structure, and it would be nice if we did not have to change it. This can easily be accomplished by binding a @@ -373,8 +373,8 @@ sequence. py::class_<Pet>(m, "Pet") .def(py::init<const std::string &, int>()) - .def("set", (void (Pet::*)(int)) &Pet::set, "Set the pet's age") - .def("set", (void (Pet::*)(const std::string &)) &Pet::set, "Set the pet's name"); + .def("set", static_cast<void (Pet::*)(int)>(&Pet::set), "Set the pet's age") + .def("set", static_cast<void (Pet::*)(const std::string &)>(&Pet::set), "Set the pet's name"); The overload signatures are also visible in the method's docstring: diff --git a/3rdparty/pybind11/docs/cmake/index.rst b/3rdparty/pybind11/docs/cmake/index.rst new file mode 100644 index 00000000..eaf66d70 --- /dev/null +++ b/3rdparty/pybind11/docs/cmake/index.rst @@ -0,0 +1,8 @@ +CMake helpers +------------- + +Pybind11 can be used with ``add_subdirectory(extern/pybind11)``, or from an +install with ``find_package(pybind11 CONFIG)``. The interface provided in +either case is functionally identical. + +.. cmake-module:: ../../tools/pybind11Config.cmake.in diff --git a/3rdparty/pybind11/docs/compiling.rst b/3rdparty/pybind11/docs/compiling.rst index c50c7d8a..f26e6cf6 100644 --- a/3rdparty/pybind11/docs/compiling.rst +++ b/3rdparty/pybind11/docs/compiling.rst @@ -3,6 +3,8 @@ Build systems ############# +.. _build-setuptools: + Building with setuptools ======================== @@ -13,6 +15,203 @@ the [python_example]_ repository. .. [python_example] https://github.com/pybind/python_example +A helper file is provided with pybind11 that can simplify usage with setuptools. + +To use pybind11 inside your ``setup.py``, you have to have some system to +ensure that ``pybind11`` is installed when you build your package. There are +four possible ways to do this, and pybind11 supports all four: You can ask all +users to install pybind11 beforehand (bad), you can use +:ref:`setup_helpers-pep518` (good, but very new and requires Pip 10), +:ref:`setup_helpers-setup_requires` (discouraged by Python packagers now that +PEP 518 is available, but it still works everywhere), or you can +:ref:`setup_helpers-copy-manually` (always works but you have to manually sync +your copy to get updates). + +An example of a ``setup.py`` using pybind11's helpers: + +.. code-block:: python + + from glob import glob + from setuptools import setup + from pybind11.setup_helpers import Pybind11Extension + + ext_modules = [ + Pybind11Extension( + "python_example", + sorted(glob("src/*.cpp")), # Sort source files for reproducibility + ), + ] + + setup( + ..., + ext_modules=ext_modules + ) + +If you want to do an automatic search for the highest supported C++ standard, +that is supported via a ``build_ext`` command override; it will only affect +``Pybind11Extensions``: + +.. code-block:: python + + from glob import glob + from setuptools import setup + from pybind11.setup_helpers import Pybind11Extension, build_ext + + ext_modules = [ + Pybind11Extension( + "python_example", + sorted(glob("src/*.cpp")), + ), + ] + + setup( + ..., + cmdclass={"build_ext": build_ext}, + ext_modules=ext_modules + ) + +Since pybind11 does not require NumPy when building, a light-weight replacement +for NumPy's parallel compilation distutils tool is included. Use it like this: + +.. code-block:: python + + from pybind11.setup_helpers import ParallelCompile + + # Optional multithreaded build + ParallelCompile("NPY_NUM_BUILD_JOBS").install() + + setup(...) + +The argument is the name of an environment variable to control the number of +threads, such as ``NPY_NUM_BUILD_JOBS`` (as used by NumPy), though you can set +something different if you want. You can also pass ``default=N`` to set the +default number of threads (0 will take the number of threads available) and +``max=N``, the maximum number of threads; if you have a large extension you may +want set this to a memory dependent number. + +If you are developing rapidly and have a lot of C++ files, you may want to +avoid rebuilding files that have not changed. For simple cases were you are +using ``pip install -e .`` and do not have local headers, you can skip the +rebuild if a object file is newer than it's source (headers are not checked!) +with the following: + +.. code-block:: python + + from pybind11.setup_helpers import ParallelCompile, naive_recompile + + SmartCompile("NPY_NUM_BUILD_JOBS", needs_recompile=naive_recompile).install() + + +If you have a more complex build, you can implement a smarter function and pass +it to ``needs_recompile``, or you can use [Ccache]_ instead. ``CXX="cache g++" +pip install -e .`` would be the way to use it with GCC, for example. Unlike the +simple solution, this even works even when not compiling in editable mode, but +it does require Ccache to be installed. + +Keep in mind that Pip will not even attempt to rebuild if it thinks it has +already built a copy of your code, which it deduces from the version number. +One way to avoid this is to use [setuptools_scm]_, which will generate a +version number that includes the number of commits since your last tag and a +hash for a dirty directory. Another way to force a rebuild is purge your cache +or use Pip's ``--no-cache-dir`` option. + +.. [Ccache] https://ccache.dev + +.. [setuptools_scm] https://github.com/pypa/setuptools_scm + +.. _setup_helpers-pep518: + +PEP 518 requirements (Pip 10+ required) +--------------------------------------- + +If you use `PEP 518's <https://www.python.org/dev/peps/pep-0518/>`_ +``pyproject.toml`` file, you can ensure that ``pybind11`` is available during +the compilation of your project. When this file exists, Pip will make a new +virtual environment, download just the packages listed here in ``requires=``, +and build a wheel (binary Python package). It will then throw away the +environment, and install your wheel. + +Your ``pyproject.toml`` file will likely look something like this: + +.. code-block:: toml + + [build-system] + requires = ["setuptools", "wheel", "pybind11==2.6.0"] + build-backend = "setuptools.build_meta" + +.. note:: + + The main drawback to this method is that a `PEP 517`_ compliant build tool, + such as Pip 10+, is required for this approach to work; older versions of + Pip completely ignore this file. If you distribute binaries (called wheels + in Python) using something like `cibuildwheel`_, remember that ``setup.py`` + and ``pyproject.toml`` are not even contained in the wheel, so this high + Pip requirement is only for source builds, and will not affect users of + your binary wheels. + +.. _PEP 517: https://www.python.org/dev/peps/pep-0517/ +.. _cibuildwheel: https://cibuildwheel.readthedocs.io + +.. _setup_helpers-setup_requires: + +Classic ``setup_requires`` +-------------------------- + +If you want to support old versions of Pip with the classic +``setup_requires=["pybind11"]`` keyword argument to setup, which triggers a +two-phase ``setup.py`` run, then you will need to use something like this to +ensure the first pass works (which has not yet installed the ``setup_requires`` +packages, since it can't install something it does not know about): + +.. code-block:: python + + try: + from pybind11.setup_helpers import Pybind11Extension + except ImportError: + from setuptools import Extension as Pybind11Extension + + +It doesn't matter that the Extension class is not the enhanced subclass for the +first pass run; and the second pass will have the ``setup_requires`` +requirements. + +This is obviously more of a hack than the PEP 518 method, but it supports +ancient versions of Pip. + +.. _setup_helpers-copy-manually: + +Copy manually +------------- + +You can also copy ``setup_helpers.py`` directly to your project; it was +designed to be usable standalone, like the old example ``setup.py``. You can +set ``include_pybind11=False`` to skip including the pybind11 package headers, +so you can use it with git submodules and a specific git version. If you use +this, you will need to import from a local file in ``setup.py`` and ensure the +helper file is part of your MANIFEST. + + +Closely related, if you include pybind11 as a subproject, you can run the +``setup_helpers.py`` inplace. If loaded correctly, this should even pick up +the correct include for pybind11, though you can turn it off as shown above if +you want to input it manually. + +Suggested usage if you have pybind11 as a submodule in ``extern/pybind11``: + +.. code-block:: python + + DIR = os.path.abspath(os.path.dirname(__file__)) + + sys.path.append(os.path.join(DIR, "extern", "pybind11")) + from pybind11.setup_helpers import Pybind11Extension # noqa: E402 + + del sys.path[-1] + + +.. versionchanged:: 2.6 + + Added ``setup_helpers`` file. + Building with cppimport ======================== @@ -33,8 +232,8 @@ extension module can be created with just a few lines of code: .. code-block:: cmake - cmake_minimum_required(VERSION 2.8.12) - project(example) + cmake_minimum_required(VERSION 3.4...3.18) + project(example LANGUAGES CXX) add_subdirectory(pybind11) pybind11_add_module(example example.cpp) @@ -50,6 +249,11 @@ PyPI integration, can be found in the [cmake_example]_ repository. .. [cmake_example] https://github.com/pybind/cmake_example +.. versionchanged:: 2.6 + CMake 3.4+ is required. + +Further information can be found at :doc:`cmake/index`. + pybind11_add_module ------------------- @@ -59,7 +263,7 @@ function with the following signature: .. code-block:: cmake pybind11_add_module(<name> [MODULE | SHARED] [EXCLUDE_FROM_ALL] - [NO_EXTRAS] [SYSTEM] [THIN_LTO] source1 [source2 ...]) + [NO_EXTRAS] [THIN_LTO] [OPT_SIZE] source1 [source2 ...]) This function behaves very much like CMake's builtin ``add_library`` (in fact, it's a wrapper function around that command). It will add a library target @@ -86,53 +290,68 @@ latter optimizations are never applied in ``Debug`` mode. If ``NO_EXTRAS`` is given, they will always be disabled, even in ``Release`` mode. However, this will result in code bloat and is generally not recommended. -By default, pybind11 and Python headers will be included with ``-I``. In order -to include pybind11 as system library, e.g. to avoid warnings in downstream -code with warn-levels outside of pybind11's scope, set the option ``SYSTEM``. - As stated above, LTO is enabled by default. Some newer compilers also support different flavors of LTO such as `ThinLTO`_. Setting ``THIN_LTO`` will cause the function to prefer this flavor if available. The function falls back to -regular LTO if ``-flto=thin`` is not available. +regular LTO if ``-flto=thin`` is not available. If +``CMAKE_INTERPROCEDURAL_OPTIMIZATION`` is set (either ``ON`` or ``OFF``), then +that will be respected instead of the built-in flag search. + +.. note:: + + If you want to set the property form on targets or the + ``CMAKE_INTERPROCEDURAL_OPTIMIZATION_<CONFIG>`` versions of this, you should + still use ``set(CMAKE_INTERPROCEDURAL_OPTIMIZATION OFF)`` (otherwise a + no-op) to disable pybind11's ipo flags. + +The ``OPT_SIZE`` flag enables size-based optimization equivalent to the +standard ``/Os`` or ``-Os`` compiler flags and the ``MinSizeRel`` build type, +which avoid optimizations that that can substantially increase the size of the +resulting binary. This flag is particularly useful in projects that are split +into performance-critical parts and associated bindings. In this case, we can +compile the project in release mode (and hence, optimize performance globally), +and specify ``OPT_SIZE`` for the binding target, where size might be the main +concern as performance is often less critical here. A ~25% size reduction has +been observed in practice. This flag only changes the optimization behavior at +a per-target level and takes precedence over the global CMake build type +(``Release``, ``RelWithDebInfo``) except for ``Debug`` builds, where +optimizations remain disabled. .. _ThinLTO: http://clang.llvm.org/docs/ThinLTO.html Configuration variables ----------------------- -By default, pybind11 will compile modules with the C++14 standard, if available -on the target compiler, falling back to C++11 if C++14 support is not -available. Note, however, that this default is subject to change: future -pybind11 releases are expected to migrate to newer C++ standards as they become -available. To override this, the standard flag can be given explicitly in -``PYBIND11_CPP_STANDARD``: +By default, pybind11 will compile modules with the compiler default or the +minimum standard required by pybind11, whichever is higher. You can set the +standard explicitly with +`CMAKE_CXX_STANDARD <https://cmake.org/cmake/help/latest/variable/CMAKE_CXX_STANDARD.html>`_: .. code-block:: cmake - # Use just one of these: - # GCC/clang: - set(PYBIND11_CPP_STANDARD -std=c++11) - set(PYBIND11_CPP_STANDARD -std=c++14) - set(PYBIND11_CPP_STANDARD -std=c++1z) # Experimental C++17 support - # MSVC: - set(PYBIND11_CPP_STANDARD /std:c++14) - set(PYBIND11_CPP_STANDARD /std:c++latest) # Enables some MSVC C++17 features + set(CMAKE_CXX_STANDARD 14 CACHE STRING "C++ version selection") # or 11, 14, 17, 20 + set(CMAKE_CXX_STANDARD_REQUIRED ON) # optional, ensure standard is supported + set(CMAKE_CXX_EXTENSIONS OFF) # optional, keep compiler extensionsn off - add_subdirectory(pybind11) # or find_package(pybind11) +The variables can also be set when calling CMake from the command line using +the ``-D<variable>=<value>`` flag. You can also manually set ``CXX_STANDARD`` +on a target or use ``target_compile_features`` on your targets - anything that +CMake supports. -Note that this and all other configuration variables must be set **before** the -call to ``add_subdirectory`` or ``find_package``. The variables can also be set -when calling CMake from the command line using the ``-D<variable>=<value>`` flag. - -The target Python version can be selected by setting ``PYBIND11_PYTHON_VERSION`` -or an exact Python installation can be specified with ``PYTHON_EXECUTABLE``. -For example: +Classic Python support: The target Python version can be selected by setting +``PYBIND11_PYTHON_VERSION`` or an exact Python installation can be specified +with ``PYTHON_EXECUTABLE``. For example: .. code-block:: bash cmake -DPYBIND11_PYTHON_VERSION=3.6 .. - # or - cmake -DPYTHON_EXECUTABLE=path/to/python .. + + # Another method: + cmake -DPYTHON_EXECUTABLE=/path/to/python .. + + # This often is a good way to get the current Python, works in environments: + cmake -DPYTHON_EXECUTABLE=$(python3 -c "import sys; print(sys.executable)") .. + find_package vs. add_subdirectory --------------------------------- @@ -143,8 +362,8 @@ See the `Config file`_ docstring for details of relevant CMake variables. .. code-block:: cmake - cmake_minimum_required(VERSION 2.8.12) - project(example) + cmake_minimum_required(VERSION 3.4...3.18) + project(example LANGUAGES CXX) find_package(pybind11 REQUIRED) pybind11_add_module(example example.cpp) @@ -155,12 +374,19 @@ the pybind11 repository : .. code-block:: bash + # Classic CMake cd pybind11 mkdir build cd build cmake .. make install + # CMake 3.15+ + cd pybind11 + cmake -S . -B build + cmake --build build -j 2 # Build on 2 cores + cmake --install build + Once detected, the aforementioned ``pybind11_add_module`` can be employed as before. The function usage and configuration variables are identical no matter if pybind11 is added as a subdirectory or found as an installed package. You @@ -169,41 +395,134 @@ can refer to the same [cmake_example]_ repository for a full sample project .. _Config file: https://github.com/pybind/pybind11/blob/master/tools/pybind11Config.cmake.in -Advanced: interface library target ----------------------------------- -When using a version of CMake greater than 3.0, pybind11 can additionally -be used as a special *interface library* . The target ``pybind11::module`` -is available with pybind11 headers, Python headers and libraries as needed, -and C++ compile definitions attached. This target is suitable for linking -to an independently constructed (through ``add_library``, not -``pybind11_add_module``) target in the consuming project. +.. _find-python-mode: + +FindPython mode +--------------- + +CMake 3.12+ (3.15+ recommended) added a new module called FindPython that had a +highly improved search algorithm and modern targets and tools. If you use +FindPython, pybind11 will detect this and use the existing targets instead: + +.. code-block:: cmake + + cmake_minumum_required(VERSION 3.15...3.18) + project(example LANGUAGES CXX) + + find_package(Python COMPONENTS Interpreter Development REQUIRED) + find_package(pybind11 CONFIG REQUIRED) + # or add_subdirectory(pybind11) + + pybind11_add_module(example example.cpp) + +You can also use the targets (as listed below) with FindPython. If you define +``PYBIND11_FINDPYTHON``, pybind11 will perform the FindPython step for you +(mostly useful when building pybind11's own tests, or as a way to change search +algorithms from the CMake invocation, with ``-DPYBIND11_FINDPYTHON=ON``. + +.. warning:: + + If you use FindPython2 and FindPython3 to dual-target Python, use the + individual targets listed below, and avoid targets that directly include + Python parts. + +There are `many ways to hint or force a discovery of a specific Python +installation <https://cmake.org/cmake/help/latest/module/FindPython.html>`_), +setting ``Python_ROOT_DIR`` may be the most common one (though with +virtualenv/venv support, and Conda support, this tends to find the correct +Python version more often than the old system did). + +.. versionadded:: 2.6 + +Advanced: interface library targets +----------------------------------- + +Pybind11 supports modern CMake usage patterns with a set of interface targets, +available in all modes. The targets provided are: + + ``pybind11::headers`` + Just the pybind11 headers and minimum compile requirements + + ``pybind11::python2_no_register`` + Quiets the warning/error when mixing C++14 or higher and Python 2 + + ``pybind11::pybind11`` + Python headers + ``pybind11::headers`` + ``pybind11::python2_no_register`` (Python 2 only) + + ``pybind11::python_link_helper`` + Just the "linking" part of pybind11:module + + ``pybind11::module`` + Everything for extension modules - ``pybind11::pybind11`` + ``Python::Module`` (FindPython CMake 3.15+) or ``pybind11::python_link_helper`` + + ``pybind11::embed`` + Everything for embedding the Python interpreter - ``pybind11::pybind11`` + ``Python::Embed`` (FindPython) or Python libs + + ``pybind11::lto`` / ``pybind11::thin_lto`` + An alternative to `INTERPROCEDURAL_OPTIMIZATION` for adding link-time optimization. + + ``pybind11::windows_extras`` + ``/bigobj`` and ``/mp`` for MSVC. + + ``pybind11::opt_size`` + ``/Os`` for MSVC, ``-Os`` for other compilers. Does nothing for debug builds. + +Two helper functions are also provided: + + ``pybind11_strip(target)`` + Strips a target (uses ``CMAKE_STRIP`` after the target is built) + + ``pybind11_extension(target)`` + Sets the correct extension (with SOABI) for a target. + +You can use these targets to build complex applications. For example, the +``add_python_module`` function is identical to: .. code-block:: cmake - cmake_minimum_required(VERSION 3.0) - project(example) + cmake_minimum_required(VERSION 3.4) + project(example LANGUAGES CXX) find_package(pybind11 REQUIRED) # or add_subdirectory(pybind11) add_library(example MODULE main.cpp) - target_link_libraries(example PRIVATE pybind11::module) - set_target_properties(example PROPERTIES PREFIX "${PYTHON_MODULE_PREFIX}" - SUFFIX "${PYTHON_MODULE_EXTENSION}") + + target_link_libraries(example PRIVATE pybind11::module pybind11::lto pybind11::windows_extras) + + pybind11_extension(example) + pybind11_strip(example) + + set_target_properties(example PROPERTIES CXX_VISIBILITY_PRESET "hidden" + CUDA_VISIBILITY_PRESET "hidden") + +Instead of setting properties, you can set ``CMAKE_*`` variables to initialize these correctly. .. warning:: Since pybind11 is a metatemplate library, it is crucial that certain compiler flags are provided to ensure high quality code generation. In contrast to the ``pybind11_add_module()`` command, the CMake interface - library only provides the *minimal* set of parameters to ensure that the - code using pybind11 compiles, but it does **not** pass these extra compiler - flags (i.e. this is up to you). + provides a *composable* set of targets to ensure that you retain flexibility. + It can be expecially important to provide or set these properties; the + :ref:`FAQ <faq:symhidden>` contains an explanation on why these are needed. + +.. versionadded:: 2.6 - These include Link Time Optimization (``-flto`` on GCC/Clang/ICPC, ``/GL`` - and ``/LTCG`` on Visual Studio) and .OBJ files with many sections on Visual - Studio (``/bigobj``). The :ref:`FAQ <faq:symhidden>` contains an - explanation on why these are needed. +.. _nopython-mode: + +Advanced: NOPYTHON mode +----------------------- + +If you want complete control, you can set ``PYBIND11_NOPYTHON`` to completely +disable Python integration (this also happens if you run ``FindPython2`` and +``FindPython3`` without running ``FindPython``). This gives you complete +freedom to integrate into an existing system (like `Scikit-Build's +<https://scikit-build.readthedocs.io>`_ ``PythonExtensions``). +``pybind11_add_module`` and ``pybind11_extension`` will be unavailable, and the +targets will be missing any Python specific behavior. + +.. versionadded:: 2.6 Embedding the Python interpreter -------------------------------- @@ -217,8 +536,8 @@ information about usage in C++, see :doc:`/advanced/embedding`. .. code-block:: cmake - cmake_minimum_required(VERSION 3.0) - project(example) + cmake_minimum_required(VERSION 3.4...3.18) + project(example LANGUAGES CXX) find_package(pybind11 REQUIRED) # or add_subdirectory(pybind11) @@ -255,7 +574,7 @@ Besides, the ``--extension-suffix`` option may or may not be available, dependin on the distribution; in the latter case, the module extension can be manually set to ``.so``. -On Mac OS: the build command is almost the same but it also requires passing +On macOS: the build command is almost the same but it also requires passing the ``-undefined dynamic_lookup`` flag so as to ignore missing symbols when building the module: @@ -279,6 +598,13 @@ build system that works on all platforms including Windows. of possibly importing a second Python library into a process that already contains one (which will lead to a segfault). + +Building with Bazel +=================== + +You can build with the Bazel build system using the `pybind11_bazel +<https://github.com/pybind/pybind11_bazel>`_ repository. + Generating binding code automatically ===================================== @@ -287,3 +613,18 @@ code by introspecting existing C++ codebases using LLVM/Clang. See the [binder]_ documentation for details. .. [binder] http://cppbinder.readthedocs.io/en/latest/about.html + +[AutoWIG]_ is a Python library that wraps automatically compiled libraries into +high-level languages. It parses C++ code using LLVM/Clang technologies and +generates the wrappers using the Mako templating engine. The approach is automatic, +extensible, and applies to very complex C++ libraries, composed of thousands of +classes or incorporating modern meta-programming constructs. + +.. [AutoWIG] https://github.com/StatisKit/AutoWIG + +[robotpy-build]_ is a is a pure python, cross platform build tool that aims to +simplify creation of python wheels for pybind11 projects, and provide +cross-project dependency management. Additionally, it is able to autogenerate +customizable pybind11-based wrappers by parsing C++ header files. + +.. [robotpy-build] https://robotpy-build.readthedocs.io diff --git a/3rdparty/pybind11/docs/conf.py b/3rdparty/pybind11/docs/conf.py index fa6332de..66db310e 100644 --- a/3rdparty/pybind11/docs/conf.py +++ b/3rdparty/pybind11/docs/conf.py @@ -17,53 +17,65 @@ import sys import os import shlex import subprocess +from pathlib import Path +import re + +DIR = Path(__file__).parent.resolve() # If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. -#sys.path.insert(0, os.path.abspath('.')) +# sys.path.insert(0, os.path.abspath('.')) # -- General configuration ------------------------------------------------ # If your documentation needs a minimal Sphinx version, state it here. -#needs_sphinx = '1.0' +# needs_sphinx = '1.0' # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. -extensions = ['breathe'] +extensions = [ + "breathe", + "sphinxcontrib.rsvgconverter", + "sphinxcontrib.moderncmakedomain", +] -breathe_projects = {'pybind11': '.build/doxygenxml/'} -breathe_default_project = 'pybind11' -breathe_domain_by_extension = {'h': 'cpp'} +breathe_projects = {"pybind11": ".build/doxygenxml/"} +breathe_default_project = "pybind11" +breathe_domain_by_extension = {"h": "cpp"} # Add any paths that contain templates here, relative to this directory. -templates_path = ['.templates'] +templates_path = [".templates"] # The suffix(es) of source filenames. # You can specify multiple suffix as a list of string: # source_suffix = ['.rst', '.md'] -source_suffix = '.rst' +source_suffix = ".rst" # The encoding of source files. -#source_encoding = 'utf-8-sig' +# source_encoding = 'utf-8-sig' # The master toctree document. -master_doc = 'index' +master_doc = "index" # General information about the project. -project = 'pybind11' -copyright = '2017, Wenzel Jakob' -author = 'Wenzel Jakob' +project = "pybind11" +copyright = "2017, Wenzel Jakob" +author = "Wenzel Jakob" # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the # built documents. -# -# The short X.Y version. -version = '2.5' + +# Read the listed version +with open("../pybind11/_version.py") as f: + code = compile(f.read(), "../pybind11/_version.py", "exec") +loc = {} +exec(code, loc) + # The full version, including alpha/beta/rc tags. -release = '2.5.0' +version = loc["__version__"] # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. @@ -74,37 +86,37 @@ language = None # There are two options for replacing |today|: either, you set today to some # non-false value, then it is used: -#today = '' +# today = '' # Else, today_fmt is used as the format for a strftime call. -#today_fmt = '%B %d, %Y' +# today_fmt = '%B %d, %Y' # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. -exclude_patterns = ['.build', 'release.rst'] +exclude_patterns = [".build", "release.rst"] # The reST default role (used for this markup: `text`) to use for all # documents. -default_role = 'any' +default_role = "any" # If true, '()' will be appended to :func: etc. cross-reference text. -#add_function_parentheses = True +# add_function_parentheses = True # If true, the current module name will be prepended to all description # unit titles (such as .. function::). -#add_module_names = True +# add_module_names = True # If true, sectionauthor and moduleauthor directives will be shown in the # output. They are ignored by default. -#show_authors = False +# show_authors = False # The name of the Pygments (syntax highlighting) style to use. -#pygments_style = 'monokai' +# pygments_style = 'monokai' # A list of ignored prefixes for module index sorting. -#modindex_common_prefix = [] +# modindex_common_prefix = [] # If true, keep warnings as "system message" paragraphs in the built documents. -#keep_warnings = False +# keep_warnings = False # If true, `todo` and `todoList` produce output, else they produce nothing. todo_include_todos = False @@ -115,141 +127,148 @@ todo_include_todos = False # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. -on_rtd = os.environ.get('READTHEDOCS', None) == 'True' +on_rtd = os.environ.get("READTHEDOCS", None) == "True" if not on_rtd: # only import and set the theme if we're building docs locally import sphinx_rtd_theme - html_theme = 'sphinx_rtd_theme' + + html_theme = "sphinx_rtd_theme" html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] - html_context = { - 'css_files': [ - '_static/theme_overrides.css' - ] - } + html_context = {"css_files": ["_static/theme_overrides.css"]} else: html_context = { - 'css_files': [ - '//media.readthedocs.org/css/sphinx_rtd_theme.css', - '//media.readthedocs.org/css/readthedocs-doc-embed.css', - '_static/theme_overrides.css' + "css_files": [ + "//media.readthedocs.org/css/sphinx_rtd_theme.css", + "//media.readthedocs.org/css/readthedocs-doc-embed.css", + "_static/theme_overrides.css", ] } # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the # documentation. -#html_theme_options = {} +# html_theme_options = {} # Add any paths that contain custom themes here, relative to this directory. -#html_theme_path = [] +# html_theme_path = [] # The name for this set of Sphinx documents. If None, it defaults to -# "<project> v<release> documentation". -#html_title = None +# "<project> v<version> documentation". +# html_title = None # A shorter title for the navigation bar. Default is the same as html_title. -#html_short_title = None +# html_short_title = None # The name of an image file (relative to this directory) to place at the top # of the sidebar. -#html_logo = None +# html_logo = None # The name of an image file (within the static path) to use as favicon of the # docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 # pixels large. -#html_favicon = None +# html_favicon = None # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ['_static'] +html_static_path = ["_static"] # Add any extra paths that contain custom files (such as robots.txt or # .htaccess) here, relative to this directory. These files are copied # directly to the root of the documentation. -#html_extra_path = [] +# html_extra_path = [] # If not '', a 'Last updated on:' timestamp is inserted at every page bottom, # using the given strftime format. -#html_last_updated_fmt = '%b %d, %Y' +# html_last_updated_fmt = '%b %d, %Y' # If true, SmartyPants will be used to convert quotes and dashes to # typographically correct entities. -#html_use_smartypants = True +# html_use_smartypants = True # Custom sidebar templates, maps document names to template names. -#html_sidebars = {} +# html_sidebars = {} # Additional templates that should be rendered to pages, maps page names to # template names. -#html_additional_pages = {} +# html_additional_pages = {} # If false, no module index is generated. -#html_domain_indices = True +# html_domain_indices = True # If false, no index is generated. -#html_use_index = True +# html_use_index = True # If true, the index is split into individual pages for each letter. -#html_split_index = False +# html_split_index = False # If true, links to the reST sources are added to the pages. -#html_show_sourcelink = True +# html_show_sourcelink = True # If true, "Created using Sphinx" is shown in the HTML footer. Default is True. -#html_show_sphinx = True +# html_show_sphinx = True # If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. -#html_show_copyright = True +# html_show_copyright = True # If true, an OpenSearch description file will be output, and all pages will # contain a <link> tag referring to it. The value of this option must be the # base URL from which the finished HTML is served. -#html_use_opensearch = '' +# html_use_opensearch = '' # This is the file name suffix for HTML files (e.g. ".xhtml"). -#html_file_suffix = None +# html_file_suffix = None # Language to be used for generating the HTML full-text search index. # Sphinx supports the following languages: # 'da', 'de', 'en', 'es', 'fi', 'fr', 'h', 'it', 'ja' # 'nl', 'no', 'pt', 'ro', 'r', 'sv', 'tr' -#html_search_language = 'en' +# html_search_language = 'en' # A dictionary with options for the search language support, empty by default. # Now only 'ja' uses this config value -#html_search_options = {'type': 'default'} +# html_search_options = {'type': 'default'} # The name of a javascript file (relative to the configuration directory) that # implements a search results scorer. If empty, the default will be used. -#html_search_scorer = 'scorer.js' +# html_search_scorer = 'scorer.js' # Output file base name for HTML help builder. -htmlhelp_basename = 'pybind11doc' +htmlhelp_basename = "pybind11doc" # -- Options for LaTeX output --------------------------------------------- latex_elements = { -# The paper size ('letterpaper' or 'a4paper'). -#'papersize': 'letterpaper', - -# The font size ('10pt', '11pt' or '12pt'). -#'pointsize': '10pt', - -# Additional stuff for the LaTeX preamble. -'preamble': '\DeclareUnicodeCharacter{00A0}{}', - -# Latex figure (float) alignment -#'figure_align': 'htbp', + # The paper size ('letterpaper' or 'a4paper'). + # 'papersize': 'letterpaper', + # + # The font size ('10pt', '11pt' or '12pt'). + # 'pointsize': '10pt', + # + # Additional stuff for the LaTeX preamble. + # remove blank pages (between the title page and the TOC, etc.) + "classoptions": ",openany,oneside", + "preamble": r""" +\usepackage{fontawesome} +\usepackage{textgreek} +\DeclareUnicodeCharacter{00A0}{} +\DeclareUnicodeCharacter{2194}{\faArrowsH} +\DeclareUnicodeCharacter{1F382}{\faBirthdayCake} +\DeclareUnicodeCharacter{1F355}{\faAdjust} +\DeclareUnicodeCharacter{0301}{'} +\DeclareUnicodeCharacter{03C0}{\textpi} + +""", + # Latex figure (float) alignment + # 'figure_align': 'htbp', } # Grouping the document tree into LaTeX files. List of tuples # (source start file, target name, title, # author, documentclass [howto, manual, or own class]). latex_documents = [ - (master_doc, 'pybind11.tex', 'pybind11 Documentation', - 'Wenzel Jakob', 'manual'), + (master_doc, "pybind11.tex", "pybind11 Documentation", "Wenzel Jakob", "manual"), ] # The name of an image file (relative to this directory) to place at the top of @@ -258,32 +277,29 @@ latex_documents = [ # For "manual" documents, if this is true, then toplevel headings are parts, # not chapters. -#latex_use_parts = False +# latex_use_parts = False # If true, show page references after internal links. -#latex_show_pagerefs = False +# latex_show_pagerefs = False # If true, show URL addresses after external links. -#latex_show_urls = False +# latex_show_urls = False # Documents to append as an appendix to all manuals. -#latex_appendices = [] +# latex_appendices = [] # If false, no module index is generated. -#latex_domain_indices = True +# latex_domain_indices = True # -- Options for manual page output --------------------------------------- # One entry per manual page. List of tuples # (source start file, name, description, authors, manual section). -man_pages = [ - (master_doc, 'pybind11', 'pybind11 Documentation', - [author], 1) -] +man_pages = [(master_doc, "pybind11", "pybind11 Documentation", [author], 1)] # If true, show URL addresses after external links. -#man_show_urls = False +# man_show_urls = False # -- Options for Texinfo output ------------------------------------------- @@ -292,41 +308,70 @@ man_pages = [ # (source start file, target name, title, author, # dir menu entry, description, category) texinfo_documents = [ - (master_doc, 'pybind11', 'pybind11 Documentation', - author, 'pybind11', 'One line description of project.', - 'Miscellaneous'), + ( + master_doc, + "pybind11", + "pybind11 Documentation", + author, + "pybind11", + "One line description of project.", + "Miscellaneous", + ), ] # Documents to append as an appendix to all manuals. -#texinfo_appendices = [] +# texinfo_appendices = [] # If false, no module index is generated. -#texinfo_domain_indices = True +# texinfo_domain_indices = True # How to display URL addresses: 'footnote', 'no', or 'inline'. -#texinfo_show_urls = 'footnote' +# texinfo_show_urls = 'footnote' # If true, do not generate a @detailmenu in the "Top" node's menu. -#texinfo_no_detailmenu = False +# texinfo_no_detailmenu = False -primary_domain = 'cpp' -highlight_language = 'cpp' +primary_domain = "cpp" +highlight_language = "cpp" def generate_doxygen_xml(app): - build_dir = os.path.join(app.confdir, '.build') + build_dir = os.path.join(app.confdir, ".build") if not os.path.exists(build_dir): os.mkdir(build_dir) try: - subprocess.call(['doxygen', '--version']) - retcode = subprocess.call(['doxygen'], cwd=app.confdir) + subprocess.call(["doxygen", "--version"]) + retcode = subprocess.call(["doxygen"], cwd=app.confdir) if retcode < 0: sys.stderr.write("doxygen error code: {}\n".format(-retcode)) except OSError as e: sys.stderr.write("doxygen execution failed: {}\n".format(e)) +def prepare(app): + with open(DIR.parent / "README.rst") as f: + contents = f.read() + + # Filter out section titles for index.rst for LaTeX + if app.builder.name == "latex": + contents = re.sub(r"^(.*)\n[-~]{3,}$", r"**\1**", contents, flags=re.MULTILINE) + + with open(DIR / "readme.rst", "w") as f: + f.write(contents) + + +def clean_up(app, exception): + (DIR / "readme.rst").unlink() + + def setup(app): - """Add hook for building doxygen xml when needed""" + + # Add hook for building doxygen xml when needed app.connect("builder-inited", generate_doxygen_xml) + + # Copy the readme in + app.connect("builder-inited", prepare) + + # Clean up the generated readme + app.connect("build-finished", clean_up) diff --git a/3rdparty/pybind11/docs/faq.rst b/3rdparty/pybind11/docs/faq.rst index 4d491fb8..8bf05a40 100644 --- a/3rdparty/pybind11/docs/faq.rst +++ b/3rdparty/pybind11/docs/faq.rst @@ -5,7 +5,7 @@ Frequently asked questions =========================================================== 1. Make sure that the name specified in PYBIND11_MODULE is identical to the -filename of the extension library (without prefixes such as .so) +filename of the extension library (without suffixes such as .so) 2. If the above did not fix the issue, you are likely using an incompatible version of Python (for instance, the extension library was compiled against @@ -27,18 +27,6 @@ The Python interpreter immediately crashes when importing my module See the first answer. -CMake doesn't detect the right Python version -============================================= - -The CMake-based build system will try to automatically detect the installed -version of Python and link against that. When this fails, or when there are -multiple versions of Python and it finds the wrong one, delete -``CMakeCache.txt`` and then invoke CMake as follows: - -.. code-block:: bash - - cmake -DPYTHON_EXECUTABLE:FILEPATH=<path-to-python-executable> . - .. _faq_reference_arguments: Limitations involving reference arguments @@ -100,8 +88,8 @@ following example: .. code-block:: cpp - void init_ex1(py::module &); - void init_ex2(py::module &); + void init_ex1(py::module_ &); + void init_ex2(py::module_ &); /* ... */ PYBIND11_MODULE(example, m) { @@ -114,7 +102,7 @@ following example: .. code-block:: cpp - void init_ex1(py::module &m) { + void init_ex1(py::module_ &m) { m.def("add", [](int a, int b) { return a + b; }); } @@ -122,7 +110,7 @@ following example: .. code-block:: cpp - void init_ex2(py::module &m) { + void init_ex2(py::module_ &m) { m.def("sub", [](int a, int b) { return a - b; }); } @@ -275,17 +263,34 @@ been received, you must either explicitly interrupt execution by throwing }); } +CMake doesn't detect the right Python version +============================================= + +The CMake-based build system will try to automatically detect the installed +version of Python and link against that. When this fails, or when there are +multiple versions of Python and it finds the wrong one, delete +``CMakeCache.txt`` and then add ``-DPYTHON_EXECUTABLE=$(which python)`` to your +CMake configure line. (Replace ``$(which python)`` with a path to python if +your prefer.) + +You can alternatively try ``-DPYBIND11_FINDPYTHON=ON``, which will activate the +new CMake FindPython support instead of pybind11's custom search. Requires +CMake 3.12+, and 3.15+ or 3.18.2+ are even better. You can set this in your +``CMakeLists.txt`` before adding or finding pybind11, as well. + Inconsistent detection of Python version in CMake and pybind11 ============================================================== -The functions ``find_package(PythonInterp)`` and ``find_package(PythonLibs)`` provided by CMake -for Python version detection are not used by pybind11 due to unreliability and limitations that make -them unsuitable for pybind11's needs. Instead pybind provides its own, more reliable Python detection -CMake code. Conflicts can arise, however, when using pybind11 in a project that *also* uses the CMake -Python detection in a system with several Python versions installed. +The functions ``find_package(PythonInterp)`` and ``find_package(PythonLibs)`` +provided by CMake for Python version detection are modified by pybind11 due to +unreliability and limitations that make them unsuitable for pybind11's needs. +Instead pybind11 provides its own, more reliable Python detection CMake code. +Conflicts can arise, however, when using pybind11 in a project that *also* uses +the CMake Python detection in a system with several Python versions installed. -This difference may cause inconsistencies and errors if *both* mechanisms are used in the same project. Consider the following -Cmake code executed in a system with Python 2.7 and 3.x installed: +This difference may cause inconsistencies and errors if *both* mechanisms are +used in the same project. Consider the following CMake code executed in a +system with Python 2.7 and 3.x installed: .. code-block:: cmake @@ -303,10 +308,24 @@ In contrast this code: find_package(PythonInterp) find_package(PythonLibs) -will detect Python 3.x for pybind11 and may crash on ``find_package(PythonLibs)`` afterwards. - -It is advised to avoid using ``find_package(PythonInterp)`` and ``find_package(PythonLibs)`` from CMake and rely -on pybind11 in detecting Python version. If this is not possible CMake machinery should be called *before* including pybind11. +will detect Python 3.x for pybind11 and may crash on +``find_package(PythonLibs)`` afterwards. + +There are three possible solutions: + +1. Avoid using ``find_package(PythonInterp)`` and ``find_package(PythonLibs)`` + from CMake and rely on pybind11 in detecting Python version. If this is not + possible, the CMake machinery should be called *before* including pybind11. +2. Set ``PYBIND11_FINDPYTHON`` to ``True`` or use ``find_package(Python + COMPONENTS Interpreter Development)`` on modern CMake (3.12+, 3.15+ better, + 3.18.2+ best). Pybind11 in these cases uses the new CMake FindPython instead + of the old, deprecated search tools, and these modules are much better at + finding the correct Python. +3. Set ``PYBIND11_NOPYTHON`` to ``TRUE``. Pybind11 will not search for Python. + However, you will have to use the target-based system, and do more setup + yourself, because it does not know about or include things that depend on + Python, like ``pybind11_add_module``. This might be ideal for integrating + into an existing system, like scikit-build's Python helpers. How to cite this project? ========================= diff --git a/3rdparty/pybind11/docs/index.rst b/3rdparty/pybind11/docs/index.rst index d236611b..4e2e8ca3 100644 --- a/3rdparty/pybind11/docs/index.rst +++ b/3rdparty/pybind11/docs/index.rst @@ -1,18 +1,17 @@ -.. only: not latex +.. only:: latex - .. image:: pybind11-logo.png + Intro + ===== -pybind11 --- Seamless operability between C++11 and Python -========================================================== +.. include:: readme.rst -.. only: not latex +.. only:: not latex Contents: .. toctree:: :maxdepth: 1 - intro changelog upgrade @@ -20,6 +19,7 @@ pybind11 --- Seamless operability between C++11 and Python :caption: The Basics :maxdepth: 2 + installing basics classes compiling @@ -45,3 +45,4 @@ pybind11 --- Seamless operability between C++11 and Python benchmark limitations reference + cmake/index diff --git a/3rdparty/pybind11/docs/installing.rst b/3rdparty/pybind11/docs/installing.rst new file mode 100644 index 00000000..25972859 --- /dev/null +++ b/3rdparty/pybind11/docs/installing.rst @@ -0,0 +1,103 @@ +.. _installing: + +Installing the library +###################### + +There are several ways to get the pybind11 source, which lives at +`pybind/pybind11 on GitHub <https://github.com/pybind/pybind11>`_. The pybind11 +developers recommend one of the first three ways listed here, submodule, PyPI, +or conda-forge, for obtaining pybind11. + +Include as a submodule +====================== + +When you are working on a project in Git, you can use the pybind11 repository +as a submodule. From your git repository, use: + +.. code-block:: bash + + git submodule add ../../pybind/pybind11 extern/pybind11 -b stable + git submodule update --init + +This assumes you are placing your dependencies in ``extern/``, and that you are +using GitHub; if you are not using GitHub, use the full https or ssh URL +instead of the relative URL ``../../pybind/pybind11`` above. Some other servers +also require the ``.git`` extension (GitHub does not). + +From here, you can now include ``extern/pybind11/include``, or you can use +the various integration tools (see :ref:`compiling`) pybind11 provides directly +from the local folder. + +Include with PyPI +================= + +You can download the sources and CMake files as a Python package from PyPI +using Pip. Just use: + +.. code-block:: bash + + pip install pybind11 + +This will provide pybind11 in a standard Python package format. If you want +pybind11 available directly in your environment root, you can use: + +.. code-block:: bash + + pip install "pybind11[global]" + +This is not recommended if you are installing with your system Python, as it +will add files to ``/usr/local/include/pybind11`` and +``/usr/local/share/cmake/pybind11``, so unless that is what you want, it is +recommended only for use in virtual environments or your ``pyproject.toml`` +file (see :ref:`compiling`). + +Include with conda-forge +======================== + +You can use pybind11 with conda packaging via `conda-forge +<https://github.com/conda-forge/pybind11-feedstock>`_: + +.. code-block:: bash + + conda install -c conda-forge pybind11 + + +Include with vcpkg +================== +You can download and install pybind11 using the Microsoft `vcpkg +<https://github.com/Microsoft/vcpkg/>`_ dependency manager: + +.. code-block:: bash + + git clone https://github.com/Microsoft/vcpkg.git + cd vcpkg + ./bootstrap-vcpkg.sh + ./vcpkg integrate install + vcpkg install pybind11 + +The pybind11 port in vcpkg is kept up to date by Microsoft team members and +community contributors. If the version is out of date, please `create an issue +or pull request <https://github.com/Microsoft/vcpkg/>`_ on the vcpkg +repository. + +Global install with brew +======================== + +The brew package manager (Homebrew on macOS, or Linuxbrew on Linux) has a +`pybind11 package +<https://github.com/Homebrew/homebrew-core/blob/master/Formula/pybind11.rb>`_. +To install: + +.. code-block:: bash + + brew install pybind11 + +.. We should list Conan, and possibly a few other C++ package managers (hunter, +.. perhaps). Conan has a very clean CMake integration that would be good to show. + +Other options +============= + +Other locations you can find pybind11 are `listed here +<https://repology.org/project/python:pybind11/versions>`_; these are maintained +by various packagers and the community. diff --git a/3rdparty/pybind11/docs/intro.rst b/3rdparty/pybind11/docs/intro.rst deleted file mode 100644 index 10e1799a..00000000 --- a/3rdparty/pybind11/docs/intro.rst +++ /dev/null @@ -1,93 +0,0 @@ -.. image:: pybind11-logo.png - -About this project -================== -**pybind11** is a lightweight header-only library that exposes C++ types in Python -and vice versa, mainly to create Python bindings of existing C++ code. Its -goals and syntax are similar to the excellent `Boost.Python`_ library by David -Abrahams: to minimize boilerplate code in traditional extension modules by -inferring type information using compile-time introspection. - -.. _Boost.Python: http://www.boost.org/doc/libs/release/libs/python/doc/index.html - -The main issue with Boost.Python—and the reason for creating such a similar -project—is Boost. Boost is an enormously large and complex suite of utility -libraries that works with almost every C++ compiler in existence. This -compatibility has its cost: arcane template tricks and workarounds are -necessary to support the oldest and buggiest of compiler specimens. Now that -C++11-compatible compilers are widely available, this heavy machinery has -become an excessively large and unnecessary dependency. -Think of this library as a tiny self-contained version of Boost.Python with -everything stripped away that isn't relevant for binding generation. Without -comments, the core header files only require ~4K lines of code and depend on -Python (2.7 or 3.x, or PyPy2.7 >= 5.7) and the C++ standard library. This -compact implementation was possible thanks to some of the new C++11 language -features (specifically: tuples, lambda functions and variadic templates). Since -its creation, this library has grown beyond Boost.Python in many ways, leading -to dramatically simpler binding code in many common situations. - -Core features -************* -The following core C++ features can be mapped to Python - -- Functions accepting and returning custom data structures per value, reference, or pointer -- Instance methods and static methods -- Overloaded functions -- Instance attributes and static attributes -- Arbitrary exception types -- Enumerations -- Callbacks -- Iterators and ranges -- Custom operators -- Single and multiple inheritance -- STL data structures -- Smart pointers with reference counting like ``std::shared_ptr`` -- Internal references with correct reference counting -- C++ classes with virtual (and pure virtual) methods can be extended in Python - -Goodies -******* -In addition to the core functionality, pybind11 provides some extra goodies: - -- Python 2.7, 3.x, and PyPy (PyPy2.7 >= 5.7) are supported with an - implementation-agnostic interface. - -- It is possible to bind C++11 lambda functions with captured variables. The - lambda capture data is stored inside the resulting Python function object. - -- pybind11 uses C++11 move constructors and move assignment operators whenever - possible to efficiently transfer custom data types. - -- It's easy to expose the internal storage of custom data types through - Pythons' buffer protocols. This is handy e.g. for fast conversion between - C++ matrix classes like Eigen and NumPy without expensive copy operations. - -- pybind11 can automatically vectorize functions so that they are transparently - applied to all entries of one or more NumPy array arguments. - -- Python's slice-based access and assignment operations can be supported with - just a few lines of code. - -- Everything is contained in just a few header files; there is no need to link - against any additional libraries. - -- Binaries are generally smaller by a factor of at least 2 compared to - equivalent bindings generated by Boost.Python. A recent pybind11 conversion - of `PyRosetta`_, an enormous Boost.Python binding project, reported a binary - size reduction of **5.4x** and compile time reduction by **5.8x**. - -- Function signatures are precomputed at compile time (using ``constexpr``), - leading to smaller binaries. - -- With little extra effort, C++ types can be pickled and unpickled similar to - regular Python objects. - -.. _PyRosetta: http://graylab.jhu.edu/RosettaCon2016/PyRosetta-4.pdf - -Supported compilers -******************* - -1. Clang/LLVM (any non-ancient version with C++11 support) -2. GCC 4.8 or newer -3. Microsoft Visual Studio 2015 or newer -4. Intel C++ compiler v17 or newer (v16 with pybind11 v2.0 and v15 with pybind11 v2.0 and a `workaround <https://github.com/pybind/pybind11/issues/276>`_ ) diff --git a/3rdparty/pybind11/docs/limitations.rst b/3rdparty/pybind11/docs/limitations.rst index a1a4f1af..be7300cd 100644 --- a/3rdparty/pybind11/docs/limitations.rst +++ b/3rdparty/pybind11/docs/limitations.rst @@ -1,6 +1,9 @@ Limitations ########### +Design choices +^^^^^^^^^^^^^^ + pybind11 strives to be a general solution to binding generation, but it also has certain limitations: @@ -11,10 +14,59 @@ certain limitations: - The NumPy interface ``pybind11::array`` greatly simplifies accessing numerical data from C++ (and vice versa), but it's not a full-blown array - class like ``Eigen::Array`` or ``boost.multi_array``. + class like ``Eigen::Array`` or ``boost.multi_array``. ``Eigen`` objects are + directly supported, however, with ``pybind11/eigen.h``. + +Large but useful features could be implemented in pybind11 but would lead to a +significant increase in complexity. Pybind11 strives to be simple and compact. +Users who require large new features are encouraged to write an extension to +pybind11; see `pybind11_json <https://github.com/pybind/pybind11_json>`_ for an +example. + + +Known bugs +^^^^^^^^^^ + +These are issues that hopefully will one day be fixed, but currently are +unsolved. If you know how to help with one of these issues, contributions +are welcome! + +- Intel 20.2 is currently having an issue with the test suite. + `#2573 <https://github.com/pybind/pybind11/pull/2573>`_ + +- Debug mode Python does not support 1-5 tests in the test suite currently. + `#2422 <https://github.com/pybind/pybind11/pull/2422>`_ + +- PyPy3 7.3.1 and 7.3.2 have issues with several tests on 32-bit Windows. + +Known limitations +^^^^^^^^^^^^^^^^^ + +These are issues that are probably solvable, but have not been fixed yet. A +clean, well written patch would likely be accepted to solve them. + +- Type casters are not kept alive recursively. + `#2527 <https://github.com/pybind/pybind11/issues/2527>`_ + One consequence is that containers of ``char *`` are currently not supported. + `#2245 <https://github.com/pybind/pybind11/issues/2245>`_ + +- The ``cpptest`` does not run on Windows with Python 3.8 or newer, due to DLL + loader changes. User code that is correctly installed should not be affected. + `#2560 <https://github.com/pybind/pybind11/issue/2560>`_ + +Python 3.9.0 warning +^^^^^^^^^^^^^^^^^^^^ -These features could be implemented but would lead to a significant increase in -complexity. I've decided to draw the line here to keep this project simple and -compact. Users who absolutely require these features are encouraged to fork -pybind11. +Combining older versions of pybind11 (< 2.6.0) with Python on 3.9.0 will +trigger undefined behavior that typically manifests as crashes during +interpreter shutdown (but could also destroy your data. **You have been +warned**). +This issue has been +`fixed in Python <https://github.com/python/cpython/pull/22670>`_. As a +mitigation until 3.9.1 is released and commonly used, pybind11 (2.6.0 or newer) +includes a temporary workaround specifically when Python 3.9.0 is detected at +runtime, leaking about 50 bytes of memory when a callback function is garbage +collected. For reference; the pybind11 test suite has about 2,000 such +callbacks, but only 49 are garbage collected before the end-of-process. Wheels +built with Python 3.9.0 will correctly avoid the leak when run in Python 3.9.1. diff --git a/3rdparty/pybind11/docs/reference.rst b/3rdparty/pybind11/docs/reference.rst index a9fbe600..e3a61afb 100644 --- a/3rdparty/pybind11/docs/reference.rst +++ b/3rdparty/pybind11/docs/reference.rst @@ -46,7 +46,7 @@ With reference counting Convenience classes for specific Python types ============================================= -.. doxygenclass:: module +.. doxygenclass:: module_ :members: .. doxygengroup:: pytypes @@ -91,15 +91,15 @@ Inheritance See :doc:`/classes` and :doc:`/advanced/classes` for more detail. -.. doxygendefine:: PYBIND11_OVERLOAD +.. doxygendefine:: PYBIND11_OVERRIDE -.. doxygendefine:: PYBIND11_OVERLOAD_PURE +.. doxygendefine:: PYBIND11_OVERRIDE_PURE -.. doxygendefine:: PYBIND11_OVERLOAD_NAME +.. doxygendefine:: PYBIND11_OVERRIDE_NAME -.. doxygendefine:: PYBIND11_OVERLOAD_PURE_NAME +.. doxygendefine:: PYBIND11_OVERRIDE_PURE_NAME -.. doxygenfunction:: get_overload +.. doxygenfunction:: get_override Exceptions ========== diff --git a/3rdparty/pybind11/docs/release.rst b/3rdparty/pybind11/docs/release.rst index 9846f971..43f502a1 100644 --- a/3rdparty/pybind11/docs/release.rst +++ b/3rdparty/pybind11/docs/release.rst @@ -1,21 +1,77 @@ +On version numbers +^^^^^^^^^^^^^^^^^^ + +The two version numbers (C++ and Python) must match when combined (checked when +you build the PyPI package), and must be a valid `PEP 440 +<https://www.python.org/dev/peps/pep-0440>`_ version when combined. + +For example: + +.. code-block:: C++ + + #define PYBIND11_VERSION_MAJOR X + #define PYBIND11_VERSION_MINOR Y + #define PYBIND11_VERSION_PATCH Z.dev1 + +For beta, ``PYBIND11_VERSION_PATCH`` should be ``Z.b1``. RC's can be ``Z.rc1``. +Always include the dot (even though PEP 440 allows it to be dropped). For a +final release, this must be a simple integer. + + To release a new version of pybind11: +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -- Update the version number and push to pypi - - Update ``pybind11/_version.py`` (set release version, remove 'dev'). - - Update ``PYBIND11_VERSION_MAJOR`` etc. in ``include/pybind11/detail/common.h``. - - Ensure that all the information in ``setup.py`` is up-to-date. - - Update version in ``docs/conf.py``. - - Tag release date in ``docs/changelog.rst``. - - ``git add`` and ``git commit``. - - if new minor version: ``git checkout -b vX.Y``, ``git push -u origin vX.Y`` - - ``git tag -a vX.Y.Z -m 'vX.Y.Z release'``. +- Update the version number + - Update ``PYBIND11_VERSION_MAJOR`` etc. in + ``include/pybind11/detail/common.h``. PATCH should be a simple integer. + - Update ``pybind11/_version.py`` (match above) + - Ensure that all the information in ``setup.py`` is up-to-date. + - Add release date in ``docs/changelog.rst``. + - ``git add`` and ``git commit``, ``git push``. **Ensure CI passes**. (If it + fails due to a known flake issue, either ignore or restart CI.) +- Add a release branch if this is a new minor version + - ``git checkout -b vX.Y``, ``git push -u origin vX.Y`` +- Update tags (optional; if you skip this, the GitHub release makes a + non-annotated tag for you) + - ``git tag -a vX.Y.Z -m 'vX.Y.Z release'``. + - ``git push --tags``. +- Update stable + - ``git checkout stable`` + - ``git merge master`` - ``git push`` - - ``git push --tags``. - - ``python setup.py sdist upload``. - - ``python setup.py bdist_wheel upload``. +- Make a GitHub release (this shows up in the UI, sends new release + notifications to users watching releases, and also uploads PyPI packages). + (Note: if you do not use an existing tag, this creates a new lightweight tag + for you, so you could skip the above step). + - GUI method: click "Create a new release" on the far right, fill in the tag + name (if you didn't tag above, it will be made here), fill in a release + name like "Version X.Y.Z", and optionally copy-and-paste the changelog into + the description (processed as markdown by Pandoc). Check "pre-release" if + this is a beta/RC. + - CLI method: with ``gh`` installed, run ``gh release create vX.Y.Z -t "Version X.Y.Z"`` + If this is a pre-release, add ``-p``. + - Get back to work - - Update ``_version.py`` (add 'dev' and increment minor). - - Update version in ``docs/conf.py`` - - Update version macros in ``include/pybind11/common.h`` - - ``git add`` and ``git commit``. - ``git push`` + - Make sure you are on master, not somewhere else: ``git checkout master`` + - Update version macros in ``include/pybind11/detail/common.h`` (set PATCH to + ``0.dev1`` and increment MINOR). + - Update ``_version.py`` to match + - Add a plot for in-development updates in ``docs/changelog.rst``. + - ``git add``, ``git commit``, ``git push`` + +If a version branch is updated, remember to set PATCH to ``1.dev1``. + + +Manual packaging +^^^^^^^^^^^^^^^^ + +If you need to manually upload releases, you can download the releases from the job artifacts and upload them with twine. You can also make the files locally (not recommended in general, as your local directory is more likely to be "dirty" and SDists love picking up random unrelated/hidden files); this is the procedure: + +.. code-block:: bash + + python3 -m pip install build + python3 -m build + PYBIND11_SDIST_GLOBAL=1 python3 -m build + twine upload dist/* + +This makes SDists and wheels, and the final line uploads them. diff --git a/3rdparty/pybind11/docs/requirements.txt b/3rdparty/pybind11/docs/requirements.txt index 3818fe80..35366e3c 100644 --- a/3rdparty/pybind11/docs/requirements.txt +++ b/3rdparty/pybind11/docs/requirements.txt @@ -1 +1,7 @@ -breathe == 4.5.0 +breathe==4.20.0 +commonmark==0.9.1 +recommonmark==0.6.0 +sphinx==3.2.1 +sphinx_rtd_theme==0.5.0 +sphinxcontrib-moderncmakedomain==3.13 +sphinxcontrib-svg2pdfconverter==1.1.0 diff --git a/3rdparty/pybind11/docs/upgrade.rst b/3rdparty/pybind11/docs/upgrade.rst index 3f569739..87bcebee 100644 --- a/3rdparty/pybind11/docs/upgrade.rst +++ b/3rdparty/pybind11/docs/upgrade.rst @@ -8,6 +8,114 @@ to a new version. But it goes into more detail. This includes things like deprecated APIs and their replacements, build system changes, general code modernization and other useful information. +.. _upgrade-guide-2.6: + +v2.6 +==== + +Usage of the ``PYBIND11_OVERLOAD*`` macros and ``get_overload`` function should +be replaced by ``PYBIND11_OVERRIDE*`` and ``get_override``. In the future, the +old macros may be deprecated and removed. + +``py::module`` has been renamed ``py::module_``, but a backward compatible +typedef has been included. This change was to avoid a language change in C++20 +that requires unqualified ``module`` not be placed at the start of a logical +line. Qualified usage is unaffected and the typedef will remain unless the +C++ language rules change again. + +The public constructors of ``py::module_`` have been deprecated. Use +``PYBIND11_MODULE`` or ``module_::create_extension_module`` instead. + +An error is now thrown when ``__init__`` is forgotten on subclasses. This was +incorrect before, but was not checked. Add a call to ``__init__`` if it is +missing. + +A ``py::type_error`` is now thrown when casting to a subclass (like +``py::bytes`` from ``py::object``) if the conversion is not valid. Make a valid +conversion instead. + +The undocumented ``h.get_type()`` method has been deprecated and replaced by +``py::type::of(h)``. + +Enums now have a ``__str__`` method pre-defined; if you want to override it, +the simplest fix is to add the new ``py::prepend()`` tag when defining +``"__str__"``. + +If ``__eq__`` defined but not ``__hash__``, ``__hash__`` is now set to +``None``, as in normal CPython. You should add ``__hash__`` if you intended the +class to be hashable, possibly using the new ``py::hash`` shortcut. + +The constructors for ``py::array`` now always take signed integers for size, +for consistency. This may lead to compiler warnings on some systems. Cast to +``py::ssize_t`` instead of ``std::size_t``. + +The ``tools/clang`` submodule and ``tools/mkdoc.py`` have been moved to a +standalone package, `pybind11-mkdoc`_. If you were using those tools, please +use them via a pip install from the new location. + +The ``pybind11`` package on PyPI no longer fills the wheel "headers" slot - if +you were using the headers from this slot, they are available by requesting the +``global`` extra, that is, ``pip install "pybind11[global]"``. (Most users will +be unaffected, as the ``pybind11/include`` location is reported by ``python -m +pybind11 --includes`` and ``pybind11.get_include()`` is still correct and has +not changed since 2.5). + +.. _pybind11-mkdoc: https://github.com/pybind/pybind11-mkdoc + +CMake support: +-------------- + +The minimum required version of CMake is now 3.4. Several details of the CMake +support have been deprecated; warnings will be shown if you need to change +something. The changes are: + +* ``PYBIND11_CPP_STANDARD=<platform-flag>`` is deprecated, please use + ``CMAKE_CXX_STANDARD=<number>`` instead, or any other valid CMake CXX or CUDA + standard selection method, like ``target_compile_features``. + +* If you do not request a standard, pybind11 targets will compile with the + compiler default, but not less than C++11, instead of forcing C++14 always. + If you depend on the old behavior, please use ``set(CMAKE_CXX_STANDARD 14 CACHE STRING "")`` + instead. + +* Direct ``pybind11::module`` usage should always be accompanied by at least + ``set(CMAKE_CXX_VISIBILITY_PRESET hidden)`` or similar - it used to try to + manually force this compiler flag (but not correctly on all compilers or with + CUDA). + +* ``pybind11_add_module``'s ``SYSTEM`` argument is deprecated and does nothing; + linking now behaves like other imported libraries consistently in both + config and submodule mode, and behaves like a ``SYSTEM`` library by + default. + +* If ``PYTHON_EXECUTABLE`` is not set, virtual environments (``venv``, + ``virtualenv``, and ``conda``) are prioritized over the standard search + (similar to the new FindPython mode). + +In addition, the following changes may be of interest: + +* ``CMAKE_INTERPROCEDURAL_OPTIMIZATION`` will be respected by + ``pybind11_add_module`` if set instead of linking to ``pybind11::lto`` or + ``pybind11::thin_lto``. + +* Using ``find_package(Python COMPONENTS Interpreter Development)`` before + pybind11 will cause pybind11 to use the new Python mechanisms instead of its + own custom search, based on a patched version of classic ``FindPythonInterp`` + / ``FindPythonLibs``. In the future, this may become the default. A recent + (3.15+ or 3.18.2+) version of CMake is recommended. + + + +v2.5 +==== + +The Python package now includes the headers as data in the package itself, as +well as in the "headers" wheel slot. ``pybind11 --includes`` and +``pybind11.get_include()`` report the new location, which is always correct +regardless of how pybind11 was installed, making the old ``user=`` argument +meaningless. If you are not using the function to get the location already, you +are encouraged to switch to the package location. + v2.2 ==== |