A code object is a marshal
object with the type byte c: one piece of compiled Python, a module, class
or function. The file’s body is the module’s code object, and each function or class
defined in it is another code object among its constants.
Fields
The fields are written in this order with no separators. An “i32” field is a little-endian 32-bit number with no type byte of its own; every other field is a marshal object.
| Field | Kind | Meaning |
|---|---|---|
co_argcount | i32 | How many positional parameters, positional-only ones included. |
co_posonlyargcount | i32 | How many of them are positional-only. |
co_kwonlyargcount | i32 | How many keyword-only parameters. |
co_nlocals | i32 | How many local variables, parameters included. |
co_stacksize | i32 | The most values the code needs on the stack at one time. |
co_flags | i32 | Facts about the code, as bits. |
co_code | bytes | The instructions. |
co_consts | tuple | Constants used by the code, including nested code objects. The docstring, if there is one, is the first item; otherwise the first item is None in a function. |
co_names | tuple of text | Names of globals, attributes and imported modules used by the code. |
co_varnames | tuple of text | Names of the parameters and locals. Local-variable instructions index this list. |
co_freevars | tuple of text | Names of the free variables, taken from enclosing functions. |
co_cellvars | tuple of text | Names of the local variables captured by inner functions. Cell instructions number these first, then the free variables. |
co_filename | text | The source file’s path as given to the compiler. |
co_name | text | The short name: f, or <module>. |
co_firstlineno | i32 | The source line where this code begins. |
co_linetable | bytes | Which source line each instruction came from: see line numbers. |
co_flags
Each bit is named by Python’s inspect module with the prefix
CO_, or for a future feature in the __future__ module.
| Bit | Name | Meaning |
|---|---|---|
| 0x00000001 | OPTIMIZED | Uses fast locals. Set on functions |
| 0x00000002 | NEWLOCALS | A new local namespace is made for each call. Set on functions |
| 0x00000004 | VARARGS | Takes *args |
| 0x00000008 | VARKEYWORDS | Takes **kwargs |
| 0x00000010 | NESTED | A nested function |
| 0x00000020 | GENERATOR | A generator function |
| 0x00000040 | NOFREE | Has no free or cell variables |
| 0x00000080 | COROUTINE | A coroutine function |
| 0x00000100 | ITERABLE_COROUTINE | A generator that can be awaited (types.coroutine) |
| 0x00000200 | ASYNC_GENERATOR | An async generator function |
| 0x00020000 | FUTURE_DIVISION | from __future__ import division |
| 0x00040000 | FUTURE_ABSOLUTE_IMPORT | from __future__ import absolute_import |
| 0x00080000 | FUTURE_WITH_STATEMENT | from __future__ import with_statement |
| 0x00100000 | FUTURE_PRINT_FUNCTION | from __future__ import print_function |
| 0x00200000 | FUTURE_UNICODE_LITERALS | from __future__ import unicode_literals |
| 0x00400000 | FUTURE_BARRY_AS_BDFL | from __future__ import barry_as_FLUFL |
| 0x00800000 | FUTURE_GENERATOR_STOP | from __future__ import generator_stop |
| 0x01000000 | FUTURE_ANNOTATIONS | from __future__ import annotations |
Worked example
Here is marshal.dumps(f) of a code object f, compiled under
Python 3.10 from this function in t.py, starting at line 1.
def f(a):
if a:
return a + 1
return 0| Bytes | Field | Value |
|---|---|---|
E3 | Type c with FLAG_REF | Saved as #0 |
01 00 00 00 | co_argcount | 1 |
00 00 00 00 | co_posonlyargcount | 0 |
00 00 00 00 | co_kwonlyargcount | 0 |
01 00 00 00 | co_nlocals | 1 |
02 00 00 00 | co_stacksize | 2 |
43 00 00 00 | co_flags | OPTIMIZED, NEWLOCALS, NOFREE |
73 10 00 00 00 … | co_code | 16 bytes |
29 03 4E E9 01 00 00 00 E9 00 00 00 00 | co_consts | (None, 1, 0); the two integers are saved as #1 and #2 |
A9 00 | co_names | (), an empty small tuple, saved as #3 |
29 01 DA 01 61 | co_varnames | ('a',); the name is saved as #4 |
72 03 00 00 00 | co_freevars | Reference to #3, () |
72 03 00 00 00 | co_cellvars | Reference to #3, () |
FA 04 74 2E 70 79 | co_filename | 't.py', saved as #5 |
DA 01 66 | co_name | 'f', saved as #6 |
01 00 00 00 | co_firstlineno | 1 |
73 06 00 00 00 04 01 08 01 04 01 | co_linetable | 6 bytes |
The same function’s line table is decoded on its own page.