xasm 1.2.1__py312-none-any.whl

xasm/pyc_convert.py

@@ -0,0 +1,259 @@
+#!/usr/bin/env python
+"""Convert Python Bytecode from one version to another for
+some limited set of Python bytecode versions
+"""
+import os
+import os.path as osp
+from copy import copy
+from tempfile import NamedTemporaryFile
+
+import click
+import xdis
+from xdis import disassemble_file, load_module, magic2int, write_bytecode_file
+from xdis.magics import magics
+from xdis.opcodes import opcode_27, opcode_33
+
+from xasm.assemble import (
+    Assembler,
+    Instruction,
+    asm_file,
+    create_code,
+    decode_lineno_tab_old,
+)
+from xasm.version import __version__
+from xasm.write_pyc import write_pycfile
+
+
+def add_credit(asm, src_version, dest_version) -> None:
+    stamp = "Converted from Python %s to %s by %s version %s" % (
+        src_version,
+        dest_version,
+        "pyc-convert",
+        __version__,
+    )
+    asm.codes[-1].co_consts = list(asm.codes[-1].co_consts).append(stamp)
+    return
+
+
+def copy_magic_into_pyc(input_pyc, output_pyc, src_version, dest_version) -> None:
+    """Bytecodes are the same except the magic number, so just change
+    that"""
+    (version, timestamp, magic_int, co, is_pypy, source_size) = load_module(input_pyc)
+    assert version == float(
+        src_version
+    ), f"Need Python {src_version} bytecode; got bytecode for version {version}"
+    magic_int = magic2int(magics.magics[dest_version])
+    write_bytecode_file(output_pyc, co, magic_int)
+    print(f"Wrote {output_pyc}")
+    return
+
+
+def xlate26_27(inst) -> None:
+    """Between 2.6 and 2.7 opcode values changed
+    Adjust for the differences by using the opcode name
+    """
+    inst.opcode = opcode_27.opmap[inst.opname]
+
+
+def conversion_to_version(conversion_type, is_dest=False):
+    if is_dest:
+        return conversion_type[-2] + "." + conversion_type[-1]
+    else:
+        return conversion_type[0] + "." + conversion_type[1]
+
+
+def transform_26_27(inst, new_inst, i, n, offset, instructions, new_asm):
+    """Change JUMP_IF_FALSE and JUMP_IF_TRUE to
+    POP_JUMP_IF_FALSE and POP_JUMP_IF_TRUE"""
+    if inst.opname in ("JUMP_IF_FALSE", "JUMP_IF_TRUE"):
+        i += 1
+        assert i < n
+        assert instructions[i].opname == "POP_TOP"
+        new_inst.offset = offset
+        new_inst.opname = (
+            "POP_JUMP_IF_FALSE"
+            if inst.opname == "JUMP_IF_FALSE"
+            else "POP_JUMP_IF_TRUE"
+        )
+        new_asm.backpatch[-1].remove(inst)
+        new_inst.arg = "L%d" % (inst.offset + inst.arg + 3)
+        new_asm.backpatch[-1].add(new_inst)
+    else:
+        xlate26_27(new_inst)
+    return xdis.op_size(new_inst.opcode, opcode_27)
+
+
+def transform_32_33(inst, new_inst, i, n, offset, instructions, new_asm):
+    """MAKE_FUNCTION adds another const. probably MAKE_CLASS as well"""
+    add_size = xdis.op_size(new_inst.opcode, opcode_33)
+    if inst.opname in ("MAKE_FUNCTION", "MAKE_CLOSURE"):
+        # Previous instruction should be a load const which
+        # contains the name of the function to call
+        prev_inst = instructions[i - 1]
+        assert prev_inst.opname == "LOAD_CONST"
+        assert isinstance(prev_inst.arg, int)
+
+        # Add the function name as an additional LOAD_CONST
+        load_fn_const = Instruction()
+        load_fn_const.opname = "LOAD_CONST"
+        load_fn_const.opcode = opcode_33.opmap["LOAD_CONST"]
+        load_fn_const.line_no = None
+        prev_const = new_asm.code.co_consts[prev_inst.arg]
+        if hasattr(prev_const, "co_name"):
+            fn_name = new_asm.code.co_consts[prev_inst.arg].co_name
+        else:
+            fn_name = "what-is-up"
+        const_index = len(new_asm.code.co_consts)
+        new_asm.code.co_consts = list(new_asm.code.co_consts)
+        new_asm.code.co_consts.append(fn_name)
+        load_fn_const.arg = const_index
+        load_fn_const.offset = offset
+        load_fn_const.starts_line = False
+        load_fn_const.is_jump_target = False
+        new_asm.code.instructions.append(load_fn_const)
+        load_const_size = xdis.op_size(load_fn_const.opcode, opcode_33)
+        add_size += load_const_size
+        new_inst.offset = offset + add_size
+        pass
+    return add_size
+
+
+def transform_33_32(inst, new_inst, i, n, offset, instructions, new_asm):
+    """MAKE_FUNCTION, and MAKE_CLOSURE have an additional LOAD_CONST of a name
+    that are not in Python 3.2. Remove these.
+    """
+    add_size = xdis.op_size(new_inst.opcode, opcode_33)
+    if inst.opname in ("MAKE_FUNCTION", "MAKE_CLOSURE"):
+        # Previous instruction should be a load const which
+        # contains the name of the function to call
+        prev_inst = instructions[i - 1]
+        assert prev_inst.opname == "LOAD_CONST"
+        assert isinstance(prev_inst.arg, int)
+        assert len(instructions) > 2
+        assert len(instructions) > 2
+        prev_inst2 = instructions[i - 2]
+        assert prev_inst2.opname == "LOAD_CONST"
+        assert isinstance(prev_inst2.arg, int)
+
+        # Remove the function name as an additional LOAD_CONST
+        prev2_const = new_asm.code.co_consts[prev_inst.arg]
+        assert hasattr(prev2_const, "co_name")
+        new_asm.code.instructions = new_asm.code.instructions[:-1]
+        load_const_size = xdis.op_size(prev_inst.opcode, opcode_33)
+        add_size -= load_const_size
+        new_inst.offset = offset - add_size
+        return -load_const_size
+    return 0
+
+
+def transform_asm(
+    asm: Assembler | None, conversion_type, src_version, dest_version
+) -> Assembler:
+    new_asm = Assembler(dest_version, is_pypy=False)
+    for field in "code size".split():
+        setattr(new_asm, field, copy(getattr(asm, field)))
+
+    if conversion_type == "26-27":
+        transform_fn = transform_26_27
+    elif conversion_type == "32-33":
+        transform_fn = transform_32_33
+    elif conversion_type == "33-32":
+        transform_fn = transform_33_32
+    else:
+        raise RuntimeError(f"Don't know how to convert {conversion_type} ")
+    for j, code in enumerate(asm.code_list):
+        offset2label = {v: k for k, v in asm.label[j].items()}
+        new_asm.backpatch.append(copy(asm.backpatch[j]))
+        new_asm.label.append(copy(asm.label[j]))
+        new_asm.codes.append(copy(code))
+        new_asm.code.co_lnotab = decode_lineno_tab_old(
+            code.co_lnotab, code.co_firstlineno
+        )
+        instructions = asm.codes[j].instructions
+        new_asm.code.instructions = []
+        i, offset, n = 0, 0, len(instructions)
+        while i < n:
+            inst = instructions[i]
+            new_inst = copy(inst)
+            inst_size = transform_fn(
+                inst, new_inst, i, offset, n, instructions, new_asm
+            )
+            if inst.offset in offset2label:
+                new_asm.label[-1][offset2label[inst.offset]] = offset
+                pass
+            offset += inst_size
+            new_asm.code.instructions.append(new_inst)
+            i += 1
+            pass
+
+    co, is_valid = create_code(new_asm, new_asm.label[-1], new_asm.backpatch[-1])
+    new_asm.code_list.append(co)
+    new_asm.code_list.reverse()
+    new_asm.status = "finished" if is_valid else "invalid"
+    return new_asm
+
+
+UPWARD_COMPATIBLE = tuple("20-21 21-22 23-24 24-23".split())
+
+
+@click.command()
+@click.option(
+    "--conversion-type",
+    "-t",
+    type=click.Choice(
+        [
+            "20-21",
+            "21-22",
+            "23-24",
+            "24-23",
+            "24-25",
+            "25-26",
+            "26-27",
+            "32-33",
+            "33-32",
+        ]
+    ),
+    help="specify conversion from/to bytecode",
+    default="26-27",
+)
+@click.argument("input_pyc", type=click.Path(writable=True), nargs=1)
+@click.argument(
+    "output_pyc", type=click.Path(writable=True), required=False, nargs=1, default=None
+)
+def main(conversion_type, input_pyc, output_pyc) -> None:
+    """Convert Python bytecode from one version to another.
+
+    INPUT_PYC contains the input bytecode path name
+    OUTPUT_PYC  contains the output bytecode path name if supplied
+    The --conversion type option specifies what conversion to do.
+
+    Note: there are a very limited set of conversions currently supported.
+    Help out and write more!"""
+
+    shortname = osp.basename(input_pyc)
+    if shortname.endswith(".pyc"):
+        shortname = shortname[:-4]
+    src_version = conversion_to_version(conversion_type, is_dest=False)
+    dest_version = conversion_to_version(conversion_type, is_dest=True)
+    if output_pyc is None:
+        output_pyc = f"{shortname}-{dest_version}.pyc"
+
+    if conversion_type in UPWARD_COMPATIBLE:
+        copy_magic_into_pyc(input_pyc, output_pyc, src_version, dest_version)
+        return
+    temp_asm = NamedTemporaryFile("w", suffix=".pyasm", prefix=shortname, delete=False)
+    (filename, co, version, timestamp, magic_int) = disassemble_file(
+        input_pyc, temp_asm, asm_format=True
+    )
+    temp_asm.close()
+    assert version == float(
+        src_version
+    ), f"Need Python {src_version} bytecode; got bytecode for version {version}"
+    asm = asm_file(temp_asm.name)
+    new_asm = transform_asm(asm, conversion_type, src_version, dest_version)
+    os.unlink(temp_asm.name)
+    write_pycfile(output_pyc, new_asm)
+
+
+if __name__ == "__main__":
+    main()

xasm/version.py

@@ -0,0 +1,8 @@
+# -*- coding: utf-8 -*-
+
+# This file is suitable for sourcing inside POSIX shell as
+# well as importing into Python. That's why there is no
+# space around "=" below.
+
+# fmt: off
+__version__="1.2.1"  # noqa

xasm/write_pyc.py

@@ -0,0 +1,48 @@
+import time
+from struct import pack
+
+import xdis
+from xdis import magic2int
+from xdis.magics import magics
+from xdis.marsh import dumps
+from xdis.version_info import PYTHON3, version_tuple_to_str
+
+
+def write_pycfile(fp, code_list, timestamp=None, version_triple=xdis.PYTHON_VERSION_TRIPLE) -> int:
+
+    rc = 0
+    version_str = version_tuple_to_str(version_triple, end=2)
+    magic_bytes = magics[version_str]
+    magic_int = magic2int(magic_bytes)
+    fp.write(magic_bytes)
+
+    if timestamp is None:
+        timestamp = int(time.time())
+    write_source_size = version_triple >= (3, 3)
+    if version_triple >= (3, 7):
+        if magic_int == 3393:
+            fp.write(pack("I", timestamp))
+            fp.write(pack("I", 0))
+        else:
+            # PEP 552. https://www.python.org/dev/peps/pep-0552/
+            # 0 in the lowest-order bit means used old-style timestamps
+            fp.write(pack("<I", 0))
+            fp.write(pack("<I", timestamp))
+    else:
+        fp.write(pack("<I", timestamp))
+
+    if write_source_size:
+        fp.write(pack("<I", 0))  # size mod 2**32
+
+    for co in code_list:
+        try:
+            co_obj = dumps(co, python_version=version_triple)
+            if PYTHON3 and version_triple < (3, 0):
+                co_obj = str.encode(co_obj)
+                pass
+
+            fp.write(co_obj)
+        except Exception as e:
+            print(f"error dumping {co}: {e}; ignoring")
+            rc = 1
+    return rc

xasm/xasm_cli.py

@@ -0,0 +1,61 @@
+#!/usr/bin/env python
+import os
+import sys
+from typing import List
+
+import click
+import xdis
+from xdis.version_info import version_tuple_to_str
+
+from xasm.assemble import asm_file
+from xasm.write_pyc import write_pycfile
+
+
+@click.command()
+@click.option("--pyc-file", default=None)
+@click.argument("asm-path", type=click.Path(exists=True, readable=True), required=True)
+def main(pyc_file: List[str], asm_path):
+    """
+    Create Python bytecode from a Python assembly file.
+
+    ASM_PATH gives the input Python assembly file. We suggest ending the
+    file in .pyc
+
+    If --pyc-file is given, that indicates the path to write the
+    Python bytecode. The path should end in '.pyc'.
+
+    See https://github.com/rocky/python-xasm/blob/master/HOW-TO-USE.rst
+    for how to write a Python assembler file.
+    """
+    if os.stat(asm_path).st_size == 0:
+        print(f"Size of assembly file {asm_path} is zero")
+        sys.exit(1)
+    asm = asm_file(asm_path)
+
+    if not pyc_file:
+        if asm_path.endswith(".pyasm"):
+            pyc_file = asm_path[: -len(".pyasm")] + ".pyc"
+        elif not pyc_file and asm_path.endswith(".xasm"):
+            pyc_file = asm_path[: -len(".xasm")] + ".pyc"
+
+    if xdis.PYTHON3:
+        file_mode = "wb"
+    else:
+        file_mode = "w"
+
+    with open(pyc_file, file_mode) as fp:
+        rc = write_pycfile(fp, asm.code_list, asm.timestamp, asm.python_version)
+        size = fp.tell()
+    print(
+        f"""Wrote Python {version_tuple_to_str(asm.python_version)} bytecode file "{pyc_file}"; {size} bytes."""
+    )
+    if size <= 16:
+        print("Warning: bytecode file is too small to be usable.")
+        rc = 2
+    if rc != 0:
+        print(f"Exiting with return code {rc}")
+    sys.exit(rc)
+
+
+if __name__ == "__main__":
+    main(sys.argv[1:])

xasm-1.2.1.dist-info/METADATA

@@ -0,0 +1,233 @@
+Metadata-Version: 2.4
+Name: xasm
+Version: 1.2.1
+Summary: Cross-version Python bytecode assembler
+Author-email: Rocky Bernstein <rb@dustyfeet.com>
+License-Expression: GPL-2.0
+Project-URL: Homepage, https://github.com/rocky/python-xasm
+Project-URL: Downloads, https://github.com/rocky/python-xasm/releases
+Keywords: Python bytecode,bytecode,disassembler
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Programming Language :: Python :: 3.8
+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: Topic :: Software Development :: Code Generators
+Description-Content-Type: text/x-rst
+License-File: LICENSE.gpl2
+Requires-Dist: click
+Requires-Dist: xdis<6.3.0,>=6.1.1
+Provides-Extra: dev
+Requires-Dist: pre-commit; extra == "dev"
+Requires-Dist: black; extra == "dev"
+Requires-Dist: isort; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Dynamic: license-file
+
+|Pypi Installs| |Latest Version| |Supported Python Versions|
+
+xasm
+====
+
+*NOTE: this is in beta.*
+
+A cross-version Python bytecode assembler
+
+
+Introduction
+------------
+
+The Python ``xasm`` module has routines for assembly, and has a command to
+assemble bytecode for several different versions of Python.
+
+Here are some potential uses:
+
+* Make small changes to existing Python bytecode when you don’t have source
+* Craft custom and efficient bytecode
+* Write an instruction-level optimizing compiler
+* Experiment with and learn about Python bytecode
+* Foil decompilers like uncompyle6_ so that they can’t disassemble bytecode (at least for now)
+
+This support the same kinds of bytecode that xdis_ supports. This is
+pretty much all released bytecode before Python 3.11. We tend to lag behind the
+latest Python releases.
+
+The code requires Python 3.6 or later.
+
+Assembly files
+--------------
+
+See how-to-use_ for more detail. Some general some principles:
+
+* Preferred extension for Python assembly is ``.pyasm``
+* assembly is designed to work with the output of ``pydisasm -F xasm``
+* Assembly file labels are at the beginning of the line
+  and end in a colon, e.g. ``END_IF:``
+* instruction offsets in the assembly file are ignored and don't need
+  to be entered
+* in those instructions that refer to offsets, if the if the
+  operand is an int, exactly that value will be used for the operand. Otherwise
+  we will look for labels and match up with that
+
+
+Installation
+------------
+
+*If you are using Python 3.11 or later*, you can install from PyPI using the name ``xasm``::
+
+    pip install xasm
+
+A GNU makefile is also provided so ``make install`` (possibly as root or
+sudo) will do the steps above.
+
+
+*If you are using Python before 3.11*, do not install using PyPI, but instead install using a file in the `GitHub Releases section <https://github.com/rocky/python-xasm/releases>`_. Older Python used to use `easy_install <https://python101.pythonlibrary.org/chapter29_pip.html#using-easy-install>`_. But this is no longer supported in PyPi or newer Python versions. And vice versa, *poetry* nor *pip*, (the newer ways) are not supported on older Pythons.
+
+If the Python version you are running xasm is between Python 3.6 through 3.11, use a tarball called xasm_36-*x.y.z*.tar.gz.
+
+If the Python version you are running xasm is 3.11 or later, use a file called xasm-*x.y.z*.tar.gz.
+
+Similarly, a tarball with or without the underscore *xx*,  e.g., xasm_36-*x.y.z*.tar.gz. works only from Python 3.11 or greater.
+
+Rationale for using Git Branches
+++++++++++++++++++++++++++++++++
+
+It is currently impossible (if not impractical) to have one Python source code of this complexity and with this many features that can run both Python 3.6 and Python 3.13+. The languages have drifted so much, and packaging is vastly different.
+
+A GNU makefile is also provided so :code:`make install` (possibly as root or sudo) will do the steps above.
+
+
+Testing
+-------
+
+::
+
+   make check
+
+A GNU makefile has been added to smooth over setting running the right
+command, and running tests from fastest to slowest.
+
+If you have remake_ installed, you can see the list of all tasks
+including tests via :code:`remake --tasks`.
+
+
+Example Assembly File
+---------------------
+
+For this Python source code:
+
+::
+
+    def five():
+        return 5
+
+    print(five())
+
+Here is an assembly for the above:
+
+::
+
+    # Python bytecode 3.6 (3379)
+
+    # Method Name:       five
+    # Filename:          /tmp/five.pl
+    # Argument count:    0
+    # Kw-only arguments: 0
+    # Number of locals:  0
+    # Stack size:        1
+    # Flags:             0x00000043 (NOFREE | NEWLOCALS | OPTIMIZED)
+    # First Line:        1
+    # Constants:
+    #    0: None
+    #    1: 5
+      2:
+                LOAD_CONST           (5)
+                RETURN_VALUE
+
+
+    # Method Name:       <module>
+    # Filename:          /tmp/five.pl
+    # Argument count:    0
+    # Kw-only arguments: 0
+    # Number of locals:  0
+    # Stack size:        2
+    # Flags:             0x00000040 (NOFREE)
+    # First Line:        1
+    # Constants:
+    #    0: <code object five at 0x0000>
+    #    1: 'five'
+    #    2: None
+    # Names:
+    #    0: five
+    #    1: print
+      1:
+                LOAD_CONST           0 (<code object five at 0x0000>)
+                LOAD_CONST           ('five')
+                MAKE_FUNCTION        0
+                STORE_NAME           (five)
+
+      3:
+                LOAD_NAME            (print)
+                LOAD_NAME            (five)
+                CALL_FUNCTION        0
+                CALL_FUNCTION        1
+                POP_TOP
+                LOAD_CONST           (None)
+                RETURN_VALUE
+
+
+The above can be created automatically from Python source code using the ``pydisasm``
+command from ``xdis``:
+
+::
+
+    pydisasm --format xasm /tmp/five.pyc
+
+In the example above though, I have shortened and simplified the result.
+
+
+Usage
+-----
+
+To create a python bytecode file from an assemble file, run:
+
+::
+
+   pyc-xasm [OPTIONS] ASM_PATH
+
+
+For usage help, type:  ``pyc-xasm --help``.
+
+
+To convert a python bytecode from one bytecode to another, run:
+
+::
+
+   pyc-convert [OPTIONS] INPUT_PYC [OUTPUT_PYC]
+
+
+For usage help, type:  ``pyc-convert --help``.
+
+
+See Also
+--------
+
+* https://github.com/rocky/python-xdis : Cross Python version disassemble
+* https://github.com/rocky/x-python : Cross Python version interpreter
+* https://github.com/rocky/python-xasm/blob/master/HOW-TO-USE.rst : How to write an assembler file
+* https://rocky.github.io/pycon2018-light.co/ : Pycolumbia 2018 Lightning talk showing how to use the assembler
+
+
+.. _uncompyle6: https://github.com/rocky/python-uncompyle6
+.. _how-to-use: https://github.com/rocky/python-xasm/blob/master/HOW-TO-USE.rst
+.. _xdis: https://github.com/rocky/xdis
+.. |Latest Version| image:: https://badge.fury.io/py/xasm.svg
+		 :target: https://badge.fury.io/py/xasm
+.. |Pypi Installs| image:: https://pepy.tech/badge/xasm
+.. |Supported Python Versions| image:: https://img.shields.io/pypi/pyversions/xasm.svg
+.. _remake: http://bashdb.sf.net/remake

xasm-1.2.1.dist-info/RECORD

@@ -0,0 +1,13 @@
+xasm/.gitignore,sha256=4M-0eEErWDaEphX2OA2Bsp72_sUTUkrs1LXr70HkItw,30
+xasm/__init__.py,sha256=gz94OZ_Jc1WozfOYH1pjQeg7IgB1L9wv5fyytJ2XgZU,174
+xasm/assemble.py,sha256=0l_0AlsQL2Pwp4ZAR8ucdC6CKnNjeZACc5pD6GORFis,26442
+xasm/pyc_convert.py,sha256=s2UixbgUQZFHv9nmtvOV7TYohLBev2lcet0GIE9g6GM,9177
+xasm/version.py,sha256=xEuuftKJb_Pe2D5lJpTv3HxDgx6Bd1-lH_6HBGWFguw,206
+xasm/write_pyc.py,sha256=ZoqjupN9rEjJ5o49SZcX9rbEhaImnqsJKkNzLnT9j4c,1455
+xasm/xasm_cli.py,sha256=4EYRZVejspzBvoNaXsWgGbN7qRU5p-MPrt05IYu1kGc,1789
+xasm-1.2.1.dist-info/licenses/LICENSE.gpl2,sha256=2ylvL381vKOhdO-w6zkrOxe9lLNBhRQpo9_0EbHC_HM,18046
+xasm-1.2.1.dist-info/METADATA,sha256=8iv_uKXBGELwvcM1oLGQRciIftEK9gcG0cqM3Is_mfM,7334
+xasm-1.2.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+xasm-1.2.1.dist-info/entry_points.txt,sha256=3NCzOsGwLI-kMOKN72-joKrVjz8DAjHdw7aZof31A2E,50
+xasm-1.2.1.dist-info/top_level.txt,sha256=24UNOItB5o_EJoJ9nqhPZEC5GiSaYtHll3F6mJXzOkA,5
+xasm-1.2.1.dist-info/RECORD,,

xasm-1.2.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

xasm-1.2.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+python-cfg = xasm.__main__:main