Code Objects¶
Code objects are a low-level detail of the CPython implementation. Each one represents a chunk of executable code that hasn’t yet been bound into a function.
-
type
PyCodeObject
¶ The C structure of the objects used to describe code objects. The fields of this type are subject to change at any time.
-
PyTypeObject
PyCode_Type
¶ This is an instance of
PyTypeObject
representing the Pythoncode
type.
-
int
PyCode_GetNumFree
(PyCodeObject *co)¶ Return the number of free variables in co.
-
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)¶ - Return value: New reference.
Return a new code object. If you need a dummy code object to create a frame, use
PyCode_NewEmpty()
instead. CallingPyCode_New()
directly will bind you to a precise Python version since the definition of the bytecode changes often. The many arguments of this function are inter-dependent in complex ways, meaning that subtle changes to values are likely to result in incorrect execution or VM crashes. Use this function only with extreme care.Changed in version 3.11: Added
exceptiontable
parameter.
-
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)¶ - Return value: New reference.
Similar to
PyCode_New()
, but with an extra “posonlyargcount” for positional-only arguments. The same caveats that apply toPyCode_New
also apply to this function.New in version 3.8.
Changed in version 3.11: Added
exceptiontable
parameter.
-
PyCodeObject *
PyCode_NewEmpty
(const char *filename, const char *funcname, int firstlineno)¶ - Return value: New reference.
Return a new empty code object with the specified filename, function name, and first line number. The resulting code object will raise an
Exception
if executed.
-
int
PyCode_Addr2Line
(PyCodeObject *co, int byte_offset)¶ Return the line number of the instruction that occurs on or before
byte_offset
and ends after it. If you just need the line number of a frame, usePyFrame_GetLineNumber()
instead.For efficiently iterating over the line numbers in a code object, use the API described in PEP 626.
-
int
PyCode_Addr2Location
(PyObject *co, int byte_offset, int *start_line, int *start_column, int *end_line, int *end_column)¶ Sets the passed
int
pointers to the source code line and column numbers for the instruction atbyte_offset
. Sets the value to0
when information is not available for any particular element.Returns
1
if the function succeeds and 0 otherwise.New in version 3.11.
-
PyObject *
PyCode_GetCode
(PyCodeObject *co)¶ Equivalent to the Python code
getattr(co, 'co_code')
. Returns a strong reference to aPyBytesObject
representing the bytecode in a code object. On error,NULL
is returned and an exception is raised.This
PyBytesObject
may be created on-demand by the interpreter and does not necessarily represent the bytecode actually executed by CPython. The primary use case for this function is debuggers and profilers.New in version 3.11.
-
PyObject *
PyCode_GetVarnames
(PyCodeObject *co)¶ Equivalent to the Python code
getattr(co, 'co_varnames')
. Returns a new reference to aPyTupleObject
containing the names of the local variables. On error,NULL
is returned and an exception is raised.New in version 3.11.
-
PyObject *
PyCode_GetCellvars
(PyCodeObject *co)¶ Equivalent to the Python code
getattr(co, 'co_cellvars')
. Returns a new reference to aPyTupleObject
containing the names of the local variables that are referenced by nested functions. On error,NULL
is returned and an exception is raised.New in version 3.11.
-
PyObject *
PyCode_GetFreevars
(PyCodeObject *co)¶ Equivalent to the Python code
getattr(co, 'co_freevars')
. Returns a new reference to aPyTupleObject
containing the names of the free variables. On error,NULL
is returned and an exception is raised.New in version 3.11.