[issue38065] Document the datetime capsule API

[Paul Ganssle]

New submission from Paul Ganssle <p.ganssle at gmail.com>:

The datetime module has a capsule API, which is very useful for other languages' bindings, but the C API documentation for datetime only covers the C macros: https://docs.python.org/3/c-api/datetime.html

The current extent of the documentation is that everyone who wants to bind to the C API (PyO3, Cython, pypy, etc), you need to just read the struct definition ( https://github.com/python/cpython/blob/master/Include/datetime.h#L150 ) and reads `_datetimemodule.c`. There's even some question as to whether the capsule is public (see, e.g. https://github.com/PyO3/pyo3/pull/393#issuecomment-476664650 ), when in fact I'm fairly certain that it's actually *preferred* to use the capsule API.

Most or many of the macros are thin wrappers around the capsule API, so we may need to figure out whether we want to try and use the same "documentation" for both versions, e.g.:

  .. c:function:: PyObject* PyDateTime_CAPI.Date_FromDate(int year, int month, int day, PyTypeObject* cls)
  .. c:function:: PyObject* PyDate_FromDate(int year, int month, int day)

     Return a :class:`datetime.date` object with the specified year, month and day.

     The version of this function in the capsule module takes an additional argument
     representing the specific subclass to construct.

Could replace:

  .. c:function:: PyObject* PyDate_FromDate(int year, int month, int day)

     Return a :class:`datetime.date` object with the specified year, month and day.

I would say that we also need a paragraph or two at the beginning of the C API document explaining why there are two ways to access most of these things?

A more minor bikeshedding-y issue is how we should stylize these: PyDatetime_CAPI.x? PyDatetime_CAPI->x? A dedicated RST directive? Something else?

----------
assignee: docs at python
components: Documentation
messages: 351427
nosy: belopolsky, docs at python, eric.araujo, ezio.melotti, mdk, p-ganssle, willingc
priority: normal
severity: normal
status: open
title: Document the datetime capsule API
type: enhancement
versions: Python 3.7, Python 3.8, Python 3.9

_______________________________________
Python tracker <report at bugs.python.org>
<https://bugs.python.org/issue38065>
_______________________________________