virtualshell 1.0.2__tar.gz → 1.1.0__tar.gz

{virtualshell-1.0.2 → virtualshell-1.1.0}/.gitignore

@@ -3,9 +3,9 @@ __pycache__/
 *.pyc
 build/
 *.egg-info/
-dev_*
 test/
 .pypirc
 dist/
 .venv*
-test_run*
+test_run*
+test_sync_timeout.py

{virtualshell-1.0.2 → virtualshell-1.1.0}/CMakeLists.txt

@@ -21,14 +21,10 @@ set(CMAKE_CXX_STANDARD 17)
 set(CMAKE_CXX_STANDARD_REQUIRED ON)
 set(CMAKE_POSITION_INDEPENDENT_CODE ON)
 
-
-if (WIN32 AND CMAKE_CXX_COMPILER_ID STREQUAL "GNU")
-  message(FATAL_ERROR "MinGW is not supported on Windows for this project. Use MSVC.")
-endif()
-
-
 set(SRC
   cpp/src/binder.cpp
+  cpp/src/io_pump.cpp
+  cpp/src/powershell_process.cpp
   cpp/src/virtual_shell.cpp
 )
 
@@ -39,7 +35,7 @@ else()
   set(_VS_OUTDIR "${SKBUILD_PLATLIB_DIR}/virtualshell")
 endif()
 
-pybind11_add_module(_core MODULE ${SRC})
+pybind11_add_module(_core MODULE ${SRC} cpp/include/py_bridge.hpp)
 target_include_directories(_core PRIVATE cpp/include)
 
 if(UNIX)

{virtualshell-1.0.2 → virtualshell-1.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: virtualshell
-Version: 1.0.2
+Version: 1.1.0
 Summary: High-performance PowerShell bridge (C++ pybind11 backend)
 Keywords: powershell,automation,shell,cpp,pybind11
 Author: Kim-Andre Myrvold
@@ -219,251 +219,187 @@ Description-Content-Type: text/markdown
 
 # virtualshell
 
-High-performance Python façade over a **C++ PowerShell runner**.  
-A single long-lived PowerShell process is managed in C++, handling pipes, threads, timeouts and output demux; Python exposes a small, predictable API.
+High-performance PowerShell automation for Python. `virtualshell` keeps a single PowerShell host warm and exposes it through a thin Python wrapper backed by a C++ engine. The result: millisecond-scale latency, async execution, and session persistence without juggling subprocesses.
+
+> Full documentation now lives in the [project wiki](https://github.com/Chamoswor/virtualshell/wiki). This README gives you the essentials and quick links.
 
 ---
 
-## Features
+## Why virtualshell?
+
+- **Persistent session** – reuse modules, `$env:*`, and functions between calls.
+- **Low latency** – avoid the 200+ ms penalty of `subprocess.run("pwsh")`; most commands settle in ~2-4 ms.
+- **Async + batching** – schedule commands concurrently or in batches with strong timeout control.
+- **Structured results** – every invocation returns stdout/stderr, exit code, success flag, and timing.
+- **Predictable failures** – typed Python exceptions for “pwsh missing”, timeouts, and execution errors.
 
-- **Persistent session** to `pwsh`/`powershell` (reuse modules, `$env:*`, functions, cwd)
-- **Sync & async** execution (Futures + optional callbacks)
-- **Script execution** (positional / named args, optional dot-sourcing)
-- **Batch** with per-command timeout & early-stop
-- **Clear failures** (typed exceptions), **context manager** lifecycle
+Typical users embed PowerShell inside Python orchestration, long-running agents, or test suites that need reliability and speed.
 
 ---
 
-## Install
+## Installation
 
 ```bash
 pip install virtualshell
-````
-
-## Platform & Python Support
-
-Prebuilt wheels are provided via PyPI for common platforms and Python versions.  
-This means you can usually `pip install virtualshell` without needing a compiler.
-
-**Supported Python versions:**
-- 3.8, 3.9, 3.10, 3.11, 3.12, 3.13
-
-**Supported platforms:**
-- **Windows** (x86_64, MSVC build)
-- **Linux** (x86_64, aarch64, manylinux2014/2.28)
-- **macOS** (universal2: x86_64 + arm64)
-
-If your platform is not listed above, pip will fall back to building from source.  
-See [Building from source](#building-from-source-advanced) for details.
-
+```
 
-> Requires PowerShell on `PATH` (`pwsh` preferred, `powershell` also supported).
+Pre-built wheels are published for Windows, Linux (x86_64/aarch64), and macOS universal2. PowerShell (`pwsh` or `powershell.exe`) must be discoverable on `PATH` unless you pass an explicit path.
 
 ---
 
 ## Quick start
 
 ```python
-import virtualshell
-
-# Create a shell with a 5s default timeout
-sh = virtualshell.Shell(timeout_seconds=5).start()
-
-# 1) One-liners (sync)
-res = sh.run("Write-Output 'hello'")
-print(res.out.strip())  # -> hello
-
-# 2) Async single command
-fut = sh.run_async("Write-Output 'async!'")
-print(fut.result().out.strip())
-
-# 3) Scripts with positional args
-r = sh.run_script(r"C:\temp\demo.ps1", args=["alpha", "42"])
-print(r.out)
-
-# 4) Scripts with named args
-r = sh.run_script_kv(r"C:\temp\demo.ps1", named_args={"Name":"Alice","Count":"3"})
-print(r.out)
+from virtualshell import Shell
 
-# 5) Context manager (auto-stop on exit)
-with virtualshell.Shell(timeout_seconds=3) as s:
-    print(s.run("Write-Output 'inside with'").out.strip())
+with Shell(timeout_seconds=5) as sh:
+    result = sh.run("Write-Output 'Hello from pwsh'")
+    print(result.out.strip())
 
-sh.stop()
+    sh.run("function Inc { $global:i++; $global:i }")
+    print(sh.run("Inc").out.strip())  # 1
+    print(sh.run("Inc").out.strip())  # 2
 ```
 
-Another example (stateful session):
+### Async execution
 
 ```python
 from virtualshell import Shell
-with Shell(timeout_seconds=3) as sh:
-    sh.run("function Inc { $global:i++; $global:i }")
-    nums = [sh.run("Inc").out.strip() for _ in range(5)]
-    print(nums)  # ['1','2','3','4','5']
-```
+import asyncio
 
----
-
-## API (overview)
+async def main():
+    shell = Shell().start()
+    fut = shell.run_async("Get-Date")
+    res = await asyncio.wrap_future(fut)
+    print(res.out.strip())
+    shell.stop()
 
-```python
-import virtualshell
-from virtualshell import ExecutionResult  # dataclass view
+asyncio.run(main())
+```
 
-sh = virtualshell.Shell(
-    powershell_path=None,                     # optional explicit path
-    working_directory=None,                   # resolved to absolute path
-    timeout_seconds=5.0,                      # default per-command timeout
-    environment={"FOO": "BAR"},               # extra child env vars
-    initial_commands=["$ErrorActionPreference='Stop'"],  # post-start setup
-).start()
+### Scripts and arguments
 
-# Sync
-res: ExecutionResult = sh.run("Get-Location | Select-Object -Expand Path")
+```python
+from pathlib import Path
+from virtualshell import Shell
 
-# Scripts
-res = sh.run_script(r"/path/to/job.ps1", args=["--fast","1"])
-res = sh.run_script_kv(r"/path/to/job.ps1", named_args={"Mode":"Fast","Count":"1"})
-res = sh.run_script(r"/path/init.ps1", dot_source=True)
+shell = Shell().start()
 
-# Async
-f = sh.run_async("Write-Output 'ping'")
-f2 = sh.run_async_batch(["$PSVersionTable", "Get-Random"])
+# Positional arguments
+shell.script(Path("./scripts/test.ps1"), args=["alpha", "42"])
 
-# Convenience
-res = sh.pwsh("literal 'quoted' string")     # safe single-quoted literal
+# Named arguments (hashtable splatting)
+shell.script(
+    Path("./scripts/test.ps1"),
+    args={"Name": "Alice", "Count": "3"},
+)
 
-sh.stop()
+shell.stop()
 ```
 
-### Return type
-
-By default you get a Python dataclass:
+Every API surface (sync/async/script) accepts `timeout` overrides and optional error raising via `raise_on_error` or callbacks.
 
-```python
-@dataclass(frozen=True)
-class ExecutionResult:
-    out: str
-    err: str
-    exit_code: int
-    success: bool
-    execution_time: float
-```
+---
 
-Pass `as_dataclass=False` to receive the raw C++ result object.
+## Core API overview
 
-### Timeouts
+| Method | Purpose |
+| --- | --- |
+| `Shell.run(cmd, *, timeout=None, raise_on_error=False)` | Execute a single command synchronously. |
+| `Shell.run_async(cmd, *, callback=None, timeout=None)` | Schedule a command; returns a `concurrent.futures.Future`. |
+| `Shell.script(path, args=None, *, timeout=None, dot_source=False, raise_on_error=False)` | Execute `.ps1` files with positional or named arguments. |
+| `Shell.script_async(...)` | Async counterpart of `script`. |
+| `Shell.save_session()` | Persist the current session to an XML snapshot. |
+| `Shell.pwsh(text)` | Safely echo a literal PowerShell string (auto quoting). |
 
-* Every method accepts a `timeout` (or `per_command_timeout`) in seconds.
-* On timeout: `success=False`, `exit_code=-1`, `err` contains `"timeout"`.
-* Async futures resolve with the timeout result; late output is dropped in C++.
+More helpers live in the wiki, including session restore, batching, and diagnostic tips.
 
 ---
 
-## Design notes
-
-* **Thin wrapper:** heavy I/O in C++; Python does orchestration only.
-* **No surprises:** stable API, documented side-effects.
-* **Clear failure modes:** `raise_on_error` and typed exceptions.
-* **Thread-friendly:** async returns Futures/callbacks; no Python GIL-level locking.
-* **Boundary hygiene:** explicit path/arg conversions, minimal marshalling.
-
-### Security
+## Configuration
 
-* The wrapper **does not sanitize** raw commands. Only `pwsh()` applies literal single-quoting for data.
-* Don’t pass untrusted strings to `run*` without proper quoting/sanitization.
-* Avoid logging secrets; env injection happens via `Shell(..., environment=...)`.
-
-### Performance
+```python
+from virtualshell import Shell
 
-* Sync/async routes call into C++ directly; Python overhead is object creation + callback dispatch.
-* Prefer **batch/async** for many small commands to amortize round-trips.
+shell = Shell(
+    powershell_path=r"C:\Program Files\PowerShell\7\pwsh.exe",
+    working_directory=r"C:\automation",
+    environment={"MY_FLAG": "1"},
+    initial_commands=[
+        "$ErrorActionPreference = 'Stop'",
+        "$ProgressPreference = 'SilentlyContinue'",
+    ],
+    timeout_seconds=10,
+    auto_restart_on_timeout=True,
+)
 
-### Lifetime
+shell.start()
+```
 
-* `Shell.start()` ensures a running backend; `Shell.stop()` tears it down.
-* `with Shell(...)` guarantees stop-on-exit, even on exceptions.
+Configuration is applied before the process starts. You can inspect or replace it later with `shell._core.get_config()` or rebuild the shell.
 
 ---
 
-## Exceptions
+## Error handling
 
 ```python
-from virtualshell.errors import (
-    VirtualShellError,
-    PowerShellNotFoundError,
-    ExecutionTimeoutError,
-    ExecutionError,
-)
+from virtualshell import Shell
+from virtualshell.errors import ExecutionError, ExecutionTimeoutError
+
+shell = Shell().start()
 
 try:
-    res = sh.run("throw 'boom'", raise_on_error=True)
+    shell.run("throw 'boom'", raise_on_error=True)
 except ExecutionTimeoutError:
-    ...
-except ExecutionError as e:
-    print("PowerShell failed:", e)
+    print("Timed out")
+except ExecutionError as exc:
+    print("PowerShell failure:", exc)
+finally:
+    shell.stop()
 ```
 
-* `ExecutionTimeoutError` is raised on timeouts **if** `raise_on_error=True`.
-* Otherwise, APIs return `ExecutionResult(success=False)`.
+Refer to `virtualshell.errors` for all exception types.
 
 ---
 
-## Configuration tips
-
-If PowerShell isn’t on `PATH`, pass `powershell_path`:
+## Performance
 
-```python
-Shell(powershell_path=r"C:\Program Files\PowerShell\7\pwsh.exe")
-```
+Up-to-date benchmark artefacts (`bench.json`, `bench.csv`) and analysis live in [docs/wiki/Project/Benchmarks.md](docs/wiki/Project/Benchmarks.md). Headline numbers from the latest run (Windows 11, Python 3.13):
 
-Session setup example:
+- Sequential commands: ~3.5 ms average
+- Batch commands: ~3.2 ms per command
+- Async latency: ~1.9–2.4 ms with 50 outstanding tasks
+- Session save: ~0.30 s median
 
-```python
-Shell(initial_commands=[
-    "$OutputEncoding = [Console]::OutputEncoding = [Text.UTF8Encoding]::new()",
-    "$ErrorActionPreference = 'Stop'"
-])
-```
+See the wiki for charts and methodology.
 
 ---
 
-# Building from source (advanced)
-Source builds require a C++ toolchain and CMake.
+## Building from source
 
-**Prereqs:** Python ≥3.8, C++17, CMake ≥3.20, `scikit-build-core`, `pybind11`.
+Dependencies:
 
-```bash
-# in repo root
-python -m pip install -U pip build
-python -m build           # -> dist/*.whl, dist/*.tar.gz
-python -m pip install dist/virtualshell-*.whl
-```
-
-Editable install:
+- Python 3.8+
+- CMake 3.20+
+- A C++17 compiler (MSVC, Clang, or GCC)
+- `scikit-build-core`, `pybind11`
 
 ```bash
-python -m pip install -e .
+python -m pip install -U build
+python -m build
+python -m pip install dist/virtualshell-*.whl
 ```
 
-* Linux wheels target **manylinux_2_28** (x86_64/aarch64).
-* macOS builds target **universal2** (x86_64 + arm64).
-
 ---
 
-## Roadmap
-
-* ✅ Windows x64 wheels (3.8–3.13)
-* ✅ Linux x64/aarch64 wheels (manylinux_2_28)
-* ✅ macOS x86_64/arm64 wheels
-* ⏳ Streaming APIs and richer progress events
-
----
+## Learn more
 
-## License
+- [Usage guides](docs/wiki/Usage)
+- [Performance tips](docs/wiki/Usage/Performance%20Tips.md)
+- [Benchmarks](docs/wiki/Project/Benchmarks.md)
 
-Apache 2.0 — see [LICENSE](LICENSE).
+Bug reports and feature requests are welcome via issues or discussions.
 
 ---
 
-*Issues & feedback are welcome. Please include Python version, OS, your PowerShell path (`pwsh`/`powershell`), and a minimal repro.*
+Licensed under the Apache 2.0 license. See [LICENSE](LICENSE).

virtualshell-1.1.0/README.md

@@ -0,0 +1,186 @@
+# virtualshell
+
+High-performance PowerShell automation for Python. `virtualshell` keeps a single PowerShell host warm and exposes it through a thin Python wrapper backed by a C++ engine. The result: millisecond-scale latency, async execution, and session persistence without juggling subprocesses.
+
+> Full documentation now lives in the [project wiki](https://github.com/Chamoswor/virtualshell/wiki). This README gives you the essentials and quick links.
+
+---
+
+## Why virtualshell?
+
+- **Persistent session** – reuse modules, `$env:*`, and functions between calls.
+- **Low latency** – avoid the 200+ ms penalty of `subprocess.run("pwsh")`; most commands settle in ~2-4 ms.
+- **Async + batching** – schedule commands concurrently or in batches with strong timeout control.
+- **Structured results** – every invocation returns stdout/stderr, exit code, success flag, and timing.
+- **Predictable failures** – typed Python exceptions for “pwsh missing”, timeouts, and execution errors.
+
+Typical users embed PowerShell inside Python orchestration, long-running agents, or test suites that need reliability and speed.
+
+---
+
+## Installation
+
+```bash
+pip install virtualshell
+```
+
+Pre-built wheels are published for Windows, Linux (x86_64/aarch64), and macOS universal2. PowerShell (`pwsh` or `powershell.exe`) must be discoverable on `PATH` unless you pass an explicit path.
+
+---
+
+## Quick start
+
+```python
+from virtualshell import Shell
+
+with Shell(timeout_seconds=5) as sh:
+    result = sh.run("Write-Output 'Hello from pwsh'")
+    print(result.out.strip())
+
+    sh.run("function Inc { $global:i++; $global:i }")
+    print(sh.run("Inc").out.strip())  # 1
+    print(sh.run("Inc").out.strip())  # 2
+```
+
+### Async execution
+
+```python
+from virtualshell import Shell
+import asyncio
+
+async def main():
+    shell = Shell().start()
+    fut = shell.run_async("Get-Date")
+    res = await asyncio.wrap_future(fut)
+    print(res.out.strip())
+    shell.stop()
+
+asyncio.run(main())
+```
+
+### Scripts and arguments
+
+```python
+from pathlib import Path
+from virtualshell import Shell
+
+shell = Shell().start()
+
+# Positional arguments
+shell.script(Path("./scripts/test.ps1"), args=["alpha", "42"])
+
+# Named arguments (hashtable splatting)
+shell.script(
+    Path("./scripts/test.ps1"),
+    args={"Name": "Alice", "Count": "3"},
+)
+
+shell.stop()
+```
+
+Every API surface (sync/async/script) accepts `timeout` overrides and optional error raising via `raise_on_error` or callbacks.
+
+---
+
+## Core API overview
+
+| Method | Purpose |
+| --- | --- |
+| `Shell.run(cmd, *, timeout=None, raise_on_error=False)` | Execute a single command synchronously. |
+| `Shell.run_async(cmd, *, callback=None, timeout=None)` | Schedule a command; returns a `concurrent.futures.Future`. |
+| `Shell.script(path, args=None, *, timeout=None, dot_source=False, raise_on_error=False)` | Execute `.ps1` files with positional or named arguments. |
+| `Shell.script_async(...)` | Async counterpart of `script`. |
+| `Shell.save_session()` | Persist the current session to an XML snapshot. |
+| `Shell.pwsh(text)` | Safely echo a literal PowerShell string (auto quoting). |
+
+More helpers live in the wiki, including session restore, batching, and diagnostic tips.
+
+---
+
+## Configuration
+
+```python
+from virtualshell import Shell
+
+shell = Shell(
+    powershell_path=r"C:\Program Files\PowerShell\7\pwsh.exe",
+    working_directory=r"C:\automation",
+    environment={"MY_FLAG": "1"},
+    initial_commands=[
+        "$ErrorActionPreference = 'Stop'",
+        "$ProgressPreference = 'SilentlyContinue'",
+    ],
+    timeout_seconds=10,
+    auto_restart_on_timeout=True,
+)
+
+shell.start()
+```
+
+Configuration is applied before the process starts. You can inspect or replace it later with `shell._core.get_config()` or rebuild the shell.
+
+---
+
+## Error handling
+
+```python
+from virtualshell import Shell
+from virtualshell.errors import ExecutionError, ExecutionTimeoutError
+
+shell = Shell().start()
+
+try:
+    shell.run("throw 'boom'", raise_on_error=True)
+except ExecutionTimeoutError:
+    print("Timed out")
+except ExecutionError as exc:
+    print("PowerShell failure:", exc)
+finally:
+    shell.stop()
+```
+
+Refer to `virtualshell.errors` for all exception types.
+
+---
+
+## Performance
+
+Up-to-date benchmark artefacts (`bench.json`, `bench.csv`) and analysis live in [docs/wiki/Project/Benchmarks.md](docs/wiki/Project/Benchmarks.md). Headline numbers from the latest run (Windows 11, Python 3.13):
+
+- Sequential commands: ~3.5 ms average
+- Batch commands: ~3.2 ms per command
+- Async latency: ~1.9–2.4 ms with 50 outstanding tasks
+- Session save: ~0.30 s median
+
+See the wiki for charts and methodology.
+
+---
+
+## Building from source
+
+Dependencies:
+
+- Python 3.8+
+- CMake 3.20+
+- A C++17 compiler (MSVC, Clang, or GCC)
+- `scikit-build-core`, `pybind11`
+
+```bash
+python -m pip install -U build
+python -m build
+python -m pip install dist/virtualshell-*.whl
+```
+
+---
+
+## Learn more
+
+- [Usage guides](docs/wiki/Usage)
+- [Performance tips](docs/wiki/Usage/Performance%20Tips.md)
+- [Benchmarks](docs/wiki/Project/Benchmarks.md)
+
+Bug reports and feature requests are welcome via issues or discussions.
+
+---
+
+Licensed under the Apache 2.0 license. See [LICENSE](LICENSE).

virtualshell-1.1.0/bench/bench.csv

@@ -0,0 +1,4 @@
+size,single_mean_ms,single_thr,batch_per_cmd_mean_ms,batch_thr,async_lat_mean_ms,async_thr,batch_eff,async_eff
+50,4.041,247.301,3.387,295.240,2.359,293.607,1.193,1.186
+100,3.754,266.165,3.685,271.400,2.247,304.264,1.019,1.142
+200,3.476,287.452,3.203,312.230,1.938,348.655,1.085,1.212