{
"cells": [
{
"cell_type": "markdown",
"id": "65b8b71b",
"metadata": {},
"source": [
"# Usage\n",
"\n",
"## Python API\n",
"\n",
"### `from_code`\n",
"\n",
"The main entrypoint to our API is the `CodeData` object. You can create it from any Python `CodeType`:"
]
},
{
"cell_type": "code",
"execution_count": 1,
"id": "b6d22cb4",
"metadata": {},
"outputs": [
{
"data": {
"text/html": [
"\n",
"CodeData(\n",
" (\n",
" (\n",
" Instruction('LOAD_FAST', Varname('a'), line_number=7),\n",
" Instruction('LOAD_FAST', Varname('b'), line_number=7),\n",
" Instruction('BINARY_ADD', line_number=7),\n",
" Instruction('RETURN_VALUE', line_number=7)\n",
" ),\n",
" ),\n",
" filename='/tmp/ipykernel_635/3063237183.py',\n",
" first_line_number=6,\n",
" name='fn',\n",
" stacksize=2,\n",
" type=Function(Args(positional_or_keyword=('a', 'b'))),\n",
" _additional_args=(Constant(None, _index_override=0),)\n",
")\n",
"\n"
],
"text/plain": [
"\n",
"\u001b[1mCodeData\u001b[0m\u001b[1m(\u001b[0m\n",
" \u001b[1m(\u001b[0m\n",
" \u001b[1m(\u001b[0m\n",
" \u001b[1mInstruction\u001b[0m\u001b[1m(\u001b[0m'LOAD_FAST', \u001b[1mVarname\u001b[0m\u001b[1m(\u001b[0m'a'\u001b[1m)\u001b[0m, line_number=\u001b[1m7\u001b[0m\u001b[1m)\u001b[0m,\n",
" \u001b[1mInstruction\u001b[0m\u001b[1m(\u001b[0m'LOAD_FAST', \u001b[1mVarname\u001b[0m\u001b[1m(\u001b[0m'b'\u001b[1m)\u001b[0m, line_number=\u001b[1m7\u001b[0m\u001b[1m)\u001b[0m,\n",
" \u001b[1mInstruction\u001b[0m\u001b[1m(\u001b[0m'BINARY_ADD', line_number=\u001b[1m7\u001b[0m\u001b[1m)\u001b[0m,\n",
" \u001b[1mInstruction\u001b[0m\u001b[1m(\u001b[0m'RETURN_VALUE', line_number=\u001b[1m7\u001b[0m\u001b[1m)\u001b[0m\n",
" \u001b[1m)\u001b[0m,\n",
" \u001b[1m)\u001b[0m,\n",
" filename='/tmp/ipykernel_635/3063237183.py',\n",
" first_line_number=\u001b[1m6\u001b[0m,\n",
" name='fn',\n",
" stacksize=\u001b[1m2\u001b[0m,\n",
" type=\u001b[1mFunction\u001b[0m\u001b[1m(\u001b[0m\u001b[1mArgs\u001b[0m\u001b[1m(\u001b[0mpositional_or_keyword=\u001b[1m(\u001b[0m'a', 'b'\u001b[1m)\u001b[0m\u001b[1m)\u001b[0m\u001b[1m)\u001b[0m,\n",
" _additional_args=\u001b[1m(\u001b[0m\u001b[1mConstant\u001b[0m\u001b[1m(\u001b[0m\u001b[3mNone\u001b[0m, _index_override=\u001b[1m0\u001b[0m\u001b[1m)\u001b[0m,\u001b[1m)\u001b[0m\n",
"\u001b[1m)\u001b[0m\n"
]
},
"metadata": {},
"output_type": "display_data"
}
],
"source": [
"# Load rich first for prettier output\n",
"from rich import pretty\n",
"pretty.install()\n",
"from code_data import CodeData\n",
"\n",
"def fn(a, b):\n",
" return a + b\n",
"\n",
"cd = CodeData.from_code(fn.__code__)\n",
"cd"
]
},
{
"cell_type": "markdown",
"id": "00eabb3c",
"metadata": {},
"source": [
"Instead of using Python's built in code object, or the `dis` module, it reduces the amoutn of information to only that which is needed to recreate the code object. So all information about how it happens to be stored on disk, the bytecode offsets for example of each instruction, is ommited, making it simpler to use.\n",
"\n",
"### `normalize`\n",
"\n",
"We are also able to \"normalize\" the code object, removing pieces of it that are unused. For example, if you have dead code, Python will still include the constants\n",
"that are present in it, even though there is no way they can be accessed:"
]
},
{
"cell_type": "code",
"execution_count": 2,
"id": "fe39e542",
"metadata": {},
"outputs": [
{
"data": {
"text/html": [
"\n",
"CodeData(\n",
" (\n",
" (\n",
" Instruction('NOP', line_number=2),\n",
" Instruction(\n",
" 'LOAD_CONST',\n",
" Constant(1, _index_override=3),\n",
" line_number=4\n",
" ),\n",
" Instruction(\n",
" 'STORE_FAST',\n",
" Varname('x', _index_override=0),\n",
" line_number=4\n",
" ),\n",
" Instruction(\n",
" 'LOAD_CONST',\n",
" Constant(None, _index_override=0),\n",
" line_number=4\n",
" ),\n",
" Instruction('RETURN_VALUE', line_number=4)\n",
" ),\n",
" ),\n",
" filename='/tmp/ipykernel_635/2121495508.py',\n",
" first_line_number=1,\n",
" name='fn',\n",
" stacksize=1,\n",
" type=Function(),\n",
" _additional_args=(\n",
" Constant(False, _index_override=1),\n",
" Constant(20, _index_override=2)\n",
" )\n",
")\n",
"\n"
],
"text/plain": [
"\n",
"\u001b[1mCodeData\u001b[0m\u001b[1m(\u001b[0m\n",
" \u001b[1m(\u001b[0m\n",
" \u001b[1m(\u001b[0m\n",
" \u001b[1mInstruction\u001b[0m\u001b[1m(\u001b[0m'NOP', line_number=\u001b[1m2\u001b[0m\u001b[1m)\u001b[0m,\n",
" \u001b[1mInstruction\u001b[0m\u001b[1m(\u001b[0m\n",
" 'LOAD_CONST',\n",
" \u001b[1mConstant\u001b[0m\u001b[1m(\u001b[0m\u001b[1m1\u001b[0m, _index_override=\u001b[1m3\u001b[0m\u001b[1m)\u001b[0m,\n",
" line_number=\u001b[1m4\u001b[0m\n",
" \u001b[1m)\u001b[0m,\n",
" \u001b[1mInstruction\u001b[0m\u001b[1m(\u001b[0m\n",
" 'STORE_FAST',\n",
" \u001b[1mVarname\u001b[0m\u001b[1m(\u001b[0m'x', _index_override=\u001b[1m0\u001b[0m\u001b[1m)\u001b[0m,\n",
" line_number=\u001b[1m4\u001b[0m\n",
" \u001b[1m)\u001b[0m,\n",
" \u001b[1mInstruction\u001b[0m\u001b[1m(\u001b[0m\n",
" 'LOAD_CONST',\n",
" \u001b[1mConstant\u001b[0m\u001b[1m(\u001b[0m\u001b[3mNone\u001b[0m, _index_override=\u001b[1m0\u001b[0m\u001b[1m)\u001b[0m,\n",
" line_number=\u001b[1m4\u001b[0m\n",
" \u001b[1m)\u001b[0m,\n",
" \u001b[1mInstruction\u001b[0m\u001b[1m(\u001b[0m'RETURN_VALUE', line_number=\u001b[1m4\u001b[0m\u001b[1m)\u001b[0m\n",
" \u001b[1m)\u001b[0m,\n",
" \u001b[1m)\u001b[0m,\n",
" filename='/tmp/ipykernel_635/2121495508.py',\n",
" first_line_number=\u001b[1m1\u001b[0m,\n",
" name='fn',\n",
" stacksize=\u001b[1m1\u001b[0m,\n",
" type=\u001b[1mFunction\u001b[0m\u001b[1m(\u001b[0m\u001b[1m)\u001b[0m,\n",
" _additional_args=\u001b[1m(\u001b[0m\n",
" \u001b[1mConstant\u001b[0m\u001b[1m(\u001b[0m\u001b[3mFalse\u001b[0m, _index_override=\u001b[1m1\u001b[0m\u001b[1m)\u001b[0m,\n",
" \u001b[1mConstant\u001b[0m\u001b[1m(\u001b[0m\u001b[1m20\u001b[0m, _index_override=\u001b[1m2\u001b[0m\u001b[1m)\u001b[0m\n",
" \u001b[1m)\u001b[0m\n",
"\u001b[1m)\u001b[0m\n"
]
},
"metadata": {},
"output_type": "display_data"
}
],
"source": [
"def fn():\n",
" if False:\n",
" x = 20\n",
" x = 1\n",
"\n",
"\n",
"cd = CodeData.from_code(fn.__code__)\n",
"cd"
]
},
{
"cell_type": "code",
"execution_count": 3,
"id": "94f46263",
"metadata": {},
"outputs": [
{
"data": {
"text/html": [
"\n",
"CodeData(\n",
" (\n",
" (\n",
" Instruction('NOP', line_number=2),\n",
" Instruction('LOAD_CONST', Constant(1), line_number=4),\n",
" Instruction('STORE_FAST', Varname('x'), line_number=4),\n",
" Instruction('LOAD_CONST', Constant(None), line_number=4),\n",
" Instruction('RETURN_VALUE', line_number=4)\n",
" ),\n",
" ),\n",
" filename='/tmp/ipykernel_635/2121495508.py',\n",
" first_line_number=1,\n",
" name='fn',\n",
" stacksize=1,\n",
" type=Function()\n",
")\n",
"\n"
],
"text/plain": [
"\n",
"\u001b[1mCodeData\u001b[0m\u001b[1m(\u001b[0m\n",
" \u001b[1m(\u001b[0m\n",
" \u001b[1m(\u001b[0m\n",
" \u001b[1mInstruction\u001b[0m\u001b[1m(\u001b[0m'NOP', line_number=\u001b[1m2\u001b[0m\u001b[1m)\u001b[0m,\n",
" \u001b[1mInstruction\u001b[0m\u001b[1m(\u001b[0m'LOAD_CONST', \u001b[1mConstant\u001b[0m\u001b[1m(\u001b[0m\u001b[1m1\u001b[0m\u001b[1m)\u001b[0m, line_number=\u001b[1m4\u001b[0m\u001b[1m)\u001b[0m,\n",
" \u001b[1mInstruction\u001b[0m\u001b[1m(\u001b[0m'STORE_FAST', \u001b[1mVarname\u001b[0m\u001b[1m(\u001b[0m'x'\u001b[1m)\u001b[0m, line_number=\u001b[1m4\u001b[0m\u001b[1m)\u001b[0m,\n",
" \u001b[1mInstruction\u001b[0m\u001b[1m(\u001b[0m'LOAD_CONST', \u001b[1mConstant\u001b[0m\u001b[1m(\u001b[0m\u001b[3mNone\u001b[0m\u001b[1m)\u001b[0m, line_number=\u001b[1m4\u001b[0m\u001b[1m)\u001b[0m,\n",
" \u001b[1mInstruction\u001b[0m\u001b[1m(\u001b[0m'RETURN_VALUE', line_number=\u001b[1m4\u001b[0m\u001b[1m)\u001b[0m\n",
" \u001b[1m)\u001b[0m,\n",
" \u001b[1m)\u001b[0m,\n",
" filename='/tmp/ipykernel_635/2121495508.py',\n",
" first_line_number=\u001b[1m1\u001b[0m,\n",
" name='fn',\n",
" stacksize=\u001b[1m1\u001b[0m,\n",
" type=\u001b[1mFunction\u001b[0m\u001b[1m(\u001b[0m\u001b[1m)\u001b[0m\n",
"\u001b[1m)\u001b[0m\n"
]
},
"metadata": {},
"output_type": "display_data"
}
],
"source": [
"cd.normalize()"
]
},
{
"cell_type": "markdown",
"id": "9d84f7b2",
"metadata": {},
"source": [
"### JSON Support\n",
"\n",
"Since the code object is now a simple data structure, we can serialize it to and from JSON. This provides a nice option if you want to analyze Python bytecode in a different language or save it on disk:"
]
},
{
"cell_type": "code",
"execution_count": 4,
"id": "415dc000",
"metadata": {},
"outputs": [
{
"data": {
"text/html": [
"\n",
"{\n",
" 'blocks': [\n",
" [\n",
" {'name': 'NOP', 'line_number': 2},\n",
" {\n",
" 'name': 'LOAD_CONST',\n",
" 'arg': {'constant': 1, '_index_override': 3},\n",
" 'line_number': 4\n",
" },\n",
" {\n",
" 'name': 'STORE_FAST',\n",
" 'arg': {'varname': 'x', '_index_override': 0},\n",
" 'line_number': 4\n",
" },\n",
" {\n",
" 'name': 'LOAD_CONST',\n",
" 'arg': {'constant': None, '_index_override': 0},\n",
" 'line_number': 4\n",
" },\n",
" {'name': 'RETURN_VALUE', 'line_number': 4}\n",
" ]\n",
" ],\n",
" 'filename': '/tmp/ipykernel_635/2121495508.py',\n",
" 'first_line_number': 1,\n",
" 'name': 'fn',\n",
" 'stacksize': 1,\n",
" 'type': {},\n",
" '_additional_args': [\n",
" {'constant': False, '_index_override': 1},\n",
" {'constant': 20, '_index_override': 2}\n",
" ]\n",
"}\n",
"\n"
],
"text/plain": [
"\n",
"\u001b[1m{\u001b[0m\n",
" 'blocks': \u001b[1m[\u001b[0m\n",
" \u001b[1m[\u001b[0m\n",
" \u001b[1m{\u001b[0m'name': 'NOP', 'line_number': \u001b[1m2\u001b[0m\u001b[1m}\u001b[0m,\n",
" \u001b[1m{\u001b[0m\n",
" 'name': 'LOAD_CONST',\n",
" 'arg': \u001b[1m{\u001b[0m'constant': \u001b[1m1\u001b[0m, '_index_override': \u001b[1m3\u001b[0m\u001b[1m}\u001b[0m,\n",
" 'line_number': \u001b[1m4\u001b[0m\n",
" \u001b[1m}\u001b[0m,\n",
" \u001b[1m{\u001b[0m\n",
" 'name': 'STORE_FAST',\n",
" 'arg': \u001b[1m{\u001b[0m'varname': 'x', '_index_override': \u001b[1m0\u001b[0m\u001b[1m}\u001b[0m,\n",
" 'line_number': \u001b[1m4\u001b[0m\n",
" \u001b[1m}\u001b[0m,\n",
" \u001b[1m{\u001b[0m\n",
" 'name': 'LOAD_CONST',\n",
" 'arg': \u001b[1m{\u001b[0m'constant': \u001b[3mNone\u001b[0m, '_index_override': \u001b[1m0\u001b[0m\u001b[1m}\u001b[0m,\n",
" 'line_number': \u001b[1m4\u001b[0m\n",
" \u001b[1m}\u001b[0m,\n",
" \u001b[1m{\u001b[0m'name': 'RETURN_VALUE', 'line_number': \u001b[1m4\u001b[0m\u001b[1m}\u001b[0m\n",
" \u001b[1m]\u001b[0m\n",
" \u001b[1m]\u001b[0m,\n",
" 'filename': '/tmp/ipykernel_635/2121495508.py',\n",
" 'first_line_number': \u001b[1m1\u001b[0m,\n",
" 'name': 'fn',\n",
" 'stacksize': \u001b[1m1\u001b[0m,\n",
" 'type': \u001b[1m{\u001b[0m\u001b[1m}\u001b[0m,\n",
" '_additional_args': \u001b[1m[\u001b[0m\n",
" \u001b[1m{\u001b[0m'constant': \u001b[3mFalse\u001b[0m, '_index_override': \u001b[1m1\u001b[0m\u001b[1m}\u001b[0m,\n",
" \u001b[1m{\u001b[0m'constant': \u001b[1m20\u001b[0m, '_index_override': \u001b[1m2\u001b[0m\u001b[1m}\u001b[0m\n",
" \u001b[1m]\u001b[0m\n",
"\u001b[1m}\u001b[0m\n"
]
},
"metadata": {},
"output_type": "display_data"
}
],
"source": [
"code_json = cd.to_json_data()\n",
"assert CodeData.from_json_data(code_json) == cd\n",
"\n",
"code_json"
]
},
{
"cell_type": "markdown",
"id": "6b4845a9",
"metadata": {},
"source": [
"## Command Line\n",
"\n",
"We provide a CLI command `python-code-data` which is useful for debugging or introspecting code objects from the command line.\n",
"\n",
"It contains many of the same\n",
"flags to load Python code as the default Python CLI, including from a string (`-c`),\n",
"from a module (`-m`), or from a path (``). It also includes a way to\n",
"load a string from Python code to eval it first, which is useful for generating\n",
"test cases on the CLI of program strings."
]
},
{
"cell_type": "code",
"execution_count": 5,
"id": "d14d260b",
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"usage: python-code-data [-h] [-c cmd] [-e eval] [-m mod] [--dis] [--dis-after]\r\n",
" [--source] [--no-normalize] [--json]\r\n",
" [file]\r\n",
"\r\n",
"Inspect Python code objects.\r\n",
"\r\n",
"positional arguments:\r\n",
" file path to Python program\r\n",
"\r\n",
"options:\r\n",
" -h, --help show this help message and exit\r\n",
" -c cmd program passed in as string\r\n",
" -e eval string evalled to make program\r\n",
" -m mod python library\r\n",
" --dis print Python's dis analysis\r\n",
" --dis-after print Python's dis analysis after round tripping to code-\r\n",
" data, for testing\r\n",
" --source print the source code\r\n",
" --no-normalize don't normalize code data before printing\r\n",
" --json Print the JSON represenation of the code data as well\r\n"
]
}
],
"source": [
"! python-code-data -h"
]
},
{
"cell_type": "code",
"execution_count": 6,
"id": "598010d2",
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"\u001b[1mCodeData\u001b[0m\u001b[1m(\u001b[0m\r\n",
" \u001b[1m(\u001b[0m\r\n",
" \u001b[1m(\u001b[0m\r\n",
" \u001b[1mInstruction\u001b[0m\u001b[1m(\u001b[0m'LOAD_NAME', \u001b[1mName\u001b[0m\u001b[1m(\u001b[0m'y'\u001b[1m)\u001b[0m, line_number=\u001b[1m1\u001b[0m\u001b[1m)\u001b[0m,\r\n",
" \u001b[1mInstruction\u001b[0m\u001b[1m(\u001b[0m'POP_JUMP_IF_FALSE', \u001b[1mJump\u001b[0m\u001b[1m(\u001b[0m\u001b[1m1\u001b[0m\u001b[1m)\u001b[0m, line_number=\u001b[1m1\u001b[0m\u001b[1m)\u001b[0m,\r\n",
" \u001b[1mInstruction\u001b[0m\u001b[1m(\u001b[0m'LOAD_NAME', \u001b[1mName\u001b[0m\u001b[1m(\u001b[0m'x'\u001b[1m)\u001b[0m, line_number=\u001b[1m1\u001b[0m\u001b[1m)\u001b[0m,\r\n",
" \u001b[1mInstruction\u001b[0m\u001b[1m(\u001b[0m'POP_TOP', line_number=\u001b[1m1\u001b[0m\u001b[1m)\u001b[0m,\r\n",
" \u001b[1mInstruction\u001b[0m\u001b[1m(\u001b[0m'LOAD_CONST', \u001b[1mConstant\u001b[0m\u001b[1m(\u001b[0m\u001b[3mNone\u001b[0m\u001b[1m)\u001b[0m, line_number=\u001b[1m1\u001b[0m\u001b[1m)\u001b[0m,\r\n",
" \u001b[1mInstruction\u001b[0m\u001b[1m(\u001b[0m'RETURN_VALUE', line_number=\u001b[1m1\u001b[0m\u001b[1m)\u001b[0m\r\n",
" \u001b[1m)\u001b[0m,\r\n",
" \u001b[1m(\u001b[0m\r\n",
" \u001b[1mInstruction\u001b[0m\u001b[1m(\u001b[0m'LOAD_NAME', \u001b[1mName\u001b[0m\u001b[1m(\u001b[0m'z'\u001b[1m)\u001b[0m, line_number=\u001b[1m1\u001b[0m\u001b[1m)\u001b[0m,\r\n",
" \u001b[1mInstruction\u001b[0m\u001b[1m(\u001b[0m'POP_TOP', line_number=\u001b[1m1\u001b[0m\u001b[1m)\u001b[0m,\r\n",
" \u001b[1mInstruction\u001b[0m\u001b[1m(\u001b[0m'LOAD_CONST', \u001b[1mConstant\u001b[0m\u001b[1m(\u001b[0m\u001b[3mNone\u001b[0m\u001b[1m)\u001b[0m, line_number=\u001b[1m1\u001b[0m\u001b[1m)\u001b[0m,\r\n",
" \u001b[1mInstruction\u001b[0m\u001b[1m(\u001b[0m'RETURN_VALUE', line_number=\u001b[1m1\u001b[0m\u001b[1m)\u001b[0m\r\n",
" \u001b[1m)\u001b[0m\r\n",
" \u001b[1m)\u001b[0m,\r\n",
" filename='',\r\n",
" first_line_number=\u001b[1m1\u001b[0m,\r\n",
" name='',\r\n",
" stacksize=\u001b[1m1\u001b[0m\r\n",
"\u001b[1m)\u001b[0m\r\n"
]
}
],
"source": [
"! python-code-data -c 'x if y else z'"
]
}
],
"metadata": {
"jupytext": {
"cell_metadata_filter": "-all",
"formats": "md:myst",
"text_representation": {
"extension": ".md",
"format_name": "myst",
"format_version": 0.13,
"jupytext_version": "1.11.5"
}
},
"kernelspec": {
"display_name": "Python 3 (ipykernel)",
"language": "python",
"name": "python3"
},
"language_info": {
"codemirror_mode": {
"name": "ipython",
"version": 3
},
"file_extension": ".py",
"mimetype": "text/x-python",
"name": "python",
"nbconvert_exporter": "python",
"pygments_lexer": "ipython3",
"version": "3.10.4"
},
"source_map": [
14,
24,
35,
44,
55,
57,
63,
68,
80,
84
]
},
"nbformat": 4,
"nbformat_minor": 5
}