opast 0.1.0__tar.gz

opast-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 YZJYBT
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

opast-0.1.0/PKG-INFO

@@ -0,0 +1,167 @@
+Metadata-Version: 2.4
+Name: opast
+Version: 0.1.0
+Summary: Conservative AST-level Python source optimizer: provably-semantics-preserving passes (folding, propagation, inlining, loop rewrites) with dynamic-code fallback, plus an opt-in numba JIT path.
+Author-email: YZJYBT <yzj0xfff2@gmail.com>
+License-Expression: MIT
+Project-URL: Repository, https://github.com/YZJYBT/pyOpAst
+Project-URL: Issues, https://github.com/YZJYBT/pyOpAst/issues
+Project-URL: Changelog, https://github.com/YZJYBT/pyOpAst/blob/main/CHANGELOG.md
+Keywords: optimizer,ast,performance,source-to-source,numba,jit
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Compilers
+Classifier: Topic :: Software Development :: Code Generators
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: jit
+Requires-Dist: numba>=0.61; extra == "jit"
+Dynamic: license-file
+
+# opast
+
+> **English** | [中文](README-ZH.md) (the Chinese document carries the exhaustive per-pass safety conditions; this one is the canonical overview)
+
+![CI](https://github.com/YZJYBT/pyOpAst/actions/workflows/ci.yml/badge.svg)
+
+**opast** ("OPtimizing AST") is a conservative AST-level source optimizer for Python. It rewrites your script into an equivalent but faster one and runs it on the very interpreter that invoked opast (plain CPython by default). Every transformation is backed by a static proof of semantic preservation; anything the optimizer cannot prove, it leaves alone.
+
+- PyPI / import package / CLI command: `opast` — GitHub repository: **pyOpAst**
+- Requires Python ≥ 3.10. Zero runtime dependencies; `numba` only for the opt-in `--jit` extra.
+
+```powershell
+pip install opast            # or from source: pip install -e .
+
+opast script.py a b c        # optimize, then run (same as python -m opast)
+opast --show --no-run script.py     # print the optimized source only
+opast --report script.py            # run + per-pass statistics on stderr
+opast -c "print(sum(i for i in range(10)))"   # inline code string, like python -c
+opast --disable inline,licm script.py         # skip passes by name
+```
+
+## Design
+
+Three principles drive every pass:
+
+1. **Prove, then rewrite.** Passes only fire on facts established by static analysis: per-function *proven-int* type inference (a greatest-fixpoint over all bindings), interval (value-range) analysis with widening, escape analysis for *fresh containers* (built locally, never leaked, never mutated), straight-line dominance scans for definite binding, and module-wide stability checks for names (bound exactly once, never `global`-declared, no dynamic constructs anywhere).
+2. **Dynamic code disables optimization, scope by scope.** Any appearance of `eval` / `exec` / `globals` / `locals` / `vars` / `compile` / `__import__` / frame-introspection attributes / `from m import *` taints the enclosing scope; tainted scopes (and everything nested inside) are skipped entirely. A tainted module top level disables the whole file. The check is name-based and deliberately over-conservative.
+3. **Zero runtime overhead.** The static passes emit ordinary Python source — no guards, no helper runtime. The only runtime machinery lives behind the opt-in `--jit` flag, and it degrades to plain Python on any failure.
+
+## Optimization passes
+
+The pipeline iterates to a fixpoint (default ≤ 8 rounds): de-dynamize → folding → constant propagation → algebraic → loop-fold → dead code → range-to-iter → LICM → CSE → unused → inline → loop-to-comp → comp-to-map → localize. Each pass feeds the next; collapsed constants cascade outward across iterations. See [README-ZH.md](README-ZH.md) for the full safety-condition spec of each pass.
+
+| Pass | What it does |
+| --- | --- |
+| `de-dynamize` | Expands *pointless* dynamic code into static equivalents: top-level `eval("<const expr>")` → the expression, `exec("<const stmts>")` → the statements, `globals()['x'] = v` → `x = v`, `getattr(o, 'a')` → `o.a`, statement-form `setattr`/`delattr` → attribute syntax. All-or-nothing: commits only if the whole module ends up free of dynamic constructs, otherwise rolls back — un-tainting the module unlocks every other pass. |
+| `constant-folding` | Folds constant arithmetic / strings / comparisons / boolean short-circuits / subscripts. Expressions that would raise at runtime are preserved; guardrails cap optimization-time work and literal sizes, with partial sub-expression folding allowed. |
+| `const-prop` | Substitutes constants for variables along four routes: single-binding names (whole scope), **cross-scope** module constants into later-defined functions, **span propagation** for multiply-bound names (from an assignment up to the first statement that could rebind), and **copy propagation** `y = x` between plain locals (function scopes only). |
+| `algebraic` | Identity cleanup (`x+0`, `x*1`, `-(-x)`, …) plus strength reduction — `E % 2**k → E & mask`, `E // 2**k → E >> k`, `E ** 2 → E * E` — and interval-analysis-backed `abs(E) → E` for provably non-negative `E`. Only on provably plain-`int` expressions; never duplicates or drops effects. |
+| `loop-fold` | **Closed-form loop evaluation**: a `for i in range(<const>)` loop whose body is pure int arithmetic (no calls) is simulated exactly at optimization time and replaced by its final constant assignments. Step and magnitude budgets; any simulated exception keeps the loop. A successful fold proves the loop cannot raise, so it is legal even inside `try`/`with`. |
+| `dead-code` | Unreachable statements after `return`/`raise`/`break`/`continue`, constant-condition `if`/`while` (with `else` semantics), `assert True`, useless constant expression statements, redundant `pass`. |
+| `range-to-iter` | `for i in range(len(x))` over a provably fresh *sequence* becomes `for v in x` (index dead) or `for i, v in enumerate(x)` (index live); per-iteration `BINARY_SUBSCR` lookups disappear. Only exact `x[i]` loads are replaced; the enumerate form keeps `x` and `i` bound, so leftovers stay correct. |
+| `licm` | Hoists provably pure-and-total loop-invariant int expressions (and `len()` of fresh containers) out of loop bodies and `while` tests into pre-loop temporaries, with dominance-checked definite binding. |
+| `cse` | Merges repeated provably pure int expressions (same criteria as LICM) within a statement block into a temporary; speculative evaluation is sound because the expressions cannot raise. |
+| `unused` | Removes unused imports, unused module-level functions (post-inlining helpers), and dead local stores (effectful right-hand sides are downgraded to bare expressions). Module-level variable assignments are deliberately kept — module globals are observable API. |
+| `inline` | Two shapes: expression-body functions (`def f(...): return <expr>`) inline at any call site with constant/name arguments; straight-line statement bodies (≤ 6 assignments + `return`) inline at statement positions with arbitrary positional arguments via ordered temporaries. Requires module-wide name stability; the leftover `def` is cleaned by `unused`. |
+| `loop-to-comp` | `x = []` + an adjacent append-accumulation loop (nested `for`/guard-`if` chains allowed) becomes a list comprehension (`set()`/`.add` → set comprehension): dedicated `LIST_APPEND`/`SET_ADD` bytecode instead of a per-iteration attribute lookup + method call. Rejected inside `try`/`with` (a mid-loop exception would expose the partially-built list). |
+| `comp-to-map` | `(f(x) for x in it)` → `map(f, it)`, with `filter` for guards, restricted to positions where the generator/`map` identity difference is unobservable and `f` is provably stable. |
+| `localize` | Per-iteration reads of stable globals/builtins inside loops become pre-loop locals (`LOAD_GLOBAL` → `LOAD_FAST`). Runs last so other passes claim names first. |
+
+LICM/CSE additionally support **`len()` caching for fresh containers** — sound only because escape analysis guarantees no reference ever leaves the function, so no call can mutate the container.
+
+## Importing modules through the optimizer (`--opt-imports`)
+
+```powershell
+opast --opt-imports script.py            # also optimize modules imported from the script's directory
+opast --opt-imports-under src script.py  # add extra roots (repeatable)
+```
+
+A `sys.meta_path` hook runs imported modules through the full pipeline before compilation. Optimized bytecode never touches `__pycache__` (a later plain `python` run must not pick it up); results go to a content-addressed private cache instead (`OPAST_NO_IMPORT_CACHE=1` bypasses). Semantics boundary: modules whose globals get monkeypatched from outside (e.g. `unittest.mock.patch`) silently lose the stability assumptions several passes rely on — do not enable this for such modules, which is why it is opt-in. `unused` is force-disabled for imported modules (their "unused" definitions are the export surface). Python API: `from opast.importhook import install, uninstall`.
+
+## Benchmarks
+
+```powershell
+python -m opast.bench            # all built-in workloads, best-of-3, results verified identical
+python -m opast.bench --jit daily
+python -m opast.bench --list
+```
+
+16 built-in workloads, each executed twice per measurement (original vs optimized) in the same interpreter with GC disabled and a `RESULT` equality check. Note that CPython's own compiler already does trivial constant folding — opast's wins come from what CPython does *not* do: inlining, type-proven algebraic rewrites, loop rewrites, de-dynamization.
+
+## IPython / Jupyter
+
+```
+%load_ext opast
+
+%%opast --report --disable licm
+total = 0
+for i in range(50_000):
+    total += i * 2
+total
+```
+
+Options mirror the CLI; the cell executes in the user namespace, so assignments persist. Analyses are cell-scoped — see README-ZH for the notebook caveats.
+
+## Experimental: `--jit` (numba, off by default)
+
+```powershell
+pip install opast[jit]
+opast --jit hot_script.py
+```
+
+After the static fixpoint, a one-shot pass decorates hot numeric functions with a guarded `numba.njit` wrapper. Measured on CPython 3.14 (8M-iteration numeric kernel): 1.22 s pure Python vs 0.011 s steady-state (~110×), first call 0.79 s including compilation.
+
+- **Static hotness** (constant loop bounds ≥ 10 000 or nested loops) compiles at decoration time; a strict whitelist predicts numba compatibility (int/float arithmetic, `range` loops, `math.*`, no containers/strings/attributes).
+- **Loop outlining** extracts hot whitelisted loops out of mixed functions and module top level into fresh compiled functions, with proven input/output sets.
+- **njit inter-calls**: candidate functions may call each other (fixpoint selection, call cycles dropped, compiled copies call raw dispatchers).
+- **Runtime lazy compilation** covers *variable* loop bounds (`for i in range(n)`): the wrapper observes plain-Python calls and compiles when a trigger fires — bound argument ≥ `OPAST_JIT_LAZY_BOUND` (default 10 000), a single call ≥ 0.1 s, or ≥ 10 calls totalling ≥ 0.3 s. The triggering call's Python result doubles as the verification expectation, and `numba` itself is imported only on the first compilation attempt — a script whose lazy candidates never get hot pays nothing.
+- **First-call verification**: whitelisted functions are pure, so the first call runs both versions and compares results; a divergence (in practice: int64 wraparound, which no static filter can rule out) triggers a permanent fallback to Python instead of silently wrong answers. `OPAST_JIT_NO_VERIFY=1` opts out.
+- **Layered degradation**: no numba / incompatible interpreter / `OPAST_DISABLE_JIT` → original function; any numba error at compile or call time → permanent Python fallback. `OPAST_JIT_DEBUG=1` explains every fallback and lazy trigger on stderr.
+
+⚠️ Opt-in semantic caveat: numba integers are fixed 64-bit — intermediate values beyond ±9.2e18 wrap silently. This is why `--jit` is not on by default and not part of the semantic-preservation contract; the verification above is a safety net, not a proof.
+
+## Python API
+
+```python
+from opast import optimize_source, optimize_file, run_path, run_source, PASS_NAMES
+
+result = optimize_file("script.py")
+print(result.source)             # optimized source (ast.unparse)
+print(result.report.summary())   # per-pass statistics
+run_path("script.py", argv=("--flag",))
+
+optimize_file("script.py", disable="inline,licm")   # every entry point accepts `disable`
+```
+
+## Tests
+
+```powershell
+python tests/verify_opast.py     # full acceptance suite: per-pass behavior assertions
+                                 # + original-vs-optimized output comparison
+```
+
+Case sources are generated into `tests/cases/` on demand (not tracked); the bench harness doubles as a correctness check.
+
+## Prior art
+
+- [pyastop](https://github.com/xiaonanln/pyastop) (2017–2018): an early AST-optimizer prototype built around whole-project analysis and comment hints. opast instead proves each rewrite safe per pass, with no user annotations.
+- [fatoptimizer](https://github.com/vstinner/fatoptimizer) (FAT Python, PEPs 509/510/511): runtime guards + function specialization, abandoned over guard overhead. opast's static passes have zero runtime overhead; runtime machinery exists only behind the opt-in `--jit`.
+- CPython's built-in AST/peephole optimizer folds constants only; opast's gains come from everything beyond that.
+
+## Known limitations
+
+- Optimized code is executed via `compile(optimized_ast, original_filename)`; traceback line numbers reuse original positions where possible but may drift slightly on rewritten lines. Inlining removes call frames from tracebacks (documented per pass).
+- All transformations require static proof; anything unprovable is left untouched. Documented edge observables (e.g. the partially-built-list window excluded via `try`/`with` checks) are listed per pass in [README-ZH.md](README-ZH.md).
+- Python ≥ 3.10.
+
+## License
+
+MIT

opast-0.1.0/README.md

@@ -0,0 +1,140 @@
+# opast
+
+> **English** | [中文](README-ZH.md) (the Chinese document carries the exhaustive per-pass safety conditions; this one is the canonical overview)
+
+![CI](https://github.com/YZJYBT/pyOpAst/actions/workflows/ci.yml/badge.svg)
+
+**opast** ("OPtimizing AST") is a conservative AST-level source optimizer for Python. It rewrites your script into an equivalent but faster one and runs it on the very interpreter that invoked opast (plain CPython by default). Every transformation is backed by a static proof of semantic preservation; anything the optimizer cannot prove, it leaves alone.
+
+- PyPI / import package / CLI command: `opast` — GitHub repository: **pyOpAst**
+- Requires Python ≥ 3.10. Zero runtime dependencies; `numba` only for the opt-in `--jit` extra.
+
+```powershell
+pip install opast            # or from source: pip install -e .
+
+opast script.py a b c        # optimize, then run (same as python -m opast)
+opast --show --no-run script.py     # print the optimized source only
+opast --report script.py            # run + per-pass statistics on stderr
+opast -c "print(sum(i for i in range(10)))"   # inline code string, like python -c
+opast --disable inline,licm script.py         # skip passes by name
+```
+
+## Design
+
+Three principles drive every pass:
+
+1. **Prove, then rewrite.** Passes only fire on facts established by static analysis: per-function *proven-int* type inference (a greatest-fixpoint over all bindings), interval (value-range) analysis with widening, escape analysis for *fresh containers* (built locally, never leaked, never mutated), straight-line dominance scans for definite binding, and module-wide stability checks for names (bound exactly once, never `global`-declared, no dynamic constructs anywhere).
+2. **Dynamic code disables optimization, scope by scope.** Any appearance of `eval` / `exec` / `globals` / `locals` / `vars` / `compile` / `__import__` / frame-introspection attributes / `from m import *` taints the enclosing scope; tainted scopes (and everything nested inside) are skipped entirely. A tainted module top level disables the whole file. The check is name-based and deliberately over-conservative.
+3. **Zero runtime overhead.** The static passes emit ordinary Python source — no guards, no helper runtime. The only runtime machinery lives behind the opt-in `--jit` flag, and it degrades to plain Python on any failure.
+
+## Optimization passes
+
+The pipeline iterates to a fixpoint (default ≤ 8 rounds): de-dynamize → folding → constant propagation → algebraic → loop-fold → dead code → range-to-iter → LICM → CSE → unused → inline → loop-to-comp → comp-to-map → localize. Each pass feeds the next; collapsed constants cascade outward across iterations. See [README-ZH.md](README-ZH.md) for the full safety-condition spec of each pass.
+
+| Pass | What it does |
+| --- | --- |
+| `de-dynamize` | Expands *pointless* dynamic code into static equivalents: top-level `eval("<const expr>")` → the expression, `exec("<const stmts>")` → the statements, `globals()['x'] = v` → `x = v`, `getattr(o, 'a')` → `o.a`, statement-form `setattr`/`delattr` → attribute syntax. All-or-nothing: commits only if the whole module ends up free of dynamic constructs, otherwise rolls back — un-tainting the module unlocks every other pass. |
+| `constant-folding` | Folds constant arithmetic / strings / comparisons / boolean short-circuits / subscripts. Expressions that would raise at runtime are preserved; guardrails cap optimization-time work and literal sizes, with partial sub-expression folding allowed. |
+| `const-prop` | Substitutes constants for variables along four routes: single-binding names (whole scope), **cross-scope** module constants into later-defined functions, **span propagation** for multiply-bound names (from an assignment up to the first statement that could rebind), and **copy propagation** `y = x` between plain locals (function scopes only). |
+| `algebraic` | Identity cleanup (`x+0`, `x*1`, `-(-x)`, …) plus strength reduction — `E % 2**k → E & mask`, `E // 2**k → E >> k`, `E ** 2 → E * E` — and interval-analysis-backed `abs(E) → E` for provably non-negative `E`. Only on provably plain-`int` expressions; never duplicates or drops effects. |
+| `loop-fold` | **Closed-form loop evaluation**: a `for i in range(<const>)` loop whose body is pure int arithmetic (no calls) is simulated exactly at optimization time and replaced by its final constant assignments. Step and magnitude budgets; any simulated exception keeps the loop. A successful fold proves the loop cannot raise, so it is legal even inside `try`/`with`. |
+| `dead-code` | Unreachable statements after `return`/`raise`/`break`/`continue`, constant-condition `if`/`while` (with `else` semantics), `assert True`, useless constant expression statements, redundant `pass`. |
+| `range-to-iter` | `for i in range(len(x))` over a provably fresh *sequence* becomes `for v in x` (index dead) or `for i, v in enumerate(x)` (index live); per-iteration `BINARY_SUBSCR` lookups disappear. Only exact `x[i]` loads are replaced; the enumerate form keeps `x` and `i` bound, so leftovers stay correct. |
+| `licm` | Hoists provably pure-and-total loop-invariant int expressions (and `len()` of fresh containers) out of loop bodies and `while` tests into pre-loop temporaries, with dominance-checked definite binding. |
+| `cse` | Merges repeated provably pure int expressions (same criteria as LICM) within a statement block into a temporary; speculative evaluation is sound because the expressions cannot raise. |
+| `unused` | Removes unused imports, unused module-level functions (post-inlining helpers), and dead local stores (effectful right-hand sides are downgraded to bare expressions). Module-level variable assignments are deliberately kept — module globals are observable API. |
+| `inline` | Two shapes: expression-body functions (`def f(...): return <expr>`) inline at any call site with constant/name arguments; straight-line statement bodies (≤ 6 assignments + `return`) inline at statement positions with arbitrary positional arguments via ordered temporaries. Requires module-wide name stability; the leftover `def` is cleaned by `unused`. |
+| `loop-to-comp` | `x = []` + an adjacent append-accumulation loop (nested `for`/guard-`if` chains allowed) becomes a list comprehension (`set()`/`.add` → set comprehension): dedicated `LIST_APPEND`/`SET_ADD` bytecode instead of a per-iteration attribute lookup + method call. Rejected inside `try`/`with` (a mid-loop exception would expose the partially-built list). |
+| `comp-to-map` | `(f(x) for x in it)` → `map(f, it)`, with `filter` for guards, restricted to positions where the generator/`map` identity difference is unobservable and `f` is provably stable. |
+| `localize` | Per-iteration reads of stable globals/builtins inside loops become pre-loop locals (`LOAD_GLOBAL` → `LOAD_FAST`). Runs last so other passes claim names first. |
+
+LICM/CSE additionally support **`len()` caching for fresh containers** — sound only because escape analysis guarantees no reference ever leaves the function, so no call can mutate the container.
+
+## Importing modules through the optimizer (`--opt-imports`)
+
+```powershell
+opast --opt-imports script.py            # also optimize modules imported from the script's directory
+opast --opt-imports-under src script.py  # add extra roots (repeatable)
+```
+
+A `sys.meta_path` hook runs imported modules through the full pipeline before compilation. Optimized bytecode never touches `__pycache__` (a later plain `python` run must not pick it up); results go to a content-addressed private cache instead (`OPAST_NO_IMPORT_CACHE=1` bypasses). Semantics boundary: modules whose globals get monkeypatched from outside (e.g. `unittest.mock.patch`) silently lose the stability assumptions several passes rely on — do not enable this for such modules, which is why it is opt-in. `unused` is force-disabled for imported modules (their "unused" definitions are the export surface). Python API: `from opast.importhook import install, uninstall`.
+
+## Benchmarks
+
+```powershell
+python -m opast.bench            # all built-in workloads, best-of-3, results verified identical
+python -m opast.bench --jit daily
+python -m opast.bench --list
+```
+
+16 built-in workloads, each executed twice per measurement (original vs optimized) in the same interpreter with GC disabled and a `RESULT` equality check. Note that CPython's own compiler already does trivial constant folding — opast's wins come from what CPython does *not* do: inlining, type-proven algebraic rewrites, loop rewrites, de-dynamization.
+
+## IPython / Jupyter
+
+```
+%load_ext opast
+
+%%opast --report --disable licm
+total = 0
+for i in range(50_000):
+    total += i * 2
+total
+```
+
+Options mirror the CLI; the cell executes in the user namespace, so assignments persist. Analyses are cell-scoped — see README-ZH for the notebook caveats.
+
+## Experimental: `--jit` (numba, off by default)
+
+```powershell
+pip install opast[jit]
+opast --jit hot_script.py
+```
+
+After the static fixpoint, a one-shot pass decorates hot numeric functions with a guarded `numba.njit` wrapper. Measured on CPython 3.14 (8M-iteration numeric kernel): 1.22 s pure Python vs 0.011 s steady-state (~110×), first call 0.79 s including compilation.
+
+- **Static hotness** (constant loop bounds ≥ 10 000 or nested loops) compiles at decoration time; a strict whitelist predicts numba compatibility (int/float arithmetic, `range` loops, `math.*`, no containers/strings/attributes).
+- **Loop outlining** extracts hot whitelisted loops out of mixed functions and module top level into fresh compiled functions, with proven input/output sets.
+- **njit inter-calls**: candidate functions may call each other (fixpoint selection, call cycles dropped, compiled copies call raw dispatchers).
+- **Runtime lazy compilation** covers *variable* loop bounds (`for i in range(n)`): the wrapper observes plain-Python calls and compiles when a trigger fires — bound argument ≥ `OPAST_JIT_LAZY_BOUND` (default 10 000), a single call ≥ 0.1 s, or ≥ 10 calls totalling ≥ 0.3 s. The triggering call's Python result doubles as the verification expectation, and `numba` itself is imported only on the first compilation attempt — a script whose lazy candidates never get hot pays nothing.
+- **First-call verification**: whitelisted functions are pure, so the first call runs both versions and compares results; a divergence (in practice: int64 wraparound, which no static filter can rule out) triggers a permanent fallback to Python instead of silently wrong answers. `OPAST_JIT_NO_VERIFY=1` opts out.
+- **Layered degradation**: no numba / incompatible interpreter / `OPAST_DISABLE_JIT` → original function; any numba error at compile or call time → permanent Python fallback. `OPAST_JIT_DEBUG=1` explains every fallback and lazy trigger on stderr.
+
+⚠️ Opt-in semantic caveat: numba integers are fixed 64-bit — intermediate values beyond ±9.2e18 wrap silently. This is why `--jit` is not on by default and not part of the semantic-preservation contract; the verification above is a safety net, not a proof.
+
+## Python API
+
+```python
+from opast import optimize_source, optimize_file, run_path, run_source, PASS_NAMES
+
+result = optimize_file("script.py")
+print(result.source)             # optimized source (ast.unparse)
+print(result.report.summary())   # per-pass statistics
+run_path("script.py", argv=("--flag",))
+
+optimize_file("script.py", disable="inline,licm")   # every entry point accepts `disable`
+```
+
+## Tests
+
+```powershell
+python tests/verify_opast.py     # full acceptance suite: per-pass behavior assertions
+                                 # + original-vs-optimized output comparison
+```
+
+Case sources are generated into `tests/cases/` on demand (not tracked); the bench harness doubles as a correctness check.
+
+## Prior art
+
+- [pyastop](https://github.com/xiaonanln/pyastop) (2017–2018): an early AST-optimizer prototype built around whole-project analysis and comment hints. opast instead proves each rewrite safe per pass, with no user annotations.
+- [fatoptimizer](https://github.com/vstinner/fatoptimizer) (FAT Python, PEPs 509/510/511): runtime guards + function specialization, abandoned over guard overhead. opast's static passes have zero runtime overhead; runtime machinery exists only behind the opt-in `--jit`.
+- CPython's built-in AST/peephole optimizer folds constants only; opast's gains come from everything beyond that.
+
+## Known limitations
+
+- Optimized code is executed via `compile(optimized_ast, original_filename)`; traceback line numbers reuse original positions where possible but may drift slightly on rewritten lines. Inlining removes call frames from tracebacks (documented per pass).
+- All transformations require static proof; anything unprovable is left untouched. Documented edge observables (e.g. the partially-built-list window excluded via `try`/`with` checks) are listed per pass in [README-ZH.md](README-ZH.md).
+- Python ≥ 3.10.
+
+## License
+
+MIT

opast-0.1.0/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["setuptools>=77"]  # PEP 639 SPDX license expression
+build-backend = "setuptools.build_meta"
+
+[project]
+# Distribution/import/CLI name: opast ("OPtimizing AST"); GitHub repo: pyOpAst.
+name = "opast"
+version = "0.1.0"
+description = "Conservative AST-level Python source optimizer: provably-semantics-preserving passes (folding, propagation, inlining, loop rewrites) with dynamic-code fallback, plus an opt-in numba JIT path."
+requires-python = ">=3.10"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "YZJYBT", email = "yzj0xfff2@gmail.com" }]
+keywords = ["optimizer", "ast", "performance", "source-to-source", "numba", "jit"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Compilers",
+    "Topic :: Software Development :: Code Generators",
+]
+
+[project.urls]
+Repository = "https://github.com/YZJYBT/pyOpAst"
+Issues = "https://github.com/YZJYBT/pyOpAst/issues"
+Changelog = "https://github.com/YZJYBT/pyOpAst/blob/main/CHANGELOG.md"
+
+[project.optional-dependencies]
+# numba >=0.61 covers Python 3.10-3.13; Python 3.14 needs numba >=0.65.
+jit = ["numba>=0.61"]
+
+[project.scripts]
+opast = "opast.__main__:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]

opast-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

opast-0.1.0/src/opast/__init__.py

@@ -0,0 +1,60 @@
+"""opast -- AST-based Python source optimizer.
+
+Optimizations: constant folding, algebraic simplification, dead code
+elimination and simple function inlining.  Scopes containing dynamic
+constructs (eval/exec/globals/locals/vars/compile/__import__/``import *`` ...)
+are conservatively skipped so optimization never changes their behaviour.
+
+Typical use::
+
+    from opast import optimize_file, run_path
+
+    result = optimize_file("script.py")
+    print(result.source)            # optimized source
+    print(result.report.summary())  # what happened
+
+    run_path("script.py", argv=("--flag",))  # optimize then execute
+
+Every entry point accepts ``disable`` -- an iterable or comma-separated
+string of pass names (see :data:`PASS_NAMES`, plus ``"jit"``) to skip::
+
+    optimize_file("script.py", disable="inline,licm")
+    run_source("print(1+1)", disable=("constant-folding",))
+"""
+
+from .pipeline import (
+    DEFAULT_MAX_ITERATIONS,
+    PASS_NAMES,
+    OptimizationReport,
+    OptimizationResult,
+    PassStats,
+    optimize_ast,
+    optimize_file,
+    optimize_source,
+)
+from .runner import execute, run_path, run_source
+
+
+def load_ipython_extension(ipython) -> None:
+    """Enable ``%%opast`` in IPython/Jupyter via ``%load_ext opast``."""
+    from .magic import load_ipython_extension as _load
+
+    _load(ipython)
+
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "DEFAULT_MAX_ITERATIONS",
+    "PASS_NAMES",
+    "OptimizationReport",
+    "OptimizationResult",
+    "PassStats",
+    "optimize_ast",
+    "optimize_file",
+    "optimize_source",
+    "execute",
+    "run_path",
+    "run_source",
+    "__version__",
+]

opast-0.1.0/src/opast/__main__.py

@@ -0,0 +1,136 @@
+"""Command line interface: ``python -m opast [options] script.py [args...]``
+or ``python -m opast [options] -c "code" [args...]``."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from pathlib import Path
+
+from .pipeline import (
+    DEFAULT_MAX_ITERATIONS,
+    PASS_NAMES,
+    optimize_file,
+    optimize_source,
+)
+from .runner import execute
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="opast",
+        description=(
+            "Optimize a Python script with AST passes (constant folding, "
+            "algebraic simplification, dead code elimination, simple function "
+            "inlining) and run it with the current interpreter. Scopes that "
+            "use dynamic constructs (eval/exec/globals/locals/vars/compile/"
+            "__import__/import *) are left untouched."
+        ),
+    )
+    parser.add_argument("--show", action="store_true",
+                        help="print the optimized source to stdout")
+    parser.add_argument("-o", "--output", metavar="FILE",
+                        help="write the optimized source to FILE")
+    parser.add_argument("--no-run", action="store_true",
+                        help="only optimize, do not execute the script")
+    parser.add_argument("--report", action="store_true",
+                        help="print per-pass statistics to stderr")
+    parser.add_argument("--max-iterations", type=int,
+                        default=DEFAULT_MAX_ITERATIONS, metavar="N",
+                        help="max pipeline iterations (default: %(default)s)")
+    parser.add_argument("--jit", action="store_true",
+                        help="decorate hot numeric functions with numba.njit "
+                             "(optional dependency 'opast[jit]'; any numba "
+                             "failure falls back to plain Python at runtime; "
+                             "see README for the int64 caveat)")
+    parser.add_argument("--disable", metavar="PASSES", default="",
+                        help="comma-separated pass names to skip: "
+                             + ", ".join((*PASS_NAMES, "jit")))
+    parser.add_argument("--opt-imports", action="store_true",
+                        help="also optimize imported pure-Python modules "
+                             "under the script's directory (opt-in: modules "
+                             "whose globals are monkeypatched from outside "
+                             "must not be optimized; see README)")
+    parser.add_argument("--opt-imports-under", metavar="DIR", action="append",
+                        default=[],
+                        help="optimize imports under DIR (repeatable; "
+                             "implies the hook without adding the script's "
+                             "directory unless --opt-imports is also given)")
+    parser.add_argument("-c", "--code", metavar="CODE",
+                        help="optimize and run CODE directly (like python -c; "
+                             "remaining arguments go to sys.argv)")
+    parser.add_argument("script", nargs="?",
+                        help="path to the Python script (or, with -c, the "
+                             "first script argument)")
+    parser.add_argument("args", nargs=argparse.REMAINDER,
+                        help="arguments passed to the script")
+    ns = parser.parse_args(argv)
+
+    if ns.code is None and ns.script is None:
+        parser.error("a script path is required (or use -c CODE)")
+
+    try:
+        if ns.code is not None:
+            result = optimize_source(
+                ns.code, filename="<string>",
+                max_iterations=ns.max_iterations, jit=ns.jit,
+                disable=ns.disable,
+            )
+        else:
+            result = optimize_file(
+                ns.script, max_iterations=ns.max_iterations, jit=ns.jit,
+                disable=ns.disable,
+            )
+    except ValueError as exc:  # unknown --disable pass name
+        parser.error(str(exc))
+
+    if ns.jit:
+        from . import jitsupport
+
+        if not jitsupport.numba_available():
+            print(
+                "opast: numba is not available on this interpreter; "
+                "--jit decorations will run as plain Python.",
+                file=sys.stderr,
+            )
+    if ns.show:
+        print(result.source)
+    if ns.output:
+        Path(ns.output).write_text(result.source + "\n", encoding="utf-8")
+    if ns.report:
+        print(result.report.summary(), file=sys.stderr)
+    if not ns.no_run:
+        finder = None
+        if ns.opt_imports or ns.opt_imports_under:
+            from . import importhook
+
+            roots = list(ns.opt_imports_under)
+            if ns.opt_imports:
+                if ns.code is not None:
+                    roots.append(os.getcwd())
+                else:
+                    roots.append(str(Path(ns.script).resolve().parent))
+            finder = importhook.install(
+                roots,
+                max_iterations=ns.max_iterations,
+                jit=ns.jit,
+                disable=ns.disable,
+                report=ns.report,
+            )
+        try:
+            if ns.code is not None:
+                # With -c the positional slot, if used, is really the first
+                # script argument -- mimic ``python -c`` (sys.argv[0] == "-c").
+                args = ([ns.script] if ns.script is not None else []) + list(ns.args)
+                execute(result, tuple(args), write_source=ns.jit, argv0="-c")
+            else:
+                execute(result, tuple(ns.args), write_source=ns.jit)
+        finally:
+            if finder is not None:
+                importhook.uninstall(finder)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())