virtualshell 1.1.6__tar.gz → 1.2.1__tar.gz

{virtualshell-1.1.6 → virtualshell-1.2.1}/.github/workflows/test_build-only.yml

@@ -199,10 +199,11 @@ jobs:
           CIBW_SKIP: "*-win32"
           CIBW_TEST_COMMAND: python -c "import virtualshell; print('ok')"
           CIBW_BUILD_VERBOSITY: "1"
+          # Ninja is forced by pyproject (cmake.args); the compiler comes from
+          # the VsDevCmd environment set up below, whatever VS version the
+          # runner image ships.
           CIBW_ENVIRONMENT_WINDOWS: >
-            CMAKE_GENERATOR="Visual Studio 17 2022"
-            CMAKE_GENERATOR_PLATFORM=x64
-            SKBUILD_CMAKE_GENERATOR="Visual Studio 17 2022"
+            CMAKE_GENERATOR=Ninja
             PYBIND11_FINDPYTHON=ON
             CMAKE_BUILD_TYPE=Release
         run: |

{virtualshell-1.1.6 → virtualshell-1.2.1}/.github/workflows/workflow.yml

@@ -25,18 +25,14 @@ jobs:
       fail-fast: false
       matrix:
         include:
-          - python: "cp38-*"
-            label: "cp38"
-          - python: "cp39-*"
-            label: "cp39"
-          - python: "cp310-*"
-            label: "cp310"
           - python: "cp311-*"
             label: "cp311"
           - python: "cp312-*"
             label: "cp312"
           - python: "cp313-*"
             label: "cp313"
+          - python: "cp314-*"
+            label: "cp314"
     steps:
       - uses: actions/checkout@v4
         with:
@@ -80,18 +76,14 @@ jobs:
       fail-fast: false
       matrix:
         include:
-          - python: "cp38-*"
-            label: "cp38"
-          - python: "cp39-*"
-            label: "cp39"
-          - python: "cp310-*"
-            label: "cp310"
           - python: "cp311-*"
             label: "cp311"
           - python: "cp312-*"
             label: "cp312"
           - python: "cp313-*"
             label: "cp313"
+          - python: "cp314-*"
+            label: "cp314"
     steps:
       - uses: actions/checkout@v4
         with:
@@ -139,18 +131,14 @@ jobs:
       fail-fast: false
       matrix:
         include:
-          - python: "cp38-*"
-            label: "cp38"
-          - python: "cp39-*"
-            label: "cp39"
-          - python: "cp310-*"
-            label: "cp310"
           - python: "cp311-*"
             label: "cp311"
           - python: "cp312-*"
             label: "cp312"
           - python: "cp313-*"
             label: "cp313"
+          - python: "cp314-*"
+            label: "cp314"
 
     steps:
       - uses: actions/checkout@v4
@@ -203,7 +191,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python: ["cp38-win_amd64", "cp39-win_amd64", "cp310-win_amd64", "cp311-win_amd64", "cp312-win_amd64", "cp313-win_amd64"]
+        python: ["cp311-win_amd64", "cp312-win_amd64", "cp313-win_amd64", "cp314-win_amd64"]
 
     steps:
       - uses: actions/checkout@v4
@@ -228,10 +216,11 @@ jobs:
           CIBW_SKIP: "*-win32"
           CIBW_TEST_COMMAND: python -c "import virtualshell; print('ok')"
           CIBW_BUILD_VERBOSITY: "1"
+          # Ninja is forced by pyproject (cmake.args); the compiler comes from
+          # the VsDevCmd environment set up below, whatever VS version the
+          # runner image ships.
           CIBW_ENVIRONMENT_WINDOWS: >
-            CMAKE_GENERATOR="Visual Studio 17 2022"
-            CMAKE_GENERATOR_PLATFORM=x64
-            SKBUILD_CMAKE_GENERATOR="Visual Studio 17 2022"
+            CMAKE_GENERATOR=Ninja
             PYBIND11_FINDPYTHON=ON
             CMAKE_BUILD_TYPE=Release
         run: |

{virtualshell-1.1.6 → virtualshell-1.2.1}/.gitignore

@@ -11,4 +11,6 @@ dist/
 test_run*
 test_performance_bridge.py
 ZEROCOPY_BRIDGE.md
-.vs/
+.vs/
+.pytest_cache/
+debug/

{virtualshell-1.1.6 → virtualshell-1.2.1}/CMakeLists.txt

@@ -39,7 +39,6 @@ set(SRC
   cpp/src/io_pump.cpp
   cpp/src/powershell_process.cpp
   cpp/src/virtual_shell.cpp
-  cpp/src/py_proxy.cpp
 )
 
 file(GLOB_RECURSE VS_HEADERS CONFIGURE_DEPENDS
@@ -47,7 +46,15 @@ file(GLOB_RECURSE VS_HEADERS CONFIGURE_DEPENDS
   "${CMAKE_CURRENT_SOURCE_DIR}/cpp/include/*.hpp"
 )
 
-pybind11_add_module(_core MODULE ${SRC} ${VS_HEADERS})
+# NO_EXTRAS on MSVC: pybind11's default /GL + LTCG (whole-program optimization)
+# triggers an internal compiler error (C1001) in newer MSVC toolsets
+# (observed with VS 2026 / cl 19.51) on the binder's lambda templates.
+# The binding layer is I/O-bound, so LTO buys nothing here anyway.
+if(MSVC)
+  pybind11_add_module(_core MODULE NO_EXTRAS ${SRC} ${VS_HEADERS})
+else()
+  pybind11_add_module(_core MODULE ${SRC} ${VS_HEADERS})
+endif()
 target_include_directories(_core PRIVATE cpp/include)
 
 # Link platform-specific libraries
@@ -93,36 +100,11 @@ install(TARGETS _core
   ARCHIVE DESTINATION virtualshell
 )
 
-# Build and link the vs_shm library on Windows
-if(WIN32 AND MSVC)
-  add_subdirectory(cpp/lib/vs_shm)
-
-  set_target_properties(_vs_shm PROPERTIES
-    RUNTIME_OUTPUT_DIRECTORY                "${_VS_OUTDIR}"
-    RUNTIME_OUTPUT_DIRECTORY_RELEASE        "${_VS_OUTDIR}"
-    RUNTIME_OUTPUT_DIRECTORY_RELWITHDEBINFO "${_VS_OUTDIR}"
-    RUNTIME_OUTPUT_DIRECTORY_DEBUG          "${_VS_OUTDIR}"
-    LIBRARY_OUTPUT_DIRECTORY                "${_VS_OUTDIR}"
-    LIBRARY_OUTPUT_DIRECTORY_RELEASE        "${_VS_OUTDIR}"
-    LIBRARY_OUTPUT_DIRECTORY_RELWITHDEBINFO "${_VS_OUTDIR}"
-    LIBRARY_OUTPUT_DIRECTORY_DEBUG          "${_VS_OUTDIR}"
-  )
-
-  add_dependencies(_core _vs_shm)
-
-  add_custom_command(TARGET _core POST_BUILD
-    COMMAND ${CMAKE_COMMAND} -E make_directory "${_VS_OUTDIR}"
-    COMMAND ${CMAKE_COMMAND} -E copy_if_different
-            "$<TARGET_FILE:_vs_shm>"
-            "${_VS_OUTDIR}/$<TARGET_FILE_NAME:_vs_shm>"
-    VERBATIM
-  )
-
-  install(TARGETS _vs_shm
-    RUNTIME DESTINATION virtualshell
-    LIBRARY DESTINATION virtualshell
-    ARCHIVE DESTINATION virtualshell
-  )
+# C++ tests (opt-in; never built by pip/scikit-build)
+option(VIRTUALSHELL_BUILD_TESTS "Build the C++ test suite (vs_core_tests)" OFF)
+if(VIRTUALSHELL_BUILD_TESTS)
+  enable_testing()
+  add_subdirectory(cpp/tests)
 endif()
 
 

{virtualshell-1.1.6 → virtualshell-1.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: virtualshell
-Version: 1.1.6
+Version: 1.2.1
 Summary: High-performance PowerShell bridge (C++ pybind11 backend)
 Keywords: powershell,automation,shell,cpp,pybind11
 Author: Kim-Andre Myrvold
@@ -208,105 +208,90 @@ License:                                  Apache License
          
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3 :: Only
+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: Programming Language :: C++
 Classifier: Operating System :: Microsoft :: Windows
 Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS
 Classifier: License :: OSI Approved :: Apache Software License
 Project-URL: Homepage, https://github.com/Chamoswor/virtualshell
 Project-URL: Issues, https://github.com/Chamoswor/virtualshell/issues
-Requires-Python: >=3.8
+Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 
-# 🐚 virtualshell
+# virtualshell
+
 [![PyPI version](https://img.shields.io/pypi/v/virtualshell.svg)](https://pypi.org/project/virtualshell/)
 [![Python versions](https://img.shields.io/pypi/pyversions/virtualshell.svg)](https://pypi.org/project/virtualshell/)
 [![OS](https://img.shields.io/badge/OS-Windows%20%7C%20Linux%20%7C%20macOS-blue)](#)
 [![License](https://img.shields.io/github/license/Chamoswor/virtualshell.svg)](LICENSE)
 [![Build](https://img.shields.io/github/actions/workflow/status/Chamoswor/virtualshell/workflow.yml)](https://github.com/Chamoswor/virtualshell/actions)
 
+**High-performance PowerShell automation for Python.**
+Run PowerShell commands with millisecond latency, persistent sessions, async
+execution, and a cross-platform zero-copy bridge — without juggling
+subprocesses.
 
-**High-performance PowerShell automation for Python**
-Run PowerShell commands with *millisecond latency*, persistent sessions, async execution, and a zero-copy bridge — without juggling subprocesses.
-
-> 🔗 **Full documentation lives in the [wiki](https://github.com/Chamoswor/virtualshell/wiki)**
-> This README focuses on *what it is*, *why it matters*, and *how to get started fast*.
-
-## ✨ What is virtualshell?
-
-`virtualshell` keeps **one PowerShell host warm** behind a thin Python wrapper powered by a **C++ engine**.
-
-Instead of spawning `pwsh` for every command, you get:
-
-* a **persistent PowerShell session**
-* **~2–4 ms execution latency**
-* **async + batch execution**
-* **structured, predictable results**
-* optional **zero-copy shared memory** (Windows)
-
-Perfect for:
-
-* Python orchestration layers
-* long-running agents
-* CI/test harnesses
-* automation tooling that must be *fast and reliable*
-
-## 🚀 Why use it?
+Full documentation lives in the
+[wiki](https://github.com/Chamoswor/virtualshell/wiki). This README covers
+what the library is, why it matters, and how to get started.
 
-* 🔄 **Persistent session**
-  Reuse loaded modules, `$env:*`, functions, and global state.
+## What is virtualshell?
 
-* ⚡ **Ultra-low latency**
-  Avoid the ~200 ms cost of `subprocess.run("pwsh")`.
+`virtualshell` keeps one PowerShell host warm behind a thin Python wrapper
+powered by a C++ engine. Instead of spawning `pwsh` for every command, you
+get:
 
-* 🔀 **Async & batching**
-  Schedule concurrent commands with timeouts and callbacks.
+* a persistent PowerShell session
+* ~2–4 ms execution latency
+* async and batch execution
+* structured, predictable results
+* optional zero-copy shared memory transfers (cross-platform)
+* live object proxies with generated type stubs
 
-* 📊 **Structured results**
-  Every call returns stdout, stderr, exit code, timing, and success state.
+Typical use cases include Python orchestration layers, long-running agents,
+CI/test harnesses, and automation tooling that must be fast and reliable.
 
-* 🚨 **Predictable failures**
-  Typed Python exceptions for timeouts, missing PowerShell, execution errors.
+## Why use it?
 
-* 🛠️ **Type-safe automation**
-  Generate Python `Protocol`s from PowerShell objects and control them via live proxies.
+* **Persistent session** — reuse loaded modules, `$env:*`, functions, and
+  global state across calls.
+* **Low latency** — avoid the ~200 ms cost of `subprocess.run("pwsh")` per
+  command.
+* **Async and batching** — schedule concurrent commands with timeouts and
+  callbacks.
+* **Structured results** — every call returns stdout, stderr, exit code,
+  timing, and success state.
+* **Predictable failures** — typed Python exceptions for timeouts, missing
+  PowerShell, and execution errors.
+* **Type-safe automation** — generate Python `Protocol` stubs from
+  PowerShell objects and control them through live proxies.
 
-## 📦 Installation
+## Requirements
 
-Pre-built wheels are published for:
+* **Python 3.11 – 3.14**
+* **PowerShell 7** (`pwsh`) on `PATH`, unless an explicit path is passed in
+  the configuration
 
-* **Windows**
-* **Linux** (x86_64 / aarch64)
-* **macOS** (universal2)
+## Installation
 
-### PowerShell requirement
-
-PowerShell (`pwsh` or `powershell.exe`) must be available on `PATH`,
-unless you pass an explicit path in the configuration.
-
----
-
-### ✅ Recommended: install pre-built wheels
+Pre-built wheels are published for Windows (x64), Linux (x86_64 / aarch64),
+and macOS (universal2):
 
 ```bash
 pip install virtualshell
 ```
 
-No compiler or build tools required.
-
----
-
-### 🔧 Build from source (optional)
+No compiler or build tools are required when installing wheels.
 
-Use this only if you explicitly want to build locally.
+### Building from source (optional)
 
-#### Windows (⚠️ 64-bit only)
-
-1. Install **Visual Studio Build Tools**
-
-   * Workload: *Desktop development with C++*
-2. Open **x64 Native Tools Command Prompt for VS**
-
----
+Building locally requires CMake and a C++17 compiler. On Windows, install
+Visual Studio Build Tools with the *Desktop development with C++* workload
+and run the build from an *x64 Native Tools Command Prompt* (64-bit only).
 
 ```bash
 pip install virtualshell --no-binary virtualshell
@@ -318,17 +303,13 @@ Or directly from GitHub:
 pip install "git+https://github.com/Chamoswor/virtualshell"
 ```
 
----
-
-### 🔍 Verify installation
+Verify the installation:
 
 ```bash
 python -c "import virtualshell; print('virtualshell OK')"
 ```
 
----
-
-## ⚡ Quick start
+## Quick start
 
 ```python
 from virtualshell import Shell
@@ -371,19 +352,18 @@ shell.script(Path("test.ps1"), args={"Name": "Alice", "Count": "3"})
 shell.stop()
 ```
 
-All execution APIs support:
-
-* per-call timeouts
-* `raise_on_error`
-* callbacks
-
-## 🧠 Advanced features
+All execution APIs support per-call timeouts, `raise_on_error`, and
+callbacks.
 
-### 🔌 Zero-Copy Bridge (Windows only)
+## Advanced features
 
-> High-throughput shared-memory transfer between Python and PowerShell
+### Zero-copy bridge
 
-Ideal for large binary blobs, files, or high-frequency data exchange.
+High-throughput shared-memory transfer between Python and PowerShell, suited
+for large binary blobs, files, or high-frequency data exchange. The payload
+moves through a file-backed memory map shared between Python (`mmap`) and
+PowerShell (.NET `MemoryMappedFile`) — no native DLL required, on Windows,
+Linux, and macOS.
 
 ```python
 from virtualshell import Shell, ZeroCopyBridge
@@ -391,50 +371,66 @@ from virtualshell import Shell, ZeroCopyBridge
 with Shell(timeout_seconds=60) as shell:
     with ZeroCopyBridge(shell) as bridge:
         data = b"x" * 1_000_000
-        bridge.send(data, "$buf")
+        bridge.send(data, "buf")
         print(shell.run("$buf.Length").out)
 ```
 
-Typical throughput: **5–150 MB/s**
-See the full guide in the wiki.
+Measured throughput is roughly 145–560 MB/s depending on payload size and
+direction — about 10–40× faster than piping the same data through stdout as
+base64. See the wiki for the full guide, including `PSObject` round-trips
+between Python and PowerShell.
 
----
+### PowerShell object proxies
 
-### 🧩 PowerShell object proxies
+Control live .NET/PowerShell objects from Python. Scalars convert to native
+Python types, byte arrays travel through the zero-copy bridge, and complex
+values come back as sub-proxies.
 
-Generate Python `Protocol`s from PowerShell types and control live objects with IDE-friendly type hints.
+```python
+with Shell() as sh:
+    writer = sh.make_proxy("", "System.IO.StreamWriter('test.txt')")
+    writer.WriteLine("Hello")
+    writer.Close()
+```
+
+A bare `[Type]` literal binds the type itself, exposing its **static**
+methods, properties and constants:
 
 ```python
-proxy = sh.make_proxy(
-    "StreamWriterProxy",
-    "System.IO.StreamWriter('test.txt')"
-)
+with Shell() as sh:
+    math = sh.make_proxy("", "[System.Math]")
+    print(math.Sqrt(16.0), math.PI)     # 4.0 3.141592653589793
+```
+
+Pair proxies with `generate_psobject`, which produces typed `Protocol` stubs
+(including overloads) for IDE completion and static analysis:
 
-proxy.WriteLine("Hello")
-proxy.Close()
+```python
+sh.generate_psobject("System.Text.StringBuilder()", Path("StringBuilder.py"))
 ```
 
-📖 Docs:
+```python
+from StringBuilder import StringBuilder
 
-* `generate_psobject`
-* `make_proxy`
+sb = sh.make_proxy(StringBuilder)   # created and typed in one call
+sb.Append("Hello")
+```
 
----
+See the `make_proxy` and `generate_psobject` pages in the wiki.
 
-## 🧰 Core API overview
+## Core API overview
 
 | Method                         | Description                     |
 | ------------------------------ | ------------------------------- |
 | `Shell.run(...)`               | Execute a command synchronously |
 | `Shell.run_async(...)`         | Schedule async execution        |
 | `Shell.script(...)`            | Run `.ps1` files                |
-| `Shell.save_session()`         | Persist session snapshot        |
-| `Shell.make_proxy(...)`        | Create live PS object proxy     |
+| `Shell.save_session()`         | Persist a session snapshot      |
+| `Shell.make_proxy(...)`        | Create a live PS object proxy   |
 | `Shell.generate_psobject(...)` | Generate Python `Protocol`s     |
+| `Shell.zero_copy_bridge()`     | Shared per-shell bridge         |
 
----
-
-## ⚙️ Configuration example
+## Configuration example
 
 ```python
 Shell(
@@ -450,23 +446,36 @@ Shell(
 )
 ```
 
----
+## Performance
 
-## 📈 Performance
+Measured with the bundled benchmarks (`bench/vs_bench.py`,
+`bench/zcb_bench.py`) on Windows 11, Python 3.14, PowerShell 7:
 
-Latest benchmarks (Windows 11, Python 3.13):
+**Command execution**
 
-* ~3.5 ms per sequential command
-* ~3.2 ms per batch command
-* ~2 ms async latency
-* ~0.3 s session save
+* ~0.45 s shell startup
+* ~3.5–4.0 ms per sequential command (~280 cmd/s)
+* ~3.2 ms per command in batches (~310 cmd/s)
+* ~2.3 ms async latency
+* ~620 cmd/s aggregate across 4 parallel shells
+* ~0.35 s session save
 
-Full methodology and charts live in the wiki.
+**Zero-copy bridge** (best of 3 runs per size)
+
+| Transfer                      | 1 MB     | 8 MB     | 32 MB    |
+| ----------------------------- | -------- | -------- | -------- |
+| PowerShell → Python (bytes)      | 145 MB/s | 385 MB/s | 413 MB/s |
+| PowerShell → Python (memoryview) | 145 MB/s | 454 MB/s | 563 MB/s |
+| Python → PowerShell (send)       | 178 MB/s | 369 MB/s | 293 MB/s |
 
----
+A 4 KB send+receive round trip takes ~8 ms (p50). For reference, moving the
+same 1 MB payload through stdout as base64 runs at ~14 MB/s, so the bridge
+is roughly 10–40× faster for bulk data.
+
+Full methodology and charts live in the wiki.
 
-## 📚 Learn more
+## Learn more
 
-* 📖 [Documentation wiki](https://github.com/Chamoswor/virtualshell/wiki)
-* 🐛 [Issues](https://github.com/Chamoswor/virtualshell/issues)
-* 💬 [Discussions](https://github.com/Chamoswor/virtualshell/discussions)
+* [Documentation wiki](https://github.com/Chamoswor/virtualshell/wiki)
+* [Issues](https://github.com/Chamoswor/virtualshell/issues)
+* [Discussions](https://github.com/Chamoswor/virtualshell/discussions)