Description

pganssle

opened on Feb 10, 2020

Issue body actions

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

Activity

1. pganssle commented on Feb 10, 2020

   

   pganssle

   on Feb 10, 2020

   MemberAuthor

   More actions

   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.
2. pganssle

   added

   3.8 (EOL)end of lifeend of life

   3.9 (EOL)end of lifeend of life

   on Feb 10, 2020
3. pganssle

   assigned

   docspython

   on Feb 10, 2020
4. pganssle

   added

   docsDocumentation in the Doc dirDocumentation in the Doc dir

   topic-C-API

   3.8 (EOL)end of lifeend of life

   3.9 (EOL)end of lifeend of life

   on Feb 10, 2020
5. pganssle

   assigned

   docspython

   on Feb 10, 2020
6. pganssle

   added

   docsDocumentation in the Doc dirDocumentation in the Doc dir

   topic-C-API

   on Feb 10, 2020
7. pitrou

   added

   3.10 (EOL)end of lifeend of life

   type-bugAn unexpected behavior, bug, or errorAn unexpected behavior, bug, or error

   on Jul 20, 2020
8. ezio-melotti

   transferred this issue fromon Apr 10, 2022
9. serhiy-storchaka

   added this to Date and time issues 🕰️on May 21, 2022
10. encukou

    removed

    type-bugAn unexpected behavior, bug, or errorAn unexpected behavior, bug, or error

    3.10 (EOL)end of lifeend of life

    3.9 (EOL)end of lifeend of life

    3.8 (EOL)end of lifeend of life

    on Mar 14, 2025
11. github-project-automation

    added this to docs issueson Mar 14, 2025
12. github-project-automation

    moved this to Todo in docs issueson Mar 14, 2025
13. StanFromIreland

    added a parent issue on Nov 14, 2025

    • Document the entire C API #141004
14. ZeroIntensity commented on Oct 20, 2026

    

    ZeroIntensity

    on Oct 20, 2026

    Member

    More actions

    I think this has been done since #141543? I don't see much point in documenting the actual structure fields if we want people to use the macros anyway.
15. ZeroIntensity

    closed this as completedon Oct 20, 2026
16. github-project-automation

    moved this to Done in Date and time issues 🕰️on Oct 20, 2026

Issue actions