mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-07-24 11:44:31 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 8

SF patch 876130: add C API to datetime module, from Anthony Tuininga.

Browse source 
The LaTeX is untested (well, so is the new API, for that matter).
Note that I also changed NULL to get spelled consistently in concrete.tex.
If that was a wrong thing to do, Fred should yell at me.
This commit is contained in:
Tim Peters 2004-06-20 22:41:32 +00:00
parent 873a277eb4
commit 9ddf40b4e1
5 changed files with 287 additions and 36 deletions
Download patch file Download diff file Expand all files Collapse all files

193
Doc/api/concrete.tex
View file

@ -137,7 +137,7 @@ There is no \cfunction{PyNone_Check()} function for the same reason.
int base}
Return a new \ctype{PyIntObject} or \ctype{PyLongObject} based on the
string value in \var{str}, which is interpreted according to the radix in
\var{base}. If \var{pend} is non-\NULL, \code{*\var{pend}} will point to
\var{base}. If \var{pend} is non-\NULL{}, \code{*\var{pend}} will point to
the first character in \var{str} which follows the representation of the
number. If \var{base} is \code{0}, the radix will be determined based on
the leading characters of \var{str}: if \var{str} starts with \code{'0x'}
@ -248,7 +248,7 @@ There is no \cfunction{PyNone_Check()} function for the same reason.
int base}
Return a new \ctype{PyLongObject} based on the string value in
\var{str}, which is interpreted according to the radix in
\var{base}. If \var{pend} is non-\NULL, \code{*\var{pend}} will
\var{base}. If \var{pend} is non-\NULL{}, \code{*\var{pend}} will
point to the first character in \var{str} which follows the
representation of the number. If \var{base} is \code{0}, the radix
will be determined based on the leading characters of \var{str}: if
@ -538,7 +538,7 @@ parameter and are called with a non-string parameter.
\begin{cfuncdesc}{PyObject*}{PyString_FromString}{const char *v}
Returns a new string object with the value \var{v} on success, and
\NULL{} on failure. The parameter \var{v} must not be \NULL; it
\NULL{} on failure. The parameter \var{v} must not be \NULL{}; it
will not be checked.
\end{cfuncdesc}
@ -546,7 +546,7 @@ parameter and are called with a non-string parameter.
int len}
Returns a new string object with the value \var{v} and length
\var{len} on success, and \NULL{} on failure. If \var{v} is
\NULL, the contents of the string are uninitialized.
\NULL{}, the contents of the string are uninitialized.
\end{cfuncdesc}
\begin{cfuncdesc}{PyObject*}{PyString_FromFormat}{const char *format, ...}
@ -615,7 +615,7 @@ parameter and are called with a non-string parameter.
The function accepts both string and Unicode objects as input. For
Unicode objects it returns the default encoded version of the
object. If \var{length} is \NULL, the resulting buffer may not
object. If \var{length} is \NULL{}, the resulting buffer may not
contain NUL characters; if it does, the function returns \code{-1}
and a \exception{TypeError} is raised.
@ -636,7 +636,7 @@ parameter and are called with a non-string parameter.
new reference. The reference to the old value of \var{string} will
be stolen. If the new string cannot be created, the old reference
to \var{string} will still be discarded and the value of
\var{*string} will be set to \NULL; the appropriate exception will
\var{*string} will be set to \NULL{}; the appropriate exception will
be set.
\end{cfuncdesc}
@ -898,9 +898,9 @@ use these APIs:
given size. \var{u} may be \NULL{} which causes the contents to be
undefined. It is the user's responsibility to fill in the needed
data. The buffer is copied into the new object. If the buffer is
not \NULL, the return value might be a shared object. Therefore,
not \NULL{}, the return value might be a shared object. Therefore,
modification of the resulting Unicode object is only allowed when
\var{u} is \NULL.
\var{u} is \NULL{}.
\end{cfuncdesc}
\begin{cfuncdesc}{Py_UNICODE*}{PyUnicode_AsUnicode}{PyObject *unicode}
@ -1070,9 +1070,9 @@ These are the UTF-16 codec APIs:
int *byteorder}
Decodes \var{length} bytes from a UTF-16 encoded buffer string and
returns the corresponding Unicode object. \var{errors} (if
non-\NULL) defines the error handling. It defaults to ``strict''.
non-\NULL{}) defines the error handling. It defaults to ``strict''.
If \var{byteorder} is non-\NULL, the decoder starts decoding using
If \var{byteorder} is non-\NULL{}, the decoder starts decoding using
the given byte order:
\begin{verbatim}
@ -1086,7 +1086,7 @@ These are the UTF-16 codec APIs:
string. After completion, \var{*byteorder} is set to the current
byte order at the end of input data.
If \var{byteorder} is \NULL, the codec starts in native order mode.
If \var{byteorder} is \NULL{}, the codec starts in native order mode.
Returns \NULL{} if an exception was raised by the codec.
\end{cfuncdesc}
@ -1351,7 +1351,7 @@ They all return \NULL{} or \code{-1} if an exception occurs.
\begin{cfuncdesc}{PyObject*}{PyUnicode_Split}{PyObject *s,
PyObject *sep,
int maxsplit}
Split a string giving a list of Unicode strings. If sep is \NULL,
Split a string giving a list of Unicode strings. If sep is \NULL{},
splitting will be done at all whitespace substrings. Otherwise,
splits occur at the given separator. At most \var{maxsplit} splits
will be done. If negative, no limit is set. Separators are not
@ -1605,7 +1605,7 @@ format.
The tuple values are initialized to the subsequent \var{n} C arguments
pointing to Python objects. \samp{PyTuple_Pack(2, \var{a}, \var{b})}
is equivalent to \samp{Py_BuildValue("(OO)", \var{a}, \var{b})}.
\versionadded{2.4}
\versionadded{2.4}
\end{cfuncdesc}
\begin{cfuncdesc}{int}{PyTuple_Size}{PyObject *p}
@ -1661,7 +1661,7 @@ format.
\code{*\var{p}} will be the same as before calling this function.
If the object referenced by \code{*\var{p}} is replaced, the
original \code{*\var{p}} is destroyed. On failure, returns
\code{-1} and sets \code{*\var{p}} to \NULL, and raises
\code{-1} and sets \code{*\var{p}} to \NULL{}, and raises
\exception{MemoryError} or
\exception{SystemError}.
\versionchanged[Removed unused third parameter, \var{last_is_sticky}]{2.2}
@ -1841,7 +1841,7 @@ format.
in \var{p} is matches \var{key}, return \code{1}, otherwise return
\code{0}. On error, return \code{-1}. This is equivalent to the
Python expression \samp{\var{key} in \var{p}}.
\versionadded{2.4}
\versionadded{2.4}
\end{cfuncdesc}
\begin{cfuncdesc}{PyObject*}{PyDict_Copy}{PyObject *p}
@ -1923,7 +1923,7 @@ format.
dictionary, and false once all pairs have been reported. The
parameters \var{pkey} and \var{pvalue} should either point to
\ctype{PyObject*} variables that will be filled in with each key and
value, respectively, or may be \NULL. Any references returned through
value, respectively, or may be \NULL{}. Any references returned through
them are borrowed. \var{ppos} should not be altered during iteration.
Its value represents offsets within the internal dictionary structure,
and since the structure is sparse, the offsets are not consecutive.
@ -2040,7 +2040,7 @@ implementation detail and may change in future releases of Python.
On success, returns a new file object that is opened on the file
given by \var{filename}, with a file mode given by \var{mode}, where
\var{mode} has the same semantics as the standard C routine
\cfunction{fopen()}\ttindex{fopen()}. On failure, returns \NULL.
\cfunction{fopen()}\ttindex{fopen()}. On failure, returns \NULL{}.
\end{cfuncdesc}
\begin{cfuncdesc}{PyObject*}{PyFile_FromFile}{FILE *fp,
@ -2143,7 +2143,7 @@ There are very few functions specific to instance objects.
Create a new instance of a specific class without calling it's
constructor. \var{class} is the class of new object. The
\var{dict} parameter will be used as the object's \member{__dict__};
if \NULL, a new dictionary will be created for the instance.
if \NULL{}, a new dictionary will be created for the instance.
\end{cfuncdesc}
@ -2161,7 +2161,7 @@ method objects.
\begin{cfuncdesc}{int}{PyMethod_Check}{PyObject *o}
Return true if \var{o} is a method object (has type
\cdata{PyMethod_Type}). The parameter must not be \NULL.
\cdata{PyMethod_Type}). The parameter must not be \NULL{}.
\end{cfuncdesc}
\begin{cfuncdesc}{PyObject*}{PyMethod_New}{PyObject *func.
@ -2196,7 +2196,7 @@ method objects.
\begin{cfuncdesc}{PyObject*}{PyMethod_Self}{PyObject *meth}
Return the instance associated with the method \var{meth} if it is
bound, otherwise return \NULL.
bound, otherwise return \NULL{}.
\end{cfuncdesc}
\begin{cfuncdesc}{PyObject*}{PyMethod_GET_SELF}{PyObject *meth}
@ -2260,7 +2260,7 @@ There are only a few functions special to module objects.
Return the name of the file from which \var{module} was loaded using
\var{module}'s \member{__file__} attribute. If this is not defined,
or if it is not a string, raise \exception{SystemError} and return
\NULL.
\NULL{}.
\withsubitem{(module attribute)}{\ttindex{__file__}}
\withsubitem{(built-in exception)}{\ttindex{SystemError}}
\end{cfuncdesc}
@ -2401,7 +2401,7 @@ They are found in the dictionary of type objects.
\begin{cfuncdesc}{int}{PySlice_Check}{PyObject *ob}
Returns true if \var{ob} is a slice object; \var{ob} must not be
\NULL.
\NULL{}.
\end{cfuncdesc}
\begin{cfuncdesc}{PyObject*}{PySlice_New}{PyObject *start, PyObject *stop,
@ -2409,7 +2409,7 @@ They are found in the dictionary of type objects.
Return a new slice object with the given values. The \var{start},
\var{stop}, and \var{step} parameters are used as the values of the
slice object attributes of the same names. Any of the values may be
\NULL, in which case the \code{None} will be used for the
\NULL{}, in which case the \code{None} will be used for the
corresponding attribute. Returns \NULL{} if the new object could
not be allocated.
\end{cfuncdesc}
@ -2431,7 +2431,7 @@ suitably renamed, in the source of your extension.
\end{cfuncdesc}
\begin{cfuncdesc}{int}{PySlice_GetIndicesEx}{PySliceObject *slice, int length,
int *start, int *stop, int *step,
int *start, int *stop, int *step,
int *slicelength}
Usable replacement for \cfunction{PySlice_GetIndices}. Retrieve the
start, stop, and step indices from the slice object \var{slice}
@ -2475,9 +2475,9 @@ acts as a proxy for the original object as much as it can.
parameter, \var{callback}, can be a callable object that receives
notification when \var{ob} is garbage collected; it should accept a
single parameter, which will be the weak reference object itself.
\var{callback} may also be \code{None} or \NULL. If \var{ob}
\var{callback} may also be \code{None} or \NULL{}. If \var{ob}
is not a weakly-referencable object, or if \var{callback} is not
callable, \code{None}, or \NULL, this will return \NULL{} and
callable, \code{None}, or \NULL{}, this will return \NULL{} and
raise \exception{TypeError}.
\versionadded{2.2}
\end{cfuncdesc}
@ -2490,9 +2490,9 @@ acts as a proxy for the original object as much as it can.
parameter, \var{callback}, can be a callable object that receives
notification when \var{ob} is garbage collected; it should accept a
single parameter, which will be the weak reference object itself.
\var{callback} may also be \code{None} or \NULL. If \var{ob} is not
\var{callback} may also be \code{None} or \NULL{}. If \var{ob} is not
a weakly-referencable object, or if \var{callback} is not callable,
\code{None}, or \NULL, this will return \NULL{} and raise
\code{None}, or \NULL{}, this will return \NULL{} and raise
\exception{TypeError}.
\versionadded{2.2}
\end{cfuncdesc}
@ -2535,7 +2535,7 @@ information on using these objects.
void (*destr)(void *)}
Create a \ctype{PyCObject} from the \code{void *}\var{cobj}. The
\var{destr} function will be called when the object is reclaimed,
unless it is \NULL.
unless it is \NULL{}.
\end{cfuncdesc}
\begin{cfuncdesc}{PyObject*}{PyCObject_FromVoidPtrAndDesc}{void* cobj,
@ -2557,7 +2557,7 @@ information on using these objects.
\end{cfuncdesc}
\begin{cfuncdesc}{int}{PyCObject_SetVoidPtr}{PyObject* self, void* cobj}
Set the void pointer inside \var{self} to \var{cobj}.
Set the void pointer inside \var{self} to \var{cobj}.
The \ctype{PyCObject} must not have an associated destructor.
Return true on success, false on failure.
\end{cfuncdesc}
@ -2585,12 +2585,12 @@ when accessed. Cell objects are not likely to be useful elsewhere.
\begin{cfuncdesc}{int}{PyCell_Check}{ob}
Return true if \var{ob} is a cell object; \var{ob} must not be
\NULL.
\NULL{}.
\end{cfuncdesc}
\begin{cfuncdesc}{PyObject*}{PyCell_New}{PyObject *ob}
Create and return a new cell object containing the value \var{ob}.
The parameter may be \NULL.
The parameter may be \NULL{}.
\end{cfuncdesc}
\begin{cfuncdesc}{PyObject*}{PyCell_Get}{PyObject *cell}
@ -2605,7 +2605,7 @@ when accessed. Cell objects are not likely to be useful elsewhere.
\begin{cfuncdesc}{int}{PyCell_Set}{PyObject *cell, PyObject *value}
Set the contents of the cell object \var{cell} to \var{value}. This
releases the reference to any current content of the cell.
\var{value} may be \NULL. \var{cell} must be non-\NULL; if it is
\var{value} may be \NULL{}. \var{cell} must be non-\NULL{}; if it is
not a cell object, \code{-1} will be returned. On success, \code{0}
will be returned.
\end{cfuncdesc}
@ -2633,16 +2633,137 @@ rather than explicitly calling \cfunction{PyGen_New}.
\begin{cfuncdesc}{int}{PyGen_Check}{ob}
Return true if \var{ob} is a generator object; \var{ob} must not be
\NULL.
\NULL{}.
\end{cfuncdesc}
\begin{cfuncdesc}{int}{PyGen_CheckExact}{ob}
Return true if \var{ob}'s type is \var{PyGen_Type}
is a generator object; \var{ob} must not be
\NULL.
\NULL{}.
\end{cfuncdesc}
\begin{cfuncdesc}{PyObject*}{PyGen_New}{PyFrameObject *frame}
Create and return a new generator object based on the \var{frame} object.
The parameter must not be \NULL.
The parameter must not be \NULL{}.
\end{cfuncdesc}
\subsection{DateTime Objects \label{datetime-objects}}
Various date and time objects are supplied by the \module{datetime}
module. Before using any of these functions, the header file
\file{datetime.h} must be included in your source (note that this is
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:
\begin{cfuncdesc}{int}{PyDate_Check}{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}
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}
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}
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}
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}
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}
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}
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}
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}
Return true if \var{ob} is of type \cdata{PyDateTime_TZInfoType}.
\var{ob} must not be \NULL{}.
\versionadded{2.4}
\end{cfuncdesc}
\begin{cfuncdesc}{PyObject*}{PyDate_FromDate}{int year, int month, int day}
Return a \code{datetime.date} object with the specified year, month
and day.
\versionadded{2.4}
\end{cfuncdesc}
\begin{cfuncdesc}{PyObject*}{PyDate_FromDateAndTime}{int year, int month,
int day, int hour, int minute, int second, int usecond}
Return a \code{datetime.datetime} object with the specified year, month,
day, hour, minute, second and microsecond.
\versionadded{2.4}
\end{cfuncdesc}
\begin{cfuncdesc}{PyObject*}{PyTime_FromTime}{int hour, int minute,
int second, int usecond}
Return a \code{datetime.time} object with the specified hour, minute,
second and microsecond.
\versionadded{2.4}
\end{cfuncdesc}
\begin{cfuncdesc}{PyObject*}{PyDelta_FromDSU}{int days, int seconds,
int useconds}
Return a \code{datetime.timedelta} object representing the given number
of days, seconds and microseconds. Normalization is performed so that
the resulting number of microseconds and seconds lie in the ranges
documented for \code{datetime.timedelta} objects.
\versionadded{2.4}
\end{cfuncdesc}
\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}