[issue45939] PyErr_SetObject documentation lacks mention of reference counting

[Eric Blake]

New submission from Eric Blake <eblake at redhat.com>:

While PyErr_SetString is obvious that you do not have to worry about the reference count of 'exception', the documentation for PyErr_SetObject is silent on whether it steals or adds a reference to 'value'.  This is particularly confusing, since other functions on the page (like PyErr_Restore) are explicit about stealing references.  Looking at non-canonical documentation, I found https://docstore.mik.ua/orelly/other/python/0596001886_pythonian-chp-24-sect-1.html which claims PyErr_SetObject steals a reference to 'value'.  But that is wrong; looking at the source code for _PyErr_SetString, it becomes obvious that once you use SetObject, the reference count will be increased, and the caller can release its own reference because nothing was stolen.

I noticed this lack of documentation when trying to debug a memory leak in nbdsh: https://listman.redhat.com/archives/libguestfs/2021-November/msg00280.html

----------
assignee: docs at python
components: Documentation
messages: 407381
nosy: docs at python, eblake
priority: normal
severity: normal
status: open
title: PyErr_SetObject documentation lacks mention of reference counting

_______________________________________
Python tracker <report at bugs.python.org>
<https://bugs.python.org/issue45939>
_______________________________________