pyassembler

🚀 The ultimate dynamic compiler by Ilya.

pyassembler is an ultra-fast, zero-overhead hardware JIT bridge that allows you to execute raw x86-64 machine code bytes directly inside the CPU transistors straight from Python! 🪐💻

🔥 Features

• Zero Overhead: Completely bypasses the Python interpreter slows by executing machine code directly on the silicon!
• Win32 Kernel Integration: Dynamically allocates memory pages via low-level VirtualAlloc with PAGE_EXECUTE_READWRITE permissions.
• Hardware Register Control: Execute custom calculations directly in the RAX and RBX general-purpose registers.
• Enterprise Type Support: Fully equipped with pyassembler.pyi stub files and py.typed for flawless PyCharm autocomplete.
• Modern Packaging: Managed declaratively via pyproject.toml (PEP 621).

🛠️ Installation

To compile and install the 64-bit static binary directly into your virtual environment, simply run:

pip install .

🕹️ Quick Start

Here is how you can use pyassembler to run hardware-level calculations using CPU stack pushes and pops:

import pyassembler

print("=== Dynamic Hardware Calculation ===")

# Raw x86-64 machine instructions:
# 0x51          -> push rcx         (Save the array pointer to CPU stack)
# 0x48, 0xC7... -> mov rax, 500     (Load 500 into RAX)
# 0x48, 0x05... -> add rax, 300     (Add 300 directly inside the chip)
# 0x48, 0x83... -> sub rax, 23      (Subtract 23, resulting in 777)
# 0x59          -> pop rcx          (Restore the array pointer to RCX)
# 0x48, 0x89... -> mov [rcx], rax   (Safely dump the 777 result back into C-memory)
# 0xC3          -> ret              (Clean return back to Python)
machine_bytes = [
    0x51,
    0x48, 0xC7, 0xC0, 0xF4, 0x01, 0x00, 0x00,
    0x48, 0x05, 0x2C, 0x01, 0x00, 0x00,
    0x48, 0x83, 0xE8, 0x17,
    0x59,
    0x48, 0x89, 0x01,
    0xC3
]

# Fire up the engine!
cpu = pyassembler.RUN(machine_bytes)

print(f"📥 Result from RAX register: {cpu['R12']}")  # Outputs: 777

📜 License

This project is licensed under the MIT License - see the LICENSE file for details.