virtualshell 0.1.2__cp312-cp312-win_amd64.whl → 1.0.0__cp312-cp312-win_amd64.whl

virtualshell/shell.py

@@ -158,8 +158,8 @@ class ExecutionResult:
     Use this class when you need a stable Pythonic type. If you require the raw C++
     object (e.g., for zero-copy interop), pass `as_dataclass=False` to public APIs.
     """
-    output: str
-    error: str
+    out: str
+    err: str
     exit_code: int
     success: bool
     execution_time: float
@@ -168,8 +168,8 @@ class ExecutionResult:
     def from_cpp(cls, r: _CPP_ExecResult) -> "ExecutionResult":
         # Attribute access is defensive to tolerate ABI field name differences.
         return cls(
-            output=getattr(r, "output", ""),
-            error=getattr(r, "error", ""),
+            out=getattr(r, "output", ""),
+            err=getattr(r, "error", ""),
             exit_code=int(getattr(r, "exit_code", getattr(r, "exitCode", -1))),
             success=bool(getattr(r, "success", False)),
             execution_time=float(getattr(r, "execution_time", getattr(r, "executionTime", 0.0))),
@@ -265,7 +265,7 @@ class Shell:
         return bool(self._core.is_alive())
 
     # -------- sync --------
-    def execute(
+    def run(
         self,
         command: str,
         timeout: Optional[float] = None,
@@ -291,7 +291,7 @@ class Shell:
         _raise_on_failure(res, raise_on_error=raise_on_error, label="Command", timeout_used=to)
         return ExecutionResult.from_cpp(res) if as_dataclass else res
 
-    def execute_script(
+    def run_script(
         self,
         script_path: Union[str, Path],
         args: Optional[Iterable[str]] = None,
@@ -320,7 +320,7 @@ class Shell:
         _raise_on_failure(res, raise_on_error=raise_on_error, label="Script", timeout_used=to)
         return ExecutionResult.from_cpp(res) if as_dataclass else res
 
-    def execute_script_kv(
+    def run_script_kv(
         self,
         script_path: Union[str, Path],
         named_args: Optional[Dict[str, str]] = None,
@@ -346,7 +346,7 @@ class Shell:
         _raise_on_failure(res, raise_on_error=raise_on_error, label="ScriptKV", timeout_used=to)
         return ExecutionResult.from_cpp(res) if as_dataclass else res
 
-    def execute_batch(
+    def run_batch(
         self,
         commands: Iterable[str],
         *,
@@ -369,7 +369,7 @@ class Shell:
             return [ExecutionResult.from_cpp(r) for r in vec]
         return vec
 
-    def execute_async(self, command: str, callback: Optional[Callable[[ExecutionResult], None]] = None, *, as_dataclass: bool = True):
+    def run_async(self, command: str, callback: Optional[Callable[[ExecutionResult], None]] = None, *, as_dataclass: bool = True):
         """Asynchronously execute a single command.
 
         - If `callback` is provided, it is invoked on completion with the result type
@@ -390,7 +390,7 @@ class Shell:
         c_fut = self._core.execute_async(command=command, callback=_cb if callback else None)
         return _map_future(c_fut, lambda r: ExecutionResult.from_cpp(r)) if as_dataclass else c_fut
 
-    def execute_async_batch(
+    def run_async_batch(
         self,
         commands: Iterable[str],
         progress: Optional[Callable[[ _CPP_BatchProg ], None]] = None,
@@ -416,7 +416,7 @@ class Shell:
             return _map_future(fut, lambda vec: [ExecutionResult.from_cpp(r) for r in vec])
         return fut
 
-    def execute_async_script(
+    def run_async_script(
         self,
         script_path: Union[str, Path],
         args: Optional[Iterable[str]] = None,
@@ -453,7 +453,7 @@ class Shell:
             return _map_future(fut, lambda r: ExecutionResult.from_cpp(r))
         return fut
 
-    def execute_async_script_kv(
+    def run_async_script_kv(
         self,
         script_path: Union[str, Path],
         named_args: Optional[Dict[str, str]] = None,
@@ -501,7 +501,7 @@ class Shell:
             `shell.pwsh("Hello 'World'")` -> runs `Write-Output 'Hello ''World'''` semantics;
             here we only quote the literal; you still provide the full command.
         """
-        return self.execute(quote_pwsh_literal(s), timeout=timeout, raise_on_error=raise_on_error)
+        return self.run(quote_pwsh_literal(s), timeout=timeout, raise_on_error=raise_on_error)
 
     def __enter__(self) -> "Shell":
         """Context manager entry: ensure backend is running."""

{virtualshell-0.1.2.dist-info → virtualshell-1.0.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: virtualshell
-Version: 0.1.2
+Version: 1.0.0
 Summary: High-performance PowerShell bridge (C++ pybind11 backend)
 Keywords: powershell,automation,shell,cpp,pybind11
 Author: Kim-Andre Myrvold
@@ -217,42 +217,38 @@ Project-URL: Issues, https://github.com/Chamoswor/virtualshell/issues
 Requires-Python: >=3.8
 Description-Content-Type: text/markdown
 
+````markdown
 # virtualshell
 
-High-performance Python façade over a **C++ PowerShell runner**.
-All heavy I/O (pipes, threads, timeouts, demux) is implemented in C++ for low latency and high throughput; Python exposes a thin API.
+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.
 
 ---
 
 ## Features
 
-* **Single persistent session** to `pwsh`/`powershell` (low overhead)
-* **Sync & async** execution (futures + optional callbacks)
-* **Script execution** with positional or named args
-* **Batch execution** with per-command timeout & early-stop
-* **Clean error model** with typed Python exceptions
-* **Context manager** (`with Shell(...)`) for lifecycle safety
+- **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
 
 ---
 
 ## Install
 
-Preview packages are published to TestPyPI:
-
 ```bash
-pip install -i https://test.pypi.org/simple/ virtualshell==0.1.2
-```
-
-### Available distributions (Windows/Linux, amd64/x86_64)
+pip install virtualshell
+````
 
+### Supported platforms
 
-> **Requirements**
->
-> * Windows 10/11 x64 | Linux x86_64
-> * PowerShell available as `pwsh` (preferred) or `powershell` on `PATH`
-> * Python 3.8–3.13 (matching the wheel you install)
+* **Windows 10/11 x64**
+* **Linux**: x86_64 and aarch64 (manylinux_2_28 / glibc ≥ 2.28)
+* **macOS**: 12+ (x86_64 and arm64)
+* **Python**: 3.8 – 3.13
 
-Linux wheels will be added after validation (initial target: `manylinux_2_28_x86_64`).
+> Requires PowerShell on `PATH` (`pwsh` preferred, `powershell` also supported).
 
 ---
 
@@ -265,88 +261,75 @@ import virtualshell
 sh = virtualshell.Shell(timeout_seconds=5).start()
 
 # 1) One-liners (sync)
-res = sh.execute("Write-Output 'hello'")
-print(res.output.strip())  # -> hello
+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) Async single command
-fut = sh.execute_async("Write-Output 'async!'")
-print(fut.result().output.strip())
+# 3) Scripts with positional args
+r = sh.run_script(r"C:\temp\demo.ps1", args=["alpha", "42"])
+print(r.out)
 
-# 4) Scripts with positional args
-r = sh.execute_script(r"C:\temp\demo.ps1", args=["alpha", "42"])
-print(r.output)
+# 4) Scripts with named args
+r = sh.run_script_kv(r"C:\temp\demo.ps1", named_args={"Name":"Alice","Count":"3"})
+print(r.out)
 
-# 5) Scripts with named args
-r = sh.execute_script_kv(r"C:\temp\demo.ps1", named_args={"Name":"Alice", "Count":"3"})
-print(r.output)
-
-# 6) Context manager (auto-stop on exit)
+# 5) Context manager (auto-stop on exit)
 with virtualshell.Shell(timeout_seconds=3) as s:
-    print(s.execute("Write-Output 'inside with'").output.strip())
+    print(s.run("Write-Output 'inside with'").out.strip())
 
 sh.stop()
 ```
 
+Another example (stateful session):
+
 ```python
 from virtualshell import Shell
 with Shell(timeout_seconds=3) as sh:
-    sh.execute("function Inc { $global:i++; $global:i }")
-    nums = [sh.execute("Inc").output.strip() for _ in range(5)]
-    print(nums)  # -> ['1', '2', '3', '4', '5']
-
+    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']
 ```
 
 ---
 
-## Python API (high-level façade)
+## API (overview)
 
 ```python
 import virtualshell
-from virtualshell import ExecutionResult  # optional: Python dataclass view
+from virtualshell import ExecutionResult  # dataclass view
 
 sh = virtualshell.Shell(
-    powershell_path=None,             # optional explicit path to pwsh/powershell
-    working_directory=None,           # resolved to absolute path if provided
-    timeout_seconds=5.0,              # default per-command timeout
-    environment={"FOO":"BAR"},        # extra env vars for the child process
-    initial_commands=["$ErrorActionPreference='Stop'"]  # run after start()
-)
-
-sh.start()                            # idempotent, safe if already running
-
-# --- Sync ---
-res: ExecutionResult = sh.execute("Get-Location | Select-Object -Expand Path")
-print(res.success, res.exit_code, res.output)
-
-res = sh.execute_script(r"C:\scripts\job.ps1", args=["--fast","1"])
-res = sh.execute_script_kv(r"C:\scripts\job.ps1", named_args={"Mode":"Fast","Count":"1"})
-
-# Dotsource script
-res = sh.execute_script(r"C:\scripts\init.ps1", dot_source=True)
+    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()
 
-# --- Async ---
-f = sh.execute_async("Write-Output 'ping'")
-print(f.result().output.strip())
+# Sync
+res: ExecutionResult = sh.run("Get-Location | Select-Object -Expand Path")
 
-def on_done(r: ExecutionResult) -> None:
-    print("DONE:", r.success, r.output.strip())
+# 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)
 
-sh.execute_async("Write-Output 'callback!'", callback=on_done)
+# Async
+f = sh.run_async("Write-Output 'ping'")
+f2 = sh.run_async_batch(["$PSVersionTable", "Get-Random"])
 
-# Async batch
-f2 = sh.execute_async_batch(["$PSVersionTable", "Get-Random"])
-print([r.success for r in f2.result()])
-
-# --- Convenience ---
-res = sh.pwsh("literal 'quoted' string")  # safely single-quote literal data
+# Convenience
+res = sh.pwsh("literal 'quoted' string")     # safe single-quoted literal
 
 sh.stop()
 ```
 
-### Return types
+### Return type
 
-By default, methods return a Python `ExecutionResult` dataclass:
+By default you get a Python dataclass:
 
 ```python
 @dataclass(frozen=True)
@@ -358,44 +341,39 @@ class ExecutionResult:
     execution_time: float
 ```
 
-Pass `as_dataclass=False` to receive the **raw C++ result object** for zero-copy scenarios.
+Pass `as_dataclass=False` to receive the raw C++ result object.
 
 ### Timeouts
 
-* Each API accepts a `timeout` (or `per_command_timeout`) in **seconds**.
-* On timeout, `success=False`, `exit_code=-1`, `error` contains `"timeout"`.
-* Async futures resolve with the timeout result; late output is discarded by the C++ layer.
+* Every method accepts a `timeout` (or `per_command_timeout`) in seconds.
+* On timeout: `success=False`, `exit_code=-1`, `error` contains `"timeout"`.
+* Async futures resolve with the timeout result; late output is dropped in C++.
 
 ---
 
-## Design goals (production-readiness)
+## Design notes
 
-* **Thin wrapper:** All heavy I/O and process orchestration live in C++ for performance.
-* **No surprises:** Stable API; no implicit state mutations beyond what is documented.
-* **Clear failure modes:** Dedicated exceptions and `raise_on_error` semantics.
-* **Thread-friendly:** Async methods return Futures and accept callbacks; no Python-side locks.
-* **Boundary hygiene:** Minimal data marshalling; explicit conversions for paths/args.
+* **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 notes
+### Security
 
-* The wrapper **does not sanitize** raw commands. Only `pwsh()` uses literal single-quoting to protect data as arguments.
-* Do **not** pass untrusted strings to `execute*` without proper quoting/sanitization.
-* Environment injection happens via the `Shell` config; avoid secrets in logs/tracebacks.
+* 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 notes
+### Performance
 
-* Sync/async routes call into C++ directly; Python overhead is mostly object allocation and callback dispatch.
-* Prefer **batch** or **async** when issuing many small commands to amortize round-trips.
+* 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.
 
 ### Lifetime
 
-* `Shell.start()` initializes/ensures a running backend; `Shell.stop()` tears it down.
-* `with Shell(...) as sh:` guarantees **stop-on-exit**, even on exceptions.
-
-### Compatibility
-
-* The C++ layer may expose both `snake_case` and `camelCase`.
-* `ExecutionResult.from_cpp()` normalizes fields to keep ABI compatibility.
+* `Shell.start()` ensures a running backend; `Shell.stop()` tears it down.
+* `with Shell(...)` guarantees stop-on-exit, even on exceptions.
 
 ---
 
@@ -403,29 +381,34 @@ Pass `as_dataclass=False` to receive the **raw C++ result object** for zero-copy
 
 ```python
 from virtualshell.errors import (
-    SmartShellError,
+    VirtualShellError,
     PowerShellNotFoundError,
     ExecutionTimeoutError,
     ExecutionError,
 )
 
 try:
-    res = sh.execute("throw 'boom'", raise_on_error=True)
+    res = sh.run("throw 'boom'", raise_on_error=True)
 except ExecutionTimeoutError:
     ...
 except ExecutionError as e:
-    print("PS failed:", e)
+    print("PowerShell failed:", e)
 ```
 
-* `ExecutionTimeoutError` is raised when `exit_code == -1` and the error mentions `timeout`, **if** `raise_on_error=True`.
-* Otherwise APIs return an `ExecutionResult` with `success=False`.
+* `ExecutionTimeoutError` is raised on timeouts **if** `raise_on_error=True`.
+* Otherwise, APIs return `ExecutionResult(success=False)`.
 
 ---
 
 ## Configuration tips
 
-* If `pwsh`/`powershell` isn’t on `PATH`, pass `powershell_path` to `Shell(...)`.
-* Use `initial_commands` for per-session setup, e.g. UTF-8:
+If PowerShell isn’t on `PATH`, pass `powershell_path`:
+
+```python
+Shell(powershell_path=r"C:\Program Files\PowerShell\7\pwsh.exe")
+```
+
+Session setup example:
 
 ```python
 Shell(initial_commands=[
@@ -436,107 +419,43 @@ Shell(initial_commands=[
 
 ---
 
-## Building from source (advanced)
-
-You typically don’t need this when using wheels, but if you want to build locally:
-
-### Prerequisites
+## Building from source (optional)
 
-* **Python** ≥ 3.8 with dev headers
-* **C++17** compiler
-* **CMake** ≥ 3.20
-* **Build backend:** [`scikit-build-core`](https://github.com/scikit-build/scikit-build-core) + [`pybind11`](https://pybind11.readthedocs.io/)
-* **Windows:** MSVC (VS 2019/2022)
-* **Linux:** GCC/Clang (Linux wheels not verified yet)
+You normally won’t need this when using wheels.
 
-The project is already configured via **`pyproject.toml`** and **`CMakeLists.txt`**. The compiled extension is installed as **`virtualshell._core`**, so `import virtualshell` works out of the box.
-
-### One-shot local build (recommended)
+**Prereqs:** Python ≥3.8, C++17, CMake ≥3.20, `scikit-build-core`, `pybind11`.
 
 ```bash
 # in repo root
 python -m pip install -U pip build
-python -m build  # produces sdist and wheel under ./dist
+python -m build           # -> dist/*.whl, dist/*.tar.gz
 python -m pip install dist/virtualshell-*.whl
 ```
 
-### Editable/dev install
+Editable install:
 
 ```bash
-python -m pip install -U pip
-python -m pip install -e .  # uses scikit-build-core to build the C++ extension
+python -m pip install -e .
 ```
 
-### Platform notes
-
-**Windows (x64)**
-
-* Visual Studio 2022 generator is used by default (see `[tool.scikit-build.cmake]` in `pyproject.toml`).
-* If you have multiple VS versions, ensure the correct **x64** toolchain is active (Developer Command Prompt or `vcvars64.bat`).
-
-**Linux (x86_64)**
-
-* Source builds work with a recent GCC/Clang + CMake.
-* Prebuilt manylinux wheels are **not** published yet; CI configuration exists, but the Linux runtime matrix is still being validated.
-
-### Build configuration
-
-Most options are declared in `pyproject.toml`:
-
-* **Backend:** `scikit_build_core.build`
-* **Build args:** CMake generator and `PYBIND11_FINDPYTHON=ON` are set (auto-discovers the active Python).
-* **Wheel layout:** packaged under `src/virtualshell/`
-* **Versioning:** `setuptools_scm` writes `src/virtualshell/_version.py` from Git tags.
-
-You can override or pass extra CMake definitions at build time if needed:
-
-```bash
-# Example: switch generator or tweak parallelism
-SCIKIT_BUILD_VERBOSE=1 \
-CMAKE_BUILD_PARALLEL_LEVEL=8 \
-python -m build
-```
-
-### Smoke test after build
-
-```bash
-python - << 'PY'
-import virtualshell
-s = virtualshell.Shell(timeout_seconds=2)
-print("import_ok:", bool(s._core))
-# Optional: only if PowerShell is available on PATH
-# if s.start().is_running:
-#     print("exec_ok:", virtualshell.Shell().start().execute("Write-Output 'ok'").success)
-PY
-```
-
-### Troubleshooting
-
-* **Cannot find MSVC/CMake:** open a *Developer Command Prompt for VS 2022* or ensure `cmake` and the MSVC toolchain are on `PATH`.
-* **ImportError: cannot import name `_core`:** the extension didn’t build or wasn’t placed under `virtualshell/_core.*`. Reinstall (`python -m pip install -e .` or `python -m build && pip install dist/*.whl`).
-* **PowerShell not found at runtime:** pass an explicit path: `Shell(powershell_path=r"C:\Program Files\PowerShell\7\pwsh.exe")`.
+* Linux wheels target **manylinux_2_28** (x86_64/aarch64).
+* macOS builds target **x86_64** and **arm64** (may be universal2).
 
 ---
 
 ## Roadmap
 
 * ✅ Windows x64 wheels (3.8–3.13)
-* ✅ Linux x64 wheels (manylinux)
+* ✅ Linux x64/aarch64 wheels (manylinux_2_28)
+* ✅ macOS x86_64/arm64 wheels
 * ⏳ Streaming APIs and richer progress events
-* ✅ Packaging polish (`pyproject`, build matrices, GitHub Actions)
 
 ---
 
 ## License
 
-Apache 2.0, see [LICENSE](LICENSE) for details.
-
----
-
-## Acknowledgments
-
-* Built with `pybind11`, and a lot of care around cross-platform pipes & process control.
+Apache 2.0 — see [LICENSE](LICENSE).
 
 ---
 
-*If you hit issues, please open an issue with your Python version, OS, `pwsh`/`powershell` path, and a minimal repro.*
+*Issues & feedback are welcome. Please include Python version, OS, your PowerShell path (`pwsh`/`powershell`), and a minimal repro.*

virtualshell-1.0.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+virtualshell/__init__.py,sha256=8PE1B8yiMyZg2gwG18EvXt2vDEflvBeAdh7mNn58-GE,912
+virtualshell/_core.cp312-win_amd64.pyd,sha256=LMHw_C49UfHgPWcSK00Lem8QrIXyE_TUvaI_cWhTL-0,407040
+virtualshell/_version.py,sha256=ZgAXEMjAMZx3cZroB6PgojYwdhTZjPbU5RqZEfdYQv0,17
+virtualshell/errors.py,sha256=fDblFND_Lz37HV5l6eKCkWXvrPXnI9_FfZs0bpEYFIU,196
+virtualshell/shell.py,sha256=iHEFnbY3ggR2G-VpxAHrP3RVx3nYy1S2VxxLUTLRHa4,20915
+virtualshell-1.0.0.dist-info/METADATA,sha256=C0_uXHh7-Lxslvmqo8JBOW1M5gK8D1YieCEVQgWf21c,20087
+virtualshell-1.0.0.dist-info/WHEEL,sha256=chqeLhPBtPdrOoreR34YMcofSk3yWDQhkrsDJ2n48LU,106
+virtualshell-1.0.0.dist-info/licenses/LICENSE,sha256=34HMvl-jxuw-TVFRK7do9XGJkawVmiiwmPGFfZACBpI,11548
+virtualshell-1.0.0.dist-info/RECORD,,

virtualshell-0.1.2.dist-info/RECORD

@@ -1,9 +0,0 @@
-virtualshell/__init__.py,sha256=8PE1B8yiMyZg2gwG18EvXt2vDEflvBeAdh7mNn58-GE,912
-virtualshell/_core.cp312-win_amd64.pyd,sha256=YfykJq36il74NZVKxcpm3BEdeZdmQjJRTpWud_T41tI,407040
-virtualshell/_version.py,sha256=ZgAXEMjAMZx3cZroB6PgojYwdhTZjPbU5RqZEfdYQv0,17
-virtualshell/errors.py,sha256=fDblFND_Lz37HV5l6eKCkWXvrPXnI9_FfZs0bpEYFIU,196
-virtualshell/shell.py,sha256=gMknFPVMWpQzsEbc-JX9VD0xtPHkxz5SS5TU521lP0Q,20961
-virtualshell-0.1.2.dist-info/METADATA,sha256=qdLeHdMI-gCwyIrAwNeN5i1S1n7A0Z6ZB6b_56Ri5mM,23684
-virtualshell-0.1.2.dist-info/WHEEL,sha256=chqeLhPBtPdrOoreR34YMcofSk3yWDQhkrsDJ2n48LU,106
-virtualshell-0.1.2.dist-info/licenses/LICENSE,sha256=34HMvl-jxuw-TVFRK7do9XGJkawVmiiwmPGFfZACBpI,11548
-virtualshell-0.1.2.dist-info/RECORD,,