# pylua_bioxen_vm_lib
A Python library for orchestrating networked Lua virtual machines through subprocess management and socket communication with multi-VM support.
## Overview
pylua_bioxen_vm_lib provides a unique approach to running multiple Lua interpreters as isolated processes, managed from Python with built-in networking capabilities. **Version 0.1.19** introduces **Phase 1 multi-VM support** with factory pattern for different VM types including XCP-ng integration placeholders.
## Key Features
- **Multi-VM Architecture** - Factory pattern supporting different VM types (basic, xcpng)
- **Process-isolated Lua VMs** - Each VM runs in its own subprocess for fault tolerance
- **XCP-ng Integration** - Phase 1 placeholder support for XCP-ng VMs (full implementation in Phase 2)
- **Built-in networking** - Socket-based communication using LuaSocket
- **Multiple communication patterns** - Server, client, and P2P messaging modes
- **Dynamic VM management** - Spawn and terminate VMs as needed
- **Language-agnostic architecture** - Could be extended to other interpreters
- **Python orchestration** - Full lifecycle management from Python
- **Interactive sessions** - Attach/detach to running VMs for real-time interaction
- **Backward compatibility** - All existing code works unchanged
## Interactive Terminal Support
pylua_bioxen_vm_lib now supports interactive session management, allowing you to attach to running Lua VMs and interact with them in real-time.
### Interactive Session Management
- Attach/detach to running Lua VMs
- Send input and receive output in real-time
- Session lifecycle management
- Multiple concurrent sessions per VM
### Example Usage
```python
from pylua_bioxen_vm_lib import VMManager, InteractiveSession
manager = VMManager()
vm = manager.create_vm("interactive_vm")
# Start an interactive session
session = InteractiveSession(vm)
session.attach()
# Send commands and get responses
session.send_input("x = 42")
session.send_input("print(x)")
output = session.read_output()
# Detach when done
session.detach()
```
### Multi-VM Support (Phase 1)
```python
from pylua_bioxen_vm_lib import create_vm, VMManager
# Create different types of VMs
basic_vm = create_vm("basic_worker", vm_type="basic")
xcpng_vm = create_vm("xcpng_worker", vm_type="xcpng", config={
"xcpng_host": "192.168.1.100",
"username": "root",
"password": "secret",
"template": "lua-bio-template"
})
# Use VMManager for coordinated operations
with VMManager() as manager:
basic = manager.create_vm("basic", vm_type="basic")
xcpng = manager.create_vm("xcpng", vm_type="xcpng", config=config)
# Get VM info
info = manager.get_vm_info("xcpng")
print(f"VM Type: {info['vm_type']}") # xcpng
```
## Architecture
```
Python Process
├── VM Manager
│ ├── Lua Process 1 (subprocess)
│ ├── Lua Process 2 (subprocess)
│ └── Lua Process N (subprocess)
└── Networking Layer
├── Socket Server
├── Socket Client
└── P2P Communication
```
## Installation
```bash
pip install pylua_bioxen_vm_lib
```
### Prerequisites
- Python 3.7+
- Lua interpreter installed on system
- LuaSocket library (`luarocks install luasocket`)
## Quick Start
```python
from pylua_bioxen_vm_lib import VMManager
# Create a VM manager
manager = VMManager()
# Spawn Lua VMs
vm1 = manager.create_vm("vm1")
vm2 = manager.create_vm("vm2")
# Execute Lua code
result = vm1.execute("return math.sqrt(16)")
print(result) # 4.0
# Enable networking
vm1.start_server(port=8080)
vm2.connect_to("localhost", 8080)
# Send messages between VMs
vm2.send_message("Hello from VM2!")
message = vm1.receive_message()
# Cleanup
manager.shutdown_all()
```
## Use Cases
- **Distributed computing** - Parallel Lua script execution
- **Game servers** - Isolated game logic processes
- **Microservices** - Lightweight Lua-based services
- **Sandboxed scripting** - Safe execution of untrusted Lua code
- **Load balancing** - Multiple worker processes
- **Protocol testing** - Network protocol simulation
## Communication Patterns
### Server Mode
```python
vm.start_server(port=8080)
vm.accept_connections()
```
### Client Mode
```python
vm.connect_to("hostname", port)
vm.send_data("message")
```
### P2P Mode
```python
vm1.establish_p2p_with(vm2)
vm1.broadcast("Hello network!")
```
example usage
```python
from pylua_bioxen_vm_lib import VMManager
with VMManager() as manager:
# Server VM
server_vm = manager.create_vm("server", networked=True)
server_future = manager.start_server_vm("server", port=8080)
# Client VM
client_vm = manager.create_vm("client", networked=True)
client_future = manager.start_client_vm("client", "localhost", 8080, "Hello!")
# P2P VM
p2p_vm = manager.create_vm("p2p", networked=True)
p2p_future = manager.start_p2p_vm("p2p", 8081, "localhost", 8080)
```
## Examples
See the `examples/` directory for:
- Basic VM management (`basic_usage.py`)
- Distributed computation (`distributed_compute.py`)
- P2P messaging (`p2p_messaging.py`)
## Documentation
- [API Reference](docs/api.md)
- [Examples](docs/examples.md)
- [Installation Guide](docs/installation.md)
## Development
```bash
git clone https://github.com/yourusername/pylua_bioxen_vm_lib.git
cd pylua_bioxen_vm_lib
pip install -e .
python -m pytest tests/
```
## Contributing
Contributions welcome! Please read our contributing guidelines and submit pull requests.
## License
MIT License - see LICENSE file for details.
## Why pylua_bioxen_vm_lib?
Existing Python-Lua integrations focus on embedding Lua within Python processes. pylua_bioxen_vm_lib takes a different approach by managing separate Lua processes, providing:
- **True isolation** - One VM crash doesn't affect others
- **Horizontal scaling** - Easy to distribute across cores/machines
- **Network-first design** - Built for distributed systems
- **Fault tolerance** - Automatic recovery and reconnection
- **Resource management** - Independent memory and CPU usage per VM
Perfect for applications requiring robust, scalable Lua script execution with network communication capabilities.
Raw data
{
"_id": null,
"home_page": "https://github.com/aptitudetechnology/pylua_bioxen_vm_lib",
"name": "pylua-bioxen-vm-lib",
"maintainer": "pylua_bioxen_vm_lib contributors",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "lua, virtual-machine, bioinformatics, distributed-computing, xcp-ng, bioXen",
"author": "pylua_bioxen_vm_lib contributors",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/71/35/d9fb58ecf58a01861152bfc73d87080fe0b92fbdc64f31b7da5e8874bebd/pylua_bioxen_vm_lib-0.1.22.tar.gz",
"platform": null,
"description": "# pylua_bioxen_vm_lib\n\nA Python library for orchestrating networked Lua virtual machines through subprocess management and socket communication with multi-VM support.\n\n## Overview\n\npylua_bioxen_vm_lib provides a unique approach to running multiple Lua interpreters as isolated processes, managed from Python with built-in networking capabilities. **Version 0.1.19** introduces **Phase 1 multi-VM support** with factory pattern for different VM types including XCP-ng integration placeholders.\n\n## Key Features\n\n- **Multi-VM Architecture** - Factory pattern supporting different VM types (basic, xcpng)\n- **Process-isolated Lua VMs** - Each VM runs in its own subprocess for fault tolerance\n- **XCP-ng Integration** - Phase 1 placeholder support for XCP-ng VMs (full implementation in Phase 2)\n- **Built-in networking** - Socket-based communication using LuaSocket\n- **Multiple communication patterns** - Server, client, and P2P messaging modes\n- **Dynamic VM management** - Spawn and terminate VMs as needed\n- **Language-agnostic architecture** - Could be extended to other interpreters\n- **Python orchestration** - Full lifecycle management from Python\n- **Interactive sessions** - Attach/detach to running VMs for real-time interaction\n- **Backward compatibility** - All existing code works unchanged\n## Interactive Terminal Support\n\npylua_bioxen_vm_lib now supports interactive session management, allowing you to attach to running Lua VMs and interact with them in real-time.\n\n### Interactive Session Management\n- Attach/detach to running Lua VMs\n- Send input and receive output in real-time\n- Session lifecycle management\n- Multiple concurrent sessions per VM\n\n### Example Usage\n```python\nfrom pylua_bioxen_vm_lib import VMManager, InteractiveSession\n\nmanager = VMManager()\nvm = manager.create_vm(\"interactive_vm\")\n\n# Start an interactive session\nsession = InteractiveSession(vm)\nsession.attach()\n\n# Send commands and get responses\nsession.send_input(\"x = 42\")\nsession.send_input(\"print(x)\")\noutput = session.read_output()\n\n# Detach when done\nsession.detach()\n```\n\n### Multi-VM Support (Phase 1)\n```python\nfrom pylua_bioxen_vm_lib import create_vm, VMManager\n\n# Create different types of VMs\nbasic_vm = create_vm(\"basic_worker\", vm_type=\"basic\")\nxcpng_vm = create_vm(\"xcpng_worker\", vm_type=\"xcpng\", config={\n \"xcpng_host\": \"192.168.1.100\",\n \"username\": \"root\", \n \"password\": \"secret\",\n \"template\": \"lua-bio-template\"\n})\n\n# Use VMManager for coordinated operations\nwith VMManager() as manager:\n basic = manager.create_vm(\"basic\", vm_type=\"basic\")\n xcpng = manager.create_vm(\"xcpng\", vm_type=\"xcpng\", config=config)\n \n # Get VM info\n info = manager.get_vm_info(\"xcpng\")\n print(f\"VM Type: {info['vm_type']}\") # xcpng\n```\n\n## Architecture\n\n```\nPython Process\n\u251c\u2500\u2500 VM Manager\n\u2502 \u251c\u2500\u2500 Lua Process 1 (subprocess)\n\u2502 \u251c\u2500\u2500 Lua Process 2 (subprocess)\n\u2502 \u2514\u2500\u2500 Lua Process N (subprocess)\n\u2514\u2500\u2500 Networking Layer\n \u251c\u2500\u2500 Socket Server\n \u251c\u2500\u2500 Socket Client\n \u2514\u2500\u2500 P2P Communication\n```\n\n## Installation\n\n```bash\npip install pylua_bioxen_vm_lib\n```\n\n### Prerequisites\n\n- Python 3.7+\n- Lua interpreter installed on system\n- LuaSocket library (`luarocks install luasocket`)\n\n## Quick Start\n\n```python\nfrom pylua_bioxen_vm_lib import VMManager\n\n# Create a VM manager\nmanager = VMManager()\n\n# Spawn Lua VMs\nvm1 = manager.create_vm(\"vm1\")\nvm2 = manager.create_vm(\"vm2\")\n\n# Execute Lua code\nresult = vm1.execute(\"return math.sqrt(16)\")\nprint(result) # 4.0\n\n# Enable networking\nvm1.start_server(port=8080)\nvm2.connect_to(\"localhost\", 8080)\n\n# Send messages between VMs\nvm2.send_message(\"Hello from VM2!\")\nmessage = vm1.receive_message()\n\n# Cleanup\nmanager.shutdown_all()\n```\n\n## Use Cases\n\n- **Distributed computing** - Parallel Lua script execution\n- **Game servers** - Isolated game logic processes\n- **Microservices** - Lightweight Lua-based services\n- **Sandboxed scripting** - Safe execution of untrusted Lua code\n- **Load balancing** - Multiple worker processes\n- **Protocol testing** - Network protocol simulation\n\n## Communication Patterns\n\n### Server Mode\n```python\nvm.start_server(port=8080)\nvm.accept_connections()\n```\n\n### Client Mode \n```python\nvm.connect_to(\"hostname\", port)\nvm.send_data(\"message\")\n```\n\n### P2P Mode\n```python\nvm1.establish_p2p_with(vm2)\nvm1.broadcast(\"Hello network!\")\n```\n\nexample usage\n\n\n```python\nfrom pylua_bioxen_vm_lib import VMManager\n\nwith VMManager() as manager:\n # Server VM\n server_vm = manager.create_vm(\"server\", networked=True)\n server_future = manager.start_server_vm(\"server\", port=8080)\n \n # Client VM \n client_vm = manager.create_vm(\"client\", networked=True)\n client_future = manager.start_client_vm(\"client\", \"localhost\", 8080, \"Hello!\")\n \n # P2P VM\n p2p_vm = manager.create_vm(\"p2p\", networked=True)\n p2p_future = manager.start_p2p_vm(\"p2p\", 8081, \"localhost\", 8080)\n```\n\n## Examples\n\nSee the `examples/` directory for:\n- Basic VM management (`basic_usage.py`)\n- Distributed computation (`distributed_compute.py`) \n- P2P messaging (`p2p_messaging.py`)\n\n## Documentation\n\n- [API Reference](docs/api.md)\n- [Examples](docs/examples.md)\n- [Installation Guide](docs/installation.md)\n\n## Development\n\n```bash\ngit clone https://github.com/yourusername/pylua_bioxen_vm_lib.git\ncd pylua_bioxen_vm_lib\npip install -e .\npython -m pytest tests/\n```\n\n## Contributing\n\nContributions welcome! Please read our contributing guidelines and submit pull requests.\n\n## License\n\nMIT License - see LICENSE file for details.\n\n## Why pylua_bioxen_vm_lib?\n\nExisting Python-Lua integrations focus on embedding Lua within Python processes. pylua_bioxen_vm_lib takes a different approach by managing separate Lua processes, providing:\n\n- **True isolation** - One VM crash doesn't affect others\n- **Horizontal scaling** - Easy to distribute across cores/machines \n- **Network-first design** - Built for distributed systems\n- **Fault tolerance** - Automatic recovery and reconnection\n- **Resource management** - Independent memory and CPU usage per VM\n\nPerfect for applications requiring robust, scalable Lua script execution with network communication capabilities.\n",
"bugtrack_url": null,
"license": null,
"summary": "Process-isolated networked Lua VMs with multi-VM support and XCP-ng integration",
"version": "0.1.22",
"project_urls": {
"Bug Reports": "https://github.com/aptitudetechnology/pylua_bioxen_vm_lib/issues",
"Changelog": "https://github.com/aptitudetechnology/pylua_bioxen_vm_lib/blob/main/CHANGELOG.md",
"Documentation": "https://github.com/aptitudetechnology/pylua_bioxen_vm_lib/blob/main/README.md",
"Homepage": "https://github.com/aptitudetechnology/pylua_bioxen_vm_lib",
"Repository": "https://github.com/aptitudetechnology/pylua_bioxen_vm_lib"
},
"split_keywords": [
"lua",
" virtual-machine",
" bioinformatics",
" distributed-computing",
" xcp-ng",
" bioxen"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "19843ea1fab171b600025a09aa72df60dcba86ff0b9f02614a4d048160f17f93",
"md5": "3420fbce8ab803b665bdbf4b296356c3",
"sha256": "dff74ce9af2b6897b09e7c08cec310c4fa2f58725076793802c56ebf0f52c57d"
},
"downloads": -1,
"filename": "pylua_bioxen_vm_lib-0.1.22-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3420fbce8ab803b665bdbf4b296356c3",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 55470,
"upload_time": "2025-09-01T08:31:02",
"upload_time_iso_8601": "2025-09-01T08:31:02.277898Z",
"url": "https://files.pythonhosted.org/packages/19/84/3ea1fab171b600025a09aa72df60dcba86ff0b9f02614a4d048160f17f93/pylua_bioxen_vm_lib-0.1.22-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "7135d9fb58ecf58a01861152bfc73d87080fe0b92fbdc64f31b7da5e8874bebd",
"md5": "e56b7d7cb35b9c8d09abf38930d6f61f",
"sha256": "1278b1f565f4e905883049d312adefd359c8c9842826d4f725efb04e07e3b646"
},
"downloads": -1,
"filename": "pylua_bioxen_vm_lib-0.1.22.tar.gz",
"has_sig": false,
"md5_digest": "e56b7d7cb35b9c8d09abf38930d6f61f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 116880,
"upload_time": "2025-09-01T08:31:04",
"upload_time_iso_8601": "2025-09-01T08:31:04.596258Z",
"url": "https://files.pythonhosted.org/packages/71/35/d9fb58ecf58a01861152bfc73d87080fe0b92fbdc64f31b7da5e8874bebd/pylua_bioxen_vm_lib-0.1.22.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-01 08:31:04",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "aptitudetechnology",
"github_project": "pylua_bioxen_vm_lib",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "requests",
"specs": [
[
">=",
"2.25.0"
]
]
},
{
"name": "paramiko",
"specs": [
[
">=",
"2.7.0"
]
]
},
{
"name": "urllib3",
"specs": [
[
">=",
"1.26.0"
]
]
}
],
"lcname": "pylua-bioxen-vm-lib"
}
JSON
