simulo 0.26.0__py3-none-any.whl

simulo/__init__.py

@@ -0,0 +1,433 @@
+"""Simulo thin client — the user-facing, torch-free SDK surface.
+
+This is the ONE Simulo distribution that ships ``simulo/__init__.py``. The
+``extend_path`` call below unions every ``simulo/`` directory on ``sys.path`` into
+this package's ``__path__`` so the PEP 420 namespace portions shipped by sibling
+distributions (``simulo.core`` / ``simulo.backend`` / ``simulo.recording`` from
+``simulo-backend``; ``simulo.interfaces`` from ``simulo-interfaces``) resolve
+alongside the clean top-level ``simulo.App`` re-exported here.
+
+It MUST run before the re-exports below, because importing the thin client's
+internal ``App`` module pulls in ``simulo.interfaces`` (a sibling distribution).
+
+**The one-import rule.** Everything a user can legitimately need is reachable
+from ``import simulo``. ``simulo.interfaces`` is a packaging detail two
+distributions share so the thin client and the backend hold ONE definition
+instead of drifting copies — it is never a namespace a user types. A user who
+can write ``simulo.Physics.rigid(...)`` must not have to discover a second
+import to write ``except simulo.JobFailedError`` or
+``collision=simulo.Collision.enabled()``.
+
+The rule is enforced as a rule, not as a hand-kept list: the thin client's
+one-import-rule test derives the expected surface from
+``simulo.interfaces.__all__`` and ``simulo.interfaces.authoring.__all__`` and
+fails on any name that is not reachable here or explicitly declared in that
+test's exclusions table with a reason. A hand-maintained whitelist is only ever
+as current as the last person who remembered to edit it, and two names were
+missed that way before the rule replaced it.
+
+Three kinds of name live on ``simulo``:
+
+* **Platform** names — ``App / Runtime / Volume / Asset / Output /
+  OutputKind / SystemType / callbacks`` — are **real, eager** attributes bound
+  below. They are always torch-free (``Output`` is the ``simulo-interfaces``
+  contract dataclass, ``OutputKind`` and ``SystemType`` its wire-stable
+  ``StrEnum``\\ s, all three re-exported).
+* **Contract vocabulary** — the shared error hierarchy (``SimuloError`` and its
+  subclasses), the ``NewType`` identifier aliases (``JobId``, ``ProjectId``, …),
+  and the authoring value types that are not already carried by the lazy
+  resolver (``Collision``, ``Transform``, the primitive shapes, the factory
+  return types, the markers, …) — are also **real, eager** attributes. They cost
+  nothing to bind: ``simulo.interfaces.authoring`` is a zero-dependency package
+  that the thin client's own learning resolver already imports at module scope,
+  so this adds no import and no dependency. Errors and IDs are likewise
+  stdlib-only (``NewType`` is the underlying ``str`` at runtime).
+* **Lazy, mode-aware** names — the learning names ``Task / Scene / Robot /
+  LearningEnv / RLTrainer / …`` plus the execution-time ``save_output`` and
+  ``run`` (the scenario execution loop) — are
+  resolved through the PEP 562 ``__getattr__`` below, which delegates to the
+  thin client's internal learning-name resolver. At submit (discovery mode) they resolve to
+  lean stand-ins so the user app imports without the heavy runtime; only the
+  backend runner (execution mode) resolves them to the real implementations.
+  Because the platform names are real attributes, ``__getattr__`` fires *only*
+  for the lazy names. The RELOCATED authoring value types (``Pose`` /
+  ``Material`` / ``Physics`` / ``Light`` / ``Terrain`` / ``World`` /
+  ``Entity`` / ``Visual`` / ``RecordConfig``) ride the same resolver but
+  resolve to their real, dependency-free ``simulo.interfaces.authoring``
+  class in BOTH modes — they need no heavy runtime, and exactly one
+  definition exists. (``Terrain`` is ground you generate; ``World`` is a
+  prebuilt place you bring, ``World.usd(...)``.)
+"""
+
+import pkgutil as _pkgutil
+from typing import TYPE_CHECKING
+
+__path__ = _pkgutil.extend_path(__path__, __name__)
+
+from simulo import callbacks
+from simulo._client.app import App
+from simulo._client.asset import Asset
+from simulo._client.learning import LEARNING_NAMES as _LEARNING_NAMES
+from simulo._client.learning import resolve as _resolve_learning
+from simulo._client.runtime import Runtime
+from simulo._client.volume import Volume
+
+# --- Contract vocabulary, re-exported under the one-import rule ---------------
+#
+# The shared error hierarchy and the identifier aliases. Both are stdlib-only:
+# the exceptions derive from ``Exception``, and every identifier is a
+# ``typing.NewType`` over ``str`` (zero runtime cost, distinct to a type
+# checker). A user catching a failed job writes ``except simulo.JobFailedError``,
+# never a second import.
+from simulo.interfaces import (
+    CheckpointId,
+    ContractViolationError,
+    Digest,
+    ImportResolutionError,
+    JobFailedError,
+    JobId,
+    JobPublicId,
+    ModelPublicId,
+    OrganizationId,
+    OutputPublicId,
+    PackageId,
+    ProjectId,
+    RecordingPublicId,
+    ResourceId,
+    ResourceNotFoundError,
+    ResourceUri,
+    ResumeIncompatibleError,
+    SimuloError,
+    TagId,
+    TrainedModelId,
+    parse_job_public_id,
+    parse_model_public_id,
+    parse_output_public_id,
+    parse_recording_public_id,
+)
+
+# The authoring value types that the lazy resolver does NOT already carry.
+# Every one is a real, dependency-free class with exactly one definition, so —
+# unlike the learning names — there is nothing mode-aware about them and no
+# reason to defer: binding them eagerly is what makes ``simulo.Collision`` and
+# ``simulo.Transform`` exist at all.
+#
+# ``simulo.Asset`` (the thin client's registry HANDLE, imported above — the
+# name every shipped example and doc page uses) and
+# ``simulo.interfaces.authoring.Asset`` (the model-source spec) used to share
+# one name — two different user-facing
+# classes, both exposing ``.usd()`` / ``.urdf()``, so re-exporting the
+# authoring one here would have silently shadowed the handle users actually
+# want. #693 (owner decision) resolved the collision by renaming the
+# contract-side class to ``AssetSource``; with the names distinct, it is
+# re-exported here like every other concrete authoring type — no exclusion
+# needed any more.
+from simulo.interfaces.authoring import (
+    ArrowMarker,
+    AssetEntity,
+    AssetSource,
+    AxesMarker,
+    Collision,
+    Cone,
+    Cuboid,
+    Cylinder,
+    DeformableMaterial,
+    DeformablePhysics,
+    DistantLight,
+    DomeLight,
+    GroundPlane,
+    LightConfig,
+    PointMarker,
+    PrimitiveShape,
+    RigidPhysics,
+    RoughTerrain,
+    Sphere,
+    SphereMarker,
+    SubTerrainConfig,
+    SurfaceMaterial,
+    TerrainConfig,
+    Transform,
+    URDFAsset,
+    USDAsset,
+    USDWorld,
+    VisualMarkerBase,
+)
+from simulo.interfaces.platform import Output, OutputKind, SystemType
+
+# Public surface = eager platform exports (real attributes; ``__getattr__`` never
+# fires for these) + the lazily-resolved learning names. Kept a static literal so
+# tooling recognises the re-exports; a test guards it against ``LEARNING_NAMES`` drift.
+__all__ = [
+    # platform (eager, real)
+    "App",
+    "Output",
+    "OutputKind",
+    "SystemType",
+    "Runtime",
+    "Volume",
+    "Asset",
+    "callbacks",
+    # contract errors (eager, real) — the shared exception hierarchy
+    "SimuloError",
+    "ContractViolationError",
+    "ImportResolutionError",
+    "ResourceNotFoundError",
+    "ResumeIncompatibleError",
+    "JobFailedError",
+    # contract identifiers (eager, real) — NewType aliases over ``str``
+    "OrganizationId",
+    "ProjectId",
+    "PackageId",
+    "JobId",
+    "JobPublicId",
+    "ModelPublicId",
+    "RecordingPublicId",
+    "OutputPublicId",
+    "parse_job_public_id",
+    "parse_model_public_id",
+    "parse_recording_public_id",
+    "parse_output_public_id",
+    "ResourceId",
+    "CheckpointId",
+    "TrainedModelId",
+    "TagId",
+    "ResourceUri",
+    "Digest",
+    # authoring value types (eager, real) — the rest of the vocabulary the
+    # lazy resolver below does not carry
+    "Collision",
+    "RigidPhysics",
+    "DeformableMaterial",
+    "DeformablePhysics",
+    "SurfaceMaterial",
+    "AssetSource",
+    "USDAsset",
+    "URDFAsset",
+    "LightConfig",
+    "DistantLight",
+    "DomeLight",
+    "TerrainConfig",
+    "GroundPlane",
+    "SubTerrainConfig",
+    "RoughTerrain",
+    "USDWorld",
+    "PrimitiveShape",
+    "Cone",
+    "Cuboid",
+    "Sphere",
+    "Cylinder",
+    "Transform",
+    "AssetEntity",
+    "VisualMarkerBase",
+    "AxesMarker",
+    "SphereMarker",
+    "ArrowMarker",
+    "PointMarker",
+    # lazy, mode-aware (the learning names + save_output)
+    "ActuatorGainsConfig",
+    "Camera",
+    "CameraSpawnConfig",
+    "ContactSensor",
+    "DifferentialIKController",
+    "Entity",
+    "ForceTorqueSensor",
+    "FrameTransformer",
+    "FrameTransformerTarget",
+    "GripperCommand",
+    "GripperState",
+    "IMU",
+    "LearningEnv",
+    "Light",
+    "Material",
+    "ObservationComponent",
+    "ObservationSet",
+    "OperationalSpaceController",
+    "ParallelGripperActuator",
+    "Physics",
+    "Player",
+    "Policy",
+    "Pose",
+    "Prop",
+    "RLPlayer",
+    "RLTrainer",
+    "RayCaster",
+    "RayPattern",
+    "RecordConfig",
+    "RewardComponent",
+    "RewardSet",
+    "Robot",
+    "Scenario",
+    "Scene",
+    "SensorOffset",
+    "Simulation",
+    "SurfaceGripperActuator",
+    "Task",
+    "Terrain",
+    "TerminationCondition",
+    "TerminationSet",
+    "Trainer",
+    "Visual",
+    "World",
+    "run",
+    "save_output",
+]
+
+
+def __getattr__(name: str) -> object:
+    """PEP 562 hook: lazily resolve the mode-aware learning names.
+
+    Fires only for attributes missing from the module dict — i.e. never for the
+    real platform exports above. Delegates the learning names to the thin
+    client's internal resolver (discovery stand-in vs. real
+    ``simulo.core`` class, by mode); everything else is a genuine ``AttributeError``.
+    """
+    if name in _LEARNING_NAMES:
+        return _resolve_learning(name)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+def __dir__() -> list[str]:
+    """Expose only the public surface to ``dir(simulo)``.
+
+    That is ``__all__`` (eager platform exports + learning names) unioned with
+    :data:`LEARNING_NAMES`. Private module globals (``_pkgutil``,
+    ``_resolve_learning``, ``_LEARNING_NAMES``, the ``TYPE_CHECKING`` import, …)
+    are deliberately filtered out so tab-completion shows the user-facing API only.
+    """
+    return sorted(set(__all__) | set(_LEARNING_NAMES))
+
+
+if TYPE_CHECKING:
+    # Static aliases so a type checker sees the learning names with precise types
+    # (PEP 562 ``__getattr__`` would otherwise type them as ``Any``). The rule that
+    # this block MUST follow — and that the mypy positive test in
+    # ``tests/test_learning_typing.py`` locks — is:
+    #
+    # * **Subclassable** names (used as ``class X(simulo.Task)``) alias their
+    #   ``interfaces.runtime`` Protocol, so the subclass is checked against the
+    #   contract (e.g. ``TaskProtocol``).
+    # * **Instantiated mirror** names (used as ``simulo.LearningEnv(task=...)``,
+    #   ``simulo.RLTrainer(env=...)``, ``simulo.Robot(...)``,
+    #   ``simulo.RLPlayer(env=...)``) alias their typing FACADE in the thin
+    #   client's internal facades module — a Protocol alias would make mypy
+    #   reject instantiation ("Cannot instantiate protocol class"), and
+    #   ``Any`` (the pre-Wave-C4 rule) type-checked nothing. The facade
+    #   declares the contract surface plus the real constructor, so both the
+    #   call and every member access are checked against the real member set
+    #   and signature shape (name, kind, arity, presence of a default —
+    #   NOT the declared type; see the facades module docstring for the
+    #   known gap); facade fidelity to the contract AND to the concrete
+    #   worker class is pinned by the backend suite's conformance engine.
+    # * **Called mirror** name (``simulo.run(scenario_class, ...)`` — the one
+    #   non-learning, non-instantiated member of this kind): same problem as
+    #   an instantiated mirror one level down — with no override, ``run``
+    #   types as ``object`` (``__getattr__``'s declared return), and
+    #   ``object`` is not *callable* at all. It aliases a plain FUNCTION
+    #   facade (there is no Protocol for a bare function to alias against),
+    #   never registered in the backend's class-shaped conformance engine —
+    #   see the facades module docstring for where its drift guard lives
+    #   instead.
+    # * **Annotation-position mirror** names alias their contract Protocol:
+    #   ``Scene`` is ``SceneProtocol`` — measured across every shipped user
+    #   surface it appears only as ``def build(self, scene: simulo.Scene)``,
+    #   never instantiated, and the Protocol alias is what keeps that override
+    #   Liskov-compatible with the contract's ``scene: SceneProtocol``.
+    # * **Relocated value types** alias their real, dependency-free
+    #   ``simulo.interfaces.authoring`` class — precise field checking in both
+    #   modes, because only one definition exists.
+    #
+    # Engine authoring vocabulary (the one-import rule's second half —
+    # ``Camera`` and its sensor siblings, ``Simulation``, the controllers, the
+    # actuators, the ``*Set`` containers): only ``Camera`` and ``Prop`` get an
+    # alias here. Both have a contract Protocol in
+    # ``simulo.interfaces.authoring`` (``CameraProtocol`` / ``PropProtocol``)
+    # and both are instantiated, never subclassed (``simulo.Camera(width=640,
+    # ...)``, ``simulo.Prop(shape)``), so each follows the "instantiated mirror
+    # -> facade" rule above exactly. The other 19 names
+    # have no TYPE_CHECKING alias, DELIBERATELY, per the rule's own "where none
+    # exists, do not invent one" corollary:
+    #   - ``CameraSpawnConfig`` / ``SensorOffset`` / ``RayPattern`` /
+    #     ``ActuatorGainsConfig`` / ``GripperState`` / ``GripperCommand`` /
+    #     ``Simulation`` have no contract Protocol at all — nothing to alias
+    #     against.
+    #   - ``ContactSensor`` / ``RayCaster`` / ``IMU`` / ``ForceTorqueSensor`` /
+    #     ``FrameTransformer`` conform only to the BASE ``SensorProtocol``
+    #     (path/update_period/enabled/debug_vis/name/update/reset) — it does not
+    #     declare their type-specific readers (``read_net_forces``,
+    #     ``read_hits``, ``read_linear_acceleration``, …), so aliasing them to
+    #     ``SensorProtocol`` would be a LOSSY, misleading type (mypy would flag
+    #     real shipped calls to those readers as errors) and aliasing to a
+    #     Protocol at all breaks instantiation ("Cannot instantiate protocol
+    #     class") — the same reason facades exist. Their own per-type contracts
+    #     are a later decision (``simulo.interfaces.authoring.sensor``'s own
+    #     docstring), not implied here.
+    #   - ``ObservationSet`` / ``RewardSet`` / ``TerminationSet`` /
+    #     ``DifferentialIKController`` / ``OperationalSpaceController`` /
+    #     ``SurfaceGripperActuator`` / ``ParallelGripperActuator`` have no
+    #     dedicated Protocol either.
+    #   Runtime resolution (the lazy resolver) is unaffected either way — these
+    #   fall back to ``__getattr__``'s ``-> object`` return type for a type
+    #   checker, same as any name with no static override.
+    from simulo._client.facades import Camera as Camera
+    from simulo._client.facades import LearningEnv as LearningEnv
+    from simulo._client.facades import Prop as Prop
+    from simulo._client.facades import RLPlayer as RLPlayer
+    from simulo._client.facades import RLTrainer as RLTrainer
+    from simulo._client.facades import Robot as Robot
+    from simulo.interfaces.authoring import SceneProtocol
+    from simulo.interfaces.runtime import (
+        ObservationComponentProtocol,
+        PlayerProtocol,
+        PolicyProtocol,
+        RewardComponentProtocol,
+        ScenarioProtocol,
+        TaskProtocol,
+        TerminationConditionProtocol,
+        TrainerProtocol,
+    )
+
+    # Subclassable names alias their Protocol so ``class X(simulo.Task)`` is checked
+    # against ``TaskProtocol``.
+    Task = TaskProtocol
+    Scenario = ScenarioProtocol
+    Policy = PolicyProtocol
+    Player = PlayerProtocol
+    Trainer = TrainerProtocol
+    ObservationComponent = ObservationComponentProtocol
+    RewardComponent = RewardComponentProtocol
+    TerminationCondition = TerminationConditionProtocol
+    # Annotation-position mirror name (see the rule above).
+    Scene = SceneProtocol
+    # ``save_output`` aliases its real execution-mode implementation (a
+    # torch-free thin-client function), so ``simulo.save_output("summary",
+    # path)`` type-checks with the precise signature instead of ``Any``.
+    # ``run`` (the scenario execution loop) aliases its typing FACADE — a
+    # plain FUNCTION facade, not a class one (there is no ``RunProtocol`` to
+    # alias against; ``run`` is not a contract method). Without this, ``run``
+    # falls back to ``__getattr__``'s ``-> object`` return type, and
+    # ``object`` is not callable: ``simulo.run(MyScenario, ...)`` in a freshly
+    # scaffolded app is a hard mypy error no ``--ignore-missing-imports`` can
+    # suppress. The facade's real target (``simulo.scenario.run``) lives in
+    # the ``simulo-backend`` distribution — outside this package's own
+    # ``MYPYPATH`` — but the facade itself is thin-client-resident code
+    # (``simulo/_client/facades.py``), exactly like ``Camera``'s facade for
+    # the same reason; see that module's docstring for the full rationale and
+    # where drift against the real function is caught (a live, unmocked
+    # signature comparison in ``simulo-backend``'s test suite, not mypy).
+    from simulo._client.facades import run as run
+    from simulo._client.outputs import save_output as save_output
+
+    # RELOCATED authoring value types (Plan C — Waves C1, C2, then C4's
+    # ``RecordConfig``): the runtime object IS the real, dependency-free
+    # ``simulo.interfaces.authoring`` class in both
+    # modes, so these alias the real class — precise field/signature checking
+    # (e.g. mypy rejects ``simulo.Pose(xyz="nope")``) instead of ``Any``.
+    from simulo.interfaces.authoring import Entity as Entity
+    from simulo.interfaces.authoring import Light as Light
+    from simulo.interfaces.authoring import Material as Material
+    from simulo.interfaces.authoring import Physics as Physics
+    from simulo.interfaces.authoring import Pose as Pose
+    from simulo.interfaces.authoring import RecordConfig as RecordConfig
+    from simulo.interfaces.authoring import Terrain as Terrain
+    from simulo.interfaces.authoring import Visual as Visual
+    from simulo.interfaces.authoring import World as World

simulo/_client/__init__.py

@@ -0,0 +1,6 @@
+"""Internal implementation package for the Simulo thin client.
+
+Nothing here is part of the public API. Users import from the top-level
+``simulo`` namespace (``simulo.App`` / ``simulo.Runtime`` / ``simulo.callbacks``);
+these modules are the private machinery behind those re-exports.
+"""