Added description of "D" format for PyArg_ParseTuple(), including example

use with function name provided as well.

Wrapped up PyArg_ParseTupleAndKeywords() description and provided example
based on Geoff Philbrick's example to the mailing list.

2 files changed, 172 insertions, 6 deletions

diff --git a/Doc/ext.tex b/Doc/ext.tex
index 22f7ebc..a462792 100644
--- a/Doc/ext.tex
+++ b/Doc/ext.tex
@@ -356,14 +356,17 @@ function.  It should normally always be \samp{METH_VARARGS} or
 \samp{METH_VARARGS | METH_KEYWORDS}; a value of \samp{0} means that an
 obsolete variant of \code{PyArg_ParseTuple()} is used.
 
+When using only \samp{METH_VARARGS}, the function should expect
+the Python-level parameters to be passed in as a tuple acceptable for
+parsing via \cfunction{PyArg_ParseTuple()}; more information on this
+function is provided below.
+
 The \code{METH_KEYWORDS} bit may be set in the third field if keyword
 arguments should be passed to the function.  In this case, the \C{}
 function should accept a third \samp{PyObject *} parameter which will
 be a dictionary of keywords.  Use \code{PyArg_ParseTupleAndKeywords()} 
 to parse the arguemts to such a function.
 
-XXX --- need to explain PyArg_ParseTupleAndKeywords() in detail.
-
 The method table must be passed to the interpreter in the module's
 initialization function (which should be the only non-\code{static}
 item defined in the module file):
@@ -621,6 +624,9 @@ Convert a Python floating point number to a \C{} \code{float}.
 \item[\samp{d} (float) {[double]}]
 Convert a Python floating point number to a \C{} \code{double}.
 
+\item[\samp{D} (complex) {[Py_complex]}]
+Convert a Python complex number to a \C{} \code{Py_complex} structure.
+
 \item[\samp{O} (object) {[PyObject *]}]
 Store a Python object (without any conversion) in a \C{} object pointer.
 The \C{} program thus receives the actual object that was passed.  The
@@ -736,8 +742,85 @@ Some example calls:
                  /* Possible Python call:
                     f(((0, 0), (400, 300)), (10, 10)) */
     }
+
+    {
+        Py_complex c;
+        ok = PyArg_ParseTuple(args, "D:myfunction", &c);
+        /* a complex, also providing a function name for errors */
+        /* Possible Python call: myfunction(1+2j) */
+    }
 \end{verbatim}
-%
+
+
+\section{Keyword Parsing with \sectcode{PyArg_ParseTupleAndKeywords()}}
+
+The \cfunction{PyArg_ParseTupleAndKeywords()} function is declared as
+follows:
+
+\bcode\begin{verbatim}
+    int PyArg_ParseTupleAndKeywords(PyObject *arg, PyObject *kwdict,
+                                    char *format, char **kwlist, ...);
+\end{verbatim}\ecode
+
+The \var{arg} and \var{format} parameters are identical to those of the
+\cfunction{PyArg_ParseTuple()} function.  The \var{kwdict} parameter
+is the dictionary of keywords received as the third parameter from the 
+Python runtime.  The \var{kwlist} parameter is a \NULL{}-terminated
+list of strings which identify the parameters; the names are matched
+with the type information from \var{format} from left to right.
+
+\strong{Note:}  Nested tuples cannot be parsed when using keyword
+arguments!  Keyword parameters passed in which are not present in the
+\var{kwlist} will cause a \exception{TypeError} to be raised.
+
+Here is an example module which uses keywords, based on an example by
+Geoff Philbrick (\email{philbrick@hks.com}):
+
+\begin{verbatim}
+#include <stdio.h>
+#include "Python.h"
+
+static PyObject *
+keywdarg_parrot(self, args, keywds)
+    PyObject *self;
+    PyObject *args;
+    PyObject *keywds;
+{  
+    int voltage;
+    char *state = "a stiff";
+    char *action = "voom";
+    char *type = "Norwegian Blue";
+
+    static char *kwlist[] = {"voltage", "state", "action", "type", NULL};
+
+    if (!PyArg_ParseTupleAndKeywords(args, keywds, "i|sss", kwlist, 
+                                     &voltage, &state, &action, &type))
+        return NULL; 
+  
+    printf("-- This parrot wouldn't %s if you put %i Volts through it.\n", 
+           action, voltage);
+    printf("-- Lovely plumage, the %s -- It's %s!\n", type, state);
+
+    Py_INCREF(Py_None);
+
+    return Py_None;
+}
+
+static PyMethodDef keywdarg_methods[] = {
+    {"parrot", (PyCFunction)keywdarg_parrot, METH_VARARGS|METH_KEYWORDS},
+    {NULL,  NULL}   /* sentinel */
+};
+
+void
+initkeywdarg()
+{
+  /* Create the module and add the functions */
+  Py_InitModule("keywdarg", keywdarg_methods);  
+  
+}
+\end{verbatim}
+
+
 \section{The \sectcode{Py_BuildValue()} Function}
 
 This function is the counterpart to \code{PyArg_ParseTuple()}.  It is
diff --git a/Doc/ext/ext.tex b/Doc/ext/ext.tex
index 22f7ebc..a462792 100644
--- a/Doc/ext/ext.tex
+++ b/Doc/ext/ext.tex
@@ -356,14 +356,17 @@ function.  It should normally always be \samp{METH_VARARGS} or
 \samp{METH_VARARGS | METH_KEYWORDS}; a value of \samp{0} means that an
 obsolete variant of \code{PyArg_ParseTuple()} is used.
 
+When using only \samp{METH_VARARGS}, the function should expect
+the Python-level parameters to be passed in as a tuple acceptable for
+parsing via \cfunction{PyArg_ParseTuple()}; more information on this
+function is provided below.
+
 The \code{METH_KEYWORDS} bit may be set in the third field if keyword
 arguments should be passed to the function.  In this case, the \C{}
 function should accept a third \samp{PyObject *} parameter which will
 be a dictionary of keywords.  Use \code{PyArg_ParseTupleAndKeywords()} 
 to parse the arguemts to such a function.
 
-XXX --- need to explain PyArg_ParseTupleAndKeywords() in detail.
-
 The method table must be passed to the interpreter in the module's
 initialization function (which should be the only non-\code{static}
 item defined in the module file):
@@ -621,6 +624,9 @@ Convert a Python floating point number to a \C{} \code{float}.
 \item[\samp{d} (float) {[double]}]
 Convert a Python floating point number to a \C{} \code{double}.
 
+\item[\samp{D} (complex) {[Py_complex]}]
+Convert a Python complex number to a \C{} \code{Py_complex} structure.
+
 \item[\samp{O} (object) {[PyObject *]}]
 Store a Python object (without any conversion) in a \C{} object pointer.
 The \C{} program thus receives the actual object that was passed.  The
@@ -736,8 +742,85 @@ Some example calls:
                  /* Possible Python call:
                     f(((0, 0), (400, 300)), (10, 10)) */
     }
+
+    {
+        Py_complex c;
+        ok = PyArg_ParseTuple(args, "D:myfunction", &c);
+        /* a complex, also providing a function name for errors */
+        /* Possible Python call: myfunction(1+2j) */
+    }
 \end{verbatim}
-%
+
+
+\section{Keyword Parsing with \sectcode{PyArg_ParseTupleAndKeywords()}}
+
+The \cfunction{PyArg_ParseTupleAndKeywords()} function is declared as
+follows:
+
+\bcode\begin{verbatim}
+    int PyArg_ParseTupleAndKeywords(PyObject *arg, PyObject *kwdict,
+                                    char *format, char **kwlist, ...);
+\end{verbatim}\ecode
+
+The \var{arg} and \var{format} parameters are identical to those of the
+\cfunction{PyArg_ParseTuple()} function.  The \var{kwdict} parameter
+is the dictionary of keywords received as the third parameter from the 
+Python runtime.  The \var{kwlist} parameter is a \NULL{}-terminated
+list of strings which identify the parameters; the names are matched
+with the type information from \var{format} from left to right.
+
+\strong{Note:}  Nested tuples cannot be parsed when using keyword
+arguments!  Keyword parameters passed in which are not present in the
+\var{kwlist} will cause a \exception{TypeError} to be raised.
+
+Here is an example module which uses keywords, based on an example by
+Geoff Philbrick (\email{philbrick@hks.com}):
+
+\begin{verbatim}
+#include <stdio.h>
+#include "Python.h"
+
+static PyObject *
+keywdarg_parrot(self, args, keywds)
+    PyObject *self;
+    PyObject *args;
+    PyObject *keywds;
+{  
+    int voltage;
+    char *state = "a stiff";
+    char *action = "voom";
+    char *type = "Norwegian Blue";
+
+    static char *kwlist[] = {"voltage", "state", "action", "type", NULL};
+
+    if (!PyArg_ParseTupleAndKeywords(args, keywds, "i|sss", kwlist, 
+                                     &voltage, &state, &action, &type))
+        return NULL; 
+  
+    printf("-- This parrot wouldn't %s if you put %i Volts through it.\n", 
+           action, voltage);
+    printf("-- Lovely plumage, the %s -- It's %s!\n", type, state);
+
+    Py_INCREF(Py_None);
+
+    return Py_None;
+}
+
+static PyMethodDef keywdarg_methods[] = {
+    {"parrot", (PyCFunction)keywdarg_parrot, METH_VARARGS|METH_KEYWORDS},
+    {NULL,  NULL}   /* sentinel */
+};
+
+void
+initkeywdarg()
+{
+  /* Create the module and add the functions */
+  Py_InitModule("keywdarg", keywdarg_methods);  
+  
+}
+\end{verbatim}
+
+
 \section{The \sectcode{Py_BuildValue()} Function}
 
 This function is the counterpart to \code{PyArg_ParseTuple()}.  It is