01d8bae291b1e4724443375634ccfa0e

Edit file

File name : call.html

Content :

<!DOCTYPE html>

<title>Call Protocol &#8212; Python 3.10.12 documentation</title><meta name="viewport" content="width=device-width, initial-scale=1.0">
 
 <link rel="stylesheet" type="text/css" href="../_static/pygments.css" />
 <link rel="stylesheet" type="text/css" href="../_static/pydoctheme.css?2022.1" />
 
 <script data-url_root="../" id="documentation_options" 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/sidebar.js"></script>
 
 <link rel="search" type="application/opensearchdescription+xml"
 title="Search within Python 3.10.12 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="Number Protocol" href="number.html" />
 <link rel="prev" title="Object Protocol" href="object.html" />
 <link rel="canonical" href="file:///usr/share/doc/python3.10/html/c-api/call.html" />

</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">
 
 </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="Quick search"/>
 <input type="submit" value="Go"/>
 </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">Table of Contents</a></h3>
 <ul>
<li><a class="reference internal" href="#">Call Protocol</a><ul>
<li><a class="reference internal" href="#the-tp-call-protocol">The tp_call Protocol</a></li>
<li><a class="reference internal" href="#the-vectorcall-protocol">The Vectorcall Protocol</a><ul>
<li><a class="reference internal" href="#recursion-control">Recursion Control</a></li>
<li><a class="reference internal" href="#vectorcall-support-api">Vectorcall Support API</a></li>
</ul>
</li>
<li><a class="reference internal" href="#object-calling-api">Object Calling API</a></li>
<li><a class="reference internal" href="#call-support-api">Call Support API</a></li>
</ul>
</li>
</ul>

<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="number.html" title="Number Protocol"
 accesskey="N">next</a> |</li>
 <li class="right" >
 <a href="object.html" title="Object Protocol"
 accesskey="P">previous</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> &#187;</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.10.12 Documentation</a> &#187;
 </li>

<li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> &#187;</li>
 <li class="nav-item nav-item-2"><a href="abstract.html" accesskey="U">Abstract Objects Layer</a> &#187;</li>
 <li class="nav-item nav-item-this"><a href="">Call Protocol</a></li>
 <li class="right">

<div class="document">
 <div class="documentwrapper">
 <div class="bodywrapper">
 <div class="body" role="main">
 
 <section id="call-protocol">
<h1>Call Protocol<a class="headerlink" href="#call-protocol" title="Permalink to this headline">¶</a></h1>
CPython supports two different calling protocols:
tp_call and vectorcall.
<section id="the-tp-call-protocol">
<h2>The tp_call Protocol<a class="headerlink" href="#the-tp-call-protocol" title="Permalink to this headline">¶</a></h2>
Instances of classes that set <a class="reference internal" href="typeobj.html#c.PyTypeObject.tp_call" title="PyTypeObject.tp_call"><code class="xref c c-member docutils literal notranslate">tp_call</code></a> are callable.
The signature of the slot is:
<div class="highlight-c notranslate"><div class="highlight"><pre>PyObject *tp_call(PyObject *callable, PyObject *args, PyObject *kwargs);
</pre></div>
</div>
A call is made using a tuple for the positional arguments
and a dict for the keyword arguments, similarly to
<code class="docutils literal notranslate">callable(*args, **kwargs)</code> in Python code.
args must be non-NULL (use an empty tuple if there are no arguments)
but kwargs may be NULL if there are no keyword arguments.
This convention is not only used by tp_call:
<a class="reference internal" href="typeobj.html#c.PyTypeObject.tp_new" title="PyTypeObject.tp_new"><code class="xref c c-member docutils literal notranslate">tp_new</code></a> and <a class="reference internal" href="typeobj.html#c.PyTypeObject.tp_init" title="PyTypeObject.tp_init"><code class="xref c c-member docutils literal notranslate">tp_init</code></a>
also pass arguments this way.
To call an object, use <a class="reference internal" href="#c.PyObject_Call" title="PyObject_Call"><code class="xref c c-func docutils literal notranslate">PyObject_Call()</code></a> or another
<a class="reference internal" href="#capi-call">call API</a>.
</section>
<section id="the-vectorcall-protocol">
<h2>The Vectorcall Protocol<a class="headerlink" href="#the-vectorcall-protocol" title="Permalink to this headline">¶</a></h2>
<div class="versionadded">
New in version 3.9.
</div>
The vectorcall protocol was introduced in <a class="pep reference external" href="https://www.python.org/dev/peps/pep-0590">PEP 590</a> as an additional protocol
for making calls more efficient.
As rule of thumb, CPython will prefer the vectorcall for internal calls
if the callable supports it. However, this is not a hard rule.
Additionally, some third-party extensions use tp_call directly
(rather than using <a class="reference internal" href="#c.PyObject_Call" title="PyObject_Call"><code class="xref c c-func docutils literal notranslate">PyObject_Call()</code></a>).
Therefore, a class supporting vectorcall must also implement
<a class="reference internal" href="typeobj.html#c.PyTypeObject.tp_call" title="PyTypeObject.tp_call"><code class="xref c c-member docutils literal notranslate">tp_call</code></a>.
Moreover, the callable must behave the same
regardless of which protocol is used.
The recommended way to achieve this is by setting
<a class="reference internal" href="typeobj.html#c.PyTypeObject.tp_call" title="PyTypeObject.tp_call"><code class="xref c c-member docutils literal notranslate">tp_call</code></a> to <a class="reference internal" href="#c.PyVectorcall_Call" title="PyVectorcall_Call"><code class="xref c c-func docutils literal notranslate">PyVectorcall_Call()</code></a>.
This bears repeating:
<div class="admonition warning">
Warning
A class supporting vectorcall must also implement
<a class="reference internal" href="typeobj.html#c.PyTypeObject.tp_call" title="PyTypeObject.tp_call"><code class="xref c c-member docutils literal notranslate">tp_call</code></a> with the same semantics.
</div>
A class should not implement vectorcall if that would be slower
than tp_call. For example, if the callee needs to convert
the arguments to an args tuple and kwargs dict anyway, then there is no point
in implementing vectorcall.
Classes can implement the vectorcall protocol by enabling the
<a class="reference internal" href="typeobj.html#Py_TPFLAGS_HAVE_VECTORCALL" title="Py_TPFLAGS_HAVE_VECTORCALL"><code class="xref py py-const docutils literal notranslate">Py_TPFLAGS_HAVE_VECTORCALL</code></a> flag and setting
<a class="reference internal" href="typeobj.html#c.PyTypeObject.tp_vectorcall_offset" title="PyTypeObject.tp_vectorcall_offset"><code class="xref c c-member docutils literal notranslate">tp_vectorcall_offset</code></a> to the offset inside the
object structure where a vectorcallfunc appears.
This is a pointer to a function with the following signature:
<dl class="c type">
<dt class="sig sig-object c" id="c.vectorcallfunc">
typedef <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *(*vectorcallfunc)(<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *callable, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *const *args, size_t nargsf, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *kwnames)<a class="headerlink" href="#c.vectorcallfunc" title="Permalink to this definition">¶</a> </dt>
<dd></dd></dl>

<ul class="simple">
<li>callable is the object being called.</li>
<li><dl class="simple">
<dt>args is a C array consisting of the positional arguments followed by the</dt><dd>values of the keyword arguments.
This can be NULL if there are no arguments.
</dd>
</dl>
</li>
<li><dl class="simple">
<dt>nargsf is the number of positional arguments plus possibly the</dt><dd><code class="xref py py-const docutils literal notranslate">PY_VECTORCALL_ARGUMENTS_OFFSET</code> flag.
To get the actual number of positional arguments from nargsf,
use <a class="reference internal" href="#c.PyVectorcall_NARGS" title="PyVectorcall_NARGS"><code class="xref c c-func docutils literal notranslate">PyVectorcall_NARGS()</code></a>.
</dd>
</dl>
</li>
<li><dl class="simple">
<dt>kwnames is a tuple containing the names of the keyword arguments;</dt><dd>in other words, the keys of the kwargs dict.
These names must be strings (instances of <code class="docutils literal notranslate">str</code> or a subclass)
and they must be unique.
If there are no keyword arguments, then kwnames can instead be NULL.
</dd>
</dl>
</li>
</ul>
<dl class="c macro">
<dt class="sig sig-object c" id="c.PY_VECTORCALL_ARGUMENTS_OFFSET">
PY_VECTORCALL_ARGUMENTS_OFFSET<a class="headerlink" href="#c.PY_VECTORCALL_ARGUMENTS_OFFSET" title="Permalink to this definition">¶</a> </dt>
<dd>If this flag is set in a vectorcall nargsf argument, the callee is allowed
to temporarily change <code class="docutils literal notranslate">args[-1]</code>. In other words, args points to
argument 1 (not 0) in the allocated vector.
The callee must restore the value of <code class="docutils literal notranslate">args[-1]</code> before returning.
For <a class="reference internal" href="#c.PyObject_VectorcallMethod" title="PyObject_VectorcallMethod"><code class="xref c c-func docutils literal notranslate">PyObject_VectorcallMethod()</code></a>, this flag means instead that
<code class="docutils literal notranslate">args[0]</code> may be changed.
Whenever they can do so cheaply (without additional allocation), callers
are encouraged to use <code class="xref py py-const docutils literal notranslate">PY_VECTORCALL_ARGUMENTS_OFFSET</code>.
Doing so will allow callables such as bound methods to make their onward
calls (which include a prepended self argument) very efficiently.
</dd></dl>

To call an object that implements vectorcall, use a <a class="reference internal" href="#capi-call">call API</a>
function as with any other callable.
<a class="reference internal" href="#c.PyObject_Vectorcall" title="PyObject_Vectorcall"><code class="xref c c-func docutils literal notranslate">PyObject_Vectorcall()</code></a> will usually be most efficient.
<div class="admonition note">
Note
In CPython 3.8, the vectorcall API and related functions were available
provisionally under names with a leading underscore:
<code class="docutils literal notranslate">_PyObject_Vectorcall</code>, <code class="docutils literal notranslate">_Py_TPFLAGS_HAVE_VECTORCALL</code>,
<code class="docutils literal notranslate">_PyObject_VectorcallMethod</code>, <code class="docutils literal notranslate">_PyVectorcall_Function</code>,
<code class="docutils literal notranslate">_PyObject_CallOneArg</code>, <code class="docutils literal notranslate">_PyObject_CallMethodNoArgs</code>,
<code class="docutils literal notranslate">_PyObject_CallMethodOneArg</code>.
Additionally, <code class="docutils literal notranslate">PyObject_VectorcallDict</code> was available as
<code class="docutils literal notranslate">_PyObject_FastCallDict</code>.
The old names are still defined as aliases of the new, non-underscored names.
</div>
<section id="recursion-control">
<h3>Recursion Control<a class="headerlink" href="#recursion-control" title="Permalink to this headline">¶</a></h3>
When using tp_call, callees do not need to worry about
<a class="reference internal" href="exceptions.html#recursion">recursion</a>: CPython uses
<a class="reference internal" href="exceptions.html#c.Py_EnterRecursiveCall" title="Py_EnterRecursiveCall"><code class="xref c c-func docutils literal notranslate">Py_EnterRecursiveCall()</code></a> and <a class="reference internal" href="exceptions.html#c.Py_LeaveRecursiveCall" title="Py_LeaveRecursiveCall"><code class="xref c c-func docutils literal notranslate">Py_LeaveRecursiveCall()</code></a>
for calls made using tp_call.
For efficiency, this is not the case for calls done using vectorcall:
the callee should use Py_EnterRecursiveCall and Py_LeaveRecursiveCall
if needed.
</section>
<section id="vectorcall-support-api">
<h3>Vectorcall Support API<a class="headerlink" href="#vectorcall-support-api" title="Permalink to this headline">¶</a></h3>
<dl class="c function">
<dt class="sig sig-object c" id="c.PyVectorcall_NARGS">
<a class="reference internal" href="intro.html#c.Py_ssize_t" title="Py_ssize_t">Py_ssize_t</a> PyVectorcall_NARGS(size_t nargsf)<a class="headerlink" href="#c.PyVectorcall_NARGS" title="Permalink to this definition">¶</a> </dt>
<dd>Given a vectorcall nargsf argument, return the actual number of
arguments.
Currently equivalent to:
<div class="highlight-c notranslate"><div class="highlight"><pre>(Py_ssize_t)(nargsf &amp; ~PY_VECTORCALL_ARGUMENTS_OFFSET)
</pre></div>
</div>
However, the function <code class="docutils literal notranslate">PyVectorcall_NARGS</code> should be used to allow
for future extensions.
<div class="versionadded">
New in version 3.8.
</div>
</dd></dl>

<dl class="c function">
<dt class="sig sig-object c" id="c.PyVectorcall_Function">
<a class="reference internal" href="#c.vectorcallfunc" title="vectorcallfunc">vectorcallfunc</a> PyVectorcall_Function(<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *op)<a class="headerlink" href="#c.PyVectorcall_Function" title="Permalink to this definition">¶</a> </dt>
<dd>If op does not support the vectorcall protocol (either because the type
does not or because the specific instance does not), return NULL.
Otherwise, return the vectorcall function pointer stored in op.
This function never raises an exception.
This is mostly useful to check whether or not op supports vectorcall,
which can be done by checking <code class="docutils literal notranslate">PyVectorcall_Function(op) != NULL</code>.
<div class="versionadded">
New in version 3.8.
</div>
</dd></dl>

<dl class="c function">
<dt class="sig sig-object c" id="c.PyVectorcall_Call">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *PyVectorcall_Call(<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *callable, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *tuple, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *dict)<a class="headerlink" href="#c.PyVectorcall_Call" title="Permalink to this definition">¶</a> </dt>
<dd>Call callable’s <a class="reference internal" href="#c.vectorcallfunc" title="vectorcallfunc"><code class="xref c c-type docutils literal notranslate">vectorcallfunc</code></a> with positional and keyword
arguments given in a tuple and dict, respectively.
This is a specialized function, intended to be put in the
<a class="reference internal" href="typeobj.html#c.PyTypeObject.tp_call" title="PyTypeObject.tp_call"><code class="xref c c-member docutils literal notranslate">tp_call</code></a> slot or be used in an implementation of <code class="docutils literal notranslate">tp_call</code>.
It does not check the <a class="reference internal" href="typeobj.html#Py_TPFLAGS_HAVE_VECTORCALL" title="Py_TPFLAGS_HAVE_VECTORCALL"><code class="xref py py-const docutils literal notranslate">Py_TPFLAGS_HAVE_VECTORCALL</code></a> flag
and it does not fall back to <code class="docutils literal notranslate">tp_call</code>.
<div class="versionadded">
New in version 3.8.
</div>
</dd></dl>

</section>
</section>
<section id="object-calling-api">
<h2>Object Calling API<a class="headerlink" href="#object-calling-api" title="Permalink to this headline">¶</a></h2>
Various functions are available for calling a Python object.
Each converts its arguments to a convention supported by the called object –
either tp_call or vectorcall.
In order to do as little conversion as possible, pick one that best fits
the format of data you have available.
The following table summarizes the available functions;
please see individual documentation for details.
<table class="docutils align-default">
<colgroup>
<col style="width: 44%" />
<col style="width: 19%" />
<col style="width: 21%" />
<col style="width: 16%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head">Function</th>
<th class="head">callable</th>
<th class="head">args</th>
<th class="head">kwargs</th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><a class="reference internal" href="#c.PyObject_Call" title="PyObject_Call"><code class="xref c c-func docutils literal notranslate">PyObject_Call()</code></a></td>
<td><code class="docutils literal notranslate">PyObject *</code></td>
<td>tuple</td>
<td>dict/<code class="docutils literal notranslate">NULL</code></td>
</tr>
<tr class="row-odd"><td><a class="reference internal" href="#c.PyObject_CallNoArgs" title="PyObject_CallNoArgs"><code class="xref c c-func docutils literal notranslate">PyObject_CallNoArgs()</code></a></td>
<td><code class="docutils literal notranslate">PyObject *</code></td>
<td>—</td>
<td>—</td>
</tr>
<tr class="row-even"><td><a class="reference internal" href="#c.PyObject_CallOneArg" title="PyObject_CallOneArg"><code class="xref c c-func docutils literal notranslate">PyObject_CallOneArg()</code></a></td>
<td><code class="docutils literal notranslate">PyObject *</code></td>
<td>1 object</td>
<td>—</td>
</tr>
<tr class="row-odd"><td><a class="reference internal" href="#c.PyObject_CallObject" title="PyObject_CallObject"><code class="xref c c-func docutils literal notranslate">PyObject_CallObject()</code></a></td>
<td><code class="docutils literal notranslate">PyObject *</code></td>
<td>tuple/<code class="docutils literal notranslate">NULL</code></td>
<td>—</td>
</tr>
<tr class="row-even"><td><a class="reference internal" href="#c.PyObject_CallFunction" title="PyObject_CallFunction"><code class="xref c c-func docutils literal notranslate">PyObject_CallFunction()</code></a></td>
<td><code class="docutils literal notranslate">PyObject *</code></td>
<td>format</td>
<td>—</td>
</tr>
<tr class="row-odd"><td><a class="reference internal" href="#c.PyObject_CallMethod" title="PyObject_CallMethod"><code class="xref c c-func docutils literal notranslate">PyObject_CallMethod()</code></a></td>
<td>obj + <code class="docutils literal notranslate">char*</code></td>
<td>format</td>
<td>—</td>
</tr>
<tr class="row-even"><td><a class="reference internal" href="#c.PyObject_CallFunctionObjArgs" title="PyObject_CallFunctionObjArgs"><code class="xref c c-func docutils literal notranslate">PyObject_CallFunctionObjArgs()</code></a></td>
<td><code class="docutils literal notranslate">PyObject *</code></td>
<td>variadic</td>
<td>—</td>
</tr>
<tr class="row-odd"><td><a class="reference internal" href="#c.PyObject_CallMethodObjArgs" title="PyObject_CallMethodObjArgs"><code class="xref c c-func docutils literal notranslate">PyObject_CallMethodObjArgs()</code></a></td>
<td>obj + name</td>
<td>variadic</td>
<td>—</td>
</tr>
<tr class="row-even"><td><a class="reference internal" href="#c.PyObject_CallMethodNoArgs" title="PyObject_CallMethodNoArgs"><code class="xref c c-func docutils literal notranslate">PyObject_CallMethodNoArgs()</code></a></td>
<td>obj + name</td>
<td>—</td>
<td>—</td>
</tr>
<tr class="row-odd"><td><a class="reference internal" href="#c.PyObject_CallMethodOneArg" title="PyObject_CallMethodOneArg"><code class="xref c c-func docutils literal notranslate">PyObject_CallMethodOneArg()</code></a></td>
<td>obj + name</td>
<td>1 object</td>
<td>—</td>
</tr>
<tr class="row-even"><td><a class="reference internal" href="#c.PyObject_Vectorcall" title="PyObject_Vectorcall"><code class="xref c c-func docutils literal notranslate">PyObject_Vectorcall()</code></a></td>
<td><code class="docutils literal notranslate">PyObject *</code></td>
<td>vectorcall</td>
<td>vectorcall</td>
</tr>
<tr class="row-odd"><td><a class="reference internal" href="#c.PyObject_VectorcallDict" title="PyObject_VectorcallDict"><code class="xref c c-func docutils literal notranslate">PyObject_VectorcallDict()</code></a></td>
<td><code class="docutils literal notranslate">PyObject *</code></td>
<td>vectorcall</td>
<td>dict/<code class="docutils literal notranslate">NULL</code></td>
</tr>
<tr class="row-even"><td><a class="reference internal" href="#c.PyObject_VectorcallMethod" title="PyObject_VectorcallMethod"><code class="xref c c-func docutils literal notranslate">PyObject_VectorcallMethod()</code></a></td>
<td>arg + name</td>
<td>vectorcall</td>
<td>vectorcall</td>
</tr>
</tbody>
</table>
<dl class="c function">
<dt class="sig sig-object c" id="c.PyObject_Call">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *PyObject_Call(<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *callable, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *args, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *kwargs)<a class="headerlink" href="#c.PyObject_Call" title="Permalink to this definition">¶</a> </dt>
<dd>Return value: New reference. Part of the <a class="reference internal" href="stable.html#stable">Stable ABI</a>.Call a callable Python object callable, with arguments given by the
tuple args, and named arguments given by the dictionary kwargs.
args must not be NULL; use an empty tuple if no arguments are needed.
If no named arguments are needed, kwargs can be NULL.
Return the result of the call on success, or raise an exception and return
NULL on failure.
This is the equivalent of the Python expression:
<code class="docutils literal notranslate">callable(*args, **kwargs)</code>.
</dd></dl>

<dl class="c function">
<dt class="sig sig-object c" id="c.PyObject_CallNoArgs">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *PyObject_CallNoArgs(<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *callable)<a class="headerlink" href="#c.PyObject_CallNoArgs" title="Permalink to this definition">¶</a> </dt>
<dd> Part of the <a class="reference internal" href="stable.html#stable">Stable ABI</a> since version 3.10.Call a callable Python object callable without any arguments. It is the
most efficient way to call a callable Python object without any argument.
Return the result of the call on success, or raise an exception and return
NULL on failure.
<div class="versionadded">
New in version 3.9.
</div>
</dd></dl>

<dl class="c function">
<dt class="sig sig-object c" id="c.PyObject_CallOneArg">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *PyObject_CallOneArg(<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *callable, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *arg)<a class="headerlink" href="#c.PyObject_CallOneArg" title="Permalink to this definition">¶</a> </dt>
<dd>Call a callable Python object callable with exactly 1 positional argument
arg and no keyword arguments.
Return the result of the call on success, or raise an exception and return
NULL on failure.
<div class="versionadded">
New in version 3.9.
</div>
</dd></dl>

<dl class="c function">
<dt class="sig sig-object c" id="c.PyObject_CallObject">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *PyObject_CallObject(<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *callable, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *args)<a class="headerlink" href="#c.PyObject_CallObject" title="Permalink to this definition">¶</a> </dt>
<dd>Return value: New reference. Part of the <a class="reference internal" href="stable.html#stable">Stable ABI</a>.Call a callable Python object callable, with arguments given by the
tuple args. If no arguments are needed, then args can be NULL.
Return the result of the call on success, or raise an exception and return
NULL on failure.
This is the equivalent of the Python expression: <code class="docutils literal notranslate">callable(*args)</code>.
</dd></dl>

<dl class="c function">
<dt class="sig sig-object c" id="c.PyObject_CallFunction">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *PyObject_CallFunction(<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *callable, const char *format, ...)<a class="headerlink" href="#c.PyObject_CallFunction" title="Permalink to this definition">¶</a> </dt>
<dd>Return value: New reference. Part of the <a class="reference internal" href="stable.html#stable">Stable ABI</a>.Call a callable Python object callable, with a variable number of C arguments.
The C arguments are described using a <a class="reference internal" href="arg.html#c.Py_BuildValue" title="Py_BuildValue"><code class="xref c c-func docutils literal notranslate">Py_BuildValue()</code></a> style format
string. The format can be NULL, indicating that no arguments are provided.
Return the result of the call on success, or raise an exception and return
NULL on failure.
This is the equivalent of the Python expression: <code class="docutils literal notranslate">callable(*args)</code>.
Note that if you only pass <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* args,
<a class="reference internal" href="#c.PyObject_CallFunctionObjArgs" title="PyObject_CallFunctionObjArgs"><code class="xref c c-func docutils literal notranslate">PyObject_CallFunctionObjArgs()</code></a> is a faster alternative.
<div class="versionchanged">
Changed in version 3.4: The type of format was changed from <code class="docutils literal notranslate">char *</code>.
</div>
</dd></dl>

<dl class="c function">
<dt class="sig sig-object c" id="c.PyObject_CallMethod">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *PyObject_CallMethod(<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *obj, const char *name, const char *format, ...)<a class="headerlink" href="#c.PyObject_CallMethod" title="Permalink to this definition">¶</a> </dt>
<dd>Return value: New reference. Part of the <a class="reference internal" href="stable.html#stable">Stable ABI</a>.Call the method named name of object obj with a variable number of C
arguments. The C arguments are described by a <a class="reference internal" href="arg.html#c.Py_BuildValue" title="Py_BuildValue"><code class="xref c c-func docutils literal notranslate">Py_BuildValue()</code></a> format
string that should produce a tuple.
The format can be NULL, indicating that no arguments are provided.
Return the result of the call on success, or raise an exception and return
NULL on failure.
This is the equivalent of the Python expression:
<code class="docutils literal notranslate">obj.name(arg1, arg2, ...)</code>.
Note that if you only pass <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* args,
<a class="reference internal" href="#c.PyObject_CallMethodObjArgs" title="PyObject_CallMethodObjArgs"><code class="xref c c-func docutils literal notranslate">PyObject_CallMethodObjArgs()</code></a> is a faster alternative.
<div class="versionchanged">
Changed in version 3.4: The types of name and format were changed from <code class="docutils literal notranslate">char *</code>.
</div>
</dd></dl>

<dl class="c function">
<dt class="sig sig-object c" id="c.PyObject_CallFunctionObjArgs">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *PyObject_CallFunctionObjArgs(<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *callable, ...)<a class="headerlink" href="#c.PyObject_CallFunctionObjArgs" title="Permalink to this definition">¶</a> </dt>
<dd>Return value: New reference. Part of the <a class="reference internal" href="stable.html#stable">Stable ABI</a>.Call a callable Python object callable, with a variable number of
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* arguments. The arguments are provided as a variable number
of parameters followed by NULL.
Return the result of the call on success, or raise an exception and return
NULL on failure.
This is the equivalent of the Python expression:
<code class="docutils literal notranslate">callable(arg1, arg2, ...)</code>.
</dd></dl>

<dl class="c function">
<dt class="sig sig-object c" id="c.PyObject_CallMethodObjArgs">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *PyObject_CallMethodObjArgs(<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *obj, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *name, ...)<a class="headerlink" href="#c.PyObject_CallMethodObjArgs" title="Permalink to this definition">¶</a> </dt>
<dd>Return value: New reference. Part of the <a class="reference internal" href="stable.html#stable">Stable ABI</a>.Call a method of the Python object obj, where the name of the method is given as a
Python string object in name. It is called with a variable number of
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* arguments. The arguments are provided as a variable number
of parameters followed by NULL.
Return the result of the call on success, or raise an exception and return
NULL on failure.
</dd></dl>

<dl class="c function">
<dt class="sig sig-object c" id="c.PyObject_CallMethodNoArgs">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *PyObject_CallMethodNoArgs(<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *obj, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *name)<a class="headerlink" href="#c.PyObject_CallMethodNoArgs" title="Permalink to this definition">¶</a> </dt>
<dd>Call a method of the Python object obj without arguments,
where the name of the method is given as a Python string object in name.
Return the result of the call on success, or raise an exception and return
NULL on failure.
<div class="versionadded">
New in version 3.9.
</div>
</dd></dl>

<dl class="c function">
<dt class="sig sig-object c" id="c.PyObject_CallMethodOneArg">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *PyObject_CallMethodOneArg(<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *obj, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *name, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *arg)<a class="headerlink" href="#c.PyObject_CallMethodOneArg" title="Permalink to this definition">¶</a> </dt>
<dd>Call a method of the Python object obj with a single positional argument
arg, where the name of the method is given as a Python string object in
name.
Return the result of the call on success, or raise an exception and return
NULL on failure.
<div class="versionadded">
New in version 3.9.
</div>
</dd></dl>

<dl class="c function">
<dt class="sig sig-object c" id="c.PyObject_Vectorcall">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *PyObject_Vectorcall(<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *callable, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *const *args, size_t nargsf, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *kwnames)<a class="headerlink" href="#c.PyObject_Vectorcall" title="Permalink to this definition">¶</a> </dt>
<dd>Call a callable Python object callable.
The arguments are the same as for <a class="reference internal" href="#c.vectorcallfunc" title="vectorcallfunc"><code class="xref c c-type docutils literal notranslate">vectorcallfunc</code></a>.
If callable supports <a class="reference internal" href="#vectorcall">vectorcall</a>, this directly calls
the vectorcall function stored in callable.
Return the result of the call on success, or raise an exception and return
NULL on failure.
<div class="versionadded">
New in version 3.9.
</div>
</dd></dl>

<dl class="c function">
<dt class="sig sig-object c" id="c.PyObject_VectorcallDict">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *PyObject_VectorcallDict(<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *callable, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *const *args, size_t nargsf, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *kwdict)<a class="headerlink" href="#c.PyObject_VectorcallDict" title="Permalink to this definition">¶</a> </dt>
<dd>Call callable with positional arguments passed exactly as in the <a class="reference internal" href="#vectorcall">vectorcall</a> protocol,
but with keyword arguments passed as a dictionary kwdict.
The args array contains only the positional arguments.
Regardless of which protocol is used internally,
a conversion of arguments needs to be done.
Therefore, this function should only be used if the caller
already has a dictionary ready to use for the keyword arguments,
but not a tuple for the positional arguments.
<div class="versionadded">
New in version 3.9.
</div>
</dd></dl>

<dl class="c function">
<dt class="sig sig-object c" id="c.PyObject_VectorcallMethod">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *PyObject_VectorcallMethod(<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *name, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *const *args, size_t nargsf, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *kwnames)<a class="headerlink" href="#c.PyObject_VectorcallMethod" title="Permalink to this definition">¶</a> </dt>
<dd>Call a method using the vectorcall calling convention. The name of the method
is given as a Python string name. The object whose method is called is
args[0], and the args array starting at args[1] represents the arguments
of the call. There must be at least one positional argument.
nargsf is the number of positional arguments including args[0],
plus <code class="xref py py-const docutils literal notranslate">PY_VECTORCALL_ARGUMENTS_OFFSET</code> if the value of <code class="docutils literal notranslate">args[0]</code> may
temporarily be changed. Keyword arguments can be passed just like in
<a class="reference internal" href="#c.PyObject_Vectorcall" title="PyObject_Vectorcall"><code class="xref c c-func docutils literal notranslate">PyObject_Vectorcall()</code></a>.
If the object has the <a class="reference internal" href="typeobj.html#Py_TPFLAGS_METHOD_DESCRIPTOR" title="Py_TPFLAGS_METHOD_DESCRIPTOR"><code class="xref py py-const docutils literal notranslate">Py_TPFLAGS_METHOD_DESCRIPTOR</code></a> feature,
this will call the unbound method object with the full
args vector as arguments.
Return the result of the call on success, or raise an exception and return
NULL on failure.
<div class="versionadded">
New in version 3.9.
</div>
</dd></dl>

</section>
<section id="call-support-api">
<h2>Call Support API<a class="headerlink" href="#call-support-api" title="Permalink to this headline">¶</a></h2>
<dl class="c function">
<dt class="sig sig-object c" id="c.PyCallable_Check">
int PyCallable_Check(<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *o)<a class="headerlink" href="#c.PyCallable_Check" title="Permalink to this definition">¶</a> </dt>
<dd> Part of the <a class="reference internal" href="stable.html#stable">Stable ABI</a>.Determine if the object o is callable. Return <code class="docutils literal notranslate">1</code> if the object is callable
and <code class="docutils literal notranslate">0</code> otherwise. This function always succeeds.
</dd></dl>

</section>
</section>

<div class="clearer"></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="#">Call Protocol</a><ul>
<li><a class="reference internal" href="#the-tp-call-protocol">The tp_call Protocol</a></li>
<li><a class="reference internal" href="#the-vectorcall-protocol">The Vectorcall Protocol</a><ul>
<li><a class="reference internal" href="#recursion-control">Recursion Control</a></li>
<li><a class="reference internal" href="#vectorcall-support-api">Vectorcall Support API</a></li>
</ul>
</li>
<li><a class="reference internal" href="#object-calling-api">Object Calling API</a></li>
<li><a class="reference internal" href="#call-support-api">Call Support API</a></li>
</ul>
</li>
</ul>

<h4>Previous topic</h4>
 <a href="object.html"
 title="previous chapter">Object Protocol</a>
 <h4>Next topic</h4>
 <a href="number.html"
 title="next chapter">Number Protocol</a>
 <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.10/Doc/c-api/call.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="number.html" title="Number Protocol"
 >next</a> |</li>
 <li class="right" >
 <a href="object.html" title="Object Protocol"
 >previous</a> |</li>

<li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> &#187;</li>
 <li class="nav-item nav-item-2"><a href="abstract.html" >Abstract Objects Layer</a> &#187;</li>
 <li class="nav-item nav-item-this"><a href="">Call Protocol</a></li>
 <li class="right">

<div class="inline-search" role="search">
 <form class="inline-search" action="../search.html" method="get">
 <input placeholder="Quick search" aria-label="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>
 |
 </li>
 
 </ul>
 </div> 
 <div class="footer">
 &copy; <a href="../copyright.html">Copyright</a> 2001-2025, Python Software Foundation.
 
 This page is licensed under the Python Software Foundation License Version 2.
 
 Examples, recipes, and other code in the documentation are additionally licensed under the Zero Clause BSD License.
 
 See <a href="/license.html">History and License</a> for more information.

The Python Software Foundation is a non-profit corporation.
<a href="https://www.python.org/psf/donations/">Please donate.</a>

Last updated on February 04, 2025.
 <a href="/bugs.html">Found a bug</a>?

Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 4.3.2.
 </div>

</body>
</html>