classification
Title: C API documentation must document if returned object is a borrowed reference or strong reference
Type: behavior Stage:
Components: C API, Documentation Versions: Python 3.10
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: baruch.sterin, docs@python, josh.r, matrixise, meador.inge, nanjekyejoannah, serhiy.storchaka
Priority: normal Keywords:

Created on 2012-03-04 04:18 by baruch.sterin, last changed 2020-07-05 01:13 by nanjekyejoannah.

Messages (5)
msg154877 - (view) Author: Baruch Sterin (baruch.sterin) Date: 2012-03-04 04:18
In addition to the description text, most C API functions have a one-line, emphasized specification whether they return a new or a borrowed reference. (e.g. 'Return value: New reference.').

The following API functions are missing that. Some of them, like PyMemoryView_FromBuffer(), have descriptions that are clear, but it would still be nice to have an unambiguous statement like most other API functions have.

The list has been generated automatically, so it might contain some errors.

Doc/c-api/arg.rst:  Py_VaBuildValue
Doc/c-api/buffer.rst:  PyMemoryView_FromBuffer
Doc/c-api/buffer.rst:  PyMemoryView_FromObject
Doc/c-api/buffer.rst:  PyMemoryView_GetContiguous
Doc/c-api/bytearray.rst:  PyByteArray_Concat
Doc/c-api/bytearray.rst:  PyByteArray_FromObject
Doc/c-api/bytearray.rst:  PyByteArray_FromStringAndSize
Doc/c-api/code.rst:  PyCode_New
Doc/c-api/codec.rst:  PyCodec_BackslashReplaceErrors
Doc/c-api/codec.rst:  PyCodec_Decode
Doc/c-api/codec.rst:  PyCodec_Decoder
Doc/c-api/codec.rst:  PyCodec_Encode
Doc/c-api/codec.rst:  PyCodec_Encoder
Doc/c-api/codec.rst:  PyCodec_IgnoreErrors
Doc/c-api/codec.rst:  PyCodec_IncrementalDecoder
Doc/c-api/codec.rst:  PyCodec_IncrementalEncoder
Doc/c-api/codec.rst:  PyCodec_LookupError
Doc/c-api/codec.rst:  PyCodec_ReplaceErrors
Doc/c-api/codec.rst:  PyCodec_StreamReader
Doc/c-api/codec.rst:  PyCodec_StreamWriter
Doc/c-api/codec.rst:  PyCodec_StrictErrors
Doc/c-api/codec.rst:  PyCodec_XMLCharRefReplaceErrors
Doc/c-api/exceptions.rst:  PyUnicodeDecodeError_Create
Doc/c-api/exceptions.rst:  PyUnicodeDecodeError_GetEncoding
Doc/c-api/exceptions.rst:  PyUnicodeDecodeError_GetObject
Doc/c-api/exceptions.rst:  PyUnicodeDecodeError_GetReason
Doc/c-api/exceptions.rst:  PyUnicodeEncodeError_Create
Doc/c-api/exceptions.rst:  PyUnicodeTranslateError_Create
Doc/c-api/float.rst:  PyFloat_GetInfo
Doc/c-api/import.rst:  PyImport_GetImporter
Doc/c-api/import.rst:  PyImport_ImportModuleNoBlock
Doc/c-api/import.rst:  _PyImport_FindExtension
Doc/c-api/import.rst:  _PyImport_FixupExtension
Doc/c-api/init.rst:  PyEval_GetCallStats
Doc/c-api/int.rst:  PyInt_FromSize_t
Doc/c-api/long.rst:  PyLong_FromSize_t
Doc/c-api/long.rst:  PyLong_FromSsize_t
Doc/c-api/number.rst:  PyNumber_Index
Doc/c-api/number.rst:  PyNumber_ToBase
Doc/c-api/object.rst:  PyObject_Bytes
Doc/c-api/object.rst:  PyObject_GenericGetAttr
Doc/c-api/unicode.rst:  PyUnicode_AsUTF32String
Doc/c-api/unicode.rst:  PyUnicode_DecodeMBCSStateful
Doc/c-api/unicode.rst:  PyUnicode_DecodeUTF32
Doc/c-api/unicode.rst:  PyUnicode_DecodeUTF32Stateful
Doc/c-api/unicode.rst:  PyUnicode_DecodeUTF7
Doc/c-api/unicode.rst:  PyUnicode_DecodeUTF7Stateful
Doc/c-api/unicode.rst:  PyUnicode_EncodeUTF32
Doc/c-api/unicode.rst:  PyUnicode_EncodeUTF7
Doc/c-api/veryhigh.rst:  PyEval_EvalCodeEx
Doc/c-api/veryhigh.rst:  PyEval_EvalFrame
Doc/c-api/veryhigh.rst:  PyEval_EvalFrameEx
msg222182 - (view) Author: Mark Lawrence (BreamoreBoy) * Date: 2014-07-03 14:05
Can someone comment please as I'm not brave enough to touch the C code or docs.
msg222248 - (view) Author: Josh Rosenberg (josh.r) * (Python triager) Date: 2014-07-04 00:39
If any of these actually return borrowed references, I'd consider it a serious documentation bug to not mention it. New reference semantics are the default, and while it's best to call them out, it can be assumed in most cases. Returning borrowed references without a big honking "not a normal function" flag in the docs causes a big problem.

Heck, the lack of such a big warning flag on PyDict_Next (which doesn't return a PyObject, but populates via a double pointer) caused me a major headache recently when I DECREF-ed the resulting objects. Totally my fault (the description says they're borrowed), but I rely on that "Returns: Borrowed Reference" header so much that I made a dumb mistake.
msg338062 - (view) Author: St├ęphane Wirtel (matrixise) * (Python committer) Date: 2019-03-16 08:07
I would like to work on this issue.
msg338064 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2019-03-16 08:22
This may be fixed recently (see issue18085, issue32077, issue35475 etc). Just check that this is true for all reported functions.
History
Date User Action Args
2020-07-05 01:13:45nanjekyejoannahsetnosy: + nanjekyejoannah
2020-06-25 09:48:44vstinnersettitle: Documentation for some C APIs is missing clear specification of the type of reference they return -> C API documentation must document if returned object is a borrowed reference or strong reference
components: + C API
versions: + Python 3.10, - Python 3.8
2019-03-16 08:22:30serhiy.storchakasetnosy: + serhiy.storchaka
messages: + msg338064
2019-03-16 08:07:36matrixisesetnosy: + matrixise

messages: + msg338062
versions: + Python 3.8, - Python 2.7
2019-03-16 00:12:58BreamoreBoysetnosy: - BreamoreBoy
2014-07-04 00:39:31josh.rsetnosy: + josh.r
messages: + msg222248
2014-07-03 14:05:47BreamoreBoysetnosy: + BreamoreBoy
messages: + msg222182
2012-03-05 04:50:39meador.ingesetnosy: + meador.inge
2012-03-04 04:18:58baruch.sterincreate