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:

assignee = None
closed_at = None
created_at = <Date 2020-02-10.22:21:41.278>
labels = ['type-bug', '3.8', '3.9', '3.10', 'expert-C-API', 'docs']
title = 'Document PyDateTimeAPI / PyDateTime_CAPI struct'
updated_at = <Date 2020-07-20.14:34:36.012>
user = 'https://github.com/pganssle'

bugs.python.org fields:

activity = <Date 2020-07-20.14:34:36.012>
actor = 'pitrou'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation', 'C API']
creation = <Date 2020-02-10.22:21:41.278>
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']

Linked PRs

• gh-141004: Document missing PyDateTime* APIs. #141543

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