308 lines
9.0 KiB
ReStructuredText
308 lines
9.0 KiB
ReStructuredText
.. _basics:
|
|
|
|
First steps
|
|
###########
|
|
|
|
This sections demonstrates the basic features of pybind11. Before getting
|
|
started, make sure that development environment is set up to compile the
|
|
included set of test cases.
|
|
|
|
|
|
Compiling the test cases
|
|
========================
|
|
|
|
Linux/macOS
|
|
-----------
|
|
|
|
On Linux you'll need to install the **python-dev** or **python3-dev** packages as
|
|
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
|
|
|
|
.. code-block:: bash
|
|
|
|
mkdir build
|
|
cd build
|
|
cmake ..
|
|
make check -j 4
|
|
|
|
The last line will both compile and run the tests.
|
|
|
|
Windows
|
|
-------
|
|
|
|
On Windows, only **Visual Studio 2017** and newer are supported.
|
|
|
|
.. 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
|
|
|
|
mkdir build
|
|
cd build
|
|
cmake ..
|
|
cmake --build . --config Release --target check
|
|
|
|
This will create a Visual Studio project, compile and run the target, all from the
|
|
command line.
|
|
|
|
.. Note::
|
|
|
|
If all tests fail, make sure that the Python binary and the testcases are compiled
|
|
for the same processor type and bitness (i.e. either **i386** or **x86_64**). You
|
|
can specify **x86_64** as the target architecture for the generated Visual Studio
|
|
project using ``cmake -A x64 ..``.
|
|
|
|
.. seealso::
|
|
|
|
Advanced users who are already familiar with Boost.Python may want to skip
|
|
the tutorial and look at the test cases in the :file:`tests` directory,
|
|
which exercise all features of pybind11.
|
|
|
|
Header and namespace conventions
|
|
================================
|
|
|
|
For brevity, all code examples assume that the following two lines are present:
|
|
|
|
.. code-block:: cpp
|
|
|
|
#include <pybind11/pybind11.h>
|
|
|
|
namespace py = pybind11;
|
|
|
|
Some features may require additional headers, but those will be specified as needed.
|
|
|
|
.. _simple_example:
|
|
|
|
Creating bindings for a simple function
|
|
=======================================
|
|
|
|
Let's start by creating Python bindings for an extremely simple function, which
|
|
adds two numbers and returns their result:
|
|
|
|
.. code-block:: cpp
|
|
|
|
int add(int i, int j) {
|
|
return i + j;
|
|
}
|
|
|
|
For simplicity [#f1]_, we'll put both this function and the binding code into
|
|
a file named :file:`example.cpp` with the following contents:
|
|
|
|
.. code-block:: cpp
|
|
|
|
#include <pybind11/pybind11.h>
|
|
|
|
int add(int i, int j) {
|
|
return i + j;
|
|
}
|
|
|
|
PYBIND11_MODULE(example, m) {
|
|
m.doc() = "pybind11 example plugin"; // optional module docstring
|
|
|
|
m.def("add", &add, "A function that adds two numbers");
|
|
}
|
|
|
|
.. [#f1] In practice, implementation and binding code will generally be located
|
|
in separate files.
|
|
|
|
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`
|
|
generates binding code that exposes the ``add()`` function to Python.
|
|
|
|
.. note::
|
|
|
|
Notice how little code was needed to expose our function to Python: all
|
|
details regarding the function's parameters and return value were
|
|
automatically inferred using template metaprogramming. This overall
|
|
approach and the used syntax are borrowed from Boost.Python, though the
|
|
underlying implementation is very different.
|
|
|
|
pybind11 is a header-only library, hence it is not necessary to link against
|
|
any special libraries and there are no intermediate (magic) translation steps.
|
|
On Linux, the above example can be compiled using the following command:
|
|
|
|
.. code-block:: bash
|
|
|
|
$ c++ -O3 -Wall -shared -std=c++11 -fPIC $(python3 -m pybind11 --includes) example.cpp -o example$(python3-config --extension-suffix)
|
|
|
|
.. note::
|
|
|
|
If you used :ref:`include_as_a_submodule` to get the pybind11 source, then
|
|
use ``$(python3-config --includes) -Iextern/pybind11/include`` instead of
|
|
``$(python3 -m pybind11 --includes)`` in the above compilation, as
|
|
explained in :ref:`building_manually`.
|
|
|
|
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.
|
|
|
|
The `python_example`_ and `cmake_example`_ repositories are also a good place
|
|
to start. They are both complete project examples with cross-platform build
|
|
systems. The only difference between the two is that `python_example`_ uses
|
|
Python's ``setuptools`` to build the module, while `cmake_example`_ uses CMake
|
|
(which may be preferable for existing C++ projects).
|
|
|
|
.. _python_example: https://github.com/pybind/python_example
|
|
.. _cmake_example: https://github.com/pybind/cmake_example
|
|
|
|
Building the above C++ code will produce a binary module file that can be
|
|
imported to Python. Assuming that the compiled module is located in the
|
|
current directory, the following interactive Python session shows how to
|
|
load and execute the example:
|
|
|
|
.. code-block:: pycon
|
|
|
|
$ python
|
|
Python 3.9.10 (main, Jan 15 2022, 11:48:04)
|
|
[Clang 13.0.0 (clang-1300.0.29.3)] on darwin
|
|
Type "help", "copyright", "credits" or "license" for more information.
|
|
>>> import example
|
|
>>> example.add(1, 2)
|
|
3
|
|
>>>
|
|
|
|
.. _keyword_args:
|
|
|
|
Keyword arguments
|
|
=================
|
|
|
|
With a simple code modification, it is possible to inform Python about the
|
|
names of the arguments ("i" and "j" in this case).
|
|
|
|
.. code-block:: cpp
|
|
|
|
m.def("add", &add, "A function which adds two numbers",
|
|
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
|
|
call the function using keyword arguments, which is a more readable alternative
|
|
particularly for functions taking many parameters:
|
|
|
|
.. code-block:: pycon
|
|
|
|
>>> import example
|
|
>>> example.add(i=1, j=2)
|
|
3L
|
|
|
|
The keyword names also appear in the function signatures within the documentation.
|
|
|
|
.. code-block:: pycon
|
|
|
|
>>> help(example)
|
|
|
|
....
|
|
|
|
FUNCTIONS
|
|
add(...)
|
|
Signature : (i: int, j: int) -> int
|
|
|
|
A function which adds two numbers
|
|
|
|
A shorter notation for named arguments is also available:
|
|
|
|
.. code-block:: cpp
|
|
|
|
// regular notation
|
|
m.def("add1", &add, py::arg("i"), py::arg("j"));
|
|
// shorthand
|
|
using namespace pybind11::literals;
|
|
m.def("add2", &add, "i"_a, "j"_a);
|
|
|
|
The :var:`_a` suffix forms a C++11 literal which is equivalent to :class:`arg`.
|
|
Note that the literal operator must first be made visible with the directive
|
|
``using namespace pybind11::literals``. This does not bring in anything else
|
|
from the ``pybind11`` namespace except for literals.
|
|
|
|
.. _default_args:
|
|
|
|
Default arguments
|
|
=================
|
|
|
|
Suppose now that the function to be bound has default arguments, e.g.:
|
|
|
|
.. code-block:: cpp
|
|
|
|
int add(int i = 1, int j = 2) {
|
|
return i + j;
|
|
}
|
|
|
|
Unfortunately, pybind11 cannot automatically extract these parameters, since they
|
|
are not part of the function's type information. However, they are simple to specify
|
|
using an extension of :class:`arg`:
|
|
|
|
.. code-block:: cpp
|
|
|
|
m.def("add", &add, "A function which adds two numbers",
|
|
py::arg("i") = 1, py::arg("j") = 2);
|
|
|
|
The default values also appear within the documentation.
|
|
|
|
.. code-block:: pycon
|
|
|
|
>>> help(example)
|
|
|
|
....
|
|
|
|
FUNCTIONS
|
|
add(...)
|
|
Signature : (i: int = 1, j: int = 2) -> int
|
|
|
|
A function which adds two numbers
|
|
|
|
The shorthand notation is also available for default arguments:
|
|
|
|
.. code-block:: cpp
|
|
|
|
// regular notation
|
|
m.def("add1", &add, py::arg("i") = 1, py::arg("j") = 2);
|
|
// shorthand
|
|
m.def("add2", &add, "i"_a=1, "j"_a=2);
|
|
|
|
Exporting variables
|
|
===================
|
|
|
|
To expose a value from C++, use the ``attr`` function to register it in a
|
|
module as shown below. Built-in types and general objects (more on that later)
|
|
are automatically converted when assigned as attributes, and can be explicitly
|
|
converted using the function ``py::cast``.
|
|
|
|
.. code-block:: cpp
|
|
|
|
PYBIND11_MODULE(example, m) {
|
|
m.attr("the_answer") = 42;
|
|
py::object world = py::cast("World");
|
|
m.attr("what") = world;
|
|
}
|
|
|
|
These are then accessible from Python:
|
|
|
|
.. code-block:: pycon
|
|
|
|
>>> import example
|
|
>>> example.the_answer
|
|
42
|
|
>>> example.what
|
|
'World'
|
|
|
|
.. _supported_types:
|
|
|
|
Supported data types
|
|
====================
|
|
|
|
A large number of data types are supported out of the box and can be used
|
|
seamlessly as functions arguments, return values or with ``py::cast`` in general.
|
|
For a full overview, see the :doc:`advanced/cast/index` section.
|