[Python-checkins] CVS: python/dist/src/Doc/api api.tex,1.135,1.136
Fred L. Drake
fdrake@users.sourceforge.net
Wed, 08 Aug 2001 12:14:56 -0700
Update of /cvsroot/python/python/dist/src/Doc/api
In directory usw-pr-cvs1:/tmp/cvs-serv1898/api
Modified Files:
api.tex
Log Message:
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
PyInterpreterState_*Head(), PyInterpreterState_Next(), and
PyThreadState_Next().
Wrapped some long lines, added some others.
Index: api.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/api/api.tex,v
retrieving revision 1.135
retrieving revision 1.136
diff -C2 -d -r1.135 -r1.136
*** api.tex 2001/08/02 18:00:28 1.135
--- api.tex 2001/08/08 19:14:53 1.136
***************
*** 1242,1246 ****
\end{cfuncdesc}
! \begin{cfuncdesc}{PyObject*}{PyImport_ImportModuleEx}{char *name, PyObject *globals, PyObject *locals, PyObject *fromlist}
Import a module. This is best described by referring to the built-in
Python function \function{__import__()}\bifuncindex{__import__}, as
--- 1242,1247 ----
\end{cfuncdesc}
! \begin{cfuncdesc}{PyObject*}{PyImport_ImportModuleEx}{char *name,
! PyObject *globals, PyObject *locals, PyObject *fromlist}
Import a module. This is best described by referring to the built-in
Python function \function{__import__()}\bifuncindex{__import__}, as
***************
*** 1501,1505 ****
! \begin{cfuncdesc}{int}{PyObject_SetAttrString}{PyObject *o, char *attr_name, PyObject *v}
Set the value of the attribute named \var{attr_name}, for object
\var{o}, to the value \var{v}. Returns \code{-1} on failure. This is
--- 1502,1507 ----
! \begin{cfuncdesc}{int}{PyObject_SetAttrString}{PyObject *o,
! char *attr_name, PyObject *v}
Set the value of the attribute named \var{attr_name}, for object
\var{o}, to the value \var{v}. Returns \code{-1} on failure. This is
***************
*** 1509,1513 ****
! \begin{cfuncdesc}{int}{PyObject_SetAttr}{PyObject *o, PyObject *attr_name, PyObject *v}
Set the value of the attribute named \var{attr_name}, for
object \var{o},
--- 1511,1516 ----
! \begin{cfuncdesc}{int}{PyObject_SetAttr}{PyObject *o,
! PyObject *attr_name, PyObject *v}
Set the value of the attribute named \var{attr_name}, for
object \var{o},
***************
*** 1696,1700 ****
! \begin{cfuncdesc}{int}{PyObject_SetItem}{PyObject *o, PyObject *key, PyObject *v}
Map the object \var{key} to the value \var{v}.
Returns \code{-1} on failure. This is the equivalent
--- 1699,1704 ----
! \begin{cfuncdesc}{int}{PyObject_SetItem}{PyObject *o,
! PyObject *key, PyObject *v}
Map the object \var{key} to the value \var{v}.
Returns \code{-1} on failure. This is the equivalent
***************
*** 1717,1720 ****
--- 1721,1725 ----
\end{cfuncdesc}
+
\section{Number Protocol \label{number}}
***************
*** 1755,1758 ****
--- 1760,1781 ----
+ \begin{cfuncdesc}{PyObject*}{PyNumber_FloorDivide}{PyObject *o1, PyObject *o2}
+ Return the floor of \var{o1} divided by \var{o2}, or \NULL{} on
+ failure. This is equivalent to the ``classic'' division of integers.
+ \versionadded{2.2}
+ \end{cfuncdesc}
+
+
+ \begin{cfuncdesc}{PyObject*}{PyNumber_TrueDivide}{PyObject *o1, PyObject *o2}
+ Return a reasonable approximation for the mathematical value of
+ \var{o1} divided by \var{o2}, or \NULL{} on failure. The return value
+ is ``approximate'' because binary floating point numbers are
+ approximate; it is not possible to represent all real numbers in base
+ two. This function can return a floating point value when passed two
+ integers.
+ \versionadded{2.2}
+ \end{cfuncdesc}
+
+
\begin{cfuncdesc}{PyObject*}{PyNumber_Remainder}{PyObject *o1, PyObject *o2}
Returns the remainder of dividing \var{o1} by \var{o2}, or \NULL{} on
***************
*** 1769,1773 ****
! \begin{cfuncdesc}{PyObject*}{PyNumber_Power}{PyObject *o1, PyObject *o2, PyObject *o3}
See the built-in function \function{pow()}\bifuncindex{pow}. Returns
\NULL{} on failure. This is the equivalent of the Python expression
--- 1792,1797 ----
! \begin{cfuncdesc}{PyObject*}{PyNumber_Power}{PyObject *o1,
! PyObject *o2, PyObject *o3}
See the built-in function \function{pow()}\bifuncindex{pow}. Returns
\NULL{} on failure. This is the equivalent of the Python expression
***************
*** 1839,1900 ****
\begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceAdd}{PyObject *o1, PyObject *o2}
! Returns the result of adding \var{o1} and \var{o2}, or \NULL{} on failure.
! The operation is done \emph{in-place} when \var{o1} supports it. This is the
! equivalent of the Python expression \samp{\var{o1} += \var{o2}}.
\end{cfuncdesc}
! \begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceSubtract}{PyObject *o1, PyObject *o2}
Returns the result of subtracting \var{o2} from \var{o1}, or
! \NULL{} on failure. The operation is done \emph{in-place} when \var{o1}
! supports it. This is the equivalent of the Python expression \samp{\var{o1}
! -= \var{o2}}.
\end{cfuncdesc}
! \begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceMultiply}{PyObject *o1, PyObject *o2}
Returns the result of multiplying \var{o1} and \var{o2}, or \NULL{} on
failure. The operation is done \emph{in-place} when \var{o1} supports it.
! This is the equivalent of the Python expression \samp{\var{o1} *= \var{o2}}.
\end{cfuncdesc}
! \begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceDivide}{PyObject *o1, PyObject *o2}
! Returns the result of dividing \var{o1} by \var{o2}, or \NULL{} on failure.
! The operation is done \emph{in-place} when \var{o1} supports it. This is the
! equivalent of the Python expression \samp{\var{o1} /= \var{o2}}.
\end{cfuncdesc}
! \begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceRemainder}{PyObject *o1, PyObject *o2}
Returns the remainder of dividing \var{o1} by \var{o2}, or \NULL{} on
failure. The operation is done \emph{in-place} when \var{o1} supports it.
! This is the equivalent of the Python expression \samp{\var{o1} \%= \var{o2}}.
\end{cfuncdesc}
! \begin{cfuncdesc}{PyObject*}{PyNumber_InPlacePower}{PyObject *o1, PyObject *o2, PyObject *o3}
! See the built-in function \function{pow()}\bifuncindex{pow}. Returns
! \NULL{} on failure. The operation is done \emph{in-place} when \var{o1}
! supports it. This is the equivalent of the Python expression \samp{\var{o1}
! **= \var{o2}} when o3 is \cdata{Py_None}, or an in-place variant of
! \samp{pow(\var{o1}, \var{o2}, \var{o3})} otherwise. If \var{o3} is to be
! ignored, pass \cdata{Py_None} in its place (passing \NULL{} for \var{o3}
! would cause an illegal memory access).
\end{cfuncdesc}
! \begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceLshift}{PyObject *o1, PyObject *o2}
! Returns the result of left shifting \var{o1} by \var{o2} on success, or
! \NULL{} on failure. The operation is done \emph{in-place} when \var{o1}
! supports it. This is the equivalent of the Python expression \samp{\var{o1}
! <\code{<=} \var{o2}}.
\end{cfuncdesc}
! \begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceRshift}{PyObject *o1, PyObject *o2}
! Returns the result of right shifting \var{o1} by \var{o2} on success, or
! \NULL{} on failure. The operation is done \emph{in-place} when \var{o1}
! supports it. This is the equivalent of the Python expression \samp{\var{o1}
! >\code{>=} \var{o2}}.
\end{cfuncdesc}
--- 1863,1957 ----
\begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceAdd}{PyObject *o1, PyObject *o2}
! Returns the result of adding \var{o1} and \var{o2}, or \NULL{} on
! failure. The operation is done \emph{in-place} when \var{o1} supports
! it. This is the equivalent of the Python statement \samp{\var{o1} +=
! \var{o2}}.
\end{cfuncdesc}
! \begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceSubtract}{PyObject *o1,
! PyObject *o2}
Returns the result of subtracting \var{o2} from \var{o1}, or
! \NULL{} on failure. The operation is done \emph{in-place} when
! \var{o1} supports it. This is the equivalent of the Python statement
! \samp{\var{o1} -= \var{o2}}.
\end{cfuncdesc}
! \begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceMultiply}{PyObject *o1,
! PyObject *o2}
Returns the result of multiplying \var{o1} and \var{o2}, or \NULL{} on
failure. The operation is done \emph{in-place} when \var{o1} supports it.
! This is the equivalent of the Python statement \samp{\var{o1} *= \var{o2}}.
\end{cfuncdesc}
! \begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceDivide}{PyObject *o1,
! PyObject *o2}
! Returns the result of dividing \var{o1} by \var{o2}, or \NULL{} on
! failure. The operation is done \emph{in-place} when \var{o1} supports
! it. This is the equivalent of the Python statement \samp{\var{o1} /=
! \var{o2}}.
\end{cfuncdesc}
! \begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceFloorDivide}{PyObject *o1,
! PyObject *o2}
! Returns the mathematical of dividing \var{o1} by \var{o2}, or \NULL{}
! on failure. The operation is done \emph{in-place} when \var{o1}
! supports it. This is the equivalent of the Python statement
! \samp{\var{o1} //= \var{o2}}.
! \versionadded{2.2}
! \end{cfuncdesc}
!
!
! \begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceTrueDivide}{PyObject *o1,
! PyObject *o2}
! Return a reasonable approximation for the mathematical value of
! \var{o1} divided by \var{o2}, or \NULL{} on failure. The return value
! is ``approximate'' because binary floating point numbers are
! approximate; it is not possible to represent all real numbers in base
! two. This function can return a floating point value when passed two
! integers. The operation is done \emph{in-place} when \var{o1}
! supports it.
! \versionadded{2.2}
! \end{cfuncdesc}
!
!
! \begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceRemainder}{PyObject *o1,
! PyObject *o2}
Returns the remainder of dividing \var{o1} by \var{o2}, or \NULL{} on
failure. The operation is done \emph{in-place} when \var{o1} supports it.
! This is the equivalent of the Python statement \samp{\var{o1} \%= \var{o2}}.
\end{cfuncdesc}
! \begin{cfuncdesc}{PyObject*}{PyNumber_InPlacePower}{PyObject *o1,
! PyObject *o2, PyObject *o3}
! See the built-in function \function{pow()}.\bifuncindex{pow} Returns
! \NULL{} on failure. The operation is done \emph{in-place} when
! \var{o1} supports it. This is the equivalent of the Python statement
! \samp{\var{o1} **= \var{o2}} when o3 is \cdata{Py_None}, or an
! in-place variant of \samp{pow(\var{o1}, \var{o2}, \var{o3})}
! otherwise. If \var{o3} is to be ignored, pass \cdata{Py_None} in its
! place (passing \NULL{} for \var{o3} would cause an illegal memory
! access).
\end{cfuncdesc}
! \begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceLshift}{PyObject *o1,
! PyObject *o2}
! Returns the result of left shifting \var{o1} by \var{o2} on success,
! or \NULL{} on failure. The operation is done \emph{in-place} when
! \var{o1} supports it. This is the equivalent of the Python statement
! \samp{\var{o1} <\code{<=} \var{o2}}.
\end{cfuncdesc}
! \begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceRshift}{PyObject *o1,
! PyObject *o2}
! Returns the result of right shifting \var{o1} by \var{o2} on success,
! or \NULL{} on failure. The operation is done \emph{in-place} when
! \var{o1} supports it. This is the equivalent of the Python statement
! \samp{\var{o1} >\code{>=} \var{o2}}.
\end{cfuncdesc}
***************
*** 1903,1907 ****
Returns the ``bitwise and'' of \var{o1} and \var{o2} on success
and \NULL{} on failure. The operation is done \emph{in-place} when
! \var{o1} supports it. This is the equivalent of the Python expression
\samp{\var{o1} \&= \var{o2}}.
\end{cfuncdesc}
--- 1960,1964 ----
Returns the ``bitwise and'' of \var{o1} and \var{o2} on success
and \NULL{} on failure. The operation is done \emph{in-place} when
! \var{o1} supports it. This is the equivalent of the Python statement
\samp{\var{o1} \&= \var{o2}}.
\end{cfuncdesc}
***************
*** 1909,1923 ****
\begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceXor}{PyObject *o1, PyObject *o2}
! Returns the ``bitwise exclusive or'' of \var{o1} by \var{o2} on success, or
! \NULL{} on failure. The operation is done \emph{in-place} when \var{o1}
! supports it. This is the equivalent of the Python expression \samp{\var{o1}
! \textasciicircum= \var{o2}}.
\end{cfuncdesc}
\begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceOr}{PyObject *o1, PyObject *o2}
! Returns the ``bitwise or'' of \var{o1} and \var{o2} on success, or \NULL{}
! on failure. The operation is done \emph{in-place} when \var{o1} supports
! it. This is the equivalent of the Python expression \samp{\var{o1} |=
! \var{o2}}.
\end{cfuncdesc}
--- 1966,1980 ----
\begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceXor}{PyObject *o1, PyObject *o2}
! Returns the ``bitwise exclusive or'' of \var{o1} by \var{o2} on
! success, or \NULL{} on failure. The operation is done \emph{in-place}
! when \var{o1} supports it. This is the equivalent of the Python
! statement \samp{\var{o1} \textasciicircum= \var{o2}}.
\end{cfuncdesc}
\begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceOr}{PyObject *o1, PyObject *o2}
! Returns the ``bitwise or'' of \var{o1} and \var{o2} on success, or
! \NULL{} on failure. The operation is done \emph{in-place} when
! \var{o1} supports it. This is the equivalent of the Python statement
! \samp{\var{o1} |= \var{o2}}.
\end{cfuncdesc}
***************
*** 1986,1990 ****
\end{cfuncdesc}
! \begin{cfuncdesc}{PyObject*}{PySequence_InPlaceConcat}{PyObject *o1, PyObject *o2}
Return the concatenation of \var{o1} and \var{o2} on success, and \NULL{} on
failure. The operation is done \emph{in-place} when \var{o1} supports it.
--- 2043,2048 ----
\end{cfuncdesc}
! \begin{cfuncdesc}{PyObject*}{PySequence_InPlaceConcat}{PyObject *o1,
! PyObject *o2}
Return the concatenation of \var{o1} and \var{o2} on success, and \NULL{} on
failure. The operation is done \emph{in-place} when \var{o1} supports it.
***************
*** 4798,4801 ****
--- 4856,4891 ----
\cfunction{PyEval_SetProfile()}, except the tracing function does
receive line-number events.
+ \end{cfuncdesc}
+
+
+ \section{Advanced Debugger Support \label{advanced-debugging}}
+ \sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
+
+ These functions are only intended to be used by advanced debugging
+ tools.
+
+ \begin{cfuncdesc}{PyInterpreterState*}{PyInterpreterState_Head}{}
+ Return the interpreter state object at the head of the list of all
+ such objects.
+ \versionadded{2.2}
+ \end{cfuncdesc}
+
+ \begin{cfuncdesc}{PyInterpreterState*}{PyInterpreterState_Next}{PyInterpreterState *interp}
+ Return the next interpreter state object after \var{interp} from the
+ list of all such objects.
+ \versionadded{2.2}
+ \end{cfuncdesc}
+
+ \begin{cfuncdesc}{PyThreadState *}{PyInterpreterState_ThreadHead}{PyInterpreterState *interp}
+ Return the a pointer to the first \ctype{PyThreadState} object in the
+ list of threads associated with the interpreter \var{interp}.
+ \versionadded{2.2}
+ \end{cfuncdesc}
+
+ \begin{cfuncdesc}{PyThreadState*}{PyThreadState_Next}{PyThreadState *tstate}
+ Return the next thread state object after \var{tstate} from the list
+ of all such objects belonging to the same \ctype{PyInterpreterState}
+ object.
+ \versionadded{2.2}
\end{cfuncdesc}