Metadata-Version: 2.5
Name: pyassembler
Version: 0.1.0
Summary: Ultra-fast hardware compiler by Ilya
Author-email: Ilya <iliaiva2015@yandex.ru>
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: C++
Classifier: Topic :: Software Development :: Compilers
License-File: LICENSE
Import-Name: pyassembler

# 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:
```bash
pip install .
```

## 🕹️ Quick Start
Here is how you can use `pyassembler` to run hardware-level calculations using CPU stack pushes and pops:

```python
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](LICENSE) file for details.

