Document PyDateTimeAPI / PyDateTime_CAPI struct

[pganssle]

BPO	39604
Nosy	@malemburg, @abalkin, @pganssle

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields: ```python assignee = None closed_at = None created_at = labels = ['type-bug', '3.8', '3.9', '3.10', 'expert-C-API', 'docs'] title = 'Document PyDateTimeAPI / PyDateTime_CAPI struct' updated_at = user = 'https://github.com/pganssle' ``` bugs.python.org fields: ```python activity = actor = 'pitrou' assignee = 'docs@python' closed = False closed_date = None closer = None components = ['Documentation', 'C API'] creation = creator = 'p-ganssle' dependencies = [] files = [] hgrepos = [] issue_num = 39604 keywords = [] message_count = 1.0 messages = ['361733'] nosy_count = 4.0 nosy_names = ['lemburg', 'belopolsky', 'docs@python', 'p-ganssle'] pr_nums = [] priority = 'normal' resolution = None stage = 'needs patch' status = 'open' superseder = None type = 'behavior' url = 'https://bugs.python.org/issue39604' versions = ['Python 3.8', 'Python 3.9', 'Python 3.10'] ```

[pganssle]

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 bpo-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.