gh-86542: New C-APIs to simplify module attribute declaration

Doc/c-api/module.rst

@@ -571,6 +571,151 @@ state:
 
    .. versionadded:: 3.9
 
+.. c:function:: PyTypeObject * PyModule_AddNewTypeFromSpec(PyObject *module, PyType_Spec *spec, PyObject *base)
+
+   Initialize a new type and add it to *module*.
+   The function is equivalent to :c:func:`PyType_FromModuleAndSpec` followed
+   by :c:func:`PyModule_AddType`. *base* must be either ``NULL``, a single
+   type object, or a tuple of types.
+   Return ``NULL`` on error; otherwise a ``PyTypeObject *``, which can
+   be assigned to a module state object.
+
+   .. versionadded:: 3.10
+
+.. c:function:: PyObject * PyModule_AddNewException(PyObject *module, const char *name, const char *doc, PyObject *base, PyObject *dict)
+
+   Create a new exception and add it to *module*.
+   The function is equivalent to :c:func:`PyErr_NewExceptionWithDoc` followed
+   by :c:func:`PyModule_AddObjectRef`. The name of the exception object is
+   taken from the last component of *name* after dot.
+   Return ``NULL`` on error; otherwise ``PyObject *``, which can be assigned
+   to a module state object.
+
+   .. versionadded:: 3.10
+
+.. c:function:: int PyModule_AddConstants(PyObject *module, PyModuleConst_Def *def)
+
+   Initialize module constants from a PyModuleConst_Def array. The function
+   provides a convenient way to declare module-level constants.
+   Return ``-1`` on error, ``0`` on success.
+
+   Example::
+
+      static PyObject*
+      example_call(PyObject *module)
+      {
+          return PyBytes_FromString("23");
+      }
+
+      #define EXAMPLE_INT 23
+      #define EXAMPLE_STRING "world"
+
+      static PyModuleConst_Def example_constants[] = {
+          PyModuleConst_None("none_value"),
+          PyModuleConst_Long("integer", 42),
+          PyModuleConst_ULong("unsigned", 42UL),
+          PyModuleConst_Bool("false_value", 0),
+          PyModuleConst_Bool("true_value", 1),
+      #ifdef Py_MATH_PI
+          PyModuleConst_Double("pi", Py_MATH_PI),
+      #endif
+          PyModuleConst_String("somestring", "Hello"),
+          PyModuleConst_Call("call", example_call),
+          PyModuleConst_LongMacro(EXAMPLE_INT),
+          PyModuleConst_StringMacro(EXAMPLE_STRING),
+          {NULL},
+      }
+
+      static int
+      example_init_constants(PyObject *module)
+      {
+          return PyModule_AddConstants(module, example_constants);
+      }
+
+      static PyModuleDef_Slot example_slots[] = {
+          {Py_mod_exec, example_init_constants},
+          {0, NULL}
+      };
+
+
+.. c:type:: PyModuleConst_Def
+
+   The values for *type* and the definition of the *value* union are
+   internal implementation details. Use any of the ``PyModuleConst_`` macros
+   to define entries. The array must be terminated by an entry with name
+   set to ``NULL``.
+
+   .. c:member:: const char *name
+
+      Attribute name.
+
+   .. c:member:: int type
+
+      Attribute type.
+
+   .. c:member:: void *value
+
+      Value of the module constant definition, whose meaning depends on
+      *type*.
+
+   .. versionadded:: 3.10
+
+.. c:macro:: PyModuleConst_None(name)
+
+   Add an entry for None.
+
+   .. versionadded:: 3.10
+
+.. c:macro:: PyModuleConst_Long(name, value)
+
+   Add an entry for an integer constant.
+
+   .. versionadded:: 3.10
+
+.. c:macro:: PyModuleConst_ULong(name, value)
+
+   Add an entry for an unsigned integer constant.
+
+   .. versionadded:: 3.10
+
+.. c:macro:: PyModuleConst_Bool(name, value)
+
+   Add an entry for a bool constant. ``0`` is false, ``1`` is true.
+
+   .. versionadded:: 3.10
+
+.. c:macro:: PyModuleConst_Double(name, value)
+
+   Add an entry for a float constant.
+
+   .. versionadded:: 3.10
+
+.. c:macro:: PyModuleConst_String(name, value)
+
+   Add an entry for a string constant.
+
+   .. versionadded:: 3.10
+
+.. c:macro:: PyModuleConst_Call(name, func)
+
+   Add an entry for a constant as returned by callback with signature
+   ``PyObject* (*func)(PyObject *module)``.
+
+   .. versionadded:: 3.10
+
+.. c:macro:: PyModuleConst_LongMacro(macro)
+
+   Add an entry for an int constant. The name and the value are taken from
+   *macro*.
+
+   .. versionadded:: 3.10
+
+.. c:macro:: PyModuleConst_StringMacro(macro)
+
+   Add an entry for a string constant. The name and the value are taken from
+   *macro*.
+
+   .. versionadded:: 3.10
 
 Module lookup
 ^^^^^^^^^^^^^

Doc/data/refcounts.dat

@@ -1325,6 +1325,10 @@ PyMethod_New:PyObject*:class:0:
 PyMethod_Self:PyObject*::0:
 PyMethod_Self:PyObject*:im:0:
 
+PyModule_AddConstants:int:::
+PyModule_AddConstants:PyObject*:module:0:
+PyModule_AddConstants:PyModuleConst_Def*:def::
+
 PyModule_AddFunctions:int:::
 PyModule_AddFunctions:PyObject*:module:0:
 PyModule_AddFunctions:PyMethodDef*:functions::
@@ -1343,6 +1347,18 @@ PyModule_AddObject:PyObject*:module:0:
 PyModule_AddObject:const char*:name::
 PyModule_AddObject:PyObject*:value:+1:
 
+PyModule_AddNewException:PyObject*::+1:
+PyModule_AddNewException:PyObject*:module:0:
+PyModule_AddNewException:const char*:name::
+PyModule_AddNewException:const char*:doc::
+PyModule_AddNewException:PyObject*:base:0:
+PyModule_AddNewException:PyObject*:dict:0:
+
+PyModule_AddNewTypeFromSpec:PyObject*::+1:
+PyModule_AddNewTypeFromSpec:PyObject*:module:0:
+PyModule_AddNewTypeFromSpec:PyType_spec*:spec::
+PyModule_AddNewTypeFromSpec:PyObject*:base:0:
+
 PyModule_AddStringConstant:int:::
 PyModule_AddStringConstant:PyObject*:module:0:
 PyModule_AddStringConstant:const char*:name::

Include/modsupport.h

@@ -154,6 +154,15 @@ PyAPI_FUNC(int) PyModule_AddType(PyObject *module, PyTypeObject *type);
 #define PyModule_AddIntMacro(m, c) PyModule_AddIntConstant(m, #c, c)
 #define PyModule_AddStringMacro(m, c) PyModule_AddStringConstant(m, #c, c)
 
+#if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x03100000
+/* New in 3.9 */
+PyAPI_FUNC(PyTypeObject *) PyModule_AddNewTypeFromSpec(
+    PyObject *module, PyType_Spec *spec, PyObject *base);
+PyAPI_FUNC(PyObject *) PyModule_AddNewException(
+    PyObject *module, const char *name, const char *doc,
+    PyObject *base, PyObject *dict);
+#endif
+
 #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x03050000
 /* New in 3.5 */
 PyAPI_FUNC(int) PyModule_SetDocString(PyObject *, const char *);

Include/moduleobject.h

@@ -72,6 +72,53 @@ typedef struct PyModuleDef_Slot{
 
 #endif /* New in 3.5 */
 
+struct PyModuleConst_Def;
+#if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x03100000
+/* New in 3.10 */
+enum _PyModuleConst_type {
+    _PyModuleConst_none_type = 1,
+    _PyModuleConst_long_type = 2,
+    _PyModuleConst_ulong_type = 3,
+    _PyModuleConst_bool_type = 4,
+    _PyModuleConst_double_type = 5,
+    _PyModuleConst_string_type = 6,
+    _PyModuleConst_call_type = 7,
+};
+
+typedef struct PyModuleConst_Def {
+    const char *name;
+    enum _PyModuleConst_type type;
+    union {
+        const char *m_str;
+        long m_long;
+        unsigned long m_ulong;
+        double m_double;
+        PyObject* (*m_call)(PyObject *module);
+    } value;
+} PyModuleConst_Def;
+
+PyAPI_FUNC(int) PyModule_AddConstants(PyObject *, PyModuleConst_Def *);
+
+#define PyModuleConst_None(name) \
+    {(name), _PyModuleConst_none_type, {.m_long=0}}
+#define PyModuleConst_Long(name, value) \
+    {(name), _PyModuleConst_long_type, {.m_long=(value)}}
+#define PyModuleConst_ULong(name, value) \
+    {(name), _PyModuleConst_ulong_type, {.m_ulong=(value)}}
+#define PyModuleConst_Bool(name, value) \
+    {(name), _PyModuleConst_bool_type, {.m_long=(value)}}
+#define PyModuleConst_Double(name, value) \
+    {(name), _PyModuleConst_double_type, {.m_double=(value)}}
+#define PyModuleConst_String(name, value) \
+    {(name), _PyModuleConst_string_type, {.m_str=(value)}}
+#define PyModuleConst_Call(name, value) \
+    {(name), _PyModuleConst_call_type, {.m_call=(value)}}
+
+#define PyModuleConst_LongMacro(m) PyModuleConst_Long(#m, m)
+#define PyModuleConst_StringMacro(m) PyModuleConst_String(#m, m)
+
+#endif /* New in 3.10 */
+
 typedef struct PyModuleDef{
   PyModuleDef_Base m_base;
   const char* m_name;

Lib/test/test_capi.py

@@ -971,5 +971,19 @@ def test_state_access(self):
                     increment_count(1, 2, 3)
 
 
+class Test_PyModuleConst_Def(unittest.TestCase):
+    def test_constants(self):
+        self.assertIs(_testcapi.const_none, None)
+        self.assertEqual(_testcapi.const_int, 42)
+        self.assertEqual(_testcapi.const_uint, _testcapi.ULONG_MAX)
+        self.assertIs(_testcapi.const_true, True)
+        self.assertIs(_testcapi.const_false, False)
+        self.assertEqual(_testcapi.const_almost_tau, 6.2831)
+        self.assertEqual(_testcapi.const_str, "Hello")
+        self.assertEqual(_testcapi.const_call, b"23")
+        self.assertEqual(_testcapi.CONST_INT, 7)
+        self.assertEqual(_testcapi.CONST_STRING, "world")
+
+
 if __name__ == "__main__":
     unittest.main()

Misc/NEWS.d/next/C API/2020-11-16-20-29-59.bpo-42376.vO9Tvu.rst

@@ -0,0 +1,3 @@
+Add new functions :c:func:`PyModule_AddConstants`,
+:c:func:`PyModule_AddNewTypeFromSpec`, :c:func:`PyModule_AddNewException` to
+simplify the declaration of attribute in modules.

Modules/_hashopenssl.c

@@ -2025,14 +2025,9 @@ hashlib_init_evptype(PyObject *module)
 {
     _hashlibstate *state = get_hashlib_state(module);
 
-    state->EVPtype = (PyTypeObject *)PyType_FromSpec(&EVPtype_spec);
-    if (state->EVPtype == NULL) {
-        return -1;
-    }
-    if (PyModule_AddType(module, state->EVPtype) < 0) {
-        return -1;
-    }
-    return 0;
+    state->EVPtype = PyModule_AddNewTypeFromSpec(
+        module, &EVPtype_spec, NULL);
+    return state->EVPtype == NULL ? -1 : 0;
 }
 
 static int
@@ -2044,33 +2039,21 @@ hashlib_init_evpxoftype(PyObject *module)
     if (state->EVPtype == NULL) {
         return -1;
     }
-
-    state->EVPXOFtype = (PyTypeObject *)PyType_FromSpecWithBases(
-        &EVPXOFtype_spec, (PyObject *)state->EVPtype
-    );
-    if (state->EVPXOFtype == NULL) {
-        return -1;
-    }
-    if (PyModule_AddType(module, state->EVPXOFtype) < 0) {
-        return -1;
-    }
+    state->EVPXOFtype = PyModule_AddNewTypeFromSpec(
+        module, &EVPXOFtype_spec, (PyObject *)state->EVPtype);
+    return state->EVPXOFtype == NULL ? -1 : 0;
 #endif
     return 0;
 }
 
 static int
 hashlib_init_hmactype(PyObject *module)
 {
-    _hashlibstate *state = get_hashlib_state(module);
+     _hashlibstate *state = get_hashlib_state(module);
 
-    state->HMACtype = (PyTypeObject *)PyType_FromSpec(&HMACtype_spec);
-    if (state->HMACtype == NULL) {
-        return -1;
-    }
-    if (PyModule_AddType(module, state->HMACtype) < 0) {
-        return -1;
-    }
-    return 0;
+    state->HMACtype = PyModule_AddNewTypeFromSpec(
+        module, &HMACtype_spec, NULL);
+    return state->HMACtype == NULL ? -1 : 0;
 }
 
 static int

Modules/_ssl.c

@@ -5459,39 +5459,30 @@ static PyMethodDef PySSL_methods[] = {
 static int
 sslmodule_init_types(PyObject *module)
 {
-    PySSLContext_Type = (PyTypeObject *)PyType_FromModuleAndSpec(
+    PySSLContext_Type = PyModule_AddNewTypeFromSpec(
         module, &PySSLContext_spec, NULL
     );
     if (PySSLContext_Type == NULL)
         return -1;
 
-    PySSLSocket_Type = (PyTypeObject *)PyType_FromModuleAndSpec(
+    PySSLSocket_Type = PyModule_AddNewTypeFromSpec(
         module, &PySSLSocket_spec, NULL
     );
     if (PySSLSocket_Type == NULL)
         return -1;
 
-    PySSLMemoryBIO_Type = (PyTypeObject *)PyType_FromModuleAndSpec(
+    PySSLMemoryBIO_Type = PyModule_AddNewTypeFromSpec(
         module, &PySSLMemoryBIO_spec, NULL
     );
     if (PySSLMemoryBIO_Type == NULL)
         return -1;
 
-    PySSLSession_Type = (PyTypeObject *)PyType_FromModuleAndSpec(
+    PySSLSession_Type = PyModule_AddNewTypeFromSpec(
         module, &PySSLSession_spec, NULL
     );
     if (PySSLSession_Type == NULL)
         return -1;
 
-    if (PyModule_AddType(module, PySSLContext_Type))
-        return -1;
-    if (PyModule_AddType(module, PySSLSocket_Type))
-        return -1;
-    if (PyModule_AddType(module, PySSLMemoryBIO_Type))
-        return -1;
-    if (PyModule_AddType(module, PySSLSession_Type))
-        return -1;
-
     return 0;
 }