virtualshell 1.2.0__cp314-cp314-win_amd64.whl

virtualshell/__init__.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+
+# start delvewheel patch
+def _delvewheel_patch_1_13_1():
+    import os
+    if os.path.isdir(libs_dir := os.path.abspath(os.path.join(os.path.dirname(__file__), os.pardir, 'virtualshell.libs'))):
+        os.add_dll_directory(libs_dir)
+
+
+_delvewheel_patch_1_13_1()
+del _delvewheel_patch_1_13_1
+# end delvewheel patch
+
+from importlib import import_module
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .shell import ExecutionResult, BatchProgress, Shell, ExitCode, Config
+    from .zero_copy_bridge_shell import ZeroCopyBridge, PSObject
+
+try:
+    from ._version import version as __version__
+except Exception:
+    __version__ = "0.0.0"
+
+from .errors import (
+    VirtualShellError,
+    PowerShellNotFoundError,
+    ExecutionTimeoutError,
+    ExecutionError,
+)
+
+__all__ = [
+    "VirtualShellError", "PowerShellNotFoundError",
+    "ExecutionTimeoutError", "ExecutionError",
+    "__version__", "Shell", "ExecutionResult", "BatchProgress", "ExitCode", "Config",
+    "ZeroCopyBridge", "PSObject",
+]
+
+# Lazy loading of submodules and attributes to avoid importing compiled extension at package import time
+def __getattr__(name: str):
+    if name in {"Shell", "ExecutionResult", "BatchProgress", "ExitCode", "Config"}:
+        mod = import_module(".shell", __name__)
+        obj = getattr(mod, name)
+        globals()[name] = obj
+        return obj
+    if name in {"ZeroCopyBridge", "PSObject"}:
+        mod = import_module(".zero_copy_bridge_shell", __name__)
+        obj = getattr(mod, name)
+        globals()[name] = obj
+        return obj
+
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+def __dir__():
+    return sorted(__all__)

virtualshell/_bootstrap.py

@@ -0,0 +1,23 @@
+"""Guarded import of the compiled pybind11 extension.
+
+Importing the extension fails if it was never built, or was built for a
+different Python version or platform. Every import of it is funnelled
+through here so that failure surfaces as a single, actionable ImportError
+instead of a bare ``ModuleNotFoundError``.
+"""
+
+from __future__ import annotations
+
+import importlib
+from pathlib import Path
+from typing import Any
+
+_CORE_MODULE_NAME = f"{__package__}._core"
+
+try:
+    core: Any = importlib.import_module(_CORE_MODULE_NAME)
+except Exception as e:
+    raise ImportError(
+        f"Failed to import the compiled extension '{_CORE_MODULE_NAME}'. "
+        "Make sure it was built and matches this Python/platform."
+    ) from e

virtualshell/_module.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+import importlib
+from typing import TYPE_CHECKING
+
+_CORE_MODULE_NAME = f"{__package__}._core"
+
+try:
+    core = importlib.import_module(_CORE_MODULE_NAME)
+except Exception as e:
+    raise ImportError(
+        f"Failed to import the compiled extension '{_CORE_MODULE_NAME}'. "
+        "Make sure it was built and matches this Python/platform."
+    ) from e
+
+if TYPE_CHECKING:
+    from ._protocols import (
+        ExecutionResultLike as ExecutionResult,
+        BatchProgressLike as BatchProgress,
+        ConfigLike as Config,
+        VirtualShellLike as VirtualShell,
+    )
+else:
+    ExecutionResult = core.ExecutionResult
+    BatchProgress = core.BatchProgress
+    Config = core.Config
+    VirtualShell = core.VirtualShell

virtualshell/_protocols.py

@@ -0,0 +1,214 @@
+from __future__ import annotations
+
+from enum import IntEnum
+import sys
+
+from typing import (
+    Protocol, 
+    Any, 
+    Callable,
+    List,
+    Dict,
+    Self,
+    runtime_checkable,
+)
+from concurrent.futures import Future
+
+class ExitCode(IntEnum):
+    SUCCESS = 0
+    GENERAL_ERROR = 1
+    TIMEOUT = -1
+    RESTARTING = -2  # Internal use; not from PowerShell itself.
+    NOT_RUNNING = -3  # Internal use; not from PowerShell itself.
+
+@runtime_checkable
+class ExecutionResultLike(Protocol):
+    out: Any
+    err: Any
+    exit_code: ExitCode
+    success: bool
+    execution_time: float
+
+@runtime_checkable
+class BatchProgressLike(Protocol):
+    currentCommand: int
+    totalCommands: int
+    lastResult: ExecutionResultLike
+    isComplete: bool
+    allResults: List[ExecutionResultLike]
+
+    @property
+    def header_bytes(self) -> int: ...
+
+    @property
+    def frame_bytes(self) -> int: ...
+
+    def __init__(self) -> None:
+        ...
+
+@runtime_checkable
+class ConfigLike(Protocol):
+    powershell_path: str = "pwsh"
+    working_directory: str = ""
+    capture_output: bool = True
+    capture_error: bool = True
+    auto_restart_on_timeout: bool = True
+    timeout_seconds: int = 30
+    environment: dict[str, str]
+    initial_commands: List[str]
+    restore_script_path: str = ""
+    session_snapshot_path: str = ""
+    stdin_buffer_size: int = 64 * 1024
+
+
+    def __init__(self) -> None:
+        ...
+
+
+@runtime_checkable
+class VirtualShellLike(Protocol):
+    
+    # ---------------------------------------------------------
+    # Process control
+    # ---------------------------------------------------------
+    def start(self) -> bool:
+        ...
+
+    def stop(self, force: bool = False) -> None:
+        ...
+
+    def is_alive(self) -> bool:
+        ...
+
+    def is_restarting(self) -> bool:
+        ...
+
+    def get_process_id(self) -> int:
+        ...
+
+    # ---------------------------------------------------------
+    # Sync commands
+    # ---------------------------------------------------------
+    def execute(self, command: str, timeout_seconds: float = 0.0) -> ExecutionResultLike:
+        ...
+
+    def execute_batch(self, commands: List[str], timeout_seconds: float = 0.0) -> List[ExecutionResultLike]:
+        ...
+
+    def execute_script(
+        self, 
+        script_path: str, 
+        args: List[str] = ..., 
+        timeout_seconds: float = 0.0, 
+        dot_source: bool = False, 
+        raise_on_error: bool = False
+    ) -> ExecutionResultLike:
+        ...
+
+    def execute_script_kv(
+        self, 
+        script_path: str, 
+        named_args: Dict[str, str], 
+        timeout_seconds: float = 0.0, 
+        dot_source: bool = False, 
+        raise_on_error: bool = False
+    ) -> ExecutionResultLike:
+        ...
+
+    # ---------------------------------------------------------
+    # Async commands
+    # ---------------------------------------------------------
+    def execute_async(
+        self, 
+        command: str, 
+        callback: Callable[..., Any] | None = None, 
+        timeout_seconds: float = 0.0
+    ) -> Future[ExecutionResultLike]:
+        ...
+
+    def execute_async_batch(
+        self, 
+        commands: List[str], 
+        progress_callback: Callable[..., Any] | None = None, 
+        stop_on_first_error: bool = True, 
+        per_command_timeout_seconds: float = 0.0
+    ) -> Future[List[ExecutionResultLike]]:
+        ...
+
+    def execute_async_script(
+        self, 
+        script_path: str, 
+        args: List[str] = ..., 
+        callback: Callable[..., Any] | None = None, 
+        timeout_seconds: float = 0.0, 
+        dot_source: bool = False, 
+        raise_on_error: bool = False
+    ) -> Future[ExecutionResultLike]:
+        ...
+
+    def execute_async_script_kv(
+        self, 
+        script_path: str, 
+        named_args: Dict[str, str], 
+        timeout_seconds: float = 0.0, 
+        dot_source: bool = False, 
+        raise_on_error: bool = False
+    ) -> Future[ExecutionResultLike]:
+        ...
+
+    # ---------------------------------------------------------
+    # Direct I/O / env / modules
+    # ---------------------------------------------------------
+    def send_input(self, input: str) -> bool:
+        ...
+
+    def read_output(self, blocking: bool = False) -> str:
+        ...
+
+    def read_error(self, blocking: bool = False) -> str:
+        ...
+
+    def set_working_directory(self, directory: str) -> bool:
+        ...
+
+    def get_working_directory(self) -> str:
+        ...
+
+    def set_environment_variable(self, name: str, value: str) -> bool:
+        ...
+
+    def get_environment_variable(self, name: str) -> str:
+        ...
+
+    def is_module_available(self, module_name: str) -> bool:
+        ...
+
+    def import_module(self, module_name: str) -> bool:
+        ...
+
+    def get_powershell_version(self) -> str:
+        ...
+
+    def get_available_modules(self) -> List[str]:
+        ...
+
+    # ---------------------------------------------------------
+    # Configuration and Internals
+    # ---------------------------------------------------------
+    def get_config(self) -> ConfigLike:
+        ...
+
+    def update_config(self, config: ConfigLike) -> bool:
+        ...
+
+    def get_shared_ptr(self) -> Self:
+            ...
+
+    # ---------------------------------------------------------
+    # Context Manager
+    # ---------------------------------------------------------
+    def __enter__(self) -> "VirtualShellLike":
+        ...
+
+    def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        ...

virtualshell/_version.py

@@ -0,0 +1 @@
+version = "1.2.0"

virtualshell/errors.py

@@ -0,0 +1,4 @@
+class VirtualShellError(RuntimeError): ...
+class PowerShellNotFoundError(VirtualShellError): ...
+class ExecutionTimeoutError(VirtualShellError): ...
+class ExecutionError(VirtualShellError): ...