Markup nits.
Added section on module objects; described functions in
moduleobject.c.
diff --git a/Doc/api/api.tex b/Doc/api/api.tex
index 1951a98..58c2f45 100644
--- a/Doc/api/api.tex
+++ b/Doc/api/api.tex
@@ -38,8 +38,7 @@
% XXX Consider moving all this back to ext.tex and giving api.tex
% XXX a *really* short intro only.
-\chapter{Introduction}
-\label{intro}
+\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.
@@ -68,8 +67,8 @@
good idea to become familiar with writing an extension before
attempting to embed Python in a real application.
-\section{Include Files}
-\label{includes}
+
+\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:
@@ -93,8 +92,8 @@
versions, which may define additional names beginning with one of
these prefixes.
-\section{Objects, Types and Reference Counts}
-\label{objects}
+
+\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 \ctype{PyObject *}. This type is a pointer
@@ -115,8 +114,8 @@
object is of that type; for instance, \samp{PyList_Check(\var{a})} is
true iff the object pointed to by \var{a} is a Python list.
-\subsection{Reference Counts}
-\label{refcounts}
+
+\subsection{Reference Counts \label{refcounts}}
The reference count is important because today's computers have a
finite (and often severely limited) memory size; it counts how many
@@ -176,8 +175,8 @@
the caller with the responsibility to call \cfunction{Py_DECREF()}
when they are done with the result; this soon becomes second nature.
-\subsubsection{Reference Count Details}
-\label{refcountDetails}
+
+\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
@@ -341,8 +340,8 @@
}
\end{verbatim}
-\subsection{Types}
-\label{types}
+
+\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 \ctype{int},
@@ -351,8 +350,8 @@
by a module or the data attributes of a new object type. These will
be discussed together with the functions that use them.
-\section{Exceptions}
-\label{exceptions}
+
+\section{Exceptions \label{exceptions}}
The Python programmer only needs to deal with exceptions if specific
error handling is required; unhandled exceptions are automatically
@@ -484,8 +483,7 @@
successful.
-\section{Embedding Python}
-\label{embedding}
+\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
@@ -547,8 +545,7 @@
a later chapter.
-\chapter{The Very High Level Layer}
-\label{veryhigh}
+\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
@@ -592,8 +589,7 @@
\end{cfuncdesc}
-\chapter{Reference Counting}
-\label{countingRefs}
+\chapter{Reference Counting \label{countingRefs}}
The macros in this section are used for managing reference counts
of Python objects.
@@ -645,8 +641,7 @@
PyMem_RESIZE(), PyMem_DEL(), PyMem_XDEL().
-\chapter{Exception Handling}
-\label{exceptionHandling}
+\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
@@ -836,8 +831,7 @@
\end{cfuncdesc}
-\section{Standard Exceptions}
-\label{standardExceptions}
+\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.
@@ -870,15 +864,13 @@
\cdata{PyExc_ZeroDivisionError}.
-\chapter{Utilities}
-\label{utilities}
+\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}
+\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
@@ -896,8 +888,7 @@
\end{cfuncdesc}
-\section{Process Control}
-\label{processControl}
+\section{Process Control \label{processControl}}
\begin{cfuncdesc}{void}{Py_FatalError}{char *message}
Print a fatal error message and kill the process. No cleanup is
@@ -928,8 +919,7 @@
\end{cfuncdesc}
-\section{Importing Modules}
-\label{importing}
+\section{Importing Modules \label{importing}}
\begin{cfuncdesc}{PyObject*}{PyImport_ImportModule}{char *name}
This is a simplified interface to \cfunction{PyImport_ImportModuleEx()}
@@ -1068,16 +1058,14 @@
\end{cvardesc}
-\chapter{Abstract Objects Layer}
-\label{abstract}
+\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
numerical types, or all sequence types). When used on object types
for which they do not apply, they will flag a Python exception.
-\section{Object Protocol}
-\label{object}
+\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
@@ -1275,8 +1263,7 @@
\end{cfuncdesc}
-\section{Number Protocol}
-\label{number}
+\section{Number Protocol \label{number}}
\begin{cfuncdesc}{int}{PyNumber_Check}{PyObject *o}
Returns \code{1} if the object \var{o} provides numeric protocols, and
@@ -1433,8 +1420,7 @@
\end{cfuncdesc}
-\section{Sequence Protocol}
-\label{sequence}
+\section{Sequence Protocol \label{sequence}}
\begin{cfuncdesc}{int}{PySequence_Check}{PyObject *o}
Return \code{1} if the object provides sequence protocol, and \code{0}
@@ -1520,8 +1506,7 @@
\end{cfuncdesc}
-\section{Mapping Protocol}
-\label{mapping}
+\section{Mapping Protocol \label{mapping}}
\begin{cfuncdesc}{int}{PyMapping_Check}{PyObject *o}
Return \code{1} if the object provides mapping protocol, and \code{0}
@@ -1672,8 +1657,7 @@
\end{cfuncdesc}
-\chapter{Concrete Objects Layer}
-\label{concrete}
+\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;
@@ -1684,27 +1668,25 @@
``family tree'' of Python object types.
-\section{Fundamental Objects}
-\label{fundamental}
+\section{Fundamental Objects \label{fundamental}}
This section describes Python type objects and the singleton object
\code{None}.
-\subsection{Type Objects}
-\label{typeObjects}
+\subsection{Type Objects \label{typeObjects}}
\begin{ctypedesc}{PyTypeObject}
\end{ctypedesc}
\begin{cvardesc}{PyObject *}{PyType_Type}
-
+This is the type object for type objects; it is the same object as
+\code{types.TypeType} in the Python layer.
\end{cvardesc}
-\subsection{The None Object}
-\label{noneObject}
+\subsection{The None Object \label{noneObject}}
\begin{cvardesc}{PyObject *}{Py_None}
The Python \code{None} object, denoting lack of value. This object has
@@ -1712,16 +1694,14 @@
\end{cvardesc}
-\section{Sequence Objects}
-\label{sequenceObjects}
+\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
objects that are intrinsic to the Python language.
-\subsection{String Objects}
-\label{stringObjects}
+\subsection{String Objects \label{stringObjects}}
\begin{ctypedesc}{PyStringObject}
This subtype of \ctype{PyObject} represents a Python string object.
@@ -1811,8 +1791,7 @@
-\subsection{Tuple Objects}
-\label{tupleObjects}
+\subsection{Tuple Objects \label{tupleObjects}}
\begin{ctypedesc}{PyTupleObject}
This subtype of \ctype{PyObject} represents a Python tuple object.
@@ -1881,8 +1860,7 @@
\end{cfuncdesc}
-\subsection{List Objects}
-\label{listObjects}
+\subsection{List Objects \label{listObjects}}
\begin{ctypedesc}{PyListObject}
This subtype of \ctype{PyObject} represents a Python list object.
@@ -1972,11 +1950,9 @@
\end{cfuncdesc}
-\section{Mapping Objects}
-\label{mapObjects}
+\section{Mapping Objects \label{mapObjects}}
-\subsection{Dictionary Objects}
-\label{dictObjects}
+\subsection{Dictionary Objects \label{dictObjects}}
\begin{ctypedesc}{PyDictObject}
This subtype of \ctype{PyObject} represents a Python dictionary object.
@@ -2066,11 +2042,9 @@
\end{cfuncdesc}
-\section{Numeric Objects}
-\label{numericObjects}
+\section{Numeric Objects \label{numericObjects}}
-\subsection{Plain Integer Objects}
-\label{intObjects}
+\subsection{Plain Integer Objects \label{intObjects}}
\begin{ctypedesc}{PyIntObject}
This subtype of \ctype{PyObject} represents a Python integer object.
@@ -2111,8 +2085,7 @@
\end{cfuncdesc}
-\subsection{Long Integer Objects}
-\label{longObjects}
+\subsection{Long Integer Objects \label{longObjects}}
\begin{ctypedesc}{PyLongObject}
This subtype of \ctype{PyObject} represents a Python long integer
@@ -2160,8 +2133,7 @@
\end{cfuncdesc}
-\subsection{Floating Point Objects}
-\label{floatObjects}
+\subsection{Floating Point Objects \label{floatObjects}}
\begin{ctypedesc}{PyFloatObject}
This subtype of \ctype{PyObject} represents a Python floating point
@@ -2191,8 +2163,7 @@
\end{cfuncdesc}
-\subsection{Complex Number Objects}
-\label{complexObjects}
+\subsection{Complex Number Objects \label{complexObjects}}
\begin{ctypedesc}{Py_complex}
The \C{} structure which corresponds to the value portion of a Python
@@ -2260,11 +2231,9 @@
-\section{Other Objects}
-\label{otherObjects}
+\section{Other Objects \label{otherObjects}}
-\subsection{File Objects}
-\label{fileObjects}
+\subsection{File Objects \label{fileObjects}}
\begin{ctypedesc}{PyFileObject}
This subtype of \ctype{PyObject} represents a Python file object.
@@ -2327,8 +2296,37 @@
\end{cfuncdesc}
-\subsection{CObjects}
-\label{cObjects}
+\subsection{Module Objects \label{moduleObjects}}
+
+\obindex{module}
+There are only a few functions special to module objects.
+
+\begin{cfuncdesc}{PyObject *}{PyModule_New}{char *name}
+Return a new module object with the \member{__name__} attribute set to
+\var{name}. Only the module's \member{__doc__} and \member{__name__}
+attributes are filled in; the caller is responsible for providing a
+\member{__file__} attribute.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject *}{PyModule_GetDict}{PyObject *module}
+Return the dictionary object that implements \var{module}'s namespace;
+this object is the same as the \member{__dict__} attribute of the
+module object. This function never fails.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{char *}{PyModule_GetName}{PyObject *module}
+Return \var{module}'s \member{__name__} value. If the module does not
+provide one, \exception{SystemError} is raised.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{char *}{PyModule_GetFilename}{PyObject *module}
+Return the name of the file from which \var{module} was loaded using
+\var{module}'s \member{__file__} attribute. If this is not defined,
+raise \exception{SystemError}.
+\end{cfuncdesc}
+
+
+\subsection{CObjects \label{cObjects}}
\begin{ctypedesc}{PyCObject}
This subtype of \ctype{PyObject} represents an opaque value, useful for
@@ -2363,8 +2361,8 @@
\var{self} was created with.
\end{cfuncdesc}
-\chapter{Initialization, Finalization, and Threads}
-\label{initialization}
+\chapter{Initialization, Finalization, and Threads
+ \label{initialization}}
\begin{cfuncdesc}{void}{Py_Initialize}{}
Initialize the Python interpreter. In an application embedding
@@ -2653,8 +2651,8 @@
% XXX Other PySys thingies (doesn't really belong in this chapter)
-\section{Thread State and the Global Interpreter Lock}
-\label{threads}
+\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
@@ -2965,8 +2963,7 @@
\end{cfuncdesc}
-\chapter{Defining New Object Types}
-\label{newTypes}
+\chapter{Defining New Object Types \label{newTypes}}
\begin{cfuncdesc}{PyObject*}{_PyObject_New}{PyTypeObject *type}
\end{cfuncdesc}
@@ -3016,8 +3013,7 @@
Py_None, _Py_NoneStruct
-\chapter{Debugging}
-\label{debugging}
+\chapter{Debugging \label{debugging}}
XXX Explain Py_DEBUG, Py_TRACE_REFS, Py_REF_DEBUG.