From 50116ee32cfd4e956a534bdb54bbdf13c5c62c87 Mon Sep 17 00:00:00 2001 From: Peter Bierma Date: Thu, 13 Nov 2025 19:58:56 -0500 Subject: [PATCH 1/5] Document missing PyDateTime* APIs. --- Doc/c-api/datetime.rst | 48 ++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 46 insertions(+), 2 deletions(-) diff --git a/Doc/c-api/datetime.rst b/Doc/c-api/datetime.rst index f311aad5f15499..cf19f112b6fead 100644 --- a/Doc/c-api/datetime.rst +++ b/Doc/c-api/datetime.rst @@ -8,11 +8,43 @@ DateTime Objects Various date and time objects are supplied by the :mod:`datetime` module. Before using any of these functions, the header file :file:`datetime.h` must be included in your source (note that this is not included by :file:`Python.h`), -and the macro :c:macro:`!PyDateTime_IMPORT` must be invoked, usually as part of +and the macro :c:macro:`PyDateTime_IMPORT` must be invoked, usually as part of 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 +into a static variable, :c:data:`PyDateTimeAPI`, that is used by the following macros. +.. c:macro:: PyDateTime_IMPORT() + + Import the datetime C API. The macro does not need a semi-colon to be called. + + On success, populate the :c:var:`PyDateTimeAPI` pointer. + + On failure, set :c:var:`PyDateTimeAPI` to ``NULL`` and set an exception. + The caller must check if an error occurred via :c:func:`PyErr_Occurred`: + + .. code-block:: + + PyDateTime_IMPORT(); // semi-colon is optional but recommended + if (PyErr_Occurred()) { /* cleanup */ } + + .. warning:: + + This is not compatible with subinterpreters. + +.. c:type:: PyDateTime_CAPI + + Structure containing the fields for the datetime C API. + + The fields of this structure are private and subject to change. + + Do not use this directly; prefer ``PyDateTime_*`` APIs instead. + +.. c:var:: PyDateTime_CAPI *PyDateTimeAPI + + Dynamically allocated object containing the datetime C API. + + This variable is only available once :c:macro:`PyDateTime_IMPORT` succeeds. + .. c:type:: PyDateTime_Date This subtype of :c:type:`PyObject` represents a Python date object. @@ -325,3 +357,15 @@ Macros for the convenience of modules implementing the DB API: Create and return a new :class:`datetime.date` object given an argument tuple suitable for passing to :meth:`datetime.date.fromtimestamp`. + +Internal data +------------- + +The following symbol are exposed by the C API but should be considered +internal-only. + +.. c:macro:: PyDateTime_CAPSULE_NAME + + Name of the datetime capsule to pass to :c:func:`PyCapsule_Import`. + + Internal usage only. Use :c:macro:`PyDateTime_IMPORT` instead. From 35347c7894929e8de7311db341ff49d056371b35 Mon Sep 17 00:00:00 2001 From: Peter Bierma Date: Thu, 13 Nov 2025 20:04:27 -0500 Subject: [PATCH 2/5] Fix typo. --- Doc/c-api/datetime.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/c-api/datetime.rst b/Doc/c-api/datetime.rst index cf19f112b6fead..c025a7583d1129 100644 --- a/Doc/c-api/datetime.rst +++ b/Doc/c-api/datetime.rst @@ -361,7 +361,7 @@ Macros for the convenience of modules implementing the DB API: Internal data ------------- -The following symbol are exposed by the C API but should be considered +The following symbols are exposed by the C API but should be considered internal-only. .. c:macro:: PyDateTime_CAPSULE_NAME From 737ecf96d1451e6e9f2f4ddda31414b9c3ba4ec5 Mon Sep 17 00:00:00 2001 From: Peter Bierma Date: Fri, 14 Nov 2025 06:17:11 -0500 Subject: [PATCH 3/5] Apply suggestion from @StanFromIreland Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com> --- Doc/c-api/datetime.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/Doc/c-api/datetime.rst b/Doc/c-api/datetime.rst index c025a7583d1129..5aeb76107a8eab 100644 --- a/Doc/c-api/datetime.rst +++ b/Doc/c-api/datetime.rst @@ -358,6 +358,7 @@ Macros for the convenience of modules implementing the DB API: Create and return a new :class:`datetime.date` object given an argument tuple suitable for passing to :meth:`datetime.date.fromtimestamp`. + Internal data ------------- From 5d43c50e2cff04d78f84777559c7d5577f0a4de1 Mon Sep 17 00:00:00 2001 From: Peter Bierma Date: Fri, 14 Nov 2025 06:17:32 -0500 Subject: [PATCH 4/5] Apply suggestion from @StanFromIreland Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com> --- Doc/c-api/datetime.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/c-api/datetime.rst b/Doc/c-api/datetime.rst index 5aeb76107a8eab..bfa591181d868e 100644 --- a/Doc/c-api/datetime.rst +++ b/Doc/c-api/datetime.rst @@ -24,7 +24,7 @@ macros. .. code-block:: - PyDateTime_IMPORT(); // semi-colon is optional but recommended + PyDateTime_IMPORT; // semi-colon is optional but recommended if (PyErr_Occurred()) { /* cleanup */ } .. warning:: From aa9d63070a20df1c002a7ad9594a3d56cdb54f5b Mon Sep 17 00:00:00 2001 From: Peter Bierma Date: Fri, 14 Nov 2025 06:18:47 -0500 Subject: [PATCH 5/5] Fix semicolon shenanigans. --- Doc/c-api/datetime.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/c-api/datetime.rst b/Doc/c-api/datetime.rst index bfa591181d868e..5b32dc412d968b 100644 --- a/Doc/c-api/datetime.rst +++ b/Doc/c-api/datetime.rst @@ -15,7 +15,7 @@ macros. .. c:macro:: PyDateTime_IMPORT() - Import the datetime C API. The macro does not need a semi-colon to be called. + Import the datetime C API. On success, populate the :c:var:`PyDateTimeAPI` pointer. @@ -24,7 +24,7 @@ macros. .. code-block:: - PyDateTime_IMPORT; // semi-colon is optional but recommended + PyDateTime_IMPORT; if (PyErr_Occurred()) { /* cleanup */ } .. warning::