Metadata-Version: 2.4
Name: tsrkit-asm
Version: 0.1.0
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Rust
Classifier: Operating System :: OS Independent
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Summary: Python Bindings for Polkavm-Assembler, a Runtime assembler for PolkaVM
Keywords: polkadot,polkavm,assembler,blockchain,jam
Author-email: Jan Bujak <jan@parity.io>, Parity Technologies <admin@parity.io>, Prasad <prasad@chainscore.finance>, Chainscore Labs <hello@chainscore.finance>
License: MIT OR Apache-2.0
Requires-Python: >=3.12, <3.13
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Homepage, https://github.com/Chainscore/tsrkit-asm
Project-URL: Issues, https://github.com/Chainscore/tsrkit-asm/issues
Project-URL: Repository, https://github.com/Chainscore/tsrkit-asm

# TSRKit ASM: PolkaVM Assembler Python Bindings

Python bindings for the PolkaVM runtime assembler, providing high-performance x86-64 assembly generation capabilities.

## Features

- **Runtime Assembly Generation**: Generate x86-64 machine code at runtime
- **Label Support**: Forward declaration and resolution of jump/call targets
- **Full Instruction Set**: Support for common x86-64 instructions including:
  - Basic operations (NOP, RET, SYSCALL)
  - Register operations (PUSH, POP, MOV)
  - Arithmetic (ADD, SUB, AND, OR, XOR, CMP)
  - Control flow (JMP, CALL, conditional jumps)
- **Type Safety**: Complete type stubs for excellent IDE support
- **High Performance**: Built on Rust for maximum speed

## Installation

```bash
pip install tsrkit-asm
```

## Quick Start

```python
from tsrkit_asm import PyAssembler

# Create an assembler instance
asm = PyAssembler()

# Generate a simple function that adds two numbers
asm.mov_reg_imm64(py_asm.RAX, 42)
asm.mov_reg_imm64(py_asm.RBX, 13)
asm.add_reg_reg(64, py_asm.RAX, py_asm.RBX)
asm.ret()

# Get the machine code
machine_code = asm.finalize()
print(f"Generated {len(machine_code)} bytes of machine code")
```

## Advanced Usage

### Using Labels for Control Flow

```python
from tsrkit_asm import PyAssembler

asm = PyAssembler()

# Create labels for a loop
loop_start = asm.forward_declare_label()
loop_end = asm.forward_declare_label()

# Initialize counter in RAX
asm.mov_reg_imm64(py_asm.RAX, 10)

# Loop start
asm.define_label(loop_start)
asm.sub_reg_imm(py_asm.RAX, 1)
asm.cmp_reg_imm(py_asm.RAX, 0)
asm.jne_label32(loop_start)

# Loop end
asm.define_label(loop_end)
asm.ret()

machine_code = asm.finalize()
```

## License

This project is licensed under Apache-2.0.

## Contributing

Contributions are welcome! Please see the main PolkaVM repository for contribution guidelines.

