From 183dabcd73e502e5f9b1a2b747807f44b35584ca Mon Sep 17 00:00:00 2001 From: Tim Peters Date: Sun, 11 Jul 2004 19:26:19 +0000 Subject: 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. --- Doc/api/concrete.tex | 100 +++++++++++++++++++++++++++++++++++++++++++-------- Misc/NEWS | 21 ++++++----- 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. -- cgit v0.12