Document PyDateTimeAPI / PyDateTime_CAPI struct

@malemburg

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

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.

Navigation Menu

Repository navigation

Document PyDateTimeAPI / PyDateTime_CAPI struct #83785

Linked PRs

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Document PyDateTimeAPI / PyDateTime_CAPI struct #83785

Description

Linked PRs

Activity

pganssle commented on Feb 10, 2020

Metadata

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Issue actions