classification
Title: Document PyDateTimeAPI / PyDateTime_CAPI struct
Type: Stage:
Components: C API, Documentation Versions: Python 3.9, Python 3.8
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: belopolsky, docs@python, lemburg, p-ganssle
Priority: normal Keywords:

Created on 2020-02-10 22:21 by p-ganssle, last changed 2020-02-11 00:08 by vstinner.

Messages (1)
msg361733 - (view) Author: Paul Ganssle (p-ganssle) * (Python committer) Date: 2020-02-10 22:21
The entire public interface documented for the datetime C API is various C macros (see: https://docs.python.org/3/c-api/datetime.html) which are wrappers around function calls to the PyDateTimeAPI / PyDatetime_CAPI struct, but the struct itself is undocumented. 

Unfortunately (or fortunately, depending on how you think the C API should look), pretty much everyone has to know the implementation details of the C API struct anyway. Bindings in other languages usually can't use the C preprocessor macros and have to directly use the C API struct so projects like PyPy, PyO3 and Cython are using it. The struct also can do things that the macros can't do: consider bug #30155 which is looking for a way to create a datetime object with a tzinfo (which is possible using the C struct).

I think we can should go ahead and make the `PyDateTimeAPI` struct "public" and document the functions on it. This may be a bit tougher than one would hope because the overlap between the macros and the struct functions isn't 100%, but it's pretty close, so I would think we'd want to document the two ways to do things rather close to one another.

nosy-ing Victor on here in case he has any strong opinions about whether these kinds of struct should be exposed as part of the official public interface.
History
Date User Action Args
2020-02-11 00:08:47vstinnersetnosy: - vstinner
2020-02-10 22:21:41p-gansslecreate