gh-83785: Document missing PyDateTime* APIs.

[ZeroIntensity]

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]

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

This is wrong.

[ZeroIntensity]

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

[StanFromIreland]

Suggested change

	if (PyErr_Occurred()) { /* cleanup */ }
	if (PyDateTimeAPI == NULL) { /* cleanup */ }

[ZeroIntensity]

Why? We should probably avoid encouraging the use of global variables here.

[StanFromIreland]

This is the current practice in CPython.

[pganssle]

Is there a situation where PyDateTime_API is null that PyErr_Occurred() does not cover, or vice versa (i.e. partially initialized PyDateTimeAPI?)

[StanFromIreland]

Per the PyCapsule_Import docs and a glance over it's source:

On failure, set an exception and return NULL.

So the checks are equivalent.

[pganssle]

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]

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.