[New-bugs-announce] [issue39604] Document PyDateTimeAPI / PyDateTime_CAPI struct

[Paul Ganssle]

New submission from Paul Ganssle <p.ganssle at gmail.com>:

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.

----------
assignee: docs at python
components: C API, Documentation
messages: 361733
nosy: belopolsky, docs at python, lemburg, p-ganssle, vstinner
priority: normal
severity: normal
status: open
title: Document PyDateTimeAPI / PyDateTime_CAPI struct
versions: Python 3.8, Python 3.9

_______________________________________
Python tracker <report at bugs.python.org>
<https://bugs.python.org/issue39604>
_______________________________________