pycrefine 1.1.1__tar.gz

pycrefine-1.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Saheb
+
+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.

pycrefine-1.1.1/PKG-INFO

@@ -0,0 +1,123 @@
+Metadata-Version: 2.4
+Name: pycrefine
+Version: 1.1.1
+Summary: A Python .pyc decompiler for educational purposes
+Author: Saheb
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/sahebbiswas/pycrefine
+Project-URL: Issues, https://github.com/sahebbiswas/pycrefine/issues
+Keywords: decompiler,bytecode,pyc,cpython,reverse-engineering
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+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 :: Disassemblers
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pylint==4.1.3; extra == "dev"
+Requires-Dist: mypy==2.4.0; extra == "dev"
+Dynamic: license-file
+
+# pycrefine
+
+[![Python 3.9](https://github.com/sahebbiswas/pycrefine/actions/workflows/ci-py39.yml/badge.svg?branch=main&event=push)](https://github.com/sahebbiswas/pycrefine/actions/workflows/ci-py39.yml)
+[![Python 3.12](https://github.com/sahebbiswas/pycrefine/actions/workflows/ci-py312.yml/badge.svg?branch=main&event=push)](https://github.com/sahebbiswas/pycrefine/actions/workflows/ci-py312.yml)
+[![Python 3.14](https://github.com/sahebbiswas/pycrefine/actions/workflows/ci-py314.yml/badge.svg?branch=main&event=push)](https://github.com/sahebbiswas/pycrefine/actions/workflows/ci-py314.yml)
+[![Lint](https://github.com/sahebbiswas/pycrefine/actions/workflows/lint.yml/badge.svg?branch=main&event=push)](https://github.com/sahebbiswas/pycrefine/actions/workflows/lint.yml)
+
+pycrefine turns compiled Python bytecode (`.pyc` files) back into readable Python source.
+It reads `.pyc` files written by CPython 3.9 and later, has no third-party dependencies,
+and works both as a command and as a library.
+
+```console
+$ pycrefine __pycache__/report.cpython-312.pyc
+def summarize(rows, limit=10):
+    totals = {}
+    for name, amount in rows:
+        totals[name] = (totals.get(name, 0) + amount)
+    return sorted(totals.items(), key=(lambda kv: -kv[1]))[:limit]
+```
+
+## Supported Python versions
+
+| Bytecode written by | Status | Run pycrefine under |
+|---|---|---|
+| Python 3.9 | supported, tested in CI | any Python 3.9 or later |
+| Python 3.12, 3.14 | supported, tested in CI | the same minor version (3.12 for 3.12 bytecode) |
+| Python 3.13 | works, not in CI | Python 3.13 |
+| Python 3.10, 3.11 | partial: loops and exception handling often come out wrong | the same minor version |
+| Python 3.8 and older | not supported | |
+
+Bytecode from 3.10 onwards can only be decompiled by the Python version that wrote it
+([#94](https://github.com/sahebbiswas/pycrefine/issues/94)). pycrefine tells you which
+version to use, and [Getting started](https://github.com/sahebbiswas/pycrefine/blob/main/docs/getting-started.md#run-under-the-python-that-wrote-the-file)
+shows how to run it under another Python in one command. Some constructs (`match`,
+`async`/`await`, `yield from`) are not reconstructed yet; see
+[Limitations](https://github.com/sahebbiswas/pycrefine/blob/main/docs/limitations.md).
+
+## Install
+
+```bash
+python -m pip install pycrefine
+```
+
+Until the first release reaches PyPI, install from GitHub instead:
+
+```bash
+python -m pip install "git+https://github.com/sahebbiswas/pycrefine"
+```
+
+Or run it from a checkout without installing: `python pycrefine.py file.pyc`. Install
+problems (`command not found`, `externally-managed-environment`, …) are covered in
+[Troubleshooting](https://github.com/sahebbiswas/pycrefine/blob/main/docs/troubleshooting.md#installation-and-setup).
+
+## Quick start
+
+```bash
+pycrefine module.cpython-312.pyc                 # print the source
+pycrefine module.cpython-312.pyc -o module.py    # save it to a file
+python -m pycrefine module.cpython-312.pyc       # same, if the command is not on PATH
+```
+
+From Python:
+
+```python
+import pycrefine
+
+source = pycrefine.get_decompiler("module.cpython-312.pyc").decompile()
+print(source)
+```
+
+## Documentation
+
+| Guide | Read it to |
+|---|---|
+| [Getting started](https://github.com/sahebbiswas/pycrefine/blob/main/docs/getting-started.md) | install, decompile a first file, and run under the right Python version |
+| [Use cases](https://github.com/sahebbiswas/pycrefine/blob/main/docs/use-cases.md) | recover a project from `__pycache__`, batch-decompile a tree, decompile PyInstaller or in-memory code, check the output |
+| [Command line and Python API](https://github.com/sahebbiswas/pycrefine/blob/main/docs/usage.md) | look up every option, exit status and API call |
+| [Troubleshooting](https://github.com/sahebbiswas/pycrefine/blob/main/docs/troubleshooting.md) | fix setup problems and understand each error message |
+| [Limitations](https://github.com/sahebbiswas/pycrefine/blob/main/docs/limitations.md) | see what is not reconstructed yet, and how to tell |
+| [Architecture](https://github.com/sahebbiswas/pycrefine/blob/main/docs/architecture.md) | find your way around the code |
+| [Contributing](https://github.com/sahebbiswas/pycrefine/blob/main/CONTRIBUTING.md) | set up a development environment, run the checks, version and release |
+
+## Contributing
+
+Bug reports with the `.pyc` file (or the source it came from) and the Python version that
+compiled it are the most useful contribution. See [CONTRIBUTING.md](https://github.com/sahebbiswas/pycrefine/blob/main/CONTRIBUTING.md) for
+the development setup, the checks every pull request runs, and the versioning policy.
+
+## License
+
+[MIT](https://github.com/sahebbiswas/pycrefine/blob/main/LICENSE)

pycrefine-1.1.1/README.md

@@ -0,0 +1,91 @@
+# pycrefine
+
+[![Python 3.9](https://github.com/sahebbiswas/pycrefine/actions/workflows/ci-py39.yml/badge.svg?branch=main&event=push)](https://github.com/sahebbiswas/pycrefine/actions/workflows/ci-py39.yml)
+[![Python 3.12](https://github.com/sahebbiswas/pycrefine/actions/workflows/ci-py312.yml/badge.svg?branch=main&event=push)](https://github.com/sahebbiswas/pycrefine/actions/workflows/ci-py312.yml)
+[![Python 3.14](https://github.com/sahebbiswas/pycrefine/actions/workflows/ci-py314.yml/badge.svg?branch=main&event=push)](https://github.com/sahebbiswas/pycrefine/actions/workflows/ci-py314.yml)
+[![Lint](https://github.com/sahebbiswas/pycrefine/actions/workflows/lint.yml/badge.svg?branch=main&event=push)](https://github.com/sahebbiswas/pycrefine/actions/workflows/lint.yml)
+
+pycrefine turns compiled Python bytecode (`.pyc` files) back into readable Python source.
+It reads `.pyc` files written by CPython 3.9 and later, has no third-party dependencies,
+and works both as a command and as a library.
+
+```console
+$ pycrefine __pycache__/report.cpython-312.pyc
+def summarize(rows, limit=10):
+    totals = {}
+    for name, amount in rows:
+        totals[name] = (totals.get(name, 0) + amount)
+    return sorted(totals.items(), key=(lambda kv: -kv[1]))[:limit]
+```
+
+## Supported Python versions
+
+| Bytecode written by | Status | Run pycrefine under |
+|---|---|---|
+| Python 3.9 | supported, tested in CI | any Python 3.9 or later |
+| Python 3.12, 3.14 | supported, tested in CI | the same minor version (3.12 for 3.12 bytecode) |
+| Python 3.13 | works, not in CI | Python 3.13 |
+| Python 3.10, 3.11 | partial: loops and exception handling often come out wrong | the same minor version |
+| Python 3.8 and older | not supported | |
+
+Bytecode from 3.10 onwards can only be decompiled by the Python version that wrote it
+([#94](https://github.com/sahebbiswas/pycrefine/issues/94)). pycrefine tells you which
+version to use, and [Getting started](https://github.com/sahebbiswas/pycrefine/blob/main/docs/getting-started.md#run-under-the-python-that-wrote-the-file)
+shows how to run it under another Python in one command. Some constructs (`match`,
+`async`/`await`, `yield from`) are not reconstructed yet; see
+[Limitations](https://github.com/sahebbiswas/pycrefine/blob/main/docs/limitations.md).
+
+## Install
+
+```bash
+python -m pip install pycrefine
+```
+
+Until the first release reaches PyPI, install from GitHub instead:
+
+```bash
+python -m pip install "git+https://github.com/sahebbiswas/pycrefine"
+```
+
+Or run it from a checkout without installing: `python pycrefine.py file.pyc`. Install
+problems (`command not found`, `externally-managed-environment`, …) are covered in
+[Troubleshooting](https://github.com/sahebbiswas/pycrefine/blob/main/docs/troubleshooting.md#installation-and-setup).
+
+## Quick start
+
+```bash
+pycrefine module.cpython-312.pyc                 # print the source
+pycrefine module.cpython-312.pyc -o module.py    # save it to a file
+python -m pycrefine module.cpython-312.pyc       # same, if the command is not on PATH
+```
+
+From Python:
+
+```python
+import pycrefine
+
+source = pycrefine.get_decompiler("module.cpython-312.pyc").decompile()
+print(source)
+```
+
+## Documentation
+
+| Guide | Read it to |
+|---|---|
+| [Getting started](https://github.com/sahebbiswas/pycrefine/blob/main/docs/getting-started.md) | install, decompile a first file, and run under the right Python version |
+| [Use cases](https://github.com/sahebbiswas/pycrefine/blob/main/docs/use-cases.md) | recover a project from `__pycache__`, batch-decompile a tree, decompile PyInstaller or in-memory code, check the output |
+| [Command line and Python API](https://github.com/sahebbiswas/pycrefine/blob/main/docs/usage.md) | look up every option, exit status and API call |
+| [Troubleshooting](https://github.com/sahebbiswas/pycrefine/blob/main/docs/troubleshooting.md) | fix setup problems and understand each error message |
+| [Limitations](https://github.com/sahebbiswas/pycrefine/blob/main/docs/limitations.md) | see what is not reconstructed yet, and how to tell |
+| [Architecture](https://github.com/sahebbiswas/pycrefine/blob/main/docs/architecture.md) | find your way around the code |
+| [Contributing](https://github.com/sahebbiswas/pycrefine/blob/main/CONTRIBUTING.md) | set up a development environment, run the checks, version and release |
+
+## Contributing
+
+Bug reports with the `.pyc` file (or the source it came from) and the Python version that
+compiled it are the most useful contribution. See [CONTRIBUTING.md](https://github.com/sahebbiswas/pycrefine/blob/main/CONTRIBUTING.md) for
+the development setup, the checks every pull request runs, and the versioning policy.
+
+## License
+
+[MIT](https://github.com/sahebbiswas/pycrefine/blob/main/LICENSE)

pycrefine-1.1.1/pyproject.toml

@@ -0,0 +1,79 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pycrefine"
+dynamic = ["version"]
+description = "A Python .pyc decompiler for educational purposes"
+readme = "README.md"
+authors = [{name = "Saheb"}]
+license = "MIT"
+requires-python = ">=3.9"
+keywords = ["decompiler", "bytecode", "pyc", "cpython", "reverse-engineering"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "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 :: Disassemblers",
+]
+dependencies = [] # Keeps your "no dependencies" promise
+
+[project.urls]
+Homepage = "https://github.com/sahebbiswas/pycrefine"
+Issues = "https://github.com/sahebbiswas/pycrefine/issues"
+
+[project.optional-dependencies]
+test = ["pytest"]
+dev = ["pytest", "pylint==4.1.3", "mypy==2.4.0"]
+
+[project.scripts]
+pycrefine = "pycrefine.cli:main" # Allows running 'pycrefine' directly in terminal
+
+[tool.setuptools.dynamic]
+version = {attr = "pycrefine.__version__"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = "test_*.py"
+
+# Type checking (docs/linting.md). Permissive by default: errors are ignored everywhere
+# except the modules listed in the override below, which are checked with the strict
+# flag set. Move a module into the list once it is clean. Run: mypy
+[tool.mypy]
+python_version = "3.10"  # oldest target mypy supports; the code itself stays 3.9-compatible
+files = ["src/pycrefine"]
+mypy_path = "src"
+ignore_errors = true
+warn_unused_configs = true
+warn_redundant_casts = true
+
+[[tool.mypy.overrides]]
+module = [
+    "pycrefine._constants",
+    "pycrefine.cli",
+    "pycrefine.codeobj",
+    "pycrefine.expr",
+    "pycrefine.instructions",
+    "pycrefine.versions",
+]
+ignore_errors = false
+disallow_any_generics = true
+disallow_untyped_calls = true
+disallow_untyped_defs = true
+disallow_incomplete_defs = true
+check_untyped_defs = true
+no_implicit_optional = true
+warn_unused_ignores = true
+warn_return_any = true

pycrefine-1.1.1/setup.cfg

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

pycrefine-1.1.1/src/pycrefine/__init__.py

@@ -0,0 +1,65 @@
+"""pycrefine: a Python .pyc decompiler that rebuilds source code from compiled bytecode.
+
+Every name that used to live in the single-file ``pycrefine`` module is re-exported here,
+so ``import pycrefine`` and ``from pycrefine import ...`` behave as before.
+"""
+__version__ = "1.1.1"
+
+from ._constants import (  # noqa: F401
+    _AUG_ASSIGN_MAP,
+    _COMPOUND_EXPR_OPS,
+    _COMPOUND_SKIP,
+    _GENERIC_SKIP_OPS,
+    _INPLACE_ASSIGN_MAP,
+    _IS_COMP_GEN_SKIP,
+    _IS_COMP_GEN_STOP,
+    _MAX_TERNARY_MINI_SEARCH_WINDOW,
+    _MAX_TERNARY_SEARCH_WINDOW,
+    _MAX_TERNARY_SHORT_SEARCH_WINDOW,
+    _MAX_WITH_EXIT_SEARCH_WINDOW,
+    _NO_INDENT_TYPES,
+    _NO_PASS_TYPES,
+    _STATEMENT_BOUNDARY_OPS,
+    _TERNARY_PURE,
+    _TERNARY_SKIP,
+    _TERNARY_STORES,
+    _TERNARY_TERM,
+    _TRY_HANDLER_EXIT_OPS,
+    _TRY_LOAD_OPS,
+    _TRY_LOOP_HEADS,
+    _TRY_SKIP_NOP,
+    _UNARY_SYMBOLS,
+    _WHILE_TRIVIAL_OPS,
+)
+from .expr import StackNULL, _BoolExpr, _CollectionAccumSentinel, _unary_operand  # noqa: F401
+from .instructions import (  # noqa: F401
+    BytecodeInstruction,
+    _const_repr,
+    _is_anonymous_func_body,
+    _render_func_tuple,
+)
+from .postprocess import (  # noqa: F401
+    _block_opener_keyword,
+    _collect_multiline_header,
+    _line_is_in_triple_quoted_string,
+    collapse_chained_comparisons,
+    flatten_elif,
+    post_process_source,
+)
+from .codeobj import ForeignCode, _is_code  # noqa: F401
+from .decompiler.base import DecompilerBase  # noqa: F401
+from .decompiler.generic import DecompilerGeneric, _pick_decompiler_class  # noqa: F401
+from .opcodes.py39 import _OPCODES_39  # noqa: F401
+from .decompiler.py39 import Decompiler39  # noqa: F401
+from .decompiler.py311 import Decompiler311Plus  # noqa: F401
+from .decompiler.py314 import Decompiler314  # noqa: F401
+from .loader import (  # noqa: F401
+    MarshalParser,
+    _CO_FAST_CELL,
+    _CO_FAST_FREE,
+    _CO_FAST_LOCAL,
+    _MARSHAL_NULL,
+    get_decompiler,
+)
+from .versions import _get_python_version_from_magic  # noqa: F401
+from .cli import main  # noqa: F401

pycrefine-1.1.1/src/pycrefine/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+main()

pycrefine-1.1.1/src/pycrefine/_constants.py

@@ -0,0 +1,136 @@
+"""Shared constant instruction sets, lookup maps and search-window sizes."""
+
+
+# --- Magic Numbers & Search Windows ---
+_MAX_WITH_EXIT_SEARCH_WINDOW = 200
+
+
+_MAX_TERNARY_SEARCH_WINDOW = 20
+
+
+_MAX_TERNARY_SHORT_SEARCH_WINDOW = 12
+
+
+_MAX_TERNARY_MINI_SEARCH_WINDOW = 8
+
+
+# --- Constant Instruction Sets ---
+_NO_PASS_TYPES = frozenset({"exc_cleanup", "finally_wrapper"})
+
+
+_NO_INDENT_TYPES = frozenset({"finally_wrapper"})
+
+
+_UNARY_SYMBOLS = {
+    "UNARY_NEGATIVE": "-", "UNARY_POSITIVE": "+", "UNARY_INVERT": "~", "UNARY_NOT": "not ",
+}
+
+
+_TERNARY_STORES = frozenset(("STORE_FAST", "STORE_NAME", "STORE_GLOBAL", "STORE_DEREF"))
+
+
+_TERNARY_SKIP = frozenset(("CACHE", "RESUME", "NOT_TAKEN", "COPY_FREE_VARS"))
+
+
+_TERNARY_TERM = frozenset(("RETURN_CONST", "RETURN_VALUE"))
+
+
+_TERNARY_PURE = frozenset((
+    "LOAD_FAST", "LOAD_NAME", "LOAD_GLOBAL", "LOAD_CONST", "LOAD_DEREF",
+    "LOAD_SMALL_INT", "LOAD_GLOBAL_MODULE", "LOAD_ATTR", "LOAD_METHOD",
+    "GET_ATTR", "LOAD_FAST_BORROW", "LOAD_FAST_BORROW_LOAD_FAST_BORROW",
+    "LOAD_CONST_BORROW", "CALL", "CALL_FUNCTION", "CALL_METHOD",
+    "COMPARE_OP", "BINARY_OP", "IS_OP", "CONTAINS_OP",
+    "UNARY_NOT", "UNARY_NEGATIVE", "UNARY_POSITIVE", "UNARY_INVERT", "CALL_INTRINSIC_1",
+    "BUILD_TUPLE", "BUILD_LIST", "BUILD_SET", "BUILD_MAP",
+    "PRECALL", "PUSH_NULL", "FORMAT_VALUE", "FORMAT_SIMPLE", "BUILD_STRING",
+    "BINARY_SUBSCR", "TO_BOOL", "BINARY_SLICE", "BUILD_SLICE",
+    # Python 3.9 named binary opcodes (3.11+ uses BINARY_OP instead):
+    "BINARY_ADD", "BINARY_SUBTRACT", "BINARY_MULTIPLY", "BINARY_TRUE_DIVIDE",
+    "BINARY_FLOOR_DIVIDE", "BINARY_MODULO", "BINARY_POWER", "BINARY_LSHIFT",
+    "BINARY_RSHIFT", "BINARY_AND", "BINARY_OR", "BINARY_XOR",
+    "BINARY_MATRIX_MULTIPLY",
+)) | _TERNARY_SKIP | _TERNARY_TERM
+
+
+_COMPOUND_SKIP = frozenset(("CACHE", "RESUME", "NOT_TAKEN", "COPY_FREE_VARS", "PRECALL", "PUSH_NULL"))
+
+
+_COMPOUND_EXPR_OPS = frozenset((
+    "LOAD_FAST", "LOAD_NAME", "LOAD_GLOBAL", "LOAD_CONST", "LOAD_DEREF",
+    "LOAD_SMALL_INT", "LOAD_FAST_BORROW", "LOAD_CONST_BORROW", "LOAD_FAST_BORROW_LOAD_FAST_BORROW",
+    "LOAD_GLOBAL_MODULE", "LOAD_ATTR", "LOAD_METHOD", "GET_ATTR",
+    "CALL", "CALL_FUNCTION", "CALL_METHOD", "COMPARE_OP", "BINARY_OP", "IS_OP", "CONTAINS_OP",
+    "UNARY_NOT", "UNARY_NEGATIVE", "UNARY_POSITIVE", "UNARY_INVERT",
+    "BUILD_TUPLE", "BUILD_LIST", "BUILD_SET", "BUILD_MAP",
+    "TO_BOOL", "FORMAT_VALUE", "FORMAT_SIMPLE", "BUILD_STRING", "BINARY_SUBSCR", "BINARY_SLICE", "BUILD_SLICE",
+    "DUP_TOP", "DUP_TOP_TWO", "ROT_TWO", "ROT_THREE", "ROT_FOUR", "SWAP", "COPY",
+    # Python 3.9 binary opcodes:
+    "BINARY_ADD", "BINARY_SUBTRACT", "BINARY_MULTIPLY", "BINARY_TRUE_DIVIDE",
+    "BINARY_FLOOR_DIVIDE", "BINARY_MODULO", "BINARY_POWER", "BINARY_LSHIFT",
+    "BINARY_RSHIFT", "BINARY_AND", "BINARY_OR", "BINARY_XOR",
+    "BINARY_MATRIX_MULTIPLY"
+)) | _COMPOUND_SKIP
+
+
+_WHILE_TRIVIAL_OPS = frozenset({"NOP", "RESUME", "NOT_TAKEN", "CACHE", "COPY_FREE_VARS"})
+
+
+_STATEMENT_BOUNDARY_OPS = frozenset({
+    "POP_TOP", "POP_ITER", "END_FOR", "RETURN_VALUE", "RETURN_CONST", "RAISE_VARARGS",
+    "RERAISE", "POP_BLOCK", "PUSH_EXC_INFO", "POP_EXCEPT",
+})
+
+
+_TRY_SKIP_NOP = frozenset({"RESUME", "CACHE", "NOT_TAKEN"})
+
+# Placeholders between a protected range's end and the code that follows it (a with
+# block's inlined exit call, a finally copy): skipped when matching positions.
+_FILLER_OPS = frozenset({"NOP", "CACHE"})
+
+
+_TRY_LOAD_OPS = frozenset({"LOAD_NAME", "LOAD_GLOBAL", "LOAD_FAST",
+                          "LOAD_DEREF", "LOAD_SMALL_INT", "LOAD_GLOBAL_MODULE"})
+
+
+_TRY_LOOP_HEADS = frozenset({"FOR_ITER", "GET_ITER", "GET_ANEXT", "GET_AWAITABLE"})
+
+
+_TRY_HANDLER_EXIT_OPS = frozenset({"POP_EXCEPT", "DELETE_FAST", "DELETE_NAME",
+                                  "DELETE_GLOBAL", "STORE_FAST", "STORE_NAME"})
+
+
+_IS_COMP_GEN_SKIP = frozenset({"POP_TOP", "CACHE", "NOP", "RESUME", "COPY", "NOT_TAKEN"})
+
+
+_IS_COMP_GEN_STOP = frozenset({"LOAD_CONST", "LOAD_NAME", "LOAD_FAST", "LOAD_GLOBAL", "LOAD_DEREF", "LOAD_SMALL_INT",
+                              "LOAD_ATTR", "PUSH_NULL", "RERAISE", "RAISE_VARARGS", "RETURN_CONST", "RETURN_VALUE", "JUMP_FORWARD"})
+
+
+_GENERIC_SKIP_OPS = frozenset({"RESUME", "CACHE", "NOP", "NOT_TAKEN", "COPY_FREE_VARS", "EXTENDED_ARG"})
+
+
+# --- Augmented Assignment Opcodes ---
+_AUG_ASSIGN_MAP = {
+    13: "+=",  14: "&=",  15: "//=", 16: "<<=", 17: "@=",
+    18: "*=",  19: "%=",  20: "|=",  21: "**=", 22: ">>=",
+    23: "-=",  24: "/=",  25: "^=",
+}
+
+
+_INPLACE_ASSIGN_MAP = {
+    "INPLACE_ADD": "+=", "INPLACE_SUBTRACT": "-=",
+    "INPLACE_MULTIPLY": "*=", "INPLACE_TRUE_DIVIDE": "/=",
+    "INPLACE_FLOOR_DIVIDE": "//=", "INPLACE_MODULO": "%=",
+    "INPLACE_POWER": "**=", "INPLACE_LSHIFT": "<<=",
+    "INPLACE_RSHIFT": ">>=", "INPLACE_AND": "&=",
+    "INPLACE_OR": "|=", "INPLACE_XOR": "^=",
+    "INPLACE_MATRIX_MULTIPLY": "@=",
+}
+
+
+# --- Value-pushing opcodes (prefixes) ---
+# Instructions that push a value, such as the callee of a call before its arguments;
+# an inlined `with` exit call never directly follows one of them.
+_VALUE_OPS = ("LOAD_", "PUSH_NULL", "CALL", "BINARY_", "BUILD_", "COPY", "GET_", "UNARY_",
+              "COMPARE_", "FORMAT_", "MAKE_FUNCTION", "CONTAINS_OP", "IS_OP")

pycrefine-1.1.1/src/pycrefine/cli.py

@@ -0,0 +1,53 @@
+"""Command-line interface."""
+import argparse
+import sys
+import traceback
+from .loader import get_decompiler
+
+
+# ---------------------------------------------------------------------------
+# CLI
+# ---------------------------------------------------------------------------
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="A Python .pyc decompiler that reconstructs readable source code from compiled bytecode."
+    )
+    parser.add_argument("input", help="The .pyc file to decompile")
+    parser.add_argument(
+        "-o", "--output",
+        help="Optional filename to save the decompiled output to. If not supplied, prints to screen."
+    )
+    parser.add_argument(
+        "--beautification-level",
+        choices=['none', 'core', 'aggressive'], default='core',
+        help="Level of code beautification to apply. 'none' does no beautification. 'core' collapses else-if to elif. 'aggressive' is a stub for future use."
+    )
+
+    args = parser.parse_args()
+
+    try:
+        decompiler = get_decompiler(args.input, args.beautification_level)
+        output_text = decompiler.decompile()
+
+        if args.output:
+            try:
+                with open(args.output, "w", encoding="utf-8") as f:
+                    f.write(output_text)
+                print(f"Decompiled output saved to {args.output}", file=sys.stderr)
+            except OSError as e:
+                print(f"Error: Failed to save decompiled output to {args.output}: {e}", file=sys.stderr)
+                sys.exit(1)
+        else:
+            if output_text and output_text.strip():
+                print(output_text)
+            else:
+                print(f"Warning: Decompiler returned no source code for {args.input}", file=sys.stderr)
+                sys.exit(1)
+
+    except ValueError as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(1)
+    except Exception:
+        traceback.print_exc()
+        sys.exit(1)

pycrefine-1.1.1/src/pycrefine/codeobj.py

@@ -0,0 +1,26 @@
+"""Code-object helpers shared by the loader and the decompilers (``ForeignCode`` for foreign-version .pyc files)."""
+import types
+from typing import Any
+
+
+class ForeignCode:
+    """
+    A code object read from a .pyc of a different Python version.
+
+    The host interpreter cannot build a real ``types.CodeType`` from another
+    version's bytecode, so the parsed fields are kept as plain ``co_*``
+    attributes. The decompilers only read those attributes.
+    """
+
+    co_name: str
+
+    def __init__(self, **fields: Any):
+        self.__dict__.update(fields)
+
+    def __repr__(self) -> str:
+        return f"<ForeignCode {self.co_name!r}>"
+
+
+def _is_code(obj: Any) -> bool:
+    """True for a host code object or one parsed from another Python version."""
+    return isinstance(obj, (types.CodeType, ForeignCode))