rhai-python/README.md

# Rhai Python Bindings - Setup Instructions

This is a basic implementation of Python bindings for the Rhai scripting language using PyO3.

## Prerequisites

1. **Rust** (latest stable version)
   ```bash
   curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
   ```

2. **Python** 3.8+ with development headers
   ```bash
   # Ubuntu/Debian
   sudo apt install python3-dev
   
   # macOS (with Homebrew)
   brew install python
   
   # Windows: Install Python from python.org
   ```

3. **Maturin** (for building Python extensions)
   ```bash
   pip install maturin
   ```

## Project Setup

1. Create the project directory structure:
   ```bash
   mkdir rhai-python
   cd rhai-python
   mkdir src python/rhai
   ```

2. Copy the provided files to their respective locations:
   - `Cargo.toml` → project root
   - `pyproject.toml` → project root
   - `src/lib.rs` → src directory
   - `python/rhai/__init__.py` → python/rhai directory
   - `example_usage.py` → project root (for testing)

## Building

1. **Development build** (recommended for testing):
   ```bash
   maturin develop
   ```
   This builds the extension and installs it in your current Python environment.

2. **Release build**:
   ```bash
   maturin build --release
   ```

3. **Build wheel for distribution**:
   ```bash
   maturin build --release --out dist/
   ```

## Testing

After building with `maturin develop`, you can test the bindings:

```bash
python example_usage.py
```

Or interactively:
```python
import rhai

# Quick evaluation
result = rhai.eval("40 + 2")
print(result)  # 42

# Using the engine
engine = rhai.RhaiEngine()
engine.set_var("x", 10)
result = engine.eval("x * 2")
print(result)  # 20
```

## Current Features

- ✅ Basic script evaluation
- ✅ Variable binding (Python → Rhai)
- ✅ Variable retrieval (Rhai → Python)
- ✅ Type conversion for:
  - Integers, floats, booleans, strings
  - Arrays (lists)
  - Objects (dictionaries)
- ✅ Error handling
- ✅ Script compilation checking
- ✅ Scope management

## Limitations & TODOs

This is a basic implementation. Future enhancements could include:

- [ ] Function registration (calling Python functions from Rhai)
- [ ] Custom type support
- [ ] Module system integration
- [ ] AST manipulation
- [ ] Debugging support
- [ ] Threading/async support
- [ ] Performance optimizations
- [ ] More comprehensive error types

## Troubleshooting

**Import errors**: Make sure you've run `maturin develop` after making changes.

**Build errors**: Ensure you have the correct Python development headers installed.

**Type conversion errors**: The current implementation supports basic types. Complex Python objects will raise conversion errors.

**Performance**: This is a proof-of-concept implementation. Production use would benefit from optimization.