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

ZeroIntensity · 2025-11-14T01:03:28Z

I was mostly inspired by Bénédikt's work on the curses C API (#141254) for this.

In the future, I think we should completely deprecate PyDateTimeAPI and PyDateTime_IMPORT because of subinterpreter incompatibility, as well as documenting all the fields on PyDateTime_CAPI to make this usable under subinterpreters, but that's a later project.

Issue: Document the entire C API #141004

📚 Documentation preview 📚: https://cpython-previews--141543.org.readthedocs.build/en/141543/c-api/datetime.html

Issue: Document PyDateTimeAPI / PyDateTime_CAPI struct #83785

StanFromIreland · 2025-11-14T08:03:07Z

Doc/c-api/datetime.rst


+.. c:macro:: PyDateTime_IMPORT()
+
+   Import the datetime C API. The macro does not need a semi-colon to be called.


The macro does not need a semi-colon to be called.

This is wrong.

Yes, I should've fact-checked this one before copy-pasting it. Good catch!

Doc/c-api/datetime.rst

Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>

pganssle · 2025-11-14T15:41:29Z

This sounded familiar so I thought there was some reason that we didn't do it, but apparently I actually wanted to go even further than this and didn't get around to it / didn't drum up enough interest: #83785

I am tempted to say we should not say the thing about the struct contents being private and subject to change because there are situations where they are legitimately the only way to accomplish things and I am not crazy about the fact that our public interface is C macros anyway (given that those macros don't work outside of C++, I'd rather they be symbols that can be linked against in an FFI).

Given the subinterpreter stuff, though, it might be a bit of an own goal to make the struct public right away before making a plan for how to move forward (in case the implementation details of the struct end up being inconvenient in that effort), so I'm +1 on the current scope of this PR.

StanFromIreland · 2025-11-14T15:45:23Z

This sounded familiar so I thought there was some reason that we didn't do it, but apparently I actually wanted to go even further than this and didn't get around to it / didn't drum up enough interest: #83785

Oh I forgot about that one! I've moved this PR under it, since it is more specific.

ZeroIntensity · 2025-11-14T16:05:31Z

I'm fine with removing the note on the contents of PyDateTime_CAPI being private, would you like me to do that?

Oh I forgot about that one! I've moved this PR under it, since it is more specific.

Please don't edit my PRs without my permission. I don't think this PR fits great under that issue; we're merely documenting that PyDateTimeAPI / PyDateTime_CAPI exist so they show up in Sphinx, whereas that issue seems more about documenting the contents of them. I'm happy to use that issue for the future work Paul and I were talking about in regards to FFIs and thread-safety.

StanFromIreland · 2025-11-14T16:14:15Z

Apologies Peter.

pganssle · 2025-11-14T16:15:27Z

I'm fine with removing the note on the contents of PyDateTime_CAPI being private, would you like me to do that?

No I think we should leave it. If we later decide that we're going to officially expose them publicly without any changes we can always backport the docs changes to older versions to retroactively document it.

ZeroIntensity · 2025-11-14T16:30:43Z

I created #141563 for discussion on the global variable.

vstinner

LGTM, I just left minor suggestions.

vstinner · 2025-11-20T11:32:20Z

Doc/c-api/datetime.rst

+   .. code-block::
+
+      PyDateTime_IMPORT;
+      if (PyErr_Occurred()) { /* cleanup */ }


Suggested change

if (PyErr_Occurred()) { /* cleanup */ }

if (PyErr_Occurred()) { /* error */ }

I like the current comment, we do similar for the curses C API: https://docs.python.org/3/c-api/curses.html

Doc/c-api/datetime.rst

Co-authored-by: Victor Stinner <vstinner@python.org>

miss-islington-app · 2025-11-20T13:48:53Z

Thanks @ZeroIntensity for the PR 🌮🎉.. I'm working now to backport this PR to: 3.14.
🐍🍒⛏🤖

miss-islington-app · 2025-11-20T13:48:54Z

Thanks @ZeroIntensity for the PR 🌮🎉.. I'm working now to backport this PR to: 3.13.
🐍🍒⛏🤖

(cherry picked from commit 4273616) Co-authored-by: Peter Bierma <zintensitydev@gmail.com> Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com> Co-authored-by: Victor Stinner <vstinner@python.org>

bedevere-app · 2025-11-20T13:49:01Z

GH-141791 is a backport of this pull request to the 3.14 branch.

(cherry picked from commit 4273616) Co-authored-by: Peter Bierma <zintensitydev@gmail.com> Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com> Co-authored-by: Victor Stinner <vstinner@python.org>

bedevere-app · 2025-11-20T13:49:06Z

GH-141792 is a backport of this pull request to the 3.13 branch.

…-141791) gh-141004: Document missing `PyDateTime*` APIs (GH-141543) (cherry picked from commit 4273616) Co-authored-by: Peter Bierma <zintensitydev@gmail.com> Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com> Co-authored-by: Victor Stinner <vstinner@python.org>

…-141792) gh-141004: Document missing `PyDateTime*` APIs (GH-141543) (cherry picked from commit 4273616) Co-authored-by: Peter Bierma <zintensitydev@gmail.com> Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com> Co-authored-by: Victor Stinner <vstinner@python.org>

Document missing PyDateTime* APIs.

50116ee

ZeroIntensity requested review from abalkin and pganssle as code owners November 14, 2025 01:03

bedevere-app bot added awaiting core review docs Documentation in the Doc dir skip news labels Nov 14, 2025

github-project-automation bot added this to Docs PRs Nov 14, 2025

github-project-automation bot moved this to Todo in Docs PRs Nov 14, 2025

bedevere-app bot mentioned this pull request Nov 14, 2025

Document the entire C API #141004

Open

Fix typo.

35347c7

StanFromIreland reviewed Nov 14, 2025

View reviewed changes

ZeroIntensity and others added 3 commits November 14, 2025 06:17

Apply suggestion from @StanFromIreland

737ecf9

Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>

Apply suggestion from @StanFromIreland

5d43c50

Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>

Fix semicolon shenanigans.

aa9d630

StanFromIreland changed the title ~~gh-141004: Document missing PyDateTime* APIs.~~ gh-83785: Document missing PyDateTime* APIs. Nov 14, 2025

bedevere-app bot mentioned this pull request Nov 14, 2025

Document PyDateTimeAPI / PyDateTime_CAPI struct #83785

Open

ZeroIntensity changed the title ~~gh-83785: Document missing PyDateTime* APIs.~~ gh-141004: Document missing PyDateTime* APIs. Nov 14, 2025

ZeroIntensity mentioned this pull request Nov 14, 2025

The datetime C API is not thread-safe #141563

Open

vstinner approved these changes Nov 20, 2025

View reviewed changes

bedevere-app bot added awaiting merge and removed awaiting core review labels Nov 20, 2025

Update Doc/c-api/datetime.rst

a9be066

Co-authored-by: Victor Stinner <vstinner@python.org>

ZeroIntensity merged commit 4273616 into python:main Nov 20, 2025
28 checks passed

ZeroIntensity deleted the document-datetime-capsule-name branch November 20, 2025 13:48

github-project-automation bot moved this from Todo to Done in Docs PRs Nov 20, 2025

bedevere-app bot removed the awaiting merge label Nov 20, 2025

ZeroIntensity added needs backport to 3.13 bugs and security fixes needs backport to 3.14 bugs and security fixes labels Nov 20, 2025

bedevere-app bot removed the needs backport to 3.14 bugs and security fixes label Nov 20, 2025

bedevere-app bot removed the needs backport to 3.13 bugs and security fixes label Nov 20, 2025


		.. c:macro:: PyDateTime_IMPORT()

		Import the datetime C API. The macro does not need a semi-colon to be called.

	if (PyErr_Occurred()) { /* cleanup */ }
	if (PyErr_Occurred()) { /* error */ }

Uh oh!

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

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

Uh oh!

Conversation

ZeroIntensity commented Nov 14, 2025 • edited by bedevere-app bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

StanFromIreland Nov 14, 2025

Choose a reason for hiding this comment

Uh oh!

ZeroIntensity Nov 14, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

pganssle commented Nov 14, 2025

Uh oh!

StanFromIreland commented Nov 14, 2025

Uh oh!

ZeroIntensity commented Nov 14, 2025

Uh oh!

StanFromIreland commented Nov 14, 2025

Uh oh!

pganssle commented Nov 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ZeroIntensity commented Nov 14, 2025

Uh oh!

vstinner left a comment

Choose a reason for hiding this comment

Uh oh!

vstinner Nov 20, 2025

Choose a reason for hiding this comment

Uh oh!

ZeroIntensity Nov 20, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

miss-islington-app bot commented Nov 20, 2025

Uh oh!

miss-islington-app bot commented Nov 20, 2025

Uh oh!

bedevere-app bot commented Nov 20, 2025

Uh oh!

bedevere-app bot commented Nov 20, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

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

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

ZeroIntensity commented Nov 14, 2025 •

edited by bedevere-app bot

Loading

pganssle commented Nov 14, 2025 •

edited

Loading