Zengtudor/pybind11
1
0
Fork 0
mirror of https://github.com/pybind/pybind11.git synced 2024-11-14 09:34:46 +00:00
Code Issues Packages Projects Releases Wiki Activity
f385eccdb7
pybind11/docs/reference.rst

118 lines
2.1 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
.. _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
Reference in New Issue Copy Permalink