104 lines
2.3 KiB
Markdown
104 lines
2.3 KiB
Markdown
# Rhai Python Bindings
|
|
|
|
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
|
|
```
|
|
|
|
## 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.
|