pychd-pyobf 0.1.0__tar.gz

pychd_pyobf-0.1.0/.gitignore

@@ -0,0 +1,172 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/#use-with-ide
+.pdm.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+**/logging.conf
+.envrc
+
+# Local Claude Code session state
+.claude/
+
+# Codex review scratch (transient, do not commit)
+.codex
+
+# Local PNG previews (SVGs are the committed source of truth)
+assets/*.png

pychd_pyobf-0.1.0/PKG-INFO

@@ -0,0 +1,51 @@
+Metadata-Version: 2.4
+Name: pychd-pyobf
+Version: 0.1.0
+Summary: Anonymise identifiers / constants / metadata inside a CPython .pyc while preserving the opcode stream — for contamination-free decompiler benchmarking
+Author-email: 卍diohabara卍 <diohabara@users.noreply.github.com>
+Requires-Python: >=3.14
+Requires-Dist: pychd>=1.2.0
+Description-Content-Type: text/markdown
+
+# pychd-pyobf
+
+Anonymise identifiers, string constants, docstrings, and metadata
+inside a CPython `.pyc` while preserving the opcode stream exactly.
+
+Built to neutralise LLM training-data memorisation when benchmarking
+Python decompilers: even if an LLM has seen the original source on
+the internet, the anonymised `.pyc` does not contain the surface
+tokens (variable names, comments, docstrings) it would use to
+recognise the source.
+
+Covers every CPython release pychd recognises: 3.0–3.14.
+- 3.14 (the running interpreter) is rewritten natively via
+  `types.CodeType.replace()`.
+- 3.0–3.13 are rewritten via a subprocess into a uv-managed Python of
+  that minor version, so the obfuscator stays a tiny dependency.
+
+Pair with `pychd-pyfuzz` (random valid-Python source generator) for
+the strongest available contamination guarantee.
+
+See the main [pychd README](https://github.com/diohabara/pychd) for
+the broader story.
+
+## Install
+
+```bash
+pip install pychd-pyobf
+```
+
+## Use
+
+```bash
+pychd-pyobf rewrite IN.pyc OUT.pyc --mapping mapping.json
+```
+
+The `--mapping` flag (optional) writes the original-to-anonymised
+identifier dict to JSON for audit / debugging. Without it, the
+mapping is discarded after rewriting.
+
+## Status
+
+Pre-release. API and CLI are still evolving with the parent project.

pychd_pyobf-0.1.0/README.md

@@ -0,0 +1,42 @@
+# pychd-pyobf
+
+Anonymise identifiers, string constants, docstrings, and metadata
+inside a CPython `.pyc` while preserving the opcode stream exactly.
+
+Built to neutralise LLM training-data memorisation when benchmarking
+Python decompilers: even if an LLM has seen the original source on
+the internet, the anonymised `.pyc` does not contain the surface
+tokens (variable names, comments, docstrings) it would use to
+recognise the source.
+
+Covers every CPython release pychd recognises: 3.0–3.14.
+- 3.14 (the running interpreter) is rewritten natively via
+  `types.CodeType.replace()`.
+- 3.0–3.13 are rewritten via a subprocess into a uv-managed Python of
+  that minor version, so the obfuscator stays a tiny dependency.
+
+Pair with `pychd-pyfuzz` (random valid-Python source generator) for
+the strongest available contamination guarantee.
+
+See the main [pychd README](https://github.com/diohabara/pychd) for
+the broader story.
+
+## Install
+
+```bash
+pip install pychd-pyobf
+```
+
+## Use
+
+```bash
+pychd-pyobf rewrite IN.pyc OUT.pyc --mapping mapping.json
+```
+
+The `--mapping` flag (optional) writes the original-to-anonymised
+identifier dict to JSON for audit / debugging. Without it, the
+mapping is discarded after rewriting.
+
+## Status
+
+Pre-release. API and CLI are still evolving with the parent project.

pychd_pyobf-0.1.0/pychd_pyobf/__init__.py

@@ -0,0 +1,28 @@
+"""pychd_pyobf — anonymise identifiers / constants / metadata in a .pyc.
+
+Public API:
+
+* :func:`obfuscate` — main entry point: ``obfuscate(in_path, out_path)``
+  rewrites a .pyc in place and returns an :class:`ObfuscationReport`.
+* :class:`ObfuscationReport` — the report dataclass (paths, writer
+  version, identifier mapping, native vs subprocess flag).
+* :class:`ObfuscationMapping` — the original→anonymised name table
+  the report carries.
+
+The CLI entry point is :func:`pychd_pyobf.cli.main` (registered as the
+``pychd-pyobf`` console script).
+"""
+
+from __future__ import annotations
+
+from .dispatch import ObfuscationReport, obfuscate
+from .rewrite_native import ObfuscationMapping
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "ObfuscationMapping",
+    "ObfuscationReport",
+    "__version__",
+    "obfuscate",
+]

pychd_pyobf-0.1.0/pychd_pyobf/cli.py

@@ -0,0 +1,67 @@
+"""``pychd-pyobf`` command-line entry point.
+
+Usage::
+
+    pychd-pyobf rewrite IN.pyc OUT.pyc [--mapping mapping.json]
+                        [--force-subprocess]
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from .dispatch import obfuscate
+
+
+def _cmd_rewrite(args: argparse.Namespace) -> int:
+    report = obfuscate(
+        args.in_pyc,
+        args.out_pyc,
+        force_subprocess=args.force_subprocess,
+    )
+    path = "native" if report.used_native else "subprocess"
+    print(
+        f"pychd-pyobf: wrote {report.out_path} "
+        f"(writer Py {report.version.version[0]}.{report.version.version[1]}, "
+        f"{path} path, {report.total_renames()} renames)",
+        file=sys.stderr,
+    )
+    if args.mapping is not None:
+        args.mapping.write_text(json.dumps(report.mapping.to_dict(), indent=2))
+        print(f"pychd-pyobf: mapping → {args.mapping}", file=sys.stderr)
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="pychd-pyobf", description=__doc__)
+    sub = parser.add_subparsers(dest="cmd", required=True)
+
+    rew = sub.add_parser("rewrite", help="anonymise IN.pyc → OUT.pyc")
+    rew.add_argument("in_pyc", type=Path)
+    rew.add_argument("out_pyc", type=Path)
+    rew.add_argument(
+        "--mapping",
+        type=Path,
+        default=None,
+        help="optional path to dump the original→anonymised JSON map",
+    )
+    rew.add_argument(
+        "--force-subprocess",
+        action="store_true",
+        help=(
+            "always take the subprocess path even when the writer minor"
+            " matches the current interpreter (useful for testing the"
+            " cross-version code)"
+        ),
+    )
+    rew.set_defaults(func=_cmd_rewrite)
+
+    args = parser.parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

pychd_pyobf-0.1.0/pychd_pyobf/dispatch.py

@@ -0,0 +1,96 @@
+"""Top-level obfuscation entry point.
+
+Dispatches between the native rewriter (when the .pyc was written by
+the *currently-running* interpreter) and the subprocess rewriter
+(everything else). Returns an :class:`ObfuscationReport` carrying the
+output path, the writer version, and the identifier mapping.
+"""
+
+from __future__ import annotations
+
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+from pychd.versions import VersionInfo
+
+from .header import header_length_for, merge_pyc, split_pyc
+from .rewrite_native import ObfuscationMapping, anonymise
+from .rewrite_subprocess import run_subprocess_rewrite, uv_run_command
+
+
+@dataclass
+class ObfuscationReport:
+    """Result of an obfuscation run."""
+
+    in_path: Path
+    out_path: Path
+    version: VersionInfo
+    used_native: bool
+    mapping: ObfuscationMapping
+
+    def total_renames(self) -> int:
+        m = self.mapping
+        return (
+            len(m.names)
+            + len(m.varnames)
+            + len(m.freevars)
+            + len(m.cellvars)
+            + len(m.consts)
+            + len(m.co_names)
+        )
+
+
+def _current_minor() -> tuple[int, int]:
+    return (sys.version_info.major, sys.version_info.minor)
+
+
+def obfuscate(
+    in_pyc: Path,
+    out_pyc: Path,
+    *,
+    force_subprocess: bool = False,
+) -> ObfuscationReport:
+    """Rewrite *in_pyc* → *out_pyc* and return an audit report.
+
+    Native path: when the writer's minor matches the running
+    interpreter we ``marshal.loads`` directly and rewrite in-process.
+    Cross-version path: spawn ``uv run --python <writer-minor>`` and
+    run the same rewrite inside it (see ``rewrite_subprocess.py``).
+
+    ``force_subprocess=True`` always takes the subprocess path; useful
+    for tests that want to verify the cross-version code on the
+    currently-running version too.
+    """
+    in_pyc = Path(in_pyc)
+    out_pyc = Path(out_pyc)
+    version, header, body = split_pyc(in_pyc)
+    hlen = header_length_for(version)
+    use_native = (not force_subprocess) and version.version == _current_minor()
+    if use_native:
+        import marshal
+
+        code = marshal.loads(body)
+        new_code, mapping = anonymise(code)
+        new_body = marshal.dumps(new_code)
+        out_pyc.parent.mkdir(parents=True, exist_ok=True)
+        out_pyc.write_bytes(merge_pyc(header, new_body))
+        return ObfuscationReport(
+            in_path=in_pyc,
+            out_path=out_pyc,
+            version=version,
+            used_native=True,
+            mapping=mapping,
+        )
+    target_cmd = uv_run_command(version.version)
+    mapping = run_subprocess_rewrite(target_cmd, in_pyc, out_pyc, hlen)
+    return ObfuscationReport(
+        in_path=in_pyc,
+        out_path=out_pyc,
+        version=version,
+        used_native=False,
+        mapping=mapping,
+    )
+
+
+__all__ = ["ObfuscationReport", "obfuscate"]

pychd_pyobf-0.1.0/pychd_pyobf/header.py

@@ -0,0 +1,72 @@
+"""CPython ``.pyc`` header parsing + reconstruction.
+
+CPython has used two header layouts across the 3.x line:
+
+* **3.0 – 3.6** (12-byte header): ``magic (4) | timestamp (4) | source_size (4)``.
+* **3.7+** (PEP 552, 16-byte header):
+  ``magic (4) | bit_field (4) | timestamp-or-hash (8) | source_size (8 if hash mode)``
+  Concretely the layout is still 16 bytes total — the ``bit_field``
+  decides whether the next 8 bytes are timestamp-based (timestamp(4) +
+  source_size(4)) or hash-based (8-byte hash).
+
+We reuse :func:`pychd.versions.read_magic` / :func:`pychd.versions.detect_version`
+to identify the writer. ``header_length_for(version)`` then tells us
+where the marshalled code object begins; ``split_pyc(pyc)`` returns
+``(header_bytes, body_bytes)``.
+
+We deliberately do not parse the bit_field — the obfuscator preserves
+the original header verbatim, so re-serialising the rewritten code
+object just needs to concatenate the original bytes with the new body.
+The only field we ever consider rewriting is ``source_size``, which we
+zero out (no source on disk for an anonymised .pyc), but only when the
+writer is 3.7+ where that field is unambiguous.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from pychd.versions import VersionInfo, detect_version
+
+
+def header_length_for(version: VersionInfo) -> int:
+    """Return the byte length of the .pyc header for *version*'s writer.
+
+    3.7 introduced the 16-byte PEP 552 header. Everything before that
+    used a 12-byte layout (magic + timestamp + source_size, each 4
+    bytes little-endian).
+    """
+    if version.version >= (3, 7):
+        return 16
+    return 12
+
+
+def split_pyc(pyc_path: Path) -> tuple[VersionInfo, bytes, bytes]:
+    """Read *pyc_path* and return (version, header_bytes, body_bytes).
+
+    The body is the marshalled top-level code object, ready to feed
+    into :func:`marshal.loads` under the writer's Python interpreter.
+    """
+    data = pyc_path.read_bytes()
+    version = detect_version(pyc_path)
+    hlen = header_length_for(version)
+    if len(data) < hlen:
+        raise ValueError(
+            f"{pyc_path}: truncated — only {len(data)} bytes but expected"
+            f" at least {hlen} for Python {version.version[0]}."
+            f"{version.version[1]}",
+        )
+    return version, data[:hlen], data[hlen:]
+
+
+def merge_pyc(header: bytes, body: bytes) -> bytes:
+    """Reassemble a .pyc from its (header, body) pair.
+
+    This is a thin wrapper that exists so callers can match the
+    :func:`split_pyc` mental model rather than concatenating raw
+    bytes.
+    """
+    return header + body
+
+
+__all__ = ["header_length_for", "split_pyc", "merge_pyc"]

pychd_pyobf-0.1.0/pychd_pyobf/rewrite_native.py

@@ -0,0 +1,210 @@
+"""Native (3.14 / running-interpreter) .pyc anonymiser.
+
+Uses :func:`marshal.loads` + :meth:`types.CodeType.replace` to rewrite
+identifiers, constants, and metadata recursively, then re-marshals the
+top-level code object. The opcode stream (``co_code``) is preserved
+byte-for-byte so :mod:`dis` still walks the result and pychd's rule
+pass still sees the same instruction structure.
+
+The cross-version path (``rewrite_subprocess``) reuses the same
+algorithm, just executed inside a subprocess running the target
+interpreter.
+
+Anonymisation rules (kept in sync with the package docstring):
+
+* ``co_names``     → ``_n0, _n1, …``
+* ``co_varnames``  → ``_v0, _v1, …``
+* ``co_freevars``  → ``_f0, _f1, …``
+* ``co_cellvars``  → ``_c0, _c1, …``
+* ``co_consts``    → string literals → ``_s0, _s1, …``; other
+                     primitives left alone; tuples / frozensets
+                     mapped recursively; nested code objects
+                     recursively anonymised
+* ``co_name``      → per-depth ``_fn0, _fn1, …``
+* ``co_qualname``  → same per-depth scheme (3.11+ only)
+* ``co_filename``  → fixed literal ``"<anonymised>"``
+* ``co_lnotab`` /
+  ``co_linetable`` /
+  ``co_positions``→ replaced with empty bytes — pychd's rule pass
+                    does not depend on line info
+* ``co_firstlineno`` → 1
+* docstring (the leading ``co_consts[0]`` when it is a ``str``) →
+  retained as a string but rewritten via the same ``co_consts``
+  mapping (so it ends up as ``_sN`` rather than its original text)
+
+The function returns an :class:`ObfuscationMapping` so callers can
+audit the rewriting (and so the unit tests can assert that every
+emitted identifier starts with the expected prefix).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from types import CodeType
+
+
+@dataclass
+class ObfuscationMapping:
+    """Original → anonymised name table, returned alongside the rewrite."""
+
+    names: dict[str, str] = field(default_factory=dict)
+    varnames: dict[str, str] = field(default_factory=dict)
+    freevars: dict[str, str] = field(default_factory=dict)
+    cellvars: dict[str, str] = field(default_factory=dict)
+    consts: dict[str, str] = field(default_factory=dict)
+    co_names: dict[str, str] = field(default_factory=dict)  # co_name (function name)
+
+    def to_dict(self) -> dict[str, dict[str, str]]:
+        return {
+            "names": dict(self.names),
+            "varnames": dict(self.varnames),
+            "freevars": dict(self.freevars),
+            "cellvars": dict(self.cellvars),
+            "consts": dict(self.consts),
+            "co_names": dict(self.co_names),
+        }
+
+
+_ANON_FILENAME = "<anonymised>"
+
+
+def _anonymise_tuple(
+    original: tuple[str, ...],
+    prefix: str,
+    mapping: dict[str, str],
+) -> tuple[str, ...]:
+    """Rewrite *original* (a tuple of strings) into ``_<prefix>N`` form,
+    growing *mapping* with the rename pairs.
+
+    The suffix counter is the *global* size of ``mapping`` rather than
+    the per-tuple index — otherwise two different code objects whose
+    parameter lists each start at index 0 would both map their first
+    fresh name to ``_<prefix>0``, producing duplicate-argument bugs
+    when ``apply_mapping_to_source`` writes them out.
+    """
+    out: list[str] = []
+    for name in original:
+        if name in mapping:
+            out.append(mapping[name])
+            continue
+        new_name = f"_{prefix}{len(mapping)}"
+        mapping[name] = new_name
+        out.append(new_name)
+    return tuple(out)
+
+
+def _anonymise_const(
+    const: object,
+    mapping: ObfuscationMapping,
+    depth: int,
+    depth_counter: dict[int, int],
+) -> object:
+    """Recursively rewrite a ``co_consts`` entry.
+
+    * Strings become ``_sN`` (interned across the whole code-object
+      tree so equal strings get the same anonymised name).
+    * Tuples / frozensets are remapped element-by-element so they
+      remain hashable.
+    * Nested :class:`CodeType` objects are recursively anonymised.
+    * Numbers, bytes, ``None``, ``True``, ``False``, ``Ellipsis`` are
+      preserved (the LLM cannot infer source identity from a numeric
+      literal that the rule pass also sees verbatim).
+    """
+    if isinstance(const, str):
+        if const in mapping.consts:
+            return mapping.consts[const]
+        new = f"_s{len(mapping.consts)}"
+        mapping.consts[const] = new
+        return new
+    if isinstance(const, tuple):
+        return tuple(
+            _anonymise_const(item, mapping, depth, depth_counter) for item in const
+        )
+    if isinstance(const, frozenset):
+        return frozenset(
+            _anonymise_const(item, mapping, depth, depth_counter) for item in const
+        )
+    if isinstance(const, CodeType):
+        return _anonymise_code(const, mapping, depth + 1, depth_counter)
+    # int / float / complex / bool / None / bytes / Ellipsis: keep.
+    return const
+
+
+def _empty_lineinfo() -> bytes:
+    return b""
+
+
+def _anonymise_code(
+    code: CodeType,
+    mapping: ObfuscationMapping,
+    depth: int,
+    depth_counter: dict[int, int],
+) -> CodeType:
+    """Return a new :class:`CodeType` with anonymised identifiers."""
+    # Identifier tuples.
+    new_names = _anonymise_tuple(code.co_names, "n", mapping.names)
+    new_varnames = _anonymise_tuple(code.co_varnames, "v", mapping.varnames)
+    new_freevars = _anonymise_tuple(code.co_freevars, "f", mapping.freevars)
+    new_cellvars = _anonymise_tuple(code.co_cellvars, "c", mapping.cellvars)
+
+    # Constants (recursive).
+    new_consts = tuple(
+        _anonymise_const(c, mapping, depth, depth_counter) for c in code.co_consts
+    )
+
+    # Per-depth function name counter — ``_fn0`` at depth 0,
+    # ``_fn1, _fn2, …`` for nested defs.
+    n_at_depth = depth_counter.setdefault(depth, 0)
+    new_co_name = f"_fn{depth}_{n_at_depth}"
+    depth_counter[depth] = n_at_depth + 1
+    mapping.co_names[code.co_name] = new_co_name
+
+    # First do the always-supported rewrite. The remaining kwargs are
+    # version-conditional and applied via a second ``replace`` call so
+    # we keep the strict signature of the first call for the type
+    # checker while still letting older interpreters skip kwargs they
+    # do not accept.
+    new_code = code.replace(
+        co_names=new_names,
+        co_varnames=new_varnames,
+        co_freevars=new_freevars,
+        co_cellvars=new_cellvars,
+        co_consts=new_consts,
+        co_name=new_co_name,
+        co_filename=_ANON_FILENAME,
+        co_firstlineno=1,
+    )
+    # Optional fields. Each ``replace`` returns a fresh CodeType, so
+    # chaining is fine.
+    if hasattr(new_code, "co_qualname"):
+        new_code = new_code.replace(co_qualname=new_co_name)
+    if hasattr(new_code, "co_linetable"):
+        # 3.11+ uses ``co_linetable`` as the canonical line table.
+        new_code = new_code.replace(co_linetable=_empty_lineinfo())
+    # On 3.10 and earlier, ``co_lnotab`` is the canonical line table.
+    # We suppress the deprecation warning that ``hasattr(code,
+    # "co_lnotab")`` raises on 3.11+ where the attribute is now a
+    # read-only alias and ``replace()`` no longer accepts the kwarg.
+    import sys as _sys
+    import warnings as _warnings
+
+    if _sys.version_info < (3, 11):
+        with _warnings.catch_warnings():
+            _warnings.simplefilter("ignore", DeprecationWarning)
+            if hasattr(new_code, "co_lnotab"):
+                new_code = new_code.replace(co_lnotab=_empty_lineinfo())
+    # ``co_exceptiontable`` (3.11+) carries try/except metadata; the
+    # opcode stream still needs valid handler offsets so we leave it
+    # alone. ``co_positions`` is computed lazily from co_linetable so
+    # zeroing the table is enough.
+    return new_code
+
+
+def anonymise(code: CodeType) -> tuple[CodeType, ObfuscationMapping]:
+    """Public entry point: anonymise a top-level code object."""
+    mapping = ObfuscationMapping()
+    new_code = _anonymise_code(code, mapping, depth=0, depth_counter={})
+    return new_code, mapping
+
+
+__all__ = ["ObfuscationMapping", "anonymise"]

pychd_pyobf-0.1.0/pychd_pyobf/rewrite_subprocess.py

@@ -0,0 +1,243 @@
+"""Cross-version .pyc anonymiser via subprocess into the target Python.
+
+The native rewriter (``rewrite_native``) only works for .pyc files
+produced by the currently-running interpreter — ``types.CodeType``
+internals (e.g. ``co_qualname`` availability, exception-table layout
+on 3.11+, the older ``co_lnotab`` shape on 3.10-) differ across
+minors and the ``replace`` kwarg surface must match.
+
+To stay version-agnostic without re-implementing every layout, this
+module spawns the *writer*'s Python interpreter under ``uv run
+--python 3.X --no-project python -c "<snippet>"`` and runs the same
+``marshal.loads → recursive replace → marshal.dumps`` dance inside
+that subprocess. The snippet is the multi-line string at the bottom
+of this file, kept as a plain ``str`` so it is easy to read and
+review.
+
+Constraints:
+
+* Communication is via three file-paths passed on argv (input .pyc,
+  output .pyc, mapping JSON). No piping marshalled bytes through
+  stdin/stdout — keeps the snippet trivial and avoids encoding
+  issues across 3.x.
+* ``uv`` is the only required tooling — it manages downloading the
+  target Python on first run via python-build-standalone. Hosts
+  without uv get a clear ``FileNotFoundError`` instead of a
+  baffling ``subprocess`` traceback.
+* 30-second wall-clock timeout per call, matching the cross-version
+  fixture builder (``tools/build_multiversion_fixtures.py``).
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+from pathlib import Path
+
+from .rewrite_native import ObfuscationMapping
+
+
+def _snippet() -> str:
+    """Return the subprocess script as a single-string ``-c`` body.
+
+    The snippet uses only standard library modules available in every
+    Python 3.x release (``marshal`` / ``types`` / ``json`` / ``sys``)
+    so we do not need to install anything inside the target venv.
+    """
+    return r"""
+import json
+import marshal
+import sys
+from pathlib import Path
+
+# argv layout: in_pyc, out_pyc, mapping_json, header_len
+in_pyc = Path(sys.argv[1])
+out_pyc = Path(sys.argv[2])
+mapping_path = Path(sys.argv[3])
+header_len = int(sys.argv[4])
+
+data = in_pyc.read_bytes()
+header = data[:header_len]
+body = data[header_len:]
+code = marshal.loads(body)
+
+mapping = {
+    "names": {},
+    "varnames": {},
+    "freevars": {},
+    "cellvars": {},
+    "consts": {},
+    "co_names": {},
+}
+
+
+def _anon_tuple(seq, prefix, table):
+    # Use the global size of *table* as the suffix counter so two
+    # distinct code objects with the same per-tuple index 0 do not
+    # both claim "_<prefix>0" — that produces duplicate-arg bugs in
+    # the anonymised source.
+    out = []
+    for name in seq:
+        if name in table:
+            out.append(table[name])
+            continue
+        new = "_" + prefix + str(len(table))
+        table[name] = new
+        out.append(new)
+    return tuple(out)
+
+
+def _anon_const(c):
+    if isinstance(c, str):
+        if c in mapping["consts"]:
+            return mapping["consts"][c]
+        new = "_s" + str(len(mapping["consts"]))
+        mapping["consts"][c] = new
+        return new
+    if isinstance(c, tuple):
+        return tuple(_anon_const(item) for item in c)
+    if isinstance(c, frozenset):
+        return frozenset(_anon_const(item) for item in c)
+    if type(c).__name__ == "code":  # CodeType
+        return _anon_code(c, depth + 1)  # noqa: F821 — depth bound at outer scope
+    return c
+
+
+_depth_counters = {}
+
+
+def _anon_code(code, depth):
+    # NOTE: ``_anon_const`` references ``depth`` via closure on each
+    # entry to ``_anon_code`` — we rebind it at each level by
+    # assigning a fresh inner function. This keeps the script under
+    # 60 LOC and avoids passing depth through the const recursion.
+    global _anon_const
+
+    def _anon_const(c, _d=depth):
+        if isinstance(c, str):
+            if c in mapping["consts"]:
+                return mapping["consts"][c]
+            new = "_s" + str(len(mapping["consts"]))
+            mapping["consts"][c] = new
+            return new
+        if isinstance(c, tuple):
+            return tuple(_anon_const(item) for item in c)
+        if isinstance(c, frozenset):
+            return frozenset(_anon_const(item) for item in c)
+        if type(c).__name__ == "code":
+            return _anon_code(c, _d + 1)
+        return c
+
+    new_names = _anon_tuple(code.co_names, "n", mapping["names"])
+    new_varnames = _anon_tuple(code.co_varnames, "v", mapping["varnames"])
+    new_freevars = _anon_tuple(code.co_freevars, "f", mapping["freevars"])
+    new_cellvars = _anon_tuple(code.co_cellvars, "c", mapping["cellvars"])
+
+    new_consts = tuple(_anon_const(c) for c in code.co_consts)
+
+    n_at_depth = _depth_counters.get(depth, 0)
+    new_co_name = "_fn" + str(depth) + "_" + str(n_at_depth)
+    _depth_counters[depth] = n_at_depth + 1
+    mapping["co_names"][code.co_name] = new_co_name
+
+    kwargs = dict(
+        co_names=new_names,
+        co_varnames=new_varnames,
+        co_freevars=new_freevars,
+        co_cellvars=new_cellvars,
+        co_consts=new_consts,
+        co_name=new_co_name,
+        co_filename="<anonymised>",
+        co_firstlineno=1,
+    )
+    if hasattr(code, "co_qualname"):
+        kwargs["co_qualname"] = new_co_name
+    if hasattr(code, "co_linetable"):
+        kwargs["co_linetable"] = b""
+    # co_lnotab is the line-table kwarg only on 3.10 and earlier; on
+    # 3.11+ it exists as a deprecated read-only alias and code.replace
+    # rejects it.
+    if hasattr(code, "co_lnotab") and sys.version_info < (3, 11):
+        kwargs["co_lnotab"] = b""
+    return code.replace(**kwargs)
+
+
+new_code = _anon_code(code, 0)
+new_body = marshal.dumps(new_code)
+out_pyc.write_bytes(header + new_body)
+mapping_path.write_text(json.dumps(mapping))
+"""
+
+
+def run_subprocess_rewrite(
+    target_python: str,
+    in_pyc: Path,
+    out_pyc: Path,
+    header_len: int,
+    *,
+    timeout: float = 30.0,
+) -> ObfuscationMapping:
+    """Spawn *target_python* and rewrite *in_pyc* into *out_pyc*.
+
+    *target_python* is the command/path that, when executed, runs the
+    correct Python minor. The standard form on this repo is
+    ``uv run --python 3.X --no-project python`` — call sites pass
+    that as a single string (or a list joined with spaces) and the
+    function dispatches via ``shlex`` if necessary.
+
+    The mapping JSON is written to a temp file next to *out_pyc* and
+    parsed back here so the caller receives a fully-populated
+    :class:`ObfuscationMapping`.
+    """
+    import shlex
+    import tempfile
+
+    out_pyc.parent.mkdir(parents=True, exist_ok=True)
+    with tempfile.NamedTemporaryFile(
+        prefix="pyobf-map-", suffix=".json", delete=False
+    ) as fh:
+        mapping_path = Path(fh.name)
+    cmd = shlex.split(target_python) + [
+        "-c",
+        _snippet(),
+        str(in_pyc),
+        str(out_pyc),
+        str(mapping_path),
+        str(header_len),
+    ]
+    proc = subprocess.run(
+        cmd,
+        capture_output=True,
+        text=True,
+        timeout=timeout,
+    )
+    if proc.returncode != 0:
+        mapping_path.unlink(missing_ok=True)
+        raise RuntimeError(
+            f"pyobf subprocess (cmd={cmd[:4]!r}) failed: "
+            f"rc={proc.returncode}, stderr={proc.stderr!r}"
+        )
+    raw = json.loads(mapping_path.read_text())
+    mapping_path.unlink(missing_ok=True)
+    om = ObfuscationMapping()
+    om.names.update(raw["names"])
+    om.varnames.update(raw["varnames"])
+    om.freevars.update(raw["freevars"])
+    om.cellvars.update(raw["cellvars"])
+    om.consts.update(raw["consts"])
+    om.co_names.update(raw["co_names"])
+    return om
+
+
+def uv_run_command(version: tuple[int, int]) -> str:
+    """Return the ``uv``-mediated command string that runs the target
+    Python without any project dependencies.
+
+    Centralised here so the dispatcher and the eval-harness both call
+    it the same way (and so the test suite can monkey-patch it when
+    running offline).
+    """
+    return f"uv run --python {version[0]}.{version[1]} --no-project python"
+
+
+__all__ = ["run_subprocess_rewrite", "uv_run_command"]

pychd_pyobf-0.1.0/pyproject.toml

@@ -0,0 +1,26 @@
+[project]
+name = "pychd-pyobf"
+version = "0.1.0"
+description = "Anonymise identifiers / constants / metadata inside a CPython .pyc while preserving the opcode stream — for contamination-free decompiler benchmarking"
+readme = "README.md"
+authors = [
+    { name = "卍diohabara卍", email = "diohabara@users.noreply.github.com" }
+]
+dependencies = [
+    # We reuse ``pychd.versions.detect_version`` to identify the .pyc
+    # magic number. xdis is a transitive dependency through pychd but we
+    # do not import it directly — the cross-version rewrite delegates to
+    # a subprocess running the target Python.
+    "pychd>=1.2.0",
+]
+requires-python = ">= 3.14"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project.scripts]
+pychd-pyobf = "pychd_pyobf.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["pychd_pyobf"]