From c29b951867f70b14855410093e60f02177f1cb8e Mon Sep 17 00:00:00 2001 From: youkaichao Date: Sun, 25 Aug 2024 21:08:07 -0700 Subject: [PATCH 1/3] add doc --- docs/index.rst | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/index.rst b/docs/index.rst index cd840342..199c2e33 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -61,10 +61,13 @@ The following figure shows two typical usages of ``depyf``, and lists all the ge You can also check `the advanced usages <./index.html>`_ and `frequently asked questions <./faq.html>`_ for more details. +If you'd like to contribute (which we highly appreciate), please read the `developer documentation <./dev_doc.html>`_ section. + .. toctree:: :maxdepth: 1 :hidden: walk_through advanced - faq \ No newline at end of file + faq + dev_doc From b96f8f2c83a9aeb69f51b6cb8e9602a8bde34b38 Mon Sep 17 00:00:00 2001 From: youkaichao Date: Sun, 25 Aug 2024 21:08:18 -0700 Subject: [PATCH 2/3] add doc --- docs/dev_doc.rst | 40 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) create mode 100644 docs/dev_doc.rst diff --git a/docs/dev_doc.rst b/docs/dev_doc.rst new file mode 100644 index 00000000..3c18d654 --- /dev/null +++ b/docs/dev_doc.rst @@ -0,0 +1,40 @@ +Developer Documentation +=========================================== + +For developers, if you want to understand and contribute to the codebase, this section is for you. + +It is recommended to read the following materials before diving into the codebase: + +- `torchdynamo deepdive `_ : This video explains the motivation and design of torchdynamo. In particular, it mentions how Python bytecode acts like a stack machine, which helps to understand how the bytecode is executed. +- `Python bytecode documentation `_ : This documentation explains the Python bytecode instructions. Note that Python bytecode does not guarentee any backward compatibility, so the bytecode instructions may change for every Python versions. We should consider all the supported Python versions when implementing the decompiler. +- `A Python Interpreter Written in Python `_ : This book chapter explains how to write a Python interpreter in Python. It is a good starting point to understand how Python bytecode is executed. + +The decompilation process is achieved by executing the Python bytecode and recording the stack and the variables, with the value of the variables represented by their source code. + +For example, consider the following simple function: + +.. code-block:: python + + def f(a, b): + return a + b + +It has the following bytecode: + +.. code-block:: text + + 0 LOAD_FAST 0 (a) + 2 LOAD_FAST 1 (b) + 4 BINARY_ADD + 6 RETURN_VALUE + +When we execute the first bytecode `LOAD_FAST`, instead of loading a variable into the stack, we push the variable name ``"a"`` in the stack, which is a string representation of the variable. + +When we execute the second bytecode `LOAD_FAST`, likewise, we push the variable name ``"b"`` in the stack. + +When we execute the third bytecode `BINARY_ADD`, which intends to add the two variables, we pop the two variables from the stack, and perform the string concatenation ``"a + b"``. The concatenated string is pushed back to the stack. + +Finally, when we execute the fourth bytecode `RETURN_VALUE`, we pop the string from the stack, prefix it with the ``return`` keyword, and then we get the decompiled source code ``"return a + b"``. + +To accurately decompile the bytecode, we need to faithfully respect the semantics of the Python bytecode instructions. It is noteworthy that the `Python bytecode documentation `_ can be outdated and inaccurate, too. The golden standard is to refer to the CPython source code and the Python interpreter's behavior. The `torchdynamo source code `_ is also a good reference to understand how the Python bytecode is generated by PyTorch. + +Should you have any further questions, feel free to ask in the `GitHub Issues `_ section. From 15d9d702e5ff8911a20c88bb0e35ad56dafda9ba Mon Sep 17 00:00:00 2001 From: youkaichao Date: Sun, 25 Aug 2024 21:12:32 -0700 Subject: [PATCH 3/3] add doc --- docs/dev_doc.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/dev_doc.rst b/docs/dev_doc.rst index 3c18d654..05fd4ce7 100644 --- a/docs/dev_doc.rst +++ b/docs/dev_doc.rst @@ -38,3 +38,4 @@ Finally, when we execute the fourth bytecode `RETURN_VALUE`, we pop the string f To accurately decompile the bytecode, we need to faithfully respect the semantics of the Python bytecode instructions. It is noteworthy that the `Python bytecode documentation `_ can be outdated and inaccurate, too. The golden standard is to refer to the CPython source code and the Python interpreter's behavior. The `torchdynamo source code `_ is also a good reference to understand how the Python bytecode is generated by PyTorch. Should you have any further questions, feel free to ask in the `GitHub Issues `_ section. +