Python字节码反编译

Decompile an entire project tree (mirrors structure into output dir):

uv run pychd decompile path/to/package/ -o recovered/

How it works — compiler-pipeline perspective

Step 1: Python compiles your source to bytecode

The CPython compiler takes your foo.py and emits foo.pyc — a binary file containing a code object for the module plus a nested code object for every function and class. Each code object holds:

- the bytecode instructions (one byte opcode + one byte argument, since 3.6 "wordcode"), - a co_consts tuple of constants used in those instructions, - a co_names tuple of identifier names, - a co_varnames tuple of local variable names, - argument counts (co_argcount, co_kwonlyargcount, etc.), - flag bits (co_flags: is it a coroutine? a generator? does it use *args?).

You can poke at this on any Python install:

>>> import dis
>>> def f(a, b=1): return a + b
>>> dis.dis(f)
  1           RESUME                   0
              LOAD_FAST                0 (a)
              LOAD_FAST                1 (b)
              BINARY_OP                0 (+)
              RETURN_VALUE
>>> f.__code__.co_argcount, f.__code__.co_varnames
(2, ('a', 'b'))

What pychd builds internally for `from os.path import join`:

ir.FromImport(module="os.path", level=0, names=[("join", None)])

then compile with Python 3.8 and run pychd + decompyle3 — see

Quick start

```bash uv tool install pychd pychd decompile path/to/module.pyc --hybrid-rewrite --backend codex

More CLI examples

```bash

Example 1: a re-export module (full rule recovery, 0 LLM calls)

Original source (a typical __init__.py):

"""Public surface for the foo package."""

from .core import Bar, Baz
from .util import parse, as_dict
from .errors import FooError

__all__ = ["Bar", "Baz", "FooError", "as_dict", "parse"]

After pychd decompile --rules-only:

"""Public surface for the foo package."""

from .core import Bar, Baz
from .util import parse, as_dict
from .errors import FooError

__all__ = ['Bar', 'Baz', 'FooError', 'as_dict', 'parse']

Identical modulo single vs double quotes in __all__. Zero LLM cost, recovered in 0.9 ms.

Example 2: a dataclass module (full hybrid-rewrite recovery)

Original:

from dataclasses import dataclass
from typing import Any

@dataclass(frozen=True)
class AgentMessage:
    type: str
    uuid: str
    agent_id: str
    message: Any = None

    @classmethod
    def from_json(cls, value):
        return cls(
            type=value["type"],
            uuid=value["uuid"],
            agent_id=value["agentId"],
            message=value.get("message"),
        )

After pychd decompile --hybrid-rewrite --backend codex (one LLM call per module; rule pass first, LLM corrects bodies + module-level recovery):

from dataclasses import dataclass
from typing import Any

@dataclass(frozen=True)
class AgentMessage:
    type: str
    uuid: str
    agent_id: str
    message: Any = None

    @classmethod
    def from_json(cls, value):
        return cls(
            type=value["type"],
            uuid=value["uuid"],
            agent_id=value["agentId"],
            message=value.get("message"),
        )

Byte-for-byte recovery on this shape — bytecode_exact round-trips under the producing 3.14 interpreter. The class declaration, every annotation, the @classmethod method decorator, the outer @dataclass(frozen=True) decorator with its keyword argument, and every method signature come straight from the rule pass; the body is filled by the LLM with the (signature + disassembly) it receives.

For the deterministic-only path:

<details><summary>Same input, <code>--rules-only</code> (no LLM)</summary>

from dataclasses import dataclass
from typing import Any

@dataclass(frozen=True)
class AgentMessage:
    type: str
    uuid: str
    agent_id: str
    message: Any = None

    @classmethod
    def from_json(cls, value):
        return cls(type=value['type'], uuid=value['uuid'], agent_id=value['agentId'], message=value.get('message'))

The trivial-body matcher even lifts this single-statement method into a real return cls(...), so the rules-only output here is already behaviorally equivalent — the LLM is only needed for multi- statement bodies and complex module-level constructs.

</details>

Example 3: a generic class (PEP 695, full hybrid-rewrite recovery)

Original:

class Stack[T]:
    def __init__(self):
        self.items: list[T] = []
    def push(self, x: T) -> None:
        self.items.append(x)

After pychd decompile --hybrid-rewrite --backend codex:

class Stack[T]:
    def __init__(self):
        self.items: list[T] = []

    def push(self, x: T) -> None:
        self.items.append(x)

Identical modulo whitespace. The PEP 695 type parameter [T] survives the rule pass — pychd recognises the synthetic <generic parameters of Stack> wrapper code object that the CPython compiler emits and unpacks it. Class-body and module-level annotations are recovered from the PEP 749 __annotate__ closure; parameter annotations (x: T) live in a separate per-method closure and the LLM rebuilds them from the disassembly during the rewrite step.

Example 4: a HumanEval problem (full bytecode round-trip)

Original (HumanEval_0.py):

from typing import List


def has_close_elements(numbers: List[float], threshold: float) -> bool:
    """ Check if in given list of numbers, are any two numbers closer to each other than
    given threshold.
    >>> has_close_elements([1.0, 2.0, 3.0], 0.5)
    False
    >>> has_close_elements([1.0, 2.8, 3.0, 4.0, 5.0, 2.0], 0.3)
    True
    """
    for idx, elem in enumerate(numbers):
        for idx2, elem2 in enumerate(numbers):
            if idx != idx2:
                distance = abs(elem - elem2)
                if distance < threshold:
                    return True

    return False

After pychd decompile --hybrid-rewrite --backend codex:

from typing import List


def has_close_elements(numbers: List[float], threshold: float) -> bool:
    """ Check if in given list of numbers, are any two numbers closer to each other than
    given threshold.
    >>> has_close_elements([1.0, 2.0, 3.0], 0.5)
    False
    >>> has_close_elements([1.0, 2.8, 3.0, 4.0, 5.0, 2.0], 0.3)
    True
    """
    for idx, elem in enumerate(numbers):
        for idx2, elem2 in enumerate(numbers):
            if idx != idx2:
                distance = abs(elem - elem2)
                if distance < threshold:
                    return True
    return False

bytecode_exact, bytecode_normalized, behavioral_smoke, and functional_correctness (the HumanEval check(candidate) oracle) all pass — the recovered module compiles to byte-identical bytecode and passes every assertion. Only difference from the original is a single blank line before the trailing return False, which the AST comparator normalises away.

Step 4 (optional, `--hybrid` mode): the LLM fills function bodies

For every UnknownBlock left in the tree, pychd sends a function-body-sized prompt to the configured LLM:

You are a Python decompiler.
The following Python 3.14 bytecode is the body of:
    def from_json(cls, value)
Reconstruct the original Python source for *just the body*…

LOAD_FAST_BORROW cls
LOAD_FAST_BORROW value
LOAD_CONST 'type'
BINARY_SUBSCR
…

The LLM never sees the rest of the module; the rule pass already nailed the signatures, imports, and names. This keeps prompts small, costs low, and identifier hallucination rare. One LLM call per body, so on modules with many small functions the cost stays modest.

Step 5 (optional, `--hybrid-rewrite` mode): the LLM rewrites the whole module

The per-body path in Step 4 fixes bodies but leaves any module-level recovery mistakes (an inlined dict comprehension that collapsed to X = {}, a for-loop side effect that wasn't preserved) unchanged. --hybrid-rewrite adds a final whole-module rewrite call:

`
You are a Python decompiler. Reconstruct the original Python 3.14
source for an entire module from its disassembled bytecode.

You are given two inputs:
1. The complete disassembled bytecode (authoritative).
2. A partial rule-based recovery (declarations reliable; bodies +
   some module-level statements may be wrong).

Bytecode disassembly:

Partial recovery:

Output ONLY valid Python 3.14 source code. Preserve every
class/function/import name from the partial recovery. Fix
module-level statements the rule pass got wrong by reading the
bytecode. The output must pass `ast.parse` and `py_compile`.

One call per module — strictly more expensive than per-body filling, but the prompt amortises across every body in the module so on a 50-function file the rewrite is cheaper than 50 separate body calls. The output is sanity-checked with ast.parse and the rule-only output is used as a fallback if the rewrite fails to parse.

This is the mode the headline benchmark numbers are reported under, and the one the README's worked examples show.

call per file. Uses your `codex login` session (no API key).

uv run pychd decompile path/to/module.pyc --hybrid-rewrite --backend codex

Pipeline at a glance

pychd routes every .pyc through two passes:

- Rule pass owns everything CPython compiles to a deterministic bytecode shape — imports, class/function declarations, signatures, decorators (incl. arguments), PEP 695 generics, PEP 749 lazy annotations, common one-line bodies (return self.x, return cls(...), constructor self.x = x, etc.). Output is reproducible offline and audit-friendly. Bodies it can't recover remain as pass. - Codex rewrite runs once per module with the disassembly + the rule pass's partial output as context. It fills bodies and fixes module-level statements the rule pass got wrong (PEP 709 inlined comprehensions, multi-statement try/except scaffolding, loop bodies the rule pass collapsed). Bytes go in, source comes out — the LLM never sees the original source.

Why bodies-as-pass happens in rule-only: a function body that compiles to non-trivial control flow (multiple statements, loops, branches, match) is many-to-one in bytecode — the same opcode sequence can come from several different source expressions. Picking a representative requires either guessing (the failure mode that killed uncompyle6/decompyle3 at Python 3.8) or asking an oracle. pychd chooses the oracle, so the rule pass deliberately leaves an UnknownBlock for the rewrite step to fill.

Hybrid-rewrite — rule pass + one LLM rewrite per module (fixes

body fills *and* module-level recovery). Recommended when you

Detailed recovery walkthrough — what happens to a real module

This section shows the four-stage recovery pipeline against a single example module — what each stage adds — so you can see why both the rule pass and the LLM are needed and what they contribute respectively.

The example: a slimmed-down dataclass module with three things the rule pass handles trivially (imports, decorators, signatures), one thing the trivial-body matcher lifts (a single-statement from_json classmethod), one thing only the LLM body fill can recover (a multi-statement __post_init__), and one thing only the `hybrid-rewrite` module-level fix-up can clean (a module-level dict-comprehension that the rule pass renders as `X = {}`).

Original agent.py:

from dataclasses import dataclass, field
from typing import Any

_ALIAS = {old: new for old, new in [('uid', 'uuid'), ('msg', 'message')]}

@dataclass(frozen=True)
class AgentMessage:
    type: str
    uuid: str
    agent_id: str
    message: Any = None
    tags: list[str] = field(default_factory=list)

    def __post_init__(self):
        if not self.type:
            raise ValueError("type must be non-empty")
        object.__setattr__(self, "type", self.type.lower())

    @classmethod
    def from_json(cls, value):
        return cls(
            type=value["type"],
            uuid=value["uuid"],
            agent_id=value["agentId"],
            message=value.get("message"),
        )

Step D: hybrid-rewrite corrects module-level mis-recoveries

pychd decompile --hybrid-rewrite --backend codex adds a final whole-module rewrite step: the LLM gets the disassembly of the entire module plus the rule pass' partial output, and emits the corrected full source. This catches:

- Module-level comprehensions the rule pass collapsed to X = {} / X = [] / X = .... - For-loop bodies whose loop variable leaked into top-level declarations (now suppressed by the rule pass' FOR_ITER skip, but the rewrite repairs older recoveries cleanly). - Multi-line dict literals whose MAP_ADD accumulator pattern was mis-read. - Module-level if __name__ == "__main__": guards. - Multi-statement try/except scaffolding.

Diff vs Step C:

-_ALIAS = {}
+_ALIAS = {old: new for old, new in [('uid', 'uuid'), ('msg', 'message')]}

Cost: one LLM call per module instead of one per body, so on modules with many small bodies (stdlib-full, pypi-top20) the rewrite is actually cheaper than per-body hybrid. The trade-off is prompt size — the rewrite sends the full module disassembly, so very large modules push closer to the model's context window. On the benchmark corpora this is rarely an issue (the largest single file fits comfortably).

This is the mode the headline numbers in Benchmarks are reported under.

Rule-only vs hybrid-rewrite ceiling

Comparison with prior Python decompilers

Four publicly-available decompilers compete with pychd on Python 3.x bytecode. Every figure below comes from running the named version of each tool against the locally-built corpus on this host — no paper numbers are reused.

The headline comparison axis is strict_match (stripped-AST equality). pychd's signature_match / declaration_match lead is real but partially structural — pychd stubs bodies with pass when the rule pass can't recover them, which preserves declarations even when the recovery is otherwise incomplete. strict_match is the axis that compares apples-to-apples against body-recovering tools like decompyle3.

Contamination-resistant head-to-head — synthetic Python 3.8

The eight synthetic modules (see §Contamination resistance) compiled with Python 3.8 and decompiled by each available 3.8-capable tool. None of these modules existed before 2026-05-26, so any tool that scores high here cannot be memorising.

Source: assets/_synthetic_comparison.json (commit-tracked). Reproduce:

```bash uv run python tools/build_corpora.py --only synthetic