[issue39604] Document PyDateTimeAPI / PyDateTime_CAPI struct

[Antoine Pitrou]

Change by Antoine Pitrou :


--
stage:  -> needs patch
type:  -> behavior
versions: +Python 3.10

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue39604] Document PyDateTimeAPI / PyDateTime_CAPI struct

[STINNER Victor]

Change by STINNER Victor :


--
nosy:  -vstinner

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue39604] Document PyDateTimeAPI / PyDateTime_CAPI struct

[Paul Ganssle]

New submission from Paul Ganssle :

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 #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.

--
assignee: docs@python
components: C API, Documentation
messages: 361733
nosy: belopolsky, docs@python, lemburg, p-ganssle, vstinner
priority: normal
severity: normal
status: open
title: Document PyDateTimeAPI / PyDateTime_CAPI struct
versions: Python 3.8, Python 3.9

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com