documentation improvements
diff --git a/docs/_static/theme_overrides.css b/docs/_static/theme_overrides.css
index f678ab5..1071809 100644
--- a/docs/_static/theme_overrides.css
+++ b/docs/_static/theme_overrides.css
@@ -5,3 +5,7 @@
.rst-content table.docutils td {
vertical-align: top !important;
}
+div[class^='highlight'] pre {
+ white-space: pre;
+ white-space: pre-wrap;
+}
diff --git a/docs/advanced.rst b/docs/advanced.rst
index 534a0f2..1c6f6e0 100644
--- a/docs/advanced.rst
+++ b/docs/advanced.rst
@@ -416,12 +416,12 @@
+==================================================+============================================================================+
| :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 @@
| :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 @@
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 @@
==============
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
diff --git a/docs/basics.rst b/docs/basics.rst
index 42ff6e4..a2a6084 100644
--- a/docs/basics.rst
+++ b/docs/basics.rst
@@ -253,7 +253,9 @@
+----------------------------+--------------------------+-----------------------+
| 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 |
+----------------------------+--------------------------+-----------------------+
diff --git a/docs/changelog.rst b/docs/changelog.rst
index 63806d8..46c8518 100644
--- a/docs/changelog.rst
+++ b/docs/changelog.rst
@@ -8,13 +8,13 @@
* 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)
diff --git a/docs/conf.py b/docs/conf.py
index a05acc3..ca76e19 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -158,7 +158,7 @@
# 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
diff --git a/docs/faq.rst b/docs/faq.rst
index 7e45b8c..2556105 100644
--- a/docs/faq.rst
+++ b/docs/faq.rst
@@ -144,7 +144,7 @@
.. 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:
diff --git a/include/pybind11/common.h b/include/pybind11/common.h
index aba804f..8bfa778 100644
--- a/include/pybind11/common.h
+++ b/include/pybind11/common.h
@@ -149,7 +149,7 @@
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 @@
/** 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
};