警告
Please be advised that the reference documentation discussing pybind11 internals is currently incomplete. Please refer to the previous sections and the pybind11 header files for the nitty gritty details. Reference #
This macro creates the entry point that will be invoked when the Python interpreter imports an extension module. The module name is given as the fist argument and it should not be in quotes. The second macro argument defines a variable of type
py::module_
which can be used to initialize the module.
The entry point is marked as “maybe unused” to aid dead-code detection analysis: since the entry point is typically only looked up at runtime and not referenced during translation, it would otherwise appear as unused (“dead”) code.
PYBIND11_MODULE(example, m) { m.doc() = "pybind11 example module"; // Add bindings here m.def("foo", []() { return "Hello, World!"; }); }
A mixin class which adds common functions to
handle
,
object
and various accessors. The only requirement for
Derived
is to implement
PyObject *Derived::ptr() const
.
Public Functions
Return an iterator equivalent to calling
iter()
in Python. The object must be a collection which supports the iteration protocol.
Return an internal functor to invoke the object’s sequence protocol. Casting the returned
detail::item_accessor
instance to a
handle
or
object
subclass causes a corresponding call to
__getitem__
. Assigning a
handle
or
object
subclass causes a call to
__setitem__
.
See above (the only difference is that the key’s reference is stolen)
See above (the only difference is that the key is provided as a string literal)
Return an internal functor to access the object’s attributes. Casting the returned
detail::obj_attr_accessor
instance to a
handle
or
object
subclass causes a corresponding call to
getattr
. Assigning a
handle
or
object
subclass causes a call to
setattr
.
See above (the only difference is that the key’s reference is stolen)
See above (the only difference is that the key is provided as a string literal)
Matches * unpacking in Python, e.g. to unpack arguments out of a
tuple
or
list
for a function call. Applying another * to the result yields ** unpacking, e.g. to unpack a dict as function keyword arguments. See
Calling Python functions
.
Check if the given item is contained within this object, i.e.
item in obj
.
Assuming the Python object is a function or implements the
__call__
protocol,
operator()
invokes the underlying function, passing an arbitrary set of parameters. The result is returned as a
object
and may need to be converted back into a Python object using
handle::cast()
.
When some of the arguments cannot be converted to Python objects, the function will throw a
cast_error
exception. When the Python function call fails, a
error_already_set
exception is thrown.
相当于
obj is other
in Python.
相当于
obj is None
in Python.
Equivalent to obj == other in Python.
Get or set the object’s docstring, i.e.
obj.__doc__
.
Return the object’s current reference count.
Holds a reference to a Python object (no reference counting)
The
handle
class is a thin wrapper around an arbitrary Python object (i.e. a
PyObject *
in Python’s C API). It does not perform any automatic reference counting and merely provides a basic C++ interface to various Python API functions.
另请参阅
The
object
类继承自
handle
and adds automatic reference counting features.
Subclassed by args_proxy, kwargs_proxy, object
Public Functions
The default constructor creates a handle with a
nullptr
-valued pointer.
Enable implicit conversion from
PyObject *
and
nullptr
. Not using
handle(PyObject *ptr)
to avoid implicit conversion from
0
.
Enable implicit conversion through
T::operator PyObject *()
.
Return the underlying
PyObject *
指针。
Manually increase the reference count of the Python object. Usually, it is preferable to use the
object
class which derives from
handle
and calls this function automatically. Returns a reference to itself.
Manually decrease the reference count of the Python object. Usually, it is preferable to use the
object
class which derives from
handle
and calls this function automatically. Returns a reference to itself.
Attempt to cast the Python object into the given C++ type. A
cast_error
will be throw upon failure.
返回
true
当
handle
wraps a valid Python object.
Deprecated: Check that the underlying pointers are the same. Equivalent to
obj1 is obj2
in Python.
Holds a reference to a Python object (with reference counting)
像
handle
，
object
class is a thin wrapper around an arbitrary Python object (i.e. a
PyObject *
in Python’s C API). In contrast to
handle
, it optionally increases the object’s reference count upon construction, and it
always
decreases the reference count when the
object
instance goes out of scope and is destructed. When using
object
instances consistently, it is much easier to get reference counting right at the first attempt.
Subclassed by anyset , bool_ , buffer , bytearray , bytes , capsule , dict , dtype, ellipsis , exception< type >, float_ , function , generic_type, int_ , iterable , iterator , list , memoryview , module_ , none , sequence , slice , staticmethod , str , tuple , type , weakref
Public Functions
Move constructor; steals the object from
other
and preserves its reference count.
Destructor; automatically calls
handle::dec_ref()
Resets the internal pointer to
nullptr
without decreasing the object’s reference count. The function returns a raw handle to the original Python object.
Declare that a
handle
or
PyObject *
is a certain type and borrow the reference. The target type
T
必须为
object
or one of its derived classes. The function doesn’t do any conversions or checks. It’s up to the user to make sure that the target type is correct.
PyObject *p = PyList_GetItem(obj, index); py::object o = reinterpret_borrow<py::object>(p); // or py::tuple t = reinterpret_borrow<py::tuple>(p); // <-- `p` must be already be a `tuple`
像
reinterpret_borrow()
, but steals the reference.
PyObject *p = PyObject_Str(obj); py::str s = reinterpret_steal<py::str>(p); // <-- `p` must be already be a `str`
Create a new top-level Python module with the given name and docstring.
Create Python binding for a new function within the module scope.
Func
can be a plain C++ function, a function pointer, or a lambda function. For details on the
Extra&& ... extra
argument, see section
Passing extra arguments to def or class_
.
Create and return a new Python submodule with the given name and docstring. This also works recursively, i.e.
py::module_ m("example", "pybind11 example plugin"); py::module_ m2 = m.def_submodule("sub", "A submodule of 'example'"); py::module_ m3 = m2.def_submodule("subsub", "A submodule of 'example.sub'");
Reload the module or throws
error_already_set
.
Adds an object to the module using the given name. Throws if an object with the given name already exists.
overwrite
should almost always be false: attempting to overwrite objects that pybind11 has established will, in most cases, break things.
Public Static Functions
Import and return a module or throws
error_already_set
.
Create a new top-level module that can be used as the main module of a C extension.
def
should point to a statically allocated module_def.
函数
Wraps a Python iterator so that it can also be used as a C++ input iterator
Caveat: copying an iterator does not (and cannot) clone the internal state of the Python iterable. This also applies to the post-increment operator. This iterator should only be used to retrieve the current value using
operator*()
.
Public Static Functions
The value which marks the end of the iteration.
it == iterator::sentinel()
is equivalent to catching
StopIteration
in Python.
void foo(py::iterator it) { while (it != py::iterator::sentinel()) { // use `*it` ++it; } }
Public Static Functions
Return a type object from a handle or an object.
Convert C++ type to handle if previously registered. Does not convert standard types, like int, float. etc. yet. See https://github.com/pybind/pybind11/issues/2486
Convert C++ type to type if previously registered. Does not convert standard types, like int, float. etc. yet. See https://github.com/pybind/pybind11/issues/2486
Public Functions
Return a string representation of the object. This is analogous to the
str()
function in Python.
Public Functions
创建
memoryview
from
buffer_info
.
buffer_info
must be created from
buffer::request()
. Otherwise throws an exception.
For creating a
memoryview
from objects that support buffer protocol, use
memoryview(const object& obj)
instead of this constructor.
Public Static Functions
创建
memoryview
from static buffer.
This method is meant for providing a
memoryview
for C/C++ buffer not managed by Python. The caller is responsible for managing the lifetime of
ptr
and
format
, which MUST outlive the memoryview constructed here.
See also: Python C API documentation for PyMemoryView_FromBuffer .
ptr – Pointer to the buffer.
itemsize – Byte size of an element.
format
– Pointer to the null-terminated format string. For homogeneous Buffers, this should be set to
format_descriptor<T>::value
.
shape – Shape of the tensor (1 entry per dimension).
strides – Number of bytes between adjacent entries (for each per dimension).
readonly – Flag to indicate if the underlying storage may be written to.
创建
memoryview
from static memory.
This method is meant for providing a
memoryview
for C/C++ buffer not managed by Python. The caller is responsible for managing the lifetime of
mem
, which MUST outlive the memoryview constructed here.
See also: Python C API documentation for PyMemoryView_FromBuffer .
警告
doxygenfunction: Unable to resolve function “make_iterator” with arguments (Iterator, Sentinel, Extra&&…) in doxygen xml output for project “pybind11” from directory: .build/doxygenxml/. Potential matches:
- template<return_value_policy Policy = return_value_policy::reference_internal, typename Iterator, typename Sentinel, typename ValueType = typename detail::iterator_access<Iterator>::result_type, typename ...Extra> iterator make_iterator(Iterator &&first, Sentinel &&last, Extra&&... extra) - template<return_value_policy Policy = return_value_policy::reference_internal, typename Type, typename ...Extra> iterator make_iterator(Type &value, Extra&&... extra)
Makes an iterator over values of an stl container or other container supporting
std::begin()
/
std::end()
警告
doxygenfunction: Unable to resolve function “make_key_iterator” with arguments (Iterator, Sentinel, Extra&&…) in doxygen xml output for project “pybind11” from directory: .build/doxygenxml/. Potential matches:
- template<return_value_policy Policy = return_value_policy::reference_internal, typename Iterator, typename Sentinel, typename KeyType = typename detail::iterator_key_access<Iterator>::result_type, typename ...Extra> iterator make_key_iterator(Iterator &&first, Sentinel &&last, Extra&&... extra) - template<return_value_policy Policy = return_value_policy::reference_internal, typename Type, typename ...Extra> iterator make_key_iterator(Type &value, Extra&&... extra)
Makes an iterator over the keys (
.first
) of a stl map-like container supporting
std::begin()
/
std::end()
警告
doxygenfunction: Unable to resolve function “make_value_iterator” with arguments (Iterator, Sentinel, Extra&&…) in doxygen xml output for project “pybind11” from directory: .build/doxygenxml/. Potential matches:
- template<return_value_policy Policy = return_value_policy::reference_internal, typename Iterator, typename Sentinel, typename ValueType = typename detail::iterator_value_access<Iterator>::result_type, typename ...Extra> iterator make_value_iterator(Iterator &&first, Sentinel &&last, Extra&&... extra) - template<return_value_policy Policy = return_value_policy::reference_internal, typename Type, typename ...Extra> iterator make_value_iterator(Type &value, Extra&&... extra)
Makes an iterator over the values (
.second
) of a stl map-like container supporting
std::begin()
/
std::end()
def
or
class_
#
Annotation for methods.
Annotation for operators.
Annotation for classes that cannot be subclassed.
Annotation for parent scope.
Annotation for documentation.
Annotation for function names.
Annotation indicating that a function is an overload associated with a given “sibling”.
Annotation indicating that a class derives from another given type.
Keep patient alive while nurse lives.
Annotation indicating that a class is involved in a multiple inheritance relationship.
Annotation which enables dynamic attributes, i.e. adds
__dict__
to a class.
Annotation which enables the buffer protocol for a type.
Annotation which requests that a special metaclass is created for a type.
Public Functions
Specifies a custom callback with signature
void (PyHeapTypeObject*)
that may be used to customize the Python type.
The callback is invoked immediately before
PyType_Ready
.
Note: This is an advanced interface, and uses of it may require changes to work with later versions of pybind11. You may wish to consult the implementation of
make_new_python_type
in
detail/classes.h
to understand the context in which the callback will be run.
Annotation that marks a class as local to the module:
Annotation to mark enums as an arithmetic type.
Mark a function for addition at the beginning of the existing overload chain instead of the end.
A call policy which places one or more guard variables (
Ts...
) around the function call.
For example, this definition:
m.def("foo", foo, py::call_guard<T>());
is equivalent to the following pseudocode:
m.def("foo", [](args...) { T scope_guard; return foo(args...); // forwarded arguments });
Annotation for arguments
Subclassed by arg_v
Public Functions
Constructs an argument with the name of the argument; if null or omitted, this is a positional argument.
Indicate that the type should not be converted in the type caster.
Indicates that the argument should/shouldn’t allow None (e.g. for nullable pointer args)
Public Members
If non-null, this is a named kwargs argument.
If set, do not allow conversion (requires a supporting type caster!)
If set (the default), allow None to be passed to this argument.
Annotation for arguments with values
Public Functions
Direct construction with name, default, and description.
Called internally when invoking
py::arg("a") = value
如同
arg::noconvert()
, but returns *this as
arg_v
&, not arg&.
如同
arg::nonone()
, but returns *this as
arg_v
&, not arg&.
Public Members
The (optional) description of the default value.
The C++ type name of the default value (only available when compiled in debug mode)
Annotation indicating that all following arguments are keyword-only; the is the equivalent of an unnamed ‘*’ argument
Annotation indicating that all previous arguments are positional-only; the is the equivalent of an unnamed ‘/’ argument (in Python 3.8)
Add a new module to the table of builtins for the interpreter. Must be defined in global scope. The first macro parameter is the name of the module (without quotes). The second parameter is the variable which will be used as the interface to add functions and classes to the module.
PYBIND11_EMBEDDED_MODULE(example, m) { // ... initialize functions and classes here m.def("foo", []() { return "Hello, World!"; }); }
Initialize the Python interpreter. No other pybind11 or CPython API functions can be called before this is done; with the exception of
PYBIND11_EMBEDDED_MODULE
。可选
init_signal_handlers
parameter can be used to skip the registration of signal handlers (see the
Python documentation
for details). Calling this function again after the interpreter has already been initialized is a fatal error.
If initializing the Python interpreter fails, then the program is terminated. (This is controlled by the CPython runtime and is an exception to pybind11’s normal behavior of throwing exceptions on errors.)
The remaining optional parameters,
argc
,
argv
，和
add_program_dir_to_path
are used to populate
sys.argv
and
sys.path
。见
PySys_SetArgvEx
文档编制
了解细节。
Shut down the Python interpreter. No pybind11 or CPython API functions can be called after this. In addition, pybind11 objects must not outlive the interpreter:
{ // BAD py::initialize_interpreter(); auto hello = py::str("Hello, World!"); py::finalize_interpreter(); } // <-- BOOM, hello's destructor is called after interpreter shutdown { // GOOD py::initialize_interpreter(); { // scoped auto hello = py::str("Hello, World!"); } // <-- OK, hello is cleaned up properly py::finalize_interpreter(); } { // BETTER py::scoped_interpreter guard{}; auto hello = py::str("Hello, World!"); }
警告
The interpreter can be restarted by calling
initialize_interpreter()
again. Modules created using pybind11 can be safely re-initialized. However, Python itself cannot completely unload binary extension modules and there are several caveats with regard to interpreter restarting. All the details can be found in the CPython documentation. In short, not all interpreter memory may be freed, either due to reference cycles or user-created global data.
Scope guard version of
initialize_interpreter()
and
finalize_interpreter()
. This a move-only guard and only a single instance can exist.
见
initialize_interpreter()
for a discussion of its constructor arguments.
#include <pybind11/embed.h> int main() { py::scoped_interpreter guard{}; py::print(Hello, World!); } // <-- interpreter shutdown
This a move-only guard that redirects output.
#include <pybind11/iostream.h> ... { py::scoped_ostream_redirect output; std::cout << "Hello, World!"; // Python stdout } // <-- return std::cout to normal
You can explicitly pass the c++ stream and the python object, for example to guard stderr instead.
{ py::scoped_ostream_redirect output{ std::cerr, py::module::import("sys").attr("stderr")}; std::cout << "Hello, World!"; }
Subclassed by scoped_estream_redirect
像
scoped_ostream_redirect
, but redirects cerr by default. This class is provided primary to make
py::call_guard
easier to make.
m.def("noisy_func", &noisy_func, py::call_guard<scoped_ostream_redirect, scoped_estream_redirect>());
This is a helper function to add a C++ redirect context manager to Python instead of using a C++ guard. To use it, add the following to your binding code:
#include <pybind11/iostream.h> ... py::add_ostream_redirect(m, "ostream_redirect");
You now have a Python context manager that redirects your output:
with m.ostream_redirect(): m.print_to_cout_function()
This manager can optionally be told which streams to operate on:
with m.ostream_redirect(stdout=true, stderr=true): m.noisy_function_with_error_printing()
Unless stated otherwise, the following C++ functions behave the same as their Python counterparts.
函数
Return a dictionary representing the global variables in the current execution frame, or
__main__.__dict__
if there is no frame (usually when the interpreter is embedded).
返回 True 若
obj
是实例化的
T
. Type
T
must be a subclass of
object
or a class which was exposed to Python as
py::class_<T>
.
Get the length hint of a Python object. Returns 0 when this cannot be determined.
见 面向对象代码 and 类 for more detail.
Macro to populate the virtual method in the trampoline class. This macro tries to look up the method from the Python side, deals with the GIL (全局解释器锁) and necessary argument conversions to call this method and return the appropriate type. This macro should be used if the method name in C and in Python are identical. See 覆写 Python 虚函数 了解更多信息。
class PyAnimal : public Animal { public: // Inherit the constructors using Animal::Animal; // Trampoline (need one for each virtual function) std::string go(int n_times) override { PYBIND11_OVERRIDE_PURE( std::string, // Return type (ret_type) Animal, // Parent class (cname) go, // Name of function in C++ (must match Python name) (fn) n_times // Argument(s) (...) ); } };
Macro for pure virtual functions, this function is identical to
PYBIND11_OVERRIDE
, except that it throws if no override can be found.
Macro to populate the virtual method in the trampoline class. This macro tries to look up a method named ‘fn’ from the Python side, deals with the
GIL (全局解释器锁)
and necessary argument conversions to call this method and return the appropriate type. See
覆写 Python 虚函数
for more information. This macro should be used when the method name in C is not the same as the method name in Python. For example with
__str__
.
std::string toString() override { PYBIND11_OVERRIDE_NAME( std::string, // Return type (ret_type) Animal, // Parent class (cname) "__str__", // Name of method in Python (name) toString, // Name of function in C++ (fn) ); }
Macro for pure virtual functions, this function is identical to
PYBIND11_OVERRIDE_NAME
, except that it throws if no override can be found.
Try to retrieve a python method by the provided name from the instance pointed to by the this_ptr.
The pointer to the object the overridden method should be retrieved for. This should be the first non-trampoline class encountered in the inheritance chain.
The name of the overridden Python method to retrieve.
The Python method by this name from the object or an empty function wrapper.
Fetch and hold an error which was already set in Python. An instance of this is typically thrown to propagate python-side errors back through C++ which can either be caught manually or else falls back to the function dispatcher (which then raises the captured error back to python).
Public Functions
Fetches the current Python exception (using PyErr_Fetch()), which will clear the current Python error indicator.
The what() result is built lazily on demand. WARNING: This member function needs to acquire the Python GIL. This can lead to crashes (undefined behavior) if the Python interpreter is finalizing.
Restores the currently-held Python error (which will clear the Python error indicator first if already set). NOTE: This member function will always restore the normalized exception, which may or may not be the original Python exception. WARNING: The GIL must be held when this member function is called!
If it is impossible to raise the currently-held error, such as in a destructor, we can write it out using Python’s unraisable hook (
sys.unraisablehook
). The error context should be some object whose
repr()
helps identify the location of the error. Python already knows the type and value of the error, so there is no need to repeat that.
An alternate version of
discard_as_unraisable()
, where a string provides information on the location of the error. For example,
__func__
could be helpful. WARNING: The GIL must be held when this member function is called!
Check if the currently trapped error type matches the given Python exception class (or a subclass thereof). May also be passed a tuple to search for any exception class matches in the given tuple.
C++ bindings of builtin Python exceptions.
Public Functions
Set the error using the Python C API.