depyo 1.1.0 → 1.2.1

package/README.md

@@ -1,116 +1,193 @@
 # depyo — Python bytecode decompiler in Node.js
 
-Depyo converts Python `.pyc` files (or archives of them) back to readable Python source. It aims for broad coverage (Python 1.0 through 3.14) and fast throughput, with fixtures for modern features (exception groups, pattern matching, walrus, f-strings, async, context managers).
+Depyo converts Python `.pyc` files (or archives of them) back to readable Python source — right from Node.js, without a Python runtime. Coverage spans **Python 1.0 through 3.15** plus PyPy, with first-class support for modern features: match/case, walrus, f-strings, exception groups, async/await, type parameters, PEP 696 TypeVar defaults, and t-strings (PEP 750).
 
-## Why depyo?
-- **Wide version coverage:** Opcode tables and expected outputs for Python 1.0–3.14, plus decompilation support for PyPy bytecode sets.
-- **Modern features:** WITH_EXCEPT_START/PREP_RERAISE_STAR, async/await, walrus, match/case, f-strings, type params, dict/set merges.
-- **Workflow friendly:** CLI options for asm dumps, raw spacing hints, raw `.pyc` preservation, and flattened output paths.
-- **Verification harness:** `run-fixtures.js` and `run-matrix.js` compare decompiled output against expected fixtures across versions.
+```bash
+npx depyo my_script.pyc
+# → writes my_script.py next to the input
+```
+
+## What it's good for
+
+- **Reverse engineering stripped Python.** You have a `.pyc` (maybe extracted from a PyInstaller binary, an Android APK's Kivy bundle, or an old archive) and no source. Depyo reconstructs the source — even for Python versions the original `uncompyle6`/`decompyle3` no longer follow.
+- **Malware / threat analysis.** Quickly triage suspicious Python payloads without setting up a matching Python interpreter. Add `--asm` for a bytecode listing alongside the source.
+- **Forensics on old codebases.** Resurrect Python 2.x (even 1.x) modules when the source is long gone.
+- **CI-side audits.** Depyo is a pure Node.js CLI — drop it in any Node pipeline to spot-check compiled `.pyc` against expected sources, or to extract and diff shipped bytecode.
+- **Learning tool.** Inspect how CPython lowers a given Python feature (comprehensions, pattern matching, exception groups) across versions. `--asm` is handy here.
+- **Batch processing.** Feed a `.zip` of `.pyc` files and get back a mirrored tree of `.py` sources.
+
+## Why depyo (vs alternatives)
+
+| Tool                  | Versions              | Modern features¹ | Runtime | Throughput | Notes                                        |
+| --------------------- | --------------------- | ---------------- | ------- | ---------- | -------------------------------------------- |
+| **depyo**             | 1.0–3.15 + PyPy       | Yes              | Node.js | ~0.1 ms/file² | Modern opcodes land fast; no Python needed |
+| uncompyle6/decompyle3 | 2.x–3.12 (stalled)    | Partial          | Python  | slower     | Development largely halted on 3.13+          |
+| pycdc (C++)           | 2.x–3.x (limited new) | Partial          | native  | fast       | Rich history, but slow to adopt new opcodes  |
+
+¹ match/case, walrus, f-strings, exception groups, async/await, type params.
+² Informal: `py314_exception_groups.pyc` × 50 in-process, Node 25, single thread (`--stats` on your machine for real numbers).
 
 ## Install
-- Global: `npm i -g depyo`
-- One-off: `npx depyo <file.pyc>`
 
-Node.js 20+ recommended (matches CI).
+```bash
+npm i -g depyo          # global CLI
+npx depyo <file.pyc>    # one-off, no install
+```
+
+Node.js 20+ recommended (CI gate).
 
 ## Quick start
 
 ```bash
-# Decompile a single .pyc
+# Single .pyc → writes <name>.py next to it
 node depyo.js /path/to/file.pyc
 
-# Decompile a zip of .pyc files, emit asm and keep raw bytes
-node depyo.js --asm --raw my_archive.zip
+# ZIP of .pyc files → mirrors structure
+node depyo.js my_archive.zip
 
-# Write sources next to inputs (skip directory mirroring)
-node depyo.js --skip-path /path/to/file.pyc
+# Also emit disassembly and preserve the raw .pyc
+node depyo.js --asm --raw my_archive.zip
 
-# Dump to stdout instead of files
+# Stream to stdout (no files written)
 node depyo.js --out /path/to/file.pyc
 
-# Marshal-only blob (no .pyc header)
-node depyo.js --marshal --py-version 3.11 /path/to/blob.bin
-node depyo.js --marshal /path/to/blob.bin
+# Flatten outputs (drop mirrored directories)
+node depyo.js --skip-path /path/to/file.pyc
 
-# Fast marshal scan (no decompile)
-node depyo.js --marshal-scan /path/to/blob.bin
+# Headerless marshal blob (no .pyc magic)
+node depyo.js --marshal --py-version 3.11 /path/to/blob.bin
+node depyo.js --marshal /path/to/blob.bin            # auto-scan
+node depyo.js --marshal-scan /path/to/blob.bin       # fast scan, no decompile
 ```
+
 Without `--py-version`, depyo scans supported versions (oldest → newest) and accepts the first clean output when all clean candidates agree. If outputs diverge (ambiguous), it stops and asks for `--py-version`. Use `--debug` to see scan results.
 
-### CLI options
-- `--asm` emit `.pyasm` disassembly alongside source
-- `--raw` emit raw `.pyc` next to output
-- `--raw-spacing` preserve blank lines/comment gaps
-- `--dump` dump marshalled object tree
-- `--stats` print throughput stats
-- `--skip-source-gen` skip writing `.py` (use with `--asm/--dump`)
-- `--skip-path` flatten output paths (write next to input)
-- `--out` print source to stdout instead of files
-- `--marshal` treat input as raw marshalled data (no .pyc header, auto-scan versions)
-- `--marshal-scan` fast scan marshal blobs and print version candidates
-- `--py-version <x.y>` bytecode version hint (use with `--marshal`)
-- `--basedir <dir>` override output root (default: alongside input)
-- `--file-ext <ext>` change emitted extension (default `py`)
-
-## Examples
-- Disassemble only (no source): `node depyo.js --skip-source-gen --asm file.pyc`
-- Keep raw + disassembly next to source: `node depyo.js --raw --asm path/to/file.pyc`
-- Flatten outputs (helpful for bulk zips): `node depyo.js --skip-path archive.zip`
+## Example
 
-## Testing
-- Smoke per version:
-  ```bash
-  node scripts/run-fixtures.js --root test/bytecode_3.14 --pattern py314_with_except_star --fail-fast
-  node scripts/run-fixtures.js --root test/bytecode_3.6 --pattern py36_fstrings --fail-fast
-  ```
-- Matrix (all versions, optional PyPy):
-  ```bash
-  node scripts/run-matrix.js                  # full sweep
-  node scripts/run-matrix.js --pattern py311_exception_groups --fail-fast
-  ```
-- Marshal fixtures (headerless marshal blobs):
-  ```bash
-  node scripts/run-marshal-fixtures.js
-  ```
-- Regenerate marshal fixtures:
-  ```bash
-  node scripts/generate-marshal-fixtures.js --clean
-  ```
-- Modern fixtures are generated via `test/generate_modern_tests.py` (Python 3.8+ on PATH).
+Input `greet.py`:
+
+```python
+async def greet(names: list[str], *, greeting: str = "Hello") -> None:
+    seen = set()
+    for name in names:
+        if name in seen:
+            continue
+        seen.add(name)
+        print(f"{greeting}, {name}!")
+```
+
+Compile (`python3.13 -c 'import py_compile; py_compile.compile("greet.py", "greet.pyc")'`) then:
+
+```bash
+$ npx depyo --out greet.pyc
+async def greet(names: list[str], *, greeting: str = "Hello") -> None:
+    seen = set()
+    for name in names:
+        if name in seen:
+            continue
+        seen.add(name)
+        print(f"{greeting}, {name}!")
+```
+
+Pattern matching round-trips too:
+
+```python
+match command.split():
+    case [action]:
+        run(action)
+    case [action, obj] if action in VERBS:
+        run(action, obj)
+    case _:
+        print("usage: ...")
+```
+
+## CLI options
+
+| Option                   | Effect                                                          |
+| ------------------------ | --------------------------------------------------------------- |
+| `--asm`                  | Emit `.pyasm` disassembly alongside source                      |
+| `--raw`                  | Copy raw `.pyc` next to output                                  |
+| `--raw-spacing`          | Preserve blank-line / comment gaps                              |
+| `--dump`                 | Dump the marshalled object tree                                 |
+| `--stats`                | Print throughput stats                                          |
+| `--skip-source-gen`      | Skip writing `.py` (useful with `--asm`/`--dump`)               |
+| `--skip-path`            | Flatten output paths (write next to input)                      |
+| `--out`                  | Print source to stdout instead of files                         |
+| `--marshal`              | Treat input as raw marshalled data (no `.pyc` header)           |
+| `--marshal-scan`         | Fast scan marshal blobs; print candidate versions               |
+| `--py-version <x.y>`     | Bytecode version hint (required for some headerless marshals)   |
+| `--basedir <dir>`        | Override output root (default: alongside input)                 |
+| `--file-ext <ext>`       | Change emitted extension (default `py`)                         |
+
+## Programmatic API
+
+```js
+const {PycReader} = require('depyo/lib/PycReader');
+const {PycDecompiler} = require('depyo/lib/PycDecompiler');
+
+const fs = require('fs');
+const buffer = fs.readFileSync('greet.pyc');
+const reader = new PycReader(buffer);
+const obj = reader.ReadObject();
+
+const decompiler = new PycDecompiler(obj);
+const ast = decompiler.decompile();
+console.log(ast.codeFragment().toString());
+```
 
 ## Support matrix
-- Python 1.0–3.14 opcode tables with expected fixtures.
-- Modern features: match/case, walrus, f-strings, exception groups, type params.
-- PyPy bytecode sets decompile; expected files are not yet part of CI.
-- Legacy CI smokes (1.x/2.7/3.0–3.6) are informational (`continue-on-error`); modern feature checks are blocking.
+
+- **Python 1.0–3.15** opcode tables and expected fixtures.
+- **Modern features:** match/case (guards, OR-patterns, bindings, wildcards), walrus, f-strings (nested, equals-sign debug), exception groups (`except*`), async comprehensions, type parameters, PEP 696 TypeVar defaults, PEP 750 t-strings.
+- **PyPy** bytecode decompiles; expected fixtures not yet part of CI.
+- **CI gates:** Modern feature checks are blocking; legacy 1.x / 2.7 / 3.0–3.6 smokes gate as well.
 
 ## Known limitations
-- **Inline comprehensions (Python 3.12+):** PEP 709 inlines list/dict/set comprehensions into parent code objects. Depyo currently reconstructs these as for-loops rather than comprehension expressions. Functions, classes, match/case, exception handling, and other constructs work correctly.
 
-## Contributing / DX tips
+- **Inline comprehensions (3.12+):** PEP 709 inlines list/dict/set comprehensions into the parent code object. Depyo currently reconstructs these as for-loops rather than comprehension expressions. Functions, classes, match/case, exception handling, and other constructs work correctly.
+- **Comments / blank lines:** Lost in compilation and not recoverable. `--raw-spacing` can hint at original gaps using line-number attributes.
+- **Source-level AST drift:** Some constructs are normalized by CPython before bytecode (e.g. `if not x: raise AssertionError` ↔ `assert x`). Depyo renders what the compiler produced.
+
+## Testing
+
+```bash
+# Smoke per version
+node scripts/run-fixtures.js --root test/bytecode_3.14 --pattern py314_with_except_star --fail-fast
+node scripts/run-fixtures.js --root test/bytecode_3.6  --pattern py36_fstrings          --fail-fast
+
+# Full matrix
+node scripts/run-matrix.js
+node scripts/run-matrix.js --pattern py311_exception_groups --fail-fast
+
+# Marshal-blob fixtures (headerless)
+node scripts/run-marshal-fixtures.js
+
+# Regenerate snapshot fixtures (destructive)
+node scripts/generate-marshal-fixtures.js --clean
+
+# Tier-1 oracle: parseability of every decompiled fixture
+node scripts/check-parseable.js
+
+# Tier-2 oracle: AST equivalence between source .py and decompiled .py
+node scripts/check-ast-equivalence.js
+
+# Sentinel leak gate (CI-critical)
+node scripts/check-no-sentinels.js
+```
+
+Modern fixtures are generated via `test/generate_modern_tests.py` (Python 3.8+ on PATH).
+
+## Contributing
+
 - Use `node scripts/run-fixtures.js --pattern <piece>` for fast repros.
 - For full coverage, `node scripts/run-matrix.js --fail-fast` (optionally add `--pattern`).
-- Enable `--raw-spacing` to inspect potential comment/blank-line gaps.
+- `--raw-spacing` helps inspect potential comment/blank-line gaps.
 - `--stats` helps when profiling throughput.
 
-Comments and docs are in English; output mirrors the target Python version syntax.
+Issues, repro `.pyc` files, and PRs welcome at https://github.com/skuznetsov/depyo.js/issues.
 
-## Comparison snapshot (at a glance)
-
-| Project            | Supported versions          | Modern features (match, walrus, f-strings, exc groups) | Delivery     | Expected fixtures | Notes                                     |
-| ------------------ | --------------------------- | ------------------------------------------------------ | ------------ | ----------------- | ----------------------------------------- |
-| depyo              | 1.0–3.14 (PyPy decompiles)  | Yes                                                    | npm/npx, CLI | Yes (1.0–3.14)    | Node.js CLI, asm/raw-spacing options      |
-| uncompyle6/decompyle3 | 2.x–3.12+ (lag on 3.13/3.14) | Partial (depends on branch)                           | pip          | Partial           | Python-based, slower adoption of new ops  |
-| pycdc (C++)        | Mostly 2.x–3.x (limited new) | Partial                                                | source build | No                | Fast, but modern coverage limited         |
+Comments and docs are in English; output mirrors the target Python version syntax.
 
-## Quick benchmark (informal)
-- Machine: local Node 25, single-thread.
-- Case: `py314_exception_groups.pyc` decompiled 50× in-process: ~5.3 ms total (≈0.1 ms per decompile).  
-Use `node depyo.js --stats <file.pyc>` for your environment.
+## License
 
-## Promotion ideas (OSS)
-- Announce on HN/Reddit (Show HN / r/Python) with npm/npx one-liners.
-- Add to awesome lists (`awesome-python`, `awesome-reverse-engineering`).
-- Provide asciinema/GIF of `npx depyo file.pyc` + `--asm`.
-- Encourage contributions via Issues/Discussions and `help wanted` labels.
+MIT — see [LICENSE](LICENSE).

package/lib/PycDecompiler.js

@@ -933,6 +933,23 @@ class PycDecompiler {
                         break;  // This WITH block hasn't reached its end yet
                     }
 
+                    // Close any blocks ABOVE this WITH whose end is also reached.
+                    // 3.14 with-bodies that contain an if/else commonly have the
+                    // else's end coincide with the with's end (both target the
+                    // post-with cleanup offset). If we close the WITH while an
+                    // Else is still open above it, the else body gets reparented
+                    // to the WITH's parent — producing a stray `else:` dedented
+                    // out of the with-block in the rendered source.
+                    while (this.blocks.length - 1 > withIdx) {
+                        const above = this.blocks.top();
+                        if (above.end <= 0 || this.code.Current.Offset < above.end) {
+                            break;
+                        }
+                        this.blocks.pop();
+                        const newTop = this.blocks.top();
+                        if (newTop) newTop.append(above);
+                    }
+
                     // Close this WITH block
                     this.blocks.splice(withIdx, 1);
                     const parentBlock = this.blocks[withIdx - 1] || this.blocks.top();
@@ -1914,9 +1931,16 @@ class PycDecompiler {
     // trailing compiler-generated reraise/cleanup nodes (bare `raise`,
     // `e = None; del e`, empty `try: pass`). Runs once on the whole tree.
     cleanupExcMatchArtifacts(root) {
-        // CHECK_EXC_MATCH only exists in Py3.11+; earlier versions never produce
-        // the EXC_MATCH compare op or the __exception__ sentinel, so skip.
-        if (this.object.Reader.versionCompare(3, 11) < 0) return;
+        // Pre-3.11 except-as handlers still need two cleanups: strip the
+        // `X = None; del X` pair CPython emits after every `except ... as X:`
+        // body (PEP 3134), and unwrap the synthetic `try: body / finally: pass`
+        // that wraps the handler body (CPython lowers `except ... as X:` to
+        // `try: body; finally: X = None; del X`, and the finally body ends up
+        // emptied as the X=None/del X move out to the handler tail).
+        if (this.object.Reader.versionCompare(3, 11) < 0) {
+            this.cleanupPre311ExceptAsArtifacts(root);
+            return;
+        }
 
         const EXC_MATCH = AST.ASTCompare.CompareOp.Exception;
 
@@ -2354,6 +2378,139 @@ class PycDecompiler {
         visit(root);
     }
 
+    // Pre-3.11 `except Foo as X:` expands to `try: body / finally: X = None;
+    // del X`. The decompiler hoists the cleanup out to the handler tail,
+    // leaving `try: body / finally: pass / X = None / del X`. Strip the pair
+    // and unwrap the synthetic try/finally so the handler renders as `body`.
+    cleanupPre311ExceptAsArtifacts(root) {
+        const isNoneDelPair = (a, b) =>
+            a instanceof AST.ASTStore &&
+            a.src instanceof AST.ASTNone &&
+            a.dest instanceof AST.ASTName &&
+            b instanceof AST.ASTDelete &&
+            b.value instanceof AST.ASTName &&
+            a.dest.name === b.value.name;
+
+        const isFinallyTrivial = (n) =>
+            n instanceof AST.ASTBlock &&
+            n.blockType === AST.ASTBlock.BlockType.Finally &&
+            (n.nodes.length === 0 ||
+             (n.nodes.length === 1 &&
+              n.nodes[0] instanceof AST.ASTKeyword &&
+              n.nodes[0].key === AST.ASTKeyword.Word.Pass));
+
+        // A CPython `except Foo as X:` body wraps user code in a synthetic
+        // `try: body / finally: X=None; del X`. After the Pass 3.5 strip the
+        // finally becomes empty / pass-only, leaving an ASTContainerBlock
+        // whose children are [Try(body), Finally(pass)]. Collapse that back
+        // to just the try-body so the handler renders as `body`.
+        const unwrapTryFinallyPassContainer = (nodes) => {
+            for (let i = nodes.length - 1; i >= 0; i--) {
+                const cont = nodes[i];
+                if (!(cont instanceof AST.ASTContainerBlock)) continue;
+                const children = cont.nodes;
+                if (!children || children.length !== 2) continue;
+                const tryBlk = children[0];
+                const finBlk = children[1];
+                if (!(tryBlk instanceof AST.ASTBlock) ||
+                    tryBlk.blockType !== AST.ASTBlock.BlockType.Try) continue;
+                if (!isFinallyTrivial(finBlk)) continue;
+                if (tryBlk.nodes.length === 0) continue;
+                // Keep real user try/except nested inside — unwrapping
+                // would change semantics when the try body itself carries
+                // handlers that could fire.
+                const hasNestedHandler = tryBlk.nodes.some(n =>
+                    n instanceof AST.ASTCondBlock &&
+                    (n.blockType === AST.ASTBlock.BlockType.Except ||
+                     n.blockType === AST.ASTBlock.BlockType.Finally));
+                if (hasNestedHandler) continue;
+                nodes.splice(i, 1, ...tryBlk.nodes);
+            }
+        };
+
+        const stripNoneDelPairs = (nodes) => {
+            for (let i = nodes.length - 2; i >= 0; i--) {
+                if (isNoneDelPair(nodes[i], nodes[i + 1])) {
+                    nodes.splice(i, 2);
+                }
+            }
+        };
+
+        // CPython 3.6+ `except Foo as X:` lowers to a try/finally cleanup
+        // wrapper around the handler body. The reconstruction sometimes
+        // emits the handler ASTCondBlock twice when the inner cleanup's
+        // END_FINALLY is misread as a second handler match. Collapse
+        // consecutive identical Except blocks (same rendered condition +
+        // body) since real Python source can't legally have them.
+        const dedupeConsecutiveExcepts = (nodes) => {
+            const renderedKey = (n) => {
+                try {
+                    const cf = n.codeFragment?.();
+                    return typeof cf === 'string' ? cf : (cf?.toString?.() || null);
+                } catch (e) {
+                    return null;
+                }
+            };
+            const isExcept = (n) => (n instanceof AST.ASTCondBlock)
+                && n.blockType === AST.ASTBlock.BlockType.Except;
+            // Walk runs of contiguous Except siblings and drop duplicates
+            // (handles both adjacent and non-adjacent duplicates within
+            // the same handler chain — e.g. `except A / except: / except A`).
+            let i = 0;
+            while (i < nodes.length) {
+                if (!isExcept(nodes[i])) { i++; continue; }
+                let j = i;
+                while (j < nodes.length && isExcept(nodes[j])) j++;
+                const seen = new Map();
+                for (let k = i; k < j; k++) {
+                    const key = renderedKey(nodes[k]);
+                    if (key && seen.has(key)) {
+                        nodes.splice(k, 1);
+                        j--;
+                        k--;
+                    } else if (key) {
+                        seen.set(key, true);
+                    }
+                }
+                i = j;
+            }
+        };
+
+        const visited = new WeakSet();
+        const visit = (n) => {
+            if (!n || visited.has(n)) return;
+            visited.add(n);
+            let nodes = null;
+            let parentType = null;
+            if (n instanceof AST.ASTNodeList) {
+                nodes = n.list;
+            } else if (n instanceof AST.ASTBlock) {
+                nodes = n.nodes;
+                parentType = n.blockType;
+            } else if (n instanceof AST.ASTStore && n.src instanceof AST.ASTFunction) {
+                const body = n.src.code?.object?.SourceCode;
+                if (body) visit(body);
+                return;
+            }
+            if (nodes) {
+                for (const c of nodes) visit(c);
+                stripNoneDelPairs(nodes);
+                // The try/finally:pass wrapper is CPython's synthetic scaffold
+                // for `except Foo as X:` — only unwrap inside Except bodies,
+                // otherwise real user-written `try: body / finally: pass`
+                // constructs at top-level/function body get collapsed too.
+                if (parentType === AST.ASTBlock.BlockType.Except) {
+                    unwrapTryFinallyPassContainer(nodes);
+                }
+                // Dedupe at every level (Container, Try, NodeList) since the
+                // duplicate Except siblings can land in any of these depending
+                // on how SETUP_FINALLY/END_FINALLY interleave.
+                dedupeConsecutiveExcepts(nodes);
+            }
+        };
+        visit(root);
+    }
+
     // An Except block can get reconstructed inside a non-Try block's body
     // (most often a For/While/If inside the protected try-body) when the
     // handler's offset range overlaps a nested loop. Python requires the

package/lib/PycReader.js

@@ -38,13 +38,14 @@ const TypeSmallTuple = ')';
 const TypeShortAscii = 'z';
 const TypeShortAsciiInterned = 'Z';
 const TypeObjectReference = 'r';
+const TypeSlice = ':'; // CPython 3.14+: marshal'd slice constant (start, stop, step)
 const KnownTypes = new Set([
     TypeNull, TypeNone, TypeFalse, TypeTrue, TypeStopiter, TypeEllipsis,
     TypeInt, TypeInt64, TypeFloat, TypeBinaryFloat, TypeComplex, TypeBinaryComplex,
     TypeLong, TypeString, TypeInterned, TypeStringRef, TypeTuple, TypeList,
     TypeDict, TypeCode, TypeCode2, TypeUnicode, TypeUnknown, TypeSet, TypeFrozenset,
     TypeAscii, TypeAsciiInterned, TypeSmallTuple, TypeShortAscii, TypeShortAsciiInterned,
-    TypeObjectReference
+    TypeObjectReference, TypeSlice
 ]);
 
 const MagicToVersion = {
@@ -590,6 +591,14 @@ class PycReader
                     obj.ClassName = "Py_FrozenSet";
                     obj.Value = frozenSet;
                     break;
+                case TypeSlice: {
+                    const sliceStart = this.ReadObject();
+                    const sliceStop = this.ReadObject();
+                    const sliceStep = this.ReadObject();
+                    obj.ClassName = "Py_Slice";
+                    obj.Value = { start: sliceStart, stop: sliceStop, step: sliceStep };
+                    break;
+                }
                 case TypeCode:
                 case TypeCode2:
                     let codeObj = this.ReadCodeObject();

package/lib/PythonObject.js

@@ -194,7 +194,13 @@ class PythonObject {
 
             case "Py_Complex":
                 return `${this.Value[0]}+${this.Value[1]}j`;
-    
+
+            case "Py_Slice": {
+                const part = (v) => v instanceof PythonObject ? v.toReprString() : String(v);
+                const { start, stop, step } = this.Value || {};
+                return `slice(${part(start)}, ${part(stop)}, ${part(step)})`;
+            }
+
             default:
                 return ["Py_String"].includes(this.ClassName) ? this.Value.toString("ascii") : null;
         }

package/lib/ast/ast_node.js

@@ -212,9 +212,14 @@ class ASTNodeList extends ASTNode {
         if (this.emptyBlock()) {
             result.add("pass");
         } else {
+            // Defensive: a handler may have appended an undefined slot (e.g.
+            // a stack-pop that returned undefined on a malformed pyc).
+            // Without this, the sibling-link loop crashes on `undefined.prevSibling`
+            // and aborts rendering of the whole code object.
+            const list = this.list.filter(n => n);
             let prevNode = null;
 
-            for (let node of this.list) {
+            for (let node of list) {
                 if (prevNode) {
                     prevNode.nextSibling = node;
                 }
@@ -223,7 +228,7 @@ class ASTNodeList extends ASTNode {
             }
             prevNode = null;
 
-            for (let node of this.list) {
+            for (let node of list) {
                 if (node.skip) {
                     continue;
                 }
@@ -2602,6 +2607,17 @@ class ASTBlock extends ASTNode {
     }
 }
 
+// Predicate: can this node legally appear as one branch of a ternary `x if c else y`?
+// Block-shaped nodes render multi-line and an ASTKeyword (pass/break/continue) is a
+// statement, not an expression — appending " if c else y" to either is invalid Python.
+function isTernaryExprNode(node) {
+    if (node == null) return false;
+    if (node instanceof ASTBlock) return false;
+    if (node instanceof ASTKeyword) return false;
+    if (node instanceof ASTReturn) return false;
+    return true;
+}
+
 class ASTCondBlock extends ASTBlock {
     static InitCondition = {
         Uninited: 0,
@@ -2636,7 +2652,23 @@ class ASTCondBlock extends ASTBlock {
     
     codeFragment() {
         let result = new PycResult("", true);
+        // Cycle guard: if a control-flow handler accidentally nests a block
+        // inside its own descendants, the recursive render would blow the JS
+        // stack and abort the enclosing code object. Detect re-entry on the
+        // same instance, emit a sentinel, and let the rest of the file render.
+        if (this.__rendering) {
+            result.add("###CYCLE###");
+            return result;
+        }
+        this.__rendering = true;
+        try {
+            return this._codeFragmentImpl(result);
+        } finally {
+            this.__rendering = false;
+        }
+    }
 
+    _codeFragmentImpl(result) {
         // This is the assert case
         if (this.blockType == ASTBlock.BlockType.If && this.negative && this.condition && this.nodes.length == 1 && this.nodes[0] instanceof ASTRaise) {
             result.lastLineAppend("assert ", false);
@@ -2651,9 +2683,11 @@ class ASTCondBlock extends ASTBlock {
             this.prevSibling instanceof ASTStore &&
             this.blockType == ASTBlock.BlockType.If &&
             this.nodes.length == 1 &&
+            isTernaryExprNode(this.nodes[0]) &&
             this.nextSibling instanceof ASTCondBlock &&
             this.nextSibling?.type == ASTBlock.BlockType.Else &&
             this.nextSibling?.nodes.length == 1 &&
+            isTernaryExprNode(this.nextSibling.nodes[0]) &&
             this.condition.line >= 0 &&
             this.condition.line == this.nodes[0].line &&
             this.condition.line == this.nextSibling?.nodes[0].line
@@ -2670,7 +2704,10 @@ class ASTCondBlock extends ASTBlock {
             this.prevSibling == null &&
             this.blockType == ASTBlock.BlockType.If &&
             this.nodes.length == 1 &&
+            isTernaryExprNode(this.nodes[0]) &&
             this.nextSibling instanceof ASTReturn &&
+            this.nextSibling.value &&
+            isTernaryExprNode(this.nextSibling.value) &&
             this.condition.line == this.nodes[0].line &&
             this.condition.line == this.nextSibling?.value.line
         ) {

package/lib/bytecode/python_3_14.js

@@ -7,7 +7,7 @@ const opcodes = [
     [0, new OpCode(OpCodes.CACHE, "CACHE")],
     [1, new OpCode(OpCodes.BINARY_SLICE, "BINARY_SLICE")],
     [2, new OpCode(OpCodes.BUILD_TEMPLATE, "BUILD_TEMPLATE")],
-    [4, new OpCode(OpCodes.CALL_FUNCTION_EX, "CALL_FUNCTION_EX")],
+    [4, new OpCode(OpCodes.CALL_FUNCTION_EX_A, "CALL_FUNCTION_EX", {HasArgument: true})],
     [5, new OpCode(OpCodes.CHECK_EG_MATCH, "CHECK_EG_MATCH")],
     [6, new OpCode(OpCodes.CHECK_EXC_MATCH, "CHECK_EXC_MATCH")],
     [7, new OpCode(OpCodes.CLEANUP_THROW, "CLEANUP_THROW")],

package/lib/handlers/binary_ops.js

@@ -2,6 +2,15 @@ const AST = require('../ast/ast_node');
 
 function handleBinaryOpA()
 {
+    // Python 3.14 fused BINARY_SUBSCR into BINARY_OP arg=26 (NB_SUBSCR).
+    if (this.code.Current.Argument === 26) {
+        let subscr = this.dataStack.pop();
+        let src = this.dataStack.pop();
+        let node = new AST.ASTSubscr(src, subscr);
+        node.line = this.code.Current.LineNo;
+        this.dataStack.push(node);
+        return;
+    }
     let rVal = this.dataStack.pop();
     let lVal = this.dataStack.pop();
     let op = AST.ASTBinary.from_binary_op(this.code.Current.Argument);

package/lib/handlers/control_flow_jumps.js

@@ -1177,12 +1177,37 @@ function handleJumpAbsoluteA() {
                 this.blocks.push(next);
                 prev = null;
             } else if (prev.blockType == AST.ASTBlock.BlockType.Except) {
-                let top = this.blocks.top();
-                let next = new AST.ASTCondBlock(AST.ASTBlock.BlockType.Except, top.start, top.end, null, false);
-                next.init();
+                // After closing one handler we speculatively open a fresh
+                // Except slot in case another handler follows. But if the
+                // chain has no more user-written handlers — only CPython's
+                // synthetic END_FINALLY re-raise terminator before our
+                // jump target — pushing an empty Except here produces a
+                // phantom `except: pass` in the output.
+                let chainTerminated = false;
+                const target = this.code.Current.JumpTarget;
+                const cursorStart = this.code.Next?.Offset;
+                if (target != null && cursorStart != null && cursorStart < target) {
+                    let cursor = cursorStart;
+                    for (let k = 0; k < 32 && cursor < target; k++) {
+                        const instr = this.code.PeekInstructionAtOffset(cursor);
+                        if (!instr) break;
+                        if (instr.OpCodeID === this.OpCodes.END_FINALLY) {
+                            chainTerminated = true;
+                            break;
+                        }
+                        cursor = instr.Offset + (instr.Size || 1);
+                    }
+                }
+                if (chainTerminated) {
+                    prev = null;
+                } else {
+                    let top = this.blocks.top();
+                    let next = new AST.ASTCondBlock(AST.ASTBlock.BlockType.Except, top.start, top.end, null, false);
+                    next.init();
 
-                this.blocks.push(next);
-                prev = null;
+                    this.blocks.push(next);
+                    prev = null;
+                }
             } else if (prev.blockType == AST.ASTBlock.BlockType.Else) {
                 /* Special case */
                 if (this.blocks.top().blockType != AST.ASTBlock.BlockType.Main) {

package/lib/handlers/load_store_names.js

@@ -182,6 +182,22 @@ function handleLoadGlobalA() {
     this.dataStack.push(node);
 }
 
+function handleLoadFromDictOrGlobalsA() {
+    // Python 3.12+: pops the class-body locals dict pushed by LOAD_LOCALS,
+    // looks up co_names[A] there, falling back to globals. For source
+    // reconstruction we render it as a bare name reference.
+    if (this.dataStack.top() instanceof AST.ASTLocals) {
+        this.dataStack.pop();
+    }
+    const varName = this.code.Current.Name || "";
+    if (!varName.length) {
+        return;
+    }
+    let node = new AST.ASTName(varName);
+    node.line = this.code.Current.LineNo;
+    this.dataStack.push(node);
+}
+
 function handleLoadFromDictOrDerefA() {
     // Python 3.12+: LOAD_FROM_DICT_OR_DEREF consumes the locals dict from TOS
     // (pushed by the preceding LOAD_LOCALS) and resolves the name against it,
@@ -253,9 +269,15 @@ function handleLoadSpecialA() {
     }
 
     // For __exit__ (oparg 1): save the context manager expression for with-block
-    // This is called BEFORE __enter__ in 3.14 bytecode pattern
+    // This is called BEFORE __enter__ in 3.14 bytecode pattern.
+    // The 3.14 with-prologue uses LOAD_FAST(ctx); COPY 1; LOAD_SPECIAL 1, which
+    // looks like the LOAD+COPY 1 match-subject idiom — clear the candidate so
+    // a later COMPARE_OP inside the with-body doesn't get wrapped in a
+    // synthetic `match ctx:` rooted on the context manager.
     if (oparg === 1) {
         this._py314WithContextMgr = obj;
+        this.potentialMatchSubject = null;
+        this.matchCandidateStart = -1;
     }
 
     // For __enter__ (oparg 0): create with-block using saved context manager
@@ -478,6 +500,28 @@ function processStore(nameOverride) {
         }
     }
 
+    // `case _ as name:` final clause: no preceding pattern ops, no LOAD
+    // before the STORE, and we're inside a match. CPython emits a bare STORE
+    // to bind the subject still living on the stack.
+    if (this.currentMatch && !this.currentCase && !this.inMatchPattern &&
+        (this.patternOps?.length || 0) === 0) {
+        const prevId = this.code.Prev?.OpCodeID;
+        const isAfterReturn = prevId == this.OpCodes.RETURN_VALUE ||
+                              prevId == this.OpCodes.RETURN_VALUE_A ||
+                              prevId == this.OpCodes.RETURN_CONST_A;
+        if (isAfterReturn) {
+            const wildcard = new AST.ASTPattern(AST.ASTPattern.PatternType.Wildcard, '_');
+            const asPattern = new AST.ASTPattern(AST.ASTPattern.PatternType.As, {
+                pattern: wildcard,
+                name: currentName
+            });
+            this.currentCase = new AST.ASTCase(asPattern, null, null);
+            this.currentCase.line = this.code.Current.LineNo;
+            this.caseBodyStartIndex = this.curBlock?.nodes?.length || 0;
+            return;
+        }
+    }
+
     if (global.g_cliArgs?.debug && currentName && (currentName === 'b' || currentName === 'i')) {
         console.log(`[processStore] varName=${currentName}, curBlock=${this.curBlock.type_str}, inited=${this.curBlock.inited}, unpack=${this.unpack}`);
         console.log(`  Block stack: ${this.blocks.map((b,i) => `[${i}]${b.type_str}(inited=${b.inited})`).join(' → ')}`);
@@ -832,6 +876,7 @@ module.exports = {
     handleLoadZeroSuperAttrA,
     handleLoadZeroSuperMethodA,
     handleLoadFromDictOrDerefA,
+    handleLoadFromDictOrGlobalsA,
     handleStoreAttrA,
     handleStoreDerefA,
     handleStoreFastA,

package/lib/handlers/misc_other.js

@@ -241,11 +241,25 @@ function reconstructPattern(patternOps) {
         ));
     }
 
-    // Literal OR pattern: multiple COMPARE_OP checks in a row
+    // Literal OR pattern: multiple COMPARE_OP checks in a row.
+    // Pattern compares share the same `left` (the matched subject). Anything
+    // with a different left is a guard expression that bled into patternOps.
     const allCompareOps = ops.filter(op => op.type === 'COMPARE');
-    if (!hasMatchSeq && allCompareOps.length > 1) {
+    const sameLeft = (a, b) => {
+        if (a === b) return true;
+        if (!a || !b) return false;
+        const af = a.codeFragment?.()?.toString?.();
+        const bf = b.codeFragment?.()?.toString?.();
+        return !!af && af === bf;
+    };
+    let patternCompareOps = allCompareOps;
+    if (allCompareOps.length > 1) {
+        const subjectLeft = allCompareOps[0].left;
+        patternCompareOps = allCompareOps.filter(op => sameLeft(op.left, subjectLeft));
+    }
+    if (!hasMatchSeq && patternCompareOps.length > 1) {
         const orPatterns = [];
-        for (const cmp of allCompareOps) {
+        for (const cmp of patternCompareOps) {
             markConsumed(cmp);
             if (cmp.right instanceof AST.ASTObject) {
                 orPatterns.push(new AST.ASTPattern(AST.ASTPattern.PatternType.Literal, cmp.right));
@@ -366,6 +380,21 @@ function hasUpcomingMatchCase() {
         return true;
     }
 
+    // `case _ as name:` final clause — CPython emits a bare STORE for the
+    // binding right after the previous case's RETURN. No LOAD precedes it
+    // (the stored value is the matched subject preserved on the stack).
+    if (this.currentMatch && this.matchSubject &&
+        (nextOpCodeId == this.OpCodes.STORE_FAST_A ||
+         nextOpCodeId == this.OpCodes.STORE_NAME_A)) {
+        const prevId = this.code.Current.OpCodeID;
+        const isAfterReturn = prevId == this.OpCodes.RETURN_VALUE ||
+                              prevId == this.OpCodes.RETURN_VALUE_A ||
+                              prevId == this.OpCodes.RETURN_CONST_A;
+        if (isAfterReturn) {
+            return true;
+        }
+    }
+
     // NOP followed by code (no COMPARE_OP) = default case (case _:)
     // This pattern appears in 3.10/3.11 after the last literal case
     if (nextOpCodeId == this.OpCodes.NOP && this.currentMatch) {
@@ -1330,6 +1359,12 @@ function handleInstrumentedLineA() {
     }
 }
 
+// CPython 3.13+: POP_ITER replaces the post-loop POP_TOP that discards an
+// exhausted iterator. Semantically identical to POP_TOP for our purposes.
+function handlePopIter() {
+    return handlePopTop.call(this);
+}
+
 module.exports = {
     beginMatchCaseFromPattern,
     flushCurrentCaseBody,
@@ -1338,6 +1373,7 @@ module.exports = {
     handleFormatSimple,
     handleFormatWithSpec,
     handlePopTop,
+    handlePopIter,
     handlePrintExpr,
     handlePrintItem,
     handlePrintItemTo,

package/lib/handlers/stack_ops.js

@@ -28,7 +28,8 @@ function handleDupTop() {
 
             // Look ahead to confirm match pattern immediately
             if (!this.currentMatch && this.lookAheadForMatchPattern()) {
-                this.currentMatch = new AST.ASTMatch(this.potentialMatchSubject);
+                this.matchSubject = this.potentialMatchSubject;
+                this.currentMatch = new AST.ASTMatch(this.matchSubject);
                 this.currentMatch.line = this.code.Current.LineNo;
                 this.matchParentBlock = this.curBlock;
                 this.inMatchPattern = true;  // Start tracking pattern operations
@@ -46,7 +47,8 @@ function handleDupTop() {
         if (!this.currentMatch && this.potentialMatchSubject &&
             this.object.Reader.versionCompare(3, 10) >= 0) {
             // First time - create match (fallback if look-ahead didn't work)
-            this.currentMatch = new AST.ASTMatch(this.potentialMatchSubject);
+            this.matchSubject = this.potentialMatchSubject;
+            this.currentMatch = new AST.ASTMatch(this.matchSubject);
             this.currentMatch.line = this.code.Current.LineNo;
             this.matchParentBlock = this.curBlock;
             this.inMatchPattern = true;

package/lib/handlers/unary_ops.js

@@ -69,6 +69,13 @@ function handleUnaryPositive() {
 
 function handleToBool() {
     // Python 3.13+ TO_BOOL: normalize truthiness. Preserve stack value.
+    // The preceding LOAD+COPY 1 here is the boolean-shortcut idiom for
+    // `if not X` / `while X`, not a match-case subject. Clear the
+    // potential-match candidate so a later COMPARE_OP (e.g. `e.code == 409`
+    // inside an except handler) doesn't get retroactively wrapped in a
+    // synthetic `match X:` rooted on this stale subject.
+    this.potentialMatchSubject = null;
+    this.matchCandidateStart = -1;
     const arg = this.dataStack.pop();
     this.dataStack.push(arg);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "depyo",
-  "version": "1.1.0",
+  "version": "1.2.1",
   "description": "Python bytecode decompiler (Python 1.0–3.15) implemented in Node.js",
   "bin": {
     "depyo": "./depyo.js"