pybind11/docs/reference.rst

.. _reference:

.. warning::

    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
#########

.. _macros:

Macros
======

.. doxygendefine:: PYBIND11_MODULE

.. _core_types:

Convenience classes for arbitrary Python types
==============================================

Common member functions
-----------------------

.. doxygenclass:: object_api
    :members:

Without reference counting
--------------------------

.. doxygenclass:: handle
    :members:

With reference counting
-----------------------

.. doxygenclass:: object
    :members:

.. doxygenfunction:: reinterpret_borrow

.. doxygenfunction:: reinterpret_steal

Convenience classes for specific Python types
=============================================

.. doxygenclass:: module
    :members:

.. doxygengroup:: pytypes
    :members:

.. _extras:

Passing extra arguments to ``def`` or ``class_``
================================================

.. doxygengroup:: annotations
    :members:

Embedding the interpreter
=========================

.. doxygendefine:: PYBIND11_EMBEDDED_MODULE

.. doxygenfunction:: initialize_interpreter

.. doxygenfunction:: finalize_interpreter

.. doxygenclass:: scoped_interpreter

Redirecting C++ streams
=======================

.. doxygenclass:: scoped_ostream_redirect

.. doxygenclass:: scoped_estream_redirect

.. doxygenfunction:: add_ostream_redirect

Python built-in functions
=========================

.. doxygengroup:: python_builtins
    :members:

Exceptions
==========

.. doxygenclass:: error_already_set
    :members:

.. doxygenclass:: builtin_exception
    :members:


Literals
========

.. doxygennamespace:: literals
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`
			`=============================================`

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:: module`
			`: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
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`