622 lines
94 KiB
HTML
622 lines
94 KiB
HTML
|
||
<!DOCTYPE html>
|
||
|
||
<html xmlns="http://www.w3.org/1999/xhtml" lang="zh_CN">
|
||
<head>
|
||
<meta charset="utf-8" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
|
||
|
||
<title>解析参数并构建值变量 — Python 3.8.20 文档</title><meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||
|
||
<link rel="stylesheet" href="../_static/pydoctheme.css" type="text/css" />
|
||
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
|
||
|
||
<script id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
|
||
<script src="../_static/jquery.js"></script>
|
||
<script src="../_static/underscore.js"></script>
|
||
<script src="../_static/doctools.js"></script>
|
||
<script src="../_static/language_data.js"></script>
|
||
<script src="../_static/translations.js"></script>
|
||
|
||
<script src="../_static/sidebar.js"></script>
|
||
|
||
<link rel="search" type="application/opensearchdescription+xml"
|
||
title="在 Python 3.8.20 文档 中搜索"
|
||
href="../_static/opensearch.xml"/>
|
||
<link rel="author" title="关于这些文档" href="../about.html" />
|
||
<link rel="index" title="索引" href="../genindex.html" />
|
||
<link rel="search" title="搜索" href="../search.html" />
|
||
<link rel="copyright" title="版权所有" href="../copyright.html" />
|
||
<link rel="next" title="字符串转换与格式化" href="conversion.html" />
|
||
<link rel="prev" title="数据 marshal 操作支持" href="marshal.html" />
|
||
<link rel="canonical" href="https://docs.python.org/3/c-api/arg.html" />
|
||
|
||
|
||
|
||
|
||
|
||
<style>
|
||
@media only screen {
|
||
table.full-width-table {
|
||
width: 100%;
|
||
}
|
||
}
|
||
</style>
|
||
<link rel="shortcut icon" type="image/png" href="../_static/py.svg" />
|
||
<script type="text/javascript" src="../_static/copybutton.js"></script>
|
||
<script type="text/javascript" src="../_static/menu.js"></script>
|
||
|
||
</head>
|
||
<body>
|
||
<div class="mobile-nav">
|
||
<input type="checkbox" id="menuToggler" class="toggler__input" aria-controls="navigation"
|
||
aria-pressed="false" aria-expanded="false" role="button" aria-label="Menu" />
|
||
<label for="menuToggler" class="toggler__label">
|
||
<span></span>
|
||
</label>
|
||
<nav class="nav-content" role="navigation">
|
||
<a href="https://www.python.org/" class="nav-logo">
|
||
<img src="../_static/py.svg" alt="Logo"/>
|
||
</a>
|
||
<div class="version_switcher_placeholder"></div>
|
||
<form role="search" class="search" action="../search.html" method="get">
|
||
<svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" class="search-icon">
|
||
<path fill-rule="nonzero"
|
||
d="M15.5 14h-.79l-.28-.27a6.5 6.5 0 001.48-5.34c-.47-2.78-2.79-5-5.59-5.34a6.505 6.505 0 00-7.27 7.27c.34 2.8 2.56 5.12 5.34 5.59a6.5 6.5 0 005.34-1.48l.27.28v.79l4.25 4.25c.41.41 1.08.41 1.49 0 .41-.41.41-1.08 0-1.49L15.5 14zm-6 0C7.01 14 5 11.99 5 9.5S7.01 5 9.5 5 14 7.01 14 9.5 11.99 14 9.5 14z" fill="#444"></path>
|
||
</svg>
|
||
<input type="text" name="q" aria-label="快速搜索"/>
|
||
<input type="submit" value="转向"/>
|
||
</form>
|
||
</nav>
|
||
<div class="menu-wrapper">
|
||
<nav class="menu" role="navigation" aria-label="main navigation">
|
||
<div class="language_switcher_placeholder"></div>
|
||
<h3><a href="../contents.html">目录</a></h3>
|
||
<ul>
|
||
<li><a class="reference internal" href="#">解析参数并构建值变量</a><ul>
|
||
<li><a class="reference internal" href="#parsing-arguments">解析参数</a><ul>
|
||
<li><a class="reference internal" href="#strings-and-buffers">字符串和缓存区</a></li>
|
||
<li><a class="reference internal" href="#numbers">数字</a></li>
|
||
<li><a class="reference internal" href="#other-objects">其他对象</a></li>
|
||
<li><a class="reference internal" href="#api-functions">API 函数</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#building-values">创建变量</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
|
||
<h4>上一个主题</h4>
|
||
<p class="topless"><a href="marshal.html"
|
||
title="上一章">数据 marshal 操作支持</a></p>
|
||
<h4>下一个主题</h4>
|
||
<p class="topless"><a href="conversion.html"
|
||
title="下一章">字符串转换与格式化</a></p>
|
||
<div role="note" aria-label="source link">
|
||
<h3>本页</h3>
|
||
<ul class="this-page-menu">
|
||
<li><a href="../bugs.html">报告 Bug</a></li>
|
||
<li>
|
||
<a href="https://github.com/python/cpython/blob/3.8/Doc/c-api/arg.rst"
|
||
rel="nofollow">显示源代码
|
||
</a>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
</nav>
|
||
</div>
|
||
</div>
|
||
|
||
<div id="outdated-warning" style="padding: .5em; text-align: center; background-color: #FFBABA; color: #6A0E0E;">
|
||
这个文档所针对的是一个已不再受支持的 Python 旧版本。
|
||
你应当升级版本，并阅读
|
||
<a href="/3/c-api/arg.html"> Python 当前稳定版本的文档</a>.
|
||
</div>
|
||
|
||
<div class="related" role="navigation" aria-label="related navigation">
|
||
<h3>导航</h3>
|
||
<ul>
|
||
<li class="right" style="margin-right: 10px">
|
||
<a href="../genindex.html" title="总目录"
|
||
accesskey="I">索引</a></li>
|
||
<li class="right" >
|
||
<a href="../py-modindex.html" title="Python 模块索引"
|
||
>模块</a> |</li>
|
||
<li class="right" >
|
||
<a href="conversion.html" title="字符串转换与格式化"
|
||
accesskey="N">下一页</a> |</li>
|
||
<li class="right" >
|
||
<a href="marshal.html" title="数据 marshal 操作支持"
|
||
accesskey="P">上一页</a> |</li>
|
||
|
||
<li><img src="../_static/py.svg" alt="python logo" style="vertical-align: middle; margin-top: -1px"/></li>
|
||
<li><a href="https://www.python.org/">Python</a> »</li>
|
||
<li class="switchers">
|
||
<div class="language_switcher_placeholder"></div>
|
||
<div class="version_switcher_placeholder"></div>
|
||
</li>
|
||
<li>
|
||
|
||
</li>
|
||
<li id="cpython-language-and-version">
|
||
<a href="../index.html">3.8.20 Documentation</a> »
|
||
</li>
|
||
|
||
<li class="nav-item nav-item-1"><a href="index.html" >Python/C API 参考手册</a> »</li>
|
||
<li class="nav-item nav-item-2"><a href="utilities.html" accesskey="U">工具</a> »</li>
|
||
<li class="right">
|
||
|
||
|
||
<div class="inline-search" role="search">
|
||
<form class="inline-search" action="../search.html" method="get">
|
||
<input placeholder="快速搜索" aria-label="快速搜索" type="text" name="q" />
|
||
<input type="submit" value="转向" />
|
||
<input type="hidden" name="check_keywords" value="yes" />
|
||
<input type="hidden" name="area" value="default" />
|
||
</form>
|
||
</div>
|
||
|
|
||
</li>
|
||
|
||
</ul>
|
||
</div>
|
||
|
||
<div class="document">
|
||
<div class="documentwrapper">
|
||
<div class="bodywrapper">
|
||
<div class="body" role="main">
|
||
|
||
<section id="parsing-arguments-and-building-values">
|
||
<span id="arg-parsing"></span><h1>解析参数并构建值变量<a class="headerlink" href="#parsing-arguments-and-building-values" title="永久链接至标题">¶</a></h1>
|
||
<p>在创建你自己的扩展函数和方法时，这些函数是有用的。其它的信息和样例见 <a class="reference internal" href="../extending/index.html#extending-index"><span class="std std-ref">扩展和嵌入 Python 解释器</span></a> 。</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>，<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>，以及 <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>，它们都使用 <em>格式化字符串</em> 来将函数期待的参数告知函数。这些函数都使用相同语法规则的格式化字符串。</p>
|
||
<section id="parsing-arguments">
|
||
<h2>解析参数<a class="headerlink" href="#parsing-arguments" title="永久链接至标题">¶</a></h2>
|
||
<p>一个格式化字符串包含 0 或者更多的格式单元。一个格式单元用来描述一个 Python 对象；它通常是一个字符或者由括号括起来的格式单元序列。除了少数例外，一个非括号序列的格式单元通常对应这些函数的具有单一地址的参数。在接下来的描述中，双引号内的表达式是格式单元；圆括号 () 内的是对应这个格式单元的 Python 对象类型；方括号 [] 内的是传递的 C 变量(变量集)类型。</p>
|
||
<section id="strings-and-buffers">
|
||
<h3>字符串和缓存区<a class="headerlink" href="#strings-and-buffers" title="永久链接至标题">¶</a></h3>
|
||
<p>这些格式允许将对象按照连续的内存块形式进行访问。你没必要提供返回的 unicode 字符或者字节区的原始数据存储。</p>
|
||
<p>一般的，当一个表达式设置一个指针指向一个缓冲区，这个缓冲区可以被相应的 Python 对象管理，并且这个缓冲区共享这个对象的生存周期。你不需要人为的释放任何内存空间。除了这些 <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>然而，当一个 <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> 结构被赋值，其包含的缓冲区被锁住，所以调用者在随后使用这个缓冲区，即使在 <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> 块中，可以避免可变数据因为调整大小或者被销毁所带来的风险。因此，<strong>你不得不调用</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> 在你结束数据的处理时(或者在之前任何中断事件中)</p>
|
||
<p>除非另有说明，缓冲区是不会以空终止的。</p>
|
||
<p>某些格式需要只读的 <a class="reference internal" href="../glossary.html#term-bytes-like-object"><span class="xref std std-term">bytes-like object</span></a>，并设置指针而不是缓冲区结构。 他们通过检查对象的 <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> 字段是否为 <code class="docutils literal notranslate"><span class="pre">NULL</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> 这样的可变对象。</p>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">注解</p>
|
||
<p>所有 <code class="docutils literal notranslate"><span class="pre">#</span></code> 表达式的变体 (<code class="docutils literal notranslate"><span class="pre">s#</span></code>，<code class="docutils literal notranslate"><span class="pre">y#</span></code> 等)，长度参数的类型 (整型或者 <code class="xref c c-type docutils literal notranslate"><span class="pre">Py_ssize_t</span></code>) 在包含 <code class="file docutils literal notranslate"><span class="pre">Python.h</span></code> 头文件之前由 <code class="xref c c-macro docutils literal notranslate"><span class="pre">PY_SSIZE_T_CLEAN</span></code> 宏的定义控制。 如果这个宏被定义，长度是一个 <code class="xref c c-type docutils literal notranslate"><span class="pre">Py_ssize_t</span></code> 而不是一个 <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span></code>。 在未来的 Python 版本中将会改变，只支持 <code class="xref c c-type docutils literal notranslate"><span class="pre">Py_ssize_t</span></code> 而放弃支持 <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span></code>。 最好一直定义 <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>将一个 Unicode 对象转换成一个指向字符串的 C 指针。一个指针指向一个已经存在的字符串，这个字符串存储的是传如的字符指针变量。C 字符串是已空结束的。Python 字符串不能包含嵌入的无效的代码点；如果由，一个 <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> 异常会被引发。Unicode 对象被转化成 <code class="docutils literal notranslate"><span class="pre">'utf-8'</span></code> 编码的 C 字符串。如果转换失败，一个 <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> 异常被引发。</p>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">注解</p>
|
||
<p>这个表达式不接受 <a class="reference internal" href="../glossary.html#term-bytes-like-object"><span class="xref std std-term">bytes-like objects</span></a>。如果你想接受文件系统路径并将它们转化成 C 字符串，建议使用 <code class="docutils literal notranslate"><span class="pre">O&</span></code> 表达式配合 <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> 作为 <em>转化函数</em>。</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">在 3.5 版更改: </span>以前，当 Python 字符串中遇到了嵌入的 null 代码点会引发 <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> 。</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>这个表达式既接受 Unicode 对象也接受类字节类型对象。它为由调用者提供的 <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> 结构赋值。这里结果的 C 字符串可能包含嵌入的 NUL 字节。Unicode 对象通过 <code class="docutils literal notranslate"><span class="pre">'utf-8'</span></code> 编码转化成 C 字符串。</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>, 只读 <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>像 <code class="docutils literal notranslate"><span class="pre">s*</span></code>，除了它不接受易变的对象。结果存储在两个 C 变量中，第一个是指向 C 字符串的指针，第二个是它的长度。字符串可能包含嵌入的 null 字节。Unicode 对象都被通过 <code class="docutils literal notranslate"><span class="pre">'utf-8'</span></code> 编码转化成 C 字符串。</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>与 <code class="docutils literal notranslate"><span class="pre">s</span></code> 类似，但 Python 对象也可能为 <code class="docutils literal notranslate"><span class="pre">None</span></code>，在这种情况下，C 指针设置为 <code class="docutils literal notranslate"><span class="pre">NULL</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>, <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>与 <code class="docutils literal notranslate"><span class="pre">s*</span></code> 类似，但 Python 对象也可能为 <code class="docutils literal notranslate"><span class="pre">None</span></code>，在这种情况下，<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> 结构的 <code class="docutils literal notranslate"><span class="pre">buf</span></code> 成员设置为 <code class="docutils literal notranslate"><span class="pre">NULL</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>, 只读 <a class="reference internal" href="../glossary.html#term-bytes-like-object"><span class="xref std std-term">bytes-like object</span></a> 或 <code class="docutils literal notranslate"><span class="pre">None</span></code>) [const char *, int 或 <code class="xref c c-type docutils literal notranslate"><span class="pre">Py_ssize_t</span></code>]</dt><dd><p>与 <code class="docutils literal notranslate"><span class="pre">s#</span></code> 类似，但 Python 对象也可能为 <code class="docutils literal notranslate"><span class="pre">None</span></code>，在这种情况下，C 指针设置为 <code class="docutils literal notranslate"><span class="pre">NULL</span></code>。</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>这个表达式将一个类字节类型对象转化成一个指向字符串的 C 指针；它不接受 Unicode 对象。字节缓存区必须不包含嵌入的 null 字节；如果包含了 null 字节，会引发一个 <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> 异常。</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">在 3.5 版更改: </span>以前，当字节缓冲区中遇到了嵌入的 null 字节会引发 <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> 。</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><code class="docutils literal notranslate"><span class="pre">s*</span></code> 的变式，不接受 Unicode 对象，只接受类字节类型变量。<strong>这是接受二进制数据的推荐方法。</strong></p>
|
||
</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>) [const char *, int 或 <code class="xref c c-type docutils literal notranslate"><span class="pre">Py_ssize_t</span></code>]</dt><dd><p><code class="docutils literal notranslate"><span class="pre">s#</span></code> 的变式，不接受 Unicode 对象，只接受类字节类型变量。</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>要求 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> 对象，不尝试进行任何转换。 如果该对象不为 bytes 对象则会引发 <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>。 C 变量也可被声明为 <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>要求 Python 对象为 <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> 对象，不尝试进行任何转换。 如果该对象不为 <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> 对象则会引发 <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>。 C 变量也可被声明为 <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>将一个 Python Unicode 对象转化成指向一个以空终止的 Unicode 字符缓冲区的指针。你必须传入一个 <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> 指针变量的地址，存储了一个指向已经存在的 Unicode 缓冲区的指针。请注意一个 <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> 类型的字符宽度取决于编译选项(16 位或者 32 位)。Python 字符串必须不能包含嵌入的 null 代码点；如果有，引发一个 <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> 异常。</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">在 3.5 版更改: </span>以前，当 Python 字符串中遇到了嵌入的 null 代码点会引发 <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> 。</p>
|
||
</div>
|
||
<div class="deprecated-removed">
|
||
<p><span class="versionmodified">Deprecated since version 3.3, will be removed in version 3.12: </span>这是旧版样式 <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; 请迁移至 <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 或 <code class="xref c c-type docutils literal notranslate"><span class="pre">Py_ssize_t</span></code>]</dt><dd><p><code class="docutils literal notranslate"><span class="pre">u</span></code> 的变式，存储两个 C 变量，第一个指针指向一个 Unicode 数据缓存区，第二个是它的长度。它允许 null 代码点。</p>
|
||
<div class="deprecated-removed">
|
||
<p><span class="versionmodified">Deprecated since version 3.3, will be removed in version 3.12: </span>这是旧版样式 <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; 请迁移至 <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> 或 <code class="docutils literal notranslate"><span class="pre">None</span></code>) [const Py_UNICODE *]</dt><dd><p>与 <code class="docutils literal notranslate"><span class="pre">u</span></code> 类似，但 Python 对象也可能为 <code class="docutils literal notranslate"><span class="pre">None</span></code>，在这种情况下 <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> 指针设置为 <code class="docutils literal notranslate"><span class="pre">NULL</span></code>。</p>
|
||
<div class="deprecated-removed">
|
||
<p><span class="versionmodified">Deprecated since version 3.3, will be removed in version 3.12: </span>这是旧版样式 <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; 请迁移至 <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> 或 <code class="docutils literal notranslate"><span class="pre">None</span></code>) [const Py_UNICODE *, int 或 <code class="xref c c-type docutils literal notranslate"><span class="pre">Py_ssize_t</span></code>]</dt><dd><p>与 <code class="docutils literal notranslate"><span class="pre">u#</span></code> 类似，但 Python 对象也可能为 <code class="docutils literal notranslate"><span class="pre">None</span></code>，在这种情况下 <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> 指针设置为 <code class="docutils literal notranslate"><span class="pre">NULL</span></code>。</p>
|
||
<div class="deprecated-removed">
|
||
<p><span class="versionmodified">Deprecated since version 3.3, will be removed in version 3.12: </span>这是旧版样式 <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; 请迁移至 <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>要求 Python 对象为 Unicode 对象，不尝试进行任何转换。 如果该对象不为 Unicode 对象则会引发 <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>。 C 变量也可被声明为 <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> (可读写 <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>这个表达式接受任何实现可读写缓存区接口的对象。它为调用者提供的 <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> 结构赋值。缓冲区可能存在嵌入的 null 字节。当缓冲区使用完后调用者需要调用 <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>。</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><code class="docutils literal notranslate"><span class="pre">s</span></code> 的变式，它将编码后的 Unicode 字符存入字符缓冲区。它只处理没有嵌 NUL 字节的已编码数据。</p>
|
||
<p>此格式需要两个参数。 第一个仅用作输入，并且必须为 <code class="xref c c-type docutils literal notranslate"><span class="pre">const</span> <span class="pre">char*</span></code>，它指向一个以 NUL 结束的字符串表示的编码格式名称，或者为 <code class="docutils literal notranslate"><span class="pre">NULL</span></code>，这表示使用 <code class="docutils literal notranslate"><span class="pre">'utf-8'</span></code> 编码格式。 如果为 Python 无法识别的编码格式名称则会引发异常。 第二个参数必须为 <code class="xref c c-type docutils literal notranslate"><span class="pre">char**</span></code>；它所引用的指针值将被设为带有参数文本内容的缓冲区。 文本将以第一个参数所指定的编码格式进行编码。</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> 会分配一个足够大小的缓冲区，将编码后的数据拷贝进这个缓冲区并且设置 <em>*buffer</em> 引用这个新分配的内存空间。调用者有责任在使用后调用 <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> 去释放已经分配的缓冲区。</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>和 <code class="docutils literal notranslate"><span class="pre">es</span></code> 相同，除了不用重编码传入的字符串对象。相反，它假设传入的参数是编码后的字符串类型。</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 或 <code class="xref c c-type docutils literal notranslate"><span class="pre">Py_ssize_t</span></code> *buffer_length]</dt><dd><p><code class="docutils literal notranslate"><span class="pre">s#</span></code> 的变式，它将已编码的 Unicode 字符存入字符缓冲区。不像 <code class="docutils literal notranslate"><span class="pre">es</span></code> 表达式，它允许传入的数据包含 NUL 字符。</p>
|
||
<p>它需要三个参数。 第一个仅用作输入，并且必须为 <code class="xref c c-type docutils literal notranslate"><span class="pre">const</span> <span class="pre">char*</span></code>，它指向一个编码格式名称，形式为以 NUL 结束的字符串或 <code class="docutils literal notranslate"><span class="pre">NULL</span></code>，在后一种情况下将使用 <code class="docutils literal notranslate"><span class="pre">'utf-8'</span></code> 编码格式。 如果编码格式名称无法被 Python 识别则会引发异常。 第二个参数必须为 <code class="xref c c-type docutils literal notranslate"><span class="pre">char**</span></code>；它所引用的指针值将被设为带有参数文本内容的缓冲区。 文本将以第一个参数所指定的编码格式进行编码。 第三个参数必须为指向一个整数的指针；被引用的整数将被设为输出缓冲区中的字节数。</p>
|
||
<p>有两种操作方式：</p>
|
||
<p>如果 <em>*buffer</em> 指向 <code class="docutils literal notranslate"><span class="pre">NULL</span></code> 指针，则函数将分配所需大小的缓冲区，将编码的数据复制到此缓冲区，并设置 <em>*buffer</em> 以引用新分配的存储。 呼叫者负责调用 <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> 以在使用后释放分配的缓冲区。</p>
|
||
<p>如果 <em>*buffer</em> 指向非 <code class="docutils literal notranslate"><span class="pre">NULL</span></code> 指针（已分配的缓冲区），则 <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> 将使用此位置作为缓冲区，并将 <em>*buffer_length</em> 的初始值解释为缓冲区大小。 然后，它将将编码的数据复制到缓冲区，并终止它。 如果缓冲区不够大，将设置一个 <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>。</p>
|
||
<p>在这两个例子中，<em>*buffer_length</em> 被设置为编码后结尾不为 NUL 的数据的长度。</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> 或 <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 或 <code class="xref c c-type docutils literal notranslate"><span class="pre">Py_ssize_t</span></code> *buffer_length]</dt><dd><p>和 <code class="docutils literal notranslate"><span class="pre">es#</span></code> 相同，除了不用重编码传入的字符串对象。相反，它假设传入的参数是编码后的字符串类型。</p>
|
||
</dd>
|
||
</dl>
|
||
</section>
|
||
<section id="numbers">
|
||
<h3>数字<a class="headerlink" href="#numbers" title="永久链接至标题">¶</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>将一个非负的 Python 整型转化成一个无符号的微整型，存储在一个 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>将一个 Python 整型转化成一个微整型并不检查溢出问题，存储在一个 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>将一个 Python 整型转化成一个 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>将一个 Python 整型转化成一个 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> 无符号短整型，并不检查溢出问题。</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>将一个 Python 整型转化成一个 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>将一个 Python 整型转化成一个 C <code class="xref c c-type docutils literal notranslate"><span class="pre">unsigned</span> <span class="pre">int</span></code> 无符号整型，并不检查溢出问题。</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>将一个 Python 整型转化成一个 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>将一个Python整型转化成一个C <code class="xref c c-type docutils literal notranslate"><span class="pre">unsigned</span> <span class="pre">long</span> <span class="pre">int</span></code> 无符号长整型，并不检查溢出问题。</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>将一个 Python 整型转化成一个 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>将一个 Python 整型转化成一个 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> 无符号长长整型，并不检查溢出问题。</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>将一个 Python 整型转化成一个 C <code class="xref c c-type docutils literal notranslate"><span class="pre">Py_ssize_t</span></code> Python 元大小类型。</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> 或者 <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> 长度为 1) [char]</dt><dd><p>将一个 Python 字节类型，如一个长度为 1 的 <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> 或者 <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> 对象，转化成一个 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">在 3.3 版更改: </span>允许 <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>
|
||
</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> 长度为 1) [int]</dt><dd><p>将一个 Python 字符，如一个长度为 1 的 <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> 字符串对象，转化成一个 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>将一个 Python 浮点数转化成一个 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>将一个Python浮点数转化成一个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>将一个 Python 复数类型转化成一个 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> Python 复数类型。</p>
|
||
</dd>
|
||
</dl>
|
||
</section>
|
||
<section id="other-objects">
|
||
<h3>其他对象<a class="headerlink" href="#other-objects" title="永久链接至标题">¶</a></h3>
|
||
<dl class="simple">
|
||
<dt><code class="docutils literal notranslate"><span class="pre">O</span></code> (object) [PyObject *]</dt><dd><p>将 Python 对象（不进行任何转换）存储在 C 对象指针中。 因此，C 程序接收已传递的实际对象。 对象的引用计数不会增加。 存储的指针不是 <code class="docutils literal notranslate"><span class="pre">NULL</span></code>。</p>
|
||
</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">O!</span></code> (object) [<em>typeobject</em>, PyObject *]</dt><dd><p>将一个 Python 对象存入一个 C 对象指针。 这类似于 <code class="docutils literal notranslate"><span class="pre">O</span></code>，但是接受两个 C 参数：第一个是 Python 类型对象的地址，第二个是存储对象指针的 C 变量 (类型为 <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>) 的地址。 如果 Python 对象不具有所要求的类型，则会引发 <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>。</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>通过一个 <em>converter</em> 函数将一个 Python 对象转换为一个 C 变量。 此函数接受两个参数：第一个是函数，第二个是 C 变量 (类型任意) 的地址，转换为 <code class="xref c c-type docutils literal notranslate"><span class="pre">void</span> <span class="pre">*</span></code> 类型。 <em>converter</em> 函数将以如下方式被调用:</p>
|
||
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n">status</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">converter</span><span class="p">(</span><span class="n">object</span><span class="p">,</span><span class="w"> </span><span class="n">address</span><span class="p">);</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>其中 <em>object</em> 是待转换的 Python 对象而 <em>address</em> 为传给 <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> 函数的 <code class="xref c c-type docutils literal notranslate"><span class="pre">void*</span></code> 参数。 返回的 <em>status</em> 应当以 <code class="docutils literal notranslate"><span class="pre">1</span></code> 代表转换成功而以 <code class="docutils literal notranslate"><span class="pre">0</span></code> 代表转换失败。 当转换失败时，<em>converter</em> 函数应当引发异常并且会让 <em>address</em> 的内容保持未修改状态。</p>
|
||
<p>如果 <em>converter</em> 返回 <code class="docutils literal notranslate"><span class="pre">Py_CLEANUP_SUPPORTED</span></code> ，则如果参数解析最终失败，它可能会再次调用该函数，从而使转换器有机会释放已分配的任何内存。在第二个调用中，<em>object</em> 参数将为 <code class="docutils literal notranslate"><span class="pre">NULL</span></code> ;因此，该参数将为 <code class="docutils literal notranslate"><span class="pre">NULL</span></code> ;因此，该参数将为 <code class="docutils literal notranslate"><span class="pre">NULL</span></code> ，因此，该参数将为 <code class="docutils literal notranslate"><span class="pre">NULL</span></code> （如果值）为 <code class="docutils literal notranslate"><span class="pre">NULL</span></code> <em>address</em> 的值与原始呼叫中的值相同。</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">在 3.1 版更改: </span><code class="docutils literal notranslate"><span class="pre">Py_CLEANUP_SUPPORTED</span></code> 被添加。</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>测试传入的值是否为真(一个布尔判断)并且将结果转化为相对应的 C true/false 整型值。如果表达式为真置 <code class="docutils literal notranslate"><span class="pre">1</span></code>，假则置 <code class="docutils literal notranslate"><span class="pre">0</span></code>。它接受任何合法的 Python 值。参见 <a class="reference internal" href="../library/stdtypes.html#truth"><span class="std std-ref">逻辑值检测</span></a> 获取更多关于 Python 如何测试值为真的信息。</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">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>对象必须是 Python 序列，它的长度是 <em>items</em> 中格式单元的数量。C 参数必须对应 <em>items</em> 中每一个独立的格式单元。序列中的格式单元可能有嵌套。</p>
|
||
</dd>
|
||
</dl>
|
||
<p>传递 "long" 整型(整型的值超过了平台的 <code class="xref py py-const docutils literal notranslate"><span class="pre">LONG_MAX</span></code> 限制)是可能的，然而没有进行适当的范围检测——当接收字段太小而接收不到值时，最重要的位被静默地截断(实际上，C 语言会在语义继承的基础上强制类型转换——期望的值可能会发生变化)。</p>
|
||
<p>格式化字符串中还有一些其他的字符具有特殊的涵义。这些可能并不嵌套在圆括号中。它们是：</p>
|
||
<dl>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">|</span></code></dt><dd><p>表明在 Python 参数列表中剩下的参数都是可选的。C 变量对应的可选参数需要初始化为默认值——当一个可选参数没有指定时， <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> 不能访问相应的 C 变量(变量集)的内容。</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：表明在 Python 参数列表中剩下的参数都是强制关键字参数。当前，所有强制关键字参数都必须也是可选参数，所以格式化字符串中 <code class="docutils literal notranslate"><span class="pre">|</span></code> 必须一直在 <code class="docutils literal notranslate"><span class="pre">$</span></code> 前面。</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">3.3 新版功能.</span></p>
|
||
</div>
|
||
</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">:</span></code></dt><dd><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> 函数引发的“关联值”异常)。</p>
|
||
</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">;</span></code></dt><dd><p>格式单元的列表结束标志；分号后的字符串被用来作为错误消息取代默认的错误消息。 <code class="docutils literal notranslate"><span class="pre">:</span></code> 和 <code class="docutils literal notranslate"><span class="pre">;</span></code> 相互排斥。</p>
|
||
</dd>
|
||
</dl>
|
||
<p>注意任何由调用者提供的 Python 对象引用是 <em>借来的</em> 引用；不要递减它们的引用计数！</p>
|
||
<p>传递给这些函数的附加参数必须是由格式化字符串确定的变量的地址；这些都是用来存储输入元组的值。有一些情况，如上面的格式单元列表中所描述的，这些参数作为输入值使用；在这种情况下，它们应该匹配指定的相应的格式单元。</p>
|
||
<p>为了转换成功，<em>arg</em> 对象必须匹配格式并且格式必须用尽。成功的话，<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> 函数返回 true，反之它们返回 false 并且引发一个合适的异常。当 <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> 函数因为某一个格式单元转化失败而失败时，对应的以及后续的格式单元地址内的变量都不会被使用。</p>
|
||
</section>
|
||
<section id="api-functions">
|
||
<h3>API 函数<a class="headerlink" href="#api-functions" title="永久链接至标题">¶</a></h3>
|
||
<dl class="function">
|
||
<dt id="c.PyArg_ParseTuple">
|
||
int <code class="sig-name 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="永久链接至目标">¶</a></dt>
|
||
<dd><p>解析一个函数的参数，表达式中的参数按参数位置顺序存入局部变量中。成功返回 true；失败返回 false 并且引发相应的异常。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="c.PyArg_VaParse">
|
||
int <code class="sig-name 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="永久链接至目标">¶</a></dt>
|
||
<dd><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> 相同，然而它接受一个 va_list 类型的参数而不是可变数量的参数集。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="c.PyArg_ParseTupleAndKeywords">
|
||
int <code class="sig-name 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="永久链接至目标">¶</a></dt>
|
||
<dd><p>分析将位置参数和关键字参数同时转换为局部变量的函数的参数。 <em>keywords</em> 参数是关键字参数名称的 <code class="docutils literal notranslate"><span class="pre">NULL</span></code> 终止数组。 空名称表示 <a class="reference internal" href="../glossary.html#positional-only-parameter"><span class="std std-ref">positional-only parameters</span></a>。成功时返回 true;发生故障时，它将返回 false 并引发相应的异常。</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">在 3.6 版更改: </span>添加了 <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="sig-name 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="永久链接至目标">¶</a></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> 相同，然而它接受一个va_list类型的参数而不是可变数量的参数集。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="c.PyArg_ValidateKeywordArguments">
|
||
int <code class="sig-name 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="永久链接至目标">¶</a></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> 不被使用的情况下，后者已经不再做这样的检查。</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">3.2 新版功能.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="c.PyArg_Parse">
|
||
int <code class="sig-name 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="永久链接至目标">¶</a></dt>
|
||
<dd><p>函数被用来析构“旧类型”函数的参数列表——这些函数使用的 <code class="xref py py-const docutils literal notranslate"><span class="pre">METH_OLDARGS</span></code> 参数解析方法已从 Python 3 中移除。这不被推荐用于新代码的参数解析，并且在标准解释器中的大多数代码已被修改，已不再用于该目的。它仍然方便于分解其他元组，然而可能因为这个目的被继续使用。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="c.PyArg_UnpackTuple">
|
||
int <code class="sig-name 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="永久链接至目标">¶</a></dt>
|
||
<dd><p>一个更简单的参数提取方式，它不使用格式字符串来指定参数类型。 使用这种方法来提取参数的函数应当在函数或方法表中被声明为 <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>。 包含实际参数的元组应当作为 <em>args</em> 传入；它必须确实是一个元组。 元组的长度必须至少为 <em>min</em> 并且不超过 <em>max</em>；<em>min</em> 和 <em>max</em> 可能相等。 额外的参数必须被传入函数，每个参数必须是一个指向 <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> 变量的指针；它们将以来自 <em>args</em> 的值填充；它们将包含暂借的引用。 对应于可选参数的变量不会由 <em>args</em> 给出的值填充；它们将由调用者来初始化。 此函数执行成功时返回真值，如果 <em>args</em> 不是元组或者包含错误数量的元素则返回假值；如果执行失败则将设置一个异常。</p>
|
||
<p>这是一个使用此函数的示例，取自 <code class="xref py py-mod docutils literal notranslate"><span class="pre">_weakref</span></code> 帮助模块用来弱化引用的源代码：</p>
|
||
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="k">static</span><span class="w"> </span><span class="n">PyObject</span><span class="w"> </span><span class="o">*</span>
|
||
<span class="nf">weakref_ref</span><span class="p">(</span><span class="n">PyObject</span><span class="w"> </span><span class="o">*</span><span class="n">self</span><span class="p">,</span><span class="w"> </span><span class="n">PyObject</span><span class="w"> </span><span class="o">*</span><span class="n">args</span><span class="p">)</span>
|
||
<span class="p">{</span>
|
||
<span class="w"> </span><span class="n">PyObject</span><span class="w"> </span><span class="o">*</span><span class="n">object</span><span class="p">;</span>
|
||
<span class="w"> </span><span class="n">PyObject</span><span class="w"> </span><span class="o">*</span><span class="n">callback</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nb">NULL</span><span class="p">;</span>
|
||
<span class="w"> </span><span class="n">PyObject</span><span class="w"> </span><span class="o">*</span><span class="n">result</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nb">NULL</span><span class="p">;</span>
|
||
|
||
<span class="w"> </span><span class="k">if</span><span class="w"> </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="w"> </span><span class="s">"ref"</span><span class="p">,</span><span class="w"> </span><span class="mi">1</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="o">&</span><span class="n">object</span><span class="p">,</span><span class="w"> </span><span class="o">&</span><span class="n">callback</span><span class="p">))</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="n">result</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">PyWeakref_NewRef</span><span class="p">(</span><span class="n">object</span><span class="p">,</span><span class="w"> </span><span class="n">callback</span><span class="p">);</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="w"> </span><span class="k">return</span><span class="w"> </span><span class="n">result</span><span class="p">;</span>
|
||
<span class="p">}</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>这个例子中调用 <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> 完全等价于调用 <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="w"> </span><span class="s">"O|O:ref"</span><span class="p">,</span><span class="w"> </span><span class="o">&</span><span class="n">object</span><span class="p">,</span><span class="w"> </span><span class="o">&</span><span class="n">callback</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
</section>
|
||
</section>
|
||
<section id="building-values">
|
||
<h2>创建变量<a class="headerlink" href="#building-values" title="永久链接至标题">¶</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="sig-name 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="永久链接至目标">¶</a></dt>
|
||
<dd><em class="refcount">Return value: New reference.</em><p>基于类似于 <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> 函数系列和一系列值的格式字符串创建新值。 在出现错误时返回值或 <code class="docutils literal notranslate"><span class="pre">NULL</span></code>;如果返回 <code class="docutils literal notranslate"><span class="pre">NULL</span></code>，将引发异常。</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> 并不一直创建一个元组。只有当它的格式化字符串包含两个或更多的格式单元才会创建一个元组。如果格式化字符串是空，它返回 <code class="docutils literal notranslate"><span class="pre">None</span></code>；如果它包含一个格式单元，它返回由格式单元描述的的任一对象。用圆括号包裹格式化字符串可以强制它返回一个大小为 0 或者 1 的元组。</p>
|
||
<p>当内存缓存区的数据以参数形式传递用来构建对象时，如 <code class="docutils literal notranslate"><span class="pre">s</span></code> 和 <code class="docutils literal notranslate"><span class="pre">s#</span></code> 格式单元，会拷贝需要的数据。调用者提供的缓冲区从来都不会被由 <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> 创建的对象来引用。换句话说，如果你的代码调用 <code class="xref c c-func docutils literal notranslate"><span class="pre">malloc()</span></code> 并且将分配的内存空间传递给 <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>，你的代码就有责任在 <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> 返回时调用 <code class="xref c c-func docutils literal notranslate"><span class="pre">free()</span></code> 。</p>
|
||
<p>在下面的描述中，双引号的表达式使格式单元；圆括号 () 内的是格式单元将要返回的 Python 对象类型；方括号 [] 内的是传递的 C 变量(变量集)的类型。</p>
|
||
<p>字符例如空格，制表符，冒号和逗号在格式化字符串中会被忽略(但是不包括格式单元，如 <code class="docutils literal notranslate"><span class="pre">s#</span></code>)。这可以使很长的格式化字符串具有更好的可读性。</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> 或 <code class="docutils literal notranslate"><span class="pre">None</span></code>) [const char *]</dt><dd><p>使用 <code class="docutils literal notranslate"><span class="pre">'utf-8'</span></code> 编码将空终止的 C 字符串转换为 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> 对象。如果 C 字符串指针为 <code class="docutils literal notranslate"><span class="pre">NULL</span></code>，则使用 <code class="docutils literal notranslate"><span class="pre">None</span></code>。</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> 或 <code class="docutils literal notranslate"><span class="pre">None</span></code>) [const char *, int 或 <code class="xref c c-type docutils literal notranslate"><span class="pre">Py_ssize_t</span></code>]</dt><dd><p>使用 <code class="docutils literal notranslate"><span class="pre">'utf-8'</span></code> 编码将 C 字符串及其长度转换为 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> 对象。如果 C 字符串指针为 <code class="docutils literal notranslate"><span class="pre">NULL</span></code>，则长度将被忽略，并返回 <code class="docutils literal notranslate"><span class="pre">None</span></code>。</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>这将 C 字符串转换为 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> 对象。 如果 C 字符串指针为 <code class="docutils literal notranslate"><span class="pre">NULL</span></code>，则返回 <code class="docutils literal notranslate"><span class="pre">None</span></code>。</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 或 <code class="xref c c-type docutils literal notranslate"><span class="pre">Py_ssize_t</span></code>]</dt><dd><p>这会将 C 字符串及其长度转换为一个 Python 对象。 如果该 C 字符串指针为 <code class="docutils literal notranslate"><span class="pre">NULL</span></code>，则返回 <code class="docutils literal notranslate"><span class="pre">None</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 *]</dt><dd><p>和 <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> 或 <code class="docutils literal notranslate"><span class="pre">None</span></code>) [const char *, int 或 <code class="xref c c-type docutils literal notranslate"><span class="pre">Py_ssize_t</span></code>]</dt><dd><p>和 <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>将空终止的 <code class="xref c c-type docutils literal notranslate"><span class="pre">wchar_t</span></code> 的 Unicode （UTF-16 或 UCS-4） 数据缓冲区转换为 Python Unicode 对象。 如果 Unicode 缓冲区指针为 <code class="docutils literal notranslate"><span class="pre">NULL</span></code>，则返回 <code class="docutils literal notranslate"><span class="pre">None</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 *, int 或 <code class="xref c c-type docutils literal notranslate"><span class="pre">Py_ssize_t</span></code>]</dt><dd><p>将 Unicode （UTF-16 或 UCS-4） 数据缓冲区及其长度转换为 Python Unicode 对象。 如果 Unicode 缓冲区指针为 <code class="docutils literal notranslate"><span class="pre">NULL</span></code>，则长度将被忽略，并返回 <code class="docutils literal notranslate"><span class="pre">None</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> 或 <code class="docutils literal notranslate"><span class="pre">None</span></code>) [const char *]</dt><dd><p>和 <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> 或 <code class="docutils literal notranslate"><span class="pre">None</span></code>) [const char *, int 或 <code class="xref c c-type docutils literal notranslate"><span class="pre">Py_ssize_t</span></code>]</dt><dd><p>和 <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>将一个 C <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span></code> 整型转化成 Python 整型对象。</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>将一个 C <code class="xref c c-type docutils literal notranslate"><span class="pre">char</span></code> 字符型转化成 Python 整型对象。</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>将一个 C <code class="xref c c-type docutils literal notranslate"><span class="pre">short</span> <span class="pre">int</span></code> 短整型转化成 Python 整型对象。</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>将一个 C <code class="xref c c-type docutils literal notranslate"><span class="pre">long</span> <span class="pre">int</span></code> 长整型转化成 Python 整型对象。</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>将一个 C <code class="xref c c-type docutils literal notranslate"><span class="pre">unsigned</span> <span class="pre">char</span></code> 无符号字符型转化成 Python 整型对象。</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>将一个 C <code class="xref c c-type docutils literal notranslate"><span class="pre">unsigned</span> <span class="pre">long</span></code> 无符号短整型转化成 Python 整型对象。</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>将一个 C <code class="xref c c-type docutils literal notranslate"><span class="pre">unsigned</span> <span class="pre">long</span></code> 无符号整型转化成 Python 整型对象。</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>将一个 C <code class="xref c c-type docutils literal notranslate"><span class="pre">unsigned</span> <span class="pre">long</span></code> 无符号长整型转化成 Python 整型对象。</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>将一个 C <code class="xref c c-type docutils literal notranslate"><span class="pre">long</span> <span class="pre">long</span></code> 长长整形转化成 Python 整形对象。</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>将一个 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> 无符号长长整型转化成 Python 整型对象。</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>将一个 C <code class="xref c c-type docutils literal notranslate"><span class="pre">Py_ssize_t</span></code> 类型转化为 Python 整型。</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> 长度为1 ) [char]</dt><dd><p>将一个 C <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span></code> 整型代表的字符转化为 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> 长度为 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> 长度为 1) [int]</dt><dd><p>将一个 C <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span></code> 整型代表的字符转化为 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> 长度为 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>将一个 C <code class="xref c c-type docutils literal notranslate"><span class="pre">double</span></code> 双精度浮点数转化为 Python 浮点数类型数字。</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>将一个 C <code class="xref c c-type docutils literal notranslate"><span class="pre">float</span></code> 单精度浮点数转化为 Python 浮点数类型数字。</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>将一个 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> 类型的结构转化为 Python 复数类型。</p>
|
||
</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">O</span></code> (object) [PyObject *]</dt><dd><p>将 Python 对象传递不变（其引用计数除外，该计数由 1 递增）。 如果传入的对象是 <code class="docutils literal notranslate"><span class="pre">NULL</span></code> 指针，则假定这是由于生成参数的调用发现错误并设置异常而引起的。因此，<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> 将返回 <code class="docutils literal notranslate"><span class="pre">NULL</span></code>，但不会引发异常。 如果尚未引发异常，则设置 <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>。</p>
|
||
</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">S</span></code> (object) [PyObject *]</dt><dd><p>和 <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>和 <code class="docutils literal notranslate"><span class="pre">O</span></code> 相同，然而它并不增加对象的引用计数。当通过调用参数列表中的对象构造器创建对象时很实用。</p>
|
||
</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">O&</span></code> (object) [<em>converter</em>, <em>anything</em>]</dt><dd><p>通过 <em>converter</em> 函数将 <em>anything</em> 转换为 Python 对象。 该函数调用时会传入 <em>anything</em> (应与 <code class="xref c c-type docutils literal notranslate"><span class="pre">void*</span></code> 兼容) 作为参数并且应当返回一个“新的”Python 对象，或者当发生错误时返回 <code class="docutils literal notranslate"><span class="pre">NULL</span></code>。</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>将一个 C 变量序列转换成 Python 元组并保持相同的元素数量。</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>相关的元素</em>]</dt><dd><p>将一个 C 变量序列转换成 Python 列表并保持相同的元素数量。</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>相关的元素</em>]</dt><dd><p>将一个C变量序列转换成 Python 字典。每一对连续的 C 变量对作为一个元素插入字典中，分别作为关键字和值。</p>
|
||
</dd>
|
||
</dl>
|
||
<p>如果格式字符串中出现错误，则设置 <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> 异常并返回 <code class="docutils literal notranslate"><span class="pre">NULL</span></code>。</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="sig-name 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="永久链接至目标">¶</a></dt>
|
||
<dd><em class="refcount">Return value: New reference.</em><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> 相同，然而它接受一个 va_list 类型的参数而不是可变数量的参数集。</p>
|
||
</dd></dl>
|
||
|
||
</section>
|
||
</section>
|
||
|
||
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
|
||
<div class="sphinxsidebarwrapper">
|
||
<h3><a href="../contents.html">目录</a></h3>
|
||
<ul>
|
||
<li><a class="reference internal" href="#">解析参数并构建值变量</a><ul>
|
||
<li><a class="reference internal" href="#parsing-arguments">解析参数</a><ul>
|
||
<li><a class="reference internal" href="#strings-and-buffers">字符串和缓存区</a></li>
|
||
<li><a class="reference internal" href="#numbers">数字</a></li>
|
||
<li><a class="reference internal" href="#other-objects">其他对象</a></li>
|
||
<li><a class="reference internal" href="#api-functions">API 函数</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#building-values">创建变量</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
|
||
<h4>上一个主题</h4>
|
||
<p class="topless"><a href="marshal.html"
|
||
title="上一章">数据 marshal 操作支持</a></p>
|
||
<h4>下一个主题</h4>
|
||
<p class="topless"><a href="conversion.html"
|
||
title="下一章">字符串转换与格式化</a></p>
|
||
<div role="note" aria-label="source link">
|
||
<h3>本页</h3>
|
||
<ul class="this-page-menu">
|
||
<li><a href="../bugs.html">报告 Bug</a></li>
|
||
<li>
|
||
<a href="https://github.com/python/cpython/blob/3.8/Doc/c-api/arg.rst"
|
||
rel="nofollow">显示源代码
|
||
</a>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="clearer"></div>
|
||
</div>
|
||
<div class="related" role="navigation" aria-label="related navigation">
|
||
<h3>导航</h3>
|
||
<ul>
|
||
<li class="right" style="margin-right: 10px">
|
||
<a href="../genindex.html" title="总目录"
|
||
>索引</a></li>
|
||
<li class="right" >
|
||
<a href="../py-modindex.html" title="Python 模块索引"
|
||
>模块</a> |</li>
|
||
<li class="right" >
|
||
<a href="conversion.html" title="字符串转换与格式化"
|
||
>下一页</a> |</li>
|
||
<li class="right" >
|
||
<a href="marshal.html" title="数据 marshal 操作支持"
|
||
>上一页</a> |</li>
|
||
|
||
<li><img src="../_static/py.svg" alt="python logo" style="vertical-align: middle; margin-top: -1px"/></li>
|
||
<li><a href="https://www.python.org/">Python</a> »</li>
|
||
<li class="switchers">
|
||
<div class="language_switcher_placeholder"></div>
|
||
<div class="version_switcher_placeholder"></div>
|
||
</li>
|
||
<li>
|
||
|
||
</li>
|
||
<li id="cpython-language-and-version">
|
||
<a href="../index.html">3.8.20 Documentation</a> »
|
||
</li>
|
||
|
||
<li class="nav-item nav-item-1"><a href="index.html" >Python/C API 参考手册</a> »</li>
|
||
<li class="nav-item nav-item-2"><a href="utilities.html" >工具</a> »</li>
|
||
<li class="right">
|
||
|
||
|
||
<div class="inline-search" role="search">
|
||
<form class="inline-search" action="../search.html" method="get">
|
||
<input placeholder="快速搜索" aria-label="快速搜索" type="text" name="q" />
|
||
<input type="submit" value="转向" />
|
||
<input type="hidden" name="check_keywords" value="yes" />
|
||
<input type="hidden" name="area" value="default" />
|
||
</form>
|
||
</div>
|
||
|
|
||
</li>
|
||
|
||
</ul>
|
||
</div>
|
||
<div class="footer">
|
||
© <a href="../copyright.html">版权所有</a> 2001-2024, Python Software Foundation.
|
||
<br />
|
||
This page is licensed under the Python Software Foundation License Version 2.
|
||
<br />
|
||
Examples, recipes, and other code in the documentation are additionally licensed under the Zero Clause BSD License.
|
||
<br />
|
||
|
||
<br />
|
||
|
||
The Python Software Foundation is a non-profit corporation.
|
||
<a href="https://www.python.org/psf/donations/">Please donate.</a>
|
||
<br />
|
||
<br />
|
||
|
||
最后更新于 12月 09, 2024.
|
||
<a href="https://docs.python.org/3/bugs.html">Found a bug</a>?
|
||
<br />
|
||
|
||
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 2.4.4.
|
||
</div>
|
||
|
||
</body>
|
||
</html> |