Zengtudor
/
pybind11
mirror of https://github.com/pybind/pybind11.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
pybind11/docs/reference.rst

131 lines
2.6 KiB
ReStructuredText
Raw Normal View History

took a stab at some documentation
2015-10-13 00:57:16 +00:00
.. _reference:
remainder of documentation
2015-10-13 21:21:54 +00:00
.. warning::
Please be advised that the reference documentation discussing pybind11
internals is currently incomplete. Please refer to the previous sections
last breaking change: be consistent about the project name
2015-10-15 16:13:33 +00:00
and the pybind11 header files for the nitty gritty details.
remainder of documentation
2015-10-13 21:21:54 +00:00
took a stab at some documentation
2015-10-13 00:57:16 +00:00
Reference
#########
Update changelog for v2.2.0 [skip ci]
2017-08-13 20:25:15 +00:00
.. _macros:
took a stab at some documentation
2015-10-13 00:57:16 +00:00
Macros
======
Replace PYBIND11_PLUGIN with PYBIND11_MODULE This commit also adds `doc()` to `object_api` as a shortcut for the `attr("__doc__")` accessor. The module macro changes from: ```c++ PYBIND11_PLUGIN(example) { pybind11::module m("example", "pybind11 example plugin"); m.def("add", [](int a, int b) { return a + b; }); return m.ptr(); } ``` to: ```c++ PYBIND11_MODULE(example, m) { m.doc() = "pybind11 example plugin"; m.def("add", [](int a, int b) { return a + b; }); } ``` Using the old macro results in a deprecation warning. The warning actually points to the `pybind11_init` function (since attributes don't bind to macros), but the message should be quite clear: "PYBIND11_PLUGIN is deprecated, use PYBIND11_MODULE".
2017-04-23 23:51:44 +00:00
.. doxygendefine:: PYBIND11_MODULE
took a stab at some documentation
2015-10-13 00:57:16 +00:00
.. _core_types:
Convenience classes for arbitrary Python types
==============================================
Automate generation of reference docs with doxygen and breathe (#598) * Make 'any' the default markup role for Sphinx docs * Automate generation of reference docs with doxygen and breathe * Improve reference docs coverage
2017-01-31 15:54:08 +00:00
Common member functions
-----------------------
took a stab at some documentation
2015-10-13 00:57:16 +00:00
Automate generation of reference docs with doxygen and breathe (#598) * Make 'any' the default markup role for Sphinx docs * Automate generation of reference docs with doxygen and breathe * Improve reference docs coverage
2017-01-31 15:54:08 +00:00
.. doxygenclass:: object_api
:members:
took a stab at some documentation
2015-10-13 00:57:16 +00:00
Automate generation of reference docs with doxygen and breathe (#598) * Make 'any' the default markup role for Sphinx docs * Automate generation of reference docs with doxygen and breathe * Improve reference docs coverage
2017-01-31 15:54:08 +00:00
Without reference counting
--------------------------
took a stab at some documentation
2015-10-13 00:57:16 +00:00
Automate generation of reference docs with doxygen and breathe (#598) * Make 'any' the default markup role for Sphinx docs * Automate generation of reference docs with doxygen and breathe * Improve reference docs coverage
2017-01-31 15:54:08 +00:00
.. doxygenclass:: handle
:members:
took a stab at some documentation
2015-10-13 00:57:16 +00:00
With reference counting
-----------------------
Automate generation of reference docs with doxygen and breathe (#598) * Make 'any' the default markup role for Sphinx docs * Automate generation of reference docs with doxygen and breathe * Improve reference docs coverage
2017-01-31 15:54:08 +00:00
.. doxygenclass:: object
:members:
Use object class to hold partially converted python objects. Using object class to hold converted object automatically deallocates object if an exception is thrown or scope is left before constructing complete Python object. Additionally added method object::release() that allows to release ownership of python object without decreasing its reference count.
2015-12-30 20:03:57 +00:00
Automate generation of reference docs with doxygen and breathe (#598) * Make 'any' the default markup role for Sphinx docs * Automate generation of reference docs with doxygen and breathe * Improve reference docs coverage
2017-01-31 15:54:08 +00:00
.. doxygenfunction:: reinterpret_borrow
Use object class to hold partially converted python objects. Using object class to hold converted object automatically deallocates object if an exception is thrown or scope is left before constructing complete Python object. Additionally added method object::release() that allows to release ownership of python object without decreasing its reference count.
2015-12-30 20:03:57 +00:00
Automate generation of reference docs with doxygen and breathe (#598) * Make 'any' the default markup role for Sphinx docs * Automate generation of reference docs with doxygen and breathe * Improve reference docs coverage
2017-01-31 15:54:08 +00:00
.. doxygenfunction:: reinterpret_steal
took a stab at some documentation
2015-10-13 00:57:16 +00:00
Convenience classes for specific Python types
=============================================
fix: rename `pybind11::module` to `pybind11::module_` (#2489) Support C++20. For backwards compatibility, we provide an alias for the old name. This change is necessary to easily avoid errors when a compiler thinks `module` is used as a keyword.
2020-09-16 21:15:42 +00:00
.. doxygenclass:: module_
Automate generation of reference docs with doxygen and breathe (#598) * Make 'any' the default markup role for Sphinx docs * Automate generation of reference docs with doxygen and breathe * Improve reference docs coverage
2017-01-31 15:54:08 +00:00
:members:
took a stab at some documentation
2015-10-13 00:57:16 +00:00
Automate generation of reference docs with doxygen and breathe (#598) * Make 'any' the default markup role for Sphinx docs * Automate generation of reference docs with doxygen and breathe * Improve reference docs coverage
2017-01-31 15:54:08 +00:00
.. doxygengroup:: pytypes
:members:
took a stab at some documentation
2015-10-13 00:57:16 +00:00
Update breathe to 4.26.1, add make_tuple, make_iterator, and make_key_iterator (#2828)
2021-01-28 11:28:16 +00:00
Convenience functions converting to Python types
================================================
.. doxygenfunction:: make_tuple(Args&&...)
.. doxygenfunction:: make_iterator(Iterator, Sentinel, Extra &&...)
.. doxygenfunction:: make_iterator(Type &, Extra&&...)
.. doxygenfunction:: make_key_iterator(Iterator, Sentinel, Extra &&...)
.. doxygenfunction:: make_key_iterator(Type &, Extra&&...)
feat: reapply fixed version of #3271 (#3293) * Add make_value_iterator (#3271) * Add make_value_iterator This is the counterpart to make_key_iterator, and will allow implementing a `value` method in `bind_map` (although doing so is left for a subsequent PR). I made a few design changes to reduce copy-and-paste boilerplate. Previously detail::iterator_state had a boolean template parameter to indicate whether it was being used for make_iterator or make_key_iterator. I replaced the boolean with a class that determines how to dereference the iterator. This allows for a generic implementation of `__next__`. I also added the ValueType and Extra... parameters to the iterator_state template args, because I think it was a bug that they were missing: if make_iterator is called twice with different values of these, only the first set has effect (because the state class is only registered once). There is still a potential issue in that the *values* of the extra arguments are latched on the first call, but since most policies are empty classes this should be even less common. * Add some remove_cv_t to appease clang-tidy * Make iterator_access and friends take reference For some reason I'd accidentally made it take a const value, which caused some issues with third-party packages. * Another attempt to remove remove_cv_t from iterators Some of the return types were const (non-reference) types because of the pecularities of decltype: `decltype((*it).first)` is the *declared* type of the member of the pair, rather than the type of the expression. So if the reference type of the iterator is `pair<const int, int> &`, then the decltype is `const int`. Wrapping an extra set of parentheses to form `decltype(((*it).first))` would instead give `const int &`. This means that the existing make_key_iterator actually returns by value from `__next__`, rather than by reference. Since for mapping types, keys are always const, this probably hasn't been noticed, but it will affect make_value_iterator if the Python code tries to mutate the returned objects. I've changed things to use double parentheses so that make_iterator, make_key_iterator and make_value_iterator should now all return the reference type of the iterator. I'll still need to add a test for that; for now I'm just checking whether I can keep Clang-Tidy happy. * Add back some NOLINTNEXTLINE to appease Clang-Tidy This is favoured over using remove_cv_t because in some cases a const value return type is deliberate (particularly for Eigen). * Add a unit test for iterator referencing Ensure that make_iterator, make_key_iterator and make_value_iterator return references to the container elements, rather than copies. The test for make_key_iterator fails to compile on master, which gives me confidence that this branch has fixed it. * Make the iterator_access etc operator() const I'm actually a little surprised it compiled at all given that the operator() is called on a temporary, but I don't claim to fully understand all the different value types in C++11. * Attempt to work around compiler bugs https://godbolt.org/ shows an example where ICC gets the wrong result for a decltype used as the default for a template argument, and CI also showed problems with PGI. This is a shot in the dark to see if it fixes things. * Make a test constructor explicit (Clang-Tidy) * Fix unit test on GCC 4.8.5 It seems to require the arguments to the std::pair constructor to be implicitly convertible to the types in the pair, rather than just requiring is_constructible. * Remove DOXYGEN_SHOULD_SKIP_THIS guards Now that a complex decltype expression has been replaced by a simpler nested type, I'm hoping Doxygen will be able to build it without issues. * Add comment to explain iterator_state template params * fix: regression in #3271 Co-authored-by: Bruce Merry <1963944+bmerry@users.noreply.github.com>
2021-09-23 19:06:07 +00:00
.. doxygenfunction:: make_value_iterator(Iterator, Sentinel, Extra &&...)
.. doxygenfunction:: make_value_iterator(Type &, Extra&&...)
took a stab at some documentation
2015-10-13 00:57:16 +00:00
.. _extras:
Automate generation of reference docs with doxygen and breathe (#598) * Make 'any' the default markup role for Sphinx docs * Automate generation of reference docs with doxygen and breathe * Improve reference docs coverage
2017-01-31 15:54:08 +00:00
Passing extra arguments to ``def`` or ``class_``
================================================
took a stab at some documentation
2015-10-13 00:57:16 +00:00
Automate generation of reference docs with doxygen and breathe (#598) * Make 'any' the default markup role for Sphinx docs * Automate generation of reference docs with doxygen and breathe * Improve reference docs coverage
2017-01-31 15:54:08 +00:00
.. doxygengroup:: annotations
:members:
took a stab at some documentation
2015-10-13 00:57:16 +00:00
Add C++ interface for the Python interpreter
2017-03-29 22:20:42 +00:00
Embedding the interpreter
=========================
.. doxygendefine:: PYBIND11_EMBEDDED_MODULE
.. doxygenfunction:: initialize_interpreter
.. doxygenfunction:: finalize_interpreter
.. doxygenclass:: scoped_interpreter
Utility for redirecting C++ streams to Python (#1009)
2017-08-25 00:12:43 +00:00
Redirecting C++ streams
=======================
.. doxygenclass:: scoped_ostream_redirect
.. doxygenclass:: scoped_estream_redirect
.. doxygenfunction:: add_ostream_redirect
Fix typo in doc: build-in -> built-in
2018-07-01 15:47:22 +00:00
Python built-in functions
Automate generation of reference docs with doxygen and breathe (#598) * Make 'any' the default markup role for Sphinx docs * Automate generation of reference docs with doxygen and breathe * Improve reference docs coverage
2017-01-31 15:54:08 +00:00
=========================
took a stab at some documentation
2015-10-13 00:57:16 +00:00
Automate generation of reference docs with doxygen and breathe (#598) * Make 'any' the default markup role for Sphinx docs * Automate generation of reference docs with doxygen and breathe * Improve reference docs coverage
2017-01-31 15:54:08 +00:00
.. doxygengroup:: python_builtins
:members:
took a stab at some documentation
2015-10-13 00:57:16 +00:00
Improve documentation related to inheritance. (#1676) * Adds section to the reference. * Adds section to advanced classes page describing how to use `get_overload`.
2019-06-10 20:12:28 +00:00
Inheritance
===========
See :doc:`/classes` and :doc:`/advanced/classes` for more detail.
Resolve empty statement warning when using PYBIND11_OVERLOAD_PURE_NAME and PYBIND11_OVERLOAD_PURE (#2325) * Wrap PYBIND11_OVERLOAD_NAME and PYBIND11_OVERLOAD_PURE_NAME in do { ... } while (false), and resolve trailing semicolon * Deprecate PYBIND11_OVERLOAD_* and get_overload in favor of PYBIND11_OVERRIDE_* and get_override * Correct erroneous usage of 'overload' instead of 'override' in the implementation and internals * Fix tests to use non-deprecated PYBIND11_OVERRIDE_* macros * Update docs to use override instead of overload where appropriate, and add warning about deprecated aliases * Add semicolons to deprecated PYBIND11_OVERLOAD macros to match original behavior * Remove deprecation of PYBIND11_OVERLOAD_* macros and get_overload * Add note to changelog and upgrade guide
2020-09-15 12:56:20 +00:00
.. doxygendefine:: PYBIND11_OVERRIDE
Improve documentation related to inheritance. (#1676) * Adds section to the reference. * Adds section to advanced classes page describing how to use `get_overload`.
2019-06-10 20:12:28 +00:00
Resolve empty statement warning when using PYBIND11_OVERLOAD_PURE_NAME and PYBIND11_OVERLOAD_PURE (#2325) * Wrap PYBIND11_OVERLOAD_NAME and PYBIND11_OVERLOAD_PURE_NAME in do { ... } while (false), and resolve trailing semicolon * Deprecate PYBIND11_OVERLOAD_* and get_overload in favor of PYBIND11_OVERRIDE_* and get_override * Correct erroneous usage of 'overload' instead of 'override' in the implementation and internals * Fix tests to use non-deprecated PYBIND11_OVERRIDE_* macros * Update docs to use override instead of overload where appropriate, and add warning about deprecated aliases * Add semicolons to deprecated PYBIND11_OVERLOAD macros to match original behavior * Remove deprecation of PYBIND11_OVERLOAD_* macros and get_overload * Add note to changelog and upgrade guide
2020-09-15 12:56:20 +00:00
.. doxygendefine:: PYBIND11_OVERRIDE_PURE
Improve documentation related to inheritance. (#1676) * Adds section to the reference. * Adds section to advanced classes page describing how to use `get_overload`.
2019-06-10 20:12:28 +00:00
Resolve empty statement warning when using PYBIND11_OVERLOAD_PURE_NAME and PYBIND11_OVERLOAD_PURE (#2325) * Wrap PYBIND11_OVERLOAD_NAME and PYBIND11_OVERLOAD_PURE_NAME in do { ... } while (false), and resolve trailing semicolon * Deprecate PYBIND11_OVERLOAD_* and get_overload in favor of PYBIND11_OVERRIDE_* and get_override * Correct erroneous usage of 'overload' instead of 'override' in the implementation and internals * Fix tests to use non-deprecated PYBIND11_OVERRIDE_* macros * Update docs to use override instead of overload where appropriate, and add warning about deprecated aliases * Add semicolons to deprecated PYBIND11_OVERLOAD macros to match original behavior * Remove deprecation of PYBIND11_OVERLOAD_* macros and get_overload * Add note to changelog and upgrade guide
2020-09-15 12:56:20 +00:00
.. doxygendefine:: PYBIND11_OVERRIDE_NAME
Improve documentation related to inheritance. (#1676) * Adds section to the reference. * Adds section to advanced classes page describing how to use `get_overload`.
2019-06-10 20:12:28 +00:00
Resolve empty statement warning when using PYBIND11_OVERLOAD_PURE_NAME and PYBIND11_OVERLOAD_PURE (#2325) * Wrap PYBIND11_OVERLOAD_NAME and PYBIND11_OVERLOAD_PURE_NAME in do { ... } while (false), and resolve trailing semicolon * Deprecate PYBIND11_OVERLOAD_* and get_overload in favor of PYBIND11_OVERRIDE_* and get_override * Correct erroneous usage of 'overload' instead of 'override' in the implementation and internals * Fix tests to use non-deprecated PYBIND11_OVERRIDE_* macros * Update docs to use override instead of overload where appropriate, and add warning about deprecated aliases * Add semicolons to deprecated PYBIND11_OVERLOAD macros to match original behavior * Remove deprecation of PYBIND11_OVERLOAD_* macros and get_overload * Add note to changelog and upgrade guide
2020-09-15 12:56:20 +00:00
.. doxygendefine:: PYBIND11_OVERRIDE_PURE_NAME
Improve documentation related to inheritance. (#1676) * Adds section to the reference. * Adds section to advanced classes page describing how to use `get_overload`.
2019-06-10 20:12:28 +00:00
Resolve empty statement warning when using PYBIND11_OVERLOAD_PURE_NAME and PYBIND11_OVERLOAD_PURE (#2325) * Wrap PYBIND11_OVERLOAD_NAME and PYBIND11_OVERLOAD_PURE_NAME in do { ... } while (false), and resolve trailing semicolon * Deprecate PYBIND11_OVERLOAD_* and get_overload in favor of PYBIND11_OVERRIDE_* and get_override * Correct erroneous usage of 'overload' instead of 'override' in the implementation and internals * Fix tests to use non-deprecated PYBIND11_OVERRIDE_* macros * Update docs to use override instead of overload where appropriate, and add warning about deprecated aliases * Add semicolons to deprecated PYBIND11_OVERLOAD macros to match original behavior * Remove deprecation of PYBIND11_OVERLOAD_* macros and get_overload * Add note to changelog and upgrade guide
2020-09-15 12:56:20 +00:00
.. doxygenfunction:: get_override
Improve documentation related to inheritance. (#1676) * Adds section to the reference. * Adds section to advanced classes page describing how to use `get_overload`.
2019-06-10 20:12:28 +00:00
Automate generation of reference docs with doxygen and breathe (#598) * Make 'any' the default markup role for Sphinx docs * Automate generation of reference docs with doxygen and breathe * Improve reference docs coverage
2017-01-31 15:54:08 +00:00
Exceptions
==========
took a stab at some documentation
2015-10-13 00:57:16 +00:00
Automate generation of reference docs with doxygen and breathe (#598) * Make 'any' the default markup role for Sphinx docs * Automate generation of reference docs with doxygen and breathe * Improve reference docs coverage
2017-01-31 15:54:08 +00:00
.. doxygenclass:: error_already_set
:members:
took a stab at some documentation
2015-10-13 00:57:16 +00:00
Automate generation of reference docs with doxygen and breathe (#598) * Make 'any' the default markup role for Sphinx docs * Automate generation of reference docs with doxygen and breathe * Improve reference docs coverage
2017-01-31 15:54:08 +00:00
.. doxygenclass:: builtin_exception
:members:
took a stab at some documentation
2015-10-13 00:57:16 +00:00
Automate generation of reference docs with doxygen and breathe (#598) * Make 'any' the default markup role for Sphinx docs * Automate generation of reference docs with doxygen and breathe * Improve reference docs coverage
2017-01-31 15:54:08 +00:00
Literals
========
added exec functions
2016-06-09 14:10:26 +00:00
Automate generation of reference docs with doxygen and breathe (#598) * Make 'any' the default markup role for Sphinx docs * Automate generation of reference docs with doxygen and breathe * Improve reference docs coverage
2017-01-31 15:54:08 +00:00
.. doxygennamespace:: literals