advanced/cast/custom.rst

0001 Custom type casters
0002 ===================
0003
0004 In very rare cases, applications may require custom type casters that cannot be
0005 expressed using the abstractions provided by pybind11, thus requiring raw
0006 Python C API calls. This is fairly advanced usage and should only be pursued by
0007 experts who are familiar with the intricacies of Python reference counting.
0008
0009 The following snippets demonstrate how this works for a very simple ``inty``
0010 type that that should be convertible from Python types that provide a
0011 ``__int__(self)`` method.
0012
0013 .. code-block:: cpp
0014
0015     struct inty { long long_value; };
0016
0017     void print(inty s) {
0018         std::cout << s.long_value << std::endl;
0019     }
0020
0021 The following Python snippet demonstrates the intended usage from the Python side:
0022
0023 .. code-block:: python
0024
0025     class A:
0026         def __int__(self):
0027             return 123
0028
0029
0030     from example import print
0031
0032     print(A())
0033
0034 To register the necessary conversion routines, it is necessary to add an
0035 instantiation of the ``pybind11::detail::type_caster<T>`` template.
0036 Although this is an implementation detail, adding an instantiation of this
0037 type is explicitly allowed.
0038
0039 .. code-block:: cpp
0040
0041     namespace PYBIND11_NAMESPACE { namespace detail {
0042         template <> struct type_caster<inty> {
0043         public:
0044             /**
0045              * This macro establishes the name 'inty' in
0046              * function signatures and declares a local variable
0047              * 'value' of type inty
0048              */
0049             PYBIND11_TYPE_CASTER(inty, const_name("inty"));
0050
0051             /**
0052              * Conversion part 1 (Python->C++): convert a PyObject into a inty
0053              * instance or return false upon failure. The second argument
0054              * indicates whether implicit conversions should be applied.
0055              */
0056             bool load(handle src, bool) {
0057                 /* Extract PyObject from handle */
0058                 PyObject *source = src.ptr();
0059                 /* Try converting into a Python integer value */
0060                 PyObject *tmp = PyNumber_Long(source);
0061                 if (!tmp)
0062                     return false;
0063                 /* Now try to convert into a C++ int */
0064                 value.long_value = PyLong_AsLong(tmp);
0065                 Py_DECREF(tmp);
0066                 /* Ensure return code was OK (to avoid out-of-range errors etc) */
0067                 return !(value.long_value == -1 && !PyErr_Occurred());
0068             }
0069
0070             /**
0071              * Conversion part 2 (C++ -> Python): convert an inty instance into
0072              * a Python object. The second and third arguments are used to
0073              * indicate the return value policy and parent object (for
0074              * ``return_value_policy::reference_internal``) and are generally
0075              * ignored by implicit casters.
0076              */
0077             static handle cast(inty src, return_value_policy /* policy */, handle /* parent */) {
0078                 return PyLong_FromLong(src.long_value);
0079             }
0080         };
0081     }} // namespace PYBIND11_NAMESPACE::detail
0082
0083 .. note::
0084
0085     A ``type_caster<T>`` defined with ``PYBIND11_TYPE_CASTER(T, ...)`` requires
0086     that ``T`` is default-constructible (``value`` is first default constructed
0087     and then ``load()`` assigns to it).
0088
0089 .. warning::
0090
0091     When using custom type casters, it's important to declare them consistently
0092     in every compilation unit of the Python extension module. Otherwise,
0093     undefined behavior can ensue.