@camera.ui/server 0.0.70 → 0.0.71-dev.0

package/dist/server/src/_camera_ui_tools/camera_ui_rpc/codec.py

@@ -0,0 +1,73 @@
+"""MessagePack encoding/decoding using ormsgpack for better performance."""
+
+from datetime import date, datetime, time
+from enum import Enum
+from typing import Any
+
+import ormsgpack
+
+
+def _default_handler(obj: Any) -> Any:
+    """Default handler for custom types."""
+    if isinstance(obj, Enum):
+        return obj.value
+    # date and time objects need special handling
+    if isinstance(obj, date) and not isinstance(obj, datetime):
+        # Convert date to datetime at midnight for timestamp encoding
+        return datetime.combine(obj, time.min)
+    if isinstance(obj, time):
+        # For time objects, return as string
+        return obj.isoformat()
+    # Let ormsgpack handle other types
+    raise TypeError(f"Object of type {type(obj).__name__} is not JSON serializable")
+
+
+def encode(data: Any) -> bytes:
+    """
+    Encode data to MessagePack binary format using ormsgpack.
+
+    Args:
+        data: Any serializable data
+
+    Returns:
+        MessagePack encoded binary data
+    """
+    # Use ormsgpack with proper options for cross-language compatibility
+    # OPT_DATETIME_AS_TIMESTAMP_EXT: Encode datetime as MessagePack timestamp extension
+    # OPT_NON_STR_KEYS: Allow non-string dict keys
+    # OPT_PASSTHROUGH_ENUM: Pass enums to default handler
+    return ormsgpack.packb(
+        data,
+        default=_default_handler,
+        option=ormsgpack.OPT_NON_STR_KEYS
+        | ormsgpack.OPT_DATETIME_AS_TIMESTAMP_EXT
+        | ormsgpack.OPT_PASSTHROUGH_ENUM,
+    )
+
+
+def _ext_hook(_code: int, _data: bytes) -> Any:
+    """Handle MessagePack extension types from other languages."""
+    # Handle undefined extension type (from msgpackr when encodeUndefinedAsNil is disabled)
+    # Extension type codes vary by implementation, return None for unknown types
+    return None
+
+
+def decode(data: bytes | bytearray | memoryview) -> Any:
+    """
+    Decode MessagePack binary data using ormsgpack.
+
+    Args:
+        data: MessagePack binary data
+
+    Returns:
+        Decoded data
+    """
+    # Use ormsgpack with proper options
+    # OPT_DATETIME_AS_TIMESTAMP_EXT: Deserialize timestamp extension objects to datetime
+    # OPT_NON_STR_KEYS: Allow non-string dict keys
+    # ext_hook: Handle extension types from Node.js msgpackr
+    return ormsgpack.unpackb(
+        data,
+        option=ormsgpack.OPT_DATETIME_AS_TIMESTAMP_EXT | ormsgpack.OPT_NON_STR_KEYS,
+        ext_hook=_ext_hook,
+    )

package/dist/server/src/_camera_ui_tools/camera_ui_rpc/decorators.py

@@ -0,0 +1,307 @@
+from collections.abc import Callable
+from typing import Any, TypeVar, cast
+
+F = TypeVar("F", bound=Callable[..., Any])
+T = TypeVar("T", bound=type)
+
+
+def RPCMethod(func: F) -> F:
+    """Mark a method for RPC exposure."""
+    func.__rpc_exposed__ = True  # type: ignore
+    return func
+
+
+def RPCNested(func: Any) -> Any:
+    """Mark a property containing nested RPC objects."""
+    # This works differently in Python - we mark the property descriptor
+    if isinstance(func, property):
+        func.__rpc_nested__ = True  # type: ignore
+    else:
+        # For regular attributes, we need to mark them differently
+        func.__rpc_nested__ = True  # type: ignore
+    return func
+
+
+def RPCClass(c: T) -> T:
+    """Mark entire class for RPC exposure (all public methods)."""
+    c.__rpc_expose_all__ = True  # type: ignore
+    return c
+
+
+class RPCPropertyDescriptor:
+    """Property descriptor that marks a property for RPC exposure."""
+
+    def __init__(self, name: str | None = None):
+        self.name: str | None = name
+        self.private_name: str | None = None
+
+    def __set_name__(self, owner: type, name: str) -> None:
+        self.name = name
+        self.private_name = f"_{name}"
+
+        # Mark the property itself as RPC method
+        if not hasattr(owner, "__rpc_methods__"):
+            owner.__rpc_methods__ = []  # type: ignore
+        owner.__rpc_methods__.append(name)  # type: ignore
+
+        # Create setter method name
+        setter_name = f"set{name[0].upper()}{name[1:]}"
+
+        # Create the setter method
+        # We need to capture private_name in the closure
+        private_name = self.private_name
+
+        def setter(instance: Any, value: Any) -> None:
+            setattr(instance, private_name, value)
+
+        # Add setter to class
+        setattr(owner, setter_name, setter)
+
+        # Mark setter as RPC method
+        owner.__rpc_methods__.append(setter_name)  # type: ignore
+
+    def __get__(self, obj: Any, objtype: type | None = None) -> Any:
+        if obj is None:
+            return self
+        assert self.private_name is not None, "Property not initialized via __set_name__"
+        return getattr(obj, self.private_name, None)
+
+    def __set__(self, obj: Any, value: Any) -> None:
+        assert self.private_name is not None, "Property not initialized via __set_name__"
+        setattr(obj, self.private_name, value)
+
+
+# Convenience function that returns a property descriptor
+RPCProperty = RPCPropertyDescriptor
+
+
+def extract_nested_methods_without_decorators(
+    obj: Any,
+    path: list[str] | None = None,
+    handlers: dict[str, Callable[..., Any]] | None = None,
+    visited: set[int] | None = None,
+) -> dict[str, Callable[..., Any]]:
+    if path is None:
+        path = []
+    if handlers is None:
+        handlers = {}
+    if visited is None:
+        visited = set()
+
+    if obj is None:
+        return handlers
+
+    # Prevent circular references
+    obj_id = id(obj)
+    if obj_id in visited:
+        return handlers
+    visited.add(obj_id)
+
+    # Handle dict objects
+    if isinstance(obj, dict):
+        for key, value in cast(dict[Any, Any], obj).items():
+            if isinstance(key, str) and key.startswith("_"):
+                continue
+
+            full_path = ".".join(path + [key])
+
+            if callable(value) and not isinstance(value, type):
+                handlers[full_path] = value
+            # Don't recurse into nested objects for without_decorators mode
+            # Only direct methods should be exposed
+
+        return handlers
+
+    # Handle class instances
+    for attr_name in dir(obj):
+        # Skip private, dunder, and internal attributes
+        if attr_name.startswith("_"):
+            continue
+
+        try:
+            # Check if it's a static method or class method on the class
+            # We need to check __dict__ directly because getattr resolves the descriptor
+            for cls in obj.__class__.__mro__:
+                if attr_name in cls.__dict__:
+                    class_attr = cls.__dict__[attr_name]
+                    if isinstance(class_attr, staticmethod | classmethod):
+                        break
+            else:
+                class_attr = None
+
+            if isinstance(class_attr, staticmethod | classmethod):
+                continue
+
+            # Get the actual value
+            value = getattr(obj, attr_name)
+
+            # Skip types/classes
+            if isinstance(value, type):
+                continue
+
+            full_path = ".".join(path + [attr_name])
+
+            if callable(value):
+                # It's a method - expose it
+                handlers[full_path] = value
+            # Don't recurse into nested objects for without_decorators mode
+            # Only direct methods should be exposed, nested objects require explicit @RPCNested
+
+        except Exception:
+            # Ignore errors in attribute access
+            pass
+
+    return handlers
+
+
+def extract_nested_methods_with_decorators(
+    obj: Any,
+    path: list[str] | None = None,
+    handlers: dict[str, Callable[..., Any]] | None = None,
+    visited: set[int] | None = None,
+) -> dict[str, Callable[..., Any]]:
+    if path is None:
+        path = []
+    if handlers is None:
+        handlers = {}
+    if visited is None:
+        visited = set()
+
+    # Prevent circular references
+    obj_id = id(obj)
+    if obj_id in visited:
+        return handlers
+    visited.add(obj_id)
+
+    # Check if it's a plain dict
+    is_plain_dict = type(obj) is dict
+
+    # Check for decorators
+    has_decorators = (
+        hasattr(obj.__class__, "__rpc_expose_all__")
+        or any(
+            hasattr(getattr(obj.__class__, attr, None), "__rpc_exposed__")
+            for attr in dir(obj.__class__)
+            if not attr.startswith("_")
+        )
+        or any(
+            hasattr(getattr(obj.__class__, attr, None), "__rpc_nested__")
+            for attr in dir(obj.__class__)
+            if not attr.startswith("_")
+        )
+    )
+
+    if is_plain_dict and not has_decorators:
+        # Plain dict mode
+        obj = cast(dict[str, Any], obj)
+        for key, value in obj.items():
+            if key.startswith("_"):
+                continue
+
+            full_path = ".".join(path + [key])
+
+            if callable(value):
+                handlers[full_path] = value
+            elif (
+                isinstance(value, dict)
+                or hasattr(value, "__dict__")
+                and not isinstance(value, str | int | float | bool | list | tuple | set)
+            ):
+                extract_nested_methods_with_decorators(value, path + [key], handlers, visited)
+            else:
+                # For non-callable values (like strings, numbers), create a getter function
+                async def value_getter(val: Any = value) -> Any:
+                    return val
+
+                handlers[full_path] = value_getter
+    else:
+        # Decorator mode
+        obj = cast(object, obj)
+        expose_all = getattr(obj.__class__, "__rpc_expose_all__", False)
+
+        # Collect decorated methods and nested properties
+        rpc_methods: list[Any] = []
+        rpc_nested: list[Any] = []
+
+        # Check all attributes in the class
+        for attr_name in dir(obj.__class__):
+            if attr_name.startswith("_"):
+                continue
+
+            try:
+                attr = getattr(obj.__class__, attr_name)
+                if hasattr(attr, "__rpc_exposed__"):
+                    rpc_methods.append(attr_name)
+                if hasattr(attr, "__rpc_nested__"):
+                    rpc_nested.append(attr_name)
+                # Check if it's a property that has been decorated
+                if isinstance(attr, property) and hasattr(attr.fget, "__rpc_nested__"):
+                    rpc_nested.append(attr_name)
+            except Exception:
+                pass
+
+        # Also check for methods marked via __rpc_methods__ (from RPCProperty)
+        if hasattr(obj.__class__, "__rpc_methods__"):
+            for method_name in obj.__class__.__rpc_methods__:
+                if method_name not in rpc_methods:
+                    rpc_methods.append(method_name)
+
+        # Also check instance __dict__ for dynamically added nested objects
+        if hasattr(obj, "__dict__"):
+            for attr_name, _ in obj.__dict__.items():
+                if not attr_name.startswith("_"):
+                    # Check if this instance attribute corresponds to a decorated property
+                    class_attr = getattr(obj.__class__, attr_name, None)
+                    if class_attr and hasattr(class_attr, "__rpc_nested__") and attr_name not in rpc_nested:
+                        rpc_nested.append(attr_name)
+
+        # Check for instance-level nested attributes marking
+        if hasattr(obj, "__rpc_nested_attrs__"):
+            for attr_name in obj.__rpc_nested_attrs__:
+                if attr_name not in rpc_nested:
+                    rpc_nested.append(attr_name)
+
+        # Process all attributes
+        for attr_name in dir(obj):
+            if attr_name.startswith("_") or attr_name == "constructor":
+                continue
+
+            try:
+                value = getattr(obj, attr_name)
+                full_path = ".".join(path + [attr_name])
+
+                if callable(value) and not isinstance(value, type):
+                    # It's a method
+                    if expose_all or attr_name in rpc_methods:
+                        handlers[full_path] = value
+                elif attr_name in rpc_methods and not callable(value):
+                    # It's a property marked with @RPCProperty
+                    # Create an async getter function
+                    async def property_getter(obj: Any = obj, attr: Any = attr_name) -> Any:
+                        return getattr(obj, attr)
+
+                    handlers[full_path] = property_getter
+                elif attr_name in rpc_nested:
+                    # It's a nested object marked with @RPCNested
+                    # For properties, we might need to call them to get the actual object
+                    nested_obj = value
+
+                    # Check if it's a property getter (method that returns an object)
+                    if callable(value) and hasattr(obj.__class__, attr_name):
+                        class_attr = getattr(obj.__class__, attr_name)
+                        if isinstance(class_attr, property):
+                            # It's a property, call it to get the actual object
+                            try:
+                                nested_obj = value()  # Call the property getter
+                            except Exception:
+                                # If calling fails, use the value as is
+                                nested_obj = value
+
+                    if nested_obj is not None:
+                        extract_nested_methods_with_decorators(
+                            nested_obj, path + [attr_name], handlers, visited
+                        )
+            except Exception:
+                pass
+
+    return handlers

package/dist/server/src/_camera_ui_tools/camera_ui_rpc/errors.py

@@ -0,0 +1,76 @@
+"""RPC exception classes."""
+
+from typing import Any
+
+from .types import ErrorCode, RPCError
+
+
+class RPCException(Exception):
+    """Base RPC exception class."""
+
+    def __init__(self, code: str, message: str, data: Any | None = None):
+        """
+        Initialize RPC exception.
+
+        Args:
+            code: Error code
+            message: Error message
+            data: Optional additional error data
+        """
+        super().__init__(message)
+        self.code: str = code
+        self.message: str = message
+        self.data: Any | None = data
+
+    def to_dict(self) -> RPCError:
+        """Convert exception to RPC error format."""
+        return RPCError(code=self.code, message=self.message, data=self.data)
+
+    @classmethod
+    def from_dict(cls, error: RPCError) -> "RPCException":
+        """Create exception from RPC error format."""
+        return cls(code=error["code"], message=error["message"], data=error.get("data"))
+
+    def __str__(self) -> str:
+        """String representation."""
+        if self.data:
+            return f"[{self.code}] {self.message} (data: {self.data})"
+        return f"[{self.code}] {self.message}"
+
+    def __repr__(self) -> str:
+        """Developer representation."""
+        return f"RPCException(code={self.code!r}, message={self.message!r}, data={self.data!r})"
+
+
+def create_error(code: ErrorCode | str, message: str, data: Any | None = None) -> RPCException:
+    """
+    Create an RPC exception with the given code and message.
+
+    Args:
+        code: Error code (from ErrorCode enum or custom string)
+        message: Error message
+        data: Optional additional error data
+
+    Returns:
+        RPCException instance
+    """
+    if isinstance(code, ErrorCode):
+        code = code.value
+    return RPCException(code=code, message=message, data=data)
+
+
+def create_error_from_dict(error_dict: dict[str, Any]) -> RPCException:
+    """
+    Create an RPC exception from a dictionary.
+
+    Args:
+        error_dict: Error dictionary with code, message, and optional data
+
+    Returns:
+        RPCException instance
+    """
+    return RPCException(
+        error_dict.get("code", ErrorCode.INTERNAL_ERROR.value),
+        error_dict.get("message", "Unknown error"),
+        error_dict.get("data"),
+    )

package/dist/server/src/_camera_ui_tools/camera_ui_rpc/executor.py

@@ -0,0 +1,29 @@
+"""This module provides a single, shared ThreadPoolExecutor for the entire application."""
+
+from concurrent.futures import ThreadPoolExecutor
+
+_executor: ThreadPoolExecutor | None = None
+
+
+def get_executor() -> ThreadPoolExecutor:
+    """
+    Returns the global singleton instance of the ThreadPoolExecutor.
+    The pool is created on the first call.
+    """
+    global _executor
+    if _executor is None:
+        # Create the executor with Python's default worker count,
+        # which is a sensible balance for I/O-bound tasks.
+        # Default is min(32, os.cpu_count() + 4).
+        _executor = ThreadPoolExecutor(thread_name_prefix="rpc_worker")
+    return _executor
+
+
+def shutdown_executor() -> None:
+    """
+    Shuts down the global executor. Should be called during application cleanup.
+    """
+    global _executor
+    if _executor is not None:
+        _executor.shutdown(wait=False)
+        _executor = None