diff options
Diffstat (limited to 'ext/pybind11/docs')
| -rw-r--r-- | ext/pybind11/docs/advanced/cast/chrono.rst | 2 | ||||
| -rw-r--r-- | ext/pybind11/docs/advanced/cast/eigen.rst | 18 | ||||
| -rw-r--r-- | ext/pybind11/docs/advanced/cast/overview.rst | 2 | ||||
| -rw-r--r-- | ext/pybind11/docs/advanced/cast/stl.rst | 5 | ||||
| -rw-r--r-- | ext/pybind11/docs/advanced/cast/strings.rst | 4 | ||||
| -rw-r--r-- | ext/pybind11/docs/advanced/classes.rst | 165 | ||||
| -rw-r--r-- | ext/pybind11/docs/advanced/exceptions.rst | 80 | ||||
| -rw-r--r-- | ext/pybind11/docs/advanced/functions.rst | 15 | ||||
| -rw-r--r-- | ext/pybind11/docs/advanced/misc.rst | 50 | ||||
| -rw-r--r-- | ext/pybind11/docs/advanced/pycpp/numpy.rst | 26 | ||||
| -rw-r--r-- | ext/pybind11/docs/changelog.rst | 300 | ||||
| -rw-r--r-- | ext/pybind11/docs/classes.rst | 42 | ||||
| -rw-r--r-- | ext/pybind11/docs/compiling.rst | 18 | ||||
| -rw-r--r-- | ext/pybind11/docs/conf.py | 4 | ||||
| -rw-r--r-- | ext/pybind11/docs/faq.rst | 96 | ||||
| -rw-r--r-- | ext/pybind11/docs/intro.rst | 8 | ||||
| -rw-r--r-- | ext/pybind11/docs/reference.rst | 17 |
17 files changed, 708 insertions, 144 deletions
diff --git a/ext/pybind11/docs/advanced/cast/chrono.rst b/ext/pybind11/docs/advanced/cast/chrono.rst index 8c6b3d7e5..fbd46057a 100644 --- a/ext/pybind11/docs/advanced/cast/chrono.rst +++ b/ext/pybind11/docs/advanced/cast/chrono.rst @@ -59,7 +59,7 @@ Provided conversions .. rubric:: Python to C++ -- ``datetime.datetime`` → ``std::chrono::system_clock::time_point`` +- ``datetime.datetime`` or ``datetime.date`` or ``datetime.time`` → ``std::chrono::system_clock::time_point`` Date/time objects are converted into system clock timepoints. Any timezone information is ignored and the type is treated as a naive object. diff --git a/ext/pybind11/docs/advanced/cast/eigen.rst b/ext/pybind11/docs/advanced/cast/eigen.rst index acdb51de6..59ba08c3c 100644 --- a/ext/pybind11/docs/advanced/cast/eigen.rst +++ b/ext/pybind11/docs/advanced/cast/eigen.rst @@ -37,11 +37,11 @@ that maps into the source ``numpy.ndarray`` data: this requires both that the data types are the same (e.g. ``dtype='float64'`` and ``MatrixType::Scalar`` is ``double``); and that the storage is layout compatible. The latter limitation is discussed in detail in the section below, and requires careful -consideration: by default, numpy matrices and eigen matrices are *not* storage +consideration: by default, numpy matrices and Eigen matrices are *not* storage compatible. If the numpy matrix cannot be used as is (either because its types differ, e.g. -passing an array of integers to an Eigen paramater requiring doubles, or +passing an array of integers to an Eigen parameter requiring doubles, or because the storage is incompatible), pybind11 makes a temporary copy and passes the copy instead. @@ -89,7 +89,7 @@ as dictated by the binding function's return value policy (see the documentation on :ref:`return_value_policies` for full details). That means, without an explicit return value policy, lvalue references will be copied and pointers will be managed by pybind11. In order to avoid copying, you should -explictly specify an appropriate return value policy, as in the following +explicitly specify an appropriate return value policy, as in the following example: .. code-block:: cpp @@ -226,7 +226,7 @@ order. Failing rather than copying =========================== -The default behaviour when binding ``Eigen::Ref<const MatrixType>`` eigen +The default behaviour when binding ``Eigen::Ref<const MatrixType>`` Eigen references is to copy matrix values when passed a numpy array that does not conform to the element type of ``MatrixType`` or does not have a compatible stride layout. If you want to explicitly avoid copying in such a case, you @@ -275,7 +275,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 -contast, has comparable 2-dimensional 1xN and Nx1 arrays, but *also* has +contrast, has comparable 2-dimensional 1xN and Nx1 arrays, but *also* has 1-dimensional arrays of size N. When passing a 2-dimensional 1xN or Nx1 array to Eigen, the Eigen type must @@ -287,15 +287,15 @@ On the other hand, pybind11 allows you to pass 1-dimensional arrays of length N as Eigen parameters. If the Eigen type can hold a column vector of length N it will be passed as such a column vector. If not, but the Eigen type constraints will accept a row vector, it will be passed as a row vector. (The column -vector takes precendence when both are supported, for example, when passing a +vector takes precedence when both are supported, for example, when passing a 1D numpy array to a MatrixXd argument). Note that the type need not be -expicitly a vector: it is permitted to pass a 1D numpy array of size 5 to an +explicitly a vector: it is permitted to pass a 1D numpy array of size 5 to an Eigen ``Matrix<double, Dynamic, 5>``: you would end up with a 1x5 Eigen matrix. Passing the same to an ``Eigen::MatrixXd`` would result in a 5x1 Eigen matrix. -When returning an eigen vector to numpy, the conversion is ambiguous: a row +When returning an Eigen vector to numpy, the conversion is ambiguous: a row vector of length 4 could be returned as either a 1D array of length 4, or as a -2D array of size 1x4. When encoutering such a situation, pybind11 compromises +2D array of size 1x4. When encountering such a situation, pybind11 compromises by considering the returned Eigen type: if it is a compile-time vector--that is, the type has either the number of rows or columns set to 1 at compile time--pybind11 converts to a 1D numpy array when returning the value. For diff --git a/ext/pybind11/docs/advanced/cast/overview.rst b/ext/pybind11/docs/advanced/cast/overview.rst index 2ac7d3009..b0e32a52f 100644 --- a/ext/pybind11/docs/advanced/cast/overview.rst +++ b/ext/pybind11/docs/advanced/cast/overview.rst @@ -131,6 +131,8 @@ as arguments and return values, refer to the section on binding :ref:`classes`. +------------------------------------+---------------------------+-------------------------------+ | ``std::vector<T>`` | STL dynamic array | :file:`pybind11/stl.h` | +------------------------------------+---------------------------+-------------------------------+ +| ``std::deque<T>`` | STL double-ended queue | :file:`pybind11/stl.h` | ++------------------------------------+---------------------------+-------------------------------+ | ``std::valarray<T>`` | STL value array | :file:`pybind11/stl.h` | +------------------------------------+---------------------------+-------------------------------+ | ``std::list<T>`` | STL linked list | :file:`pybind11/stl.h` | diff --git a/ext/pybind11/docs/advanced/cast/stl.rst b/ext/pybind11/docs/advanced/cast/stl.rst index 3f30c0290..e48409f02 100644 --- a/ext/pybind11/docs/advanced/cast/stl.rst +++ b/ext/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::list<>``/``std::array<>``, +between ``std::vector<>``/``std::deque<>``/``std::list<>``/``std::array<>``, ``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<>`` @@ -175,9 +175,6 @@ in Python, and to define a set of available operations, e.g.: }, py::keep_alive<0, 1>()) /* Keep vector alive while iterator is used */ // .... -Please take a look at the :ref:`macro_notes` before using the -``PYBIND11_MAKE_OPAQUE`` macro. - .. seealso:: The file :file:`tests/test_opaque_types.cpp` contains a complete diff --git a/ext/pybind11/docs/advanced/cast/strings.rst b/ext/pybind11/docs/advanced/cast/strings.rst index 2cdbade3a..e25701eca 100644 --- a/ext/pybind11/docs/advanced/cast/strings.rst +++ b/ext/pybind11/docs/advanced/cast/strings.rst @@ -58,7 +58,9 @@ Passing bytes to C++ -------------------- A Python ``bytes`` object will be passed to C++ functions that accept -``std::string`` or ``char*`` *without* conversion. +``std::string`` or ``char*`` *without* conversion. On Python 3, in order to +make a function *only* accept ``bytes`` (and not ``str``), declare it as taking +a ``py::bytes`` argument. Returning C++ strings to Python diff --git a/ext/pybind11/docs/advanced/classes.rst b/ext/pybind11/docs/advanced/classes.rst index 93deeec62..ae5907dee 100644 --- a/ext/pybind11/docs/advanced/classes.rst +++ b/ext/pybind11/docs/advanced/classes.rst @@ -46,11 +46,10 @@ Normally, the binding code for these classes would look as follows: .. code-block:: cpp PYBIND11_MODULE(example, m) { - py::class_<Animal> animal(m, "Animal"); - animal + py::class_<Animal>(m, "Animal") .def("go", &Animal::go); - py::class_<Dog>(m, "Dog", animal) + py::class_<Dog, Animal>(m, "Dog") .def(py::init<>()); m.def("call_go", &call_go); @@ -81,10 +80,10 @@ helper class that is defined as follows: } }; -The macro :func:`PYBIND11_OVERLOAD_PURE` should be used for pure virtual -functions, and :func:`PYBIND11_OVERLOAD` should be used for functions which have -a default implementation. There are also two alternate macros -:func:`PYBIND11_OVERLOAD_PURE_NAME` and :func:`PYBIND11_OVERLOAD_NAME` which +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 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 @@ -93,15 +92,14 @@ function have different names, e.g. ``operator()`` vs ``__call__``. The binding code also needs a few minor adaptations (highlighted): .. code-block:: cpp - :emphasize-lines: 2,4,5 + :emphasize-lines: 2,3 PYBIND11_MODULE(example, m) { - py::class_<Animal, PyAnimal /* <--- trampoline*/> animal(m, "Animal"); - animal + py::class_<Animal, PyAnimal /* <--- trampoline*/>(m, "Animal") .def(py::init<>()) .def("go", &Animal::go); - py::class_<Dog>(m, "Dog", animal) + py::class_<Dog, Animal>(m, "Dog") .def(py::init<>()); m.def("call_go", &call_go); @@ -116,11 +114,11 @@ define a constructor as usual. Bindings should be made against the actual class, not the trampoline helper class. .. code-block:: cpp + :emphasize-lines: 3 - py::class_<Animal, PyAnimal /* <--- trampoline*/> animal(m, "Animal"); - animal - .def(py::init<>()) - .def("go", &PyAnimal::go); /* <--- THIS IS WRONG, use &Animal::go */ + py::class_<Animal, PyAnimal /* <--- trampoline*/>(m, "Animal"); + .def(py::init<>()) + .def("go", &PyAnimal::go); /* <--- THIS IS WRONG, use &Animal::go */ Note, however, that the above is sufficient for allowing python classes to extend ``Animal``, but not ``Dog``: see :ref:`virtual_and_inheritance` for the @@ -155,9 +153,9 @@ Here is an example: .. code-block:: python - class Dachschund(Dog): + class Dachshund(Dog): def __init__(self, name): - Dog.__init__(self) # Without this, undefind behavior may occur if the C++ portions are referenced. + Dog.__init__(self) # Without this, undefined behavior may occur if the C++ portions are referenced. self.name = name def bark(self): return "yap!" @@ -241,7 +239,7 @@ override the ``name()`` method): class PyDog : public Dog { public: using Dog::Dog; // Inherit constructors - std::string go(int n_times) override { PYBIND11_OVERLOAD_PURE(std::string, Dog, go, n_times); } + 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, ); } }; @@ -327,6 +325,10 @@ can now create a python class that inherits from ``Dog``: Extended trampoline class functionality ======================================= +.. _extended_class_functionality_forced_trampoline: + +Forced trampoline class initialisation +-------------------------------------- The trampoline classes described in the previous sections are, by default, only initialized when needed. More specifically, they are initialized when a python class actually inherits from a registered type (instead of merely creating an @@ -354,6 +356,45 @@ ensuring member initialization and (eventual) destruction. See the file :file:`tests/test_virtual_functions.cpp` for complete examples showing both normal and forced trampoline instantiation. +Different method signatures +--------------------------- +The macro's introduced in :ref:`overriding_virtuals` cover most of the standard +use cases when exposing C++ classes to Python. Sometimes it is hard or unwieldy +to create a direct one-on-one mapping between the arguments and method return +type. + +An example would be when the C++ signature contains output arguments using +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 +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 +something should be done with the ``value``. This can be made convenient on the +Python side by allowing the Python function to return ``None`` or an ``int``: + +.. code-block:: cpp + + 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. + 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. + } else { + return false; // Python returned none, return false. + } + } + return false; // Alternatively return MyClass::myMethod(value); + } + + .. _custom_constructors: Custom constructors @@ -621,6 +662,7 @@ to Python. .def(py::self *= float()) .def(float() * py::self) .def(py::self * float()) + .def(-py::self) .def("__repr__", &Vector2::toString); } @@ -760,7 +802,7 @@ document)---pybind11 will automatically find out which is which. The only requirement is that the first template argument is the type to be declared. It is also permitted to inherit multiply from exported C++ classes in Python, -as well as inheriting from multiple Python and/or pybind-exported classes. +as well as inheriting from multiple Python and/or pybind11-exported classes. There is one caveat regarding the implementation of this feature: @@ -781,7 +823,7 @@ are listed. Module-local class bindings =========================== -When creating a binding for a class, pybind by default makes that binding +When creating a binding for a class, pybind11 by default makes that binding "global" across modules. What this means is that a type defined in one module can be returned from any module resulting in the same Python type. For example, this allows the following: @@ -999,3 +1041,86 @@ described trampoline: requires a more explicit function binding in the form of ``.def("foo", static_cast<int (A::*)() const>(&Publicist::foo));`` where ``int (A::*)() const`` is the type of ``A::foo``. + +Custom automatic downcasters +============================ + +As explained in :ref:`inheritance`, pybind11 comes with built-in +understanding of the dynamic type of polymorphic objects in C++; that +is, returning a Pet to Python produces a Python object that knows it's +wrapping a Dog, if Pet has virtual methods and pybind11 knows about +Dog and this Pet is in fact a Dog. Sometimes, you might want to +provide this automatic downcasting behavior when creating bindings for +a class hierarchy that does not use standard C++ polymorphism, such as +LLVM [#f4]_. As long as there's some way to determine at runtime +whether a downcast is safe, you can proceed by specializing the +``pybind11::polymorphic_type_hook`` template: + +.. code-block:: cpp + + enum class PetKind { Cat, Dog, Zebra }; + struct Pet { // Not polymorphic: has no virtual methods + const PetKind kind; + int age = 0; + protected: + Pet(PetKind _kind) : kind(_kind) {} + }; + struct Dog : Pet { + Dog() : Pet(PetKind::Dog) {} + std::string sound = "woof!"; + std::string bark() const { return sound; } + }; + + namespace pybind11 { + template<> struct polymorphic_type_hook<Pet> { + static const void *get(const Pet *src, const std::type_info*& type) { + // note that src may be nullptr + if (src && src->kind == PetKind::Dog) { + type = &typeid(Dog); + return static_cast<const Dog*>(src); + } + return src; + } + }; + } // namespace pybind11 + +When pybind11 wants to convert a C++ pointer of type ``Base*`` to a +Python object, it calls ``polymorphic_type_hook<Base>::get()`` to +determine if a downcast is possible. The ``get()`` function should use +whatever runtime information is available to determine if its ``src`` +parameter is in fact an instance of some class ``Derived`` that +inherits from ``Base``. If it finds such a ``Derived``, it sets ``type += &typeid(Derived)`` and returns a pointer to the ``Derived`` object +that contains ``src``. Otherwise, it just returns ``src``, leaving +``type`` at its default value of nullptr. If you set ``type`` to a +type that pybind11 doesn't know about, no downcasting will occur, and +the original ``src`` pointer will be used with its static type +``Base*``. + +It is critical that the returned pointer and ``type`` argument of +``get()`` agree with each other: if ``type`` is set to something +non-null, the returned pointer must point to the start of an object +whose type is ``type``. If the hierarchy being exposed uses only +single inheritance, a simple ``return src;`` will achieve this just +fine, but in the general case, you must cast ``src`` to the +appropriate derived-class pointer (e.g. using +``static_cast<Derived>(src)``) before allowing it to be returned as a +``void*``. + +.. [#f4] https://llvm.org/docs/HowToSetUpLLVMStyleRTTI.html + +.. note:: + + pybind11's standard support for downcasting objects whose types + have virtual methods is implemented using + ``polymorphic_type_hook`` too, using the standard C++ ability to + determine the most-derived type of a polymorphic object using + ``typeid()`` and to cast a base pointer to that most-derived type + (even if you don't know what it is) using ``dynamic_cast<void*>``. + +.. seealso:: + + The file :file:`tests/test_tagbased_polymorphic.cpp` contains a + 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. diff --git a/ext/pybind11/docs/advanced/exceptions.rst b/ext/pybind11/docs/advanced/exceptions.rst index 348337916..75ac24ae9 100644 --- a/ext/pybind11/docs/advanced/exceptions.rst +++ b/ext/pybind11/docs/advanced/exceptions.rst @@ -11,45 +11,45 @@ exceptions: .. tabularcolumns:: |p{0.5\textwidth}|p{0.45\textwidth}| -+--------------------------------------+------------------------------+ -| C++ exception type | Python exception type | -+======================================+==============================+ -| :class:`std::exception` | ``RuntimeError`` | -+--------------------------------------+------------------------------+ -| :class:`std::bad_alloc` | ``MemoryError`` | -+--------------------------------------+------------------------------+ -| :class:`std::domain_error` | ``ValueError`` | -+--------------------------------------+------------------------------+ -| :class:`std::invalid_argument` | ``ValueError`` | -+--------------------------------------+------------------------------+ -| :class:`std::length_error` | ``ValueError`` | -+--------------------------------------+------------------------------+ -| :class:`std::out_of_range` | ``ValueError`` | -+--------------------------------------+------------------------------+ -| :class:`std::range_error` | ``ValueError`` | -+--------------------------------------+------------------------------+ -| :class:`pybind11::stop_iteration` | ``StopIteration`` (used to | -| | implement custom iterators) | -+--------------------------------------+------------------------------+ -| :class:`pybind11::index_error` | ``IndexError`` (used to | -| | indicate out of bounds | -| | accesses in ``__getitem__``, | -| | ``__setitem__``, etc.) | -+--------------------------------------+------------------------------+ -| :class:`pybind11::value_error` | ``ValueError`` (used to | -| | indicate wrong value passed | -| | in ``container.remove(...)`` | -+--------------------------------------+------------------------------+ -| :class:`pybind11::key_error` | ``KeyError`` (used to | -| | indicate out of bounds | -| | accesses in ``__getitem__``, | -| | ``__setitem__`` in dict-like | -| | objects, etc.) | -+--------------------------------------+------------------------------+ -| :class:`pybind11::error_already_set` | Indicates that the Python | -| | exception flag has already | -| | been initialized | -+--------------------------------------+------------------------------+ ++--------------------------------------+--------------------------------------+ +| C++ exception type | Python exception type | ++======================================+======================================+ +| :class:`std::exception` | ``RuntimeError`` | ++--------------------------------------+--------------------------------------+ +| :class:`std::bad_alloc` | ``MemoryError`` | ++--------------------------------------+--------------------------------------+ +| :class:`std::domain_error` | ``ValueError`` | ++--------------------------------------+--------------------------------------+ +| :class:`std::invalid_argument` | ``ValueError`` | ++--------------------------------------+--------------------------------------+ +| :class:`std::length_error` | ``ValueError`` | ++--------------------------------------+--------------------------------------+ +| :class:`std::out_of_range` | ``IndexError`` | ++--------------------------------------+--------------------------------------+ +| :class:`std::range_error` | ``ValueError`` | ++--------------------------------------+--------------------------------------+ +| :class:`pybind11::stop_iteration` | ``StopIteration`` (used to implement | +| | custom iterators) | ++--------------------------------------+--------------------------------------+ +| :class:`pybind11::index_error` | ``IndexError`` (used to indicate out | +| | of bounds access in ``__getitem__``, | +| | ``__setitem__``, etc.) | ++--------------------------------------+--------------------------------------+ +| :class:`pybind11::value_error` | ``ValueError`` (used to indicate | +| | wrong value passed in | +| | ``container.remove(...)``) | ++--------------------------------------+--------------------------------------+ +| :class:`pybind11::key_error` | ``KeyError`` (used to indicate out | +| | of bounds access in ``__getitem__``, | +| | ``__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 @@ -138,5 +138,5 @@ section. error return without exception set``. Exceptions that you do not plan to handle should simply not be caught, or - may be explicity (re-)thrown to delegate it to the other, + may be explicitly (re-)thrown to delegate it to the other, previously-declared existing exception translators. diff --git a/ext/pybind11/docs/advanced/functions.rst b/ext/pybind11/docs/advanced/functions.rst index c7892b5d3..3e1a3ff0e 100644 --- a/ext/pybind11/docs/advanced/functions.rst +++ b/ext/pybind11/docs/advanced/functions.rst @@ -126,7 +126,7 @@ targeted arguments can be passed through the :class:`cpp_function` constructor: .. warning:: - Code with invalid return value policies might access unitialized memory or + Code with invalid return value policies might access uninitialized memory or free data structures multiple times, which can lead to hard-to-debug non-determinism and segmentation faults, hence it is worth spending the time to understand all the different options in the table above. @@ -438,7 +438,7 @@ To explicitly enable or disable this behaviour, using the py::class_<Cat>(m, "Cat").def(py::init<>()); m.def("bark", [](Dog *dog) -> std::string { if (dog) return "woof!"; /* Called with a Dog instance */ - else return "(no dog)"; /* Called with None, d == nullptr */ + else return "(no dog)"; /* Called with None, dog == nullptr */ }, py::arg("dog").none(true)); m.def("meow", [](Cat *cat) -> std::string { // Can't be called with None argument @@ -467,13 +467,22 @@ dog)"``, while attempting to call ``meow(None)`` will raise a ``TypeError``: The default behaviour when the tag is unspecified is to allow ``None``. +.. note:: + + Even when ``.none(true)`` is specified for an argument, ``None`` will be converted to a + ``nullptr`` *only* for custom and :ref:`opaque <opaque>` types. Pointers to built-in types + (``double *``, ``int *``, ...) and STL types (``std::vector<T> *``, ...; if ``pybind11/stl.h`` + is included) are copied when converted to C++ (see :doc:`/advanced/cast/overview`) and will + not allow ``None`` as argument. To pass optional argument of these copied types consider + using ``std::optional<T>`` + Overload resolution order ========================= When a function or method with multiple overloads is called from Python, pybind11 determines which overload to call in two passes. The first pass attempts to call each overload without allowing argument conversion (as if -every argument had been specified as ``py::arg().noconvert()`` as decribed +every argument had been specified as ``py::arg().noconvert()`` as described above). If no overload succeeds in the no-conversion first pass, a second pass is diff --git a/ext/pybind11/docs/advanced/misc.rst b/ext/pybind11/docs/advanced/misc.rst index 87481ba32..5b38ec759 100644 --- a/ext/pybind11/docs/advanced/misc.rst +++ b/ext/pybind11/docs/advanced/misc.rst @@ -7,13 +7,32 @@ General notes regarding convenience macros ========================================== pybind11 provides a few convenience macros such as -:func:`PYBIND11_MAKE_OPAQUE` and :func:`PYBIND11_DECLARE_HOLDER_TYPE`, and -``PYBIND11_OVERLOAD_*``. 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 such as ``PYBIND11_OVERLOAD(MyReturnValue<T1, -T2>, myFunc)``. In this case, the preprocessor assumes that the comma indicates -the beginning of the next parameter. Use a ``typedef`` to bind the template to -another name and use it in the macro to avoid this problem. +:func:`PYBIND11_DECLARE_HOLDER_TYPE` and ``PYBIND11_OVERLOAD_*``. 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) + +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, +there are two alternatives: you can use a type alias, or you can wrap the type +using the ``PYBIND11_TYPE`` macro: + +.. code-block:: cpp + + // Version 1: using a type alias + using ReturnType = MyReturnType<T1, T2>; + using ClassType = Class<T3, T4>; + PYBIND11_OVERLOAD(ReturnType, ClassType, func); + + // Version 2: using the PYBIND11_TYPE macro: + PYBIND11_OVERLOAD(PYBIND11_TYPE(MyReturnType<T1, T2>), + PYBIND11_TYPE(Class<T3, T4>), func) + +The ``PYBIND11_MAKE_OPAQUE`` macro does *not* require the above workarounds. .. _gil: @@ -137,7 +156,7 @@ Naturally, both methods will fail when there are cyclic dependencies. Note that pybind11 code compiled with hidden-by-default symbol visibility (e.g. via the command line flag ``-fvisibility=hidden`` on GCC/Clang), which is -required proper pybind11 functionality, can interfere with the ability to +required for proper pybind11 functionality, can interfere with the ability to access types defined in another extension module. Working around this requires manually exporting types that are accessed by multiple extension modules; pybind11 provides a macro to do just this: @@ -216,6 +235,21 @@ avoids this issue involves weak reference with a cleanup callback: // Create a weak reference with a cleanup callback and initially leak it (void) py::weakref(m.attr("BaseClass"), cleanup_callback).release(); +.. 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: + + .. code-block:: cpp + + auto atexit = py::module::import("atexit"); + atexit.attr("register")(py::cpp_function([]() { + // perform cleanup here -- this function is called with the GIL held + })); + + .. [#f7] https://docs.python.org/3/library/atexit.html + Generating documentation using Sphinx ===================================== diff --git a/ext/pybind11/docs/advanced/pycpp/numpy.rst b/ext/pybind11/docs/advanced/pycpp/numpy.rst index 98b0c25b9..458f99e97 100644 --- a/ext/pybind11/docs/advanced/pycpp/numpy.rst +++ b/ext/pybind11/docs/advanced/pycpp/numpy.rst @@ -41,7 +41,7 @@ completely avoid copy operations with Python expressions like py::format_descriptor<float>::format(), /* Python struct-style format descriptor */ 2, /* Number of dimensions */ { m.rows(), m.cols() }, /* Buffer dimensions */ - { sizeof(float) * m.rows(), /* Strides (in bytes) for each index */ + { sizeof(float) * m.cols(), /* Strides (in bytes) for each index */ sizeof(float) } ); }); @@ -261,7 +261,7 @@ simply using ``vectorize``). namespace py = pybind11; py::array_t<double> add_arrays(py::array_t<double> input1, py::array_t<double> input2) { - auto buf1 = input1.request(), buf2 = input2.request(); + py::buffer_info buf1 = input1.request(), buf2 = input2.request(); if (buf1.ndim != 1 || buf2.ndim != 1) throw std::runtime_error("Number of dimensions must be one"); @@ -272,7 +272,7 @@ simply using ``vectorize``). /* No pointer is passed, so NumPy will allocate the buffer */ auto result = py::array_t<double>(buf1.size); - auto buf3 = result.request(); + py::buffer_info buf3 = result.request(); double *ptr1 = (double *) buf1.ptr, *ptr2 = (double *) buf2.ptr, @@ -364,3 +364,23 @@ uses of ``py::array``: The file :file:`tests/test_numpy_array.cpp` contains additional examples demonstrating the use of this feature. + +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. + +.. code-block:: python + + a = # a NumPy array + b = a[0, ..., 0] + +The function ``py::ellipsis()`` function can be used to perform the same +operation on the C++ side: + +.. code-block:: cpp + + py::array a = /* A NumPy array */; + py::array b = a[py::make_tuple(0, py::ellipsis(), 0)]; diff --git a/ext/pybind11/docs/changelog.rst b/ext/pybind11/docs/changelog.rst index 1ca501d15..25c7808d2 100644 --- a/ext/pybind11/docs/changelog.rst +++ b/ext/pybind11/docs/changelog.rst @@ -6,10 +6,297 @@ Changelog Starting with version 1.8.0, pybind11 releases use a `semantic versioning <http://semver.org>`_ policy. -v2.3.0 (Not yet released) +v2.4.1 (Sep 20, 2019) ----------------------------------------------------- -* TBD +* Fixed a problem involving implicit conversion from enumerations to integers + on Python 3.8. `1780 <https://github.com/pybind/pybind11/pull/1780>`_. + +v2.4.0 (Sep 19, 2019) +----------------------------------------------------- + +* Try harder to keep pybind11-internal data structures separate when there + are potential ABI incompatibilities. Fixes crashes that occurred when loading + multiple pybind11 extensions that were e.g. compiled by GCC (libstdc++) + and Clang (libc++). + `#1588 <https://github.com/pybind/pybind11/pull/1588>`_ and + `c9f5a <https://github.com/pybind/pybind11/commit/c9f5a>`_. + +* Added support for ``__await__``, ``__aiter__``, and ``__anext__`` protocols. + `#1842 <https://github.com/pybind/pybind11/pull/1842>`_. + +* ``pybind11_add_module()``: don't strip symbols when compiling in + ``RelWithDebInfo`` mode. `#1980 + <https://github.com/pybind/pybind11/pull/1980>`_. + +* ``enum_``: Reproduce Python behavior when comparing against invalid values + (e.g. ``None``, strings, etc.). Add back support for ``__invert__()``. + `#1912 <https://github.com/pybind/pybind11/pull/1912>`_, + `#1907 <https://github.com/pybind/pybind11/pull/1907>`_. + +* List insertion operation for ``py::list``. + Added ``.empty()`` to all collection types. + Added ``py::set::contains()`` and ``py::dict::contains()``. + `#1887 <https://github.com/pybind/pybind11/pull/1887>`_, + `#1884 <https://github.com/pybind/pybind11/pull/1884>`_, + `#1888 <https://github.com/pybind/pybind11/pull/1888>`_. + +* ``py::details::overload_cast_impl`` is available in C++11 mode, can be used + like ``overload_cast`` with an additional set of parantheses. + `#1581 <https://github.com/pybind/pybind11/pull/1581>`_. + +* Fixed ``get_include()`` on Conda. + `#1877 <https://github.com/pybind/pybind11/pull/1877>`_. + +* ``stl_bind.h``: negative indexing support. + `#1882 <https://github.com/pybind/pybind11/pull/1882>`_. + +* Minor CMake fix to add MinGW compatibility. + `#1851 <https://github.com/pybind/pybind11/pull/1851>`_. + +* GIL-related fixes. + `#1836 <https://github.com/pybind/pybind11/pull/1836>`_, + `8b90b <https://github.com/pybind/pybind11/commit/8b90b>`_. + +* Other very minor/subtle fixes and improvements. + `#1329 <https://github.com/pybind/pybind11/pull/1329>`_, + `#1910 <https://github.com/pybind/pybind11/pull/1910>`_, + `#1863 <https://github.com/pybind/pybind11/pull/1863>`_, + `#1847 <https://github.com/pybind/pybind11/pull/1847>`_, + `#1890 <https://github.com/pybind/pybind11/pull/1890>`_, + `#1860 <https://github.com/pybind/pybind11/pull/1860>`_, + `#1848 <https://github.com/pybind/pybind11/pull/1848>`_, + `#1821 <https://github.com/pybind/pybind11/pull/1821>`_, + `#1837 <https://github.com/pybind/pybind11/pull/1837>`_, + `#1833 <https://github.com/pybind/pybind11/pull/1833>`_, + `#1748 <https://github.com/pybind/pybind11/pull/1748>`_, + `#1852 <https://github.com/pybind/pybind11/pull/1852>`_. + +v2.3.0 (June 11, 2019) +----------------------------------------------------- + +* Significantly reduced module binary size (10-20%) when compiled in C++11 mode + with GCC/Clang, or in any mode with MSVC. Function signatures are now always + precomputed at compile time (this was previously only available in C++14 mode + for non-MSVC compilers). + `#934 <https://github.com/pybind/pybind11/pull/934>`_. + +* Add basic support for tag-based static polymorphism, where classes + provide a method to returns the desired type of an instance. + `#1326 <https://github.com/pybind/pybind11/pull/1326>`_. + +* Python type wrappers (``py::handle``, ``py::object``, etc.) + now support map Python's number protocol onto C++ arithmetic + operators such as ``operator+``, ``operator/=``, etc. + `#1511 <https://github.com/pybind/pybind11/pull/1511>`_. + +* A number of improvements related to enumerations: + + 1. The ``enum_`` implementation was rewritten from scratch to reduce + code bloat. Rather than instantiating a full implementation for each + enumeration, most code is now contained in a generic base class. + `#1511 <https://github.com/pybind/pybind11/pull/1511>`_. + + 2. The ``value()`` method of ``py::enum_`` now accepts an optional + docstring that will be shown in the documentation of the associated + enumeration. `#1160 <https://github.com/pybind/pybind11/pull/1160>`_. + + 3. check for already existing enum value and throw an error if present. + `#1453 <https://github.com/pybind/pybind11/pull/1453>`_. + +* Support for over-aligned type allocation via C++17's aligned ``new`` + statement. `#1582 <https://github.com/pybind/pybind11/pull/1582>`_. + +* Added ``py::ellipsis()`` method for slicing of multidimensional NumPy arrays + `#1502 <https://github.com/pybind/pybind11/pull/1502>`_. + +* Numerous Improvements to the ``mkdoc.py`` script for extracting documentation + from C++ header files. + `#1788 <https://github.com/pybind/pybind11/pull/1788>`_. + +* ``pybind11_add_module()``: allow including Python as a ``SYSTEM`` include path. + `#1416 <https://github.com/pybind/pybind11/pull/1416>`_. + +* ``pybind11/stl.h`` does not convert strings to ``vector<string>`` anymore. + `#1258 <https://github.com/pybind/pybind11/issues/1258>`_. + +* Mark static methods as such to fix auto-generated Sphinx documentation. + `#1732 <https://github.com/pybind/pybind11/pull/1732>`_. + +* Re-throw forced unwind exceptions (e.g. during pthread termination). + `#1208 <https://github.com/pybind/pybind11/pull/1208>`_. + +* Added ``__contains__`` method to the bindings of maps (``std::map``, + ``std::unordered_map``). + `#1767 <https://github.com/pybind/pybind11/pull/1767>`_. + +* Improvements to ``gil_scoped_acquire``. + `#1211 <https://github.com/pybind/pybind11/pull/1211>`_. + +* Type caster support for ``std::deque<T>``. + `#1609 <https://github.com/pybind/pybind11/pull/1609>`_. + +* Support for ``std::unique_ptr`` holders, whose deleters differ between a base and derived + class. `#1353 <https://github.com/pybind/pybind11/pull/1353>`_. + +* Construction of STL array/vector-like data structures from + iterators. Added an ``extend()`` operation. + `#1709 <https://github.com/pybind/pybind11/pull/1709>`_, + +* CMake build system improvements for projects that include non-C++ + files (e.g. plain C, CUDA) in ``pybind11_add_module`` et al. + `#1678 <https://github.com/pybind/pybind11/pull/1678>`_. + +* Fixed asynchronous invocation and deallocation of Python functions + wrapped in ``std::function``. + `#1595 <https://github.com/pybind/pybind11/pull/1595>`_. + +* Fixes regarding return value policy propagation in STL type casters. + `#1603 <https://github.com/pybind/pybind11/pull/1603>`_. + +* Fixed scoped enum comparisons. + `#1571 <https://github.com/pybind/pybind11/pull/1571>`_. + +* Fixed iostream redirection for code that releases the GIL. + `#1368 <https://github.com/pybind/pybind11/pull/1368>`_, + +* A number of CI-related fixes. + `#1757 <https://github.com/pybind/pybind11/pull/1757>`_, + `#1744 <https://github.com/pybind/pybind11/pull/1744>`_, + `#1670 <https://github.com/pybind/pybind11/pull/1670>`_. + +v2.2.4 (September 11, 2018) +----------------------------------------------------- + +* Use new Python 3.7 Thread Specific Storage (TSS) implementation if available. + `#1454 <https://github.com/pybind/pybind11/pull/1454>`_, + `#1517 <https://github.com/pybind/pybind11/pull/1517>`_. + +* Fixes for newer MSVC versions and C++17 mode. + `#1347 <https://github.com/pybind/pybind11/pull/1347>`_, + `#1462 <https://github.com/pybind/pybind11/pull/1462>`_. + +* Propagate return value policies to type-specific casters + when casting STL containers. + `#1455 <https://github.com/pybind/pybind11/pull/1455>`_. + +* Allow ostream-redirection of more than 1024 characters. + `#1479 <https://github.com/pybind/pybind11/pull/1479>`_. + +* Set ``Py_DEBUG`` define when compiling against a debug Python build. + `#1438 <https://github.com/pybind/pybind11/pull/1438>`_. + +* Untangle integer logic in number type caster to work for custom + types that may only be castable to a restricted set of builtin types. + `#1442 <https://github.com/pybind/pybind11/pull/1442>`_. + +* CMake build system: Remember Python version in cache file. + `#1434 <https://github.com/pybind/pybind11/pull/1434>`_. + +* Fix for custom smart pointers: use ``std::addressof`` to obtain holder + address instead of ``operator&``. + `#1435 <https://github.com/pybind/pybind11/pull/1435>`_. + +* Properly report exceptions thrown during module initialization. + `#1362 <https://github.com/pybind/pybind11/pull/1362>`_. + +* Fixed a segmentation fault when creating empty-shaped NumPy array. + `#1371 <https://github.com/pybind/pybind11/pull/1371>`_. + +* The version of Intel C++ compiler must be >= 2017, and this is now checked by + the header files. `#1363 <https://github.com/pybind/pybind11/pull/1363>`_. + +* A few minor typo fixes and improvements to the test suite, and + patches that silence compiler warnings. + +* Vectors now support construction from generators, as well as ``extend()`` from a + list or generator. + `#1496 <https://github.com/pybind/pybind11/pull/1496>`_. + + +v2.2.3 (April 29, 2018) +----------------------------------------------------- + +* The pybind11 header location detection was replaced by a new implementation + that no longer depends on ``pip`` internals (the recently released ``pip`` + 10 has restricted access to this API). + `#1190 <https://github.com/pybind/pybind11/pull/1190>`_. + +* Small adjustment to an implementation detail to work around a compiler segmentation fault in Clang 3.3/3.4. + `#1350 <https://github.com/pybind/pybind11/pull/1350>`_. + +* The minimal supported version of the Intel compiler was >= 17.0 since + pybind11 v2.1. This check is now explicit, and a compile-time error is raised + if the compiler meet the requirement. + `#1363 <https://github.com/pybind/pybind11/pull/1363>`_. + +* Fixed an endianness-related fault in the test suite. + `#1287 <https://github.com/pybind/pybind11/pull/1287>`_. + +v2.2.2 (February 7, 2018) +----------------------------------------------------- + +* Fixed a segfault when combining embedded interpreter + shutdown/reinitialization with external loaded pybind11 modules. + `#1092 <https://github.com/pybind/pybind11/pull/1092>`_. + +* Eigen support: fixed a bug where Nx1/1xN numpy inputs couldn't be passed as + arguments to Eigen vectors (which for Eigen are simply compile-time fixed + Nx1/1xN matrices). + `#1106 <https://github.com/pybind/pybind11/pull/1106>`_. + +* Clarified to license by moving the licensing of contributions from + ``LICENSE`` into ``CONTRIBUTING.md``: the licensing of contributions is not + actually part of the software license as distributed. This isn't meant to be + a substantial change in the licensing of the project, but addresses concerns + that the clause made the license non-standard. + `#1109 <https://github.com/pybind/pybind11/issues/1109>`_. + +* Fixed a regression introduced in 2.1 that broke binding functions with lvalue + character literal arguments. + `#1128 <https://github.com/pybind/pybind11/pull/1128>`_. + +* MSVC: fix for compilation failures under /permissive-, and added the flag to + the appveyor test suite. + `#1155 <https://github.com/pybind/pybind11/pull/1155>`_. + +* Fixed ``__qualname__`` generation, and in turn, fixes how class names + (especially nested class names) are shown in generated docstrings. + `#1171 <https://github.com/pybind/pybind11/pull/1171>`_. + +* Updated the FAQ with a suggested project citation reference. + `#1189 <https://github.com/pybind/pybind11/pull/1189>`_. + +* Added fixes for deprecation warnings when compiled under C++17 with + ``-Wdeprecated`` turned on, and add ``-Wdeprecated`` to the test suite + compilation flags. + `#1191 <https://github.com/pybind/pybind11/pull/1191>`_. + +* Fixed outdated PyPI URLs in ``setup.py``. + `#1213 <https://github.com/pybind/pybind11/pull/1213>`_. + +* Fixed a refcount leak for arguments that end up in a ``py::args`` argument + for functions with both fixed positional and ``py::args`` arguments. + `#1216 <https://github.com/pybind/pybind11/pull/1216>`_. + +* Fixed a potential segfault resulting from possible premature destruction of + ``py::args``/``py::kwargs`` arguments with overloaded functions. + `#1223 <https://github.com/pybind/pybind11/pull/1223>`_. + +* Fixed ``del map[item]`` for a ``stl_bind.h`` bound stl map. + `#1229 <https://github.com/pybind/pybind11/pull/1229>`_. + +* Fixed a regression from v2.1.x where the aggregate initialization could + unintentionally end up at a constructor taking a templated + ``std::initializer_list<T>`` argument. + `#1249 <https://github.com/pybind/pybind11/pull/1249>`_. + +* Fixed an issue where calling a function with a keep_alive policy on the same + nurse/patient pair would cause the internal patient storage to needlessly + grow (unboundedly, if the nurse is long-lived). + `#1251 <https://github.com/pybind/pybind11/issues/1251>`_. + +* Various other minor fixes. v2.2.1 (September 14, 2017) ----------------------------------------------------- @@ -236,6 +523,9 @@ v2.2.0 (August 31, 2017) * Fixed overriding static properties in derived classes. `#784 <https://github.com/pybind/pybind11/pull/784>`_. +* Added support for write only properties. + `#1144 <https://github.com/pybind/pybind11/pull/1144>`_. + * Improved deduction of member functions of a derived class when its bases aren't registered with pybind11. `#855 <https://github.com/pybind/pybind11/pull/855>`_. @@ -503,7 +793,7 @@ Happy Christmas! being (notably dynamic attributes in custom types). `#527 <https://github.com/pybind/pybind11/pull/527>`_. -* Significant work on the documentation -- in particular, the monolitic +* Significant work on the documentation -- in particular, the monolithic ``advanced.rst`` file was restructured into a easier to read hierarchical organization. `#448 <https://github.com/pybind/pybind11/pull/448>`_. @@ -571,8 +861,8 @@ Happy Christmas! <https://github.com/pybind/pybind11/pull/527>`_. - 3. This version of pybind11 uses a redesigned mechnism for instantiating - trempoline classes that are used to override virtual methods from within + 3. This version of pybind11 uses a redesigned mechanism for instantiating + trampoline classes that are used to override virtual methods from within Python. This led to the following user-visible syntax change: instead of .. code-block:: cpp diff --git a/ext/pybind11/docs/classes.rst b/ext/pybind11/docs/classes.rst index ca2477e83..a63f6a196 100644 --- a/ext/pybind11/docs/classes.rst +++ b/ext/pybind11/docs/classes.rst @@ -155,6 +155,9 @@ the setter and getter functions: .def_property("name", &Pet::getName, &Pet::setName) // ... remainder ... +Write only properties can be defined by passing ``nullptr`` as the +input for the read function. + .. seealso:: Similar functions :func:`class_::def_readwrite_static`, @@ -225,8 +228,8 @@ just brings them on par. .. _inheritance: -Inheritance and automatic upcasting -=================================== +Inheritance and automatic downcasting +===================================== Suppose now that the example consists of two data structures with an inheritance relationship: @@ -295,7 +298,7 @@ inheritance relationship. This is reflected in Python: >>> p = example.pet_store() >>> type(p) # `Dog` instance behind `Pet` pointer - Pet # no pointer upcasting for regular non-polymorphic types + Pet # no pointer downcasting for regular non-polymorphic types >>> p.bark() AttributeError: 'Pet' object has no attribute 'bark' @@ -327,11 +330,11 @@ will automatically recognize this: >>> p = example.pet_store2() >>> type(p) - PolymorphicDog # automatically upcast + PolymorphicDog # automatically downcast >>> p.bark() u'woof!' -Given a pointer to a polymorphic base, pybind11 performs automatic upcasting +Given a pointer to a polymorphic base, pybind11 performs automatic downcasting to the actual derived type. Note that this goes beyond the usual situation in C++: we don't just get access to the virtual functions of the base, we get the concrete derived type including functions and attributes that the base type may @@ -419,6 +422,17 @@ on constness, the ``py::const_`` tag should be used: .def("foo_mutable", py::overload_cast<int, float>(&Widget::foo)) .def("foo_const", py::overload_cast<int, float>(&Widget::foo, py::const_)); +If you prefer the ``py::overload_cast`` syntax but have a C++11 compatible compiler only, +you can use ``py::detail::overload_cast_impl`` with an additional set of parentheses: + +.. code-block:: cpp + + template <typename... Args> + using overload_cast_ = pybind11::detail::overload_cast_impl<Args...>; + + py::class_<Pet>(m, "Pet") + .def("set", overload_cast_<int>()(&Pet::set), "Set the pet's age") + .def("set", overload_cast_<const std::string &>()(&Pet::set), "Set the pet's name"); .. [#cpp14] A compiler which supports the ``-std=c++14`` flag or Visual Studio 2015 Update 2 and newer. @@ -485,6 +499,24 @@ The entries defined by the enumeration type are exposed in the ``__members__`` p >>> Pet.Kind.__members__ {'Dog': Kind.Dog, 'Cat': Kind.Cat} +The ``name`` property returns the name of the enum value as a unicode string. + +.. note:: + + It is also possible to use ``str(enum)``, however these accomplish different + goals. The following shows how these two approaches differ. + + .. code-block:: pycon + + >>> p = Pet( "Lucy", Pet.Cat ) + >>> pet_type = p.type + >>> pet_type + Pet.Cat + >>> str(pet_type) + 'Pet.Cat' + >>> pet_type.name + 'Cat' + .. note:: When the special tag ``py::arithmetic()`` is specified to the ``enum_`` diff --git a/ext/pybind11/docs/compiling.rst b/ext/pybind11/docs/compiling.rst index b5d6ce948..c50c7d8af 100644 --- a/ext/pybind11/docs/compiling.rst +++ b/ext/pybind11/docs/compiling.rst @@ -59,7 +59,7 @@ function with the following signature: .. code-block:: cmake pybind11_add_module(<name> [MODULE | SHARED] [EXCLUDE_FROM_ALL] - [NO_EXTRAS] [THIN_LTO] source1 [source2 ...]) + [NO_EXTRAS] [SYSTEM] [THIN_LTO] 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,6 +86,10 @@ 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 @@ -145,6 +149,18 @@ See the `Config file`_ docstring for details of relevant CMake variables. find_package(pybind11 REQUIRED) pybind11_add_module(example example.cpp) +Note that ``find_package(pybind11)`` will only work correctly if pybind11 +has been correctly installed on the system, e. g. after downloading or cloning +the pybind11 repository : + +.. code-block:: bash + + cd pybind11 + mkdir build + cd build + cmake .. + make install + 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 diff --git a/ext/pybind11/docs/conf.py b/ext/pybind11/docs/conf.py index cd0e17eb7..5e9b9b2a4 100644 --- a/ext/pybind11/docs/conf.py +++ b/ext/pybind11/docs/conf.py @@ -61,9 +61,9 @@ author = 'Wenzel Jakob' # built documents. # # The short X.Y version. -version = '2.2' +version = '2.4' # The full version, including alpha/beta/rc tags. -release = '2.2.1' +release = '2.4.1' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. diff --git a/ext/pybind11/docs/faq.rst b/ext/pybind11/docs/faq.rst index 8f33eb014..93ccf10e5 100644 --- a/ext/pybind11/docs/faq.rst +++ b/ext/pybind11/docs/faq.rst @@ -4,9 +4,13 @@ Frequently asked questions "ImportError: dynamic module does not define init function" =========================================================== -You are likely using an incompatible version of Python (for instance, the -extension library was compiled against Python 2, while the interpreter is -running on top of some version of Python 3, or vice versa). +1. Make sure that the name specified in PYBIND11_MODULE is identical to the +filename of the extension library (without prefixes 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 +Python 2, while the interpreter is running on top of some version of Python +3, or vice versa). "Symbol not found: ``__Py_ZeroStruct`` / ``_PyInstanceMethod_Type``" ======================================================================== @@ -35,6 +39,8 @@ multiple versions of Python and it finds the wrong one, delete cmake -DPYTHON_EXECUTABLE:FILEPATH=<path-to-python-executable> . +.. _faq_reference_arguments: + Limitations involving reference arguments ========================================= @@ -116,7 +122,7 @@ following example: .. code-block:: cpp - void init_ex1(py::module &m) { + void init_ex2(py::module &m) { m.def("sub", [](int a, int b) { return a - b; }); } @@ -228,46 +234,64 @@ In addition to decreasing binary size, ``-fvisibility=hidden`` also avoids potential serious issues when loading multiple modules and is required for proper pybind operation. See the previous FAQ entry for more details. -Another aspect that can require a fair bit of code are function signature -descriptions. pybind11 automatically generates human-readable function -signatures for docstrings, e.g.: - -.. code-block:: none - - | __init__(...) - | __init__(*args, **kwargs) - | Overloaded function. - | - | 1. __init__(example.Example1) -> NoneType - | - | Docstring for overload #1 goes here - | - | 2. __init__(example.Example1, int) -> NoneType - | - | Docstring for overload #2 goes here - | - | 3. __init__(example.Example1, example.Example1) -> NoneType - | - | Docstring for overload #3 goes here - - -In C++11 mode, these are generated at run time using string concatenation, -which can amount to 10-20% of the size of the resulting binary. If you can, -enable C++14 language features (using ``-std=c++14`` for GCC/Clang), in which -case signatures are efficiently pre-generated at compile time. Unfortunately, -Visual Studio's C++14 support (``constexpr``) is not good enough as of April -2016, so it always uses the more expensive run-time approach. - -Working with ancient Visual Studio 2009 builds on Windows +Working with ancient Visual Studio 2008 builds on Windows ========================================================= The official Windows distributions of Python are compiled using truly ancient versions of Visual Studio that lack good C++11 support. Some users implicitly assume that it would be impossible to load a plugin built with Visual Studio 2015 into a Python distribution that was compiled using Visual -Studio 2009. However, no such issue exists: it's perfectly legitimate to +Studio 2008. However, no such issue exists: it's perfectly legitimate to interface DLLs that are built with different compilers and/or C libraries. Common gotchas to watch out for involve not ``free()``-ing memory region that that were ``malloc()``-ed in another shared library, using data structures with incompatible ABIs, and so on. pybind11 is very careful not to make these types of mistakes. + +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. + +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 + + find_package(PythonInterp) + find_package(PythonLibs) + find_package(pybind11) + +It will detect Python 2.7 and pybind11 will pick it as well. + +In contrast this code: + +.. code-block:: cmake + + find_package(pybind11) + 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. + +How to cite this project? +========================= + +We suggest the following BibTeX template to cite pybind11 in scientific +discourse: + +.. code-block:: bash + + @misc{pybind11, + author = {Wenzel Jakob and Jason Rhinelander and Dean Moldovan}, + year = {2017}, + note = {https://github.com/pybind/pybind11}, + title = {pybind11 -- Seamless operability between C++11 and Python} + } diff --git a/ext/pybind11/docs/intro.rst b/ext/pybind11/docs/intro.rst index 2149c18db..10e1799a1 100644 --- a/ext/pybind11/docs/intro.rst +++ b/ext/pybind11/docs/intro.rst @@ -41,7 +41,6 @@ The following core C++ features can be mapped to Python - Custom operators - Single and multiple inheritance - STL data structures -- Iterators and ranges - 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 @@ -77,9 +76,8 @@ In addition to the core functionality, pybind11 provides some extra goodies: of `PyRosetta`_, an enormous Boost.Python binding project, reported a binary size reduction of **5.4x** and compile time reduction by **5.8x**. -- When supported by the compiler, two new C++14 features (relaxed constexpr and - return value deduction) are used to precompute function signatures at compile - time, leading to smaller binaries. +- 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. @@ -92,4 +90,4 @@ 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 v15 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/ext/pybind11/docs/reference.rst b/ext/pybind11/docs/reference.rst index e41141bd9..a9fbe6001 100644 --- a/ext/pybind11/docs/reference.rst +++ b/ext/pybind11/docs/reference.rst @@ -80,12 +80,27 @@ Redirecting C++ streams .. doxygenfunction:: add_ostream_redirect -Python build-in functions +Python built-in functions ========================= .. doxygengroup:: python_builtins :members: +Inheritance +=========== + +See :doc:`/classes` and :doc:`/advanced/classes` for more detail. + +.. doxygendefine:: PYBIND11_OVERLOAD + +.. doxygendefine:: PYBIND11_OVERLOAD_PURE + +.. doxygendefine:: PYBIND11_OVERLOAD_NAME + +.. doxygendefine:: PYBIND11_OVERLOAD_PURE_NAME + +.. doxygenfunction:: get_overload + Exceptions ========== |