diff options
| -rw-r--r-- | Doc/api.tex | 1241 | ||||
| -rw-r--r-- | Doc/api/api.tex | 1241 |
2 files changed, 1234 insertions, 1248 deletions
diff --git a/Doc/api.tex b/Doc/api.tex index 780034a..b13a097 100644 --- a/Doc/api.tex +++ b/Doc/api.tex @@ -523,34 +523,40 @@ initialized state. More information about these functions is given in a later chapter. -\chapter{Basic Utilities} +\chapter{The Very High Level Layer} -XXX These utilities should be moved to some other section... +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}{void}{Py_FatalError}{char *message} -Print a fatal error message and kill the process. No cleanup is -performed. This function should only be invoked when a condition is -detected that would make it dangerous to continue using the Python -interpreter; e.g., when the object administration appears to be -corrupted. On \UNIX{}, the standard \C{} library function \code{abort()} is -called which will attempt to produce a \file{core} file. +\begin{cfuncdesc}{int}{PyRun_AnyFile}{FILE *, char *} \end{cfuncdesc} -\begin{cfuncdesc}{void}{Py_Exit}{int status} -Exit the current process. This calls \code{Py_Finalize()} and then -calls the standard \C{} library function \code{exit(\var{status})}. +\begin{cfuncdesc}{int}{PyRun_SimpleString}{char *} \end{cfuncdesc} -\begin{cfuncdesc}{int}{Py_AtExit}{void (*func) ()} -Register a cleanup function to be called by \cfunction{Py_Finalize()}. -The cleanup function will be called with no arguments and should -return no value. At most 32 cleanup functions can be registered. -When the registration is successful, \cfunction{Py_AtExit()} returns -\code{0}; on failure, it returns \code{-1}. The cleanup function -registered last is called first. Each cleanup function will be called -at most once. Since Python's internal finallization will have -completed before the cleanup function, no Python APIs should be called -by \var{func}. +\begin{cfuncdesc}{int}{PyRun_SimpleFile}{FILE *, char *} +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyRun_InteractiveOne}{FILE *, char *} +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyRun_InteractiveLoop}{FILE *, char *} +\end{cfuncdesc} + +\begin{cfuncdesc}{struct _node *}{PyParser_SimpleParseString}{char *, int} +\end{cfuncdesc} + +\begin{cfuncdesc}{struct _node *}{PyParser_SimpleParseFile}{FILE *, char *, int} +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject *}{PyRun_String}{char *, int, PyObject *, PyObject *} +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject *}{PyRun_File}{FILE *, char *, int, PyObject *, PyObject *} +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject *}{Py_CompileString}{char *, char *, int} \end{cfuncdesc} @@ -849,7 +855,36 @@ the standard \C{} library function \code{time()}. \end{cfuncdesc} -\section{Importing modules} +\section{Process Control} + +\begin{cfuncdesc}{void}{Py_FatalError}{char *message} +Print a fatal error message and kill the process. No cleanup is +performed. This function should only be invoked when a condition is +detected that would make it dangerous to continue using the Python +interpreter; e.g., when the object administration appears to be +corrupted. On \UNIX{}, the standard \C{} library function \code{abort()} is +called which will attempt to produce a \file{core} file. +\end{cfuncdesc} + +\begin{cfuncdesc}{void}{Py_Exit}{int status} +Exit the current process. This calls \code{Py_Finalize()} and then +calls the standard \C{} library function \code{exit(\var{status})}. +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{Py_AtExit}{void (*func) ()} +Register a cleanup function to be called by \cfunction{Py_Finalize()}. +The cleanup function will be called with no arguments and should +return no value. At most 32 cleanup functions can be registered. +When the registration is successful, \cfunction{Py_AtExit()} returns +\code{0}; on failure, it returns \code{-1}. The cleanup function +registered last is called first. Each cleanup function will be called +at most once. Since Python's internal finallization will have +completed before the cleanup function, no Python APIs should be called +by \var{func}. +\end{cfuncdesc} + + +\section{Importing Modules} \begin{cfuncdesc}{PyObject *}{PyImport_ImportModule}{char *name} This is a simplified interface to \code{PyImport_ImportModuleEx} @@ -978,48 +1013,6 @@ dynamically created collection of frozen modules. \end{cvardesc} -\chapter{Debugging} - -XXX Explain Py_DEBUG, Py_TRACE_REFS, Py_REF_DEBUG. - - -\chapter{The Very High Level Layer} - -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 *} -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyRun_SimpleString}{char *} -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyRun_SimpleFile}{FILE *, char *} -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyRun_InteractiveOne}{FILE *, char *} -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyRun_InteractiveLoop}{FILE *, char *} -\end{cfuncdesc} - -\begin{cfuncdesc}{struct _node *}{PyParser_SimpleParseString}{char *, int} -\end{cfuncdesc} - -\begin{cfuncdesc}{struct _node *}{PyParser_SimpleParseFile}{FILE *, char *, int} -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject *}{PyRun_String}{char *, int, PyObject *, PyObject *} -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject *}{PyRun_File}{FILE *, char *, int, PyObject *, PyObject *} -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject *}{Py_CompileString}{char *, char *, int} -\end{cfuncdesc} - - \chapter{Abstract Objects Layer} The functions in this chapter interact with Python objects regardless @@ -1609,23 +1602,569 @@ types. Passing them an object of the wrong type is not a good idea; if you receive an object from a Python program and you are not sure that it has the right type, you must perform a type check first; e.g. to check that an object is a dictionary, use -\code{PyDict_Check()}. +\cfunction{PyDict_Check()}. The chapter is structured like the +``family tree'' of Python object types. -\chapter{Defining New Object Types} +\section{Fundamental Objects} + +This section describes Python type objects and the singleton object +\code{None}. + + +\subsection{Type Objects} + +\begin{ctypedesc}{PyTypeObject} + +\end{ctypedesc} + +\begin{cvardesc}{PyObject *}{PyType_Type} + +\end{cvardesc} + + +\subsection{The None Object} + +\begin{cvardesc}{PyObject *}{Py_None} +XXX macro +\end{cvardesc} + + +\section{Sequence Objects} + +Generic operations on sequence objects were discussed in the previous +chapter; this section deals with the specific kinds of sequence +objects that are intrinsic to the Python language. + + +\subsection{String Objects} + +\begin{ctypedesc}{PyStringObject} +This subtype of \code{PyObject} represents a Python string object. +\end{ctypedesc} + +\begin{cvardesc}{PyTypeObject}{PyString_Type} +This instance of \code{PyTypeObject} represents the Python string type. +\end{cvardesc} + +\begin{cfuncdesc}{int}{PyString_Check}{PyObject *o} -\begin{cfuncdesc}{PyObject *}{_PyObject_New}{PyTypeObject *type} \end{cfuncdesc} -\begin{cfuncdesc}{PyObject *}{_PyObject_NewVar}{PyTypeObject *type, int size} +\begin{cfuncdesc}{PyObject *}{PyString_FromStringAndSize}{const char *, int} + \end{cfuncdesc} -\begin{cfuncdesc}{TYPE}{_PyObject_NEW}{TYPE, PyTypeObject *} +\begin{cfuncdesc}{PyObject *}{PyString_FromString}{const char *} + \end{cfuncdesc} -\begin{cfuncdesc}{TYPE}{_PyObject_NEW_VAR}{TYPE, PyTypeObject *, int size} +\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 *} + +\end{cfuncdesc} + + +\subsection{Tuple Objects} + +\begin{ctypedesc}{PyTupleObject} +This subtype of \code{PyObject} represents a Python tuple object. +\end{ctypedesc} + +\begin{cvardesc}{PyTypeObject}{PyTuple_Type} +This instance of \code{PyTypeObject} represents the Python tuple type. +\end{cvardesc} + +\begin{cfuncdesc}{int}{PyTuple_Check}{PyObject *p} +Return true if the argument is a tuple object. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyTupleObject *}{PyTuple_New}{int s} +Return a new tuple object of size \code{s} +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyTuple_Size}{PyTupleObject *p} +akes a pointer to a tuple object, and returns the size +of that tuple. \end{cfuncdesc} +\begin{cfuncdesc}{PyObject *}{PyTuple_GetItem}{PyTupleObject *p, int pos} +returns the object at position \code{pos} in the tuple pointed +to by \code{p}. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject *}{PyTuple_GET_ITEM}{PyTupleObject *p, int pos} +does the same, but does no checking of it's +arguments. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyTupleObject *}{PyTuple_GetSlice}{PyTupleObject *p, + int low, + int high} +takes a slice of the tuple pointed to by \code{p} from +\code{low} to \code{high} and returns it as a new tuple. +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyTuple_SetItem}{PyTupleObject *p, + int pos, + PyObject *o} +inserts a reference to object \code{o} at position \code{pos} of +the tuple pointed to by \code{p}. It returns 0 on success. +\end{cfuncdesc} + +\begin{cfuncdesc}{void}{PyTuple_SET_ITEM}{PyTupleObject *p, + int pos, + PyObject *o} + +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, + int new, + int last_is_sticky} +can be used to resize a tuple. Because tuples are +\emph{supposed} to be immutable, this should only be used if there is only +one module referencing the object. Do \emph{not} use this if the tuple may +already be known to some other part of the code. \code{last_is_sticky} is +a flag - if set, the tuple will grow or shrink at the front, otherwise +it will grow or shrink at the end. Think of this as destroying the old +tuple and creating a new one, only more efficiently. +\end{cfuncdesc} + + +\subsection{List Objects} + +\begin{ctypedesc}{PyListObject} +This subtype of \code{PyObject} represents a Python list object. +\end{ctypedesc} + +\begin{cvardesc}{PyTypeObject}{PyList_Type} +This instance of \code{PyTypeObject} represents the Python list type. +\end{cvardesc} + +\begin{cfuncdesc}{int}{PyList_Check}{PyObject *p} +returns true if it's argument is a \code{PyListObject} +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject *}{PyList_New}{int size} + +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyList_Size}{PyObject *} + +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject *}{PyList_GetItem}{PyObject *, int} + +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyList_SetItem}{PyObject *, int, PyObject *} + +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyList_Insert}{PyObject *, int, PyObject *} + +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyList_Append}{PyObject *, PyObject *} + +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject *}{PyList_GetSlice}{PyObject *, int, int} + +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyList_SetSlice}{PyObject *, int, int, PyObject *} + +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyList_Sort}{PyObject *} + +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyList_Reverse}{PyObject *} + +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject *}{PyList_AsTuple}{PyObject *} + +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject *}{PyList_GET_ITEM}{PyObject *list, int i} + +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyList_GET_SIZE}{PyObject *list} + +\end{cfuncdesc} + + +\section{Mapping Objects} + +\subsection{Dictionary Objects} + +\begin{ctypedesc}{PyDictObject} +This subtype of \code{PyObject} represents a Python dictionary object. +\end{ctypedesc} + +\begin{cvardesc}{PyTypeObject}{PyDict_Type} +This instance of \code{PyTypeObject} represents the Python dictionary type. +\end{cvardesc} + +\begin{cfuncdesc}{int}{PyDict_Check}{PyObject *p} +returns true if it's argument is a PyDictObject +\end{cfuncdesc} + +\begin{cfuncdesc}{PyDictObject *}{PyDict_New}{} +returns a new empty dictionary. +\end{cfuncdesc} + +\begin{cfuncdesc}{void}{PyDict_Clear}{PyDictObject *p} +empties an existing dictionary and deletes it. +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyDict_SetItem}{PyDictObject *p, + PyObject *key, + PyObject *val} +inserts \code{value} into the dictionary with a key of +\code{key}. Both \code{key} and \code{value} should be PyObjects, and \code{key} should +be hashable. +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyDict_SetItemString}{PyDictObject *p, + char *key, + PyObject *val} +inserts \code{value} into the dictionary using \code{key} +as a key. \code{key} should be a char * +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyDict_DelItem}{PyDictObject *p, PyObject *key} +removes the entry in dictionary \code{p} with key \code{key}. +\code{key} is a PyObject. +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyDict_DelItemString}{PyDictObject *p, char *key} +removes the entry in dictionary \code{p} which has a key +specified by the \code{char *}\code{key}. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject *}{PyDict_GetItem}{PyDictObject *p, PyObject *key} +returns the object from dictionary \code{p} which has a key +\code{key}. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject *}{PyDict_GetItemString}{PyDictObject *p, char *key} +does the same, but \code{key} is specified as a +\code{char *}, rather than a \code{PyObject *}. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyListObject *}{PyDict_Items}{PyDictObject *p} +returns a PyListObject containing all the items +from the dictionary, as in the mapping method \code{items()} (see the Reference +Guide) +\end{cfuncdesc} + +\begin{cfuncdesc}{PyListObject *}{PyDict_Keys}{PyDictObject *p} +returns a PyListObject containing all the keys +from the dictionary, as in the mapping method \code{keys()} (see the Reference Guide) +\end{cfuncdesc} + +\begin{cfuncdesc}{PyListObject *}{PyDict_Values}{PyDictObject *p} +returns a PyListObject containing all the values +from the dictionary, as in the mapping method \code{values()} (see the Reference Guide) +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyDict_Size}{PyDictObject *p} +returns the number of items in the dictionary. +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyDict_Next}{PyDictObject *p, + int ppos, + PyObject **pkey, + PyObject **pvalue} + +\end{cfuncdesc} + + +\section{Numeric Objects} + +\subsection{Plain Integer Objects} + +\begin{ctypedesc}{PyIntObject} +This subtype of \code{PyObject} represents a Python integer object. +\end{ctypedesc} + +\begin{cvardesc}{PyTypeObject}{PyInt_Type} +This instance of \code{PyTypeObject} represents the Python plain +integer type. +\end{cvardesc} + +\begin{cfuncdesc}{int}{PyInt_Check}{PyObject *} + +\end{cfuncdesc} + +\begin{cfuncdesc}{PyIntObject *}{PyInt_FromLong}{long ival} +creates a new integer object with a value of \code{ival}. + +The current implementation keeps an array of integer objects for all +integers between -1 and 100, when you create an int in that range you +actually just get back a reference to the existing object. So it should +be possible to change the value of 1. I suspect the behaviour of python +in this case is undefined. :-) +\end{cfuncdesc} + +\begin{cfuncdesc}{long}{PyInt_AS_LONG}{PyIntObject *io} +returns the value of the object \code{io}. +\end{cfuncdesc} + +\begin{cfuncdesc}{long}{PyInt_AsLong}{PyObject *io} +will first attempt to cast the object to a PyIntObject, if +it is not already one, and the return it's value. +\end{cfuncdesc} + +\begin{cfuncdesc}{long}{PyInt_GetMax}{} +returns the systems idea of the largest int it can handle +(LONG_MAX, as defined in the system header files) +\end{cfuncdesc} + + +\subsection{Long Integer Objects} + +\begin{ctypedesc}{PyLongObject} +This subtype of \code{PyObject} represents a Python long integer object. +\end{ctypedesc} + +\begin{cvardesc}{PyTypeObject}{PyLong_Type} +This instance of \code{PyTypeObject} represents the Python long integer type. +\end{cvardesc} + +\begin{cfuncdesc}{int}{PyLong_Check}{PyObject *p} +returns true if it's argument is a \code{PyLongObject} +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject *}{PyLong_FromLong}{long} + +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject *}{PyLong_FromUnsignedLong}{unsigned long} + +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject *}{PyLong_FromDouble}{double} + +\end{cfuncdesc} + +\begin{cfuncdesc}{long}{PyLong_AsLong}{PyObject *} + +\end{cfuncdesc} + +\begin{cfuncdesc}{unsigned long}{PyLong_AsUnsignedLong}{PyObject } + +\end{cfuncdesc} + +\begin{cfuncdesc}{double}{PyLong_AsDouble}{PyObject *} + +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject *}{PyLong_FromString}{char *, char **, int} + +\end{cfuncdesc} + + +\subsection{Floating Point Objects} + +\begin{ctypedesc}{PyFloatObject} +This subtype of \code{PyObject} represents a Python floating point object. +\end{ctypedesc} + +\begin{cvardesc}{PyTypeObject}{PyFloat_Type} +This instance of \code{PyTypeObject} represents the Python floating +point type. +\end{cvardesc} + +\begin{cfuncdesc}{int}{PyFloat_Check}{PyObject *p} +returns true if it's argument is a \code{PyFloatObject} +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject *}{PyFloat_FromDouble}{double} + +\end{cfuncdesc} + +\begin{cfuncdesc}{double}{PyFloat_AsDouble}{PyObject *} + +\end{cfuncdesc} + +\begin{cfuncdesc}{double}{PyFloat_AS_DOUBLE}{PyFloatObject *} + +\end{cfuncdesc} + + +\subsection{Complex Number Objects} + +\begin{ctypedesc}{Py_complex} +typedef struct { + double real; + double imag; +} +\end{ctypedesc} + +\begin{ctypedesc}{PyComplexObject} +This subtype of \code{PyObject} represents a Python complex number object. +\end{ctypedesc} + +\begin{cvardesc}{PyTypeObject}{PyComplex_Type} +This instance of \code{PyTypeObject} represents the Python complex +number type. +\end{cvardesc} + +\begin{cfuncdesc}{int}{PyComplex_Check}{PyObject *p} +returns true if it's argument is a \code{PyComplexObject} +\end{cfuncdesc} + +\begin{cfuncdesc}{Py_complex}{_Py_c_sum}{Py_complex, Py_complex} + +\end{cfuncdesc} + +\begin{cfuncdesc}{Py_complex}{_Py_c_diff}{Py_complex, Py_complex} + +\end{cfuncdesc} + +\begin{cfuncdesc}{Py_complex}{_Py_c_neg}{Py_complex} + +\end{cfuncdesc} + +\begin{cfuncdesc}{Py_complex}{_Py_c_prod}{Py_complex, Py_complex} + +\end{cfuncdesc} + +\begin{cfuncdesc}{Py_complex}{_Py_c_quot}{Py_complex, Py_complex} + +\end{cfuncdesc} + +\begin{cfuncdesc}{Py_complex}{_Py_c_pow}{Py_complex, Py_complex} + +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject *}{PyComplex_FromCComplex}{Py_complex} + +\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} + + + +\section{Other Objects} + +\subsection{File Objects} + +\begin{ctypedesc}{PyFileObject} +This subtype of \code{PyObject} represents a Python file object. +\end{ctypedesc} + +\begin{cvardesc}{PyTypeObject}{PyFile_Type} +This instance of \code{PyTypeObject} represents the Python file type. +\end{cvardesc} + +\begin{cfuncdesc}{int}{PyFile_Check}{PyObject *p} +returns true if it's argument is a \code{PyFileObject} +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject *}{PyFile_FromString}{char *name, char *mode} +creates a new PyFileObject pointing to the file +specified in \code{name} with the mode specified in \code{mode} +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject *}{PyFile_FromFile}{FILE *fp, + char *name, char *mode, int (*close}) +creates a new PyFileObject from the already-open \code{fp}. +The function \code{close} will be called when the file should be closed. +\end{cfuncdesc} + +\begin{cfuncdesc}{FILE *}{PyFile_AsFile}{PyFileObject *p} +returns the file object associated with \code{p} as a \code{FILE *} +\end{cfuncdesc} + +\begin{cfuncdesc}{PyStringObject *}{PyFile_GetLine}{PyObject *p, int n} +undocumented as yet +\end{cfuncdesc} + +\begin{cfuncdesc}{PyStringObject *}{PyFile_Name}{PyObject *p} +returns the name of the file specified by \code{p} as a +PyStringObject +\end{cfuncdesc} + +\begin{cfuncdesc}{void}{PyFile_SetBufSize}{PyFileObject *p, int n} +on systems with \code{setvbuf} only +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyFile_SoftSpace}{PyFileObject *p, int newflag} +same as the file object method \code{softspace} +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyFile_WriteObject}{PyObject *obj, PyFileObject *p} +writes object \code{obj} to file object \code{p} +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyFile_WriteString}{char *s, PyFileObject *p} +writes string \code{s} to file object \code{p} +\end{cfuncdesc} + + +\subsection{CObjects} + +XXX + + \chapter{Initialization, Finalization, and Threads} \begin{cfuncdesc}{void}{Py_Initialize}{} @@ -2265,570 +2804,24 @@ _PyObject_New, _PyObject_NewVar PyObject_NEW, PyObject_NEW_VAR -\chapter{Specific Data Types} - -This chapter describes the functions that deal with specific types of -Python objects. It is structured like the ``family tree'' of Python -object types. - - -\section{Fundamental Objects} - -This section describes Python type objects and the singleton object -\code{None}. - - -\subsection{Type Objects} - -\begin{ctypedesc}{PyTypeObject} - -\end{ctypedesc} - -\begin{cvardesc}{PyObject *}{PyType_Type} - -\end{cvardesc} - - -\subsection{The None Object} - -\begin{cvardesc}{PyObject *}{Py_None} -XXX macro -\end{cvardesc} - - -\section{Sequence Objects} - -Generic operations on sequence objects were discussed in the previous -chapter; this section deals with the specific kinds of sequence -objects that are intrinsic to the Python language. - - -\subsection{String Objects} - -\begin{ctypedesc}{PyStringObject} -This subtype of \code{PyObject} represents a Python string object. -\end{ctypedesc} - -\begin{cvardesc}{PyTypeObject}{PyString_Type} -This instance of \code{PyTypeObject} represents the Python string type. -\end{cvardesc} - -\begin{cfuncdesc}{int}{PyString_Check}{PyObject *o} - -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject *}{PyString_FromStringAndSize}{const char *, int} - -\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 *} - -\end{cfuncdesc} - - -\subsection{Tuple Objects} - -\begin{ctypedesc}{PyTupleObject} -This subtype of \code{PyObject} represents a Python tuple object. -\end{ctypedesc} - -\begin{cvardesc}{PyTypeObject}{PyTuple_Type} -This instance of \code{PyTypeObject} represents the Python tuple type. -\end{cvardesc} - -\begin{cfuncdesc}{int}{PyTuple_Check}{PyObject *p} -Return true if the argument is a tuple object. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyTupleObject *}{PyTuple_New}{int s} -Return a new tuple object of size \code{s} -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyTuple_Size}{PyTupleObject *p} -akes a pointer to a tuple object, and returns the size -of that tuple. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject *}{PyTuple_GetItem}{PyTupleObject *p, int pos} -returns the object at position \code{pos} in the tuple pointed -to by \code{p}. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject *}{PyTuple_GET_ITEM}{PyTupleObject *p, int pos} -does the same, but does no checking of it's -arguments. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyTupleObject *}{PyTuple_GetSlice}{PyTupleObject *p, - int low, - int high} -takes a slice of the tuple pointed to by \code{p} from -\code{low} to \code{high} and returns it as a new tuple. -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyTuple_SetItem}{PyTupleObject *p, - int pos, - PyObject *o} -inserts a reference to object \code{o} at position \code{pos} of -the tuple pointed to by \code{p}. It returns 0 on success. -\end{cfuncdesc} - -\begin{cfuncdesc}{void}{PyTuple_SET_ITEM}{PyTupleObject *p, - int pos, - PyObject *o} - -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, - int new, - int last_is_sticky} -can be used to resize a tuple. Because tuples are -\emph{supposed} to be immutable, this should only be used if there is only -one module referencing the object. Do \emph{not} use this if the tuple may -already be known to some other part of the code. \code{last_is_sticky} is -a flag - if set, the tuple will grow or shrink at the front, otherwise -it will grow or shrink at the end. Think of this as destroying the old -tuple and creating a new one, only more efficiently. -\end{cfuncdesc} - - -\subsection{List Objects} - -\begin{ctypedesc}{PyListObject} -This subtype of \code{PyObject} represents a Python list object. -\end{ctypedesc} - -\begin{cvardesc}{PyTypeObject}{PyList_Type} -This instance of \code{PyTypeObject} represents the Python list type. -\end{cvardesc} - -\begin{cfuncdesc}{int}{PyList_Check}{PyObject *p} -returns true if it's argument is a \code{PyListObject} -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject *}{PyList_New}{int size} - -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyList_Size}{PyObject *} - -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject *}{PyList_GetItem}{PyObject *, int} - -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyList_SetItem}{PyObject *, int, PyObject *} - -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyList_Insert}{PyObject *, int, PyObject *} - -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyList_Append}{PyObject *, PyObject *} - -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject *}{PyList_GetSlice}{PyObject *, int, int} - -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyList_SetSlice}{PyObject *, int, int, PyObject *} - -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyList_Sort}{PyObject *} - -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyList_Reverse}{PyObject *} - -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject *}{PyList_AsTuple}{PyObject *} - -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject *}{PyList_GET_ITEM}{PyObject *list, int i} - -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyList_GET_SIZE}{PyObject *list} - -\end{cfuncdesc} - - -\section{Mapping Objects} - -\subsection{Dictionary Objects} - -\begin{ctypedesc}{PyDictObject} -This subtype of \code{PyObject} represents a Python dictionary object. -\end{ctypedesc} - -\begin{cvardesc}{PyTypeObject}{PyDict_Type} -This instance of \code{PyTypeObject} represents the Python dictionary type. -\end{cvardesc} - -\begin{cfuncdesc}{int}{PyDict_Check}{PyObject *p} -returns true if it's argument is a PyDictObject -\end{cfuncdesc} - -\begin{cfuncdesc}{PyDictObject *}{PyDict_New}{} -returns a new empty dictionary. -\end{cfuncdesc} - -\begin{cfuncdesc}{void}{PyDict_Clear}{PyDictObject *p} -empties an existing dictionary and deletes it. -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyDict_SetItem}{PyDictObject *p, - PyObject *key, - PyObject *val} -inserts \code{value} into the dictionary with a key of -\code{key}. Both \code{key} and \code{value} should be PyObjects, and \code{key} should -be hashable. -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyDict_SetItemString}{PyDictObject *p, - char *key, - PyObject *val} -inserts \code{value} into the dictionary using \code{key} -as a key. \code{key} should be a char * -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyDict_DelItem}{PyDictObject *p, PyObject *key} -removes the entry in dictionary \code{p} with key \code{key}. -\code{key} is a PyObject. -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyDict_DelItemString}{PyDictObject *p, char *key} -removes the entry in dictionary \code{p} which has a key -specified by the \code{char *}\code{key}. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject *}{PyDict_GetItem}{PyDictObject *p, PyObject *key} -returns the object from dictionary \code{p} which has a key -\code{key}. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject *}{PyDict_GetItemString}{PyDictObject *p, char *key} -does the same, but \code{key} is specified as a -\code{char *}, rather than a \code{PyObject *}. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyListObject *}{PyDict_Items}{PyDictObject *p} -returns a PyListObject containing all the items -from the dictionary, as in the mapping method \code{items()} (see the Reference -Guide) -\end{cfuncdesc} - -\begin{cfuncdesc}{PyListObject *}{PyDict_Keys}{PyDictObject *p} -returns a PyListObject containing all the keys -from the dictionary, as in the mapping method \code{keys()} (see the Reference Guide) -\end{cfuncdesc} - -\begin{cfuncdesc}{PyListObject *}{PyDict_Values}{PyDictObject *p} -returns a PyListObject containing all the values -from the dictionary, as in the mapping method \code{values()} (see the Reference Guide) -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyDict_Size}{PyDictObject *p} -returns the number of items in the dictionary. -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyDict_Next}{PyDictObject *p, - int ppos, - PyObject **pkey, - PyObject **pvalue} - -\end{cfuncdesc} - - -\section{Numeric Objects} - -\subsection{Plain Integer Objects} - -\begin{ctypedesc}{PyIntObject} -This subtype of \code{PyObject} represents a Python integer object. -\end{ctypedesc} - -\begin{cvardesc}{PyTypeObject}{PyInt_Type} -This instance of \code{PyTypeObject} represents the Python plain -integer type. -\end{cvardesc} - -\begin{cfuncdesc}{int}{PyInt_Check}{PyObject *} - -\end{cfuncdesc} - -\begin{cfuncdesc}{PyIntObject *}{PyInt_FromLong}{long ival} -creates a new integer object with a value of \code{ival}. - -The current implementation keeps an array of integer objects for all -integers between -1 and 100, when you create an int in that range you -actually just get back a reference to the existing object. So it should -be possible to change the value of 1. I suspect the behaviour of python -in this case is undefined. :-) -\end{cfuncdesc} - -\begin{cfuncdesc}{long}{PyInt_AS_LONG}{PyIntObject *io} -returns the value of the object \code{io}. -\end{cfuncdesc} - -\begin{cfuncdesc}{long}{PyInt_AsLong}{PyObject *io} -will first attempt to cast the object to a PyIntObject, if -it is not already one, and the return it's value. -\end{cfuncdesc} - -\begin{cfuncdesc}{long}{PyInt_GetMax}{} -returns the systems idea of the largest int it can handle -(LONG_MAX, as defined in the system header files) -\end{cfuncdesc} - - -\subsection{Long Integer Objects} - -\begin{ctypedesc}{PyLongObject} -This subtype of \code{PyObject} represents a Python long integer object. -\end{ctypedesc} - -\begin{cvardesc}{PyTypeObject}{PyLong_Type} -This instance of \code{PyTypeObject} represents the Python long integer type. -\end{cvardesc} - -\begin{cfuncdesc}{int}{PyLong_Check}{PyObject *p} -returns true if it's argument is a \code{PyLongObject} -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject *}{PyLong_FromLong}{long} - -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject *}{PyLong_FromUnsignedLong}{unsigned long} - -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject *}{PyLong_FromDouble}{double} - -\end{cfuncdesc} - -\begin{cfuncdesc}{long}{PyLong_AsLong}{PyObject *} - -\end{cfuncdesc} - -\begin{cfuncdesc}{unsigned long}{PyLong_AsUnsignedLong}{PyObject } - -\end{cfuncdesc} - -\begin{cfuncdesc}{double}{PyLong_AsDouble}{PyObject *} - -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject *}{PyLong_FromString}{char *, char **, int} - -\end{cfuncdesc} - - -\subsection{Floating Point Objects} - -\begin{ctypedesc}{PyFloatObject} -This subtype of \code{PyObject} represents a Python floating point object. -\end{ctypedesc} - -\begin{cvardesc}{PyTypeObject}{PyFloat_Type} -This instance of \code{PyTypeObject} represents the Python floating -point type. -\end{cvardesc} - -\begin{cfuncdesc}{int}{PyFloat_Check}{PyObject *p} -returns true if it's argument is a \code{PyFloatObject} -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject *}{PyFloat_FromDouble}{double} - -\end{cfuncdesc} - -\begin{cfuncdesc}{double}{PyFloat_AsDouble}{PyObject *} - -\end{cfuncdesc} - -\begin{cfuncdesc}{double}{PyFloat_AS_DOUBLE}{PyFloatObject *} - -\end{cfuncdesc} - - -\subsection{Complex Number Objects} - -\begin{ctypedesc}{Py_complex} -typedef struct { - double real; - double imag; -} -\end{ctypedesc} - -\begin{ctypedesc}{PyComplexObject} -This subtype of \code{PyObject} represents a Python complex number object. -\end{ctypedesc} - -\begin{cvardesc}{PyTypeObject}{PyComplex_Type} -This instance of \code{PyTypeObject} represents the Python complex -number type. -\end{cvardesc} - -\begin{cfuncdesc}{int}{PyComplex_Check}{PyObject *p} -returns true if it's argument is a \code{PyComplexObject} -\end{cfuncdesc} - -\begin{cfuncdesc}{Py_complex}{_Py_c_sum}{Py_complex, Py_complex} - -\end{cfuncdesc} - -\begin{cfuncdesc}{Py_complex}{_Py_c_diff}{Py_complex, Py_complex} - -\end{cfuncdesc} - -\begin{cfuncdesc}{Py_complex}{_Py_c_neg}{Py_complex} - -\end{cfuncdesc} - -\begin{cfuncdesc}{Py_complex}{_Py_c_prod}{Py_complex, Py_complex} - -\end{cfuncdesc} - -\begin{cfuncdesc}{Py_complex}{_Py_c_quot}{Py_complex, Py_complex} - -\end{cfuncdesc} - -\begin{cfuncdesc}{Py_complex}{_Py_c_pow}{Py_complex, Py_complex} - -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject *}{PyComplex_FromCComplex}{Py_complex} - -\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} - - - -\section{Other Objects} - -\subsection{File Objects} - -\begin{ctypedesc}{PyFileObject} -This subtype of \code{PyObject} represents a Python file object. -\end{ctypedesc} - -\begin{cvardesc}{PyTypeObject}{PyFile_Type} -This instance of \code{PyTypeObject} represents the Python file type. -\end{cvardesc} - -\begin{cfuncdesc}{int}{PyFile_Check}{PyObject *p} -returns true if it's argument is a \code{PyFileObject} -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject *}{PyFile_FromString}{char *name, char *mode} -creates a new PyFileObject pointing to the file -specified in \code{name} with the mode specified in \code{mode} -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject *}{PyFile_FromFile}{FILE *fp, - char *name, char *mode, int (*close}) -creates a new PyFileObject from the already-open \code{fp}. -The function \code{close} will be called when the file should be closed. -\end{cfuncdesc} - -\begin{cfuncdesc}{FILE *}{PyFile_AsFile}{PyFileObject *p} -returns the file object associated with \code{p} as a \code{FILE *} -\end{cfuncdesc} - -\begin{cfuncdesc}{PyStringObject *}{PyFile_GetLine}{PyObject *p, int n} -undocumented as yet -\end{cfuncdesc} - -\begin{cfuncdesc}{PyStringObject *}{PyFile_Name}{PyObject *p} -returns the name of the file specified by \code{p} as a -PyStringObject -\end{cfuncdesc} +\chapter{Defining New Object Types} -\begin{cfuncdesc}{void}{PyFile_SetBufSize}{PyFileObject *p, int n} -on systems with \code{setvbuf} only +\begin{cfuncdesc}{PyObject *}{_PyObject_New}{PyTypeObject *type} \end{cfuncdesc} -\begin{cfuncdesc}{int}{PyFile_SoftSpace}{PyFileObject *p, int newflag} -same as the file object method \code{softspace} +\begin{cfuncdesc}{PyObject *}{_PyObject_NewVar}{PyTypeObject *type, int size} \end{cfuncdesc} -\begin{cfuncdesc}{int}{PyFile_WriteObject}{PyObject *obj, PyFileObject *p} -writes object \code{obj} to file object \code{p} +\begin{cfuncdesc}{TYPE}{_PyObject_NEW}{TYPE, PyTypeObject *} \end{cfuncdesc} -\begin{cfuncdesc}{int}{PyFile_WriteString}{char *s, PyFileObject *p} -writes string \code{s} to file object \code{p} +\begin{cfuncdesc}{TYPE}{_PyObject_NEW_VAR}{TYPE, PyTypeObject *, int size} \end{cfuncdesc} -\subsection{CObjects} +\chapter{Debugging} -XXX +XXX Explain Py_DEBUG, Py_TRACE_REFS, Py_REF_DEBUG. \input{api.ind} % Index -- must be last diff --git a/Doc/api/api.tex b/Doc/api/api.tex index 780034a..b13a097 100644 --- a/Doc/api/api.tex +++ b/Doc/api/api.tex @@ -523,34 +523,40 @@ initialized state. More information about these functions is given in a later chapter. -\chapter{Basic Utilities} +\chapter{The Very High Level Layer} -XXX These utilities should be moved to some other section... +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}{void}{Py_FatalError}{char *message} -Print a fatal error message and kill the process. No cleanup is -performed. This function should only be invoked when a condition is -detected that would make it dangerous to continue using the Python -interpreter; e.g., when the object administration appears to be -corrupted. On \UNIX{}, the standard \C{} library function \code{abort()} is -called which will attempt to produce a \file{core} file. +\begin{cfuncdesc}{int}{PyRun_AnyFile}{FILE *, char *} \end{cfuncdesc} -\begin{cfuncdesc}{void}{Py_Exit}{int status} -Exit the current process. This calls \code{Py_Finalize()} and then -calls the standard \C{} library function \code{exit(\var{status})}. +\begin{cfuncdesc}{int}{PyRun_SimpleString}{char *} \end{cfuncdesc} -\begin{cfuncdesc}{int}{Py_AtExit}{void (*func) ()} -Register a cleanup function to be called by \cfunction{Py_Finalize()}. -The cleanup function will be called with no arguments and should -return no value. At most 32 cleanup functions can be registered. -When the registration is successful, \cfunction{Py_AtExit()} returns -\code{0}; on failure, it returns \code{-1}. The cleanup function -registered last is called first. Each cleanup function will be called -at most once. Since Python's internal finallization will have -completed before the cleanup function, no Python APIs should be called -by \var{func}. +\begin{cfuncdesc}{int}{PyRun_SimpleFile}{FILE *, char *} +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyRun_InteractiveOne}{FILE *, char *} +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyRun_InteractiveLoop}{FILE *, char *} +\end{cfuncdesc} + +\begin{cfuncdesc}{struct _node *}{PyParser_SimpleParseString}{char *, int} +\end{cfuncdesc} + +\begin{cfuncdesc}{struct _node *}{PyParser_SimpleParseFile}{FILE *, char *, int} +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject *}{PyRun_String}{char *, int, PyObject *, PyObject *} +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject *}{PyRun_File}{FILE *, char *, int, PyObject *, PyObject *} +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject *}{Py_CompileString}{char *, char *, int} \end{cfuncdesc} @@ -849,7 +855,36 @@ the standard \C{} library function \code{time()}. \end{cfuncdesc} -\section{Importing modules} +\section{Process Control} + +\begin{cfuncdesc}{void}{Py_FatalError}{char *message} +Print a fatal error message and kill the process. No cleanup is +performed. This function should only be invoked when a condition is +detected that would make it dangerous to continue using the Python +interpreter; e.g., when the object administration appears to be +corrupted. On \UNIX{}, the standard \C{} library function \code{abort()} is +called which will attempt to produce a \file{core} file. +\end{cfuncdesc} + +\begin{cfuncdesc}{void}{Py_Exit}{int status} +Exit the current process. This calls \code{Py_Finalize()} and then +calls the standard \C{} library function \code{exit(\var{status})}. +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{Py_AtExit}{void (*func) ()} +Register a cleanup function to be called by \cfunction{Py_Finalize()}. +The cleanup function will be called with no arguments and should +return no value. At most 32 cleanup functions can be registered. +When the registration is successful, \cfunction{Py_AtExit()} returns +\code{0}; on failure, it returns \code{-1}. The cleanup function +registered last is called first. Each cleanup function will be called +at most once. Since Python's internal finallization will have +completed before the cleanup function, no Python APIs should be called +by \var{func}. +\end{cfuncdesc} + + +\section{Importing Modules} \begin{cfuncdesc}{PyObject *}{PyImport_ImportModule}{char *name} This is a simplified interface to \code{PyImport_ImportModuleEx} @@ -978,48 +1013,6 @@ dynamically created collection of frozen modules. \end{cvardesc} -\chapter{Debugging} - -XXX Explain Py_DEBUG, Py_TRACE_REFS, Py_REF_DEBUG. - - -\chapter{The Very High Level Layer} - -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 *} -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyRun_SimpleString}{char *} -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyRun_SimpleFile}{FILE *, char *} -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyRun_InteractiveOne}{FILE *, char *} -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyRun_InteractiveLoop}{FILE *, char *} -\end{cfuncdesc} - -\begin{cfuncdesc}{struct _node *}{PyParser_SimpleParseString}{char *, int} -\end{cfuncdesc} - -\begin{cfuncdesc}{struct _node *}{PyParser_SimpleParseFile}{FILE *, char *, int} -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject *}{PyRun_String}{char *, int, PyObject *, PyObject *} -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject *}{PyRun_File}{FILE *, char *, int, PyObject *, PyObject *} -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject *}{Py_CompileString}{char *, char *, int} -\end{cfuncdesc} - - \chapter{Abstract Objects Layer} The functions in this chapter interact with Python objects regardless @@ -1609,23 +1602,569 @@ types. Passing them an object of the wrong type is not a good idea; if you receive an object from a Python program and you are not sure that it has the right type, you must perform a type check first; e.g. to check that an object is a dictionary, use -\code{PyDict_Check()}. +\cfunction{PyDict_Check()}. The chapter is structured like the +``family tree'' of Python object types. -\chapter{Defining New Object Types} +\section{Fundamental Objects} + +This section describes Python type objects and the singleton object +\code{None}. + + +\subsection{Type Objects} + +\begin{ctypedesc}{PyTypeObject} + +\end{ctypedesc} + +\begin{cvardesc}{PyObject *}{PyType_Type} + +\end{cvardesc} + + +\subsection{The None Object} + +\begin{cvardesc}{PyObject *}{Py_None} +XXX macro +\end{cvardesc} + + +\section{Sequence Objects} + +Generic operations on sequence objects were discussed in the previous +chapter; this section deals with the specific kinds of sequence +objects that are intrinsic to the Python language. + + +\subsection{String Objects} + +\begin{ctypedesc}{PyStringObject} +This subtype of \code{PyObject} represents a Python string object. +\end{ctypedesc} + +\begin{cvardesc}{PyTypeObject}{PyString_Type} +This instance of \code{PyTypeObject} represents the Python string type. +\end{cvardesc} + +\begin{cfuncdesc}{int}{PyString_Check}{PyObject *o} -\begin{cfuncdesc}{PyObject *}{_PyObject_New}{PyTypeObject *type} \end{cfuncdesc} -\begin{cfuncdesc}{PyObject *}{_PyObject_NewVar}{PyTypeObject *type, int size} +\begin{cfuncdesc}{PyObject *}{PyString_FromStringAndSize}{const char *, int} + \end{cfuncdesc} -\begin{cfuncdesc}{TYPE}{_PyObject_NEW}{TYPE, PyTypeObject *} +\begin{cfuncdesc}{PyObject *}{PyString_FromString}{const char *} + \end{cfuncdesc} -\begin{cfuncdesc}{TYPE}{_PyObject_NEW_VAR}{TYPE, PyTypeObject *, int size} +\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 *} + +\end{cfuncdesc} + + +\subsection{Tuple Objects} + +\begin{ctypedesc}{PyTupleObject} +This subtype of \code{PyObject} represents a Python tuple object. +\end{ctypedesc} + +\begin{cvardesc}{PyTypeObject}{PyTuple_Type} +This instance of \code{PyTypeObject} represents the Python tuple type. +\end{cvardesc} + +\begin{cfuncdesc}{int}{PyTuple_Check}{PyObject *p} +Return true if the argument is a tuple object. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyTupleObject *}{PyTuple_New}{int s} +Return a new tuple object of size \code{s} +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyTuple_Size}{PyTupleObject *p} +akes a pointer to a tuple object, and returns the size +of that tuple. \end{cfuncdesc} +\begin{cfuncdesc}{PyObject *}{PyTuple_GetItem}{PyTupleObject *p, int pos} +returns the object at position \code{pos} in the tuple pointed +to by \code{p}. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject *}{PyTuple_GET_ITEM}{PyTupleObject *p, int pos} +does the same, but does no checking of it's +arguments. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyTupleObject *}{PyTuple_GetSlice}{PyTupleObject *p, + int low, + int high} +takes a slice of the tuple pointed to by \code{p} from +\code{low} to \code{high} and returns it as a new tuple. +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyTuple_SetItem}{PyTupleObject *p, + int pos, + PyObject *o} +inserts a reference to object \code{o} at position \code{pos} of +the tuple pointed to by \code{p}. It returns 0 on success. +\end{cfuncdesc} + +\begin{cfuncdesc}{void}{PyTuple_SET_ITEM}{PyTupleObject *p, + int pos, + PyObject *o} + +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, + int new, + int last_is_sticky} +can be used to resize a tuple. Because tuples are +\emph{supposed} to be immutable, this should only be used if there is only +one module referencing the object. Do \emph{not} use this if the tuple may +already be known to some other part of the code. \code{last_is_sticky} is +a flag - if set, the tuple will grow or shrink at the front, otherwise +it will grow or shrink at the end. Think of this as destroying the old +tuple and creating a new one, only more efficiently. +\end{cfuncdesc} + + +\subsection{List Objects} + +\begin{ctypedesc}{PyListObject} +This subtype of \code{PyObject} represents a Python list object. +\end{ctypedesc} + +\begin{cvardesc}{PyTypeObject}{PyList_Type} +This instance of \code{PyTypeObject} represents the Python list type. +\end{cvardesc} + +\begin{cfuncdesc}{int}{PyList_Check}{PyObject *p} +returns true if it's argument is a \code{PyListObject} +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject *}{PyList_New}{int size} + +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyList_Size}{PyObject *} + +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject *}{PyList_GetItem}{PyObject *, int} + +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyList_SetItem}{PyObject *, int, PyObject *} + +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyList_Insert}{PyObject *, int, PyObject *} + +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyList_Append}{PyObject *, PyObject *} + +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject *}{PyList_GetSlice}{PyObject *, int, int} + +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyList_SetSlice}{PyObject *, int, int, PyObject *} + +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyList_Sort}{PyObject *} + +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyList_Reverse}{PyObject *} + +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject *}{PyList_AsTuple}{PyObject *} + +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject *}{PyList_GET_ITEM}{PyObject *list, int i} + +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyList_GET_SIZE}{PyObject *list} + +\end{cfuncdesc} + + +\section{Mapping Objects} + +\subsection{Dictionary Objects} + +\begin{ctypedesc}{PyDictObject} +This subtype of \code{PyObject} represents a Python dictionary object. +\end{ctypedesc} + +\begin{cvardesc}{PyTypeObject}{PyDict_Type} +This instance of \code{PyTypeObject} represents the Python dictionary type. +\end{cvardesc} + +\begin{cfuncdesc}{int}{PyDict_Check}{PyObject *p} +returns true if it's argument is a PyDictObject +\end{cfuncdesc} + +\begin{cfuncdesc}{PyDictObject *}{PyDict_New}{} +returns a new empty dictionary. +\end{cfuncdesc} + +\begin{cfuncdesc}{void}{PyDict_Clear}{PyDictObject *p} +empties an existing dictionary and deletes it. +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyDict_SetItem}{PyDictObject *p, + PyObject *key, + PyObject *val} +inserts \code{value} into the dictionary with a key of +\code{key}. Both \code{key} and \code{value} should be PyObjects, and \code{key} should +be hashable. +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyDict_SetItemString}{PyDictObject *p, + char *key, + PyObject *val} +inserts \code{value} into the dictionary using \code{key} +as a key. \code{key} should be a char * +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyDict_DelItem}{PyDictObject *p, PyObject *key} +removes the entry in dictionary \code{p} with key \code{key}. +\code{key} is a PyObject. +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyDict_DelItemString}{PyDictObject *p, char *key} +removes the entry in dictionary \code{p} which has a key +specified by the \code{char *}\code{key}. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject *}{PyDict_GetItem}{PyDictObject *p, PyObject *key} +returns the object from dictionary \code{p} which has a key +\code{key}. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject *}{PyDict_GetItemString}{PyDictObject *p, char *key} +does the same, but \code{key} is specified as a +\code{char *}, rather than a \code{PyObject *}. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyListObject *}{PyDict_Items}{PyDictObject *p} +returns a PyListObject containing all the items +from the dictionary, as in the mapping method \code{items()} (see the Reference +Guide) +\end{cfuncdesc} + +\begin{cfuncdesc}{PyListObject *}{PyDict_Keys}{PyDictObject *p} +returns a PyListObject containing all the keys +from the dictionary, as in the mapping method \code{keys()} (see the Reference Guide) +\end{cfuncdesc} + +\begin{cfuncdesc}{PyListObject *}{PyDict_Values}{PyDictObject *p} +returns a PyListObject containing all the values +from the dictionary, as in the mapping method \code{values()} (see the Reference Guide) +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyDict_Size}{PyDictObject *p} +returns the number of items in the dictionary. +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyDict_Next}{PyDictObject *p, + int ppos, + PyObject **pkey, + PyObject **pvalue} + +\end{cfuncdesc} + + +\section{Numeric Objects} + +\subsection{Plain Integer Objects} + +\begin{ctypedesc}{PyIntObject} +This subtype of \code{PyObject} represents a Python integer object. +\end{ctypedesc} + +\begin{cvardesc}{PyTypeObject}{PyInt_Type} +This instance of \code{PyTypeObject} represents the Python plain +integer type. +\end{cvardesc} + +\begin{cfuncdesc}{int}{PyInt_Check}{PyObject *} + +\end{cfuncdesc} + +\begin{cfuncdesc}{PyIntObject *}{PyInt_FromLong}{long ival} +creates a new integer object with a value of \code{ival}. + +The current implementation keeps an array of integer objects for all +integers between -1 and 100, when you create an int in that range you +actually just get back a reference to the existing object. So it should +be possible to change the value of 1. I suspect the behaviour of python +in this case is undefined. :-) +\end{cfuncdesc} + +\begin{cfuncdesc}{long}{PyInt_AS_LONG}{PyIntObject *io} +returns the value of the object \code{io}. +\end{cfuncdesc} + +\begin{cfuncdesc}{long}{PyInt_AsLong}{PyObject *io} +will first attempt to cast the object to a PyIntObject, if +it is not already one, and the return it's value. +\end{cfuncdesc} + +\begin{cfuncdesc}{long}{PyInt_GetMax}{} +returns the systems idea of the largest int it can handle +(LONG_MAX, as defined in the system header files) +\end{cfuncdesc} + + +\subsection{Long Integer Objects} + +\begin{ctypedesc}{PyLongObject} +This subtype of \code{PyObject} represents a Python long integer object. +\end{ctypedesc} + +\begin{cvardesc}{PyTypeObject}{PyLong_Type} +This instance of \code{PyTypeObject} represents the Python long integer type. +\end{cvardesc} + +\begin{cfuncdesc}{int}{PyLong_Check}{PyObject *p} +returns true if it's argument is a \code{PyLongObject} +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject *}{PyLong_FromLong}{long} + +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject *}{PyLong_FromUnsignedLong}{unsigned long} + +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject *}{PyLong_FromDouble}{double} + +\end{cfuncdesc} + +\begin{cfuncdesc}{long}{PyLong_AsLong}{PyObject *} + +\end{cfuncdesc} + +\begin{cfuncdesc}{unsigned long}{PyLong_AsUnsignedLong}{PyObject } + +\end{cfuncdesc} + +\begin{cfuncdesc}{double}{PyLong_AsDouble}{PyObject *} + +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject *}{PyLong_FromString}{char *, char **, int} + +\end{cfuncdesc} + + +\subsection{Floating Point Objects} + +\begin{ctypedesc}{PyFloatObject} +This subtype of \code{PyObject} represents a Python floating point object. +\end{ctypedesc} + +\begin{cvardesc}{PyTypeObject}{PyFloat_Type} +This instance of \code{PyTypeObject} represents the Python floating +point type. +\end{cvardesc} + +\begin{cfuncdesc}{int}{PyFloat_Check}{PyObject *p} +returns true if it's argument is a \code{PyFloatObject} +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject *}{PyFloat_FromDouble}{double} + +\end{cfuncdesc} + +\begin{cfuncdesc}{double}{PyFloat_AsDouble}{PyObject *} + +\end{cfuncdesc} + +\begin{cfuncdesc}{double}{PyFloat_AS_DOUBLE}{PyFloatObject *} + +\end{cfuncdesc} + + +\subsection{Complex Number Objects} + +\begin{ctypedesc}{Py_complex} +typedef struct { + double real; + double imag; +} +\end{ctypedesc} + +\begin{ctypedesc}{PyComplexObject} +This subtype of \code{PyObject} represents a Python complex number object. +\end{ctypedesc} + +\begin{cvardesc}{PyTypeObject}{PyComplex_Type} +This instance of \code{PyTypeObject} represents the Python complex +number type. +\end{cvardesc} + +\begin{cfuncdesc}{int}{PyComplex_Check}{PyObject *p} +returns true if it's argument is a \code{PyComplexObject} +\end{cfuncdesc} + +\begin{cfuncdesc}{Py_complex}{_Py_c_sum}{Py_complex, Py_complex} + +\end{cfuncdesc} + +\begin{cfuncdesc}{Py_complex}{_Py_c_diff}{Py_complex, Py_complex} + +\end{cfuncdesc} + +\begin{cfuncdesc}{Py_complex}{_Py_c_neg}{Py_complex} + +\end{cfuncdesc} + +\begin{cfuncdesc}{Py_complex}{_Py_c_prod}{Py_complex, Py_complex} + +\end{cfuncdesc} + +\begin{cfuncdesc}{Py_complex}{_Py_c_quot}{Py_complex, Py_complex} + +\end{cfuncdesc} + +\begin{cfuncdesc}{Py_complex}{_Py_c_pow}{Py_complex, Py_complex} + +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject *}{PyComplex_FromCComplex}{Py_complex} + +\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} + + + +\section{Other Objects} + +\subsection{File Objects} + +\begin{ctypedesc}{PyFileObject} +This subtype of \code{PyObject} represents a Python file object. +\end{ctypedesc} + +\begin{cvardesc}{PyTypeObject}{PyFile_Type} +This instance of \code{PyTypeObject} represents the Python file type. +\end{cvardesc} + +\begin{cfuncdesc}{int}{PyFile_Check}{PyObject *p} +returns true if it's argument is a \code{PyFileObject} +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject *}{PyFile_FromString}{char *name, char *mode} +creates a new PyFileObject pointing to the file +specified in \code{name} with the mode specified in \code{mode} +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject *}{PyFile_FromFile}{FILE *fp, + char *name, char *mode, int (*close}) +creates a new PyFileObject from the already-open \code{fp}. +The function \code{close} will be called when the file should be closed. +\end{cfuncdesc} + +\begin{cfuncdesc}{FILE *}{PyFile_AsFile}{PyFileObject *p} +returns the file object associated with \code{p} as a \code{FILE *} +\end{cfuncdesc} + +\begin{cfuncdesc}{PyStringObject *}{PyFile_GetLine}{PyObject *p, int n} +undocumented as yet +\end{cfuncdesc} + +\begin{cfuncdesc}{PyStringObject *}{PyFile_Name}{PyObject *p} +returns the name of the file specified by \code{p} as a +PyStringObject +\end{cfuncdesc} + +\begin{cfuncdesc}{void}{PyFile_SetBufSize}{PyFileObject *p, int n} +on systems with \code{setvbuf} only +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyFile_SoftSpace}{PyFileObject *p, int newflag} +same as the file object method \code{softspace} +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyFile_WriteObject}{PyObject *obj, PyFileObject *p} +writes object \code{obj} to file object \code{p} +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyFile_WriteString}{char *s, PyFileObject *p} +writes string \code{s} to file object \code{p} +\end{cfuncdesc} + + +\subsection{CObjects} + +XXX + + \chapter{Initialization, Finalization, and Threads} \begin{cfuncdesc}{void}{Py_Initialize}{} @@ -2265,570 +2804,24 @@ _PyObject_New, _PyObject_NewVar PyObject_NEW, PyObject_NEW_VAR -\chapter{Specific Data Types} - -This chapter describes the functions that deal with specific types of -Python objects. It is structured like the ``family tree'' of Python -object types. - - -\section{Fundamental Objects} - -This section describes Python type objects and the singleton object -\code{None}. - - -\subsection{Type Objects} - -\begin{ctypedesc}{PyTypeObject} - -\end{ctypedesc} - -\begin{cvardesc}{PyObject *}{PyType_Type} - -\end{cvardesc} - - -\subsection{The None Object} - -\begin{cvardesc}{PyObject *}{Py_None} -XXX macro -\end{cvardesc} - - -\section{Sequence Objects} - -Generic operations on sequence objects were discussed in the previous -chapter; this section deals with the specific kinds of sequence -objects that are intrinsic to the Python language. - - -\subsection{String Objects} - -\begin{ctypedesc}{PyStringObject} -This subtype of \code{PyObject} represents a Python string object. -\end{ctypedesc} - -\begin{cvardesc}{PyTypeObject}{PyString_Type} -This instance of \code{PyTypeObject} represents the Python string type. -\end{cvardesc} - -\begin{cfuncdesc}{int}{PyString_Check}{PyObject *o} - -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject *}{PyString_FromStringAndSize}{const char *, int} - -\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 *} - -\end{cfuncdesc} - - -\subsection{Tuple Objects} - -\begin{ctypedesc}{PyTupleObject} -This subtype of \code{PyObject} represents a Python tuple object. -\end{ctypedesc} - -\begin{cvardesc}{PyTypeObject}{PyTuple_Type} -This instance of \code{PyTypeObject} represents the Python tuple type. -\end{cvardesc} - -\begin{cfuncdesc}{int}{PyTuple_Check}{PyObject *p} -Return true if the argument is a tuple object. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyTupleObject *}{PyTuple_New}{int s} -Return a new tuple object of size \code{s} -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyTuple_Size}{PyTupleObject *p} -akes a pointer to a tuple object, and returns the size -of that tuple. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject *}{PyTuple_GetItem}{PyTupleObject *p, int pos} -returns the object at position \code{pos} in the tuple pointed -to by \code{p}. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject *}{PyTuple_GET_ITEM}{PyTupleObject *p, int pos} -does the same, but does no checking of it's -arguments. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyTupleObject *}{PyTuple_GetSlice}{PyTupleObject *p, - int low, - int high} -takes a slice of the tuple pointed to by \code{p} from -\code{low} to \code{high} and returns it as a new tuple. -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyTuple_SetItem}{PyTupleObject *p, - int pos, - PyObject *o} -inserts a reference to object \code{o} at position \code{pos} of -the tuple pointed to by \code{p}. It returns 0 on success. -\end{cfuncdesc} - -\begin{cfuncdesc}{void}{PyTuple_SET_ITEM}{PyTupleObject *p, - int pos, - PyObject *o} - -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, - int new, - int last_is_sticky} -can be used to resize a tuple. Because tuples are -\emph{supposed} to be immutable, this should only be used if there is only -one module referencing the object. Do \emph{not} use this if the tuple may -already be known to some other part of the code. \code{last_is_sticky} is -a flag - if set, the tuple will grow or shrink at the front, otherwise -it will grow or shrink at the end. Think of this as destroying the old -tuple and creating a new one, only more efficiently. -\end{cfuncdesc} - - -\subsection{List Objects} - -\begin{ctypedesc}{PyListObject} -This subtype of \code{PyObject} represents a Python list object. -\end{ctypedesc} - -\begin{cvardesc}{PyTypeObject}{PyList_Type} -This instance of \code{PyTypeObject} represents the Python list type. -\end{cvardesc} - -\begin{cfuncdesc}{int}{PyList_Check}{PyObject *p} -returns true if it's argument is a \code{PyListObject} -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject *}{PyList_New}{int size} - -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyList_Size}{PyObject *} - -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject *}{PyList_GetItem}{PyObject *, int} - -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyList_SetItem}{PyObject *, int, PyObject *} - -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyList_Insert}{PyObject *, int, PyObject *} - -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyList_Append}{PyObject *, PyObject *} - -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject *}{PyList_GetSlice}{PyObject *, int, int} - -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyList_SetSlice}{PyObject *, int, int, PyObject *} - -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyList_Sort}{PyObject *} - -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyList_Reverse}{PyObject *} - -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject *}{PyList_AsTuple}{PyObject *} - -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject *}{PyList_GET_ITEM}{PyObject *list, int i} - -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyList_GET_SIZE}{PyObject *list} - -\end{cfuncdesc} - - -\section{Mapping Objects} - -\subsection{Dictionary Objects} - -\begin{ctypedesc}{PyDictObject} -This subtype of \code{PyObject} represents a Python dictionary object. -\end{ctypedesc} - -\begin{cvardesc}{PyTypeObject}{PyDict_Type} -This instance of \code{PyTypeObject} represents the Python dictionary type. -\end{cvardesc} - -\begin{cfuncdesc}{int}{PyDict_Check}{PyObject *p} -returns true if it's argument is a PyDictObject -\end{cfuncdesc} - -\begin{cfuncdesc}{PyDictObject *}{PyDict_New}{} -returns a new empty dictionary. -\end{cfuncdesc} - -\begin{cfuncdesc}{void}{PyDict_Clear}{PyDictObject *p} -empties an existing dictionary and deletes it. -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyDict_SetItem}{PyDictObject *p, - PyObject *key, - PyObject *val} -inserts \code{value} into the dictionary with a key of -\code{key}. Both \code{key} and \code{value} should be PyObjects, and \code{key} should -be hashable. -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyDict_SetItemString}{PyDictObject *p, - char *key, - PyObject *val} -inserts \code{value} into the dictionary using \code{key} -as a key. \code{key} should be a char * -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyDict_DelItem}{PyDictObject *p, PyObject *key} -removes the entry in dictionary \code{p} with key \code{key}. -\code{key} is a PyObject. -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyDict_DelItemString}{PyDictObject *p, char *key} -removes the entry in dictionary \code{p} which has a key -specified by the \code{char *}\code{key}. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject *}{PyDict_GetItem}{PyDictObject *p, PyObject *key} -returns the object from dictionary \code{p} which has a key -\code{key}. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject *}{PyDict_GetItemString}{PyDictObject *p, char *key} -does the same, but \code{key} is specified as a -\code{char *}, rather than a \code{PyObject *}. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyListObject *}{PyDict_Items}{PyDictObject *p} -returns a PyListObject containing all the items -from the dictionary, as in the mapping method \code{items()} (see the Reference -Guide) -\end{cfuncdesc} - -\begin{cfuncdesc}{PyListObject *}{PyDict_Keys}{PyDictObject *p} -returns a PyListObject containing all the keys -from the dictionary, as in the mapping method \code{keys()} (see the Reference Guide) -\end{cfuncdesc} - -\begin{cfuncdesc}{PyListObject *}{PyDict_Values}{PyDictObject *p} -returns a PyListObject containing all the values -from the dictionary, as in the mapping method \code{values()} (see the Reference Guide) -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyDict_Size}{PyDictObject *p} -returns the number of items in the dictionary. -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyDict_Next}{PyDictObject *p, - int ppos, - PyObject **pkey, - PyObject **pvalue} - -\end{cfuncdesc} - - -\section{Numeric Objects} - -\subsection{Plain Integer Objects} - -\begin{ctypedesc}{PyIntObject} -This subtype of \code{PyObject} represents a Python integer object. -\end{ctypedesc} - -\begin{cvardesc}{PyTypeObject}{PyInt_Type} -This instance of \code{PyTypeObject} represents the Python plain -integer type. -\end{cvardesc} - -\begin{cfuncdesc}{int}{PyInt_Check}{PyObject *} - -\end{cfuncdesc} - -\begin{cfuncdesc}{PyIntObject *}{PyInt_FromLong}{long ival} -creates a new integer object with a value of \code{ival}. - -The current implementation keeps an array of integer objects for all -integers between -1 and 100, when you create an int in that range you -actually just get back a reference to the existing object. So it should -be possible to change the value of 1. I suspect the behaviour of python -in this case is undefined. :-) -\end{cfuncdesc} - -\begin{cfuncdesc}{long}{PyInt_AS_LONG}{PyIntObject *io} -returns the value of the object \code{io}. -\end{cfuncdesc} - -\begin{cfuncdesc}{long}{PyInt_AsLong}{PyObject *io} -will first attempt to cast the object to a PyIntObject, if -it is not already one, and the return it's value. -\end{cfuncdesc} - -\begin{cfuncdesc}{long}{PyInt_GetMax}{} -returns the systems idea of the largest int it can handle -(LONG_MAX, as defined in the system header files) -\end{cfuncdesc} - - -\subsection{Long Integer Objects} - -\begin{ctypedesc}{PyLongObject} -This subtype of \code{PyObject} represents a Python long integer object. -\end{ctypedesc} - -\begin{cvardesc}{PyTypeObject}{PyLong_Type} -This instance of \code{PyTypeObject} represents the Python long integer type. -\end{cvardesc} - -\begin{cfuncdesc}{int}{PyLong_Check}{PyObject *p} -returns true if it's argument is a \code{PyLongObject} -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject *}{PyLong_FromLong}{long} - -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject *}{PyLong_FromUnsignedLong}{unsigned long} - -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject *}{PyLong_FromDouble}{double} - -\end{cfuncdesc} - -\begin{cfuncdesc}{long}{PyLong_AsLong}{PyObject *} - -\end{cfuncdesc} - -\begin{cfuncdesc}{unsigned long}{PyLong_AsUnsignedLong}{PyObject } - -\end{cfuncdesc} - -\begin{cfuncdesc}{double}{PyLong_AsDouble}{PyObject *} - -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject *}{PyLong_FromString}{char *, char **, int} - -\end{cfuncdesc} - - -\subsection{Floating Point Objects} - -\begin{ctypedesc}{PyFloatObject} -This subtype of \code{PyObject} represents a Python floating point object. -\end{ctypedesc} - -\begin{cvardesc}{PyTypeObject}{PyFloat_Type} -This instance of \code{PyTypeObject} represents the Python floating -point type. -\end{cvardesc} - -\begin{cfuncdesc}{int}{PyFloat_Check}{PyObject *p} -returns true if it's argument is a \code{PyFloatObject} -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject *}{PyFloat_FromDouble}{double} - -\end{cfuncdesc} - -\begin{cfuncdesc}{double}{PyFloat_AsDouble}{PyObject *} - -\end{cfuncdesc} - -\begin{cfuncdesc}{double}{PyFloat_AS_DOUBLE}{PyFloatObject *} - -\end{cfuncdesc} - - -\subsection{Complex Number Objects} - -\begin{ctypedesc}{Py_complex} -typedef struct { - double real; - double imag; -} -\end{ctypedesc} - -\begin{ctypedesc}{PyComplexObject} -This subtype of \code{PyObject} represents a Python complex number object. -\end{ctypedesc} - -\begin{cvardesc}{PyTypeObject}{PyComplex_Type} -This instance of \code{PyTypeObject} represents the Python complex -number type. -\end{cvardesc} - -\begin{cfuncdesc}{int}{PyComplex_Check}{PyObject *p} -returns true if it's argument is a \code{PyComplexObject} -\end{cfuncdesc} - -\begin{cfuncdesc}{Py_complex}{_Py_c_sum}{Py_complex, Py_complex} - -\end{cfuncdesc} - -\begin{cfuncdesc}{Py_complex}{_Py_c_diff}{Py_complex, Py_complex} - -\end{cfuncdesc} - -\begin{cfuncdesc}{Py_complex}{_Py_c_neg}{Py_complex} - -\end{cfuncdesc} - -\begin{cfuncdesc}{Py_complex}{_Py_c_prod}{Py_complex, Py_complex} - -\end{cfuncdesc} - -\begin{cfuncdesc}{Py_complex}{_Py_c_quot}{Py_complex, Py_complex} - -\end{cfuncdesc} - -\begin{cfuncdesc}{Py_complex}{_Py_c_pow}{Py_complex, Py_complex} - -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject *}{PyComplex_FromCComplex}{Py_complex} - -\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} - - - -\section{Other Objects} - -\subsection{File Objects} - -\begin{ctypedesc}{PyFileObject} -This subtype of \code{PyObject} represents a Python file object. -\end{ctypedesc} - -\begin{cvardesc}{PyTypeObject}{PyFile_Type} -This instance of \code{PyTypeObject} represents the Python file type. -\end{cvardesc} - -\begin{cfuncdesc}{int}{PyFile_Check}{PyObject *p} -returns true if it's argument is a \code{PyFileObject} -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject *}{PyFile_FromString}{char *name, char *mode} -creates a new PyFileObject pointing to the file -specified in \code{name} with the mode specified in \code{mode} -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject *}{PyFile_FromFile}{FILE *fp, - char *name, char *mode, int (*close}) -creates a new PyFileObject from the already-open \code{fp}. -The function \code{close} will be called when the file should be closed. -\end{cfuncdesc} - -\begin{cfuncdesc}{FILE *}{PyFile_AsFile}{PyFileObject *p} -returns the file object associated with \code{p} as a \code{FILE *} -\end{cfuncdesc} - -\begin{cfuncdesc}{PyStringObject *}{PyFile_GetLine}{PyObject *p, int n} -undocumented as yet -\end{cfuncdesc} - -\begin{cfuncdesc}{PyStringObject *}{PyFile_Name}{PyObject *p} -returns the name of the file specified by \code{p} as a -PyStringObject -\end{cfuncdesc} +\chapter{Defining New Object Types} -\begin{cfuncdesc}{void}{PyFile_SetBufSize}{PyFileObject *p, int n} -on systems with \code{setvbuf} only +\begin{cfuncdesc}{PyObject *}{_PyObject_New}{PyTypeObject *type} \end{cfuncdesc} -\begin{cfuncdesc}{int}{PyFile_SoftSpace}{PyFileObject *p, int newflag} -same as the file object method \code{softspace} +\begin{cfuncdesc}{PyObject *}{_PyObject_NewVar}{PyTypeObject *type, int size} \end{cfuncdesc} -\begin{cfuncdesc}{int}{PyFile_WriteObject}{PyObject *obj, PyFileObject *p} -writes object \code{obj} to file object \code{p} +\begin{cfuncdesc}{TYPE}{_PyObject_NEW}{TYPE, PyTypeObject *} \end{cfuncdesc} -\begin{cfuncdesc}{int}{PyFile_WriteString}{char *s, PyFileObject *p} -writes string \code{s} to file object \code{p} +\begin{cfuncdesc}{TYPE}{_PyObject_NEW_VAR}{TYPE, PyTypeObject *, int size} \end{cfuncdesc} -\subsection{CObjects} +\chapter{Debugging} -XXX +XXX Explain Py_DEBUG, Py_TRACE_REFS, Py_REF_DEBUG. \input{api.ind} % Index -- must be last |