feat: add WIP interpreter internals and bytecode analysis tools

- Add bytecode inspector with disassembly analysis
- Add interpreter internals documentation and code
- Add lambda AST explorer and bytecode analysis
- Include supporting documentation files

These are work-in-progress tools for understanding Python's internal
execution model and bytecode generation.

Co-Authored-By: Claude <noreply@anthropic.com>

Author: claude

bytecode-inspector.org

@@ -0,0 +1,53 @@
+#+TITLE: Python Bytecode Inspector
+#+AUTHOR: jwalsh
+#+DATE: [2025-04-04]
+#+PROPERTY: header-args:python :tangle bytecode_inspector.py :mkdirp t
+
+* Python Bytecode Inspector
+
+This tool compiles Python files to bytecode and allows inspection of the generated bytecode.
+
+** Implementation
+
+#+begin_src python
+# bytecode_inspector.py code here...
+#+end_src
+
+** Usage Examples
+
+*** Compile and inspect closures.py
+#+begin_src shell :results output
+python bytecode_inspector.py closures.py
+#+end_src
+
+*** Inspect existing bytecode without recompiling
+#+begin_src shell :results output
+python bytecode_inspector.py closures.py --no-compile
+#+end_src
+
+*** Batch process multiple files
+#+begin_src shell :results output
+for file in *.py; do
+  echo "Processing $file..."
+  python bytecode_inspector.py "$file"
+done
+#+end_src
+
+** Mermaid Diagram: Bytecode Inspection Process
+
+#+begin_src mermaid :file bytecode_process.png
+flowchart TD
+    A[Python Source File] -->|py_compile| B[.pyc File]
+    B -->|importlib| C[Load Module]
+    B -->|direct read| D[Read Raw Bytecode]
+    C -->|dis.dis| E[Disassemble Functions]
+    D -->|marshal.load| F[Load Code Object]
+    F -->|dis.dis| G[Disassemble Raw Bytecode]
+    E --> H[Bytecode Analysis]
+    G --> H
+#+end_src
+
+* Future Enhancements
+- Add comparison between different Python versions
+- Visualize bytecode execution flow
+- Analyze optimization opportunities

bytecode_inspector.py

@@ -0,0 +1,104 @@
+# bytecode_inspector.py
+
+import py_compile
+import dis
+import os
+import marshal
+import importlib.util
+import argparse
+from pathlib import Path
+
+def compile_to_bytecode(file_path):
+    """Compile a Python file to bytecode and return the path to the .pyc file"""
+    try:
+        py_compile.compile(file_path)
+        print(f"Successfully compiled {file_path}")
+        
+        # Find the compiled .pyc file
+        cache_dir = '__pycache__'
+        base_name = os.path.basename(file_path)
+        module_name = os.path.splitext(base_name)[0]
+        
+        if os.path.exists(cache_dir):
+            pyc_files = [f for f in os.listdir(cache_dir) if f.startswith(f"{module_name}.")]
+            if pyc_files:
+                return os.path.join(cache_dir, pyc_files[0])
+    except Exception as e:
+        print(f"Error compiling {file_path}: {e}")
+    
+    return None
+
+def inspect_bytecode(pyc_path):
+    """Disassemble and inspect a .pyc file"""
+    if not pyc_path or not os.path.exists(pyc_path):
+        print("No valid .pyc file found")
+        return
+    
+    try:
+        # Load the module from the .pyc file
+        spec = importlib.util.spec_from_file_location("module.name", pyc_path)
+        if spec:
+            module = importlib.util.module_from_spec(spec)
+            spec.loader.exec_module(module)
+            
+            # Print all functions/classes and their bytecode
+            for name, obj in module.__dict__.items():
+                if callable(obj) and not name.startswith('__'):
+                    print(f"\n{'='*50}")
+                    print(f"Disassembly of {name}:")
+                    print(f"{'='*50}")
+                    dis.dis(obj)
+        
+        # Directly examine the bytecode
+        print(f"\n{'='*50}")
+        print(f"Raw bytecode from {pyc_path}:")
+        print(f"{'='*50}")
+        with open(pyc_path, 'rb') as pyc_file:
+            # Skip the magic number and timestamp/size
+            pyc_file.read(16)  # 4 bytes magic + 4 bytes timestamp + 4 bytes size + 4 bytes hash
+            
+            # Load the code object
+            try:
+                code_obj = marshal.load(pyc_file)
+                dis.dis(code_obj)
+            except Exception as e:
+                print(f"Error loading code object: {e}")
+                
+    except Exception as e:
+        print(f"Error inspecting {pyc_path}: {e}")
+
+def main():
+    parser = argparse.ArgumentParser(description='Compile Python files to bytecode and inspect them')
+    parser.add_argument('file', help='Python file to compile and inspect')
+    parser.add_argument('--no-compile', action='store_true', 
+                        help='Inspect existing .pyc without recompiling')
+    
+    args = parser.parse_args()
+    
+    file_path = args.file
+    if not os.path.exists(file_path):
+        print(f"File not found: {file_path}")
+        return
+    
+    if args.no_compile:
+        # Try to find existing .pyc file
+        cache_dir = '__pycache__'
+        base_name = os.path.basename(file_path)
+        module_name = os.path.splitext(base_name)[0]
+        
+        if os.path.exists(cache_dir):
+            pyc_files = [f for f in os.listdir(cache_dir) if f.startswith(f"{module_name}.")]
+            if pyc_files:
+                pyc_path = os.path.join(cache_dir, pyc_files[0])
+                print(f"Using existing .pyc file: {pyc_path}")
+                inspect_bytecode(pyc_path)
+            else:
+                print(f"No existing .pyc file found for {file_path}")
+    else:
+        pyc_path = compile_to_bytecode(file_path)
+        if pyc_path:
+            print(f"Compiled to: {pyc_path}")
+            inspect_bytecode(pyc_path)
+
+if __name__ == "__main__":
+    main()