diff --git a/docs/src/userguide/language_basics.rst b/docs/src/userguide/language_basics.rst index 25dc0be9cd2992110d93c19dd74943a74db4c438..5b5f5f6524950b67bfba33942ea1c41774724cff 100644 --- a/docs/src/userguide/language_basics.rst +++ b/docs/src/userguide/language_basics.rst @@ -526,26 +526,33 @@ Where C uses ``"("`` and ``")"``, Cython uses ``"<"`` and ``">"``. For example:: cdef float *q p = <char*>q -If one of the types is a Python object for ``<type>x``, Cython will try to do a coercion. +When casting a C value to a Python object type or vice versa, +Cython will attempt a coercion. Simple examples are casts like ``<int>pyobj``, +which converts a Python number to a plain C ``int`` value, or ``<bytes>charptr``, +which copies a C ``char*`` string into a new Python bytes object. - .. note:: Cython will not stop a casting where there is no conversion, but it will emit a warning. + .. note:: Cython will not prevent a redundant cast, but emits a warning for it. To get the address of some Python object, use a cast to a pointer type like ``<void*>`` or ``<PyObject*>``. -You can also get the python object from a pointer to this object by doing ``<object>``. +You can also cast a C pointer back to a Python object reference +with ``<object>``, or a more specific builtin or extension type +(e.g. ``<MyExtType>ptr``). This will increase the reference count of +the object by one, i.e. the cast returns an owned reference. Here is an example:: from __future__ import print_function from cpython.ref cimport PyObject + from libc.stdint cimport uintptr_t python_string = "foo" cdef void* ptr = <void*>python_string - cdef long adress_in_c = <long>ptr + cdef uintptr_t adress_in_c = <uintptr_t>ptr address_from_void = adress_in_c # address_from_void is a python int cdef PyObject* ptr2 = <PyObject*>python_string - cdef long address_in_c2 = <long>ptr2 + cdef uintptr_t address_in_c2 = <uintptr_t>ptr2 address_from_PyObject = address_in_c2 # address_from_PyObject is a python int assert address_from_void == address_from_PyObject == id(python_string)