<!DOCTYPE html PUBLIC
"-//W3C//DTD HTML 4.0 Transitional//EN">
<link rel=
"STYLESHEET" href=
"ext.css" type='text/css'
/>
<link rel=
"SHORTCUT ICON" href=
"../icons/pyfav.png" type=
"image/png" />
<link rel='start' href='../index.html' title='Python Documentation Index'
/>
<link rel=
"first" href=
"ext.html" title='Extending and Embedding the Python Interpreter'
/>
<link rel='contents' href='contents.html'
title=
"Contents" />
<link rel='last' href='about.html' title='About this document...'
/>
<link rel='help' href='about.html' title='About this document...'
/>
<link rel=
"next" href=
"buildValue.html" />
<link rel=
"prev" href=
"parseTuple.html" />
<link rel=
"parent" href=
"intro.html" />
<link rel=
"next" href=
"buildValue.html" />
<meta name='aesop' content='information'
/>
<title>1.8 Keyword Parameters for Extension Functions
<div id='top-navigation-panel' xml:id='top-navigation-panel'
>
<table align=
"center" width=
"100%" cellpadding=
"0" cellspacing=
"2">
<td class='online-navigation'
><a rel=
"prev" title=
"1.7 Extracting Parameters in"
href=
"parseTuple.html"><img src='../icons/previous.png'
border='
0' height='
32' alt='Previous Page' width='
32'
/></A></td>
<td class='online-navigation'
><a rel=
"parent" title=
"1. Extending Python with"
href=
"intro.html"><img src='../icons/up.png'
border='
0' height='
32' alt='Up One Level' width='
32'
/></A></td>
<td class='online-navigation'
><a rel=
"next" title=
"1.9 Building Arbitrary Values"
href=
"buildValue.html"><img src='../icons/next.png'
border='
0' height='
32' alt='Next Page' width='
32'
/></A></td>
<td align=
"center" width=
"100%">Extending and Embedding the Python Interpreter
</td>
<td class='online-navigation'
><a rel=
"contents" title=
"Table of Contents"
href=
"contents.html"><img src='../icons/contents.png'
border='
0' height='
32' alt='Contents' width='
32'
/></A></td>
<td class='online-navigation'
><img src='../icons/blank.png'
border='
0' height='
32' alt='' width='
32'
/></td>
<td class='online-navigation'
><img src='../icons/blank.png'
border='
0' height='
32' alt='' width='
32'
/></td>
<div class='online-navigation'
>
<b class=
"navlabel">Previous:
</b>
<a class=
"sectref" rel=
"prev" href=
"parseTuple.html">1.7 Extracting Parameters in
</A>
<b class=
"navlabel">Up:
</b>
<a class=
"sectref" rel=
"parent" href=
"intro.html">1. Extending Python with
</A>
<b class=
"navlabel">Next:
</b>
<a class=
"sectref" rel=
"next" href=
"buildValue.html">1.9 Building Arbitrary Values
</A>
<!--End of Navigation Panel-->
<H1><A NAME=
"SECTION003800000000000000000"></A><A NAME=
"parseTupleAndKeywords"></A><a id='l2h-
3' xml:id='l2h-
3'
></a>
1.8 Keyword Parameters for Extension Functions
<a id='l2h-
4' xml:id='l2h-
4'
></a>
The
<tt class=
"cfunction">PyArg_ParseTupleAndKeywords()
</tt> function is declared as
<div class=
"verbatim"><pre>
int PyArg_ParseTupleAndKeywords(PyObject *arg, PyObject *kwdict,
char *format, char *kwlist[], ...);
The
<var>arg
</var> and
<var>format
</var> parameters are identical to those of the
<tt class=
"cfunction">PyArg_ParseTuple()
</tt> function. The
<var>kwdict
</var> parameter
is the dictionary of keywords received as the third parameter from the
Python runtime. The
<var>kwlist
</var> parameter is a
<tt class=
"constant">NULL
</tt>-terminated
list of strings which identify the parameters; the names are matched
with the type information from
<var>format
</var> from left to right. On
success,
<tt class=
"cfunction">PyArg_ParseTupleAndKeywords()
</tt> returns true,
otherwise it returns false and raises an appropriate exception.
<span class=
"note"><b class=
"label">Note:
</b>
Nested tuples cannot be parsed when using keyword
arguments! Keyword parameters passed in which are not present in the
<var>kwlist
</var> will cause
<tt class=
"exception">TypeError
</tt> to be raised.
</span>
Here is an example module which uses keywords, based on an example by
Geoff Philbrick (
<span class=
"email">philbrick@hks.com
</span>):
<div class=
"verbatim"><pre>
keywdarg_parrot(PyObject *self, PyObject *args, PyObject *keywds)
char *type =
"Norwegian Blue";
static char *kwlist[] = {
"voltage",
"state",
"action",
"type", NULL};
if (!PyArg_ParseTupleAndKeywords(args, keywds,
"i|sss", kwlist,
&voltage,
&state,
&action,
&type))
printf(
"-- This parrot wouldn't %s if you put %i Volts through it.\n",
printf(
"-- Lovely plumage, the %s -- It's %s!\n", type, state);
static PyMethodDef keywdarg_methods[] = {
/* The cast of the function is necessary since PyCFunction values
* only take two PyObject* parameters, and keywdarg_parrot() takes
{
"parrot", (PyCFunction)keywdarg_parrot, METH_VARARGS | METH_KEYWORDS,
"Print a lovely skit to standard output."},
{NULL, NULL,
0, NULL} /* sentinel */
<div class=
"verbatim"><pre>
/* Create the module and add the functions */
Py_InitModule(
"keywdarg", keywdarg_methods);
<div class='online-navigation'
>
<table align=
"center" width=
"100%" cellpadding=
"0" cellspacing=
"2">
<td class='online-navigation'
><a rel=
"prev" title=
"1.7 Extracting Parameters in"
href=
"parseTuple.html"><img src='../icons/previous.png'
border='
0' height='
32' alt='Previous Page' width='
32'
/></A></td>
<td class='online-navigation'
><a rel=
"parent" title=
"1. Extending Python with"
href=
"intro.html"><img src='../icons/up.png'
border='
0' height='
32' alt='Up One Level' width='
32'
/></A></td>
<td class='online-navigation'
><a rel=
"next" title=
"1.9 Building Arbitrary Values"
href=
"buildValue.html"><img src='../icons/next.png'
border='
0' height='
32' alt='Next Page' width='
32'
/></A></td>
<td align=
"center" width=
"100%">Extending and Embedding the Python Interpreter
</td>
<td class='online-navigation'
><a rel=
"contents" title=
"Table of Contents"
href=
"contents.html"><img src='../icons/contents.png'
border='
0' height='
32' alt='Contents' width='
32'
/></A></td>
<td class='online-navigation'
><img src='../icons/blank.png'
border='
0' height='
32' alt='' width='
32'
/></td>
<td class='online-navigation'
><img src='../icons/blank.png'
border='
0' height='
32' alt='' width='
32'
/></td>
<div class='online-navigation'
>
<b class=
"navlabel">Previous:
</b>
<a class=
"sectref" rel=
"prev" href=
"parseTuple.html">1.7 Extracting Parameters in
</A>
<b class=
"navlabel">Up:
</b>
<a class=
"sectref" rel=
"parent" href=
"intro.html">1. Extending Python with
</A>
<b class=
"navlabel">Next:
</b>
<a class=
"sectref" rel=
"next" href=
"buildValue.html">1.9 Building Arbitrary Values
</A>
<span class=
"release-info">Release
2.4.2, documentation updated on
28 September
2005.
</span>
<!--End of Navigation Panel-->
See
<i><a href=
"about.html">About this document...
</a></i> for information on suggesting changes.