Zengtudor/pybind11
1
0
Fork 0
mirror of https://github.com/pybind/pybind11.git synced 2024-11-21 20:55:11 +00:00
Code Issues Packages Projects Releases Wiki Activity

documentation improvements

Browse Source
This commit is contained in:
Wenzel Jakob 2016-04-26 23:19:19 +02:00
parent d361a57863
commit e84f557edf
7 changed files with 67 additions and 46 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
docs/_static/theme_overrides.css vendored
View File

@ -5,3 +5,7 @@
.rst-content table.docutils td {
vertical-align: top !important;
}
div[class^='highlight'] pre {
white-space: pre;
white-space: pre-wrap;
}

77
docs/advanced.rst
View File

@ -416,12 +416,12 @@ functions. The default policy is :enum:`return_value_policy::automatic`.
+==================================================+============================================================================+
| :enum:`return_value_policy::automatic` | This is the default return value policy, which falls back to the policy |
| | :enum:`return_value_policy::take_ownership` when the return value is a |
| | pointer. Otherwise, it uses :enum::`return_value::move` or |
| | :enum::`return_value::copy` for rvalue and lvalue references, respectively.|
| | pointer. Otherwise, it uses :enum:`return_value::move` or |
| | :enum:`return_value::copy` for rvalue and lvalue references, respectively. |
| | See below for a description of what all of these different policies do. |
+--------------------------------------------------+----------------------------------------------------------------------------+
| :enum:`return_value_policy::automatic_reference` | As above, but use policy :enum:`return_value_policy::reference` when the |
| | return value is a pointer. |
| | return value is a pointer. You probably won't need to use this. |
+--------------------------------------------------+----------------------------------------------------------------------------+
| :enum:`return_value_policy::take_ownership` | Reference an existing object (i.e. do not create a new copy) and take |
| | ownership. Python will call the destructor and delete operator when the |
@ -439,36 +439,22 @@ functions. The default policy is :enum:`return_value_policy::automatic`.
| :enum:`return_value_policy::reference` | Reference an existing object, but do not take ownership. The C++ side is |
| | responsible for managing the object's lifetime and deallocating it when |
| | it is no longer used. Warning: undefined behavior will ensue when the C++ |
| | side deletes an object that is still referenced by Python. |
| | side deletes an object that is still referenced and used by Python. |
+--------------------------------------------------+----------------------------------------------------------------------------+
| :enum:`return_value_policy::reference_internal` | Reference the object, but do not take ownership. The object is considered |
| | be owned by the C++ instance whose method or property returned it. The |
| | Python object will increase the reference count of this 'parent' by 1 |
| | to ensure that it won't be deallocated while Python is using the 'child' |
| :enum:`return_value_policy::reference_internal` | This policy only applies to methods and properties. It references the |
| | object without taking ownership similar to the above |
| | :enum:`return_value_policy::reference` policy. In contrast to that policy, |
| | the function or property's implicit ``this`` argument (called the *parent*)|
| | is considered to be the the owner of the return value (the *child*). |
| | pybind11 then couples the lifetime of the parent to the child via a |
| | reference relationship that ensures that the parent cannot be garbage |
| | collected while Python is still using the child. More advanced variations |
| | of this scheme are also possible using combinations of |
| | :enum:`return_value_policy::reference` and the :class:`keep_alive` call |
| | policy described next. |
+--------------------------------------------------+----------------------------------------------------------------------------+
.. warning::
Code with invalid call policies might access unitialized memory or free
data structures multiple times, which can lead to hard-to-debug
non-determinism and segmentation faults, hence it is worth spending the
time to understand all the different options above.
.. note::
The next section on :ref:`call_policies` discusses *call policies* that can be
specified *in addition* to a return value policy from the list above. Call
policies indicate reference relationships that can involve both return values
and parameters of functions.
.. note::
As an alternative to elaborate call policies and lifetime management logic,
consider using smart pointers (see :ref:`smart_pointers` for details) that
can be used to share reference count information between C++ and Python.
See below for an example that uses the
The following example snippet shows a use case of the
:enum:`return_value_policy::reference_internal` policy.
.. code-block:: cpp
@ -485,11 +471,34 @@ See below for an example that uses the
py::class_<Example>(m, "Example")
.def(py::init<>())
.def("get_internal", &Example::get_internal, "Return the internal data", py::return_value_policy::reference_internal);
.def("get_internal", &Example::get_internal, "Return the internal data",
py::return_value_policy::reference_internal);
return m.ptr();
}
.. warning::
Code with invalid call policies might access unitialized memory or free
data structures multiple times, which can lead to hard-to-debug
non-determinism and segmentation faults, hence it is worth spending the
time to understand all the different options in the table above.
.. note::
The next section on :ref:`call_policies` discusses *call policies* that can be
specified *in addition* to a return value policy from the list above. Call
policies indicate reference relationships that can involve both return values
and parameters of functions.
.. note::
As an alternative to elaborate call policies and lifetime management logic,
consider using smart pointers (see the section on :ref:`smart_pointers` for
details). Smart pointers can tell whether an object is still referenced from
C++ or Python, which generally eliminates the kinds of inconsistencies that
can lead to crashes or undefined behavior. For functions returning smart
pointers, it is not necessary to specify a return value policy.
.. _call_policies:
@ -590,10 +599,10 @@ Smart pointers
==============
This section explains how to pass values that are wrapped in "smart" pointer
types with internal reference counting. For simpler C++11 unique pointers,
please refer to the previous section.
types with internal reference counting. For the simpler C++11 unique pointers,
refer to the previous section.
The binding generator for classes (:class:`class_`) takes an optional second
The binding generator for classes, :class:`class_`, takes an optional second
template type, which denotes a special *holder* type that is used to manage
references to the object. When wrapping a type named ``Type``, the default
value of this template parameter is ``std::unique_ptr<Type>``, which means that

4
docs/basics.rst
View File

@ -253,7 +253,9 @@ as arguments and return values, refer to the section on binding :ref:`classes`.
+----------------------------+--------------------------+-----------------------+
| std::pair<T1, T2> | Pair of two custom types | pybind11/pybind11.h |
+----------------------------+--------------------------+-----------------------+
| std::tuple<....> | Arbitrary tuple of types | pybind11/pybind11.h |
| std::tuple<...> | Arbitrary tuple of types | pybind11/pybind11.h |
+----------------------------+--------------------------+-----------------------+
| std::reference_wrapper<...>| Reference type wrapper | pybind11/pybind11.h |
+----------------------------+--------------------------+-----------------------+
| std::complex<T> | Complex numbers | pybind11/complex.h |
+----------------------------+--------------------------+-----------------------+

4
docs/changelog.rst
View File

@ -8,13 +8,13 @@ Changelog
* Added a new ``move`` return value policy that triggers C++11 move semantics.
The automatic return value policy falls back to this case when a rvalue
reference is encountered
* Significantly more general GIL state routines that are used instead of
Python's troublesome ``PyGILState_Ensure`` and ``PyGILState_Release`` API
* ``keep_alive`` fix: don't fail when there is no patient
* ``functional.h``: acquire the GIL before calling Python function
* Added Python RAII type wrappers ``none`` and ``iterable``
* Added ``*args`` and ``*kwargs`` pass-through parameters to
``pybind11.get_include()`` function
* Significantly more general GIL state routines that are used instead of
Python's troublesome ``PyGILState_Ensure`` and ``PyGILState_Release`` API.
* Documentation improvements: ``opaque``, return value policies
1.5 (April 21, 2016)

2
docs/conf.py
View File

@ -158,7 +158,7 @@ else:
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['.static']
html_static_path = ['_static']
# Add any extra paths that contain custom files (such as robots.txt or
# .htaccess) here, relative to this directory. These files are copied

2
docs/faq.rst
View File

@ -144,7 +144,7 @@ the included test suite contains the following symbol:
.. code-block:: cpp
__ZN8pybind1112cpp_functionC1Iv8Example2JRNSt3__16vectorINS3_12basic_stringIwNS3_11char_traitsIwEENS3_9allocatorIwEEEENS8_ISA_EEEEEJNS_4nameENS_7siblingENS_9is_methodEA28_cEEEMT0_FT_DpT1_EDpRKT2_
__ZN8pybind1112cpp_functionC1Iv8Example2JRNSt3__16vectorINS3_12basic_stringIwNS3_11char_traitsIwEENS​3_9allocatorIwEEEENS8_ISA_EEEEEJNS_4nameENS_7siblingENS_9is_methodEA28_cEEEMT0_FT_DpT1_EDpRKT2_
which is the mangled form of the following function type:

20
include/pybind11/common.h
View File

@ -149,7 +149,7 @@ enum class return_value_policy : int {
automatic = 0,
/** As above, but use policy return_value_policy::reference when the return
value is a pointer. */
value is a pointer. You probably won't need to use this. */
automatic_reference,
/** Reference an existing object (i.e. do not create a new copy) and take
@ -172,14 +172,20 @@ enum class return_value_policy : int {
/** Reference an existing object, but do not take ownership. The C++ side
is responsible for managing the object’s lifetime and deallocating it
when it is no longer used. Warning: undefined behavior will ensue when
the C++ side deletes an object that is still referenced by Python. */
the C++ side deletes an object that is still referenced and used by
Python. */
reference,
/** Reference the object, but do not take ownership. The object is
considered be owned by the C++ instance whose method or property
returned it. The Python object will increase the reference count of this
‘parent’ by 1 to ensure that it won’t be deallocated while Python is
using the ‘child’ */
/** This policy only applies to methods and properties. It references the
object without taking ownership similar to the above
return_value_policy::reference policy. In contrast to that policy, the
function or property’s implicit this argument (called the parent) is
considered to be the the owner of the return value (the child).
pybind11 then couples the lifetime of the parent to the child via a
reference relationship that ensures that the parent cannot be garbage
collected while Python is still using the child. More advanced
variations of this scheme are also possible using combinations of
return_value_policy::reference and the keep_alive call policy */
reference_internal
};