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

Author: tiran

Doc/c-api/module.rst

@@ -577,6 +577,141 @@ 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.12
+
+.. 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.12
+
+.. 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.
+
+   .. versionadded:: 3.12
+
+   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
+
+   Definition of a module constant.
+
+   The members of this struct are internal implementation details.
+   To define entries, use only the ``PyModuleConst_`` macros below,
+   and ``{NULL}`` to mark the end of the array.
+
+   .. versionadded:: 3.12
+
+.. 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.12
+
+.. c:macro:: PyModuleConst_ULong(name, value)
+
+   Add an entry for an unsigned integer constant.
+
+   .. versionadded:: 3.12
+
+.. c:macro:: PyModuleConst_Bool(name, value)
+
+   Add an entry for a bool constant. ``0`` is false, ``1`` is true.
+
+   .. versionadded:: 3.12
+
+.. c:macro:: PyModuleConst_Double(name, value)
+
+   Add an entry for a float constant.
+
+   .. versionadded:: 3.12
+
+.. c:macro:: PyModuleConst_String(name, value)
+
+   Add an entry for a string constant.
+
+   .. versionadded:: 3.12
+
+.. c:macro:: PyModuleConst_Call(name, func)
+
+   Add an entry for a constant as returned by callback with signature
+   ``PyObject* (*func)(PyObject *module)``.
+
+   .. versionadded:: 3.12
+
+.. c:macro:: PyModuleConst_LongMacro(macro)
+
+   Add an entry for an int constant. The name and the value are taken from
+   *macro*.
+
+   .. versionadded:: 3.12
+
+.. c:macro:: PyModuleConst_StringMacro(macro)
+
+   Add an entry for a string constant. The name and the value are taken from
+   *macro*.
+
+   .. versionadded:: 3.12
 
 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

@@ -59,6 +59,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

@@ -71,6 +71,65 @@ struct PyModuleDef_Slot {
 
 #endif /* New in 3.5 */
 
+struct PyModuleConst_Def;
+#if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x03b00000
+/* New in 3.12 */
+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);
+        // unused, included to force alignment and size for future use.
+        long long m_long_long;
+#ifdef HAVE_LONG_DOUBLE
+        long double m_long_double;
+#endif
+#ifdef HAVE_GCC_UINT128_T
+        __uint128_t m_uint128;
+#endif
+#ifdef HAVE_GCC_FLOAT128_T
+        __float128_t m_float128;
+#endif
+    char __m[16]; // 128 bits
+    } 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.12 */
+
 struct PyModuleDef {
   PyModuleDef_Base m_base;
   const char* m_name;

Lib/test/test_capi.py

@@ -1203,5 +1203,19 @@ def func2(x=None):
         self.do_test(func2)
 
 
+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/2022-07-31-13-37-31.gh-issue-86542.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

@@ -2132,14 +2132,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
@@ -2151,33 +2146,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/_testcapimodule.c

@@ -7530,6 +7530,29 @@ static PyTypeObject ContainerNoGC_type = {
     .tp_new = ContainerNoGC_new,
 };
 
+static PyObject *
+_testcapimodule_const_call(PyObject *module)
+{
+    return PyBytes_FromString("23");
+}
+
+#define CONST_INT 7
+#define CONST_STRING "world"
+
+static PyModuleConst_Def _testcapimodule_consts[] = {
+    PyModuleConst_None("const_none"),
+    PyModuleConst_Long("const_int", 42),
+    PyModuleConst_ULong("const_uint", ULONG_MAX),
+    PyModuleConst_Bool("const_false", 0),
+    PyModuleConst_Bool("const_true", 1),
+    PyModuleConst_Double("const_almost_tau", 6.2831),
+    PyModuleConst_String("const_str", "Hello"),
+    PyModuleConst_Call("const_call", _testcapimodule_const_call),
+    PyModuleConst_LongMacro(CONST_INT),
+    PyModuleConst_StringMacro(CONST_STRING),
+    {NULL},
+};
+
 
 static struct PyModuleDef _testcapimodule = {
     PyModuleDef_HEAD_INIT,
@@ -7555,6 +7578,11 @@ PyInit__testcapi(void)
     if (m == NULL)
         return NULL;
 
+    if (PyModule_AddConstants(m, _testcapimodule_consts) < 0) {
+        Py_DECREF(m);
+        return NULL;
+    }
+
     Py_SET_TYPE(&_HashInheritanceTester_Type, &PyType_Type);
 
     Py_SET_TYPE(&test_structmembersType, &PyType_Type);