virtualshell 1.2.0__tar.gz → 1.2.1__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: virtualshell
-Version: 1.2.0
+Version: 1.2.1
 Summary: High-performance PowerShell bridge (C++ pybind11 backend)
 Keywords: powershell,automation,shell,cpp,pybind11
 Author: Kim-Andre Myrvold
@@ -393,6 +393,15 @@ with Shell() as sh:
     writer.Close()
 ```
 
+A bare `[Type]` literal binds the type itself, exposing its **static**
+methods, properties and constants:
+
+```python
+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:
 

{virtualshell-1.2.0 → virtualshell-1.2.1}/README.md

@@ -169,6 +169,15 @@ with Shell() as sh:
     writer.Close()
 ```
 
+A bare `[Type]` literal binds the type itself, exposing its **static**
+methods, properties and constants:
+
+```python
+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:
 

{virtualshell-1.2.0 → virtualshell-1.2.1}/cpp/src/binder.cpp

@@ -264,7 +264,7 @@ PYBIND11_MODULE(_core, m) {
     }, "Create a new VirtualShell instance", py::arg("config"));
 
     // Metadata
-    m.attr("__version__") = "1.2.0";
+    m.attr("__version__") = "1.2.1";
     m.attr("__author__")  = "Kim-Andre Myrvold";
 }
 

{virtualshell-1.2.0 → virtualshell-1.2.1}/pyproject.toml

@@ -9,7 +9,7 @@ build-backend = "scikit_build_core.build"
 [project]
 name = "virtualshell"
 description = "High-performance PowerShell bridge (C++ pybind11 backend)"
-version = "1.2.0"
+version = "1.2.1"
 readme = "README.md"
 license = { file = "LICENSE" }
 authors = [{ name = "Kim-Andre Myrvold" }]

virtualshell-1.2.1/src/virtualshell/_version.py

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

{virtualshell-1.2.0 → virtualshell-1.2.1}/src/virtualshell/generate_psobject.py

@@ -413,14 +413,17 @@ def _property_type(entry: MutableMapping[str, Any]) -> str:
     if isinstance(definition, list) and definition:
         definition = definition[0]
     if isinstance(definition, str):
-        token = definition.strip().split(" ", 1)[0]
+        # Static definitions read "static datetime Now {get;}".
+        text = re.sub(r"^\s*static\s+", "", definition.strip())
+        token = text.split(" ", 1)[0]
         if token and TYPE_LIKE_PATTERN.fullmatch(token):
             return token
     return ""
 
 
 def render_protocol(class_name: str, members: Iterable[MutableMapping[str, Any]], *,
-                    ps_type_name: str = "", ps_expression: str = "") -> str:
+                    ps_type_name: str = "", ps_expression: str = "",
+                    ps_static: bool = False) -> str:
     grouped = categorize_members(members)
     typing_bits: Set[str] = {"Protocol"}
     runtime_bits: Set[str] = set()
@@ -472,6 +475,8 @@ def render_protocol(class_name: str, members: Iterable[MutableMapping[str, Any]]
         meta_lines.append(f"    __ps_type_name__: ClassVar[str] = {ps_type_name!r}")
     if ps_expression:
         meta_lines.append(f"    __ps_expression__: ClassVar[str] = {ps_expression!r}")
+    if ps_static:
+        meta_lines.append("    __ps_static__: ClassVar[bool] = True")
     if meta_lines:
         typing_bits.add("ClassVar")
 
@@ -509,6 +514,21 @@ def render_protocol(class_name: str, members: Iterable[MutableMapping[str, Any]]
     return "\n".join(lines)
 
 
+def _decode_members(raw_text: str) -> List[MutableMapping[str, Any]]:
+    if not raw_text:
+        raise RuntimeError("Get-Member returned no data")
+    try:
+        members: Any = json.loads(raw_text)
+    except json.JSONDecodeError as exc:
+        raise RuntimeError("Failed to parse Get-Member output as JSON") from exc
+
+    if isinstance(members, MutableMapping):
+        members = [members]
+    if not members:
+        raise RuntimeError("Get-Member produced an empty result set")
+    return members
+
+
 def fetch_members(shell, command: str) -> Tuple[str, List[MutableMapping[str, Any]]]:
     shell.run("Remove-Variable obj -ErrorAction SilentlyContinue", raise_on_error=False)
     assignment = f"$obj = ({command})"
@@ -525,20 +545,28 @@ def fetch_members(shell, command: str) -> Tuple[str, List[MutableMapping[str, An
         "Get-Member -InputObject $obj | ConvertTo-Json -Depth 6 -Compress",
         raise_on_error=True,
     )
-    raw_text = (raw_result.out or "").strip()
-    if not raw_text:
-        raise RuntimeError("Get-Member returned no data")
+    return type_name, _decode_members((raw_result.out or "").strip())
 
-    try:
-        members: Any = json.loads(raw_text)
-    except json.JSONDecodeError as exc:
-        raise RuntimeError("Failed to parse Get-Member output as JSON") from exc
 
-    if isinstance(members, MutableMapping):
-        members = [members]
-    if not members:
-        raise RuntimeError("Get-Member produced an empty result set")
-    return type_name, members
+def fetch_static_members(shell, type_text: str) -> Tuple[str, List[MutableMapping[str, Any]]]:
+    """Static members of ``[type_text]``.
+
+    Piping (not -InputObject) matters here: Get-Member special-cases a piped
+    System.Type with -Static and reports that type's own static members.
+    """
+    shell.run("Remove-Variable obj -ErrorAction SilentlyContinue", raise_on_error=False)
+    shell.run(f"$obj = [{type_text}]", raise_on_error=True)
+
+    type_result = shell.run("[string]$obj.FullName", raise_on_error=True)
+    type_name = (type_result.out or "").strip()
+    if not type_name:
+        raise RuntimeError("Type reports no name")
+
+    raw_result = shell.run(
+        "$obj | Get-Member -Static | ConvertTo-Json -Depth 6 -Compress",
+        raise_on_error=True,
+    )
+    return type_name, _decode_members((raw_result.out or "").strip())
 
 
 def safe_class_name(type_name: str) -> str:
@@ -556,13 +584,32 @@ def generate(shell, obj: str, output_path: Path) -> None:
     shell.run("$PSStyle.OutputRendering = 'PlainText'", raise_on_error=False)
     shell.run("$OutputEncoding = [Console]::OutputEncoding = [Text.UTF8Encoding]::new()", raise_on_error=False)
 
-    from .ps_proxy import build_creation_strategies
+    from .ps_proxy import build_creation_strategies, static_type_literal
 
     strategies = build_creation_strategies(obj)
     errors: List[str] = []
     chosen: Optional[Tuple[str, str, str, List[MutableMapping[str, Any]]]] = None
 
     try:
+        static_inner = static_type_literal(obj)
+        if static_inner is not None:
+            try:
+                type_name, members = fetch_static_members(shell, static_inner)
+            except Exception as ex:
+                raise RuntimeError(
+                    f"Unable to materialise a static type from '{obj}': {ex}") from ex
+            expression = f"[{static_inner}]"
+            # Name the class after the caller's spelling: the reflected
+            # FullName of a closed generic is assembly-qualified soup.
+            protocol_name = safe_class_name(static_inner)
+            source = render_protocol(protocol_name, members,
+                                     ps_type_name=type_name,
+                                     ps_expression=expression, ps_static=True)
+            output_path.write_text(source, encoding="utf-8")
+            print(f"Generated {output_path} for static {type_name} "
+                  f"(expression: {expression})")
+            return
+
         for label, candidate in strategies:
             try:
                 type_name, members = fetch_members(shell, candidate)

{virtualshell-1.2.0 → virtualshell-1.2.1}/src/virtualshell/ps_proxy.py

@@ -66,6 +66,53 @@ def _method_call_expr(ref: str, name: str, args: List[str]) -> str:
     return f"{ref}.PSObject.Methods[{_ps_quote(name)}].Invoke({arg_text})"
 
 
+# `ref` holds a [type] object in static mode; PowerShell resolves `::` against
+# the contained type, so `$t = [Math]; $t::Sqrt(16)` works like `[Math]::Sqrt`.
+_STATIC_BINDING_FLAGS = "[System.Reflection.BindingFlags]'Public,Static"
+
+
+def _static_member_expr(ref: str, name: str) -> str:
+    """Expression reading static member `name` on the type held by `ref`."""
+    if _IDENT_RE.match(name):
+        return f"{ref}::{name}"
+    return (f"{ref}.InvokeMember({_ps_quote(name)}, "
+            f"{_STATIC_BINDING_FLAGS},GetProperty,GetField', $null, $null, @())")
+
+
+def _static_method_call_expr(ref: str, name: str, args: List[str]) -> str:
+    arg_text = ", ".join(args)
+    if _IDENT_RE.match(name):
+        return f"{ref}::{name}({arg_text})"
+    return (f"{ref}.InvokeMember({_ps_quote(name)}, "
+            f"{_STATIC_BINDING_FLAGS},InvokeMethod', $null, $null, @({arg_text}))")
+
+
+def static_type_literal(expr: str) -> Optional[str]:
+    """Return the type name inside a bare ``[Type]`` literal, else None.
+
+    A bare literal (nothing outside the brackets) is how callers name a
+    static class, e.g. ``[System.Windows.Forms.MessageBox]``. Invocations
+    (``[T]::new()``) and casts (``[int](3)``) do not match, and neither do
+    unbalanced brackets, so generic literals like
+    ``[System.Collections.Generic.List[int]]`` resolve correctly.
+    """
+    cleaned = (expr or "").strip()
+    if len(cleaned) < 3 or not (cleaned.startswith("[") and cleaned.endswith("]")):
+        return None
+    inner = cleaned[1:-1].strip()
+    if not inner or not _TYPE_LIKE_RE.fullmatch(inner):
+        return None
+    depth = 0
+    for char in inner:
+        if char == "[":
+            depth += 1
+        elif char == "]":
+            depth -= 1
+            if depth < 0:
+                return None
+    return inner if depth == 0 else None
+
+
 def split_invocation(expr: str) -> Optional[Tuple[str, str]]:
     """Return (target, argument_text) when `expr` ends with a (...) call."""
     depth = 0
@@ -243,6 +290,60 @@ $__vs_sm = @($__vs_o.PSObject.Members |
 """.strip()
 
 
+# Static-mode counterpart: {ref} holds a [type] object, so reflection runs on
+# the type itself (not GetType(), which would describe RuntimeType). Constants
+# and static fields surface as properties; writability follows the setter /
+# IsInitOnly / IsLiteral rules.
+_STATIC_SCHEMA_SCRIPT = """
+$__vs_o = {ref}
+$__vs_flags = [System.Reflection.BindingFlags]'Public,Static'
+$__vs_props = @()
+foreach ($__vs_pi in $__vs_o.GetProperties($__vs_flags)) {{
+    $__vs_props += [pscustomobject]@{{
+        n = $__vs_pi.Name
+        t = [string]$__vs_pi.PropertyType.FullName
+        w = ($null -ne $__vs_pi.SetMethod)
+    }}
+}}
+foreach ($__vs_fi in $__vs_o.GetFields($__vs_flags)) {{
+    $__vs_props += [pscustomobject]@{{
+        n = $__vs_fi.Name
+        t = [string]$__vs_fi.FieldType.FullName
+        w = (-not ($__vs_fi.IsInitOnly -or $__vs_fi.IsLiteral))
+    }}
+}}
+$__vs_meths = @()
+try {{
+    $__vs_groups = $__vs_o.GetMethods($__vs_flags) |
+        Where-Object {{ -not $_.IsSpecialName }} |
+        Group-Object Name
+}} catch {{ $__vs_groups = @() }}
+foreach ($__vs_g in $__vs_groups) {{
+    $__vs_ovl = @(foreach ($__vs_mi in $__vs_g.Group) {{
+        [pscustomobject]@{{
+            r = $__vs_mi.ReturnType.FullName
+            p = @(foreach ($__vs_pp in $__vs_mi.GetParameters()) {{
+                [pscustomobject]@{{
+                    n = $__vs_pp.Name
+                    t = $__vs_pp.ParameterType.FullName
+                    o = $__vs_pp.IsOut
+                    rf = $__vs_pp.ParameterType.IsByRef
+                    a = $__vs_pp.ParameterType.IsArray
+                }}
+            }})
+        }}
+    }})
+    $__vs_meths += ,([pscustomobject]@{{ n = $__vs_g.Name; o = $__vs_ovl }})
+}}
+[pscustomobject]@{{
+    tn = [string]$__vs_o.FullName
+    props = $__vs_props
+    meths = $__vs_meths
+    sm = @()
+}} | ConvertTo-Json -Depth 8 -Compress
+""".strip()
+
+
 def _parse_schema(payload: Dict[str, Any]) -> Schema:
     schema = Schema(type_name=str(payload.get("tn") or "System.Object"))
 
@@ -360,6 +461,10 @@ class PsProxy:
 
     Attribute access reads/writes properties and calls methods on the
     underlying object inside the PowerShell session.
+
+    A bare ``[Type]`` literal (or ``static=True``) selects static mode: the
+    proxy binds the type itself and exposes its static methods, properties
+    and constants, invoked with ``::`` in the session.
     """
 
     def __init__(
@@ -369,6 +474,7 @@ class PsProxy:
         object_ref: str = "$obj",
         *,
         timeout: Optional[float] = None,
+        static: bool = False,
     ) -> None:
         object.__setattr__(self, "_shell", shell)
         object.__setattr__(self, "_timeout", timeout)
@@ -384,10 +490,17 @@ class PsProxy:
         if not ref:
             raise ValueError("object_ref or type_name is required")
 
+        literal = static_type_literal(ref)
+        object.__setattr__(self, "_static", bool(static) or literal is not None)
+
         if ref.startswith("$"):
             self._validate_ref(ref)
             object.__setattr__(self, "_ref", ref)
             object.__setattr__(self, "_owns_ref", False)
+        elif self._static:
+            inner = literal if literal is not None else ref
+            object.__setattr__(self, "_ref", self._materialize_static(inner))
+            object.__setattr__(self, "_owns_ref", True)
         else:
             object.__setattr__(self, "_ref", self._materialize(ref))
             object.__setattr__(self, "_owns_ref", True)
@@ -404,6 +517,18 @@ class PsProxy:
         return (res.out or "").strip()
 
     def _validate_ref(self, ref: str) -> None:
+        if self._static:
+            out = self._run(
+                f"if ({ref} -is [type]) {{ 'ok' }} "
+                f"elseif ($null -eq {ref}) {{ 'null' }} else {{ 'notatype' }}",
+                label=f"Binding to {ref}")
+            if out == "null":
+                raise ValueError(f"PowerShell variable {ref} is null or undefined")
+            if out != "ok":
+                raise ValueError(
+                    f"PowerShell variable {ref} does not hold a [type]; "
+                    "a static proxy must bind a type object")
+            return
         out = self._run(
             f"if ($null -eq {ref}) {{ 'null' }} else {{ 'ok' }}",
             label=f"Binding to {ref}")
@@ -434,13 +559,34 @@ class PsProxy:
             f"Failed to create PowerShell object from {expression!r}. Tried:\n  "
             + "\n  ".join(errors))
 
+    def _materialize_static(self, type_text: str) -> str:
+        """Bind a ``[Type]`` literal to a session variable (static mode)."""
+        inner = type_text.strip()
+        if inner.startswith("[") and inner.endswith("]"):
+            inner = inner[1:-1].strip()
+        if not inner or not _TYPE_LIKE_RE.fullmatch(inner):
+            raise ValueError(f"Cannot resolve a static type from {type_text!r}")
+
+        var = _next_var("proxy")
+        res = self._shell.run(f"${var} = [{inner}]", timeout=self._timeout)
+        if res.success:
+            check = self._shell.run(
+                f"if (${var} -is [type]) {{ 'ok' }} else {{ 'no' }}",
+                timeout=self._timeout)
+            if check.success and (check.out or "").strip() == "ok":
+                return f"${var}"
+        raise RuntimeError(
+            f"Failed to resolve static type [{inner}]: "
+            f"{(res.err or '').strip()[:200] or 'expression did not yield a type'}")
+
     def _load_schema(self, provided_type: str) -> Schema:
         run_id = self._shell.python_run_id
 
         # A provided type name is only trusted as a cache key after we have
         # resolved it once; the real type name always comes from the object.
+        script = _STATIC_SCHEMA_SCRIPT if self._static else _SCHEMA_SCRIPT
         out = self._run(
-            _SCHEMA_SCRIPT.format(ref=self._ref),
+            script.format(ref=self._ref),
             label=f"Schema query for {self._ref}")
         try:
             payload = json.loads(out)
@@ -449,8 +595,11 @@ class PsProxy:
                 f"Schema query for {self._ref} returned invalid JSON") from exc
 
         schema = _parse_schema(payload)
+        # Static schemas get their own key: the same type can also have an
+        # instance schema, and _sub_proxy looks instance schemas up by name.
+        key = f"static:{schema.type_name}" if self._static else schema.type_name
         with _SCHEMA_LOCK:
-            _SCHEMA_CACHE[(run_id, schema.type_name)] = schema
+            _SCHEMA_CACHE[(run_id, key)] = schema
         return schema
 
     @classmethod
@@ -466,6 +615,8 @@ class PsProxy:
         object.__setattr__(proxy, "_method_cache", {})
         object.__setattr__(proxy, "_ref", ref)
         object.__setattr__(proxy, "_owns_ref", True)
+        # Values returned from calls are instances, never types.
+        object.__setattr__(proxy, "_static", False)
 
         cached = self._cached_schema(self._shell.python_run_id, type_name)
         if cached is not None:
@@ -590,9 +741,10 @@ class PsProxy:
             method_cache[name] = bound
             return bound
         if name in schema.properties:
+            expr = (_static_member_expr(self._ref, name) if self._static
+                    else _member_expr(self._ref, name))
             return self._fetch_value(
-                _member_expr(self._ref, name),
-                label=f"Read property {schema.type_name}.{name}")
+                expr, label=f"Read property {schema.type_name}.{name}")
         if name in dynamic:
             return dynamic[name]
         raise AttributeError(
@@ -610,11 +762,16 @@ class PsProxy:
             meta = schema.properties[name]
             if not meta.writable:
                 raise AttributeError(f"Property {name!r} is read-only")
+            if self._static and not _IDENT_RE.match(name):
+                raise AttributeError(
+                    f"Cannot write static member {name!r}: not an identifier")
+            target = (_static_member_expr(self._ref, name) if self._static
+                      else _member_expr(self._ref, name))
             cleanup: List[str] = []
             try:
                 rhs = self._format_argument(value, cleanup=cleanup)
                 self._run(
-                    f"{_member_expr(self._ref, name)} = {rhs}",
+                    f"{target} = {rhs}",
                     label=f"Set property {schema.type_name}.{name}")
             finally:
                 self._cleanup_vars(cleanup)
@@ -632,7 +789,8 @@ class PsProxy:
         return sorted(names)
 
     def __repr__(self) -> str:
-        return f"<PsProxy type='{self._schema.type_name}' ref='{self._ref}'>"
+        kind = "static type" if self._static else "type"
+        return f"<PsProxy {kind}='{self._schema.type_name}' ref='{self._ref}'>"
 
     # -- methods ---------------------------------------------------------------
 
@@ -679,7 +837,10 @@ class PsProxy:
                     ps_args.append(self._format_argument(value,
                                                          cleanup=cleanup))
 
-            call = _method_call_expr(self._ref, meta.name, ps_args)
+            if self._static:
+                call = _static_method_call_expr(self._ref, meta.name, ps_args)
+            else:
+                call = _method_call_expr(self._ref, meta.name, ps_args)
             return_type = overload.return_type if overload else ""
             if _AWAITABLE_RE.search(return_type):
                 call = f"({call}).GetAwaiter().GetResult()"
@@ -754,7 +915,11 @@ class PsProxy:
                 for one_call in call_args[start:start + batch_size]:
                     ps_args = [self._format_argument(a, cleanup=cleanup)
                                for a in one_call]
-                    call = _method_call_expr(self._ref, method_name, ps_args)
+                    if self._static:
+                        call = _static_method_call_expr(
+                            self._ref, method_name, ps_args)
+                    else:
+                        call = _method_call_expr(self._ref, method_name, ps_args)
                     lines.append(f"$__vs_mc.Add(({call}))")
                 lines.append(
                     "ConvertTo-Json -InputObject $__vs_mc -Depth 4 -Compress")

{virtualshell-1.2.0 → virtualshell-1.2.1}/src/virtualshell/shell.py

@@ -492,12 +492,15 @@ class Shell:
             return self._zcb
 
     @overload
-    def make_proxy(self, type_name: str, obj_ref: Optional[str] = None) -> "PsProxy": ...
+    def make_proxy(self, type_name: str, obj_ref: Optional[str] = None,
+                   *, static: bool = False) -> "PsProxy": ...
 
     @overload
-    def make_proxy(self, type_name: Type[_ProxyProtocol], obj_ref: Optional[str] = None) -> _ProxyProtocol: ...
+    def make_proxy(self, type_name: Type[_ProxyProtocol], obj_ref: Optional[str] = None,
+                   *, static: bool = False) -> _ProxyProtocol: ...
 
-    def make_proxy(self, type_name: Union[str, Type[Any]], obj_ref: Optional[str] = None) -> Any:
+    def make_proxy(self, type_name: Union[str, Type[Any]], obj_ref: Optional[str] = None,
+                   *, static: bool = False) -> Any:
         """Create a live proxy for a PowerShell object.
 
         Two call forms:
@@ -509,6 +512,11 @@ class Shell:
           recreates the object, and the return value is typed as the protocol
           so no annotation is needed. Pass `obj_ref` (e.g. "$existing") to
           bind an existing variable instead of creating a new object.
+
+        A bare type literal such as ``make_proxy("", "[System.IO.Path]")``
+        yields a *static* proxy exposing the type's static methods,
+        properties and constants. `static=True` forces static mode for an
+        unbracketed type name or a ``$variable`` that holds a type object.
         """
         from .ps_proxy import PsProxy
 
@@ -520,9 +528,12 @@ class Shell:
                 raise TypeError(
                     f"{proto.__name__} carries no __ps_type_name__/__ps_expression__ "
                     "metadata; regenerate it with generate_psobject")
-            return PsProxy(self, ps_type, obj_ref if obj_ref is not None else expression)
+            is_static = static or bool(getattr(proto, "__ps_static__", False))
+            return PsProxy(self, ps_type, obj_ref if obj_ref is not None else expression,
+                           static=is_static)
 
-        return PsProxy(self, type_name, obj_ref if obj_ref is not None else "$obj")
+        return PsProxy(self, type_name, obj_ref if obj_ref is not None else "$obj",
+                       static=static)
 
     def generate_psobject(self, command: str, output_path: Path) -> None:
         """Generate a PowerShell object from a command."""

{virtualshell-1.2.0 → virtualshell-1.2.1}/tests/test_generate_psobject.py

@@ -7,6 +7,7 @@ import shutil
 import pytest
 
 from virtualshell.generate_psobject import (
+    _property_type,
     build_method_signatures,
     categorize_members,
     first_signature,
@@ -253,6 +254,38 @@ class TestRenderProtocol:
     def test_no_metadata_classvars_by_default(self):
         source = render_protocol("MyProxy", self.MEMBERS)
         assert "__ps_type_name__" not in source
+        assert "__ps_static__" not in source
+
+
+class TestStaticRendering:
+    # Shaped like `[System.Math] | Get-Member -Static | ConvertTo-Json`.
+    MEMBERS = [
+        {"Name": "PI", "MemberType": 4,
+         "Definition": "static double PI {get;}"},
+        {"Name": "Sqrt", "MemberType": 64,
+         "Definition": "static double Sqrt(double d)"},
+    ]
+
+    def test_static_property_type_strips_prefix(self):
+        assert _property_type(
+            {"Definition": "static datetime Now {get;}"}) == "datetime"
+        # Instance definitions are unaffected.
+        assert _property_type({"Definition": "int Year {get;}"}) == "int"
+
+    def test_ps_static_classvar_embedded(self):
+        source = render_protocol(
+            "Math", self.MEMBERS,
+            ps_type_name="System.Math", ps_expression="[System.Math]",
+            ps_static=True)
+        compile(source, "<generated>", "exec")
+        assert "__ps_static__: ClassVar[bool] = True" in source
+        assert "__ps_expression__: ClassVar[str] = '[System.Math]'" in source
+
+    def test_static_members_render_with_real_types(self):
+        source = render_protocol("Math", self.MEMBERS, ps_static=True)
+        compile(source, "<generated>", "exec")
+        assert "def PI(self) -> float: ..." in source
+        assert "def Sqrt(self, d: float) -> float: ..." in source
 
 
 # =============================================================================
@@ -367,3 +400,37 @@ class TestGenerateEndToEnd:
         bound = shell.make_proxy(StringBuilder, "$vs_gen_bind")
         bound.Append("bundet")
         assert shell.run("$vs_gen_bind.ToString()").out.strip() == "bundet"
+
+    def test_generate_static_type(self, shell, tmp_path):
+        from virtualshell.generate_psobject import generate
+
+        out_file = tmp_path / "math_static.py"
+        generate(shell, "[System.Math]", out_file)
+        source = out_file.read_text(encoding="utf-8")
+
+        compile(source, str(out_file), "exec")
+        assert "class Math(Protocol):" in source
+        assert "__ps_static__: ClassVar[bool] = True" in source
+        assert "__ps_expression__: ClassVar[str] = '[System.Math]'" in source
+        assert "def Sqrt(self" in source
+        assert "def PI(self) -> float: ..." in source
+
+    def test_make_proxy_from_generated_static_protocol(self, shell, tmp_path):
+        """generate -> import -> make_proxy(StaticProtocol) round trip."""
+        import importlib.util
+
+        from virtualshell.generate_psobject import generate
+
+        out_file = tmp_path / "math_protocol.py"
+        generate(shell, "[System.Math]", out_file)
+
+        spec = importlib.util.spec_from_file_location("math_protocol", out_file)
+        module = importlib.util.module_from_spec(spec)
+        spec.loader.exec_module(module)
+        Math = module.Math
+
+        assert Math.__ps_static__ is True
+
+        m = shell.make_proxy(Math)
+        assert m.Sqrt(16.0) == 4.0
+        assert abs(m.PI - 3.141592653589793) < 1e-12

{virtualshell-1.2.0 → virtualshell-1.2.1}/tests/test_ps_proxy_integration.py

@@ -305,3 +305,93 @@ class TestMultiCall:
         al = shell.make_proxy("", "System.Collections.ArrayList")
         with pytest.raises(TypeError):
             al.proxy_multi_call(len, 3)
+
+
+class TestStaticProxies:
+    def test_type_literal_selects_static_mode(self, shell):
+        m = shell.make_proxy("", "[System.Math]")
+        assert m.type_name == "System.Math"
+        assert "static" in repr(m)
+        assert m.Sqrt(16.0) == 4.0
+        assert m.Max(3, 7) == 7
+
+    def test_constant_field_reads_as_property(self, shell):
+        m = shell.make_proxy("", "[System.Math]")
+        assert abs(m.PI - 3.141592653589793) < 1e-12
+
+    def test_static_method_with_string_args(self, shell):
+        p = shell.make_proxy("", "[System.IO.Path]")
+        assert p.Combine("a", "b") in ("a\\b", "a/b")
+
+    def test_static_datetime_roundtrip(self, shell):
+        from datetime import datetime
+
+        dt = shell.make_proxy("", "[datetime]")
+        parsed = dt.Parse("2024-01-02T03:04:05")
+        assert parsed == datetime(2024, 1, 2, 3, 4, 5)
+
+    def test_enum_values_read_as_strings(self, shell):
+        dow = shell.make_proxy("", "[System.DayOfWeek]")
+        assert dow.Monday == "Monday"
+
+    def test_writable_static_property_and_const(self, shell):
+        shell.run(
+            "Add-Type -TypeDefinition 'public static class VsStaticTest { "
+            "public static int Counter { get; set; } "
+            "public static string Echo(string s) { return s + \"!\"; } "
+            "public const double Ratio = 2.5; }'",
+            raise_on_error=True)
+        t = shell.make_proxy("", "[VsStaticTest]")
+        t.Counter = 5
+        assert t.Counter == 5
+        assert t.Echo("hei") == "hei!"
+        assert t.Ratio == 2.5
+        with pytest.raises(AttributeError, match="read-only"):
+            t.Ratio = 3.0
+
+    def test_static_true_with_unbracketed_name(self, shell):
+        m = shell.make_proxy("", "System.Math", static=True)
+        assert m.Sqrt(9.0) == 3.0
+
+    def test_static_true_binds_existing_type_variable(self, shell):
+        shell.run("$vs_static_t = [System.Math]", raise_on_error=True)
+        m = shell.make_proxy("", "$vs_static_t", static=True)
+        assert m.Sqrt(25.0) == 5.0
+
+    def test_static_true_rejects_non_type_variable(self, shell):
+        shell.run("$vs_not_a_type = 42", raise_on_error=True)
+        with pytest.raises(ValueError, match="does not hold"):
+            shell.make_proxy("", "$vs_not_a_type", static=True)
+
+    def test_unknown_static_type_raises(self, shell):
+        with pytest.raises(RuntimeError, match="Failed to resolve static type"):
+            shell.make_proxy("", "[No.Such.Type.Exists]")
+
+    def test_instance_members_absent_from_static_schema(self, shell):
+        m = shell.make_proxy("", "[System.Text.StringBuilder]")
+        names = {x["Name"] for x in m.proxy_schema()["Methods"]}
+        # ToString is an instance method; a static proxy must not offer it.
+        assert "ToString" not in names
+
+    def test_static_and_instance_schemas_coexist(self, shell):
+        from virtualshell.ps_proxy import _SCHEMA_CACHE
+        shell.make_proxy("", "[System.Text.StringBuilder]")
+        shell.make_proxy("", "System.Text.StringBuilder")
+        run_id = shell.python_run_id
+        assert (run_id, "System.Text.StringBuilder") in _SCHEMA_CACHE
+        assert (run_id, "static:System.Text.StringBuilder") in _SCHEMA_CACHE
+
+    def test_static_multi_call(self, shell):
+        m = shell.make_proxy("", "[System.Math]")
+        assert m.proxy_multi_call(m.Sqrt, [4.0, 9.0, 16.0]) == [2.0, 3.0, 4.0]
+
+    def test_messagebox_scenario_schema(self, shell):
+        """The motivating case: a WinForms MessageBox static proxy exposes
+        Show without being called (calling it would block on a modal)."""
+        res = shell.run("Add-Type -AssemblyName System.Windows.Forms")
+        if not res.success:
+            pytest.skip("System.Windows.Forms not available")
+        mb = shell.make_proxy("", "[System.Windows.Forms.MessageBox]")
+        assert mb.type_name == "System.Windows.Forms.MessageBox"
+        names = {x["Name"] for x in mb.proxy_schema()["Methods"]}
+        assert "Show" in names

{virtualshell-1.2.0 → virtualshell-1.2.1}/tests/test_ps_proxy_unit.py

@@ -14,8 +14,11 @@ from virtualshell.ps_proxy import (
     _parse_iso_datetime,
     _parse_schema,
     _ps_quote,
+    _static_member_expr,
+    _static_method_call_expr,
     build_creation_strategies,
     split_invocation,
+    static_type_literal,
 )
 
 
@@ -49,6 +52,56 @@ class TestExpressions:
         assert expr == "$x.PSObject.Methods['my method'].Invoke(1, 2)"
 
 
+class TestStaticExpressions:
+    def test_static_member(self):
+        assert _static_member_expr("$t", "PI") == "$t::PI"
+
+    def test_static_member_with_special_name_uses_reflection(self):
+        expr = _static_member_expr("$t", "weird name")
+        assert "InvokeMember('weird name'" in expr
+        assert "GetProperty,GetField" in expr
+
+    def test_static_call(self):
+        assert _static_method_call_expr("$t", "Sqrt", ["16"]) == "$t::Sqrt(16)"
+
+    def test_static_call_with_special_name_uses_reflection(self):
+        expr = _static_method_call_expr("$t", "my method", ["1", "2"])
+        assert "InvokeMember('my method'" in expr
+        assert "InvokeMethod" in expr
+        assert "@(1, 2)" in expr
+
+
+class TestStaticTypeLiteral:
+    def test_bare_literal(self):
+        assert static_type_literal("[System.Math]") == "System.Math"
+
+    def test_whitespace_tolerated(self):
+        assert static_type_literal("  [System.IO.Path] ") == "System.IO.Path"
+
+    def test_generic_literal(self):
+        assert (static_type_literal("[System.Collections.Generic.List[int]]")
+                == "System.Collections.Generic.List[int]")
+
+    def test_plain_type_name_is_not_a_literal(self):
+        assert static_type_literal("System.Math") is None
+
+    def test_invocation_is_not_a_literal(self):
+        assert static_type_literal("[System.Text.StringBuilder]::new(3)") is None
+
+    def test_cast_is_not_a_literal(self):
+        assert static_type_literal("[int](3)") is None
+
+    def test_variable_is_not_a_literal(self):
+        assert static_type_literal("$var") is None
+
+    def test_unbalanced_brackets_rejected(self):
+        assert static_type_literal("[int][string]") is None
+
+    def test_empty_and_tiny_inputs(self):
+        assert static_type_literal("") is None
+        assert static_type_literal("[]") is None
+
+
 class TestSplitInvocation:
     def test_ctor_like(self):
         assert split_invocation("System.Text.StringBuilder(16)") == (

{virtualshell-1.2.0 → virtualshell-1.2.1}/tests/test_shell_unit.py

@@ -293,14 +293,17 @@ class TestConvenience:
         created = {}
 
         class StubProxy:
-            def __init__(self, shell, type_name, object_ref):
-                created["args"] = (shell, type_name, object_ref)
+            def __init__(self, shell, type_name, object_ref, *, static=False):
+                created["args"] = (shell, type_name, object_ref, static)
 
         monkeypatch.setattr(ps_proxy_module, "PsProxy", StubProxy)
         sh = Shell(cpp_module=fake_core).start()
         proxy = sh.make_proxy("System.IO.FileInfo", "$file")
         assert isinstance(proxy, StubProxy)
-        assert created["args"] == (sh, "System.IO.FileInfo", "$file")
+        assert created["args"] == (sh, "System.IO.FileInfo", "$file", False)
+
+        sh.make_proxy("System.Math", "$t", static=True)
+        assert created["args"] == (sh, "System.Math", "$t", True)
 
     def test_make_proxy_accepts_generated_protocol_class(self, fake_core, monkeypatch):
         import virtualshell.ps_proxy as ps_proxy_module
@@ -308,8 +311,8 @@ class TestConvenience:
         created = {}
 
         class StubProxy:
-            def __init__(self, shell, type_name, object_ref):
-                created["args"] = (type_name, object_ref)
+            def __init__(self, shell, type_name, object_ref, *, static=False):
+                created["args"] = (type_name, object_ref, static)
 
         class StringBuilder:  # shaped like generate_psobject output
             __ps_type_name__ = "System.Text.StringBuilder"
@@ -321,11 +324,35 @@ class TestConvenience:
         # Default: recreate the object from the embedded expression.
         sh.make_proxy(StringBuilder)
         assert created["args"] == ("System.Text.StringBuilder",
-                                   "[System.Text.StringBuilder]::new()")
+                                   "[System.Text.StringBuilder]::new()", False)
 
         # Explicit obj_ref binds an existing variable instead.
         sh.make_proxy(StringBuilder, "$existing")
-        assert created["args"] == ("System.Text.StringBuilder", "$existing")
+        assert created["args"] == ("System.Text.StringBuilder", "$existing", False)
+
+    def test_make_proxy_honours_static_protocol_metadata(self, fake_core, monkeypatch):
+        import virtualshell.ps_proxy as ps_proxy_module
+
+        created = {}
+
+        class StubProxy:
+            def __init__(self, shell, type_name, object_ref, *, static=False):
+                created["args"] = (type_name, object_ref, static)
+
+        class Math:  # shaped like generate_psobject output for '[System.Math]'
+            __ps_type_name__ = "System.Math"
+            __ps_expression__ = "[System.Math]"
+            __ps_static__ = True
+
+        monkeypatch.setattr(ps_proxy_module, "PsProxy", StubProxy)
+        sh = Shell(cpp_module=fake_core).start()
+
+        sh.make_proxy(Math)
+        assert created["args"] == ("System.Math", "[System.Math]", True)
+
+        # Static metadata sticks when binding an existing type variable.
+        sh.make_proxy(Math, "$existing_type")
+        assert created["args"] == ("System.Math", "$existing_type", True)
 
     def test_make_proxy_rejects_class_without_metadata(self, fake_core):
         class Naked:

{virtualshell-1.2.0 → virtualshell-1.2.1}/wiki/Usage/API Overview.md

@@ -18,7 +18,7 @@
 - `pwsh(s: str, timeout: float|None=None, raise_on_error=False) -> ExecutionResult`  _(executes a **literal** string safely)_
 - `save_session(timeout: float|None=None, raise_on_error=True) -> ExecutionResult`
 - `restore_session(snapshot_path: str|Path, timeout: float|None=None, raise_on_error=True) -> ExecutionResult`
-- `make_proxy(type_name: str, obj_ref: str = "$obj") -> PsProxy`  _(live object proxy; `obj_ref` is a `$variable` or a creation expression)_
+- `make_proxy(type_name: str, obj_ref: str = "$obj", *, static: bool = False) -> PsProxy`  _(live object proxy; `obj_ref` is a `$variable`, a creation expression, or a `[Type]` literal for a static proxy)_
 - `generate_psobject(type_expression: str, output_path: str|Path) -> None`
 - `zero_copy_bridge(frame_mb: int = 16, chunk_mb: int = 4) -> ZeroCopyBridge`  _(shared per-shell bridge, created lazily)_
 

{virtualshell-1.2.0 → virtualshell-1.2.1}/wiki/Usage/generate_psobject.md

@@ -57,6 +57,26 @@ metadata, which is what lets `make_proxy(WebClient)` recreate the object
 without repeating the PowerShell expression. Pass an explicit variable to
 bind instead: `shell.make_proxy(WebClient, "$client")`.
 
+## Static Classes
+
+Passing a bare `[Type]` literal generates a protocol for the type's
+**static** surface instead (collected with `Get-Member -Static`):
+
+```python
+shell.generate_psobject("[System.Math]", Path("Math.py"))
+```
+
+The generated class additionally embeds ``__ps_static__ = True``, so
+`make_proxy(Math)` binds a [static proxy](make_proxy.md#static-classes)
+automatically:
+
+```python
+from Math import Math
+
+math = shell.make_proxy(Math)
+math.Sqrt(16.0)     # 4.0 - with full IDE completion
+```
+
 The protocol only describes the members discovered at generation time. If the PowerShell type changes or you need a different view, rerun `generate_psobject` with the updated command.
 
 ### End-to-End Example

{virtualshell-1.2.0 → virtualshell-1.2.1}/wiki/Usage/make_proxy.md

@@ -7,14 +7,15 @@ The proxy is implemented in pure Python and works on Windows, Linux and macOS. B
 ## Signature
 
 ```python
-proxy = shell.make_proxy(type_name: str, obj_ref: str | None = None)
-proxy = shell.make_proxy(GeneratedProtocol, obj_ref: str | None = None)
+proxy = shell.make_proxy(type_name: str, obj_ref: str | None = None, *, static: bool = False)
+proxy = shell.make_proxy(GeneratedProtocol, obj_ref: str | None = None, *, static: bool = False)
 ```
 
 | Parameter | Description |
 |-----------|-------------|
 | `type_name` | Optional label (`""` is fine — the real type is resolved from the live object), **or** a Protocol class produced by `generate_psobject`. |
-| `obj_ref` | Either an existing PowerShell variable (`"$client"`), or a **creation expression** such as `"System.Text.StringBuilder(32)"`. Creation tries `[Type]::new(...)`, `New-Object`, and COM instantiation in order. |
+| `obj_ref` | Either an existing PowerShell variable (`"$client"`), or a **creation expression** such as `"System.Text.StringBuilder(32)"`. Creation tries `[Type]::new(...)`, `New-Object`, and COM instantiation in order. A bare type literal (`"[System.IO.Path]"`) selects [static mode](#static-classes). |
+| `static` | Force static mode for an unbracketed type name or a `$variable` that holds a type object. |
 
 With a generated Protocol class as the first argument, the object is created
 from the metadata embedded in the class, and the return value is typed as the
@@ -49,6 +50,45 @@ with Shell() as sh:
     client = sh.make_proxy("", "$client")
 ```
 
+## Static Classes
+
+A bare `[Type]` literal binds the *type itself* instead of creating an
+instance. The proxy then exposes the type's **static** methods, properties
+and constants (invoked with `::` in the session):
+
+```python
+with Shell() as sh:
+    math = sh.make_proxy("", "[System.Math]")
+    math.Sqrt(16.0)                     # 4.0
+    math.PI                             # 3.141592653589793 (const field)
+
+    path = sh.make_proxy("", "[System.IO.Path]")
+    path.Combine("a", "b")              # "a\\b"
+
+    dow = sh.make_proxy("", "[System.DayOfWeek]")
+    dow.Monday                          # "Monday" (enum values are fields)
+```
+
+The motivating example — a WinForms message box:
+
+```python
+with Shell(initial_commands=["Add-Type -AssemblyName System.Windows.Forms"]) as sh:
+    msg_box = sh.make_proxy("", "[System.Windows.Forms.MessageBox]")
+    msg_box.Show("Hello from Python!", "Title")   # blocks until dismissed
+```
+
+Notes:
+
+- Return values convert exactly like instance calls (the table below):
+  scalars inline, `byte[]` via the bridge, complex values as sub-proxies.
+- Writable static properties can be assigned; consts and `readonly` fields
+  are read-only and raise `AttributeError` on assignment.
+- Instance members are **not** available on a static proxy (and vice
+  versa); the same type can have one proxy of each kind.
+- `static=True` forces static mode when the name is unbracketed
+  (`make_proxy("", "System.Math", static=True)`) or when binding a
+  `$variable` that already holds a type object.
+
 ## Value Conversion
 
 Every read is routed through a runtime type check in PowerShell:

virtualshell-1.2.0/src/virtualshell/_version.py

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