lliquidlink 1.0.0__py3-none-any.whl

lliquidlink/__init__.py

@@ -0,0 +1,9 @@
+"""lliquidlink: Python side of the Unity JSON-RPC bridge.
+
+Subpackages:
+    lliquidlink.core   - transport-agnostic JSON-RPC core shared by client and server.
+    lliquidlink.client - Client that connects to a Unity Editor server.
+    lliquidlink.server - Server middleware bridging external clients to Unity over stdio.
+"""
+
+__version__ = "1.0.0"

lliquidlink/client/__init__.py

@@ -0,0 +1,51 @@
+"""lliquidlink.client - Python client to control the Unity Editor over JSON-RPC.
+
+Usage::
+
+    def on_execute(client):
+        go = client.Find("Player")
+        go.transform.Rotate(0, 90, 0)
+
+    client = Client(TcpJsonRpcTransport("localhost", 8700))
+    client.on_execute += on_execute
+    client.mainloop()
+"""
+import logging
+
+from ._client import Client, gc_flush
+from ._event import Event
+from ._proxy import ObjectProxy, PropertyProxy
+from ._transports import StdioJsonRpcTransport, TcpJsonRpcTransport
+from ..core import ConnectionClosedError, RpcError
+from . import models
+
+logger = logging.getLogger("lliquidlink.client")
+
+def setup_logger():
+    level = logging.DEBUG
+    h = logging.StreamHandler()
+    h.setFormatter(logging.Formatter("[Client] %(message)s"))
+    h.setLevel(level)
+    logger.addHandler(h)
+    logger.setLevel(level)
+    for name in [
+        # "anyio", "websockets"
+    ]:
+        _logger = logging.getLogger(name)
+        for h in logger.handlers:
+            _logger.addHandler(h)
+        _logger.setLevel(logger.level)
+setup_logger()
+
+__all__ = [
+    "Client",
+    "gc_flush",
+    "Event",
+    "ObjectProxy",
+    "PropertyProxy",
+    "StdioJsonRpcTransport",
+    "TcpJsonRpcTransport",
+    "ConnectionClosedError",
+    "RpcError",
+    "models",
+]

lliquidlink/client/_client.py

@@ -0,0 +1,138 @@
+"""Client: anyio runtime, RPC dispatch, object-release batching."""
+from __future__ import annotations
+import functools
+import json
+import threading
+import weakref
+from typing import Any, List, TYPE_CHECKING
+if TYPE_CHECKING:
+    from ._transports import StreamTransport
+
+import anyio
+
+from ._event import Event
+from ._proxy import ObjectProxy, PropertyProxy
+from ._serialization import Serialization
+
+import logging
+logger = logging.getLogger(__name__)
+
+async def _await(coro):
+    """Await a coroutine; used to run it on the event loop from a worker thread."""
+    return await coro
+
+
+def gc_flush(func):
+    """Decorator: flush pending Unity object releases after the method returns."""
+    @functools.wraps(func)
+    def wrapper(self, *args, **kwargs):
+        try:
+            return func(self, *args, **kwargs)
+        finally:
+            self.flush_releases()
+    return wrapper
+
+
+class Client:
+    """Client that connects to a Unity Editor server and sends RPC commands.
+
+    Register a handler on the :attr:`on_execute` event with ``+=``, then call
+    :meth:`mainloop`.
+    """
+
+    def __init__(self, transport : StreamTransport):
+        self._transport = transport
+        self._serialization = Serialization(lambda data: ObjectProxy(self, data))
+        transport.bind_codec(self._serialization)
+        self._pending_releases = set()
+        self._release_lock = threading.Lock()
+        self.on_execute = Event()
+
+    # ── RPC dispatch ─────────────────────────────────────────────────────────
+
+    def __getattr__(self, name: str) -> PropertyProxy:
+        """Treat any undefined non-underscore attribute as a Unity RPC method."""
+        if name.startswith("_"):
+            raise AttributeError(name)
+        return PropertyProxy(self, None, [name])
+
+    async def _call_async(self, method: str, params: list) -> Any:
+        return await self._transport.rpc_call(method, params)
+
+    def _call_sync(self, method: str, params: list) -> Any:
+        return self._run(self._call_async(method, params))
+
+    def _run(self, coro):
+        """Run a coroutine synchronously from a worker thread, else return it."""
+        try:
+            return anyio.from_thread.run(_await, coro)
+        except RuntimeError:
+            return coro
+
+    # ── Object release batching ──────────────────────────────────────────────
+
+    def _track_release(self, proxy, data: dict) -> None:
+        instance_id = data.get("instanceId")
+        if instance_id is None:
+            return
+        weakref.finalize(proxy, self._schedule_release, instance_id)
+
+    def _schedule_release(self, instance_id: int) -> None:
+        with self._release_lock:
+            self._pending_releases.add(instance_id)
+
+    async def _flush_releases(self) -> None:
+        with self._release_lock:
+            if not self._pending_releases:
+                return
+            ids = sorted(self._pending_releases)
+            self._pending_releases.clear()
+        if self._transport.closed:
+            return
+        # await self._transport.rpc_notify("release_objects", [json.dumps(ids)])
+
+    def flush_releases(self) -> None:
+        """Send pending object releases now (callable from a worker thread)."""
+        self._run(self._flush_releases())
+
+    # ── Lifecycle ────────────────────────────────────────────────────────────
+
+    @property
+    def is_running(self) -> bool:
+        return not self._transport.closed
+
+    def mainloop(self) -> None:
+        """Connect, run on_execute in a worker thread, flush, then disconnect."""
+        anyio.run(self._amain)
+
+    async def _amain(self) -> None:
+        await self._transport.open()
+        try:
+            await self.execute(self.on_execute)
+            await self._flush_releases()
+        finally:
+            await self._transport.aclose()
+
+    async def connect(self) -> None:
+        """Open the connection to the Unity server."""
+        await self._transport.open()
+
+    async def disconnect(self) -> None:
+        """Close the connection to the Unity server."""
+        await self._transport.aclose()
+
+    async def execute(self, on_execute) -> None:
+        """Run a callback in a worker thread with this client as its argument."""
+        await anyio.to_thread.run_sync(on_execute, self)
+
+    def add_abbreviated_classes(self, class_names: List[str]) -> None:
+        """Register a class name whose methods can be called without namespace prefix."""
+        if isinstance(class_names, str):
+            class_names = [class_names]
+        self._call_sync("add_abbreviated_classes", [class_names])
+
+    def add_abbreviated_namespaces(self, namespaces: List[str]) -> None:
+        """Register namespaces whose types can be referred to by simple name."""
+        if isinstance(namespaces, str):
+            namespaces = [namespaces]
+        self._call_sync("add_abbreviated_namespaces", [namespaces])

lliquidlink/client/_event.py

@@ -0,0 +1,26 @@
+"""Minimal C#-style multicast event supporting += / -= handler registration."""
+from __future__ import annotations
+from typing import Callable, List
+
+
+class Event:
+    """A list of callbacks invoked in registration order when called."""
+
+    def __init__(self) -> None:
+        self._handlers: List[Callable] = []
+
+    def __iadd__(self, handler: Callable) -> "Event":
+        self._handlers.append(handler)
+        return self
+
+    def __isub__(self, handler: Callable) -> "Event":
+        try:
+            self._handlers.remove(handler)
+        except ValueError:
+            pass
+        return self
+
+    def __call__(self, *args, **kwargs) -> None:
+        # Snapshot so a handler that mutates registration mid-dispatch is safe.
+        for handler in list(self._handlers):
+            handler(*args, **kwargs)

lliquidlink/client/_proxy.py

@@ -0,0 +1,92 @@
+"""Lazy proxies for Unity object property/method access over RPC."""
+from __future__ import annotations
+from typing import Any, List
+
+from .models import RpcChainStep
+
+def _resolve_arg(arg):
+    if isinstance(arg, PropertyProxy):
+        return arg()
+    else:
+        return arg
+
+def _resolve_args(args: List):
+    ret = []
+    for arg in args:
+        ret.append(_resolve_arg(arg))
+    return ret
+
+class ObjectProxy:
+    """Proxy for a live Unity object; attribute access builds RPC chains.
+
+    The raw server descriptor is kept on ``data``; garbage collection of this
+    proxy schedules a batched release of the underlying Unity object.
+    """
+
+    def __init__(self, client, data: dict):
+        object.__setattr__(self, "_client", client)
+        object.__setattr__(self, "data", data)
+        client._track_release(self, data)
+
+    def __getattr__(self, name: str) -> Any:
+        if name.startswith("_"):
+            raise AttributeError(name)
+        return PropertyProxy(self._client, self.data, [name])
+
+    def __setattr__(self, name: str, value: Any) -> None:
+        if name.startswith("_") or name == "data":
+            object.__setattr__(self, name, value)
+            return
+        value = _resolve_arg(value)
+        self._client._call_sync("JsonRpc_ResolveChainSet", [self.data, [], name, value])
+
+    def __repr__(self) -> str:
+        return "ObjectProxy(%r)" % (self.data,)
+
+
+class PropertyProxy:
+    """Accumulates a property/method chain, resolved server-side when called.
+
+    Examples::
+
+        obj.prop                       # proxy
+        obj.prop()                     # resolved value
+        obj.parent.child               # chained getter
+        obj.GetComponent('Foo')        # chained method call
+    """
+
+    def __init__(self, client, obj, chain: List[str]):
+        object.__setattr__(self, "_client", client)
+        object.__setattr__(self, "_obj", obj)
+        object.__setattr__(self, "_chain", chain)
+
+    def __getattr__(self, name: str) -> "PropertyProxy":
+        if name.startswith("_"):
+            raise AttributeError(name)
+        return PropertyProxy(self._client, self._obj, self._chain + [name])
+
+    def __setattr__(self, name: str, value: Any) -> None:
+        if name.startswith("_"):
+            object.__setattr__(self, name, value)
+            return
+        value = _resolve_arg(value)
+        steps = [RpcChainStep(p) for p in self._chain]
+        self._client._call_sync("JsonRpc_ResolveChainSet", [self._obj, steps, name, value])
+
+    async def _resolve(self, *args) -> Any:
+        """Send the accumulated chain to Unity and return the resolved value."""
+        method = self._chain[-1]
+        params = list(args)
+        if (self._obj is None) and (len(self._chain) <= 1):
+            return await self._client._call_async(method, params)
+        steps = [RpcChainStep(p) for p in self._chain[:-1]]
+        return await self._client._call_async(
+            "JsonRpc_ResolveChain", [self._obj, steps, method, params])
+
+    def __call__(self, *args) -> Any:
+        """Resolve synchronously (worker thread) or return a coroutine (async)."""
+        args = _resolve_args(args)
+        return self._client._run(self._resolve(*args))
+
+    def __await__(self):
+        return self._resolve().__await__()

lliquidlink/client/_schema.py

@@ -0,0 +1,40 @@
+"""RPC wire-protocol type definitions.
+
+Auto-generated by tools/generate_schema.py.
+Do not edit manually. Edit tools/schema_def.py and re-run the generator.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Literal
+
+
+@dataclass
+class RpcType:
+    """Represents a .NET Type reference transmitted as a JSON-RPC parameter."""
+
+    value: str
+    rpcType: int = 1
+
+
+@dataclass
+class RpcChainStep:
+    """Single step in a property/method chain resolved server-side."""
+
+    name: str
+
+
+@dataclass
+class ReleaseRequest:
+    """Batch request to release Unity object references held by the server."""
+
+    data_list: list[dict]
+    action: Literal['release_objects'] = 'release_objects'
+
+
+@dataclass
+class RpcEnum:
+    """Represents a .NET Type reference transmitted as a JSON-RPC parameter."""
+
+    value: str
+    rpcEnum: int = 1

lliquidlink/client/_serialization.py

@@ -0,0 +1,26 @@
+"""JSON encode/decode hooks bridging Python values and the JSON-RPC wire format."""
+from __future__ import annotations
+import dataclasses
+from typing import Any
+
+from ._proxy import ObjectProxy
+
+class Serialization:
+    """Namespace for the json.dumps default and json.loads object_hook factories."""
+    def __init__(self, make_object_proxy):
+        self._make_object_proxy = make_object_proxy
+
+    @staticmethod
+    def encode_default(obj: Any) -> Any:
+        """json.dumps default: ObjectProxy -> raw dict; dataclass -> dict."""
+        if isinstance(obj, ObjectProxy):
+            return obj.data
+        if dataclasses.is_dataclass(obj) and not isinstance(obj, type):
+            return dataclasses.asdict(obj)
+        raise TypeError("Object of type %s is not JSON serializable" % type(obj).__name__)
+
+    def object_hook(self, d: dict):
+        """Build a json.loads object_hook: InstanceObject dict -> ObjectProxy."""
+        if "instanceObjectAttr" in d.keys():
+            return self._make_object_proxy(d)
+        return d

lliquidlink/client/_transports.py

@@ -0,0 +1,97 @@
+"""Transport implementations: byte-stream openers wrapping the JSON-RPC core.
+
+Currently TCP and stdio. Unix-domain-socket can be added later by
+subclassing ``StreamTransport`` and implementing ``_open()`` with
+``anyio.connect_unix``.
+"""
+from __future__ import annotations
+
+import asyncio
+
+import anyio
+
+from ..core import JsonRpcPeer, StdioByteStream
+from typing import Any, TYPE_CHECKING
+if TYPE_CHECKING:
+    from ._serialization import Serialization
+
+import logging
+logger = logging.getLogger(__name__)
+
+class StreamTransport:
+    """Base transport: opens a byte stream and runs a JsonRpcPeer over it.
+
+    The serve loop runs as a plain asyncio Task so open/aclose can be called
+    from different asyncio tasks without triggering anyio cancel-scope affinity
+    errors.
+    """
+
+    def __init__(self):
+        self._peer = None
+        self._serve_task = None
+        self._default = None
+        self._object_hook = None
+
+    def bind_codec(self, serialization : Serialization) -> None:
+        """Set the json.dumps default / json.loads object_hook used by the peer."""
+        self._default = serialization.encode_default
+        self._object_hook = serialization.object_hook
+
+    async def _open(self):
+        """Open and return the underlying byte stream. Override in subclasses."""
+        raise NotImplementedError
+
+    async def open(self) -> None:
+        stream = await self._open()
+        self._peer = JsonRpcPeer(stream, self._default, self._object_hook)
+        self._serve_task = asyncio.ensure_future(self._peer.serve())
+
+    async def aclose(self) -> None:
+        if self._peer is not None:
+            await self._peer.aclose()
+            self._peer = None
+        if self._serve_task is not None:
+            task = self._serve_task
+            self._serve_task = None
+            if not task.done():
+                task.cancel()
+            try:
+                await task
+            except (asyncio.CancelledError, Exception):
+                pass
+
+    @property
+    def closed(self) -> bool:
+        return self._peer is None or self._peer.closed
+
+    async def rpc_call(self, method, params):
+        logger.debug("rpc_call %s(%s)", method, params)
+        ret = await self._peer.request(method, params)
+        logger.debug("rpc_call ret: %s", ret)
+        return ret
+
+    async def rpc_notify(self, method, params):
+        await self._peer.notify(method, params)
+
+
+class StdioJsonRpcTransport(StreamTransport):
+    """JSON-RPC transport over this process's stdin/stdout."""
+
+    async def _open(self):
+        return StdioByteStream()
+
+
+class TcpJsonRpcTransport(StreamTransport):
+    """JSON-RPC transport over a raw TCP socket.
+
+    anyio's SocketStream already implements the send/receive/aclose
+    byte-stream interface JsonRpcPeer expects, so no adapter is needed.
+    """
+
+    def __init__(self, host: str, port: int):
+        super().__init__()
+        self._host = host
+        self._port = port
+
+    async def _open(self):
+        return await anyio.connect_tcp(self._host, self._port)

lliquidlink/client/models.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+from ._schema import *
+
+def type_(value: str):
+    """Create an RpcType parameter for passing a .NET Type to a Unity RPC method.
+
+    Args:
+        value: Fully qualified .NET type name, e.g. ``"UnityEngine.GameObject"``.
+
+    Returns:
+        An RpcType instance wrapping the given type name.
+    """
+    return RpcType(value)
+
+def enum(value: str):
+    return RpcEnum(value)

lliquidlink/core/__init__.py

@@ -0,0 +1,20 @@
+"""Role-agnostic JSON-RPC core shared by lliquidlink.client and lliquidlink.server."""
+from __future__ import annotations
+
+from ._rpc import (
+    JsonRpcPeer,
+    StdioByteStream,
+    ConnectionClosedError,
+    RpcError,
+    encode_frame,
+    decode_frame,
+)
+
+__all__ = [
+    "JsonRpcPeer",
+    "StdioByteStream",
+    "ConnectionClosedError",
+    "RpcError",
+    "encode_frame",
+    "decode_frame",
+]