782 lines
88 KiB
HTML
782 lines
88 KiB
HTML
|
||
<!DOCTYPE html>
|
||
|
||
<html xmlns="http://www.w3.org/1999/xhtml">
|
||
<head>
|
||
<meta charset="utf-8" />
|
||
<title>Parsing arguments and building values — Python 3.7.4 documentation</title>
|
||
<link rel="stylesheet" href="../_static/pydoctheme.css" type="text/css" />
|
||
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
|
||
|
||
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
|
||
<script type="text/javascript" src="../_static/jquery.js"></script>
|
||
<script type="text/javascript" src="../_static/underscore.js"></script>
|
||
<script type="text/javascript" src="../_static/doctools.js"></script>
|
||
<script type="text/javascript" src="../_static/language_data.js"></script>
|
||
|
||
<script type="text/javascript" src="../_static/sidebar.js"></script>
|
||
|
||
<link rel="search" type="application/opensearchdescription+xml"
|
||
title="Search within Python 3.7.4 documentation"
|
||
href="../_static/opensearch.xml"/>
|
||
<link rel="author" title="About these documents" href="../about.html" />
|
||
<link rel="index" title="Index" href="../genindex.html" />
|
||
<link rel="search" title="Search" href="../search.html" />
|
||
<link rel="copyright" title="Copyright" href="../copyright.html" />
|
||
<link rel="next" title="String conversion and formatting" href="conversion.html" />
|
||
<link rel="prev" title="Data marshalling support" href="marshal.html" />
|
||
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
|
||
<link rel="canonical" href="https://docs.python.org/3/c-api/arg.html" />
|
||
|
||
<script type="text/javascript" src="../_static/copybutton.js"></script>
|
||
<script type="text/javascript" src="../_static/switchers.js"></script>
|
||
|
||
|
||
|
||
<style>
|
||
@media only screen {
|
||
table.full-width-table {
|
||
width: 100%;
|
||
}
|
||
}
|
||
</style>
|
||
|
||
|
||
</head><body>
|
||
|
||
<div class="related" role="navigation" aria-label="related navigation">
|
||
<h3>Navigation</h3>
|
||
<ul>
|
||
<li class="right" style="margin-right: 10px">
|
||
<a href="../genindex.html" title="General Index"
|
||
accesskey="I">index</a></li>
|
||
<li class="right" >
|
||
<a href="../py-modindex.html" title="Python Module Index"
|
||
>modules</a> |</li>
|
||
<li class="right" >
|
||
<a href="conversion.html" title="String conversion and formatting"
|
||
accesskey="N">next</a> |</li>
|
||
<li class="right" >
|
||
<a href="marshal.html" title="Data marshalling support"
|
||
accesskey="P">previous</a> |</li>
|
||
<li><img src="../_static/py.png" alt=""
|
||
style="vertical-align: middle; margin-top: -1px"/></li>
|
||
<li><a href="https://www.python.org/">Python</a> »</li>
|
||
<li>
|
||
<span class="language_switcher_placeholder">en</span>
|
||
<span class="version_switcher_placeholder">3.7.4</span>
|
||
<a href="../index.html">Documentation </a> »
|
||
</li>
|
||
|
||
<li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> »</li>
|
||
<li class="nav-item nav-item-2"><a href="utilities.html" accesskey="U">Utilities</a> »</li>
|
||
<li class="right">
|
||
|
||
|
||
<div class="inline-search" style="display: none" role="search">
|
||
<form class="inline-search" action="../search.html" method="get">
|
||
<input placeholder="Quick search" type="text" name="q" />
|
||
<input type="submit" value="Go" />
|
||
<input type="hidden" name="check_keywords" value="yes" />
|
||
<input type="hidden" name="area" value="default" />
|
||
</form>
|
||
</div>
|
||
<script type="text/javascript">$('.inline-search').show(0);</script>
|
||
|
|
||
</li>
|
||
|
||
</ul>
|
||
</div>
|
||
|
||
<div class="document">
|
||
<div class="documentwrapper">
|
||
<div class="bodywrapper">
|
||
<div class="body" role="main">
|
||
|
||
<div class="section" id="parsing-arguments-and-building-values">
|
||
<span id="arg-parsing"></span><h1>Parsing arguments and building values<a class="headerlink" href="#parsing-arguments-and-building-values" title="Permalink to this headline">¶</a></h1>
|
||
<p>These functions are useful when creating your own extensions functions and
|
||
methods. Additional information and examples are available in
|
||
<a class="reference internal" href="../extending/index.html#extending-index"><span class="std std-ref">Extending and Embedding the Python Interpreter</span></a>.</p>
|
||
<p>The first three of these functions described, <a class="reference internal" href="#c.PyArg_ParseTuple" title="PyArg_ParseTuple"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyArg_ParseTuple()</span></code></a>,
|
||
<a class="reference internal" href="#c.PyArg_ParseTupleAndKeywords" title="PyArg_ParseTupleAndKeywords"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyArg_ParseTupleAndKeywords()</span></code></a>, and <a class="reference internal" href="#c.PyArg_Parse" title="PyArg_Parse"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyArg_Parse()</span></code></a>, all use <em>format
|
||
strings</em> which are used to tell the function about the expected arguments. The
|
||
format strings use the same syntax for each of these functions.</p>
|
||
<div class="section" id="parsing-arguments">
|
||
<h2>Parsing arguments<a class="headerlink" href="#parsing-arguments" title="Permalink to this headline">¶</a></h2>
|
||
<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
|
||
these functions. 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.</p>
|
||
<div class="section" id="strings-and-buffers">
|
||
<h3>Strings and buffers<a class="headerlink" href="#strings-and-buffers" title="Permalink to this headline">¶</a></h3>
|
||
<p>These formats allow accessing an object as a contiguous chunk of memory.
|
||
You don’t have to provide raw storage for the returned unicode or bytes
|
||
area.</p>
|
||
<p>In general, when a format sets a pointer to a buffer, the buffer is
|
||
managed by the corresponding Python object, and the buffer shares
|
||
the lifetime of this object. You won’t have to release any memory yourself.
|
||
The only exceptions are <code class="docutils literal notranslate"><span class="pre">es</span></code>, <code class="docutils literal notranslate"><span class="pre">es#</span></code>, <code class="docutils literal notranslate"><span class="pre">et</span></code> and <code class="docutils literal notranslate"><span class="pre">et#</span></code>.</p>
|
||
<p>However, when a <a class="reference internal" href="buffer.html#c.Py_buffer" title="Py_buffer"><code class="xref c c-type docutils literal notranslate"><span class="pre">Py_buffer</span></code></a> structure gets filled, the underlying
|
||
buffer is locked so that the caller can subsequently use the buffer even
|
||
inside a <a class="reference internal" href="init.html#c.Py_BEGIN_ALLOW_THREADS" title="Py_BEGIN_ALLOW_THREADS"><code class="xref c c-type docutils literal notranslate"><span class="pre">Py_BEGIN_ALLOW_THREADS</span></code></a> block without the risk of mutable data
|
||
being resized or destroyed. As a result, <strong>you have to call</strong>
|
||
<a class="reference internal" href="buffer.html#c.PyBuffer_Release" title="PyBuffer_Release"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyBuffer_Release()</span></code></a> after you have finished processing the data (or
|
||
in any early abort case).</p>
|
||
<p>Unless otherwise stated, buffers are not NUL-terminated.</p>
|
||
<p>Some formats require a read-only <a class="reference internal" href="../glossary.html#term-bytes-like-object"><span class="xref std std-term">bytes-like object</span></a>, and set a
|
||
pointer instead of a buffer structure. They work by checking that
|
||
the object’s <a class="reference internal" href="typeobj.html#c.PyBufferProcs.bf_releasebuffer" title="PyBufferProcs.bf_releasebuffer"><code class="xref c c-member docutils literal notranslate"><span class="pre">PyBufferProcs.bf_releasebuffer</span></code></a> field is <em>NULL</em>,
|
||
which disallows mutable objects such as <a class="reference internal" href="../library/stdtypes.html#bytearray" title="bytearray"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytearray</span></code></a>.</p>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>For all <code class="docutils literal notranslate"><span class="pre">#</span></code> variants of formats (<code class="docutils literal notranslate"><span class="pre">s#</span></code>, <code class="docutils literal notranslate"><span class="pre">y#</span></code>, etc.), the type of
|
||
the length argument (int or <code class="xref c c-type docutils literal notranslate"><span class="pre">Py_ssize_t</span></code>) is controlled by
|
||
defining the macro <code class="xref c c-macro docutils literal notranslate"><span class="pre">PY_SSIZE_T_CLEAN</span></code> before including
|
||
<code class="file docutils literal notranslate"><span class="pre">Python.h</span></code>. If the macro was defined, length is a
|
||
<code class="xref c c-type docutils literal notranslate"><span class="pre">Py_ssize_t</span></code> rather than an <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span></code>. This behavior will change
|
||
in a future Python version to only support <code class="xref c c-type docutils literal notranslate"><span class="pre">Py_ssize_t</span></code> and
|
||
drop <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span></code> support. It is best to always define <code class="xref c c-macro docutils literal notranslate"><span class="pre">PY_SSIZE_T_CLEAN</span></code>.</p>
|
||
</div>
|
||
<dl>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">s</span></code> (<a class="reference internal" href="../library/stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a>) [const char *]</dt><dd><p>Convert a Unicode object to a C pointer to a character string.
|
||
A pointer to an existing string is stored in the character pointer
|
||
variable whose address you pass. The C string is NUL-terminated.
|
||
The Python string must not contain embedded null code points; if it does,
|
||
a <a class="reference internal" href="../library/exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ValueError</span></code></a> exception is raised. Unicode objects are converted
|
||
to C strings using <code class="docutils literal notranslate"><span class="pre">'utf-8'</span></code> encoding. If this conversion fails, a
|
||
<a class="reference internal" href="../library/exceptions.html#UnicodeError" title="UnicodeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">UnicodeError</span></code></a> is raised.</p>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>This format does not accept <a class="reference internal" href="../glossary.html#term-bytes-like-object"><span class="xref std std-term">bytes-like objects</span></a>. If you want to accept
|
||
filesystem paths and convert them to C character strings, it is
|
||
preferable to use the <code class="docutils literal notranslate"><span class="pre">O&</span></code> format with <a class="reference internal" href="unicode.html#c.PyUnicode_FSConverter" title="PyUnicode_FSConverter"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyUnicode_FSConverter()</span></code></a>
|
||
as <em>converter</em>.</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.5: </span>Previously, <a class="reference internal" href="../library/exceptions.html#TypeError" title="TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a> was raised when embedded null code points
|
||
were encountered in the Python string.</p>
|
||
</div>
|
||
</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">s*</span></code> (<a class="reference internal" href="../library/stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a> or <a class="reference internal" href="../glossary.html#term-bytes-like-object"><span class="xref std std-term">bytes-like object</span></a>) [Py_buffer]</dt><dd><p>This format accepts Unicode objects as well as bytes-like objects.
|
||
It fills a <a class="reference internal" href="buffer.html#c.Py_buffer" title="Py_buffer"><code class="xref c c-type docutils literal notranslate"><span class="pre">Py_buffer</span></code></a> structure provided by the caller.
|
||
In this case the resulting C string may contain embedded NUL bytes.
|
||
Unicode objects are converted to C strings using <code class="docutils literal notranslate"><span class="pre">'utf-8'</span></code> encoding.</p>
|
||
</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">s#</span></code> (<a class="reference internal" href="../library/stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a>, read-only <a class="reference internal" href="../glossary.html#term-bytes-like-object"><span class="xref std std-term">bytes-like object</span></a>) [const char *, int or <code class="xref c c-type docutils literal notranslate"><span class="pre">Py_ssize_t</span></code>]</dt><dd><p>Like <code class="docutils literal notranslate"><span class="pre">s*</span></code>, except that it doesn’t accept mutable objects.
|
||
The result is stored into two C variables,
|
||
the first one a pointer to a C string, the second one its length.
|
||
The string may contain embedded null bytes. Unicode objects are converted
|
||
to C strings using <code class="docutils literal notranslate"><span class="pre">'utf-8'</span></code> encoding.</p>
|
||
</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">z</span></code> (<a class="reference internal" href="../library/stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a> or <code class="docutils literal notranslate"><span class="pre">None</span></code>) [const char *]</dt><dd><p>Like <code class="docutils literal notranslate"><span class="pre">s</span></code>, but the Python object may also be <code class="docutils literal notranslate"><span class="pre">None</span></code>, in which case the C
|
||
pointer is set to <em>NULL</em>.</p>
|
||
</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">z*</span></code> (<a class="reference internal" href="../library/stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a>, <a class="reference internal" href="../glossary.html#term-bytes-like-object"><span class="xref std std-term">bytes-like object</span></a> or <code class="docutils literal notranslate"><span class="pre">None</span></code>) [Py_buffer]</dt><dd><p>Like <code class="docutils literal notranslate"><span class="pre">s*</span></code>, but the Python object may also be <code class="docutils literal notranslate"><span class="pre">None</span></code>, in which case the
|
||
<code class="docutils literal notranslate"><span class="pre">buf</span></code> member of the <a class="reference internal" href="buffer.html#c.Py_buffer" title="Py_buffer"><code class="xref c c-type docutils literal notranslate"><span class="pre">Py_buffer</span></code></a> structure is set to <em>NULL</em>.</p>
|
||
</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">z#</span></code> (<a class="reference internal" href="../library/stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a>, read-only <a class="reference internal" href="../glossary.html#term-bytes-like-object"><span class="xref std std-term">bytes-like object</span></a> or <code class="docutils literal notranslate"><span class="pre">None</span></code>) [const char *, int]</dt><dd><p>Like <code class="docutils literal notranslate"><span class="pre">s#</span></code>, but the Python object may also be <code class="docutils literal notranslate"><span class="pre">None</span></code>, in which case the C
|
||
pointer is set to <em>NULL</em>.</p>
|
||
</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">y</span></code> (read-only <a class="reference internal" href="../glossary.html#term-bytes-like-object"><span class="xref std std-term">bytes-like object</span></a>) [const char *]</dt><dd><p>This format converts a bytes-like object to a C pointer to a character
|
||
string; it does not accept Unicode objects. The bytes buffer must not
|
||
contain embedded null bytes; if it does, a <a class="reference internal" href="../library/exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ValueError</span></code></a>
|
||
exception is raised.</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.5: </span>Previously, <a class="reference internal" href="../library/exceptions.html#TypeError" title="TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a> was raised when embedded null bytes were
|
||
encountered in the bytes buffer.</p>
|
||
</div>
|
||
</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">y*</span></code> (<a class="reference internal" href="../glossary.html#term-bytes-like-object"><span class="xref std std-term">bytes-like object</span></a>) [Py_buffer]</dt><dd><p>This variant on <code class="docutils literal notranslate"><span class="pre">s*</span></code> doesn’t accept Unicode objects, only
|
||
bytes-like objects. <strong>This is the recommended way to accept
|
||
binary data.</strong></p>
|
||
</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">y#</span></code> (read-only <a class="reference internal" href="../glossary.html#term-bytes-like-object"><span class="xref std std-term">bytes-like object</span></a>) [const char *, int]</dt><dd><p>This variant on <code class="docutils literal notranslate"><span class="pre">s#</span></code> doesn’t accept Unicode objects, only bytes-like
|
||
objects.</p>
|
||
</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">S</span></code> (<a class="reference internal" href="../library/stdtypes.html#bytes" title="bytes"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code></a>) [PyBytesObject *]</dt><dd><p>Requires that the Python object is a <a class="reference internal" href="../library/stdtypes.html#bytes" title="bytes"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code></a> object, without
|
||
attempting any conversion. Raises <a class="reference internal" href="../library/exceptions.html#TypeError" title="TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a> if the object is not
|
||
a bytes object. The C variable may also be declared as <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyObject*</span></code></a>.</p>
|
||
</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">Y</span></code> (<a class="reference internal" href="../library/stdtypes.html#bytearray" title="bytearray"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytearray</span></code></a>) [PyByteArrayObject *]</dt><dd><p>Requires that the Python object is a <a class="reference internal" href="../library/stdtypes.html#bytearray" title="bytearray"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytearray</span></code></a> object, without
|
||
attempting any conversion. Raises <a class="reference internal" href="../library/exceptions.html#TypeError" title="TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a> if the object is not
|
||
a <a class="reference internal" href="../library/stdtypes.html#bytearray" title="bytearray"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytearray</span></code></a> object. The C variable may also be declared as <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyObject*</span></code></a>.</p>
|
||
</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">u</span></code> (<a class="reference internal" href="../library/stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a>) [const Py_UNICODE *]</dt><dd><p>Convert a Python Unicode object to a C pointer to a NUL-terminated buffer of
|
||
Unicode characters. You must pass the address of a <a class="reference internal" href="unicode.html#c.Py_UNICODE" title="Py_UNICODE"><code class="xref c c-type docutils literal notranslate"><span class="pre">Py_UNICODE</span></code></a>
|
||
pointer variable, which will be filled with the pointer to an existing
|
||
Unicode buffer. Please note that the width of a <a class="reference internal" href="unicode.html#c.Py_UNICODE" title="Py_UNICODE"><code class="xref c c-type docutils literal notranslate"><span class="pre">Py_UNICODE</span></code></a>
|
||
character depends on compilation options (it is either 16 or 32 bits).
|
||
The Python string must not contain embedded null code points; if it does,
|
||
a <a class="reference internal" href="../library/exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ValueError</span></code></a> exception is raised.</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.5: </span>Previously, <a class="reference internal" href="../library/exceptions.html#TypeError" title="TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a> was raised when embedded null code points
|
||
were encountered in the Python string.</p>
|
||
</div>
|
||
<div class="deprecated">
|
||
<p><span class="versionmodified">Deprecated since version 3.3, will be removed in version 4.0: </span>Part of the old-style <a class="reference internal" href="unicode.html#c.Py_UNICODE" title="Py_UNICODE"><code class="xref c c-type docutils literal notranslate"><span class="pre">Py_UNICODE</span></code></a> API; please migrate to using
|
||
<a class="reference internal" href="unicode.html#c.PyUnicode_AsWideCharString" title="PyUnicode_AsWideCharString"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyUnicode_AsWideCharString()</span></code></a>.</p>
|
||
</div>
|
||
</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">u#</span></code> (<a class="reference internal" href="../library/stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a>) [const Py_UNICODE *, int]</dt><dd><p>This variant on <code class="docutils literal notranslate"><span class="pre">u</span></code> stores into two C variables, the first one a pointer to a
|
||
Unicode data buffer, the second one its length. This variant allows
|
||
null code points.</p>
|
||
<div class="deprecated">
|
||
<p><span class="versionmodified">Deprecated since version 3.3, will be removed in version 4.0: </span>Part of the old-style <a class="reference internal" href="unicode.html#c.Py_UNICODE" title="Py_UNICODE"><code class="xref c c-type docutils literal notranslate"><span class="pre">Py_UNICODE</span></code></a> API; please migrate to using
|
||
<a class="reference internal" href="unicode.html#c.PyUnicode_AsWideCharString" title="PyUnicode_AsWideCharString"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyUnicode_AsWideCharString()</span></code></a>.</p>
|
||
</div>
|
||
</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">Z</span></code> (<a class="reference internal" href="../library/stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a> or <code class="docutils literal notranslate"><span class="pre">None</span></code>) [const Py_UNICODE *]</dt><dd><p>Like <code class="docutils literal notranslate"><span class="pre">u</span></code>, but the Python object may also be <code class="docutils literal notranslate"><span class="pre">None</span></code>, in which case the
|
||
<a class="reference internal" href="unicode.html#c.Py_UNICODE" title="Py_UNICODE"><code class="xref c c-type docutils literal notranslate"><span class="pre">Py_UNICODE</span></code></a> pointer is set to <em>NULL</em>.</p>
|
||
<div class="deprecated">
|
||
<p><span class="versionmodified">Deprecated since version 3.3, will be removed in version 4.0: </span>Part of the old-style <a class="reference internal" href="unicode.html#c.Py_UNICODE" title="Py_UNICODE"><code class="xref c c-type docutils literal notranslate"><span class="pre">Py_UNICODE</span></code></a> API; please migrate to using
|
||
<a class="reference internal" href="unicode.html#c.PyUnicode_AsWideCharString" title="PyUnicode_AsWideCharString"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyUnicode_AsWideCharString()</span></code></a>.</p>
|
||
</div>
|
||
</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">Z#</span></code> (<a class="reference internal" href="../library/stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a> or <code class="docutils literal notranslate"><span class="pre">None</span></code>) [const Py_UNICODE *, int]</dt><dd><p>Like <code class="docutils literal notranslate"><span class="pre">u#</span></code>, but the Python object may also be <code class="docutils literal notranslate"><span class="pre">None</span></code>, in which case the
|
||
<a class="reference internal" href="unicode.html#c.Py_UNICODE" title="Py_UNICODE"><code class="xref c c-type docutils literal notranslate"><span class="pre">Py_UNICODE</span></code></a> pointer is set to <em>NULL</em>.</p>
|
||
<div class="deprecated">
|
||
<p><span class="versionmodified">Deprecated since version 3.3, will be removed in version 4.0: </span>Part of the old-style <a class="reference internal" href="unicode.html#c.Py_UNICODE" title="Py_UNICODE"><code class="xref c c-type docutils literal notranslate"><span class="pre">Py_UNICODE</span></code></a> API; please migrate to using
|
||
<a class="reference internal" href="unicode.html#c.PyUnicode_AsWideCharString" title="PyUnicode_AsWideCharString"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyUnicode_AsWideCharString()</span></code></a>.</p>
|
||
</div>
|
||
</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">U</span></code> (<a class="reference internal" href="../library/stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a>) [PyObject *]</dt><dd><p>Requires that the Python object is a Unicode object, without attempting
|
||
any conversion. Raises <a class="reference internal" href="../library/exceptions.html#TypeError" title="TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a> if the object is not a Unicode
|
||
object. The C variable may also be declared as <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyObject*</span></code></a>.</p>
|
||
</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">w*</span></code> (read-write <a class="reference internal" href="../glossary.html#term-bytes-like-object"><span class="xref std std-term">bytes-like object</span></a>) [Py_buffer]</dt><dd><p>This format accepts any object which implements the read-write buffer
|
||
interface. It fills a <a class="reference internal" href="buffer.html#c.Py_buffer" title="Py_buffer"><code class="xref c c-type docutils literal notranslate"><span class="pre">Py_buffer</span></code></a> structure provided by the caller.
|
||
The buffer may contain embedded null bytes. The caller have to call
|
||
<a class="reference internal" href="buffer.html#c.PyBuffer_Release" title="PyBuffer_Release"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyBuffer_Release()</span></code></a> when it is done with the buffer.</p>
|
||
</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">es</span></code> (<a class="reference internal" href="../library/stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a>) [const char *encoding, char **buffer]</dt><dd><p>This variant on <code class="docutils literal notranslate"><span class="pre">s</span></code> is used for encoding Unicode into a character buffer.
|
||
It only works for encoded data without embedded NUL bytes.</p>
|
||
<p>This format requires two arguments. The first is only used as input, and
|
||
must be a <code class="xref c c-type docutils literal notranslate"><span class="pre">const</span> <span class="pre">char*</span></code> which points to the name of an encoding as a
|
||
NUL-terminated string, or <em>NULL</em>, in which case <code class="docutils literal notranslate"><span class="pre">'utf-8'</span></code> encoding is used.
|
||
An exception is raised if the named encoding is not known to Python. The
|
||
second argument must be a <code class="xref c c-type docutils literal notranslate"><span class="pre">char**</span></code>; the value of the pointer it
|
||
references will be set to a buffer with the contents of the argument text.
|
||
The text will be encoded in the encoding specified by the first argument.</p>
|
||
<p><a class="reference internal" href="#c.PyArg_ParseTuple" title="PyArg_ParseTuple"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyArg_ParseTuple()</span></code></a> will allocate a buffer of the needed size, copy the
|
||
encoded data into this buffer and adjust <em>*buffer</em> to reference the newly
|
||
allocated storage. The caller is responsible for calling <a class="reference internal" href="memory.html#c.PyMem_Free" title="PyMem_Free"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyMem_Free()</span></code></a> to
|
||
free the allocated buffer after use.</p>
|
||
</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">et</span></code> (<a class="reference internal" href="../library/stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a>, <a class="reference internal" href="../library/stdtypes.html#bytes" title="bytes"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code></a> or <a class="reference internal" href="../library/stdtypes.html#bytearray" title="bytearray"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytearray</span></code></a>) [const char *encoding, char **buffer]</dt><dd><p>Same as <code class="docutils literal notranslate"><span class="pre">es</span></code> except that byte string objects are passed through without
|
||
recoding them. Instead, the implementation assumes that the byte string object uses
|
||
the encoding passed in as parameter.</p>
|
||
</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">es#</span></code> (<a class="reference internal" href="../library/stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a>) [const char *encoding, char **buffer, int *buffer_length]</dt><dd><p>This variant on <code class="docutils literal notranslate"><span class="pre">s#</span></code> is used for encoding Unicode into a character buffer.
|
||
Unlike the <code class="docutils literal notranslate"><span class="pre">es</span></code> format, this variant allows input data which contains NUL
|
||
characters.</p>
|
||
<p>It requires three arguments. The first is only used as input, and must be a
|
||
<code class="xref c c-type docutils literal notranslate"><span class="pre">const</span> <span class="pre">char*</span></code> which points to the name of an encoding as a
|
||
NUL-terminated string, or <em>NULL</em>, in which case <code class="docutils literal notranslate"><span class="pre">'utf-8'</span></code> encoding is used.
|
||
An exception is raised if the named encoding is not known to Python. The
|
||
second argument must be a <code class="xref c c-type docutils literal notranslate"><span class="pre">char**</span></code>; the value of the pointer it
|
||
references will be set to a buffer with the contents of the argument text.
|
||
The text will be encoded in the encoding specified by the first argument.
|
||
The third argument must be a pointer to an integer; the referenced integer
|
||
will be set to the number of bytes in the output buffer.</p>
|
||
<p>There are two modes of operation:</p>
|
||
<p>If <em>*buffer</em> points a <em>NULL</em> pointer, the function will allocate a buffer of
|
||
the needed size, copy the encoded data into this buffer and set <em>*buffer</em> to
|
||
reference the newly allocated storage. The caller is responsible for calling
|
||
<a class="reference internal" href="memory.html#c.PyMem_Free" title="PyMem_Free"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyMem_Free()</span></code></a> to free the allocated buffer after usage.</p>
|
||
<p>If <em>*buffer</em> points to a non-<em>NULL</em> pointer (an already allocated buffer),
|
||
<a class="reference internal" href="#c.PyArg_ParseTuple" title="PyArg_ParseTuple"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyArg_ParseTuple()</span></code></a> will use this location as the buffer and interpret the
|
||
initial value of <em>*buffer_length</em> as the buffer size. It will then copy the
|
||
encoded data into the buffer and NUL-terminate it. If the buffer is not large
|
||
enough, a <a class="reference internal" href="../library/exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ValueError</span></code></a> will be set.</p>
|
||
<p>In both cases, <em>*buffer_length</em> is set to the length of the encoded data
|
||
without the trailing NUL byte.</p>
|
||
</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">et#</span></code> (<a class="reference internal" href="../library/stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a>, <a class="reference internal" href="../library/stdtypes.html#bytes" title="bytes"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code></a> or <a class="reference internal" href="../library/stdtypes.html#bytearray" title="bytearray"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytearray</span></code></a>) [const char *encoding, char **buffer, int *buffer_length]</dt><dd><p>Same as <code class="docutils literal notranslate"><span class="pre">es#</span></code> except that byte string objects are passed through without recoding
|
||
them. Instead, the implementation assumes that the byte string object uses the
|
||
encoding passed in as parameter.</p>
|
||
</dd>
|
||
</dl>
|
||
</div>
|
||
<div class="section" id="numbers">
|
||
<h3>Numbers<a class="headerlink" href="#numbers" title="Permalink to this headline">¶</a></h3>
|
||
<dl>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">b</span></code> (<a class="reference internal" href="../library/functions.html#int" title="int"><code class="xref py py-class docutils literal notranslate"><span class="pre">int</span></code></a>) [unsigned char]</dt><dd><p>Convert a nonnegative Python integer to an unsigned tiny int, stored in a C
|
||
<code class="xref c c-type docutils literal notranslate"><span class="pre">unsigned</span> <span class="pre">char</span></code>.</p>
|
||
</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">B</span></code> (<a class="reference internal" href="../library/functions.html#int" title="int"><code class="xref py py-class docutils literal notranslate"><span class="pre">int</span></code></a>) [unsigned char]</dt><dd><p>Convert a Python integer to a tiny int without overflow checking, stored in a C
|
||
<code class="xref c c-type docutils literal notranslate"><span class="pre">unsigned</span> <span class="pre">char</span></code>.</p>
|
||
</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">h</span></code> (<a class="reference internal" href="../library/functions.html#int" title="int"><code class="xref py py-class docutils literal notranslate"><span class="pre">int</span></code></a>) [short int]</dt><dd><p>Convert a Python integer to a C <code class="xref c c-type docutils literal notranslate"><span class="pre">short</span> <span class="pre">int</span></code>.</p>
|
||
</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">H</span></code> (<a class="reference internal" href="../library/functions.html#int" title="int"><code class="xref py py-class docutils literal notranslate"><span class="pre">int</span></code></a>) [unsigned short int]</dt><dd><p>Convert a Python integer to a C <code class="xref c c-type docutils literal notranslate"><span class="pre">unsigned</span> <span class="pre">short</span> <span class="pre">int</span></code>, without overflow
|
||
checking.</p>
|
||
</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">i</span></code> (<a class="reference internal" href="../library/functions.html#int" title="int"><code class="xref py py-class docutils literal notranslate"><span class="pre">int</span></code></a>) [int]</dt><dd><p>Convert a Python integer to a plain C <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span></code>.</p>
|
||
</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">I</span></code> (<a class="reference internal" href="../library/functions.html#int" title="int"><code class="xref py py-class docutils literal notranslate"><span class="pre">int</span></code></a>) [unsigned int]</dt><dd><p>Convert a Python integer to a C <code class="xref c c-type docutils literal notranslate"><span class="pre">unsigned</span> <span class="pre">int</span></code>, without overflow
|
||
checking.</p>
|
||
</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">l</span></code> (<a class="reference internal" href="../library/functions.html#int" title="int"><code class="xref py py-class docutils literal notranslate"><span class="pre">int</span></code></a>) [long int]</dt><dd><p>Convert a Python integer to a C <code class="xref c c-type docutils literal notranslate"><span class="pre">long</span> <span class="pre">int</span></code>.</p>
|
||
</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">k</span></code> (<a class="reference internal" href="../library/functions.html#int" title="int"><code class="xref py py-class docutils literal notranslate"><span class="pre">int</span></code></a>) [unsigned long]</dt><dd><p>Convert a Python integer to a C <code class="xref c c-type docutils literal notranslate"><span class="pre">unsigned</span> <span class="pre">long</span></code> without
|
||
overflow checking.</p>
|
||
</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">L</span></code> (<a class="reference internal" href="../library/functions.html#int" title="int"><code class="xref py py-class docutils literal notranslate"><span class="pre">int</span></code></a>) [long long]</dt><dd><p>Convert a Python integer to a C <code class="xref c c-type docutils literal notranslate"><span class="pre">long</span> <span class="pre">long</span></code>.</p>
|
||
</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">K</span></code> (<a class="reference internal" href="../library/functions.html#int" title="int"><code class="xref py py-class docutils literal notranslate"><span class="pre">int</span></code></a>) [unsigned long long]</dt><dd><p>Convert a Python integer to a C <code class="xref c c-type docutils literal notranslate"><span class="pre">unsigned</span> <span class="pre">long</span> <span class="pre">long</span></code>
|
||
without overflow checking.</p>
|
||
</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">n</span></code> (<a class="reference internal" href="../library/functions.html#int" title="int"><code class="xref py py-class docutils literal notranslate"><span class="pre">int</span></code></a>) [Py_ssize_t]</dt><dd><p>Convert a Python integer to a C <code class="xref c c-type docutils literal notranslate"><span class="pre">Py_ssize_t</span></code>.</p>
|
||
</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">c</span></code> (<a class="reference internal" href="../library/stdtypes.html#bytes" title="bytes"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code></a> or <a class="reference internal" href="../library/stdtypes.html#bytearray" title="bytearray"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytearray</span></code></a> of length 1) [char]</dt><dd><p>Convert a Python byte, represented as a <a class="reference internal" href="../library/stdtypes.html#bytes" title="bytes"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code></a> or
|
||
<a class="reference internal" href="../library/stdtypes.html#bytearray" title="bytearray"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytearray</span></code></a> object of length 1, to a C <code class="xref c c-type docutils literal notranslate"><span class="pre">char</span></code>.</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.3: </span>Allow <a class="reference internal" href="../library/stdtypes.html#bytearray" title="bytearray"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytearray</span></code></a> objects.</p>
|
||
</div>
|
||
</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">C</span></code> (<a class="reference internal" href="../library/stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a> of length 1) [int]</dt><dd><p>Convert a Python character, represented as a <a class="reference internal" href="../library/stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a> object of
|
||
length 1, to a C <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span></code>.</p>
|
||
</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">f</span></code> (<a class="reference internal" href="../library/functions.html#float" title="float"><code class="xref py py-class docutils literal notranslate"><span class="pre">float</span></code></a>) [float]</dt><dd><p>Convert a Python floating point number to a C <code class="xref c c-type docutils literal notranslate"><span class="pre">float</span></code>.</p>
|
||
</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">d</span></code> (<a class="reference internal" href="../library/functions.html#float" title="float"><code class="xref py py-class docutils literal notranslate"><span class="pre">float</span></code></a>) [double]</dt><dd><p>Convert a Python floating point number to a C <code class="xref c c-type docutils literal notranslate"><span class="pre">double</span></code>.</p>
|
||
</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">D</span></code> (<a class="reference internal" href="../library/functions.html#complex" title="complex"><code class="xref py py-class docutils literal notranslate"><span class="pre">complex</span></code></a>) [Py_complex]</dt><dd><p>Convert a Python complex number to a C <a class="reference internal" href="complex.html#c.Py_complex" title="Py_complex"><code class="xref c c-type docutils literal notranslate"><span class="pre">Py_complex</span></code></a> structure.</p>
|
||
</dd>
|
||
</dl>
|
||
</div>
|
||
<div class="section" id="other-objects">
|
||
<h3>Other objects<a class="headerlink" href="#other-objects" title="Permalink to this headline">¶</a></h3>
|
||
<dl class="simple">
|
||
<dt><code class="docutils literal notranslate"><span class="pre">O</span></code> (object) [PyObject *]</dt><dd><p>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 <em>NULL</em>.</p>
|
||
</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">O!</span></code> (object) [<em>typeobject</em>, PyObject *]</dt><dd><p>Store a Python object in a C object pointer. This is similar to <code class="docutils literal notranslate"><span class="pre">O</span></code>, 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 <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyObject*</span></code></a>) into which
|
||
the object pointer is stored. If the Python object does not have the required
|
||
type, <a class="reference internal" href="../library/exceptions.html#TypeError" title="TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a> is raised.</p>
|
||
</dd>
|
||
</dl>
|
||
<dl id="o-ampersand">
|
||
<dt><code class="docutils literal notranslate"><span class="pre">O&</span></code> (object) [<em>converter</em>, <em>anything</em>]</dt><dd><p>Convert a Python object to a C variable through a <em>converter</em> function. This
|
||
takes two arguments: the first is a function, the second is the address of a C
|
||
variable (of arbitrary type), converted to <code class="xref c c-type docutils literal notranslate"><span class="pre">void</span> <span class="pre">*</span></code>. The <em>converter</em>
|
||
function in turn is called as follows:</p>
|
||
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n">status</span> <span class="o">=</span> <span class="n">converter</span><span class="p">(</span><span class="n">object</span><span class="p">,</span> <span class="n">address</span><span class="p">);</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>where <em>object</em> is the Python object to be converted and <em>address</em> is the
|
||
<code class="xref c c-type docutils literal notranslate"><span class="pre">void*</span></code> argument that was passed to the <a class="reference internal" href="#c.PyArg_Parse" title="PyArg_Parse"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyArg_Parse*()</span></code></a> function.
|
||
The returned <em>status</em> should be <code class="docutils literal notranslate"><span class="pre">1</span></code> for a successful conversion and <code class="docutils literal notranslate"><span class="pre">0</span></code> if
|
||
the conversion has failed. When the conversion fails, the <em>converter</em> function
|
||
should raise an exception and leave the content of <em>address</em> unmodified.</p>
|
||
<p>If the <em>converter</em> returns <code class="docutils literal notranslate"><span class="pre">Py_CLEANUP_SUPPORTED</span></code>, it may get called a
|
||
second time if the argument parsing eventually fails, giving the converter a
|
||
chance to release any memory that it had already allocated. In this second
|
||
call, the <em>object</em> parameter will be NULL; <em>address</em> will have the same value
|
||
as in the original call.</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.1: </span><code class="docutils literal notranslate"><span class="pre">Py_CLEANUP_SUPPORTED</span></code> was added.</p>
|
||
</div>
|
||
</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">p</span></code> (<a class="reference internal" href="../library/functions.html#bool" title="bool"><code class="xref py py-class docutils literal notranslate"><span class="pre">bool</span></code></a>) [int]</dt><dd><p>Tests the value passed in for truth (a boolean <strong>p</strong>redicate) and converts
|
||
the result to its equivalent C true/false integer value.
|
||
Sets the int to <code class="docutils literal notranslate"><span class="pre">1</span></code> if the expression was true and <code class="docutils literal notranslate"><span class="pre">0</span></code> if it was false.
|
||
This accepts any valid Python value. See <a class="reference internal" href="../library/stdtypes.html#truth"><span class="std std-ref">Truth Value Testing</span></a> for more
|
||
information about how Python tests values for truth.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.3.</span></p>
|
||
</div>
|
||
</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">(items)</span></code> (<a class="reference internal" href="../library/stdtypes.html#tuple" title="tuple"><code class="xref py py-class docutils literal notranslate"><span class="pre">tuple</span></code></a>) [<em>matching-items</em>]</dt><dd><p>The object must be a Python sequence whose length is the number of format units
|
||
in <em>items</em>. The C arguments must correspond to the individual format units in
|
||
<em>items</em>. Format units for sequences may be nested.</p>
|
||
</dd>
|
||
</dl>
|
||
<p>It is possible to pass “long” integers (integers whose value exceeds the
|
||
platform’s <code class="xref py py-const docutils literal notranslate"><span class="pre">LONG_MAX</span></code>) 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>
|
||
<p>A few other characters have a meaning in a format string. These may not occur
|
||
inside nested parentheses. They are:</p>
|
||
<dl>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">|</span></code></dt><dd><p>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,
|
||
<a class="reference internal" href="#c.PyArg_ParseTuple" title="PyArg_ParseTuple"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyArg_ParseTuple()</span></code></a> does not touch the contents of the corresponding C
|
||
variable(s).</p>
|
||
</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">$</span></code></dt><dd><p><a class="reference internal" href="#c.PyArg_ParseTupleAndKeywords" title="PyArg_ParseTupleAndKeywords"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyArg_ParseTupleAndKeywords()</span></code></a> only:
|
||
Indicates that the remaining arguments in the Python argument list are
|
||
keyword-only. Currently, all keyword-only arguments must also be optional
|
||
arguments, so <code class="docutils literal notranslate"><span class="pre">|</span></code> must always be specified before <code class="docutils literal notranslate"><span class="pre">$</span></code> in the format
|
||
string.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.3.</span></p>
|
||
</div>
|
||
</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">:</span></code></dt><dd><p>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
|
||
<a class="reference internal" href="#c.PyArg_ParseTuple" title="PyArg_ParseTuple"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyArg_ParseTuple()</span></code></a> raises).</p>
|
||
</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">;</span></code></dt><dd><p>The list of format units ends here; the string after the semicolon is used as
|
||
the error message <em>instead</em> of the default error message. <code class="docutils literal notranslate"><span class="pre">:</span></code> and <code class="docutils literal notranslate"><span class="pre">;</span></code>
|
||
mutually exclude each other.</p>
|
||
</dd>
|
||
</dl>
|
||
<p>Note that any Python object references which are provided to the caller are
|
||
<em>borrowed</em> references; do not decrement their reference count!</p>
|
||
<p>Additional arguments passed to these functions must be addresses of variables
|
||
whose type is determined by the format string; these are used to store values
|
||
from the input tuple. There are a few cases, as described in the list of format
|
||
units above, where these parameters are used as input values; they should match
|
||
what is specified for the corresponding format unit in that case.</p>
|
||
<p>For the conversion to succeed, the <em>arg</em> object must match the format
|
||
and the format must be exhausted. On success, the
|
||
<a class="reference internal" href="#c.PyArg_Parse" title="PyArg_Parse"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyArg_Parse*()</span></code></a> functions return true, otherwise they return
|
||
false and raise an appropriate exception. When the
|
||
<a class="reference internal" href="#c.PyArg_Parse" title="PyArg_Parse"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyArg_Parse*()</span></code></a> functions fail due to conversion failure in one
|
||
of the format units, the variables at the addresses corresponding to that
|
||
and the following format units are left untouched.</p>
|
||
</div>
|
||
<div class="section" id="api-functions">
|
||
<h3>API Functions<a class="headerlink" href="#api-functions" title="Permalink to this headline">¶</a></h3>
|
||
<dl class="function">
|
||
<dt id="c.PyArg_ParseTuple">
|
||
int <code class="descname">PyArg_ParseTuple</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *args</em>, const char<em> *format</em>, ...<span class="sig-paren">)</span><a class="headerlink" href="#c.PyArg_ParseTuple" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>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.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="c.PyArg_VaParse">
|
||
int <code class="descname">PyArg_VaParse</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *args</em>, const char<em> *format</em>, va_list<em> vargs</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyArg_VaParse" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Identical to <a class="reference internal" href="#c.PyArg_ParseTuple" title="PyArg_ParseTuple"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyArg_ParseTuple()</span></code></a>, except that it accepts a va_list rather
|
||
than a variable number of arguments.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="c.PyArg_ParseTupleAndKeywords">
|
||
int <code class="descname">PyArg_ParseTupleAndKeywords</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *args</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *kw</em>, const char<em> *format</em>, char<em> *keywords[]</em>, ...<span class="sig-paren">)</span><a class="headerlink" href="#c.PyArg_ParseTupleAndKeywords" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Parse the parameters of a function that takes both positional and keyword
|
||
parameters into local variables. The <em>keywords</em> argument is a
|
||
<em>NULL</em>-terminated array of keyword parameter names. Empty names denote
|
||
<a class="reference internal" href="../glossary.html#positional-only-parameter"><span class="std std-ref">positional-only parameters</span></a>.
|
||
Returns true on success; on failure, it returns false and raises the
|
||
appropriate exception.</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.6: </span>Added support for <a class="reference internal" href="../glossary.html#positional-only-parameter"><span class="std std-ref">positional-only parameters</span></a>.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="c.PyArg_VaParseTupleAndKeywords">
|
||
int <code class="descname">PyArg_VaParseTupleAndKeywords</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *args</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *kw</em>, const char<em> *format</em>, char<em> *keywords[]</em>, va_list<em> vargs</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyArg_VaParseTupleAndKeywords" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Identical to <a class="reference internal" href="#c.PyArg_ParseTupleAndKeywords" title="PyArg_ParseTupleAndKeywords"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyArg_ParseTupleAndKeywords()</span></code></a>, except that it accepts a
|
||
va_list rather than a variable number of arguments.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="c.PyArg_ValidateKeywordArguments">
|
||
int <code class="descname">PyArg_ValidateKeywordArguments</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyArg_ValidateKeywordArguments" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Ensure that the keys in the keywords argument dictionary are strings. This
|
||
is only needed if <a class="reference internal" href="#c.PyArg_ParseTupleAndKeywords" title="PyArg_ParseTupleAndKeywords"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyArg_ParseTupleAndKeywords()</span></code></a> is not used, since the
|
||
latter already does this check.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.2.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="c.PyArg_Parse">
|
||
int <code class="descname">PyArg_Parse</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *args</em>, const char<em> *format</em>, ...<span class="sig-paren">)</span><a class="headerlink" href="#c.PyArg_Parse" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Function used to deconstruct the argument lists of “old-style” functions —
|
||
these are functions which use the <code class="xref py py-const docutils literal notranslate"><span class="pre">METH_OLDARGS</span></code> parameter parsing
|
||
method, which has been removed in Python 3. 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.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="c.PyArg_UnpackTuple">
|
||
int <code class="descname">PyArg_UnpackTuple</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *args</em>, const char<em> *name</em>, Py_ssize_t<em> min</em>, Py_ssize_t<em> max</em>, ...<span class="sig-paren">)</span><a class="headerlink" href="#c.PyArg_UnpackTuple" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>A simpler form of parameter retrieval which does not use a format string to
|
||
specify the types of the arguments. Functions which use this method to retrieve
|
||
their parameters should be declared as <a class="reference internal" href="structures.html#METH_VARARGS" title="METH_VARARGS"><code class="xref py py-const docutils literal notranslate"><span class="pre">METH_VARARGS</span></code></a> in function or
|
||
method tables. The tuple containing the actual parameters should be passed as
|
||
<em>args</em>; it must actually be a tuple. The length of the tuple must be at least
|
||
<em>min</em> and no more than <em>max</em>; <em>min</em> and <em>max</em> may be equal. Additional
|
||
arguments must be passed to the function, each of which should be a pointer to a
|
||
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyObject*</span></code></a> variable; these will be filled in with the values from
|
||
<em>args</em>; they will contain borrowed references. The variables which correspond
|
||
to optional parameters not given by <em>args</em> will not be filled in; these should
|
||
be initialized by the caller. This function returns true on success and false if
|
||
<em>args</em> is not a tuple or contains the wrong number of elements; an exception
|
||
will be set if there was a failure.</p>
|
||
<p>This is an example of the use of this function, taken from the sources for the
|
||
<code class="xref py py-mod docutils literal notranslate"><span class="pre">_weakref</span></code> helper module for weak references:</p>
|
||
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="k">static</span> <span class="n">PyObject</span> <span class="o">*</span>
|
||
<span class="nf">weakref_ref</span><span class="p">(</span><span class="n">PyObject</span> <span class="o">*</span><span class="n">self</span><span class="p">,</span> <span class="n">PyObject</span> <span class="o">*</span><span class="n">args</span><span class="p">)</span>
|
||
<span class="p">{</span>
|
||
<span class="n">PyObject</span> <span class="o">*</span><span class="n">object</span><span class="p">;</span>
|
||
<span class="n">PyObject</span> <span class="o">*</span><span class="n">callback</span> <span class="o">=</span> <span class="nb">NULL</span><span class="p">;</span>
|
||
<span class="n">PyObject</span> <span class="o">*</span><span class="n">result</span> <span class="o">=</span> <span class="nb">NULL</span><span class="p">;</span>
|
||
|
||
<span class="k">if</span> <span class="p">(</span><span class="n">PyArg_UnpackTuple</span><span class="p">(</span><span class="n">args</span><span class="p">,</span> <span class="s">"ref"</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="o">&</span><span class="n">object</span><span class="p">,</span> <span class="o">&</span><span class="n">callback</span><span class="p">))</span> <span class="p">{</span>
|
||
<span class="n">result</span> <span class="o">=</span> <span class="n">PyWeakref_NewRef</span><span class="p">(</span><span class="n">object</span><span class="p">,</span> <span class="n">callback</span><span class="p">);</span>
|
||
<span class="p">}</span>
|
||
<span class="k">return</span> <span class="n">result</span><span class="p">;</span>
|
||
<span class="p">}</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>The call to <a class="reference internal" href="#c.PyArg_UnpackTuple" title="PyArg_UnpackTuple"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyArg_UnpackTuple()</span></code></a> in this example is entirely equivalent to
|
||
this call to <a class="reference internal" href="#c.PyArg_ParseTuple" title="PyArg_ParseTuple"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyArg_ParseTuple()</span></code></a>:</p>
|
||
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n">PyArg_ParseTuple</span><span class="p">(</span><span class="n">args</span><span class="p">,</span> <span class="s">"O|O:ref"</span><span class="p">,</span> <span class="o">&</span><span class="n">object</span><span class="p">,</span> <span class="o">&</span><span class="n">callback</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
</div>
|
||
</div>
|
||
<div class="section" id="building-values">
|
||
<h2>Building values<a class="headerlink" href="#building-values" title="Permalink to this headline">¶</a></h2>
|
||
<dl class="function">
|
||
<dt id="c.Py_BuildValue">
|
||
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">Py_BuildValue</code><span class="sig-paren">(</span>const char<em> *format</em>, ...<span class="sig-paren">)</span><a class="headerlink" href="#c.Py_BuildValue" title="Permalink to this definition">¶</a></dt>
|
||
<dd><em class="refcount">Return value: New reference.</em><p>Create a new value based on a format string similar to those accepted by the
|
||
<a class="reference internal" href="#c.PyArg_Parse" title="PyArg_Parse"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyArg_Parse*()</span></code></a> family of functions and a sequence of values. Returns
|
||
the value or <em>NULL</em> in the case of an error; an exception will be raised if
|
||
<em>NULL</em> is returned.</p>
|
||
<p><a class="reference internal" href="#c.Py_BuildValue" title="Py_BuildValue"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_BuildValue()</span></code></a> does not always build a tuple. It builds a tuple only if
|
||
its format string contains two or more format units. If the format string is
|
||
empty, it returns <code class="docutils literal notranslate"><span class="pre">None</span></code>; if it contains exactly one format unit, it returns
|
||
whatever object is described by that format unit. To force it to return a tuple
|
||
of size 0 or one, parenthesize the format string.</p>
|
||
<p>When memory buffers are passed as parameters to supply data to build objects, as
|
||
for the <code class="docutils literal notranslate"><span class="pre">s</span></code> and <code class="docutils literal notranslate"><span class="pre">s#</span></code> formats, the required data is copied. Buffers provided
|
||
by the caller are never referenced by the objects created by
|
||
<a class="reference internal" href="#c.Py_BuildValue" title="Py_BuildValue"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_BuildValue()</span></code></a>. In other words, if your code invokes <code class="xref c c-func docutils literal notranslate"><span class="pre">malloc()</span></code>
|
||
and passes the allocated memory to <a class="reference internal" href="#c.Py_BuildValue" title="Py_BuildValue"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_BuildValue()</span></code></a>, your code is
|
||
responsible for calling <code class="xref c c-func docutils literal notranslate"><span class="pre">free()</span></code> for that memory once
|
||
<a class="reference internal" href="#c.Py_BuildValue" title="Py_BuildValue"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_BuildValue()</span></code></a> returns.</p>
|
||
<p>In the following description, the quoted form is the format unit; the entry in
|
||
(round) parentheses is the Python object type that the format unit will return;
|
||
and the entry in [square] brackets is the type of the C value(s) to be passed.</p>
|
||
<p>The characters space, tab, colon and comma are ignored in format strings (but
|
||
not within format units such as <code class="docutils literal notranslate"><span class="pre">s#</span></code>). This can be used to make long format
|
||
strings a tad more readable.</p>
|
||
<dl class="simple">
|
||
<dt><code class="docutils literal notranslate"><span class="pre">s</span></code> (<a class="reference internal" href="../library/stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a> or <code class="docutils literal notranslate"><span class="pre">None</span></code>) [const char *]</dt><dd><p>Convert a null-terminated C string to a Python <a class="reference internal" href="../library/stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a> object using <code class="docutils literal notranslate"><span class="pre">'utf-8'</span></code>
|
||
encoding. If the C string pointer is <em>NULL</em>, <code class="docutils literal notranslate"><span class="pre">None</span></code> is used.</p>
|
||
</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">s#</span></code> (<a class="reference internal" href="../library/stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a> or <code class="docutils literal notranslate"><span class="pre">None</span></code>) [const char *, int]</dt><dd><p>Convert a C string and its length to a Python <a class="reference internal" href="../library/stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a> object using <code class="docutils literal notranslate"><span class="pre">'utf-8'</span></code>
|
||
encoding. If the C string pointer is <em>NULL</em>, the length is ignored and
|
||
<code class="docutils literal notranslate"><span class="pre">None</span></code> is returned.</p>
|
||
</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">y</span></code> (<a class="reference internal" href="../library/stdtypes.html#bytes" title="bytes"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code></a>) [const char *]</dt><dd><p>This converts a C string to a Python <a class="reference internal" href="../library/stdtypes.html#bytes" title="bytes"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code></a> object. If the C
|
||
string pointer is <em>NULL</em>, <code class="docutils literal notranslate"><span class="pre">None</span></code> is returned.</p>
|
||
</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">y#</span></code> (<a class="reference internal" href="../library/stdtypes.html#bytes" title="bytes"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code></a>) [const char *, int]</dt><dd><p>This converts a C string and its lengths to a Python object. If the C
|
||
string pointer is <em>NULL</em>, <code class="docutils literal notranslate"><span class="pre">None</span></code> is returned.</p>
|
||
</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">z</span></code> (<a class="reference internal" href="../library/stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a> or <code class="docutils literal notranslate"><span class="pre">None</span></code>) [const char *]</dt><dd><p>Same as <code class="docutils literal notranslate"><span class="pre">s</span></code>.</p>
|
||
</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">z#</span></code> (<a class="reference internal" href="../library/stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a> or <code class="docutils literal notranslate"><span class="pre">None</span></code>) [const char *, int]</dt><dd><p>Same as <code class="docutils literal notranslate"><span class="pre">s#</span></code>.</p>
|
||
</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">u</span></code> (<a class="reference internal" href="../library/stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a>) [const wchar_t *]</dt><dd><p>Convert a null-terminated <code class="xref c c-type docutils literal notranslate"><span class="pre">wchar_t</span></code> buffer of Unicode (UTF-16 or UCS-4)
|
||
data to a Python Unicode object. If the Unicode buffer pointer is <em>NULL</em>,
|
||
<code class="docutils literal notranslate"><span class="pre">None</span></code> is returned.</p>
|
||
</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">u#</span></code> (<a class="reference internal" href="../library/stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a>) [const wchar_t *, int]</dt><dd><p>Convert a Unicode (UTF-16 or UCS-4) data buffer and its length to a Python
|
||
Unicode object. If the Unicode buffer pointer is <em>NULL</em>, the length is ignored
|
||
and <code class="docutils literal notranslate"><span class="pre">None</span></code> is returned.</p>
|
||
</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">U</span></code> (<a class="reference internal" href="../library/stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a> or <code class="docutils literal notranslate"><span class="pre">None</span></code>) [const char *]</dt><dd><p>Same as <code class="docutils literal notranslate"><span class="pre">s</span></code>.</p>
|
||
</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">U#</span></code> (<a class="reference internal" href="../library/stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a> or <code class="docutils literal notranslate"><span class="pre">None</span></code>) [const char *, int]</dt><dd><p>Same as <code class="docutils literal notranslate"><span class="pre">s#</span></code>.</p>
|
||
</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">i</span></code> (<a class="reference internal" href="../library/functions.html#int" title="int"><code class="xref py py-class docutils literal notranslate"><span class="pre">int</span></code></a>) [int]</dt><dd><p>Convert a plain C <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span></code> to a Python integer object.</p>
|
||
</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">b</span></code> (<a class="reference internal" href="../library/functions.html#int" title="int"><code class="xref py py-class docutils literal notranslate"><span class="pre">int</span></code></a>) [char]</dt><dd><p>Convert a plain C <code class="xref c c-type docutils literal notranslate"><span class="pre">char</span></code> to a Python integer object.</p>
|
||
</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">h</span></code> (<a class="reference internal" href="../library/functions.html#int" title="int"><code class="xref py py-class docutils literal notranslate"><span class="pre">int</span></code></a>) [short int]</dt><dd><p>Convert a plain C <code class="xref c c-type docutils literal notranslate"><span class="pre">short</span> <span class="pre">int</span></code> to a Python integer object.</p>
|
||
</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">l</span></code> (<a class="reference internal" href="../library/functions.html#int" title="int"><code class="xref py py-class docutils literal notranslate"><span class="pre">int</span></code></a>) [long int]</dt><dd><p>Convert a C <code class="xref c c-type docutils literal notranslate"><span class="pre">long</span> <span class="pre">int</span></code> to a Python integer object.</p>
|
||
</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">B</span></code> (<a class="reference internal" href="../library/functions.html#int" title="int"><code class="xref py py-class docutils literal notranslate"><span class="pre">int</span></code></a>) [unsigned char]</dt><dd><p>Convert a C <code class="xref c c-type docutils literal notranslate"><span class="pre">unsigned</span> <span class="pre">char</span></code> to a Python integer object.</p>
|
||
</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">H</span></code> (<a class="reference internal" href="../library/functions.html#int" title="int"><code class="xref py py-class docutils literal notranslate"><span class="pre">int</span></code></a>) [unsigned short int]</dt><dd><p>Convert a C <code class="xref c c-type docutils literal notranslate"><span class="pre">unsigned</span> <span class="pre">short</span> <span class="pre">int</span></code> to a Python integer object.</p>
|
||
</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">I</span></code> (<a class="reference internal" href="../library/functions.html#int" title="int"><code class="xref py py-class docutils literal notranslate"><span class="pre">int</span></code></a>) [unsigned int]</dt><dd><p>Convert a C <code class="xref c c-type docutils literal notranslate"><span class="pre">unsigned</span> <span class="pre">int</span></code> to a Python integer object.</p>
|
||
</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">k</span></code> (<a class="reference internal" href="../library/functions.html#int" title="int"><code class="xref py py-class docutils literal notranslate"><span class="pre">int</span></code></a>) [unsigned long]</dt><dd><p>Convert a C <code class="xref c c-type docutils literal notranslate"><span class="pre">unsigned</span> <span class="pre">long</span></code> to a Python integer object.</p>
|
||
</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">L</span></code> (<a class="reference internal" href="../library/functions.html#int" title="int"><code class="xref py py-class docutils literal notranslate"><span class="pre">int</span></code></a>) [long long]</dt><dd><p>Convert a C <code class="xref c c-type docutils literal notranslate"><span class="pre">long</span> <span class="pre">long</span></code> to a Python integer object.</p>
|
||
</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">K</span></code> (<a class="reference internal" href="../library/functions.html#int" title="int"><code class="xref py py-class docutils literal notranslate"><span class="pre">int</span></code></a>) [unsigned long long]</dt><dd><p>Convert a C <code class="xref c c-type docutils literal notranslate"><span class="pre">unsigned</span> <span class="pre">long</span> <span class="pre">long</span></code> to a Python integer object.</p>
|
||
</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">n</span></code> (<a class="reference internal" href="../library/functions.html#int" title="int"><code class="xref py py-class docutils literal notranslate"><span class="pre">int</span></code></a>) [Py_ssize_t]</dt><dd><p>Convert a C <code class="xref c c-type docutils literal notranslate"><span class="pre">Py_ssize_t</span></code> to a Python integer.</p>
|
||
</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">c</span></code> (<a class="reference internal" href="../library/stdtypes.html#bytes" title="bytes"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code></a> of length 1) [char]</dt><dd><p>Convert a C <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span></code> representing a byte to a Python <a class="reference internal" href="../library/stdtypes.html#bytes" title="bytes"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code></a> object of
|
||
length 1.</p>
|
||
</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">C</span></code> (<a class="reference internal" href="../library/stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a> of length 1) [int]</dt><dd><p>Convert a C <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span></code> representing a character to Python <a class="reference internal" href="../library/stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a>
|
||
object of length 1.</p>
|
||
</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">d</span></code> (<a class="reference internal" href="../library/functions.html#float" title="float"><code class="xref py py-class docutils literal notranslate"><span class="pre">float</span></code></a>) [double]</dt><dd><p>Convert a C <code class="xref c c-type docutils literal notranslate"><span class="pre">double</span></code> to a Python floating point number.</p>
|
||
</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">f</span></code> (<a class="reference internal" href="../library/functions.html#float" title="float"><code class="xref py py-class docutils literal notranslate"><span class="pre">float</span></code></a>) [float]</dt><dd><p>Convert a C <code class="xref c c-type docutils literal notranslate"><span class="pre">float</span></code> to a Python floating point number.</p>
|
||
</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">D</span></code> (<a class="reference internal" href="../library/functions.html#complex" title="complex"><code class="xref py py-class docutils literal notranslate"><span class="pre">complex</span></code></a>) [Py_complex *]</dt><dd><p>Convert a C <a class="reference internal" href="complex.html#c.Py_complex" title="Py_complex"><code class="xref c c-type docutils literal notranslate"><span class="pre">Py_complex</span></code></a> structure to a Python complex number.</p>
|
||
</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">O</span></code> (object) [PyObject *]</dt><dd><p>Pass a Python object untouched (except for its reference count, which is
|
||
incremented by one). If the object passed in is a <em>NULL</em> pointer, it is assumed
|
||
that this was caused because the call producing the argument found an error and
|
||
set an exception. Therefore, <a class="reference internal" href="#c.Py_BuildValue" title="Py_BuildValue"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_BuildValue()</span></code></a> will return <em>NULL</em> but won’t
|
||
raise an exception. If no exception has been raised yet, <a class="reference internal" href="../library/exceptions.html#SystemError" title="SystemError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">SystemError</span></code></a> is
|
||
set.</p>
|
||
</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">S</span></code> (object) [PyObject *]</dt><dd><p>Same as <code class="docutils literal notranslate"><span class="pre">O</span></code>.</p>
|
||
</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">N</span></code> (object) [PyObject *]</dt><dd><p>Same as <code class="docutils literal notranslate"><span class="pre">O</span></code>, except it doesn’t increment the reference count on the object.
|
||
Useful when the object is created by a call to an object constructor in the
|
||
argument list.</p>
|
||
</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">O&</span></code> (object) [<em>converter</em>, <em>anything</em>]</dt><dd><p>Convert <em>anything</em> to a Python object through a <em>converter</em> function. The
|
||
function is called with <em>anything</em> (which should be compatible with <code class="xref c c-type docutils literal notranslate"><span class="pre">void</span>
|
||
<span class="pre">*</span></code>) as its argument and should return a “new” Python object, or <em>NULL</em> if an
|
||
error occurred.</p>
|
||
</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">(items)</span></code> (<a class="reference internal" href="../library/stdtypes.html#tuple" title="tuple"><code class="xref py py-class docutils literal notranslate"><span class="pre">tuple</span></code></a>) [<em>matching-items</em>]</dt><dd><p>Convert a sequence of C values to a Python tuple with the same number of items.</p>
|
||
</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">[items]</span></code> (<a class="reference internal" href="../library/stdtypes.html#list" title="list"><code class="xref py py-class docutils literal notranslate"><span class="pre">list</span></code></a>) [<em>matching-items</em>]</dt><dd><p>Convert a sequence of C values to a Python list with the same number of items.</p>
|
||
</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">{items}</span></code> (<a class="reference internal" href="../library/stdtypes.html#dict" title="dict"><code class="xref py py-class docutils literal notranslate"><span class="pre">dict</span></code></a>) [<em>matching-items</em>]</dt><dd><p>Convert a sequence of C values to a Python dictionary. Each pair of consecutive
|
||
C values adds one item to the dictionary, serving as key and value,
|
||
respectively.</p>
|
||
</dd>
|
||
</dl>
|
||
<p>If there is an error in the format string, the <a class="reference internal" href="../library/exceptions.html#SystemError" title="SystemError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">SystemError</span></code></a> exception is
|
||
set and <em>NULL</em> returned.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="c.Py_VaBuildValue">
|
||
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">Py_VaBuildValue</code><span class="sig-paren">(</span>const char<em> *format</em>, va_list<em> vargs</em><span class="sig-paren">)</span><a class="headerlink" href="#c.Py_VaBuildValue" title="Permalink to this definition">¶</a></dt>
|
||
<dd><em class="refcount">Return value: New reference.</em><p>Identical to <a class="reference internal" href="#c.Py_BuildValue" title="Py_BuildValue"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_BuildValue()</span></code></a>, except that it accepts a va_list
|
||
rather than a variable number of arguments.</p>
|
||
</dd></dl>
|
||
|
||
</div>
|
||
</div>
|
||
|
||
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
|
||
<div class="sphinxsidebarwrapper">
|
||
<h3><a href="../contents.html">Table of Contents</a></h3>
|
||
<ul>
|
||
<li><a class="reference internal" href="#">Parsing arguments and building values</a><ul>
|
||
<li><a class="reference internal" href="#parsing-arguments">Parsing arguments</a><ul>
|
||
<li><a class="reference internal" href="#strings-and-buffers">Strings and buffers</a></li>
|
||
<li><a class="reference internal" href="#numbers">Numbers</a></li>
|
||
<li><a class="reference internal" href="#other-objects">Other objects</a></li>
|
||
<li><a class="reference internal" href="#api-functions">API Functions</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#building-values">Building values</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
|
||
<h4>Previous topic</h4>
|
||
<p class="topless"><a href="marshal.html"
|
||
title="previous chapter">Data marshalling support</a></p>
|
||
<h4>Next topic</h4>
|
||
<p class="topless"><a href="conversion.html"
|
||
title="next chapter">String conversion and formatting</a></p>
|
||
<div role="note" aria-label="source link">
|
||
<h3>This Page</h3>
|
||
<ul class="this-page-menu">
|
||
<li><a href="../bugs.html">Report a Bug</a></li>
|
||
<li>
|
||
<a href="https://github.com/python/cpython/blob/3.7/Doc/c-api/arg.rst"
|
||
rel="nofollow">Show Source
|
||
</a>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="clearer"></div>
|
||
</div>
|
||
<div class="related" role="navigation" aria-label="related navigation">
|
||
<h3>Navigation</h3>
|
||
<ul>
|
||
<li class="right" style="margin-right: 10px">
|
||
<a href="../genindex.html" title="General Index"
|
||
>index</a></li>
|
||
<li class="right" >
|
||
<a href="../py-modindex.html" title="Python Module Index"
|
||
>modules</a> |</li>
|
||
<li class="right" >
|
||
<a href="conversion.html" title="String conversion and formatting"
|
||
>next</a> |</li>
|
||
<li class="right" >
|
||
<a href="marshal.html" title="Data marshalling support"
|
||
>previous</a> |</li>
|
||
<li><img src="../_static/py.png" alt=""
|
||
style="vertical-align: middle; margin-top: -1px"/></li>
|
||
<li><a href="https://www.python.org/">Python</a> »</li>
|
||
<li>
|
||
<span class="language_switcher_placeholder">en</span>
|
||
<span class="version_switcher_placeholder">3.7.4</span>
|
||
<a href="../index.html">Documentation </a> »
|
||
</li>
|
||
|
||
<li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> »</li>
|
||
<li class="nav-item nav-item-2"><a href="utilities.html" >Utilities</a> »</li>
|
||
<li class="right">
|
||
|
||
|
||
<div class="inline-search" style="display: none" role="search">
|
||
<form class="inline-search" action="../search.html" method="get">
|
||
<input placeholder="Quick search" type="text" name="q" />
|
||
<input type="submit" value="Go" />
|
||
<input type="hidden" name="check_keywords" value="yes" />
|
||
<input type="hidden" name="area" value="default" />
|
||
</form>
|
||
</div>
|
||
<script type="text/javascript">$('.inline-search').show(0);</script>
|
||
|
|
||
</li>
|
||
|
||
</ul>
|
||
</div>
|
||
<div class="footer">
|
||
© <a href="../copyright.html">Copyright</a> 2001-2019, Python Software Foundation.
|
||
<br />
|
||
The Python Software Foundation is a non-profit corporation.
|
||
<a href="https://www.python.org/psf/donations/">Please donate.</a>
|
||
<br />
|
||
Last updated on Jul 13, 2019.
|
||
<a href="../bugs.html">Found a bug</a>?
|
||
<br />
|
||
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 2.0.1.
|
||
</div>
|
||
|
||
</body>
|
||
</html> |