[Python-checkins] CVS: python/dist/src/Doc/api api.tex,1.65,1.66
Fred L. Drake
python-dev@python.org
Fri, 16 Jun 2000 12:58:45 -0700
Update of /cvsroot/python/python/dist/src/Doc/api
In directory slayer.i.sourceforge.net:/tmp/cvs-serv30416
Modified Files:
api.tex
Log Message:
Documented PySequence_List() and PySequence_Tuple().
Added a bit more documentation in the chapter on building extension types,
including Py_FindMethod() documentation.
Several minor consistency nits were fixed.
Index: api.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/api/api.tex,v
retrieving revision 1.65
retrieving revision 1.66
diff -C2 -r1.65 -r1.66
*** api.tex 2000/04/10 18:50:14 1.65
--- api.tex 2000/06/16 19:58:42 1.66
***************
*** 211,215 ****
Nothing needs to be done for a borrowed reference.
! Conversely, when calling a function passes it a reference to an
object, there are two possibilities: the function \emph{steals} a
reference to the object, or it does not. Few functions steal
--- 211,215 ----
Nothing needs to be done for a borrowed reference.
! Conversely, when a calling function passes it a reference to an
object, there are two possibilities: the function \emph{steals} a
reference to the object, or it does not. Few functions steal
***************
*** 603,607 ****
value of \cfunction{PyRun_InteractiveLoop()}, otherwise return the
result of \cfunction{PyRun_SimpleFile()}. If \var{filename} is
! \NULL{}, this function uses \code{"???"} as the filename.
\end{cfuncdesc}
--- 603,607 ----
value of \cfunction{PyRun_InteractiveLoop()}, otherwise return the
result of \cfunction{PyRun_SimpleFile()}. If \var{filename} is
! \NULL{}, this function uses \code{'???'} as the filename.
\end{cfuncdesc}
***************
*** 1025,1029 ****
\cdata{Py_InteractiveFlag} is true, this function also returns true if
the \var{name} pointer is \NULL{} or if the name is equal to one of
! the strings \code{"<stdin>"} or \code{"???"}.
\end{cfuncdesc}
--- 1025,1029 ----
\cdata{Py_InteractiveFlag} is true, this function also returns true if
the \var{name} pointer is \NULL{} or if the name is equal to one of
! the strings \code{'<stdin>'} or \code{'???'}.
\end{cfuncdesc}
***************
*** 1664,1668 ****
--- 1664,1679 ----
\end{cfuncdesc}
+ \begin{cfuncdesc}{PyObject*}{PySequence_List}{PyObject *o}
+ Return a list object with the same contents as the arbitrary sequence
+ \var{o}. The returned list is guaranteed to be new.
+ \end{cfuncdesc}
+
+ \begin{cfuncdesc}{PyObject*}{PySequence_Tuple}{PyObject *o}
+ Return a tuple object with the same contents as the arbitrary sequence
+ \var{o}. If \var{o} is a tuple, a new reference will be returned,
+ otherwise a tuple will be constructed with the appropriate contents.
+ \end{cfuncdesc}
+
\section{Mapping Protocol \label{mapping}}
***************
*** 2232,2236 ****
Unicode data in \var{s}.
! If \var{byteorder} is not 0, output is written according to the
following byte order:
--- 2243,2247 ----
Unicode data in \var{s}.
! If \var{byteorder} is not \code{0}, output is written according to the
following byte order:
***************
*** 2241,2245 ****
\end{verbatim}
! If byteorder is 0, the output string will always start with the
Unicode BOM mark (U+FEFF). In the other two modes, no BOM mark is
prepended.
--- 2252,2256 ----
\end{verbatim}
! If byteorder is \code{0}, the output string will always start with the
Unicode BOM mark (U+FEFF). In the other two modes, no BOM mark is
prepended.
***************
*** 2253,2257 ****
\begin{cfuncdesc}{PyObject*}{PyUnicode_AsUTF16String}{PyObject *unicode}
-
Returns a Python string using the UTF-16 encoding in native byte
order. The string always starts with a BOM mark. Error handling is
--- 2264,2267 ----
***************
*** 3603,3607 ****
used by \cfunction{Py_GetPath()}\ttindex{Py_GetPath()} and some other
functions below to find the Python run-time libraries relative to the
! interpreter executable. The default value is \code{"python"}. The
argument should point to a zero-terminated character string in static
storage whose contents will not change for the duration of the
--- 3613,3617 ----
used by \cfunction{Py_GetPath()}\ttindex{Py_GetPath()} and some other
functions below to find the Python run-time libraries relative to the
! interpreter executable. The default value is \code{'python'}. The
argument should point to a zero-terminated character string in static
storage whose contents will not change for the duration of the
***************
*** 3621,3629 ****
is derived through a number of complicated rules from the program name
set with \cfunction{Py_SetProgramName()} and some environment variables;
! for example, if the program name is \code{"/usr/local/bin/python"},
! the prefix is \code{"/usr/local"}. The returned string points into
static storage; the caller should not modify its value. This
corresponds to the \makevar{prefix} variable in the top-level
! \file{Makefile} and the \programopt{-}\programopt{-prefix} argument to the
\program{configure} script at build time. The value is available to
Python code as \code{sys.prefix}. It is only useful on \UNIX{}. See
--- 3631,3639 ----
is derived through a number of complicated rules from the program name
set with \cfunction{Py_SetProgramName()} and some environment variables;
! for example, if the program name is \code{'/usr/local/bin/python'},
! the prefix is \code{'/usr/local'}. The returned string points into
static storage; the caller should not modify its value. This
corresponds to the \makevar{prefix} variable in the top-level
! \file{Makefile} and the \longprogramopt{prefix} argument to the
\program{configure} script at build time. The value is available to
Python code as \code{sys.prefix}. It is only useful on \UNIX{}. See
***************
*** 3636,3644 ****
program name set with \cfunction{Py_SetProgramName()} and some environment
variables; for example, if the program name is
! \code{"/usr/local/bin/python"}, the exec-prefix is
! \code{"/usr/local"}. The returned string points into static storage;
the caller should not modify its value. This corresponds to the
\makevar{exec_prefix} variable in the top-level \file{Makefile} and the
! \programopt{-}\programopt{-exec_prefix} argument to the
\program{configure} script at build time. The value is available to
Python code as \code{sys.exec_prefix}. It is only useful on \UNIX{}.
--- 3646,3654 ----
program name set with \cfunction{Py_SetProgramName()} and some environment
variables; for example, if the program name is
! \code{'/usr/local/bin/python'}, the exec-prefix is
! \code{'/usr/local'}. The returned string points into static storage;
the caller should not modify its value. This corresponds to the
\makevar{exec_prefix} variable in the top-level \file{Makefile} and the
! \longprogramopt{exec-prefix} argument to the
\program{configure} script at build time. The value is available to
Python code as \code{sys.exec_prefix}. It is only useful on \UNIX{}.
***************
*** 3648,3653 ****
installed in a different directory tree. In a typical installation,
platform dependent files may be installed in the
! \code{"/usr/local/plat"} subtree while platform independent may be
! installed in \code{"/usr/local"}.
Generally speaking, a platform is a combination of hardware and
--- 3658,3663 ----
installed in a different directory tree. In a typical installation,
platform dependent files may be installed in the
! \file{/usr/local/plat} subtree while platform independent may be
! installed in \file{/usr/local}.
Generally speaking, a platform is a combination of hardware and
***************
*** 3664,3669 ****
System administrators will know how to configure the \program{mount} or
! \program{automount} programs to share \code{"/usr/local"} between platforms
! while having \code{"/usr/local/plat"} be a different filesystem for each
platform.
\end{cfuncdesc}
--- 3674,3679 ----
System administrators will know how to configure the \program{mount} or
! \program{automount} programs to share \file{/usr/local} between platforms
! while having \file{/usr/local/plat} be a different filesystem for each
platform.
\end{cfuncdesc}
***************
*** 3718,3723 ****
converted to lower case, followed by the major revision number; e.g.,
for Solaris 2.x, which is also known as SunOS 5.x, the value is
! \code{"sunos5"}. On Macintosh, it is \code{"mac"}. On Windows, it
! is \code{"win"}. The returned string points into static storage;
the caller should not modify its value. The value is available to
Python code as \code{sys.platform}.
--- 3728,3733 ----
converted to lower case, followed by the major revision number; e.g.,
for Solaris 2.x, which is also known as SunOS 5.x, the value is
! \code{'sunos5'}. On Macintosh, it is \code{'mac'}. On Windows, it
! is \code{'win'}. The returned string points into static storage;
the caller should not modify its value. The value is available to
Python code as \code{sys.platform}.
***************
*** 3729,3733 ****
for example
! \code{"Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam"}
The returned string points into static storage; the caller should not
--- 3739,3743 ----
for example
! \code{'Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam'}
The returned string points into static storage; the caller should not
***************
*** 4376,4379 ****
--- 4386,4413 ----
destructor, printfunc, getattrfunc, getattrofunc, setattrfunc,
setattrofunc, cmpfunc, reprfunc, hashfunc
+
+ \begin{ctypedesc}{PyCFunction}
+ Type of the functions used to implement most Python callables in C.
+ \end{ctypedesc}
+
+ \begin{ctypedesc}{PyMethodDef}
+ Structure used to describe a method of an extension type. This
+ structure has four fields:
+
+ \begin{tableiii}{l|l|l}{member}{Field}{C Type}{Meaning}
+ \lineiii{ml_name}{char *}{name of the method}
+ \lineiii{ml_meth}{PyCFunction}{pointer to the C implementation}
+ \lineiii{ml_flags}{int}{flag bits indicating how the call should be
+ constructed}
+ \lineiii{ml_doc}{char *}{points to the contents of the docstring}
+ \end{tableiii}
+ \end{ctypedesc}
+
+ \begin{cfuncdesc}{PyObject*}{Py_FindMethod}{PyMethodDef[] table,
+ PyObject *ob, char *name}
+ Return a bound method object for an extension type implemented in C.
+ This function also handles the special attribute \member{__methods__},
+ returning a list of all the method names defined in \var{table}.
+ \end{cfuncdesc}