new repository

1 files changed, 63 insertions, 0 deletions

diff --git a/devdocs/python~3.12/c-api%2Ffunction.html b/devdocs/python~3.12/c-api%2Ffunction.html
new file mode 100644
index 00000000..2e19709a
--- /dev/null
+++ b/devdocs/python~3.12/c-api%2Ffunction.html
@@ -0,0 +1,63 @@
+ <span id="id1"></span><h1>Function Objects</h1> <p id="index-0">There are a few functions specific to Python functions.</p> <dl class="c type"> <dt class="sig sig-object c" id="c.PyFunctionObject">
+<code>type PyFunctionObject</code> </dt> <dd>
+<p>The C structure used for functions.</p> </dd>
+</dl> <dl class="c var"> <dt class="sig sig-object c" id="c.PyFunction_Type">
+<code>PyTypeObject PyFunction_Type</code> </dt> <dd>
+<p id="index-1">This is an instance of <a class="reference internal" href="type#c.PyTypeObject" title="PyTypeObject"><code>PyTypeObject</code></a> and represents the Python function type. It is exposed to Python programmers as <code>types.FunctionType</code>.</p> </dd>
+</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyFunction_Check">
+<code>int PyFunction_Check(PyObject *o)</code> </dt> <dd>
+<p>Return true if <em>o</em> is a function object (has type <a class="reference internal" href="#c.PyFunction_Type" title="PyFunction_Type"><code>PyFunction_Type</code></a>). The parameter must not be <code>NULL</code>. This function always succeeds.</p> </dd>
+</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyFunction_New">
+<code>PyObject *PyFunction_New(PyObject *code, PyObject *globals)</code> </dt> <dd>
+<em class="refcount">Return value: New reference.</em><p>Return a new function object associated with the code object <em>code</em>. <em>globals</em> must be a dictionary with the global variables accessible to the function.</p> <p>The function’s docstring and name are retrieved from the code object. <a class="reference internal" href="../reference/datamodel#function.__module__" title="function.__module__"><code>__module__</code></a> is retrieved from <em>globals</em>. The argument defaults, annotations and closure are set to <code>NULL</code>. <a class="reference internal" href="../reference/datamodel#function.__qualname__" title="function.__qualname__"><code>__qualname__</code></a> is set to the same value as the code object’s <a class="reference internal" href="../reference/datamodel#codeobject.co_qualname" title="codeobject.co_qualname"><code>co_qualname</code></a> field.</p> </dd>
+</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyFunction_NewWithQualName">
+<code>PyObject *PyFunction_NewWithQualName(PyObject *code, PyObject *globals, PyObject *qualname)</code> </dt> <dd>
+<em class="refcount">Return value: New reference.</em><p>As <a class="reference internal" href="#c.PyFunction_New" title="PyFunction_New"><code>PyFunction_New()</code></a>, but also allows setting the function object’s <a class="reference internal" href="../reference/datamodel#function.__qualname__" title="function.__qualname__"><code>__qualname__</code></a> attribute. <em>qualname</em> should be a unicode object or <code>NULL</code>; if <code>NULL</code>, the <code>__qualname__</code> attribute is set to the same value as the code object’s <a class="reference internal" href="../reference/datamodel#codeobject.co_qualname" title="codeobject.co_qualname"><code>co_qualname</code></a> field.</p> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.3.</span></p> </div> </dd>
+</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyFunction_GetCode">
+<code>PyObject *PyFunction_GetCode(PyObject *op)</code> </dt> <dd>
+<em class="refcount">Return value: Borrowed reference.</em><p>Return the code object associated with the function object <em>op</em>.</p> </dd>
+</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyFunction_GetGlobals">
+<code>PyObject *PyFunction_GetGlobals(PyObject *op)</code> </dt> <dd>
+<em class="refcount">Return value: Borrowed reference.</em><p>Return the globals dictionary associated with the function object <em>op</em>.</p> </dd>
+</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyFunction_GetModule">
+<code>PyObject *PyFunction_GetModule(PyObject *op)</code> </dt> <dd>
+<em class="refcount">Return value: Borrowed reference.</em><p>Return a <a class="reference internal" href="../glossary#term-borrowed-reference"><span class="xref std std-term">borrowed reference</span></a> to the <a class="reference internal" href="../reference/datamodel#function.__module__" title="function.__module__"><code>__module__</code></a> attribute of the <a class="reference internal" href="../reference/datamodel#user-defined-funcs"><span class="std std-ref">function object</span></a> <em>op</em>. It can be <em>NULL</em>.</p> <p>This is normally a <a class="reference internal" href="../library/stdtypes#str" title="str"><code>string</code></a> containing the module name, but can be set to any other object by Python code.</p> </dd>
+</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyFunction_GetDefaults">
+<code>PyObject *PyFunction_GetDefaults(PyObject *op)</code> </dt> <dd>
+<em class="refcount">Return value: Borrowed reference.</em><p>Return the argument default values of the function object <em>op</em>. This can be a tuple of arguments or <code>NULL</code>.</p> </dd>
+</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyFunction_SetDefaults">
+<code>int PyFunction_SetDefaults(PyObject *op, PyObject *defaults)</code> </dt> <dd>
+<p>Set the argument default values for the function object <em>op</em>. <em>defaults</em> must be <code>Py_None</code> or a tuple.</p> <p>Raises <a class="reference internal" href="../library/exceptions#SystemError" title="SystemError"><code>SystemError</code></a> and returns <code>-1</code> on failure.</p> </dd>
+</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyFunction_SetVectorcall">
+<code>void PyFunction_SetVectorcall(PyFunctionObject *func, vectorcallfunc vectorcall)</code> </dt> <dd>
+<p>Set the vectorcall field of a given function object <em>func</em>.</p> <p>Warning: extensions using this API must preserve the behavior of the unaltered (default) vectorcall function!</p> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.12.</span></p> </div> </dd>
+</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyFunction_GetClosure">
+<code>PyObject *PyFunction_GetClosure(PyObject *op)</code> </dt> <dd>
+<em class="refcount">Return value: Borrowed reference.</em><p>Return the closure associated with the function object <em>op</em>. This can be <code>NULL</code> or a tuple of cell objects.</p> </dd>
+</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyFunction_SetClosure">
+<code>int PyFunction_SetClosure(PyObject *op, PyObject *closure)</code> </dt> <dd>
+<p>Set the closure associated with the function object <em>op</em>. <em>closure</em> must be <code>Py_None</code> or a tuple of cell objects.</p> <p>Raises <a class="reference internal" href="../library/exceptions#SystemError" title="SystemError"><code>SystemError</code></a> and returns <code>-1</code> on failure.</p> </dd>
+</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyFunction_GetAnnotations">
+<code>PyObject *PyFunction_GetAnnotations(PyObject *op)</code> </dt> <dd>
+<em class="refcount">Return value: Borrowed reference.</em><p>Return the annotations of the function object <em>op</em>. This can be a mutable dictionary or <code>NULL</code>.</p> </dd>
+</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyFunction_SetAnnotations">
+<code>int PyFunction_SetAnnotations(PyObject *op, PyObject *annotations)</code> </dt> <dd>
+<p>Set the annotations for the function object <em>op</em>. <em>annotations</em> must be a dictionary or <code>Py_None</code>.</p> <p>Raises <a class="reference internal" href="../library/exceptions#SystemError" title="SystemError"><code>SystemError</code></a> and returns <code>-1</code> on failure.</p> </dd>
+</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyFunction_AddWatcher">
+<code>int PyFunction_AddWatcher(PyFunction_WatchCallback callback)</code> </dt> <dd>
+<p>Register <em>callback</em> as a function watcher for the current interpreter. Return an ID which may be passed to <a class="reference internal" href="#c.PyFunction_ClearWatcher" title="PyFunction_ClearWatcher"><code>PyFunction_ClearWatcher()</code></a>. In case of error (e.g. no more watcher IDs available), return <code>-1</code> and set an exception.</p> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.12.</span></p> </div> </dd>
+</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyFunction_ClearWatcher">
+<code>int PyFunction_ClearWatcher(int watcher_id)</code> </dt> <dd>
+<p>Clear watcher identified by <em>watcher_id</em> previously returned from <a class="reference internal" href="#c.PyFunction_AddWatcher" title="PyFunction_AddWatcher"><code>PyFunction_AddWatcher()</code></a> for the current interpreter. Return <code>0</code> on success, or <code>-1</code> and set an exception on error (e.g. if the given <em>watcher_id</em> was never registered.)</p> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.12.</span></p> </div> </dd>
+</dl> <dl class="c type"> <dt class="sig sig-object c" id="c.PyFunction_WatchEvent">
+<code>type PyFunction_WatchEvent</code> </dt> <dd>
+<p>Enumeration of possible function watcher events: - <code>PyFunction_EVENT_CREATE</code> - <code>PyFunction_EVENT_DESTROY</code> - <code>PyFunction_EVENT_MODIFY_CODE</code> - <code>PyFunction_EVENT_MODIFY_DEFAULTS</code> - <code>PyFunction_EVENT_MODIFY_KWDEFAULTS</code></p> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.12.</span></p> </div> </dd>
+</dl> <dl class="c type"> <dt class="sig sig-object c" id="c.PyFunction_WatchCallback">
+<code>typedef int (*PyFunction_WatchCallback)(PyFunction_WatchEvent event, PyFunctionObject *func, PyObject *new_value)</code> </dt> <dd>
+<p>Type of a function watcher callback function.</p> <p>If <em>event</em> is <code>PyFunction_EVENT_CREATE</code> or <code>PyFunction_EVENT_DESTROY</code> then <em>new_value</em> will be <code>NULL</code>. Otherwise, <em>new_value</em> will hold a <a class="reference internal" href="../glossary#term-borrowed-reference"><span class="xref std std-term">borrowed reference</span></a> to the new value that is about to be stored in <em>func</em> for the attribute that is being modified.</p> <p>The callback may inspect but must not modify <em>func</em>; doing so could have unpredictable effects, including infinite recursion.</p> <p>If <em>event</em> is <code>PyFunction_EVENT_CREATE</code>, then the callback is invoked after <code>func</code> has been fully initialized. Otherwise, the callback is invoked before the modification to <em>func</em> takes place, so the prior state of <em>func</em> can be inspected. The runtime is permitted to optimize away the creation of function objects when possible. In such cases no event will be emitted. Although this creates the possibility of an observable difference of runtime behavior depending on optimization decisions, it does not change the semantics of the Python code being executed.</p> <p>If <em>event</em> is <code>PyFunction_EVENT_DESTROY</code>, Taking a reference in the callback to the about-to-be-destroyed function will resurrect it, preventing it from being freed at this time. When the resurrected object is destroyed later, any watcher callbacks active at that time will be called again.</p> <p>If the callback sets an exception, it must return <code>-1</code>; this exception will be printed as an unraisable exception using <a class="reference internal" href="exceptions#c.PyErr_WriteUnraisable" title="PyErr_WriteUnraisable"><code>PyErr_WriteUnraisable()</code></a>. Otherwise it should return <code>0</code>.</p> <p>There may already be a pending exception set on entry to the callback. In this case, the callback should return <code>0</code> with the same exception still set. This means the callback may not call any other API that can set an exception unless it saves and clears the exception state first, and restores it before returning.</p> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.12.</span></p> </div> </dd>
+</dl> <div class="_attribution">
+  <p class="_attribution-p">
+    &copy; 2001&ndash;2023 Python Software Foundation<br>Licensed under the PSF License.<br>
+    <a href="https://docs.python.org/3.12/c-api/function.html" class="_attribution-link">https://docs.python.org/3.12/c-api/function.html</a>
+  </p>
+</div>