Cython: `object` vs `PyObject*`

[kne42]

From my (limited) understanding from reading the Cython includes directory along with the CPython API, in many cases it seems that object is used interchangeably with PyObject*. However, the compiler complains about not being able to convert between the two when again, they appear to be interchangeable.

So it seems that one of the following holds true:

• object and PyObject* are equivalent and the Cython compiler has a bug where it does not consider object a shorthand for PyObject*.
• object and PyObject* are not equivalent and the Includes directory has .pxd files with wrong specifications.

[scoder]

Hmm, right, that's probably worth explaining somewhere.

object is a refcounted owned reference, PyObject* is a non-refcounted (usually borrowed) pointer to an object. There is no dedicated borrowed reference type in Cython, that's why we use the pointer type for it. Converting between a pointer (any pointer in fact, also void*) and an owned object reference is done through a cast, either obj = <object>ptr (which increases the refcount => owned reference) or ptr = <PyObject*>obj (which leaves the refcount allone => borrowed reference).

PR welcome that puts that explanation into a reasonable place.

[gmc444-b]

One place where this could be clarified here: https://cython.readthedocs.io/en/latest/src/userguide/language_basics.html?highlight=%22except%20%20%22#python-objects-as-parameters-and-return-values

At the C/C++ level, the function would be declared as returning PyObject*, but in Cython it can be declared as returning object explicitly as well as implicitly.