diff --git a/peps/pep-0733.rst b/peps/pep-0733.rst index 0d7dbb34330..74f1aa64183 100644 --- a/peps/pep-0733.rst +++ b/peps/pep-0733.rst @@ -366,17 +366,26 @@ different memory management schemes Object Reference Management --------------------------- -There are C API functions that return borrowed references, and -functions that decref arguments, but there isn't a -naming convention that makes this obvious, so this is error prone +There does not exist a consistent naming convention for functions +which makes their reference semantics obvious, and this leads to +error prone C API functions, where they do not follow the typical +behaviour. When a C API function returns a ``PyObject*``, the +caller typically gains ownership of a reference to the object. +However, there are exceptions where a function returns a +"borrowed" reference, which the caller can access but does not own +a reference to. Similarly, functions typically do not change the +ownership of references to their arguments, but there are +exceptions where a function "steals" a reference, i.e., the +ownership of the reference is permanently transferred from the +caller to the callee by the call [`Issue 8 `__ and `Issue 52 `__]. The terminology used to describe these situations in the documentation can also be improved [`Issue 11 `__]. -A more radical change is necessary in the case of a function that -returns a ``PyObject*`` that it did not incref (such as ``PyList_GetItem``) +A more radical change is necessary in the case of functions that +return "borrowed" references (such as ``PyList_GetItem``) [`Issue 5 `__ and `Issue 21 `__] or pointers to parts of the internal structure of an object