Stowage/cpython
2
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-12-08 06:10:17 +00:00
Code Issues Projects Releases Packages Wiki Activity

[3.13] gh-141004: Document missing PyDateTime* APIs (GH-141543) (GH-141792)

Browse source 
gh-141004: Document missing `PyDateTime*` APIs (GH-141543)
(cherry picked from commit 4273616ebf)

Co-authored-by: Peter Bierma <zintensitydev@gmail.com>
Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>
Co-authored-by: Victor Stinner <vstinner@python.org>
This commit is contained in:
Miss Islington (bot) 2025-11-20 14:55:17 +01:00 • committed by GitHub
parent e90d8953a0
commit 7a27c7b2e4
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
1 changed files with 46 additions and 2 deletions
Download patch file Download diff file Expand all files Collapse all files

48
Doc/c-api/datetime.rst
View file

@ -8,11 +8,42 @@ DateTime Objects
Various date and time objects are supplied by the :mod:`datetime` module. 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 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`), 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 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. macros.
.. c:macro:: PyDateTime_IMPORT()
Import the datetime C API.
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;
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 .. c:type:: PyDateTime_Date
This subtype of :c:type:`PyObject` represents a Python date object. This subtype of :c:type:`PyObject` represents a Python date object.
@ -325,3 +356,16 @@ Macros for the convenience of modules implementing the DB API:
Create and return a new :class:`datetime.date` object given an argument Create and return a new :class:`datetime.date` object given an argument
tuple suitable for passing to :meth:`datetime.date.fromtimestamp`. tuple suitable for passing to :meth:`datetime.date.fromtimestamp`.
Internal data
-------------
The following symbols 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.