309 lines
13 KiB
ReStructuredText
309 lines
13 KiB
ReStructuredText
Frequently asked questions
|
||
##########################
|
||
|
||
"ImportError: dynamic module does not define init function"
|
||
===========================================================
|
||
|
||
1. Make sure that the name specified in PYBIND11_MODULE is identical to the
|
||
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 that does not match what you compiled with.
|
||
|
||
"Symbol not found: ``__Py_ZeroStruct`` / ``_PyInstanceMethod_Type``"
|
||
========================================================================
|
||
|
||
See the first answer.
|
||
|
||
"SystemError: dynamic module not initialized properly"
|
||
======================================================
|
||
|
||
See the first answer.
|
||
|
||
The Python interpreter immediately crashes when importing my module
|
||
===================================================================
|
||
|
||
See the first answer.
|
||
|
||
.. _faq_reference_arguments:
|
||
|
||
Limitations involving reference arguments
|
||
=========================================
|
||
|
||
In C++, it's fairly common to pass arguments using mutable references or
|
||
mutable pointers, which allows both read and write access to the value
|
||
supplied by the caller. This is sometimes done for efficiency reasons, or to
|
||
realize functions that have multiple return values. Here are two very basic
|
||
examples:
|
||
|
||
.. code-block:: cpp
|
||
|
||
void increment(int &i) { i++; }
|
||
void increment_ptr(int *i) { (*i)++; }
|
||
|
||
In Python, all arguments are passed by reference, so there is no general
|
||
issue in binding such code from Python.
|
||
|
||
However, certain basic Python types (like ``str``, ``int``, ``bool``,
|
||
``float``, etc.) are **immutable**. This means that the following attempt
|
||
to port the function to Python doesn't have the same effect on the value
|
||
provided by the caller -- in fact, it does nothing at all.
|
||
|
||
.. code-block:: python
|
||
|
||
def increment(i):
|
||
i += 1 # nope..
|
||
|
||
pybind11 is also affected by such language-level conventions, which means that
|
||
binding ``increment`` or ``increment_ptr`` will also create Python functions
|
||
that don't modify their arguments.
|
||
|
||
Although inconvenient, one workaround is to encapsulate the immutable types in
|
||
a custom type that does allow modifications.
|
||
|
||
An other alternative involves binding a small wrapper lambda function that
|
||
returns a tuple with all output arguments (see the remainder of the
|
||
documentation for examples on binding lambda functions). An example:
|
||
|
||
.. code-block:: cpp
|
||
|
||
int foo(int &i) { i++; return 123; }
|
||
|
||
and the binding code
|
||
|
||
.. code-block:: cpp
|
||
|
||
m.def("foo", [](int i) { int rv = foo(i); return std::make_tuple(rv, i); });
|
||
|
||
|
||
How can I reduce the build time?
|
||
================================
|
||
|
||
It's good practice to split binding code over multiple files, as in the
|
||
following example:
|
||
|
||
:file:`example.cpp`:
|
||
|
||
.. code-block:: cpp
|
||
|
||
void init_ex1(py::module_ &);
|
||
void init_ex2(py::module_ &);
|
||
/* ... */
|
||
|
||
PYBIND11_MODULE(example, m) {
|
||
init_ex1(m);
|
||
init_ex2(m);
|
||
/* ... */
|
||
}
|
||
|
||
:file:`ex1.cpp`:
|
||
|
||
.. code-block:: cpp
|
||
|
||
void init_ex1(py::module_ &m) {
|
||
m.def("add", [](int a, int b) { return a + b; });
|
||
}
|
||
|
||
:file:`ex2.cpp`:
|
||
|
||
.. code-block:: cpp
|
||
|
||
void init_ex2(py::module_ &m) {
|
||
m.def("sub", [](int a, int b) { return a - b; });
|
||
}
|
||
|
||
:command:`python`:
|
||
|
||
.. code-block:: pycon
|
||
|
||
>>> import example
|
||
>>> example.add(1, 2)
|
||
3
|
||
>>> example.sub(1, 1)
|
||
0
|
||
|
||
As shown above, the various ``init_ex`` functions should be contained in
|
||
separate files that can be compiled independently from one another, and then
|
||
linked together into the same final shared object. Following this approach
|
||
will:
|
||
|
||
1. reduce memory requirements per compilation unit.
|
||
|
||
2. enable parallel builds (if desired).
|
||
|
||
3. allow for faster incremental builds. For instance, when a single class
|
||
definition is changed, only a subset of the binding code will generally need
|
||
to be recompiled.
|
||
|
||
"recursive template instantiation exceeded maximum depth of 256"
|
||
================================================================
|
||
|
||
If you receive an error about excessive recursive template evaluation, try
|
||
specifying a larger value, e.g. ``-ftemplate-depth=1024`` on GCC/Clang. The
|
||
culprit is generally the generation of function signatures at compile time
|
||
using C++14 template metaprogramming.
|
||
|
||
.. _`faq:hidden_visibility`:
|
||
|
||
"'SomeClass' declared with greater visibility than the type of its field 'SomeClass::member' [-Wattributes]"
|
||
============================================================================================================
|
||
|
||
This error typically indicates that you are compiling without the required
|
||
``-fvisibility`` flag. pybind11 code internally forces hidden visibility on
|
||
all internal code, but if non-hidden (and thus *exported*) code attempts to
|
||
include a pybind type (for example, ``py::object`` or ``py::list``) you can run
|
||
into this warning.
|
||
|
||
To avoid it, make sure you are specifying ``-fvisibility=hidden`` when
|
||
compiling pybind code.
|
||
|
||
As to why ``-fvisibility=hidden`` is necessary, because pybind modules could
|
||
have been compiled under different versions of pybind itself, it is also
|
||
important that the symbols defined in one module do not clash with the
|
||
potentially-incompatible symbols defined in another. While Python extension
|
||
modules are usually loaded with localized symbols (under POSIX systems
|
||
typically using ``dlopen`` with the ``RTLD_LOCAL`` flag), this Python default
|
||
can be changed, but even if it isn't it is not always enough to guarantee
|
||
complete independence of the symbols involved when not using
|
||
``-fvisibility=hidden``.
|
||
|
||
Additionally, ``-fvisibility=hidden`` can deliver considerably binary size
|
||
savings. (See the following section for more details.)
|
||
|
||
|
||
.. _`faq:symhidden`:
|
||
|
||
How can I create smaller binaries?
|
||
==================================
|
||
|
||
To do its job, pybind11 extensively relies on a programming technique known as
|
||
*template metaprogramming*, which is a way of performing computation at compile
|
||
time using type information. Template metaprogramming usually instantiates code
|
||
involving significant numbers of deeply nested types that are either completely
|
||
removed or reduced to just a few instructions during the compiler's optimization
|
||
phase. However, due to the nested nature of these types, the resulting symbol
|
||
names in the compiled extension library can be extremely long. For instance,
|
||
the included test suite contains the following symbol:
|
||
|
||
.. only:: html
|
||
|
||
.. code-block:: none
|
||
|
||
__ZN8pybind1112cpp_functionC1Iv8Example2JRNSt3__16vectorINS3_12basic_stringIwNS3_11char_traitsIwEENS3_9allocatorIwEEEENS8_ISA_EEEEEJNS_4nameENS_7siblingENS_9is_methodEA28_cEEEMT0_FT_DpT1_EDpRKT2_
|
||
|
||
.. only:: not html
|
||
|
||
.. code-block:: cpp
|
||
|
||
__ZN8pybind1112cpp_functionC1Iv8Example2JRNSt3__16vectorINS3_12basic_stringIwNS3_11char_traitsIwEENS3_9allocatorIwEEEENS8_ISA_EEEEEJNS_4nameENS_7siblingENS_9is_methodEA28_cEEEMT0_FT_DpT1_EDpRKT2_
|
||
|
||
which is the mangled form of the following function type:
|
||
|
||
.. code-block:: cpp
|
||
|
||
pybind11::cpp_function::cpp_function<void, Example2, std::__1::vector<std::__1::basic_string<wchar_t, std::__1::char_traits<wchar_t>, std::__1::allocator<wchar_t> >, std::__1::allocator<std::__1::basic_string<wchar_t, std::__1::char_traits<wchar_t>, std::__1::allocator<wchar_t> > > >&, pybind11::name, pybind11::sibling, pybind11::is_method, char [28]>(void (Example2::*)(std::__1::vector<std::__1::basic_string<wchar_t, std::__1::char_traits<wchar_t>, std::__1::allocator<wchar_t> >, std::__1::allocator<std::__1::basic_string<wchar_t, std::__1::char_traits<wchar_t>, std::__1::allocator<wchar_t> > > >&), pybind11::name const&, pybind11::sibling const&, pybind11::is_method const&, char const (&) [28])
|
||
|
||
The memory needed to store just the mangled name of this function (196 bytes)
|
||
is larger than the actual piece of code (111 bytes) it represents! On the other
|
||
hand, it's silly to even give this function a name -- after all, it's just a
|
||
tiny cog in a bigger piece of machinery that is not exposed to the outside
|
||
world. So we'll generally only want to export symbols for those functions which
|
||
are actually called from the outside.
|
||
|
||
This can be achieved by specifying the parameter ``-fvisibility=hidden`` to GCC
|
||
and Clang, which sets the default symbol visibility to *hidden*, which has a
|
||
tremendous impact on the final binary size of the resulting extension library.
|
||
(On Visual Studio, symbols are already hidden by default, so nothing needs to
|
||
be done there.)
|
||
|
||
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.
|
||
|
||
How can I properly handle Ctrl-C in long-running functions?
|
||
===========================================================
|
||
|
||
Ctrl-C is received by the Python interpreter, and holds it until the GIL
|
||
is released, so a long-running function won't be interrupted.
|
||
|
||
To interrupt from inside your function, you can use the ``PyErr_CheckSignals()``
|
||
function, that will tell if a signal has been raised on the Python side. This
|
||
function merely checks a flag, so its impact is negligible. When a signal has
|
||
been received, you must either explicitly interrupt execution by throwing
|
||
``py::error_already_set`` (which will propagate the existing
|
||
``KeyboardInterrupt``), or clear the error (which you usually will not want):
|
||
|
||
.. code-block:: cpp
|
||
|
||
PYBIND11_MODULE(example, m)
|
||
{
|
||
m.def("long running_func", []()
|
||
{
|
||
for (;;) {
|
||
if (PyErr_CheckSignals() != 0)
|
||
throw py::error_already_set();
|
||
// Long running iteration
|
||
}
|
||
});
|
||
}
|
||
|
||
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 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.
|
||
|
||
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. If FindPythonLibs/Interp are not available
|
||
(CMake 3.27+), then this will be ignored and FindPython will be used.
|
||
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?
|
||
=========================
|
||
|
||
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}
|
||
}
|