bpo-26868: Fix example usage of PyModule_AddObject. (#15725)
* Add a note to the PyModule_AddObject docs.
* Correct example usages of PyModule_AddObject.
* Whitespace.
* Clean up wording.
* 📜🤖 Added by blurb_it.
* First code review.
* Add < 0 in the tests with PyModule_AddObject
diff --git a/Doc/c-api/module.rst b/Doc/c-api/module.rst
index 68cbda2..feca1ec 100644
--- a/Doc/c-api/module.rst
+++ b/Doc/c-api/module.rst
@@ -417,7 +417,22 @@
Add an object to *module* as *name*. This is a convenience function which can
be used from the module's initialization function. This steals a reference to
- *value*. Return ``-1`` on error, ``0`` on success.
+ *value* on success. Return ``-1`` on error, ``0`` on success.
+
+ .. note::
+
+ Unlike other functions that steal references, ``PyModule_AddObject()`` only
+ decrements the reference count of *value* **on success**.
+
+ This means that its return value must be checked, and calling code must
+ :c:func:`Py_DECREF` *value* manually on error. Example usage::
+
+ Py_INCREF(spam);
+ if (PyModule_AddObject(module, "spam", spam) < 0) {
+ Py_DECREF(module);
+ Py_DECREF(spam);
+ return NULL;
+ }
.. c:function:: int PyModule_AddIntConstant(PyObject *module, const char *name, long value)