matrixise · Sep 12, 2019 · Sep 7, 2019 · Sep 7, 2019 · Sep 7, 2019 · Sep 7, 2019
diff --git a/Doc/c-api/module.rst b/Doc/c-api/module.rst
@@ -419,6 +419,21 @@ state:
    be used from the module's initialization function.  This steals a reference to
    *value*.  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)) {
+             Py_DECREF(module);
+             Py_DECREF(spam);
+             return NULL;
+         }
+
 .. c:function:: int PyModule_AddIntConstant(PyObject *module, const char *name, long value)
 
    Add an integer constant to *module* as *name*.  This convenience function can be

diff --git a/Doc/extending/extending.rst b/Doc/extending/extending.rst
@@ -222,7 +222,12 @@ with an exception object (leaving out the error checking for now)::
 
        SpamError = PyErr_NewException("spam.error", NULL, NULL);
        Py_INCREF(SpamError);
-       PyModule_AddObject(m, "error", SpamError);
+       if (PyModule_AddObject(m, "error", SpamError)) {
+           Py_DECREF(SpamError);
+           Py_DECREF(m);
+           return NULL;
+       }
+
        return m;
    }
 
@@ -1261,8 +1266,17 @@ function must take care of initializing the C API pointer array::
        /* Create a Capsule containing the API pointer array's address */
        c_api_object = PyCapsule_New((void *)PySpam_API, "spam._C_API", NULL);
 
-       if (c_api_object != NULL)
-           PyModule_AddObject(m, "_C_API", c_api_object);
+       if (c_api_object == NULL) {
+           Py_DECREF(m);
+           return NULL;
+       }
+
+       if (PyModule_AddObject(m, "_C_API", c_api_object)) {
+           Py_DECREF(c_api_object);
+           Py_DECREF(m);
+           return NULL;
+       }
+
        return m;
    }
 

diff --git a/Doc/extending/newtypes_tutorial.rst b/Doc/extending/newtypes_tutorial.rst
@@ -179,7 +179,12 @@ This initializes the :class:`Custom` type, filling in a number of members
 to the appropriate default values, including :attr:`ob_type` that we initially
 set to *NULL*. ::
 
-   PyModule_AddObject(m, "Custom", (PyObject *) &CustomType);
+   Py_INCREF(&CustomType);
+   if (PyModule_AddObject(m, "Custom", (PyObject *) &CustomType)) {
+       Py_DECREF(&CustomType);
+       PY_DECREF(m);
+       return NULL;
+   }
 
 This adds the type to the module dictionary.  This allows us to create
 :class:`Custom` instances by calling the :class:`Custom` class:
@@ -864,7 +869,12 @@ function::
            return NULL;
 
        Py_INCREF(&SubListType);
-       PyModule_AddObject(m, "SubList", (PyObject *) &SubListType);
+       if (PyModule_AddObject(m, "SubList", (PyObject *) &SubListType)) {
+           Py_DECREF(&SubListType);
+           Py_DECREF(m);
+           return NULL;
+       }
+
        return m;
    }
 

diff --git a/Doc/includes/custom.c b/Doc/includes/custom.c
@@ -35,6 +35,11 @@ PyInit_custom(void)
         return NULL;
 
     Py_INCREF(&CustomType);
-    PyModule_AddObject(m, "Custom", (PyObject *) &CustomType);
+    if (PyModule_AddObject(m, "Custom", (PyObject *) &CustomType)) {
+        Py_DECREF(&CustomType);
+        PY_DECREF(m);
+        return NULL;
+    }
+
     return m;
 }
diff --git a/Doc/includes/custom2.c b/Doc/includes/custom2.c
@@ -128,6 +128,11 @@ PyInit_custom2(void)
         return NULL;
 
     Py_INCREF(&CustomType);
-    PyModule_AddObject(m, "Custom", (PyObject *) &CustomType);
+    if (PyModule_AddObject(m, "Custom", (PyObject *) &CustomType)) {
+        Py_DECREF(&CustomType);
+        Py_DECREF(m);
+        return NULL;
+    }
+
     return m;
 }
diff --git a/Doc/includes/custom3.c b/Doc/includes/custom3.c
@@ -179,6 +179,11 @@ PyInit_custom3(void)
         return NULL;
 
     Py_INCREF(&CustomType);
-    PyModule_AddObject(m, "Custom", (PyObject *) &CustomType);
+    if (PyModule_AddObject(m, "Custom", (PyObject *) &CustomType)) {
+        Py_DECREF(&CustomType);
+        Py_DECREF(m);
+        return NULL;
+    }
+
     return m;
 }
diff --git a/Doc/includes/custom4.c b/Doc/includes/custom4.c
@@ -193,6 +193,11 @@ PyInit_custom4(void)
         return NULL;
 
     Py_INCREF(&CustomType);
-    PyModule_AddObject(m, "Custom", (PyObject *) &CustomType);
+    if (PyModule_AddObject(m, "Custom", (PyObject *) &CustomType)) {
+        Py_DECREF(&CustomType);
+        Py_DECREF(m);
+        return NULL;
+    }
+
     return m;
 }
diff --git a/Doc/includes/sublist.c b/Doc/includes/sublist.c
@@ -59,6 +59,11 @@ PyInit_sublist(void)
         return NULL;
 
     Py_INCREF(&SubListType);
-    PyModule_AddObject(m, "SubList", (PyObject *) &SubListType);
+    if ((m, "SubList", (PyObject *) &SubListType)) {
+        Py_DECREF(&SubListType);
+        Py_DECREF(m);
+        return NULL;
+    }
+
     return m;
 }
diff --git a/Misc/NEWS.d/next/Documentation/2019-09-07-15-55-46.bpo-26868.Raw0Gd.rst b/Misc/NEWS.d/next/Documentation/2019-09-07-15-55-46.bpo-26868.Raw0Gd.rst
@@ -0,0 +1 @@
+Fix example usage of :c:func:`PyModule_AddObject` to properly handle errors.
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		Fix example usage of :c:func:`PyModule_AddObject` to properly handle errors.