mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-09-27 02:39:58 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 13

Markup consistency & nits.

Browse source 
Fix typo in a C code example:  KeyError is spelled PyExc_KeyError in C; the
"K" is upper case!

Some index entries.

On function signatures, always use parameter names.  Make return types match
what's in the header files.  When the return type is a pointer, always omit
the space between te type name and the "*"; leaving it in results in

	type * func(..)

and having two spaces there just looks terrible.
This commit is contained in:
Fred Drake 1998-04-02 06:47:24 +00:00
parent e9625e86b8
commit c6fa34e4d0
2 changed files with 342 additions and 372 deletions
Download patch file Download diff file Expand all files Collapse all files

279
Doc/api.tex
View file

@ -55,7 +55,7 @@ Python in other applications since its early existence, the process of
embedding Python is less straightforward that writing an extension.
Python 1.5 introduces a number of new API functions as well as some
changes to the build process that make embedding much simpler.
This manual describes the \version\ state of affair.
This manual describes the \version\ state of affairs.
% XXX Eventually, take the historical notes out
Many API functions are useful independent of whether you're embedding
@ -200,6 +200,7 @@ the moment; a better way to code this is shown below anyway):
\begin{verbatim}
PyObject *t;
t = PyTuple_New(3);
PyTuple_SetItem(t, 0, PyInt_FromLong(1L));
PyTuple_SetItem(t, 1, PyInt_FromLong(2L));
@ -220,6 +221,7 @@ difference between the two (the extra \cfunction{Py_DECREF()} calls):
\begin{verbatim}
PyObject *l, *x;
l = PyList_New(3);
x = PyInt_FromLong(1L);
PySequence_SetItem(l, 0, x); Py_DECREF(x);
@ -239,6 +241,7 @@ also takes care of the error checking):
\begin{verbatim}
PyObject *t, *l;
t = Py_BuildValue("(iis)", 1, 2, "three");
l = Py_BuildValue("[iis]", 1, 2, "three");
\end{verbatim}
@ -256,6 +259,7 @@ item:
int set_all(PyObject *target, PyObject *item)
{
int i, n;
n = PyObject_Length(target);
if (n < 0)
return -1;
@ -299,6 +303,7 @@ long sum_list(PyObject *list)
int i, n;
long total = 0;
PyObject *item;
n = PyList_Size(list);
if (n < 0)
return -1; /* Not a list */
@ -364,7 +369,7 @@ ambiguous return value, and require explicit testing for errors with
Exception state is maintained in per-thread storage (this is
equivalent to using global storage in an unthreaded application). A
thread can be on one of two states: an exception has occurred, or not.
thread can be in one of two states: an exception has occurred, or not.
The function \cfunction{PyErr_Occurred()} can be used to check for
this: it returns a borrowed reference to the exception type object
when an exception has occurred, and \NULL{} otherwise. There are a
@ -384,7 +389,7 @@ exception state only exists while an exception is being passed on
between \C{} functions until it reaches the Python interpreter, which
takes care of transferring it to \code{sys.exc_type} and friends.
(Note that starting with Python 1.5, the preferred, thread-safe way to
Note that starting with Python 1.5, the preferred, thread-safe way to
access the exception state from Python code is to call the function
\function{sys.exc_info()}, which returns the per-thread exception state
for Python code. Also, the semantics of both ways to access the
@ -394,7 +399,7 @@ preserve the exception state of its caller. This prevents common bugs
in exception handling code caused by an innocent-looking function
overwriting the exception being handled; it also reduces the often
unwanted lifetime extension for objects that are referenced by the
stack frames in the traceback.)
stack frames in the traceback.
As a general principle, a function that calls another function to
perform some task should check whether the called function raised an
@ -431,8 +436,8 @@ int incr_item(PyObject *dict, PyObject *key)
item = PyObject_GetItem(dict, key);
if (item == NULL) {
/* Handle keyError only: */
if (!PyErr_ExceptionMatches(PyExc_keyError)) goto error;
/* Handle KeyError only: */
if (!PyErr_ExceptionMatches(PyExc_KeyError)) goto error;
/* Clear the error and use zero: */
PyErr_Clear();
@ -489,7 +494,8 @@ This initializes the table of loaded modules, and creates the
fundamental modules \module{__builtin__}\refbimodindex{__builtin__},
\module{__main__}\refbimodindex{__main__} and
\module{sys}\refbimodindex{sys}. It also initializes the module
search path (\code{sys.path}).
search path (\code{sys.path}).%
\indexiii{module}{search}{path}
\cfunction{Py_Initialize()} does not set the ``script argument list''
(\code{sys.argv}). If this variable is needed by Python code that
@ -506,21 +512,21 @@ interpreter executable. In particular, it looks for a directory named
\file{lib/python\version} (replacing \file{\version} with the current
interpreter version) relative to the parent directory where the
executable named \file{python} is found on the shell command search
path (the environment variable \code{\$PATH}).
path (the environment variable \envvar{PATH}).
For instance, if the Python executable is found in
\file{/usr/local/bin/python}, it will assume that the libraries are in
\file{/usr/local/lib/python\version}. (In fact, this particular path
is also the ``fallback'' location, used when no executable file named
\file{python} is found along \code{\$PATH}.) The user can override
this behavior by setting the environment variable \code{\$PYTHONHOME},
\file{python} is found along \envvar{PATH}.) The user can override
this behavior by setting the environment variable \envvar{PYTHONHOME},
or insert additional directories in front of the standard path by
setting \code{\$PYTHONPATH}.
setting \envvar{PYTHONPATH}.
The embedding application can steer the search by calling
\code{Py_SetProgramName(\var{file})} \emph{before} calling
\cfunction{Py_Initialize()}. Note that \code{\$PYTHONHOME} still
overrides this and \code{\$PYTHONPATH} is still inserted in front of
\cfunction{Py_Initialize()}. Note that \envvar{PYTHONHOME} still
overrides this and \envvar{PYTHONPATH} is still inserted in front of
the standard path. An application that requires total control has to
provide its own implementation of \cfunction{Py_GetPath()},
\cfunction{Py_GetPrefix()}, \cfunction{Py_GetExecPrefix()},
@ -544,34 +550,41 @@ The functions in this chapter will let you execute Python source code
given in a file or a buffer, but they will not let you interact in a
more detailed way with the interpreter.
\begin{cfuncdesc}{int}{PyRun_AnyFile}{FILE *, char *}
\begin{cfuncdesc}{int}{PyRun_AnyFile}{FILE *fp, char *filename}
\end{cfuncdesc}
\begin{cfuncdesc}{int}{PyRun_SimpleString}{char *}
\begin{cfuncdesc}{int}{PyRun_SimpleString}{char *command}
\end{cfuncdesc}
\begin{cfuncdesc}{int}{PyRun_SimpleFile}{FILE *, char *}
\begin{cfuncdesc}{int}{PyRun_SimpleFile}{FILE *fp, char *filename}
\end{cfuncdesc}
\begin{cfuncdesc}{int}{PyRun_InteractiveOne}{FILE *, char *}
\begin{cfuncdesc}{int}{PyRun_InteractiveOne}{FILE *fp, char *filename}
\end{cfuncdesc}
\begin{cfuncdesc}{int}{PyRun_InteractiveLoop}{FILE *, char *}
\begin{cfuncdesc}{int}{PyRun_InteractiveLoop}{FILE *fp, char *filename}
\end{cfuncdesc}
\begin{cfuncdesc}{struct _node *}{PyParser_SimpleParseString}{char *, int}
\begin{cfuncdesc}{struct _node*}{PyParser_SimpleParseString}{char *str,
int start}
\end{cfuncdesc}
\begin{cfuncdesc}{struct _node *}{PyParser_SimpleParseFile}{FILE *, char *, int}
\begin{cfuncdesc}{struct _node*}{PyParser_SimpleParseFile}{FILE *fp,
char *filename, int start}
\end{cfuncdesc}
\begin{cfuncdesc}{PyObject *}{PyRun_String}{char *, int, PyObject *, PyObject *}
\begin{cfuncdesc}{PyObject*}{PyRun_String}{char *str, int start,
PyObject *globals,
PyObject *locals}
\end{cfuncdesc}
\begin{cfuncdesc}{PyObject *}{PyRun_File}{FILE *, char *, int, PyObject *, PyObject *}
\begin{cfuncdesc}{PyObject*}{PyRun_File}{FILE *fp, char *filename,
int start, PyObject *globals,
PyObject *locals}
\end{cfuncdesc}
\begin{cfuncdesc}{PyObject *}{Py_CompileString}{char *, char *, int}
\begin{cfuncdesc}{PyObject*}{Py_CompileString}{char *str, char *filename,
int start}
\end{cfuncdesc}
@ -582,7 +595,7 @@ The macros in this section are used for managing reference counts
of Python objects.
\begin{cfuncdesc}{void}{Py_INCREF}{PyObject *o}
Increment the reference count for object \code{o}. The object must
Increment the reference count for object \var{o}. The object must
not be \NULL{}; if you aren't sure that it isn't \NULL{}, use
\cfunction{Py_XINCREF()}.
\end{cfuncdesc}
@ -798,7 +811,8 @@ the effect of a \constant{SIGINT} signal arriving --- the next time
\end{cfuncdesc}
\begin{cfuncdesc}{PyObject*}{PyErr_NewException}{char *name,
PyObject *base, PyObject *dict}
PyObject *base,
PyObject *dict}
This utility function creates and returns a new exception object. The
\var{name} argument must be the name of the new exception, a \C{} string
of the form \code{module.class}. The \var{base} and \var{dict}
@ -925,7 +939,7 @@ effect when \var{name} in fact specifies a subpackage instead of a
submodule: the submodules specified in the package's \code{__all__}
variable are loaded.) Return a new reference to the imported module,
or \NULL{} with an exception set on failure (the module may still
be created in this case).
be created in this case --- examine \code{sys.modules} to find out).
\end{cfuncdesc}
\begin{cfuncdesc}{PyObject*}{PyImport_ImportModuleEx}{char *name, PyObject *globals, PyObject *locals, PyObject *fromlist}
@ -1003,11 +1017,11 @@ Empty the module table. For internal use only.
Finalize the import mechanism. For internal use only.
\end{cfuncdesc}
\begin{cfuncdesc}{extern PyObject *}{_PyImport_FindExtension}{char *, char *}
\begin{cfuncdesc}{PyObject*}{_PyImport_FindExtension}{char *, char *}
For internal use only.
\end{cfuncdesc}
\begin{cfuncdesc}{extern PyObject *}{_PyImport_FixupExtension}{char *, char *}
\begin{cfuncdesc}{PyObject*}{_PyImport_FixupExtension}{char *, char *}
For internal use only.
\end{cfuncdesc}
@ -1022,8 +1036,10 @@ already imported.)
\begin{ctypedesc}{struct _frozen}
This is the structure type definition for frozen module descriptors,
as generated by the \code{freeze} utility (see \file{Tools/freeze/} in
the Python source distribution). Its definition is:
as generated by the \program{freeze}\index{freeze utility} utility
(see \file{Tools/freeze/} in the Python source distribution). Its
definition is:
\begin{verbatim}
struct _frozen {
char *name;
@ -1037,7 +1053,7 @@ struct _frozen {
This pointer is initialized to point to an array of \code{struct
_frozen} records, terminated by one whose members are all \NULL{}
or zero. When a frozen module is imported, it is searched in this
table. Third party code could play tricks with this to provide a
table. Third-party code could play tricks with this to provide a
dynamically created collection of frozen modules.
\end{cvardesc}
@ -1708,51 +1724,45 @@ This instance of \code{PyTypeObject} represents the Python string type.
\end{cfuncdesc}
\begin{cfuncdesc}{PyObject *}{PyString_FromStringAndSize}{const char *, int}
\begin{cfuncdesc}{PyObject*}{PyString_FromStringAndSize}{const char *v,
int len}
\end{cfuncdesc}
\begin{cfuncdesc}{PyObject*}{PyString_FromString}{const char *v}
\end{cfuncdesc}
\begin{cfuncdesc}{int}{PyString_Size}{PyObject *string}
\end{cfuncdesc}
\begin{cfuncdesc}{char*}{PyString_AsString}{PyObject *string}
\end{cfuncdesc}
\begin{cfuncdesc}{void}{PyString_Concat}{PyObject **string,
PyObject *newpart}
\end{cfuncdesc}
\begin{cfuncdesc}{void}{PyString_ConcatAndDel}{PyObject **string,
PyObject *newpart}
\end{cfuncdesc}
\begin{cfuncdesc}{int}{_PyString_Resize}{PyObject **string, int newsize}
\end{cfuncdesc}
\begin{cfuncdesc}{PyObject*}{PyString_Format}{PyObject *format,
PyObject *args}
\end{cfuncdesc}
\begin{cfuncdesc}{void}{PyString_InternInPlace}{PyObject **string}
\end{cfuncdesc}
\begin{cfuncdesc}{PyObject*}{PyString_InternFromString}{const char *v}
\end{cfuncdesc}
\begin{cfuncdesc}{char*}{PyString_AS_STRING}{PyObject *string}
\end{cfuncdesc}
\begin{cfuncdesc}{PyObject *}{PyString_FromString}{const char *}
\end{cfuncdesc}
\begin{cfuncdesc}{int}{PyString_Size}{PyObject *}
\end{cfuncdesc}
\begin{cfuncdesc}{char *}{PyString_AsString}{PyObject *}
\end{cfuncdesc}
\begin{cfuncdesc}{void}{PyString_Concat}{PyObject **, PyObject *}
\end{cfuncdesc}
\begin{cfuncdesc}{void}{PyString_ConcatAndDel}{PyObject **, PyObject *}
\end{cfuncdesc}
\begin{cfuncdesc}{int}{_PyString_Resize}{PyObject **, int}
\end{cfuncdesc}
\begin{cfuncdesc}{PyObject *}{PyString_Format}{PyObject *, PyObject *}
\end{cfuncdesc}
\begin{cfuncdesc}{void}{PyString_InternInPlace}{PyObject **}
\end{cfuncdesc}
\begin{cfuncdesc}{PyObject *}{PyString_InternFromString}{const char *}
\end{cfuncdesc}
\begin{cfuncdesc}{char *}{PyString_AS_STRING}{PyStringObject *}
\end{cfuncdesc}
\begin{cfuncdesc}{int}{PyString_GET_SIZE}{PyStringObject *}
\begin{cfuncdesc}{int}{PyString_GET_SIZE}{PyObject *string}
\end{cfuncdesc}
@ -1772,7 +1782,7 @@ This instance of \code{PyTypeObject} represents the Python tuple type.
Return true if the argument is a tuple object.
\end{cfuncdesc}
\begin{cfuncdesc}{PyTupleObject *}{PyTuple_New}{int s}
\begin{cfuncdesc}{PyObject*}{PyTuple_New}{int s}
Return a new tuple object of size \var{s}.
\end{cfuncdesc}
@ -1791,7 +1801,7 @@ raises an \exception{IndexError} exception.
Does the same, but does no checking of its arguments.
\end{cfuncdesc}
\begin{cfuncdesc}{PyTupleObject *}{PyTuple_GetSlice}{PyTupleObject *p,
\begin{cfuncdesc}{PyObject*}{PyTuple_GetSlice}{PyTupleObject *p,
int low,
int high}
Takes a slice of the tuple pointed to by \var{p} from
@ -1813,7 +1823,7 @@ Does the same, but does no error checking, and
should \emph{only} be used to fill in brand new tuples.
\end{cfuncdesc}
\begin{cfuncdesc}{PyTupleObject *}{_PyTuple_Resize}{PyTupleObject *p,
\begin{cfuncdesc}{int}{_PyTuple_Resize}{PyTupleObject *p,
int new,
int last_is_sticky}
Can be used to resize a tuple. Because tuples are
@ -1842,55 +1852,47 @@ Returns true if its argument is a \code{PyListObject}.
\end{cfuncdesc}
\begin{cfuncdesc}{PyObject*}{PyList_New}{int size}
\end{cfuncdesc}
\begin{cfuncdesc}{int}{PyList_Size}{PyObject *}
\begin{cfuncdesc}{int}{PyList_Size}{PyObject *list}
\end{cfuncdesc}
\begin{cfuncdesc}{PyObject *}{PyList_GetItem}{PyObject *, int}
\begin{cfuncdesc}{PyObject*}{PyList_GetItem}{PyObject *list, int index}
\end{cfuncdesc}
\begin{cfuncdesc}{int}{PyList_SetItem}{PyObject *, int, PyObject *}
\begin{cfuncdesc}{int}{PyList_SetItem}{PyObject *list, int index,
PyObject *item}
\end{cfuncdesc}
\begin{cfuncdesc}{int}{PyList_Insert}{PyObject *, int, PyObject *}
\begin{cfuncdesc}{int}{PyList_Insert}{PyObject *list, int index,
PyObject *index}
\end{cfuncdesc}
\begin{cfuncdesc}{int}{PyList_Append}{PyObject *, PyObject *}
\begin{cfuncdesc}{int}{PyList_Append}{PyObject *list, PyObject *item}
\end{cfuncdesc}
\begin{cfuncdesc}{PyObject *}{PyList_GetSlice}{PyObject *, int, int}
\begin{cfuncdesc}{PyObject*}{PyList_GetSlice}{PyObject *list,
int low, int high}
\end{cfuncdesc}
\begin{cfuncdesc}{int}{PyList_SetSlice}{PyObject *, int, int, PyObject *}
\begin{cfuncdesc}{int}{PyList_SetSlice}{PyObject *list,
int low, int high,
PyObject *itemlist}
\end{cfuncdesc}
\begin{cfuncdesc}{int}{PyList_Sort}{PyObject *}
\begin{cfuncdesc}{int}{PyList_Sort}{PyObject *list}
\end{cfuncdesc}
\begin{cfuncdesc}{int}{PyList_Reverse}{PyObject *}
\begin{cfuncdesc}{int}{PyList_Reverse}{PyObject *list}
\end{cfuncdesc}
\begin{cfuncdesc}{PyObject *}{PyList_AsTuple}{PyObject *}
\begin{cfuncdesc}{PyObject*}{PyList_AsTuple}{PyObject *list}
\end{cfuncdesc}
\begin{cfuncdesc}{PyObject*}{PyList_GET_ITEM}{PyObject *list, int i}
\end{cfuncdesc}
\begin{cfuncdesc}{int}{PyList_GET_SIZE}{PyObject *list}
\end{cfuncdesc}
@ -1912,7 +1914,7 @@ This instance of \code{PyTypeObject} represents the Python dictionary type.
Returns true if its argument is a \code{PyDictObject}.
\end{cfuncdesc}
\begin{cfuncdesc}{PyDictObject *}{PyDict_New}{}
\begin{cfuncdesc}{PyObject*}{PyDict_New}{}
Returns a new empty dictionary.
\end{cfuncdesc}
@ -1956,19 +1958,19 @@ Does the same, but \var{key} is specified as a
\code{char *}, rather than a \code{PyObject *}.
\end{cfuncdesc}
\begin{cfuncdesc}{PyListObject *}{PyDict_Items}{PyDictObject *p}
\begin{cfuncdesc}{PyObject*}{PyDict_Items}{PyDictObject *p}
Returns a \code{PyListObject} containing all the items
from the dictionary, as in the mapping method \method{items()} (see
the \emph{Python Library Reference}).
\end{cfuncdesc}
\begin{cfuncdesc}{PyListObject *}{PyDict_Keys}{PyDictObject *p}
\begin{cfuncdesc}{PyObject*}{PyDict_Keys}{PyDictObject *p}
Returns a \code{PyListObject} containing all the keys
from the dictionary, as in the mapping method \method{keys()} (see the
\emph{Python Library Reference}).
\end{cfuncdesc}
\begin{cfuncdesc}{PyListObject *}{PyDict_Values}{PyDictObject *p}
\begin{cfuncdesc}{PyObject*}{PyDict_Values}{PyDictObject *p}
Returns a \code{PyListObject} containing all the values
from the dictionary \var{p}, as in the mapping method
\method{values()} (see the \emph{Python Library Reference}).
@ -2005,7 +2007,7 @@ integer type.
\end{cfuncdesc}
\begin{cfuncdesc}{PyIntObject *}{PyInt_FromLong}{long ival}
\begin{cfuncdesc}{PyObject*}{PyInt_FromLong}{long ival}
Creates a new integer object with a value of \var{ival}.
The current implementation keeps an array of integer objects for all
@ -2048,32 +2050,26 @@ integer type.
Returns true if its argument is a \code{PyLongObject}.
\end{cfuncdesc}
\begin{cfuncdesc}{PyObject *}{PyLong_FromLong}{long}
\begin{cfuncdesc}{PyObject*}{PyLong_FromLong}{long v}
\end{cfuncdesc}
\begin{cfuncdesc}{PyObject *}{PyLong_FromUnsignedLong}{unsigned long}
\begin{cfuncdesc}{PyObject*}{PyLong_FromUnsignedLong}{unsigned long v}
\end{cfuncdesc}
\begin{cfuncdesc}{PyObject *}{PyLong_FromDouble}{double}
\begin{cfuncdesc}{PyObject*}{PyLong_FromDouble}{double v}
\end{cfuncdesc}
\begin{cfuncdesc}{long}{PyLong_AsLong}{PyObject *}
\begin{cfuncdesc}{long}{PyLong_AsLong}{PyObject *pylong}
\end{cfuncdesc}
\begin{cfuncdesc}{unsigned long}{PyLong_AsUnsignedLong}{PyObject }
\begin{cfuncdesc}{unsigned long}{PyLong_AsUnsignedLong}{PyObject *pylong}
\end{cfuncdesc}
\begin{cfuncdesc}{double}{PyLong_AsDouble}{PyObject *}
\begin{cfuncdesc}{double}{PyLong_AsDouble}{PyObject *pylong}
\end{cfuncdesc}
\begin{cfuncdesc}{PyObject *}{PyLong_FromString}{char *, char **, int}
\begin{cfuncdesc}{PyObject*}{PyLong_FromString}{char *str, char **pend,
int base}
\end{cfuncdesc}
@ -2094,16 +2090,13 @@ point type.
Returns true if its argument is a \code{PyFloatObject}.
\end{cfuncdesc}
\begin{cfuncdesc}{PyObject *}{PyFloat_FromDouble}{double}
\begin{cfuncdesc}{PyObject*}{PyFloat_FromDouble}{double v}
\end{cfuncdesc}
\begin{cfuncdesc}{double}{PyFloat_AsDouble}{PyObject *}
\begin{cfuncdesc}{double}{PyFloat_AsDouble}{PyObject *pyfloat}
\end{cfuncdesc}
\begin{cfuncdesc}{double}{PyFloat_AS_DOUBLE}{PyFloatObject *}
\begin{cfuncdesc}{double}{PyFloat_AS_DOUBLE}{PyObject *pyfloat}
\end{cfuncdesc}
@ -2137,48 +2130,38 @@ number type.
Returns true if its argument is a \code{PyComplexObject}.
\end{cfuncdesc}
\begin{cfuncdesc}{Py_complex}{_Py_c_sum}{Py_complex, Py_complex}
\begin{cfuncdesc}{Py_complex}{_Py_c_sum}{Py_complex left, Py_complex right}
\end{cfuncdesc}
\begin{cfuncdesc}{Py_complex}{_Py_c_diff}{Py_complex, Py_complex}
\begin{cfuncdesc}{Py_complex}{_Py_c_diff}{Py_complex left, Py_complex right}
\end{cfuncdesc}
\begin{cfuncdesc}{Py_complex}{_Py_c_neg}{Py_complex}
\begin{cfuncdesc}{Py_complex}{_Py_c_neg}{Py_complex complex}
\end{cfuncdesc}
\begin{cfuncdesc}{Py_complex}{_Py_c_prod}{Py_complex, Py_complex}
\begin{cfuncdesc}{Py_complex}{_Py_c_prod}{Py_complex left, Py_complex right}
\end{cfuncdesc}
\begin{cfuncdesc}{Py_complex}{_Py_c_quot}{Py_complex, Py_complex}
\begin{cfuncdesc}{Py_complex}{_Py_c_quot}{Py_complex dividend,
Py_complex divisor}
\end{cfuncdesc}
\begin{cfuncdesc}{Py_complex}{_Py_c_pow}{Py_complex, Py_complex}
\begin{cfuncdesc}{Py_complex}{_Py_c_pow}{Py_complex num, Py_complex exp}
\end{cfuncdesc}
\begin{cfuncdesc}{PyObject *}{PyComplex_FromCComplex}{Py_complex}
\begin{cfuncdesc}{PyObject*}{PyComplex_FromCComplex}{Py_complex v}
\end{cfuncdesc}
\begin{cfuncdesc}{PyObject*}{PyComplex_FromDoubles}{double real, double imag}
\end{cfuncdesc}
\begin{cfuncdesc}{double}{PyComplex_RealAsDouble}{PyObject *op}
\end{cfuncdesc}
\begin{cfuncdesc}{double}{PyComplex_ImagAsDouble}{PyObject *op}
\end{cfuncdesc}
\begin{cfuncdesc}{Py_complex}{PyComplex_AsCComplex}{PyObject *op}
\end{cfuncdesc}
@ -2217,11 +2200,11 @@ closed.
Returns the file object associated with \var{p} as a \code{FILE *}.
\end{cfuncdesc}
\begin{cfuncdesc}{PyStringObject *}{PyFile_GetLine}{PyObject *p, int n}
\begin{cfuncdesc}{PyObject*}{PyFile_GetLine}{PyObject *p, int n}
undocumented as yet
\end{cfuncdesc}
\begin{cfuncdesc}{PyStringObject *}{PyFile_Name}{PyObject *p}
\begin{cfuncdesc}{PyObject*}{PyFile_Name}{PyObject *p}
Returns the name of the file specified by \var{p} as a
\code{PyStringObject}.
\end{cfuncdesc}
@ -2233,17 +2216,19 @@ only be called immediately after file object creation.
\begin{cfuncdesc}{int}{PyFile_SoftSpace}{PyFileObject *p, int newflag}
Sets the \code{softspace} attribute of \var{p} to \var{newflag}.
Returns the previosu value. This function clears any errors, and will
Returns the previous value. This function clears any errors, and will
return \code{0} as the previous value if the attribute either does not
exist or if there were errors in retrieving it. There is no way to
detect errors from this function, but doing so should not be needed.
\end{cfuncdesc}
\begin{cfuncdesc}{int}{PyFile_WriteObject}{PyObject *obj, PyFileObject *p}
\begin{cfuncdesc}{int}{PyFile_WriteObject}{PyObject *obj, PyFileObject *p,
int flags}
Writes object \var{obj} to file object \var{p}.
\end{cfuncdesc}
\begin{cfuncdesc}{int}{PyFile_WriteString}{char *s, PyFileObject *p}
\begin{cfuncdesc}{int}{PyFile_WriteString}{char *s, PyFileObject *p,
int flags}
Writes string \var{s} to file object \var{p}.
\end{cfuncdesc}

279
Doc/api/api.tex
View file

@ -55,7 +55,7 @@ Python in other applications since its early existence, the process of
embedding Python is less straightforward that writing an extension.
Python 1.5 introduces a number of new API functions as well as some
changes to the build process that make embedding much simpler.
This manual describes the \version\ state of affair.
This manual describes the \version\ state of affairs.
% XXX Eventually, take the historical notes out
Many API functions are useful independent of whether you're embedding
@ -200,6 +200,7 @@ the moment; a better way to code this is shown below anyway):
\begin{verbatim}
PyObject *t;
t = PyTuple_New(3);
PyTuple_SetItem(t, 0, PyInt_FromLong(1L));
PyTuple_SetItem(t, 1, PyInt_FromLong(2L));
@ -220,6 +221,7 @@ difference between the two (the extra \cfunction{Py_DECREF()} calls):
\begin{verbatim}
PyObject *l, *x;
l = PyList_New(3);
x = PyInt_FromLong(1L);
PySequence_SetItem(l, 0, x); Py_DECREF(x);
@ -239,6 +241,7 @@ also takes care of the error checking):
\begin{verbatim}
PyObject *t, *l;
t = Py_BuildValue("(iis)", 1, 2, "three");
l = Py_BuildValue("[iis]", 1, 2, "three");
\end{verbatim}
@ -256,6 +259,7 @@ item:
int set_all(PyObject *target, PyObject *item)
{
int i, n;
n = PyObject_Length(target);
if (n < 0)
return -1;
@ -299,6 +303,7 @@ long sum_list(PyObject *list)
int i, n;
long total = 0;
PyObject *item;
n = PyList_Size(list);
if (n < 0)
return -1; /* Not a list */
@ -364,7 +369,7 @@ ambiguous return value, and require explicit testing for errors with
Exception state is maintained in per-thread storage (this is
equivalent to using global storage in an unthreaded application). A
thread can be on one of two states: an exception has occurred, or not.
thread can be in one of two states: an exception has occurred, or not.
The function \cfunction{PyErr_Occurred()} can be used to check for
this: it returns a borrowed reference to the exception type object
when an exception has occurred, and \NULL{} otherwise. There are a
@ -384,7 +389,7 @@ exception state only exists while an exception is being passed on
between \C{} functions until it reaches the Python interpreter, which
takes care of transferring it to \code{sys.exc_type} and friends.
(Note that starting with Python 1.5, the preferred, thread-safe way to
Note that starting with Python 1.5, the preferred, thread-safe way to
access the exception state from Python code is to call the function
\function{sys.exc_info()}, which returns the per-thread exception state
for Python code. Also, the semantics of both ways to access the
@ -394,7 +399,7 @@ preserve the exception state of its caller. This prevents common bugs
in exception handling code caused by an innocent-looking function
overwriting the exception being handled; it also reduces the often
unwanted lifetime extension for objects that are referenced by the
stack frames in the traceback.)
stack frames in the traceback.
As a general principle, a function that calls another function to
perform some task should check whether the called function raised an
@ -431,8 +436,8 @@ int incr_item(PyObject *dict, PyObject *key)
item = PyObject_GetItem(dict, key);
if (item == NULL) {
/* Handle keyError only: */
if (!PyErr_ExceptionMatches(PyExc_keyError)) goto error;
/* Handle KeyError only: */
if (!PyErr_ExceptionMatches(PyExc_KeyError)) goto error;
/* Clear the error and use zero: */
PyErr_Clear();
@ -489,7 +494,8 @@ This initializes the table of loaded modules, and creates the
fundamental modules \module{__builtin__}\refbimodindex{__builtin__},
\module{__main__}\refbimodindex{__main__} and
\module{sys}\refbimodindex{sys}. It also initializes the module
search path (\code{sys.path}).
search path (\code{sys.path}).%
\indexiii{module}{search}{path}
\cfunction{Py_Initialize()} does not set the ``script argument list''
(\code{sys.argv}). If this variable is needed by Python code that
@ -506,21 +512,21 @@ interpreter executable. In particular, it looks for a directory named
\file{lib/python\version} (replacing \file{\version} with the current
interpreter version) relative to the parent directory where the
executable named \file{python} is found on the shell command search
path (the environment variable \code{\$PATH}).
path (the environment variable \envvar{PATH}).
For instance, if the Python executable is found in
\file{/usr/local/bin/python}, it will assume that the libraries are in
\file{/usr/local/lib/python\version}. (In fact, this particular path
is also the ``fallback'' location, used when no executable file named
\file{python} is found along \code{\$PATH}.) The user can override
this behavior by setting the environment variable \code{\$PYTHONHOME},
\file{python} is found along \envvar{PATH}.) The user can override
this behavior by setting the environment variable \envvar{PYTHONHOME},
or insert additional directories in front of the standard path by
setting \code{\$PYTHONPATH}.
setting \envvar{PYTHONPATH}.
The embedding application can steer the search by calling
\code{Py_SetProgramName(\var{file})} \emph{before} calling
\cfunction{Py_Initialize()}. Note that \code{\$PYTHONHOME} still
overrides this and \code{\$PYTHONPATH} is still inserted in front of
\cfunction{Py_Initialize()}. Note that \envvar{PYTHONHOME} still
overrides this and \envvar{PYTHONPATH} is still inserted in front of
the standard path. An application that requires total control has to
provide its own implementation of \cfunction{Py_GetPath()},
\cfunction{Py_GetPrefix()}, \cfunction{Py_GetExecPrefix()},
@ -544,34 +550,41 @@ The functions in this chapter will let you execute Python source code
given in a file or a buffer, but they will not let you interact in a
more detailed way with the interpreter.
\begin{cfuncdesc}{int}{PyRun_AnyFile}{FILE *, char *}
\begin{cfuncdesc}{int}{PyRun_AnyFile}{FILE *fp, char *filename}
\end{cfuncdesc}
\begin{cfuncdesc}{int}{PyRun_SimpleString}{char *}
\begin{cfuncdesc}{int}{PyRun_SimpleString}{char *command}
\end{cfuncdesc}
\begin{cfuncdesc}{int}{PyRun_SimpleFile}{FILE *, char *}
\begin{cfuncdesc}{int}{PyRun_SimpleFile}{FILE *fp, char *filename}
\end{cfuncdesc}
\begin{cfuncdesc}{int}{PyRun_InteractiveOne}{FILE *, char *}
\begin{cfuncdesc}{int}{PyRun_InteractiveOne}{FILE *fp, char *filename}
\end{cfuncdesc}
\begin{cfuncdesc}{int}{PyRun_InteractiveLoop}{FILE *, char *}
\begin{cfuncdesc}{int}{PyRun_InteractiveLoop}{FILE *fp, char *filename}
\end{cfuncdesc}
\begin{cfuncdesc}{struct _node *}{PyParser_SimpleParseString}{char *, int}
\begin{cfuncdesc}{struct _node*}{PyParser_SimpleParseString}{char *str,
int start}
\end{cfuncdesc}
\begin{cfuncdesc}{struct _node *}{PyParser_SimpleParseFile}{FILE *, char *, int}
\begin{cfuncdesc}{struct _node*}{PyParser_SimpleParseFile}{FILE *fp,
char *filename, int start}
\end{cfuncdesc}
\begin{cfuncdesc}{PyObject *}{PyRun_String}{char *, int, PyObject *, PyObject *}
\begin{cfuncdesc}{PyObject*}{PyRun_String}{char *str, int start,
PyObject *globals,
PyObject *locals}
\end{cfuncdesc}
\begin{cfuncdesc}{PyObject *}{PyRun_File}{FILE *, char *, int, PyObject *, PyObject *}
\begin{cfuncdesc}{PyObject*}{PyRun_File}{FILE *fp, char *filename,
int start, PyObject *globals,
PyObject *locals}
\end{cfuncdesc}
\begin{cfuncdesc}{PyObject *}{Py_CompileString}{char *, char *, int}
\begin{cfuncdesc}{PyObject*}{Py_CompileString}{char *str, char *filename,
int start}
\end{cfuncdesc}
@ -582,7 +595,7 @@ The macros in this section are used for managing reference counts
of Python objects.
\begin{cfuncdesc}{void}{Py_INCREF}{PyObject *o}
Increment the reference count for object \code{o}. The object must
Increment the reference count for object \var{o}. The object must
not be \NULL{}; if you aren't sure that it isn't \NULL{}, use
\cfunction{Py_XINCREF()}.
\end{cfuncdesc}
@ -798,7 +811,8 @@ the effect of a \constant{SIGINT} signal arriving --- the next time
\end{cfuncdesc}
\begin{cfuncdesc}{PyObject*}{PyErr_NewException}{char *name,
PyObject *base, PyObject *dict}
PyObject *base,
PyObject *dict}
This utility function creates and returns a new exception object. The
\var{name} argument must be the name of the new exception, a \C{} string
of the form \code{module.class}. The \var{base} and \var{dict}
@ -925,7 +939,7 @@ effect when \var{name} in fact specifies a subpackage instead of a
submodule: the submodules specified in the package's \code{__all__}
variable are loaded.) Return a new reference to the imported module,
or \NULL{} with an exception set on failure (the module may still
be created in this case).
be created in this case --- examine \code{sys.modules} to find out).
\end{cfuncdesc}
\begin{cfuncdesc}{PyObject*}{PyImport_ImportModuleEx}{char *name, PyObject *globals, PyObject *locals, PyObject *fromlist}
@ -1003,11 +1017,11 @@ Empty the module table. For internal use only.
Finalize the import mechanism. For internal use only.
\end{cfuncdesc}
\begin{cfuncdesc}{extern PyObject *}{_PyImport_FindExtension}{char *, char *}
\begin{cfuncdesc}{PyObject*}{_PyImport_FindExtension}{char *, char *}
For internal use only.
\end{cfuncdesc}
\begin{cfuncdesc}{extern PyObject *}{_PyImport_FixupExtension}{char *, char *}
\begin{cfuncdesc}{PyObject*}{_PyImport_FixupExtension}{char *, char *}
For internal use only.
\end{cfuncdesc}
@ -1022,8 +1036,10 @@ already imported.)
\begin{ctypedesc}{struct _frozen}
This is the structure type definition for frozen module descriptors,
as generated by the \code{freeze} utility (see \file{Tools/freeze/} in
the Python source distribution). Its definition is:
as generated by the \program{freeze}\index{freeze utility} utility
(see \file{Tools/freeze/} in the Python source distribution). Its
definition is:
\begin{verbatim}
struct _frozen {
char *name;
@ -1037,7 +1053,7 @@ struct _frozen {
This pointer is initialized to point to an array of \code{struct
_frozen} records, terminated by one whose members are all \NULL{}
or zero. When a frozen module is imported, it is searched in this
table. Third party code could play tricks with this to provide a
table. Third-party code could play tricks with this to provide a
dynamically created collection of frozen modules.
\end{cvardesc}
@ -1708,51 +1724,45 @@ This instance of \code{PyTypeObject} represents the Python string type.
\end{cfuncdesc}
\begin{cfuncdesc}{PyObject *}{PyString_FromStringAndSize}{const char *, int}
\begin{cfuncdesc}{PyObject*}{PyString_FromStringAndSize}{const char *v,
int len}
\end{cfuncdesc}
\begin{cfuncdesc}{PyObject*}{PyString_FromString}{const char *v}
\end{cfuncdesc}
\begin{cfuncdesc}{int}{PyString_Size}{PyObject *string}
\end{cfuncdesc}
\begin{cfuncdesc}{char*}{PyString_AsString}{PyObject *string}
\end{cfuncdesc}
\begin{cfuncdesc}{void}{PyString_Concat}{PyObject **string,
PyObject *newpart}
\end{cfuncdesc}
\begin{cfuncdesc}{void}{PyString_ConcatAndDel}{PyObject **string,
PyObject *newpart}
\end{cfuncdesc}
\begin{cfuncdesc}{int}{_PyString_Resize}{PyObject **string, int newsize}
\end{cfuncdesc}
\begin{cfuncdesc}{PyObject*}{PyString_Format}{PyObject *format,
PyObject *args}
\end{cfuncdesc}
\begin{cfuncdesc}{void}{PyString_InternInPlace}{PyObject **string}
\end{cfuncdesc}
\begin{cfuncdesc}{PyObject*}{PyString_InternFromString}{const char *v}
\end{cfuncdesc}
\begin{cfuncdesc}{char*}{PyString_AS_STRING}{PyObject *string}
\end{cfuncdesc}
\begin{cfuncdesc}{PyObject *}{PyString_FromString}{const char *}
\end{cfuncdesc}
\begin{cfuncdesc}{int}{PyString_Size}{PyObject *}
\end{cfuncdesc}
\begin{cfuncdesc}{char *}{PyString_AsString}{PyObject *}
\end{cfuncdesc}
\begin{cfuncdesc}{void}{PyString_Concat}{PyObject **, PyObject *}
\end{cfuncdesc}
\begin{cfuncdesc}{void}{PyString_ConcatAndDel}{PyObject **, PyObject *}
\end{cfuncdesc}
\begin{cfuncdesc}{int}{_PyString_Resize}{PyObject **, int}
\end{cfuncdesc}
\begin{cfuncdesc}{PyObject *}{PyString_Format}{PyObject *, PyObject *}
\end{cfuncdesc}
\begin{cfuncdesc}{void}{PyString_InternInPlace}{PyObject **}
\end{cfuncdesc}
\begin{cfuncdesc}{PyObject *}{PyString_InternFromString}{const char *}
\end{cfuncdesc}
\begin{cfuncdesc}{char *}{PyString_AS_STRING}{PyStringObject *}
\end{cfuncdesc}
\begin{cfuncdesc}{int}{PyString_GET_SIZE}{PyStringObject *}
\begin{cfuncdesc}{int}{PyString_GET_SIZE}{PyObject *string}
\end{cfuncdesc}
@ -1772,7 +1782,7 @@ This instance of \code{PyTypeObject} represents the Python tuple type.
Return true if the argument is a tuple object.
\end{cfuncdesc}
\begin{cfuncdesc}{PyTupleObject *}{PyTuple_New}{int s}
\begin{cfuncdesc}{PyObject*}{PyTuple_New}{int s}
Return a new tuple object of size \var{s}.
\end{cfuncdesc}
@ -1791,7 +1801,7 @@ raises an \exception{IndexError} exception.
Does the same, but does no checking of its arguments.
\end{cfuncdesc}
\begin{cfuncdesc}{PyTupleObject *}{PyTuple_GetSlice}{PyTupleObject *p,
\begin{cfuncdesc}{PyObject*}{PyTuple_GetSlice}{PyTupleObject *p,
int low,
int high}
Takes a slice of the tuple pointed to by \var{p} from
@ -1813,7 +1823,7 @@ Does the same, but does no error checking, and
should \emph{only} be used to fill in brand new tuples.
\end{cfuncdesc}
\begin{cfuncdesc}{PyTupleObject *}{_PyTuple_Resize}{PyTupleObject *p,
\begin{cfuncdesc}{int}{_PyTuple_Resize}{PyTupleObject *p,
int new,
int last_is_sticky}
Can be used to resize a tuple. Because tuples are
@ -1842,55 +1852,47 @@ Returns true if its argument is a \code{PyListObject}.
\end{cfuncdesc}
\begin{cfuncdesc}{PyObject*}{PyList_New}{int size}
\end{cfuncdesc}
\begin{cfuncdesc}{int}{PyList_Size}{PyObject *}
\begin{cfuncdesc}{int}{PyList_Size}{PyObject *list}
\end{cfuncdesc}
\begin{cfuncdesc}{PyObject *}{PyList_GetItem}{PyObject *, int}
\begin{cfuncdesc}{PyObject*}{PyList_GetItem}{PyObject *list, int index}
\end{cfuncdesc}
\begin{cfuncdesc}{int}{PyList_SetItem}{PyObject *, int, PyObject *}
\begin{cfuncdesc}{int}{PyList_SetItem}{PyObject *list, int index,
PyObject *item}
\end{cfuncdesc}
\begin{cfuncdesc}{int}{PyList_Insert}{PyObject *, int, PyObject *}
\begin{cfuncdesc}{int}{PyList_Insert}{PyObject *list, int index,
PyObject *index}
\end{cfuncdesc}
\begin{cfuncdesc}{int}{PyList_Append}{PyObject *, PyObject *}
\begin{cfuncdesc}{int}{PyList_Append}{PyObject *list, PyObject *item}
\end{cfuncdesc}
\begin{cfuncdesc}{PyObject *}{PyList_GetSlice}{PyObject *, int, int}
\begin{cfuncdesc}{PyObject*}{PyList_GetSlice}{PyObject *list,
int low, int high}
\end{cfuncdesc}
\begin{cfuncdesc}{int}{PyList_SetSlice}{PyObject *, int, int, PyObject *}
\begin{cfuncdesc}{int}{PyList_SetSlice}{PyObject *list,
int low, int high,
PyObject *itemlist}
\end{cfuncdesc}
\begin{cfuncdesc}{int}{PyList_Sort}{PyObject *}
\begin{cfuncdesc}{int}{PyList_Sort}{PyObject *list}
\end{cfuncdesc}
\begin{cfuncdesc}{int}{PyList_Reverse}{PyObject *}
\begin{cfuncdesc}{int}{PyList_Reverse}{PyObject *list}
\end{cfuncdesc}
\begin{cfuncdesc}{PyObject *}{PyList_AsTuple}{PyObject *}
\begin{cfuncdesc}{PyObject*}{PyList_AsTuple}{PyObject *list}
\end{cfuncdesc}
\begin{cfuncdesc}{PyObject*}{PyList_GET_ITEM}{PyObject *list, int i}
\end{cfuncdesc}
\begin{cfuncdesc}{int}{PyList_GET_SIZE}{PyObject *list}
\end{cfuncdesc}
@ -1912,7 +1914,7 @@ This instance of \code{PyTypeObject} represents the Python dictionary type.
Returns true if its argument is a \code{PyDictObject}.
\end{cfuncdesc}
\begin{cfuncdesc}{PyDictObject *}{PyDict_New}{}
\begin{cfuncdesc}{PyObject*}{PyDict_New}{}
Returns a new empty dictionary.
\end{cfuncdesc}
@ -1956,19 +1958,19 @@ Does the same, but \var{key} is specified as a
\code{char *}, rather than a \code{PyObject *}.
\end{cfuncdesc}
\begin{cfuncdesc}{PyListObject *}{PyDict_Items}{PyDictObject *p}
\begin{cfuncdesc}{PyObject*}{PyDict_Items}{PyDictObject *p}
Returns a \code{PyListObject} containing all the items
from the dictionary, as in the mapping method \method{items()} (see
the \emph{Python Library Reference}).
\end{cfuncdesc}
\begin{cfuncdesc}{PyListObject *}{PyDict_Keys}{PyDictObject *p}
\begin{cfuncdesc}{PyObject*}{PyDict_Keys}{PyDictObject *p}
Returns a \code{PyListObject} containing all the keys
from the dictionary, as in the mapping method \method{keys()} (see the
\emph{Python Library Reference}).
\end{cfuncdesc}
\begin{cfuncdesc}{PyListObject *}{PyDict_Values}{PyDictObject *p}
\begin{cfuncdesc}{PyObject*}{PyDict_Values}{PyDictObject *p}
Returns a \code{PyListObject} containing all the values
from the dictionary \var{p}, as in the mapping method
\method{values()} (see the \emph{Python Library Reference}).
@ -2005,7 +2007,7 @@ integer type.
\end{cfuncdesc}
\begin{cfuncdesc}{PyIntObject *}{PyInt_FromLong}{long ival}
\begin{cfuncdesc}{PyObject*}{PyInt_FromLong}{long ival}
Creates a new integer object with a value of \var{ival}.
The current implementation keeps an array of integer objects for all
@ -2048,32 +2050,26 @@ integer type.
Returns true if its argument is a \code{PyLongObject}.
\end{cfuncdesc}
\begin{cfuncdesc}{PyObject *}{PyLong_FromLong}{long}
\begin{cfuncdesc}{PyObject*}{PyLong_FromLong}{long v}
\end{cfuncdesc}
\begin{cfuncdesc}{PyObject *}{PyLong_FromUnsignedLong}{unsigned long}
\begin{cfuncdesc}{PyObject*}{PyLong_FromUnsignedLong}{unsigned long v}
\end{cfuncdesc}
\begin{cfuncdesc}{PyObject *}{PyLong_FromDouble}{double}
\begin{cfuncdesc}{PyObject*}{PyLong_FromDouble}{double v}
\end{cfuncdesc}
\begin{cfuncdesc}{long}{PyLong_AsLong}{PyObject *}
\begin{cfuncdesc}{long}{PyLong_AsLong}{PyObject *pylong}
\end{cfuncdesc}
\begin{cfuncdesc}{unsigned long}{PyLong_AsUnsignedLong}{PyObject }
\begin{cfuncdesc}{unsigned long}{PyLong_AsUnsignedLong}{PyObject *pylong}
\end{cfuncdesc}
\begin{cfuncdesc}{double}{PyLong_AsDouble}{PyObject *}
\begin{cfuncdesc}{double}{PyLong_AsDouble}{PyObject *pylong}
\end{cfuncdesc}
\begin{cfuncdesc}{PyObject *}{PyLong_FromString}{char *, char **, int}
\begin{cfuncdesc}{PyObject*}{PyLong_FromString}{char *str, char **pend,
int base}
\end{cfuncdesc}
@ -2094,16 +2090,13 @@ point type.
Returns true if its argument is a \code{PyFloatObject}.
\end{cfuncdesc}
\begin{cfuncdesc}{PyObject *}{PyFloat_FromDouble}{double}
\begin{cfuncdesc}{PyObject*}{PyFloat_FromDouble}{double v}
\end{cfuncdesc}
\begin{cfuncdesc}{double}{PyFloat_AsDouble}{PyObject *}
\begin{cfuncdesc}{double}{PyFloat_AsDouble}{PyObject *pyfloat}
\end{cfuncdesc}
\begin{cfuncdesc}{double}{PyFloat_AS_DOUBLE}{PyFloatObject *}
\begin{cfuncdesc}{double}{PyFloat_AS_DOUBLE}{PyObject *pyfloat}
\end{cfuncdesc}
@ -2137,48 +2130,38 @@ number type.
Returns true if its argument is a \code{PyComplexObject}.
\end{cfuncdesc}
\begin{cfuncdesc}{Py_complex}{_Py_c_sum}{Py_complex, Py_complex}
\begin{cfuncdesc}{Py_complex}{_Py_c_sum}{Py_complex left, Py_complex right}
\end{cfuncdesc}
\begin{cfuncdesc}{Py_complex}{_Py_c_diff}{Py_complex, Py_complex}
\begin{cfuncdesc}{Py_complex}{_Py_c_diff}{Py_complex left, Py_complex right}
\end{cfuncdesc}
\begin{cfuncdesc}{Py_complex}{_Py_c_neg}{Py_complex}
\begin{cfuncdesc}{Py_complex}{_Py_c_neg}{Py_complex complex}
\end{cfuncdesc}
\begin{cfuncdesc}{Py_complex}{_Py_c_prod}{Py_complex, Py_complex}
\begin{cfuncdesc}{Py_complex}{_Py_c_prod}{Py_complex left, Py_complex right}
\end{cfuncdesc}
\begin{cfuncdesc}{Py_complex}{_Py_c_quot}{Py_complex, Py_complex}
\begin{cfuncdesc}{Py_complex}{_Py_c_quot}{Py_complex dividend,
Py_complex divisor}
\end{cfuncdesc}
\begin{cfuncdesc}{Py_complex}{_Py_c_pow}{Py_complex, Py_complex}
\begin{cfuncdesc}{Py_complex}{_Py_c_pow}{Py_complex num, Py_complex exp}
\end{cfuncdesc}
\begin{cfuncdesc}{PyObject *}{PyComplex_FromCComplex}{Py_complex}
\begin{cfuncdesc}{PyObject*}{PyComplex_FromCComplex}{Py_complex v}
\end{cfuncdesc}
\begin{cfuncdesc}{PyObject*}{PyComplex_FromDoubles}{double real, double imag}
\end{cfuncdesc}
\begin{cfuncdesc}{double}{PyComplex_RealAsDouble}{PyObject *op}
\end{cfuncdesc}
\begin{cfuncdesc}{double}{PyComplex_ImagAsDouble}{PyObject *op}
\end{cfuncdesc}
\begin{cfuncdesc}{Py_complex}{PyComplex_AsCComplex}{PyObject *op}
\end{cfuncdesc}
@ -2217,11 +2200,11 @@ closed.
Returns the file object associated with \var{p} as a \code{FILE *}.
\end{cfuncdesc}
\begin{cfuncdesc}{PyStringObject *}{PyFile_GetLine}{PyObject *p, int n}
\begin{cfuncdesc}{PyObject*}{PyFile_GetLine}{PyObject *p, int n}
undocumented as yet
\end{cfuncdesc}
\begin{cfuncdesc}{PyStringObject *}{PyFile_Name}{PyObject *p}
\begin{cfuncdesc}{PyObject*}{PyFile_Name}{PyObject *p}
Returns the name of the file specified by \var{p} as a
\code{PyStringObject}.
\end{cfuncdesc}
@ -2233,17 +2216,19 @@ only be called immediately after file object creation.
\begin{cfuncdesc}{int}{PyFile_SoftSpace}{PyFileObject *p, int newflag}
Sets the \code{softspace} attribute of \var{p} to \var{newflag}.
Returns the previosu value. This function clears any errors, and will
Returns the previous value. This function clears any errors, and will
return \code{0} as the previous value if the attribute either does not
exist or if there were errors in retrieving it. There is no way to
detect errors from this function, but doing so should not be needed.
\end{cfuncdesc}
\begin{cfuncdesc}{int}{PyFile_WriteObject}{PyObject *obj, PyFileObject *p}
\begin{cfuncdesc}{int}{PyFile_WriteObject}{PyObject *obj, PyFileObject *p,
int flags}
Writes object \var{obj} to file object \var{p}.
\end{cfuncdesc}
\begin{cfuncdesc}{int}{PyFile_WriteString}{char *s, PyFileObject *p}
\begin{cfuncdesc}{int}{PyFile_WriteString}{char *s, PyFileObject *p,
int flags}
Writes string \var{s} to file object \var{p}.
\end{cfuncdesc}