Metadata-Version: 2.4
Name: multi-env-employer
Version: 1.1.0
Summary: Execute Python code from different virtual environments as regular functions. Supports multiple Python versions, async/await, generators, and more.
Author: REYIL
License: MIT License
        
        Copyright (c) 2025 Азамат Ильбулов (REYIL)
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/REYIL/MultiEnvEmployer
Project-URL: Repository, https://github.com/REYIL/MultiEnvEmployer
Project-URL: Issues, https://github.com/REYIL/MultiEnvEmployer/issues
Project-URL: Telegram, https://t.me/REYIL_DEV
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Distributed Computing
Classifier: Topic :: Software Development :: Testing
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Operating System :: OS Independent
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Environment :: Console
Classifier: Typing :: Typed
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# MultiEnvEmployer

**Execute Python code from different virtual environments as regular functions.**

Run functions from isolated environments with different Python versions and conflicting dependencies without import conflicts or version issues.

---

## Features

- ✅ **Isolated Execution** - Run code in separate virtual environments
- ✅ **Transparent API** - Call remote functions as if they were local
- ✅ **Multiple Python Versions** - Support for Python 3.5+ modules
- ✅ **Stateful & Stateless** - Choose between persistent or one-shot execution
- ✅ **Print Interception** - Capture stdout from remote processes
- ✅ **Generators** - Full support for generator functions
- ✅ **Async Functions** - Automatic handling of async/await
- ✅ **Result Caching** - Optional caching for expensive operations
- ✅ **Large Data Streaming** - Automatic chunking for big results
- ✅ **Timeout Control** - Flexible timeout modes (none, absolute, progress)
- ✅ **Error Handling** - Remote exceptions as local exceptions
- ✅ **Process Management** - Fine-grained control over worker processes

---

## Installation

```bash
pip install multi-env-employer
```

---

## Quick Start

```python
from pathlib import Path
from MultiEnvEmployer import Employer, RemoteModule

# Initialize employer with target environment
emp = Employer(
    project_dir=Path("path/to/modules"),
    venv_path=Path("path/to/venv")
)

# Connect to remote module
module = RemoteModule(emp, "my_module")

# Call functions as if they were local
result = module.add(2, 3)
print(result)  # 5

# Use context manager for automatic cleanup
with Employer("path/to/modules", "path/to/venv") as emp:
    module = RemoteModule(emp, "my_module")
    result = module.process_data([1, 2, 3])
```

---

## Basic Usage

### Stateless Execution (default)

New process per function call:

```python
module = RemoteModule(emp, "my_module", stateful=False)
module.func1()  # Process A
module.func2()  # Process B
```

### Stateful Execution

Single process for all calls:

```python
module = RemoteModule(emp, "my_module", stateful=True)
module.set_value(10)  # Process A
module.get_value()    # Process A (same process)
```

### Print Interception

```python
module = RemoteModule(emp, "my_module", print_output="terminal")
module.my_function()  # Prints are captured and displayed
```

### Generators

```python
for value in module.stream_numbers(5):
    print(value)  # 0, 1, 2, 3, 4
```

### Async Functions

```python
result = module.async_operation(10)  # Called synchronously
```

### Result Caching

```python
module = RemoteModule(emp, "my_module", caching=True)
result1 = module.expensive_function(x=10)  # Executes
result2 = module.expensive_function(x=10)  # From cache
```

### Timeout Control

```python
from MultiEnvEmployer import TimeoutPolicy

# No timeout
module = RemoteModule(emp, "my_module", 
    timeout=TimeoutPolicy(seconds=60, mode="none"))

# Absolute timeout (hard limit)
module = RemoteModule(emp, "my_module",
    timeout=TimeoutPolicy(seconds=30, mode="absolute"))

# Progress timeout (resets on activity)
module = RemoteModule(emp, "my_module",
    timeout=TimeoutPolicy(seconds=10, mode="progress"))
```

### Error Handling

```python
from MultiEnvEmployer import errors

try:
    result = module.failing_function()
except errors.RemoteExecutionError as e:
    print(f"Remote error: {e.error_type}")
    print(f"Message: {e.error_message}")
    print(f"Traceback:\n{e.remote_traceback}")
except errors.RemoteTimeoutError as e:
    print(f"Timeout after {e.timeout_seconds}s")
except errors.WrongArgumentsError as e:
    print(f"Invalid arguments: {e.details}")
```

---

## Advanced Features

### Large Data Streaming

Large return values are automatically streamed in chunks:

```python
result = module.get_large_list()  # Automatically chunked if > 1 MB
```

### Process Management

```python
# Close specific module
emp.close(module)

# Close specific function (stateless)
emp.close("module_name.function_name")

# Close all processes
emp.close()
```

### Custom Configuration

```python
emp = Employer(
    project_dir=Path("modules"),
    venv_path=Path("venv"),
    cache_path=Path("cache"),
    pickle_protocol=4,
    stream_threshold=1024 * 1024,  # 1 MB
    chunk_size=512 * 1024          # 512 KB
)
```

---

## Requirements

- Python 3.8+ (for the library itself)
- Python 3.5+ (for remote modules)
- Virtual environment with target Python version

---

## Security Warning

⚠️ **CRITICAL**: This library uses pickle for inter-process communication. **Never use with untrusted data sources**.

- Pickle can execute arbitrary code during deserialization
- Only use MultiEnvEmployer with code and data you control
- Not suitable for processing user-supplied data or external inputs

---

## Use Cases

- **Legacy Code Integration** - Run old Python 2.7 code from Python 3.x
- **Dependency Isolation** - Use conflicting library versions in one project
- **Version Testing** - Test code across multiple Python versions
- **Resource Isolation** - Isolate memory-intensive operations
- **Sandboxing** - Run untrusted code in separate processes

---

## Documentation

Full documentation: [GitHub Repository](https://github.com/REYIL/MultiEnvEmployer)

---

## License

MIT License - see [LICENSE](https://github.com/REYIL/MultiEnvEmployer/blob/main/LICENSE)

---

## Contact

- GitHub Issues: https://github.com/REYIL/MultiEnvEmployer/issues
- Telegram: [@REYIL_DEV](https://t.me/REYIL_DEV)
