Expose UTC singleton to the datetime C API

Author: pganssle

Doc/c-api/datetime.rst

@@ -13,6 +13,16 @@ the module initialisation function.  The macro puts a pointer to a C structure
 into a static variable, :c:data:`PyDateTimeAPI`, that is used by the following
 macros.
 
+Macro for access to the UTC singleton:
+
+.. c:var:: PyObject* PyDateTime_TimeZone_UTC
+
+   Returns the time zone singleton representing UTC, the same object as
+   :attr:``datetime.timezone.utc``.
+
+   .. versionadded:: 3.7
+
+
 Type-check macros:
 
 .. c:function:: int PyDate_Check(PyObject *ob)

Include/datetime.h

@@ -206,6 +206,9 @@ static PyDateTime_CAPI *PyDateTimeAPI = NULL;
 #define PyDateTime_IMPORT \
     PyDateTimeAPI = (PyDateTime_CAPI *)PyCapsule_Import(PyDateTime_CAPSULE_NAME, 0)
 
+/* Macro for access to the UTC singleton */
+#define PyDateTime_TimeZone_UTC PyDateTimeAPI->TimeZone_UTC
+
 /* Macros for type checking when not building the Python core. */
 #define PyDate_Check(op) PyObject_TypeCheck(op, PyDateTimeAPI->DateType)
 #define PyDate_CheckExact(op) (Py_TYPE(op) == PyDateTimeAPI->DateType)

Lib/test/datetimetester.py

@@ -5457,9 +5457,11 @@ def setUp(self):
         _testcapi.test_datetime_capi()
 
     def test_utc_capi(self):
-        capi_utc = _testcapi.get_timezone_utc_capi()
+        for use_macro in (True, False):
+            capi_utc = _testcapi.get_timezone_utc_capi(use_macro)
 
-        self.assertIs(capi_utc, timezone.utc)
+            with self.subTest(use_macro=use_macro):
+                self.assertIs(capi_utc, timezone.utc)
 
     def test_timezones_capi(self):
         est_capi, est_macro, est_macro_nn = _testcapi.make_timezones_capi()

Modules/_testcapimodule.c

@@ -2295,7 +2295,15 @@ make_timezones_capi(PyObject *self, PyObject *args) {
 
 static PyObject *
 get_timezone_utc_capi(PyObject* self, PyObject *args) {
-    return PyDateTimeAPI->TimeZone_UTC;
+    int macro = 0;
+    if (!PyArg_ParseTuple(args, "|p", &macro)) {
+        return NULL;
+    }
+    if (macro) {
+        return PyDateTime_TimeZone_UTC;
+    } else {
+        return PyDateTimeAPI->TimeZone_UTC;
+    }
 }
 
 
@@ -4523,7 +4531,7 @@ static PyMethodDef TestMethods[] = {
     {"datetime_check_delta",     datetime_check_delta,           METH_VARARGS},
     {"datetime_check_tzinfo",     datetime_check_tzinfo,         METH_VARARGS},
     {"make_timezones_capi",     make_timezones_capi,             METH_NOARGS},
-    {"get_timezone_utc_capi",    get_timezone_utc_capi,            METH_NOARGS},
+    {"get_timezone_utc_capi",    get_timezone_utc_capi,            METH_VARARGS},
     {"test_list_api",           (PyCFunction)test_list_api,      METH_NOARGS},
     {"test_dict_iteration",     (PyCFunction)test_dict_iteration,METH_NOARGS},
     {"dict_getitem_knownhash",  dict_getitem_knownhash,          METH_VARARGS},