<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<!--Converted with LaTeX2HTML 98.2 beta6 (August 14th, 1998)
original version by:  Nikos Drakos, CBLU, University of Leeds
* revised and updated by:  Marcus Hennecke, Ross Moore, Herb Swan
* with significant contributions from:
  Jens Lippmann, Marek Rouchal, Martin Wilck and others -->
<HTML>
<HEAD>
<TITLE>1.7 Format Strings for PyArg_ParseTuple()
</TITLE>
<META NAME="description" CONTENT="1.7 Format Strings for PyArg_ParseTuple()
">
<META NAME="keywords" CONTENT="ext">
<META NAME="resource-type" CONTENT="document">
<META NAME="distribution" CONTENT="global">
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
<LINK REL="STYLESHEET" HREF="ext.css">
<LINK REL="next" HREF="parseTupleAndKeywords.html">
<LINK REL="previous" HREF="callingPython.html">
<LINK REL="up" HREF="intro.html">
<LINK REL="next" HREF="parseTupleAndKeywords.html">
</HEAD>
<BODY bgcolor="#ffffff">
<div class=navigation>
<table align=center width="100%" cellpadding=0 cellspacing=2>
<tr>
<td><A HREF="parseTupleAndKeywords.html"><img width=32 height=32 align=bottom border=0 alt="next"
 src="../icons/next.gif"></A></td>
<td><A HREF="intro.html"><img width=32 height=32 align=bottom border=0 alt="up"
 src="../icons/up.gif"></A></td>
<td><A HREF="callingPython.html"><img width=32 height=32 align=bottom border=0 alt="previous"
 src="../icons/previous.gif"></A></td>
<td align=center bgcolor="#99CCFF" width="100%">
 <b class=title>Extending and Embedding the Python Interpreter</b></td>
<td><A HREF="contents.html"><img width=32 height=32 align=bottom border=0 alt="contents"
 src="../icons/contents.gif"></A></td>
<td><img width=32 height=32 align=bottom border=0 alt=""
 src="../icons/blank.gif"></td>
<td><img width=32 height=32 align=bottom border=0 alt=""
 src="../icons/blank.gif"></td>
</tr></table><b class=navlabel>Next:</b> <span class=sectref><A HREF="parseTupleAndKeywords.html">1.8 Keyword Parsing with</A></span>
<b class=navlabel>Up:</b> <span class=sectref><A HREF="intro.html">1. Extending Python with</A></span>
<b class=navlabel>Previous:</b> <span class=sectref><A HREF="callingPython.html">1.6 Calling Python Functions</A></span>
<br><hr></div>
<!--End of Navigation Panel-->

<H1><A NAME="SECTION003700000000000000000"></A>
<BR>
1.7 Format Strings for <tt class=cfunction>PyArg_ParseTuple()</tt>
         
</H1>

<P>
The <tt class=cfunction>PyArg_ParseTuple()</tt> function is declared as follows:

<P>
<dl><dd><pre class=verbatim>
int PyArg_ParseTuple(PyObject *arg, char *format, ...);
</pre></dl>

<P>
The <var>arg</var> argument must be a tuple object containing an argument
list passed from Python to a C function.  The <var>format</var> argument
must be a format string, whose syntax is explained below.  The
remaining arguments must be addresses of variables whose type is
determined by the format string.  For the conversion to succeed, the
<var>arg</var> object must match the format and the format must be
exhausted.

<P>
Note that while <tt class=cfunction>PyArg_ParseTuple()</tt> checks that the Python
arguments have the required types, it cannot check the validity of the
addresses of C variables passed to the call: if you make mistakes
there, your code will probably crash or at least overwrite random bits
in memory.  So be careful!

<P>
A format string consists of zero or more ``format units''.  A format
unit describes one Python object; it is usually a single character or
a parenthesized sequence of format units.  With a few exceptions, a
format unit that is not a parenthesized sequence normally corresponds
to a single address argument to <tt class=cfunction>PyArg_ParseTuple()</tt>.  In the
following description, the quoted form is the format unit; the entry
in (round) parentheses is the Python object type that matches the
format unit; and the entry in [square] brackets is the type of the C
variable(s) whose address should be passed.  (Use the "<tt class=samp>&amp;</tt>"operator to pass a variable's address.)

<P>
<DL>
<DD><P>
<DT><STRONG>"<tt class=samp>s</tt>" (string) [char *]</STRONG>
<DD>Convert a Python string to a C pointer to a character string.  You
must not provide storage for the string itself; a pointer to an
existing string is stored into the character pointer variable whose
address you pass.  The C string is null-terminated.  The Python string
must not contain embedded null bytes; if it does, a <tt class=exception>TypeError</tt>
exception is raised.

<P>
<DT><STRONG>"<tt class=samp>s#</tt>" (string) [char *, int]</STRONG>
<DD>This variant on "<tt class=samp>s</tt>" stores into two C variables, the first one
a pointer to a character string, the second one its length.  In this
case the Python string may contain embedded null bytes.

<P>
<DT><STRONG>"<tt class=samp>z</tt>" (string or <tt>None</tt>) [char *]</STRONG>
<DD>Like "<tt class=samp>s</tt>", but the Python object may also be <tt>None</tt>, in which
case the C pointer is set to <tt>NULL</tt>.

<P>
<DT><STRONG>"<tt class=samp>z#</tt>" (string or <tt>None</tt>) [char *, int]</STRONG>
<DD>This is to "<tt class=samp>s#</tt>" as "<tt class=samp>z</tt>" is to "<tt class=samp>s</tt>".

<P>
<DT><STRONG>"<tt class=samp>b</tt>" (integer) [char]</STRONG>
<DD>Convert a Python integer to a tiny int, stored in a C <tt class=ctype>char</tt>.

<P>
<DT><STRONG>"<tt class=samp>h</tt>" (integer) [short int]</STRONG>
<DD>Convert a Python integer to a C <tt class=ctype>short int</tt>.

<P>
<DT><STRONG>"<tt class=samp>i</tt>" (integer) [int]</STRONG>
<DD>Convert a Python integer to a plain C <tt class=ctype>int</tt>.

<P>
<DT><STRONG>"<tt class=samp>l</tt>" (integer) [long int]</STRONG>
<DD>Convert a Python integer to a C <tt class=ctype>long int</tt>.

<P>
<DT><STRONG>"<tt class=samp>c</tt>" (string of length 1) [char]</STRONG>
<DD>Convert a Python character, represented as a string of length 1, to a
C <tt class=ctype>char</tt>.

<P>
<DT><STRONG>"<tt class=samp>f</tt>" (float) [float]</STRONG>
<DD>Convert a Python floating point number to a C <tt class=ctype>float</tt>.

<P>
<DT><STRONG>"<tt class=samp>d</tt>" (float) [double]</STRONG>
<DD>Convert a Python floating point number to a C <tt class=ctype>double</tt>.

<P>
<DT><STRONG>"<tt class=samp>D</tt>" (complex) [Py_complex]</STRONG>
<DD>Convert a Python complex number to a C <tt class=ctype>Py_complex</tt> structure.

<P>
<DT><STRONG>"<tt class=samp>O</tt>" (object) [PyObject *]</STRONG>
<DD>Store a Python object (without any conversion) in a C object pointer.
The C program thus receives the actual object that was passed.  The
object's reference count is not increased.  The pointer stored is not
<tt>NULL</tt>.

<P>
<DT><STRONG>"<tt class=samp>O!</tt>" (object) [<var>typeobject</var>, PyObject *]</STRONG>
<DD>Store a Python object in a C object pointer.  This is similar to
"<tt class=samp>O</tt>", but takes two C arguments: the first is the address of a
Python type object, the second is the address of the C variable (of
type <tt class=ctype>PyObject *</tt>) into which the object pointer is stored.
If the Python object does not have the required type, a
<tt class=exception>TypeError</tt> exception is raised.

<P>
<DT><STRONG>"<tt class=samp>O&amp;</tt>" (object) [<var>converter</var>, <var>anything</var>]</STRONG>
<DD>Convert a Python object to a C variable through a <var>converter</var>
function.  This takes two arguments: the first is a function, the
second is the address of a C variable (of arbitrary type), converted
to <tt class=ctype>void *</tt>.  The <var>converter</var> function in turn is called as
follows:

<P>
<tt><var>status</var> = <var>converter</var>(<var>object</var>, <var>address</var>);</tt>
<P>
where <var>object</var> is the Python object to be converted and
<var>address</var> is the <tt class=ctype>void *</tt> argument that was passed to
<tt class=cfunction>PyArg_ConvertTuple()</tt>.  The returned <var>status</var> should be
<tt>1</tt> for a successful conversion and <tt>0</tt> if the conversion
has failed.  When the conversion fails, the <var>converter</var> function
should raise an exception.

<P>
<DT><STRONG>"<tt class=samp>S</tt>" (string) [PyStringObject *]</STRONG>
<DD>Like "<tt class=samp>O</tt>" but requires that the Python object is a string object.
Raises a <tt class=exception>TypeError</tt> exception if the object is not a string
object.  The C variable may also be declared as <tt class=ctype>PyObject *</tt>.

<P>
<DT><STRONG>"<tt class=samp>(<var>items</var>)</tt>" (tuple) [<var>matching-items</var>]</STRONG>
<DD>The object must be a Python sequence whose length is the number of
format units in <var>items</var>.  The C arguments must correspond to the
individual format units in <var>items</var>.  Format units for sequences
may be nested.

<P>
<b>Note:</b> Prior to Python version 1.5.2, this format specifier
only accepted a tuple containing the individual parameters, not an
arbitrary sequence.  Code which previously caused a
<tt class=exception>TypeError</tt> to be raised here may now proceed without an
exception.  This is not expected to be a problem for existing code.

<P>
</DL>

<P>
It is possible to pass Python long integers where integers are
requested; however no proper range checking is done -- the most
significant bits are silently truncated when the receiving field is
too small to receive the value (actually, the semantics are inherited
from downcasts in C -- your mileage may vary).

<P>
A few other characters have a meaning in a format string.  These may
not occur inside nested parentheses.  They are:

<P>
<DL>
<DD><P>
<DT><STRONG>"<tt class=samp>|</tt>"</STRONG>
<DD>Indicates that the remaining arguments in the Python argument list are
optional.  The C variables corresponding to optional arguments should
be initialized to their default value -- when an optional argument is
not specified, <tt class=cfunction>PyArg_ParseTuple()</tt> does not touch the contents
of the corresponding C variable(s).

<P>
<DT><STRONG>"<tt class=samp>:</tt>"</STRONG>
<DD>The list of format units ends here; the string after the colon is used
as the function name in error messages (the ``associated value'' of
the exception that <tt class=cfunction>PyArg_ParseTuple()</tt> raises).

<P>
<DT><STRONG>"<tt class=samp>;</tt>"</STRONG>
<DD>The list of format units ends here; the string after the colon is used
as the error message <i>instead</i> of the default error message.
Clearly, "<tt class=samp>:</tt>" and "<tt class=samp>;</tt>" mutually exclude each other.

<P>
</DL>

<P>
Some example calls:

<P>
<dl><dd><pre class=verbatim>
    int ok;
    int i, j;
    long k, l;
    char *s;
    int size;

    ok = PyArg_ParseTuple(args, ""); /* No arguments */
        /* Python call: f() */
</pre></dl>

<P>
<dl><dd><pre class=verbatim>
    ok = PyArg_ParseTuple(args, "s", &amp;s); /* A string */
        /* Possible Python call: f('whoops!') */
</pre></dl>

<P>
<dl><dd><pre class=verbatim>
    ok = PyArg_ParseTuple(args, "lls", &amp;k, &amp;l, &amp;s); /* Two longs and a string */
        /* Possible Python call: f(1, 2, 'three') */
</pre></dl>

<P>
<dl><dd><pre class=verbatim>
    ok = PyArg_ParseTuple(args, "(ii)s#", &amp;i, &amp;j, &amp;s, &amp;size);
        /* A pair of ints and a string, whose size is also returned */
        /* Possible Python call: f((1, 2), 'three') */
</pre></dl>

<P>
<dl><dd><pre class=verbatim>
    {
        char *file;
        char *mode = "r";
        int bufsize = 0;
        ok = PyArg_ParseTuple(args, "s|si", &amp;file, &amp;mode, &amp;bufsize);
        /* A string, and optionally another string and an integer */
        /* Possible Python calls:
           f('spam')
           f('spam', 'w')
           f('spam', 'wb', 100000) */
    }
</pre></dl>

<P>
<dl><dd><pre class=verbatim>
    {
        int left, top, right, bottom, h, v;
        ok = PyArg_ParseTuple(args, "((ii)(ii))(ii)",
                 &amp;left, &amp;top, &amp;right, &amp;bottom, &amp;h, &amp;v);
        /* A rectangle and a point */
        /* Possible Python call:
           f(((0, 0), (400, 300)), (10, 10)) */
    }
</pre></dl>

<P>
<dl><dd><pre class=verbatim>
    {
        Py_complex c;
        ok = PyArg_ParseTuple(args, "D:myfunction", &amp;c);
        /* a complex, also providing a function name for errors */
        /* Possible Python call: myfunction(1+2j) */
    }
</pre></dl>

<P>
<p>
<div class=navigation><hr><table align=center width="100%" cellpadding=0 cellspacing=2>
<tr>
<td><A HREF="parseTupleAndKeywords.html"><img width=32 height=32 align=bottom border=0 alt="next"
 src="../icons/next.gif"></A></td>
<td><A HREF="intro.html"><img width=32 height=32 align=bottom border=0 alt="up"
 src="../icons/up.gif"></A></td>
<td><A HREF="callingPython.html"><img width=32 height=32 align=bottom border=0 alt="previous"
 src="../icons/previous.gif"></A></td>
<td align=center bgcolor="#99CCFF" width="100%">
 <b class=title>Extending and Embedding the Python Interpreter</b></td>
<td><A HREF="contents.html"><img width=32 height=32 align=bottom border=0 alt="contents"
 src="../icons/contents.gif"></A></td>
<td><img width=32 height=32 align=bottom border=0 alt=""
 src="../icons/blank.gif"></td>
<td><img width=32 height=32 align=bottom border=0 alt=""
 src="../icons/blank.gif"></td>
</tr></table><b class=navlabel>Next:</b> <span class=sectref><A HREF="parseTupleAndKeywords.html">1.8 Keyword Parsing with</A></span>
<b class=navlabel>Up:</b> <span class=sectref><A HREF="intro.html">1. Extending Python with</A></span>
<b class=navlabel>Previous:</b> <span class=sectref><A HREF="callingPython.html">1.6 Calling Python Functions</A></span>
</div>
<!--End of Navigation Panel-->
<ADDRESS>
<hr>Send comments on this document to <a href="mailto:python-docs@python.org">python-docs@python.org</a>.
</ADDRESS>
</BODY>
</HTML>
