How zrax/pycdc works
Project Type & Purpose
• A C++-based command-line tool providing two front-ends:
• pycdas – a Python byte-code disassembler
• pycdc – a Python byte-code decompiler
• Supports all Python versions by shipping version-specific opcode maps.
File Structure
• Root sources:
• pycdas.cpp, pycdc.cpp – CLI entrypoints
• bytecode.cpp/.h, bytecode_ops.inl – disassembler core
• ASTNode.*, ASTree.* – in-memory AST representation
• pyc_*.cpp/.h (module, code, numeric, object, sequence, string) – decompiler codegen
• FastStack.h, data.* – utilities
• bytes/: per-version opcode maps (e.g. python_3_10.cpp)
• scripts/: CI/Docker builds, Python-build patches, test harness setup
• tests/:
• tests/input/….py – test Python snippets
• tests/tokenized/….txt – expected disassembly
• tests/run_tests.py – test runner
README for Insights
• Confirms CMake-driven build, CLI usage patterns, support for marshalled code objects, plug-in style version control.
Main Components & Their Relationships
a. CLI Front-Ends (pycdas, pycdc)
– Parse command-line flags → open .pyc file
b. Bytecode Loader (pyc_module, pyc_code)
– Read header, extract raw byte stream or marshalled object
c. Disassembler Engine (bytecode.cpp, bytecode_ops)
– Uses version maps from bytes/ → emits token stream
d. AST Builder (ASTNode, ASTree)
– Consumes tokens → constructs AST
e. Decompiler Code Generator (pyc_numeric, pyc_object, etc.)
– Traverses AST (Visitor pattern) → emits Python source
f. Utilities (FastStack, data)
g. Version Maps (bytes/python_X_Y.cpp)
– Plug-in modules for opcode definitions
h. Testing Harness
– Invokes CLI tools → compares output to expected tokens/source
Data Flow:
.pyc file → Loader → Disassembler → Token Stream → AST Builder → AST → Code Generator → .py source on stdout
Architectural Patterns & Design Principles
• Modular layering: loader, disassembler, AST, codegen
• Plug-in/version pattern: add new bytes/python_X_Y.cpp for new Python versions
• Visitor-style AST traversals for code generation
• Separation of concerns: tests, scripts, build system isolated
Technologies & Frameworks
• C++ (ISO, C++17 or later)
• CMake (build orchestration)
• Python scripts (testing, Dockerfile generation)
• GitHub Actions (CI workflows under .github/workflows/)
Essential Elements
• Build orchestration (CMake) as a separate top-level element
• Test harness path from CLI → tests → pass/fail reports