➜
This issue tracker has been migrated to GitHub,
and is currently read-only.
For more information,
see the GitHub FAQs in the Python's Developer Guide.
Created on 2012-03-04 04:18 by baruch.sterin, last changed 2022-04-11 14:57 by admin. This issue is now closed.
| Messages (6) | |||
|---|---|---|---|
| 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) *  |
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) *  |
Date: 2019-03-16 08:07 | |
I would like to work on this issue. |
|||
| msg338064 - (view) | Author: Serhiy Storchaka (serhiy.storchaka) * |
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. |
|||
| msg389259 - (view) | Author: Irit Katriel (iritkatriel) * |
Date: 2021-03-21 18:55 | |
This was fixed for all the functions listed by the OP, except a few that no longer exist AFAICT: 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 |
|||
| History | |||
|---|---|---|---|
| Date | User | Action | Args |
| 2022-04-11 14:57:27 | admin | set | github: 58397 |
| 2021-03-21 18:55:30 | iritkatriel | set | status: open -> closed nosy: + iritkatriel messages: + msg389259 resolution: fixed stage: resolved |
| 2020-07-05 01:13:45 | nanjekyejoannah | set | nosy:
+ nanjekyejoannah |
| 2020-06-25 09:48:44 | vstinner | set | title: 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:30 | serhiy.storchaka | set | nosy:
+ serhiy.storchaka messages: + msg338064 |
| 2019-03-16 08:07:36 | matrixise | set | nosy:
+ matrixise messages: + msg338062 versions: + Python 3.8, - Python 2.7 |
| 2019-03-16 00:12:58 | BreamoreBoy | set | nosy:
- BreamoreBoy |
| 2014-07-04 00:39:31 | josh.r | set | nosy:
+ josh.r messages: + msg222248 |
| 2014-07-03 14:05:47 | BreamoreBoy | set | nosy:
+ BreamoreBoy messages: + msg222182 |
| 2012-03-05 04:50:39 | meador.inge | set | nosy:
+ meador.inge |
| 2012-03-04 04:18:58 | baruch.sterin | create | |