SF patch 986010: add missing doc for datetime C API, from

Anthony Tuininga.

This is a derived patch, taking the opportunity to add some organization
to the now-large pile of datetime-related macros, and to factor out
tedious repeated text.

Also improved some clumsy wording in NEWS.

2 files changed, 97 insertions, 24 deletions

diff --git a/Doc/api/concrete.tex b/Doc/api/concrete.tex
index 176d786..82990b6 100644
--- a/Doc/api/concrete.tex
+++ b/Doc/api/concrete.tex
@@ -2656,73 +2656,77 @@ module.  Before using any of these functions, the header file
 not include by \file{Python.h}), and macro \cfunction{PyDateTime_IMPORT()}
 must be invoked.  The macro arranges to put a pointer to a C structure
 in a static variable \code{PyDateTimeAPI}, which is used by the following
-macros:
+macros.
 
-\begin{cfuncdesc}{int}{PyDate_Check}{ob}
+Type-check macros:
+
+\begin{cfuncdesc}{int}{PyDate_Check}{PyObject *ob}
   Return true if \var{ob} is of type \cdata{PyDateTime_DateType} or
   a subtype of \cdata{PyDateTime_DateType}.  \var{ob} must not be
   \NULL{}.
   \versionadded{2.4}
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{int}{PyDate_CheckExact}{ob}
+\begin{cfuncdesc}{int}{PyDate_CheckExact}{PyObject *ob}
   Return true if \var{ob} is of type \cdata{PyDateTime_DateType}.
   \var{ob} must not be \NULL{}.
   \versionadded{2.4}
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{int}{PyDateTime_Check}{ob}
+\begin{cfuncdesc}{int}{PyDateTime_Check}{PyObject *ob}
   Return true if \var{ob} is of type \cdata{PyDateTime_DateTimeType} or
   a subtype of \cdata{PyDateTime_DateTimeType}.  \var{ob} must not be
   \NULL{}.
   \versionadded{2.4}
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{int}{PyDateTime_CheckExact}{ob}
+\begin{cfuncdesc}{int}{PyDateTime_CheckExact}{PyObject *ob}
   Return true if \var{ob} is of type \cdata{PyDateTime_DateTimeType}.
   \var{ob} must not be \NULL{}.
   \versionadded{2.4}
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{int}{PyTime_Check}{ob}
+\begin{cfuncdesc}{int}{PyTime_Check}{PyObject *ob}
   Return true if \var{ob} is of type \cdata{PyDateTime_TimeType} or
   a subtype of \cdata{PyDateTime_TimeType}.  \var{ob} must not be
   \NULL{}.
   \versionadded{2.4}
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{int}{PyTime_CheckExact}{ob}
+\begin{cfuncdesc}{int}{PyTime_CheckExact}{PyObject *ob}
   Return true if \var{ob} is of type \cdata{PyDateTime_TimeType}.
   \var{ob} must not be \NULL{}.
   \versionadded{2.4}
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{int}{PyDelta_Check}{ob}
+\begin{cfuncdesc}{int}{PyDelta_Check}{PyObject *ob}
   Return true if \var{ob} is of type \cdata{PyDateTime_DeltaType} or
   a subtype of \cdata{PyDateTime_DeltaType}.  \var{ob} must not be
   \NULL{}.
   \versionadded{2.4}
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{int}{PyDelta_CheckExact}{ob}
+\begin{cfuncdesc}{int}{PyDelta_CheckExact}{PyObject *ob}
   Return true if \var{ob} is of type \cdata{PyDateTime_DeltaType}.
   \var{ob} must not be \NULL{}.
   \versionadded{2.4}
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{int}{PyTZInfo_Check}{ob}
+\begin{cfuncdesc}{int}{PyTZInfo_Check}{PyObject *ob}
   Return true if \var{ob} is of type \cdata{PyDateTime_TZInfoType} or
   a subtype of \cdata{PyDateTime_TZInfoType}.  \var{ob} must not be
   \NULL{}.
   \versionadded{2.4}
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{int}{PyTZInfo_CheckExact}{ob}
+\begin{cfuncdesc}{int}{PyTZInfo_CheckExact}{PyObject *ob}
   Return true if \var{ob} is of type \cdata{PyDateTime_TZInfoType}.
   \var{ob} must not be \NULL{}.
   \versionadded{2.4}
 \end{cfuncdesc}
 
+Macros to create objects:
+
 \begin{cfuncdesc}{PyObject*}{PyDate_FromDate}{int year, int month, int day}
   Return a \code{datetime.date} object with the specified year, month
   and day.
@@ -2752,18 +2756,84 @@ macros:
   \versionadded{2.4}
 \end{cfuncdesc}
 
+Macros to extract fields from date objects.  The argument must an
+instance of \cdata{PyDateTime_Date}, including subclasses (such as
+\cdata{PyDateTime_DateTime}).  The argument must not be \NULL{}, and
+the type is not checked:
+
+\begin{cfuncdesc}{int}{PyDateTime_GET_YEAR}{PyDateTime_Date *o}
+  Return the year, as a positive int.
+  \versionadded{2.4}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyDateTime_GET_MONTH}{PyDateTime_Date *o}
+  Return the month, as an int from 1 through 12.
+  \versionadded{2.4}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyDateTime_GET_DAY}{PyDateTime_Date *o}
+  Return the day, as an int from 1 through 31.
+  \versionadded{2.4}
+\end{cfuncdesc}
+
+Macros to extract fields from datetime objects.  The argument must an
+instance of \cdata{PyDateTime_DateTime}, including subclasses.
+The argument must not be \NULL{}, and the type is not checked:
+
+\begin{cfuncdesc}{int}{PyDateTime_DATE_GET_HOUR}{PyDateTime_DateTime *o}
+  Return the hour, an an int from 0 though 23.
+  \versionadded{2.4}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyDateTime_DATE_GET_MINUTE}{PyDateTime_DateTime *o}
+  Return the minute, as an int from 0 through 59.
+  \versionadded{2.4}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyDateTime_DATE_GET_SECOND}{PyDateTime_DateTime *o}
+  Return the second, as an int from 0 through 59.
+  \versionadded{2.4}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyDateTime_DATE_GET_MICROSECOND}{PyDateTime_DateTime *o}
+  Return the microsecond, as an int from 0 through 999999.
+  \versionadded{2.4}
+\end{cfuncdesc}
+
+Macros to extract fields from time objects.  The argument must an
+instance of \cdata{PyDateTime_Time}, including subclasses.
+The argument must not be \NULL{}, and the type is not checked:
+
+\begin{cfuncdesc}{int}{PyDateTime_TIME_GET_HOUR}{PyDateTime_Time *o}
+  Return the hour, as an int from 0 though 23.
+  \versionadded{2.4}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyDateTime_TIME_GET_MINUTE}{PyDateTime_Time *o}
+  Return the minute, as an int from 0 through 59.
+  \versionadded{2.4}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyDateTime_TIME_GET_SECOND}{PyDateTime_Time *o}
+  Return the second, as an int from 0 through 59.
+  \versionadded{2.4}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyDateTime_TIME_GET_MICROSECOND}{PyDateTime_Time *o}
+  Return the microsecond, as an int from 0 through 999999.
+  \versionadded{2.4}
+\end{cfuncdesc}
+
+Macros for the convenience of modules implementing the DB API:
+
 \begin{cfuncdesc}{PyObject*}{PyDateTime_FromTimestamp}{PyObject *args}
   Create and return a new \code{datetime.datetime} object given an argument
   tuple suitable for passing to \code{datetime.datetime.fromtimestamp()}.
-  This macro is included for the convenience of modules implementing the
-  DB API.
   \versionadded{2.4}
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{PyObject*}{PyDate_FromTimestamp}{PyObject *args}
   Create and return a new \code{datetime.date} object given an argument
   tuple suitable for passing to \code{datetime.date.fromtimestamp()}.
-  This macro is included for the convenience of modules implementing the
-  DB API.
   \versionadded{2.4}
 \end{cfuncdesc}
diff --git a/Misc/NEWS b/Misc/NEWS
index 507c7a5..5593f00 100644
--- a/Misc/NEWS
+++ b/Misc/NEWS
@@ -13,13 +13,13 @@ Core and builtins
 -----------------
 
 - Patch #550732: Add PyArg_VaParseTupleAndKeywords().  Analogous to
-PyArg_VaParse().  Both are now documented.  Thanks Greg Chapman.
+  PyArg_VaParse().  Both are now documented.  Thanks Greg Chapman.
 
 - Allow string and unicode return types from .encode()/.decode()
-  methods on string and unicode objects. Added unicode.decode()
+  methods on string and unicode objects.  Added unicode.decode()
   which was missing for no apparent reason.
 
-- An attempt to fix the mess that is Python's behaviour with 
+- An attempt to fix the mess that is Python's behaviour with
   signal handlers and threads, complicated by readline's behaviour.
   It's quite possible that there are still bugs here.
 
@@ -29,9 +29,9 @@ Extension modules
 Library
 -------
 
-- Bug #979794: difflib.get_grouped_opcodes() now handles the case of when it is
-  comparing two empty lists.  Was affecting both context_diff() and
-  unified_diff().  Was also a duplicate of bug #980117.
+- Bugs #979794 and #980117: difflib.get_grouped_opcodes() now handles the
+  case of comparing two empty lists.  This affected both context_diff() and
+  unified_diff(),
 
 - Bug #980938: smtplib now prints debug output to sys.stderr.
 
@@ -47,7 +47,7 @@ Library
   for file sizes (compressed and uncompressed) was being stored as signed
   instead of unsigned.
 
-- decimal.py now only uses signals in the spec.  The other conditions are
+- decimal.py now only uses signals in the IBM spec.  The other conditions are
   no longer part of the public API.
 
 - codecs module now has two new generic APIs: encode() and decode()
@@ -57,7 +57,7 @@ Library
 - asyncore's dispatcher.set_reuse_addr() now works correctly on Windows.
   SF patch 982681.
 
-- Non-blocking SSL sockets work again; they were broken in Python 2.3. 
+- Non-blocking SSL sockets work again; they were broken in Python 2.3.
   SF patch 945642.
 
 Tools/Demos
@@ -69,6 +69,9 @@ Build
 C API
 -----
 
+- A large pile of datetime field-extraction macros is now documented,
+  thanks to Anthony Tuininga (patch #986010).
+
 New platforms
 -------------
 
@@ -438,7 +441,7 @@ Extension modules
 
 Library
 -------
-  
+
 - Bug #981530: Fix UnboundLocalError in shutil.rmtree().  This affects
   the documented behavior: the function passed to the onerror()
   handler can now also be os.listdir.