[Python-checkins] python/dist/src/Doc/api concrete.tex,1.44,1.45

Sun Jun 20 18:41:57 EDT 2004

Update of /cvsroot/python/python/dist/src/Doc/api
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv18815/Doc/api
Modified Files:
	concrete.tex 
Log Message:
SF patch 876130: add C API to datetime module, from Anthony Tuininga.
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.
Index: concrete.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/api/concrete.tex,v
retrieving revision 1.44
retrieving revision 1.45
diff -C2 -d -r1.44 -r1.45
*** concrete.tex	8 Jun 2004 02:58:50 -0000	1.44
--- concrete.tex	20 Jun 2004 22:41:23 -0000	1.45
***************
*** 138,142 ****
 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
 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
--- 138,142 ----
 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
 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
***************
*** 249,253 ****
 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
 point to the first character in \var{str} which follows the
 representation of the number. If \var{base} is \code{0}, the radix
--- 249,253 ----
 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
 point to the first character in \var{str} which follows the
 representation of the number. If \var{base} is \code{0}, the radix
***************
*** 539,543 ****
 \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
 will not be checked.
 \end{cfuncdesc}
--- 539,543 ----
 \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
 will not be checked.
 \end{cfuncdesc}
***************
*** 547,551 ****
 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.
 \end{cfuncdesc}

--- 547,551 ----
 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.
 \end{cfuncdesc}

***************
*** 616,620 ****
 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
 contain NUL characters; if it does, the function returns \code{-1}
 and a \exception{TypeError} is raised.
--- 616,620 ----
 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
 contain NUL characters; if it does, the function returns \code{-1}
 and a \exception{TypeError} is raised.
***************
*** 637,641 ****
 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
 be set.
 \end{cfuncdesc}
--- 637,641 ----
 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
 be set.
 \end{cfuncdesc}
***************
*** 899,905 ****
 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,
 modification of the resulting Unicode object is only allowed when
! \var{u} is \NULL.
 \end{cfuncdesc}

--- 899,905 ----
 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,
 modification of the resulting Unicode object is only allowed when
! \var{u} is \NULL{}.
 \end{cfuncdesc}

***************
*** 1071,1077 ****
 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''.

! If \var{byteorder} is non-\NULL, the decoder starts decoding using
 the given byte order:

--- 1071,1077 ----
 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''.

! If \var{byteorder} is non-\NULL{}, the decoder starts decoding using
 the given byte order:

***************
*** 1087,1091 ****
 byte order at the end of input data.

! If \var{byteorder} is \NULL, the codec starts in native order mode.

 Returns \NULL{} if an exception was raised by the codec.
--- 1087,1091 ----
 byte order at the end of input data.

! If \var{byteorder} is \NULL{}, the codec starts in native order mode.

 Returns \NULL{} if an exception was raised by the codec.
***************
*** 1352,1356 ****
 PyObject *sep,
 int maxsplit}
! 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
--- 1352,1356 ----
 PyObject *sep,
 int maxsplit}
! 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
***************
*** 1606,1610 ****
 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}			 
 \end{cfuncdesc}

--- 1606,1610 ----
 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}
 \end{cfuncdesc}

***************
*** 1662,1666 ****
 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
 \exception{MemoryError} or
 \exception{SystemError}.
--- 1662,1666 ----
 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
 \exception{MemoryError} or
 \exception{SystemError}.
***************
*** 1842,1846 ****
 \code{0}. On error, return \code{-1}. This is equivalent to the
 Python expression \samp{\var{key} in \var{p}}.
! \versionadded{2.4}			 
 \end{cfuncdesc}

--- 1842,1846 ----
 \code{0}. On error, return \code{-1}. This is equivalent to the
 Python expression \samp{\var{key} in \var{p}}.
! \versionadded{2.4}
 \end{cfuncdesc}

***************
*** 1924,1928 ****
 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
 them are borrowed. \var{ppos} should not be altered during iteration.
 Its value represents offsets within the internal dictionary structure,
--- 1924,1928 ----
 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
 them are borrowed. \var{ppos} should not be altered during iteration.
 Its value represents offsets within the internal dictionary structure,
***************
*** 2041,2045 ****
 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.
 \end{cfuncdesc}

--- 2041,2045 ----
 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{}.
 \end{cfuncdesc}

***************
*** 2144,2148 ****
 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.
 \end{cfuncdesc}

--- 2144,2148 ----
 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.
 \end{cfuncdesc}

***************
*** 2162,2166 ****
 \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.
 \end{cfuncdesc}

--- 2162,2166 ----
 \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{}.
 \end{cfuncdesc}

***************
*** 2197,2201 ****
 \begin{cfuncdesc}{PyObject*}{PyMethod_Self}{PyObject *meth}
 Return the instance associated with the method \var{meth} if it is
! bound, otherwise return \NULL.
 \end{cfuncdesc}

--- 2197,2201 ----
 \begin{cfuncdesc}{PyObject*}{PyMethod_Self}{PyObject *meth}
 Return the instance associated with the method \var{meth} if it is
! bound, otherwise return \NULL{}.
 \end{cfuncdesc}

***************
*** 2261,2265 ****
 \var{module}'s \member{__file__} attribute. If this is not defined,
 or if it is not a string, raise \exception{SystemError} and return
! \NULL.
 \withsubitem{(module attribute)}{\ttindex{__file__}}
 \withsubitem{(built-in exception)}{\ttindex{SystemError}}
--- 2261,2265 ----
 \var{module}'s \member{__file__} attribute. If this is not defined,
 or if it is not a string, raise \exception{SystemError} and return
! \NULL{}.
 \withsubitem{(module attribute)}{\ttindex{__file__}}
 \withsubitem{(built-in exception)}{\ttindex{SystemError}}
***************
*** 2402,2406 ****
 \begin{cfuncdesc}{int}{PySlice_Check}{PyObject *ob}
 Returns true if \var{ob} is a slice object; \var{ob} must not be
! \NULL.
 \end{cfuncdesc}

--- 2402,2406 ----
 \begin{cfuncdesc}{int}{PySlice_Check}{PyObject *ob}
 Returns true if \var{ob} is a slice object; \var{ob} must not be
! \NULL{}.
 \end{cfuncdesc}

***************
*** 2410,2414 ****
 \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
 corresponding attribute. Returns \NULL{} if the new object could
 not be allocated.
--- 2410,2414 ----
 \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
 corresponding attribute. Returns \NULL{} if the new object could
 not be allocated.
***************
*** 2432,2436 ****

 \begin{cfuncdesc}{int}{PySlice_GetIndicesEx}{PySliceObject *slice, int length,
! int *start, int *stop, int *step, 
 int *slicelength}
 Usable replacement for \cfunction{PySlice_GetIndices}. Retrieve the
--- 2432,2436 ----

 \begin{cfuncdesc}{int}{PySlice_GetIndicesEx}{PySliceObject *slice, int length,
! int *start, int *stop, int *step,
 int *slicelength}
 Usable replacement for \cfunction{PySlice_GetIndices}. Retrieve the
***************
*** 2476,2482 ****
 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 a weakly-referencable object, or if \var{callback} is not
! callable, \code{None}, or \NULL, this will return \NULL{} and
 raise \exception{TypeError}.
 \versionadded{2.2}
--- 2476,2482 ----
 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 a weakly-referencable object, or if \var{callback} is not
! callable, \code{None}, or \NULL{}, this will return \NULL{} and
 raise \exception{TypeError}.
 \versionadded{2.2}
***************
*** 2491,2497 ****
 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
 a weakly-referencable object, or if \var{callback} is not callable,
! \code{None}, or \NULL, this will return \NULL{} and raise
 \exception{TypeError}.
 \versionadded{2.2}
--- 2491,2497 ----
 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
 a weakly-referencable object, or if \var{callback} is not callable,
! \code{None}, or \NULL{}, this will return \NULL{} and raise
 \exception{TypeError}.
 \versionadded{2.2}
***************
*** 2536,2540 ****
 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.
 \end{cfuncdesc}

--- 2536,2540 ----
 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{}.
 \end{cfuncdesc}

***************
*** 2558,2562 ****

 \begin{cfuncdesc}{int}{PyCObject_SetVoidPtr}{PyObject* self, void* 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.
--- 2558,2562 ----

 \begin{cfuncdesc}{int}{PyCObject_SetVoidPtr}{PyObject* self, void* 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.
***************
*** 2586,2595 ****
 \begin{cfuncdesc}{int}{PyCell_Check}{ob}
 Return true if \var{ob} is a cell object; \var{ob} must not be
! \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.
 \end{cfuncdesc}

--- 2586,2595 ----
 \begin{cfuncdesc}{int}{PyCell_Check}{ob}
 Return true if \var{ob} is a cell object; \var{ob} must not be
! \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{}.
 \end{cfuncdesc}

***************
*** 2606,2610 ****
 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
 not a cell object, \code{-1} will be returned. On success, \code{0}
 will be returned.
--- 2606,2610 ----
 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
 not a cell object, \code{-1} will be returned. On success, \code{0}
 will be returned.
***************
*** 2634,2638 ****
 \begin{cfuncdesc}{int}{PyGen_Check}{ob}
 Return true if \var{ob} is a generator object; \var{ob} must not be
! \NULL.
 \end{cfuncdesc}

--- 2634,2638 ----
 \begin{cfuncdesc}{int}{PyGen_Check}{ob}
 Return true if \var{ob} is a generator object; \var{ob} must not be
! \NULL{}.
 \end{cfuncdesc}

***************
*** 2640,2648 ****
 Return true if \var{ob}'s type is \var{PyGen_Type}
 is a generator object; \var{ob} must not be
! \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.
 \end{cfuncdesc}
--- 2640,2769 ----
 Return true if \var{ob}'s type is \var{PyGen_Type}
 is a generator object; \var{ob} must not be
! \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{}.
! \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}