From 9cd58b9cc62ccbfac82e1e12c93731e3157e7cfb Mon Sep 17 00:00:00 2001 From: Irit Katriel Date: Fri, 27 Oct 2023 17:39:19 +0100 Subject: [PATCH] reword reference management paragraph --- peps/pep-0733.rst | 19 ++++++++++++++----- 1 file changed, 14 insertions(+), 5 deletions(-) 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