simulo 0.26.0__py3-none-any.whl

simulo/_client/stub.py

@@ -0,0 +1,41 @@
+"""Inert, torch-free placeholder shared across the discovery (submit) surface.
+
+A :class:`Stub` stands in for any symbol a user app might *touch* while it is
+imported in discovery mode. Attribute access, calls, and subscription all yield
+further stubs, so a stub never explodes on access — and because no job body runs
+during discovery, a stub is only ever touched, never used for real computation.
+
+Two consumers share it:
+
+* ``discovery.py`` — the ``runtime.imports()`` stub modules return stubs for any
+  attribute the user reads off a deferred heavy import (e.g. ``torch.Tensor``).
+* ``learning.py`` — the *value/config + in-body-only* learning names
+  (``simulo.Scene(...)``, ``simulo.Terrain.plane(...)``, ``simulo.LearningEnv(...)``,
+  …) resolve to a stub in discovery so they are harmless even if touched in a
+  class or job body that is read (but not executed) at submit.
+"""
+
+from __future__ import annotations
+
+
+class Stub:
+    """Inert placeholder whose every interaction yields another :class:`Stub`."""
+
+    __slots__ = ("_name",)
+
+    def __init__(self, name: str) -> None:
+        self._name = name
+
+    def __call__(self, *args: object, **kwargs: object) -> "Stub":
+        return Stub(f"{self._name}()")
+
+    def __getattr__(self, item: str) -> "Stub":
+        if item.startswith("__") and item.endswith("__"):
+            raise AttributeError(item)
+        return Stub(f"{self._name}.{item}")
+
+    def __getitem__(self, item: object) -> "Stub":
+        return Stub(f"{self._name}[]")
+
+    def __repr__(self) -> str:
+        return f"<simulo discovery stub {self._name!r}>"