@@ -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,
@@ -165,3 +184,70 @@ bound into a function.
165184 :c:func: `PyErr_WriteUnraisable `. Otherwise it should return ``0 ``.
166185
167186 .. versionadded :: 3.12
187+
188+
189+ Extra information
190+ -----------------
191+
192+ To support low-level extensions to frame evaluation, such as external
193+ just-in-time compilers, it is possible to attach arbitrary extra data to
194+ code objects.
195+
196+ These functions are part of the unstable C API tier:
197+ this functionality is a CPython implementation detail, and the API
198+ may change without deprecation warnings.
199+
200+ .. c :function :: Py_ssize_t PyUnstable_Eval_RequestCodeExtraIndex (freefunc free)
201+
202+ Return a new an opaque index value used to adding data to code objects.
203+
204+ You generally call this function once (per interpreter) and use the result
205+ with ``PyCode_GetExtra`` and ``PyCode_SetExtra`` to manipulate
206+ data on individual code objects.
207+
208+ If *free* is not ``NULL``: when a code object is deallocated,
209+ *free* will be called on non-``NULL`` data stored under the new index.
210+ Use :c:func:`Py_DecRef` when storing :c:type:`PyObject`.
211+
212+ .. index:: single: _PyEval_RequestCodeExtraIndex
213+
214+ .. versionadded:: 3.6 as ``_PyEval_RequestCodeExtraIndex``
215+
216+ .. versionchanged:: 3.12
217+
218+ Renamed to ``PyUnstable_Eval_RequestCodeExtraIndex``.
219+ The old private name is deprecated, but will be available until the API
220+ changes.
221+
222+ .. c:function:: int PyUnstable_Code_GetExtra(PyObject *code, Py_ssize_t index, void **extra)
223+
224+ Set *extra * to the extra data stored under the given index.
225+ Return 0 on success. Set an exception and return -1 on failure.
226+
227+ If no data was set under the index, set *extra * to ``NULL `` and return
228+ 0 without setting an exception.
229+
230+ .. index :: single: _PyCode_GetExtra
231+
232+ .. versionadded :: 3.6 as ``_PyCode_GetExtra``
233+
234+ .. versionchanged :: 3.12
235+
236+ Renamed to ``PyUnstable_Code_GetExtra ``.
237+ The old private name is deprecated, but will be available until the API
238+ changes.
239+
240+ .. c :function :: int PyUnstable_Code_SetExtra (PyObject *code, Py_ssize_t index, void *extra)
241+
242+ Set the extra data stored under the given index to *extra *.
243+ Return 0 on success. Set an exception and return -1 on failure.
244+
245+ .. index :: single: _PyCode_SetExtra
246+
247+ .. versionadded :: 3.6 as ``_PyCode_SetExtra``
248+
249+ .. versionchanged :: 3.12
250+
251+ Renamed to ``PyUnstable_Code_SetExtra ``.
252+ The old private name is deprecated, but will be available until the API
253+ changes.
0 commit comments