% XXX a *really* short intro only.
\chapter{Introduction}
+\label{intro}
The Application Programmer's Interface to Python gives \C{} and \Cpp{}
programmers access to the Python interpreter at a variety of levels.
attempting to embed Python in a real application.
\section{Include Files}
+\label{includes}
All function, type and macro definitions needed to use the Python/C
API are included in your code by the following line:
these prefixes.
\section{Objects, Types and Reference Counts}
+\label{objects}
Most Python/C API functions have one or more arguments as well as a
return value of type \code{PyObject *}. This type is a pointer
true iff the object pointed to by \var{a} is a Python list.
\subsection{Reference Counts}
+\label{refcounts}
The reference count is important because today's computers have a
finite (and often severly limited) memory size; it counts how many
when they are done with the result; this soon becomes second nature.
\subsubsection{Reference Count Details}
+\label{refcountDetails}
The reference count behavior of functions in the Python/C API is best
expelained in terms of \emph{ownership of references}. Note that we
\end{verbatim}
\subsection{Types}
+\label{types}
There are few other data types that play a significant role in
the Python/C API; most are simple \C{} types such as \code{int},
be discussed together with the functions that use them.
\section{Exceptions}
+\label{exceptions}
The Python programmer only needs to deal with exceptions if specific
error handling is required; unhandled exceptions are automatically
\section{Embedding Python}
+\label{embedding}
The one important task that only embedders (as opposed to extension
writers) of the Python interpreter have to worry about is the
\chapter{The Very High Level Layer}
+\label{veryhigh}
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
\chapter{Reference Counting}
+\label{countingRefs}
The macros in this section are used for managing reference counts
of Python objects.
\chapter{Exception Handling}
+\label{exceptionHandling}
The functions in this chapter will let you handle and raise Python
exceptions. It is important to understand some of the basics of
\section{Standard Exceptions}
+\label{standardExceptions}
All standard Python exceptions are available as global variables whose
names are \samp{PyExc_} followed by the Python exception name.
\chapter{Utilities}
+\label{utilities}
The functions in this chapter perform various utility tasks, such as
parsing function arguments and constructing Python values from \C{}
values.
\section{OS Utilities}
+\label{os}
\begin{cfuncdesc}{int}{Py_FdIsInteractive}{FILE *fp, char *filename}
Return true (nonzero) if the standard I/O file \var{fp} with name
\section{Process Control}
+\label{processControl}
\begin{cfuncdesc}{void}{Py_FatalError}{char *message}
Print a fatal error message and kill the process. No cleanup is
\section{Importing Modules}
+\label{importing}
\begin{cfuncdesc}{PyObject *}{PyImport_ImportModule}{char *name}
This is a simplified interface to \cfunction{PyImport_ImportModuleEx()}
\chapter{Abstract Objects Layer}
+\label{abstract}
The functions in this chapter interact with Python objects regardless
of their type, or with wide classes of object types (e.g. all
for which they do not apply, they will flag a Python exception.
\section{Object Protocol}
+\label{object}
\begin{cfuncdesc}{int}{PyObject_Print}{PyObject *o, FILE *fp, int flags}
Print an object \var{o}, on file \var{fp}. Returns \code{-1} on error
\section{Number Protocol}
+\label{number}
\begin{cfuncdesc}{int}{PyNumber_Check}{PyObject *o}
Returns \code{1} if the object \var{o} provides numeric protocols, and
\section{Sequence Protocol}
+\label{sequence}
\begin{cfuncdesc}{int}{PySequence_Check}{PyObject *o}
Return \code{1} if the object provides sequence protocol, and \code{0}
the Python expression \samp{\var{o}.index(\var{value})}.
\end{cfuncdesc}
+
\section{Mapping Protocol}
+\label{mapping}
\begin{cfuncdesc}{int}{PyMapping_Check}{PyObject *o}
Return \code{1} if the object provides mapping protocol, and \code{0}
\chapter{Concrete Objects Layer}
+\label{concrete}
The functions in this chapter are specific to certain Python object
types. Passing them an object of the wrong type is not a good idea;
\section{Fundamental Objects}
+\label{fundamental}
This section describes Python type objects and the singleton object
\code{None}.
\subsection{Type Objects}
+\label{typeObjects}
\begin{ctypedesc}{PyTypeObject}
\subsection{The None Object}
+\label{noneObject}
\begin{cvardesc}{PyObject *}{Py_None}
XXX macro
\section{Sequence Objects}
+\label{sequenceObjects}
Generic operations on sequence objects were discussed in the previous
chapter; this section deals with the specific kinds of sequence
\subsection{String Objects}
+\label{stringObjects}
\begin{ctypedesc}{PyStringObject}
This subtype of \code{PyObject} represents a Python string object.
\subsection{Tuple Objects}
+\label{tupleObjects}
\begin{ctypedesc}{PyTupleObject}
This subtype of \code{PyObject} represents a Python tuple object.
\subsection{List Objects}
+\label{listObjects}
\begin{ctypedesc}{PyListObject}
This subtype of \code{PyObject} represents a Python list object.
\section{Mapping Objects}
+\label{mapObjects}
\subsection{Dictionary Objects}
+\label{dictObjects}
\begin{ctypedesc}{PyDictObject}
This subtype of \code{PyObject} represents a Python dictionary object.
\section{Numeric Objects}
+\label{numericObjects}
\subsection{Plain Integer Objects}
+\label{intObjects}
\begin{ctypedesc}{PyIntObject}
This subtype of \code{PyObject} represents a Python integer object.
\subsection{Long Integer Objects}
+\label{longObjects}
\begin{ctypedesc}{PyLongObject}
This subtype of \code{PyObject} represents a Python long integer
\subsection{Floating Point Objects}
+\label{floatObjects}
\begin{ctypedesc}{PyFloatObject}
This subtype of \code{PyObject} represents a Python floating point
\subsection{Complex Number Objects}
+\label{complexObjects}
\begin{ctypedesc}{Py_complex}
The \C{} structure which corresponds to the value portion of a Python
\section{Other Objects}
+\label{otherObjects}
\subsection{File Objects}
+\label{fileObjects}
\begin{ctypedesc}{PyFileObject}
This subtype of \code{PyObject} represents a Python file object.
\subsection{CObjects}
+\label{cObjects}
XXX
\chapter{Initialization, Finalization, and Threads}
+\label{initialization}
\begin{cfuncdesc}{void}{Py_Initialize}{}
Initialize the Python interpreter. In an application embedding
% XXX Other PySys thingies (doesn't really belong in this chapter)
\section{Thread State and the Global Interpreter Lock}
+\label{threads}
The Python interpreter is not fully thread safe. In order to support
multi-threaded Python programs, there's a global lock that must be
\chapter{Defining New Object Types}
+\label{newTypes}
\begin{cfuncdesc}{PyObject *}{_PyObject_New}{PyTypeObject *type}
\end{cfuncdesc}
\chapter{Debugging}
+\label{debugging}
XXX Explain Py_DEBUG, Py_TRACE_REFS, Py_REF_DEBUG.
% XXX a *really* short intro only.
\chapter{Introduction}
+\label{intro}
The Application Programmer's Interface to Python gives \C{} and \Cpp{}
programmers access to the Python interpreter at a variety of levels.
attempting to embed Python in a real application.
\section{Include Files}
+\label{includes}
All function, type and macro definitions needed to use the Python/C
API are included in your code by the following line:
these prefixes.
\section{Objects, Types and Reference Counts}
+\label{objects}
Most Python/C API functions have one or more arguments as well as a
return value of type \code{PyObject *}. This type is a pointer
true iff the object pointed to by \var{a} is a Python list.
\subsection{Reference Counts}
+\label{refcounts}
The reference count is important because today's computers have a
finite (and often severly limited) memory size; it counts how many
when they are done with the result; this soon becomes second nature.
\subsubsection{Reference Count Details}
+\label{refcountDetails}
The reference count behavior of functions in the Python/C API is best
expelained in terms of \emph{ownership of references}. Note that we
\end{verbatim}
\subsection{Types}
+\label{types}
There are few other data types that play a significant role in
the Python/C API; most are simple \C{} types such as \code{int},
be discussed together with the functions that use them.
\section{Exceptions}
+\label{exceptions}
The Python programmer only needs to deal with exceptions if specific
error handling is required; unhandled exceptions are automatically
\section{Embedding Python}
+\label{embedding}
The one important task that only embedders (as opposed to extension
writers) of the Python interpreter have to worry about is the
\chapter{The Very High Level Layer}
+\label{veryhigh}
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
\chapter{Reference Counting}
+\label{countingRefs}
The macros in this section are used for managing reference counts
of Python objects.
\chapter{Exception Handling}
+\label{exceptionHandling}
The functions in this chapter will let you handle and raise Python
exceptions. It is important to understand some of the basics of
\section{Standard Exceptions}
+\label{standardExceptions}
All standard Python exceptions are available as global variables whose
names are \samp{PyExc_} followed by the Python exception name.
\chapter{Utilities}
+\label{utilities}
The functions in this chapter perform various utility tasks, such as
parsing function arguments and constructing Python values from \C{}
values.
\section{OS Utilities}
+\label{os}
\begin{cfuncdesc}{int}{Py_FdIsInteractive}{FILE *fp, char *filename}
Return true (nonzero) if the standard I/O file \var{fp} with name
\section{Process Control}
+\label{processControl}
\begin{cfuncdesc}{void}{Py_FatalError}{char *message}
Print a fatal error message and kill the process. No cleanup is
\section{Importing Modules}
+\label{importing}
\begin{cfuncdesc}{PyObject *}{PyImport_ImportModule}{char *name}
This is a simplified interface to \cfunction{PyImport_ImportModuleEx()}
\chapter{Abstract Objects Layer}
+\label{abstract}
The functions in this chapter interact with Python objects regardless
of their type, or with wide classes of object types (e.g. all
for which they do not apply, they will flag a Python exception.
\section{Object Protocol}
+\label{object}
\begin{cfuncdesc}{int}{PyObject_Print}{PyObject *o, FILE *fp, int flags}
Print an object \var{o}, on file \var{fp}. Returns \code{-1} on error
\section{Number Protocol}
+\label{number}
\begin{cfuncdesc}{int}{PyNumber_Check}{PyObject *o}
Returns \code{1} if the object \var{o} provides numeric protocols, and
\section{Sequence Protocol}
+\label{sequence}
\begin{cfuncdesc}{int}{PySequence_Check}{PyObject *o}
Return \code{1} if the object provides sequence protocol, and \code{0}
the Python expression \samp{\var{o}.index(\var{value})}.
\end{cfuncdesc}
+
\section{Mapping Protocol}
+\label{mapping}
\begin{cfuncdesc}{int}{PyMapping_Check}{PyObject *o}
Return \code{1} if the object provides mapping protocol, and \code{0}
\chapter{Concrete Objects Layer}
+\label{concrete}
The functions in this chapter are specific to certain Python object
types. Passing them an object of the wrong type is not a good idea;
\section{Fundamental Objects}
+\label{fundamental}
This section describes Python type objects and the singleton object
\code{None}.
\subsection{Type Objects}
+\label{typeObjects}
\begin{ctypedesc}{PyTypeObject}
\subsection{The None Object}
+\label{noneObject}
\begin{cvardesc}{PyObject *}{Py_None}
XXX macro
\section{Sequence Objects}
+\label{sequenceObjects}
Generic operations on sequence objects were discussed in the previous
chapter; this section deals with the specific kinds of sequence
\subsection{String Objects}
+\label{stringObjects}
\begin{ctypedesc}{PyStringObject}
This subtype of \code{PyObject} represents a Python string object.
\subsection{Tuple Objects}
+\label{tupleObjects}
\begin{ctypedesc}{PyTupleObject}
This subtype of \code{PyObject} represents a Python tuple object.
\subsection{List Objects}
+\label{listObjects}
\begin{ctypedesc}{PyListObject}
This subtype of \code{PyObject} represents a Python list object.
\section{Mapping Objects}
+\label{mapObjects}
\subsection{Dictionary Objects}
+\label{dictObjects}
\begin{ctypedesc}{PyDictObject}
This subtype of \code{PyObject} represents a Python dictionary object.
\section{Numeric Objects}
+\label{numericObjects}
\subsection{Plain Integer Objects}
+\label{intObjects}
\begin{ctypedesc}{PyIntObject}
This subtype of \code{PyObject} represents a Python integer object.
\subsection{Long Integer Objects}
+\label{longObjects}
\begin{ctypedesc}{PyLongObject}
This subtype of \code{PyObject} represents a Python long integer
\subsection{Floating Point Objects}
+\label{floatObjects}
\begin{ctypedesc}{PyFloatObject}
This subtype of \code{PyObject} represents a Python floating point
\subsection{Complex Number Objects}
+\label{complexObjects}
\begin{ctypedesc}{Py_complex}
The \C{} structure which corresponds to the value portion of a Python
\section{Other Objects}
+\label{otherObjects}
\subsection{File Objects}
+\label{fileObjects}
\begin{ctypedesc}{PyFileObject}
This subtype of \code{PyObject} represents a Python file object.
\subsection{CObjects}
+\label{cObjects}
XXX
\chapter{Initialization, Finalization, and Threads}
+\label{initialization}
\begin{cfuncdesc}{void}{Py_Initialize}{}
Initialize the Python interpreter. In an application embedding
% XXX Other PySys thingies (doesn't really belong in this chapter)
\section{Thread State and the Global Interpreter Lock}
+\label{threads}
The Python interpreter is not fully thread safe. In order to support
multi-threaded Python programs, there's a global lock that must be
\chapter{Defining New Object Types}
+\label{newTypes}
\begin{cfuncdesc}{PyObject *}{_PyObject_New}{PyTypeObject *type}
\end{cfuncdesc}
\chapter{Debugging}
+\label{debugging}
XXX Explain Py_DEBUG, Py_TRACE_REFS, Py_REF_DEBUG.
projects / python / commitdiff