Merge branch 'main' into dependabot/github_actions/actions/upload-pages-artifact-4

Author: phil65

.gitignore

@@ -10,6 +10,7 @@ coverage.xml
 .hatch
 .pytest_cache/
 junit.xml
+.beamignore
 # Jupyter Notebook
 .ipynb_checkpoints
 # pyenv
@@ -30,3 +31,4 @@ junit.xml
 uv.lock
 # DiskCache cache file
 ./model_cache
+node_modules/

README.md

@@ -24,3 +24,258 @@
 [![PyUp](https://pyup.io/repos/github/phil65/exxec/shield.svg)](https://pyup.io/repos/github/phil65/exxec/)
 
 [Read the documentation!](https://phil65.github.io/exxec/)
+
+
+
+### Basic Usage
+
+Use the `get_environment()` function to create execution environments:
+
+```python
+from exxec import get_environment
+
+# Local execution (same process)
+env = get_environment("local")
+
+# Subprocess execution (separate process when executing python code)
+env = get_environment("local", isolated=True)
+
+# Docker execution (containerized)
+env = get_environment("docker")
+
+# Execute code
+async with env:
+    result = await env.execute("""
+    async def main():
+        return "Hello from execution environment!"
+    """)
+    print(result.result)  # "Hello from execution environment!"
+```
+
+## Available Providers
+
+### Local Provider
+Executes code in the same Python process. Fastest option but offers no isolation.
+
+```python
+env = get_environment("local", timeout=30.0)
+```
+
+**Parameters:**
+- `timeout` (float): Execution timeout in seconds (default: 30.0)
+- `isolated` (bool): Whether to execute code in a separate process (default: False)
+- `language` (Language): Programming language (default: "python")
+
+
+### Docker Provider
+Executes code in Docker containers for strong isolation and reproducible environments.
+
+```python
+env = get_environment(
+    "docker",
+    image="python:3.13-slim",
+    timeout=60.0,
+    language="python"
+)
+```
+
+**Parameters:**
+- `lifespan_handler`: Tool server context manager (optional)
+- `image` (str): Docker image to use (default: "python:3.13-slim")
+- `timeout` (float): Execution timeout in seconds (default: 60.0)
+- `language` (Language): Programming language (default: "python")
+
+
+### Daytona Provider
+Executes code in remote Daytona sandboxes for cloud-based development environments.
+
+```python
+env = get_environment(
+    "daytona",
+    api_url="https://api.daytona.io",
+    api_key="your-api-key",
+    timeout=300.0,
+    keep_alive=False
+)
+```
+
+**Parameters:**
+- `api_url` (str): Daytona API URL (optional, uses env vars if not provided)
+- `api_key` (str): API key for authentication (optional)
+- `target` (str): Target configuration (optional)
+- `image` (str): Container image (default: "python:3.13-slim")
+- `timeout` (float): Execution timeout in seconds (default: 300.0)
+- `keep_alive` (bool): Keep sandbox running after execution (default: False)
+
+
+### E2B Provider
+Executes code in E2B sandboxes for secure, ephemeral execution environments.
+
+```python
+env = get_environment(
+    "e2b",
+    template="python",
+    timeout=300.0,
+    keep_alive=False,
+    language="python"
+)
+```
+
+**Parameters:**
+- `template` (str): E2B template to use (optional)
+- `timeout` (float): Execution timeout in seconds (default: 300.0)
+- `keep_alive` (bool): Keep sandbox running after execution (default: False)
+- `language` (Language): Programming language (default: "python")
+
+
+### Beam Provider
+Executes code in Beam cloud sandboxes for scalable, serverless execution environments.
+
+```python
+env = get_environment(
+    "beam",
+    cpu=1.0,
+    memory=128,
+    keep_warm_seconds=600,
+    timeout=300.0,
+    language="python"
+)
+```
+
+**Parameters:**
+- `cpu` (float | str): CPU cores allocated to the container (default: 1.0)
+- `memory` (int | str): Memory allocated to the container in MiB (default: 128)
+- `keep_warm_seconds` (int): Seconds to keep sandbox alive, -1 for no timeout (default: 600)
+- `timeout` (float): Execution timeout in seconds (default: 300.0)
+- `language` (Language): Programming language (default: "python")
+
+
+### MCP Provider
+Executes Python code with Model Context Protocol support for AI integrations.
+
+```python
+env = get_environment(
+    "mcp",
+    dependencies=["requests", "numpy"],
+    allow_networking=True,
+    timeout=30.0
+)
+```
+
+**Parameters:**
+- `dependencies` (list[str]): Python packages to install (optional)
+- `allow_networking` (bool): Allow network access (default: True)
+- `timeout` (float): Execution timeout in seconds (default: 30.0)
+
+
+## Code Execution Patterns
+
+All providers support two execution patterns:
+
+### 1. Main Function Pattern
+```python
+code = """
+async def main():
+    # Your code here
+    return "result"
+"""
+```
+
+### 2. Result Variable Pattern
+```python
+code = """
+import math
+_result = math.pi * 2
+"""
+```
+
+## Error Handling
+
+Execution results include comprehensive error information:
+
+```python
+async with env:
+    result = await env.execute(code)
+    if result.success:
+        print(f"Result: {result.result}")
+        print(f"Duration: {result.duration:.3f}s")
+    else:
+        print(f"Error: {result.error}")
+        print(f"Error Type: {result.error_type}")
+```
+
+## Multi-Language Support
+
+Some providers support multiple programming languages:
+
+```python
+# JavaScript execution
+env = get_environment("subprocess", language="javascript", executable="node")
+
+# TypeScript execution
+env = get_environment("docker", language="typescript", image="node:18")
+```
+
+## Advanced Usage
+
+### Context Managers
+All environments are async context managers for proper resource cleanup:
+
+```python
+async with get_environment("docker") as env:
+    result1 = await env.execute(code1)
+    result2 = await env.execute(code2)  # Reuses same container
+# Container automatically cleaned up
+```
+
+### Custom Configurations
+Each provider supports environment-specific customization:
+
+```python
+# Docker with custom image and networking
+env = get_environment(
+    "docker",
+    image="tensorflow/tensorflow:latest-py3",
+    timeout=600.0
+)
+
+# Subprocess with specific Python version
+env = get_environment(
+    "subprocess",
+    executable="/usr/bin/python3.11",
+    timeout=120.0
+)
+```
+
+### Streaming Output
+
+Some providers support streaming output line by line, useful for long-running processes:
+
+```python
+from exxec import get_environment
+
+# Stream output from subprocess execution
+env = get_environment("subprocess")
+
+async with env:
+    async for line in env.execute_stream("""
+    import time
+    for i in range(5):
+        print(f"Processing step {i+1}...")
+        time.sleep(1)
+    print("Done!")
+    """):
+        print(f"Live output: {line}")
+
+# Also works with Docker execution
+env = get_environment("docker")
+async with env:
+    async for line in env.execute_stream(code):
+        # Process each line as it's produced
+        if "ERROR" in line:
+            print(f"⚠️  {line}")
+        else:
+            print(f"✓ {line}")
+```
+
+**Supported providers:** `docker`, `local`, `beam`, `e2b`, `modal`, `vercel`, `ssh`, `daytona`

pyproject.toml

@@ -2,7 +2,7 @@
 
 [project]
 name = "exxec"
-version = "0.1.0"
+version = "0.4.0"
 description = "Execution environments"
 readme = "README.md"
 requires-python = ">=3.13"
@@ -29,6 +29,8 @@ classifiers = [
   "Typing :: Typed",
 ]
 dependencies = [
+  "anyenv>=1.11.6",
+  "ptyprocess>=0.7.0",
   "pydantic",
   "schemez",
   # Only add below (Copier)
@@ -44,12 +46,15 @@ Source = "https://github.com/phil65/exxec"
 
 [project.optional-dependencies]
 beam = ["beam-client>=0.2.187"]
+cloudflare = ["httpx>=0.27"]
 daytona = ["daytona; python_version < '3.14'"]
-docker = ["testcontainers", "morefs"]
+docker = ["testcontainers"]
 e2b = ["e2b-code-interpreter"]
+hopx = ["hopx-ai"]
 mcp = ["fastmcp", "mcp-run-python"]
 microsandbox = ["microsandbox"]
 modal = ["modal"]
+sprites = ["sprites-py"]
 ssh = ["asyncssh", "sshfs"]
 vercel = ["vercel"]
 
@@ -101,8 +106,8 @@ docstring-style = "google"
 
 [tool.mypy]
 python_version = "3.13"
-disable_error_code = ["misc", "import"]
 pretty = true
+strict = true
 check_untyped_defs = true
 exclude = ["venv/", ".venv/", "tests/"]
 plugins = ["pydantic.mypy"]
@@ -127,9 +132,13 @@ reportSelfClsParameterName = false
 reportPrivateImportUsage = false
 
 [tool.pytest]
+addopts = ["-m", "not integration"]
 log_cli = true
 log_date_format = "%Y-%m-%d %H:%M:%S"
 log_format = "%(asctime)s %(levelname)s %(message)s"
+markers = [
+  "integration: marks tests as integration tests (deselected by default)",
+]
 minversion = "9.0"
 testpaths = ["tests/"]
 asyncio_mode = "auto"
@@ -281,10 +290,20 @@ preview = true
 python-version = "3.13"
 python-platform = "all"
 
+[tool.ty.rules]
+unresolved-import = "ignore"
+unused-type-ignore-comment = "ignore"
+
 [tool.uv]
 default-groups = ["dev", "lint", "docs"]
+# Override to resolve beam-client (<14) vs daytona (>=15) websockets conflict
+override-dependencies = ["websockets>=15.0.0"]
 
 [tool.uv.build-backend]
+module-name = [
+  "exxec",
+  "exxec_config",
+]
 wheel-exclude = [
   ".mypy_cache/**",
   "__pycache__/**",