Typo: PyArgs_ParseTuple --> PyArg_ParseTuple

Moved the PyArg_Parse*(), Py_BuildValue() functions to the Utilities
chapter, added a minimal description and reference to the Extending
manual for Py_BuildValue().

1 files changed, 62 insertions, 30 deletions

diff --git a/Doc/api/api.tex b/Doc/api/api.tex
index 1b8f25d..5d2820e 100644
--- a/Doc/api/api.tex
+++ b/Doc/api/api.tex
@@ -1131,9 +1131,11 @@ release.
 
 \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.
+The functions in this chapter perform various utility tasks, ranging
+from helping C code be more portable across platforms, using Python
+modules from C, and parsing function arguments and constructing Python
+values from C values.
+
 
 \section{Operating System Utilities \label{os}}
 
@@ -1396,6 +1398,58 @@ internal table.  This should be called before
 \end{cfuncdesc}
 
 
+\section{Parsing arguements and building values
+         \label{arg-parsing}}
+
+These functions are useful when creating your own extensions functions
+and methods.  Additional information and examples are available in
+\citetitle[../ext/ext.html]{Extending and Embedding the Python
+Interpreter}.
+
+\begin{cfuncdesc}{int}{PyArg_ParseTuple}{PyObject *args, char *format,
+                                         \moreargs}
+  Parse the parameters of a function that takes only positional
+  parameters into local variables.  Returns true on success; on
+  failure, it returns false and raises the appropriate exception.  See
+  \citetitle[../ext/parseTuple.html]{Extending and Embedding the
+  Python Interpreter} for more information.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyArg_ParseTupleAndKeywords}{PyObject *args,
+                       PyObject *kw, char *format, char *keywords[],
+                       \moreargs}
+  Parse the parameters of a function that takes both positional and
+  keyword parameters into local variables.  Returns true on success;
+  on failure, it returns false and raises the appropriate exception.
+  See \citetitle[../ext/parseTupleAndKeywords.html]{Extending and
+  Embedding the Python Interpreter} for more information.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyArg_Parse}{PyObject *args, char *format,
+                                    \moreargs}
+  Function used to deconstruct the argument lists of ``old-style''
+  functions --- these are functions which use the
+  \constant{METH_OLDARGS} parameter parsing method.  This is not
+  recommended for use in parameter parsing in new code, and most code
+  in the standard interpreter has been modified to no longer use this
+  for that purpose.  It does remain a convenient way to decompose
+  other tuples, however, and may continue to be used for that
+  purpose.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{Py_BuildValue}{char *format,
+                                            \moreargs}
+  Create a new value based on a format string similar to those
+  accepted by the \cfunction{PyArg_Parse*()} family of functions and a
+  sequence of values.  Returns the value or \NULL{} in the case of an
+  error; an exception will be raised if \NULL{} is returned.  For more
+  information on the format string and additional parameters, see
+  \citetitle[../ext/buildValue.html]{Extending and Embedding the
+  Python Interpreter}.
+\end{cfuncdesc}
+
+
+
 \chapter{Abstract Objects Layer \label{abstract}}
 
 The functions in this chapter interact with Python objects regardless
@@ -3353,7 +3407,7 @@ that array elements may be multi-byte values.
 An example user of the buffer interface is the file object's
 \method{write()} method. Any object that can export a series of bytes
 through the buffer interface can be written to a file. There are a
-number of format codes to \cfunction{PyArgs_ParseTuple()} that operate 
+number of format codes to \cfunction{PyArg_ParseTuple()} that operate 
 against an object's buffer interface, returning data from the target
 object.
 
@@ -4939,6 +4993,10 @@ implementing new object types in C.
 
 \chapter{Defining New Object Types \label{newTypes}}
 
+
+\section{Allocating Objects on the Heap
+         \label{allocating-objects}}
+
 \begin{cfuncdesc}{PyObject*}{_PyObject_New}{PyTypeObject *type}
 \end{cfuncdesc}
 
@@ -5042,32 +5100,6 @@ implementing new object types in C.
   sure you need it.
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{int}{PyArg_ParseTuple}{PyObject *args, char *format,
-                                         \moreargs}
-  Parse the parameters of a function that takes only positional
-  parameters into local variables.  See
-  \citetitle[../ext/parseTuple.html]{Extending and Embedding the
-  Python Interpreter} for more information.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyArg_ParseTupleAndKeywords}{PyObject *args,
-                    PyObject *kw, char *format, char *keywords[], \moreargs}
-  Parse the parameters of a function that takes both positional and
-  keyword parameters into local variables.  See
-  \citetitle[../ext/parseTupleAndKeywords.html]{Extending and
-  Embedding the Python Interpreter} for more information.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyArg_Parse}{PyObject *args, char *format, \moreargs}
-  Function used to deconstruct the argument lists of ``old-style''
-  functions --- these are functions which use the
-  \constant{METH_OLDARGS} parameter parsing method.  This is not
-  recommended for new code, and most code in the standard interpreter
-  has been modified to no longer use this.
-\end{cfuncdesc}
-
-Py_BuildValue
-
 DL_IMPORT
 
 \begin{cvardesc}{PyObject}{_Py_NoneStruct}