GV

GeezerVison

The World Wide Web, restored to 800 pixels of glory.

Home|About|Gaming cabinet|Archives|How it works|Starter sites

On this site

  • Sign in
  • ActionsCI/CD and automation
  • CodespacesCloud development environments
  • All Features
  • Documentation
  • Training
  • Certifications
  • Build with Copilot
  • Customize Copilot
  • Integrations
  • Trending repos
  • GitHub Sponsors
  • Developer articles
  • Enterprises

This view

  • Original page
  • New address

GeezerVison is showing github.com — gh-141004: Document missing `PyDateTime*` APIs. by ZeroIntensity · Pull Request #141543 · python/cpython

Conversation

@ZeroIntensity

@ZeroIntensity ZeroIntensity commented Nov 14, 2025 •
edited by bedevere-app Bot
Loading

Uh oh!

There was an error while loading. Please reload this page.

Copy link
Copy Markdown
Member

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

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions
@ZeroIntensity
Document missing PyDateTime* APIs.
50116ee
@ZeroIntensity
ZeroIntensity requested review from abalkin and pganssle as code owners November 14, 2025 01:03
@bedevere-app bedevere-app Bot added awaiting core review docs Documentation in the Doc dir skip news labels Nov 14, 2025
@github-project-automation github-project-automation Bot added this to Docs PRs Nov 14, 2025
@github-project-automation github-project-automation Bot moved this to Todo in Docs PRs Nov 14, 2025
@bedevere-app bedevere-app Bot mentioned this pull request Nov 14, 2025
Document the entire C API #141004
Closed
@ZeroIntensity
Fix typo.
35347c7
StanFromIreland
StanFromIreland reviewed Nov 14, 2025
View reviewed changes
Comment thread Doc/c-api/datetime.rst Outdated

.. c:macro:: PyDateTime_IMPORT()

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

@StanFromIreland StanFromIreland Nov 14, 2025

Copy link
Copy Markdown
Member

There was a problem hiding this comment.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

This is wrong.

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions

@ZeroIntensity ZeroIntensity Nov 14, 2025

Copy link
Copy Markdown
Member Author

There was a problem hiding this comment.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions
Comment thread Doc/c-api/datetime.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.
Comment thread Doc/c-api/datetime.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.
Comment thread Doc/c-api/datetime.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.
ZeroIntensity and others added 3 commits November 14, 2025 06:17
@ZeroIntensity @StanFromIreland
Apply suggestion from @StanFromIreland
737ecf9 
Co-authored-by: Stan Ulbrych <[email protected]>
@ZeroIntensity @StanFromIreland
Apply suggestion from @StanFromIreland
5d43c50 
Co-authored-by: Stan Ulbrych <[email protected]>
@ZeroIntensity
Fix semicolon shenanigans.
aa9d630
@pganssle

pganssle commented Nov 14, 2025

Copy link
Copy Markdown
Member

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.
All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
@StanFromIreland StanFromIreland changed the title gh-141004: Document missing PyDateTime* APIs. gh-83785: Document missing PyDateTime* APIs. Nov 14, 2025
@bedevere-app bedevere-app Bot mentioned this pull request Nov 14, 2025
Document PyDateTimeAPI / PyDateTime_CAPI struct #83785
Closed
@StanFromIreland

StanFromIreland commented Nov 14, 2025

Copy link
Copy Markdown
Member

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.
All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
@ZeroIntensity

ZeroIntensity commented Nov 14, 2025

Copy link
Copy Markdown
Member Author

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.
All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
@ZeroIntensity ZeroIntensity changed the title gh-83785: Document missing PyDateTime* APIs. gh-141004: Document missing PyDateTime* APIs. Nov 14, 2025
@StanFromIreland

StanFromIreland commented Nov 14, 2025

Copy link
Copy Markdown
Member

Apologies Peter.
ZeroIntensity reacted with heart emoji
All reactions
  • ❤️ 1 reaction

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
@pganssle

pganssle commented Nov 14, 2025 •
edited
Loading

Uh oh!

There was an error while loading. Please reload this page.

Copy link
Copy Markdown
Member

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 reacted with thumbs up emoji
All reactions
  • 👍 1 reaction

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
@ZeroIntensity ZeroIntensity mentioned this pull request Nov 14, 2025
The datetime C API is not thread-safe #141563
Closed
@ZeroIntensity

ZeroIntensity commented Nov 14, 2025

Copy link
Copy Markdown
Member Author

I created #141563 for discussion on the global variable.
All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
vstinner
vstinner approved these changes Nov 20, 2025
View reviewed changes

@vstinner vstinner left a comment

Copy link
Copy Markdown
Member

There was a problem hiding this comment.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM, I just left minor suggestions.

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions
Comment thread Doc/c-api/datetime.rst
.. code-block::

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

@vstinner vstinner Nov 20, 2025

Copy link
Copy Markdown
Member

There was a problem hiding this comment.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions

@ZeroIntensity ZeroIntensity Nov 20, 2025

Copy link
Copy Markdown
Member Author

There was a problem hiding this comment.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
vstinner reacted with thumbs up emoji
All reactions
  • 👍 1 reaction
Comment thread Doc/c-api/datetime.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.
@bedevere-app bedevere-app Bot added awaiting merge and removed awaiting core review labels Nov 20, 2025
@ZeroIntensity @vstinner
Update Doc/c-api/datetime.rst
a9be066 
Co-authored-by: Victor Stinner <[email protected]>
@ZeroIntensity
ZeroIntensity merged commit 4273616 into python:main Nov 20, 2025
28 checks passed

Uh oh!

There was an error while loading. Please reload this page.
@ZeroIntensity
ZeroIntensity deleted the document-datetime-capsule-name branch November 20, 2025 13:48
@github-project-automation github-project-automation Bot moved this from Todo to Done in Docs PRs Nov 20, 2025
@bedevere-app bedevere-app Bot removed the awaiting merge label Nov 20, 2025
@ZeroIntensity ZeroIntensity added needs backport to 3.13 only security fixes needs backport to 3.14 bugs and security fixes labels Nov 20, 2025
@miss-islington-app

miss-islington-app Bot commented Nov 20, 2025

Copy link
Copy Markdown

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

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
@miss-islington-app

miss-islington-app Bot commented Nov 20, 2025

Copy link
Copy Markdown

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

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
miss-islington pushed a commit to miss-islington/cpython that referenced this pull request Nov 20, 2025
@ZeroIntensity @StanFromIreland
@vstinner @miss-islington
pythongh-141004: Document missing PyDateTime* APIs (pythonGH-141543)
1570254 
(cherry picked from commit 4273616)

Co-authored-by: Peter Bierma <[email protected]>
Co-authored-by: Stan Ulbrych <[email protected]>
Co-authored-by: Victor Stinner <[email protected]>
@bedevere-app

bedevere-app Bot commented Nov 20, 2025

Copy link
Copy Markdown

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

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
@bedevere-app bedevere-app Bot removed the needs backport to 3.14 bugs and security fixes label Nov 20, 2025
miss-islington pushed a commit to miss-islington/cpython that referenced this pull request Nov 20, 2025
@ZeroIntensity @StanFromIreland
@vstinner @miss-islington
pythongh-141004: Document missing PyDateTime* APIs (pythonGH-141543)
e04a1da 
(cherry picked from commit 4273616)

Co-authored-by: Peter Bierma <[email protected]>
Co-authored-by: Stan Ulbrych <[email protected]>
Co-authored-by: Victor Stinner <[email protected]>
@bedevere-app

bedevere-app Bot commented Nov 20, 2025

Copy link
Copy Markdown

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

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
@bedevere-app bedevere-app Bot removed the needs backport to 3.13 only security fixes label Nov 20, 2025
ZeroIntensity added a commit that referenced this pull request Nov 20, 2025
@miss-islington @ZeroIntensity
@StanFromIreland @vstinner
[3.14] gh-141004: Document missing PyDateTime* APIs (GH-141543) (GH…
f1bed5b 
…-141791)

gh-141004: Document missing `PyDateTime*` APIs (GH-141543)
(cherry picked from commit 4273616)

Co-authored-by: Peter Bierma <[email protected]>
Co-authored-by: Stan Ulbrych <[email protected]>
Co-authored-by: Victor Stinner <[email protected]>
ZeroIntensity added a commit that referenced this pull request Nov 20, 2025
@miss-islington @ZeroIntensity
@StanFromIreland @vstinner
[3.13] gh-141004: Document missing PyDateTime* APIs (GH-141543) (GH…
7a27c7b 
…-141792)

gh-141004: Document missing `PyDateTime*` APIs (GH-141543)
(cherry picked from commit 4273616)

Co-authored-by: Peter Bierma <[email protected]>
Co-authored-by: Stan Ulbrych <[email protected]>
Co-authored-by: Victor Stinner <[email protected]>
StanFromIreland added a commit to StanFromIreland/cpython that referenced this pull request Dec 6, 2025
@ZeroIntensity @StanFromIreland @vstinner
pythongh-141004: Document missing PyDateTime* APIs (pythonGH-141543)
2874c25 
Co-authored-by: Stan Ulbrych <[email protected]>
Co-authored-by: Victor Stinner <[email protected]>
ashm-dev pushed a commit to ashm-dev/cpython that referenced this pull request Dec 8, 2025
@ZeroIntensity @StanFromIreland
@vstinner @ashm-dev
pythongh-141004: Document missing PyDateTime* APIs (pythonGH-141543)
7dceff5 
Co-authored-by: Stan Ulbrych <[email protected]>
Co-authored-by: Victor Stinner <[email protected]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@StanFromIreland StanFromIreland StanFromIreland left review comments
@vstinner vstinner vstinner approved these changes
@pganssle pganssle Awaiting requested review from pganssle pganssle is a code owner
@abalkin abalkin Awaiting requested review from abalkin

Uh oh!

There was an error while loading. Please reload this page.

Assignees

No one assigned

Labels

docs Documentation in the Doc dir skip news

Projects

Docs PRs
Status: Done

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Uh oh!

There was an error while loading. Please reload this page.

4 participants

@ZeroIntensity @pganssle @StanFromIreland @vstinner
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
You are visitor 01402503 — GeezerVison does not store the pages you look up.
Best viewed with Netscape Navigator 4.7 or Internet Explorer 6 at 800×600. No cookies required.