@@ -33,28 +33,47 @@ bound into a function.
3333
3434 Return the number of free variables in *co *.
3535
36- .. c :function :: PyCodeObject* PyCode_New (int argcount, int kwonlyargcount, int nlocals, int stacksize, int flags, PyObject *code, PyObject *consts, PyObject *names, PyObject *varnames, PyObject *freevars, PyObject *cellvars, PyObject *filename, PyObject *name, int firstlineno, PyObject *linetable, PyObject *exceptiontable)
36+ .. c :function :: PyCodeObject* PyUnstable_Code_New (int argcount, int kwonlyargcount, int nlocals, int stacksize, int flags, PyObject *code, PyObject *consts, PyObject *names, PyObject *varnames, PyObject *freevars, PyObject *cellvars, PyObject *filename, PyObject *name, int firstlineno, PyObject *linetable, PyObject *exceptiontable)
3737
3838 Return a new code object. If you need a dummy code object to create a frame,
39- use :c:func: `PyCode_NewEmpty ` instead. Calling :c:func: `PyCode_New ` directly
40- will bind you to a precise Python version since the definition of the bytecode
41- changes often. The many arguments of this function are inter-dependent in complex
39+ use :c:func: `PyCode_NewEmpty ` instead.
40+
41+ Since the definition of the bytecode changes often, calling
42+ :c:func: `PyCode_New ` directly can bind you to a precise Python version.
43+
44+ The many arguments of this function are inter-dependent in complex
4245 ways, meaning that subtle changes to values are likely to result in incorrect
4346 execution or VM crashes. Use this function only with extreme care.
4447
4548 .. versionchanged :: 3.11
4649 Added ``exceptiontable `` parameter.
4750
48- .. c :function :: PyCodeObject* PyCode_NewWithPosOnlyArgs (int argcount, int posonlyargcount, int kwonlyargcount, int nlocals, int stacksize, int flags, PyObject *code, PyObject *consts, PyObject *names, PyObject *varnames, PyObject *freevars, PyObject *cellvars, PyObject *filename, PyObject *name, int firstlineno, PyObject *linetable, PyObject *exceptiontable)
51+ .. index :: single: PyCode_New
52+
53+ .. versionchanged :: 3.12
54+
55+ Renamed from ``PyCode_New `` as part of :ref: `unstable-c-api `.
56+ The old name is deprecated, but will remain available until the
57+ signature changes again.
58+
59+ .. c :function :: PyCodeObject* PyUnstable_Code_NewWithPosOnlyArgs (int argcount, int posonlyargcount, int kwonlyargcount, int nlocals, int stacksize, int flags, PyObject *code, PyObject *consts, PyObject *names, PyObject *varnames, PyObject *freevars, PyObject *cellvars, PyObject *filename, PyObject *name, int firstlineno, PyObject *linetable, PyObject *exceptiontable)
4960
5061 Similar to :c:func: `PyCode_New `, but with an extra "posonlyargcount" for positional-only arguments.
5162 The same caveats that apply to ``PyCode_New `` also apply to this function.
5263
53- .. versionadded :: 3.8
64+ .. index :: single: PyCode_NewWithPosOnlyArgs
65+
66+ .. versionadded :: 3.8 as ``PyCode_NewWithPosOnlyArgs``
5467
5568 .. versionchanged :: 3.11
5669 Added ``exceptiontable `` parameter.
5770
71+ .. versionchanged :: 3.12
72+
73+ Renamed to ``PyUnstable_Code_NewWithPosOnlyArgs ``.
74+ The old name is deprecated, but will remain available until the
75+ signature changes again.
76+
5877.. c :function :: PyCodeObject* PyCode_NewEmpty (const char *filename, const char *funcname, int firstlineno)
5978
6079 Return a new empty code object with the specified filename,
@@ -153,15 +172,93 @@ bound into a function.
153172 before the destruction of *co* takes place, so the prior state of *co*
154173 can be inspected.
155174
175+ If *event* is ``PY_CODE_EVENT_DESTROY``, taking a reference in the callback
176+ to the about-to-be-destroyed code object will resurrect it and prevent it
177+ from being freed at this time. When the resurrected object is destroyed
178+ later, any watcher callbacks active at that time will be called again.
179+
156180 Users of this API should not rely on internal runtime implementation
157181 details. Such details may include, but are not limited to, the exact
158182 order and timing of creation and destruction of code objects. While
159183 changes in these details may result in differences observable by watchers
160184 (including whether a callback is invoked or not), it does not change
161185 the semantics of the Python code being executed.
162186
163- If the callback returns with an exception set, it must return ``-1``; this
164-
165- :c:func: `PyErr_WriteUnraisable `. Otherwise it should return ``0 ``.
187+ If the callback sets an exception, it must return ``-1``; this exception will
188+ :c:func: `PyErr_WriteUnraisable `.
189+ Otherwise it should return ``0 ``.
190+
191+ There may already be a pending exception set on entry to the callback. In
192+ this case, the callback should return ``0 `` with the same exception still
193+ set. This means the callback may not call any other API that can set an
194+ exception unless it saves and clears the exception state first, and restores
195+ it before returning.
166196
167197 .. versionadded :: 3.12
198+
199+
200+ Extra information
201+ -----------------
202+
203+ To support low-level extensions to frame evaluation, such as external
204+ just-in-time compilers, it is possible to attach arbitrary extra data to
205+ code objects.
206+
207+ These functions are part of the unstable C API tier:
208+ this functionality is a CPython implementation detail, and the API
209+ may change without deprecation warnings.
210+
211+ .. c :function :: Py_ssize_t PyUnstable_Eval_RequestCodeExtraIndex (freefunc free)
212+
213+ Return a new an opaque index value used to adding data to code objects.
214+
215+ You generally call this function once (per interpreter) and use the result
216+ with ``PyCode_GetExtra`` and ``PyCode_SetExtra`` to manipulate
217+ data on individual code objects.
218+
219+ If *free* is not ``NULL``: when a code object is deallocated,
220+ *free* will be called on non-``NULL`` data stored under the new index.
221+ Use :c:func:`Py_DecRef` when storing :c:type:`PyObject`.
222+
223+ .. index:: single: _PyEval_RequestCodeExtraIndex
224+
225+ .. versionadded:: 3.6 as ``_PyEval_RequestCodeExtraIndex``
226+
227+ .. versionchanged:: 3.12
228+
229+ Renamed to ``PyUnstable_Eval_RequestCodeExtraIndex``.
230+ The old private name is deprecated, but will be available until the API
231+ changes.
232+
233+ .. c:function:: int PyUnstable_Code_GetExtra(PyObject *code, Py_ssize_t index, void **extra)
234+
235+ Set *extra * to the extra data stored under the given index.
236+ Return 0 on success. Set an exception and return -1 on failure.
237+
238+ If no data was set under the index, set *extra * to ``NULL `` and return
239+ 0 without setting an exception.
240+
241+ .. index :: single: _PyCode_GetExtra
242+
243+ .. versionadded :: 3.6 as ``_PyCode_GetExtra``
244+
245+ .. versionchanged :: 3.12
246+
247+ Renamed to ``PyUnstable_Code_GetExtra ``.
248+ The old private name is deprecated, but will be available until the API
249+ changes.
250+
251+ .. c :function :: int PyUnstable_Code_SetExtra (PyObject *code, Py_ssize_t index, void *extra)
252+
253+ Set the extra data stored under the given index to *extra *.
254+ Return 0 on success. Set an exception and return -1 on failure.
255+
256+ .. index :: single: _PyCode_SetExtra
257+
258+ .. versionadded :: 3.6 as ``_PyCode_SetExtra``
259+
260+ .. versionchanged :: 3.12
261+
262+ Renamed to ``PyUnstable_Code_SetExtra ``.
263+ The old private name is deprecated, but will be available until the API
264+ changes.
0 commit comments