grpc-frame 0.5.13__py3-none-any.whl

grpc_frame/__init__.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+import sys
+
+# --- ctrl gRPC スタブ
+from grpc_frame import ctrl_pb2 as _ctrl_pb2
+from grpc_frame import ctrl_pb2_grpc as _ctrl_pb2_grpc
+
+# ctrl_pb2 を トップレベル名として解決できるように
+sys.modules["ctrl_pb2"] = _ctrl_pb2
+sys.modules["ctrl_pb2_grpc"] = _ctrl_pb2_grpc
+
+# --- events ---
+from grpc_frame import events_pb2 as _events_pb2
+from grpc_frame import events_pb2_grpc as _events_pb2_grpc
+
+sys.modules["events_pb2"] = _events_pb2
+sys.modules["events_pb2_grpc"] = _events_pb2_grpc
+
+# --- public API (client) ---
+from grpc_frame.grpc_client import AsyncGrpcClient
+from grpc_frame.grpc_client import SyncGrpcClient
+from grpc_frame.grpc_client import GrpcClient
+
+
+# --- public API (DeviceProxy) ---
+from grpc_frame.device_proxy import DeviceProxyEntry
+from grpc_frame.device_proxy import register_device_proxy
+from grpc_frame.device_proxy import unregister_device_proxy
+from grpc_frame.device_proxy import get_device_proxy_entry
+from grpc_frame.device_proxy import list_device_proxies
+from grpc_frame.device_proxy import DeviceProxy
+from grpc_frame.device_proxy import create_device_proxy
+
+# --- public API for COM (server) ---
+from grpc_frame.grpc_com import ComExecutionRunner
+from grpc_frame.grpc_com import ThreadSafeCtrlProxy
+
+# --- public API (server) ---
+from grpc_frame.grpc_server import _ControlServicer
+from grpc_frame.dispatch_core import *
+from grpc_frame.adapter import *
+
+# --- pyi generation ---
+from grpc_frame.make_pyi import generate_client_pyi

grpc_frame/adapter.py

@@ -0,0 +1,188 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+"""
+引数表現は adapter の「JSON優先 + pickleフォールバック」
+adapter.pack_args/pack_kwargs/pack_result は
+
+1.	JSON 変換を試す（bytes は base64 で JSON に入れる）
+2.	失敗したら pickle
+
+という二段。payload 先頭 1byte に b"J" / b"P" を付ける方式
+
+「イベントを JSON で送りたい」
+「バイナリを運びたい」
+いずれも収容可能
+
+Kengo NAKADA
+kengo.nakada@mat.shimane-u.ac.jp
+kengo.nakada@gmail.com
+"""
+
+from __future__ import annotations
+from typing import Any, Dict, List, Optional, Union, Tuple, Callable, Sequence
+
+import base64
+import json
+import pickle
+
+# JSON でシリアライズされたことを示す識別子（先頭 1 byte）
+_JSON_MAGIC: bytes = b"J"
+
+# pickle でシリアライズされたことを示す識別子（先頭 1 byte）
+_PICKLE_MAGIC: bytes = b"P"
+
+# tuple を JSON 上で区別するための識別キー
+_TUPLE_MAGIC_KEY: str = "__frame_tuple__"
+
+
+class _BytesJsonEncoder(json.JSONEncoder):
+    # JSONEncoder を拡張し、bytes / bytearray を base64 文字列として扱う
+    def default(
+        self,
+        obj: Any,
+    ) -> Any:
+        # bytes / bytearray は JSON で直接扱えないため base64 化
+        if isinstance(obj, (bytes, bytearray)):
+            b64: str = base64.b64encode(bytes(obj)).decode("ascii")
+            # 復元用の識別キー "__bytes__" を付与
+            return {"__bytes__": b64}
+
+        # それ以外は標準の JSONEncoder に委譲
+        return json.JSONEncoder.default(self, obj)
+
+
+def _bytes_json_object_hook(d: Dict[str, Any]) -> Any:
+    # JSON decode 時に "__bytes__" キーを検出した場合の復元処理
+    if "__bytes__" in d:
+        b64 = d["__bytes__"]
+        if isinstance(b64, str):
+            # base64 文字列を bytes に戻
+            return base64.b64decode(b64.encode("ascii"))
+
+    # tuple 復元用の識別キー
+    if _TUPLE_MAGIC_KEY in d:
+        items = d[_TUPLE_MAGIC_KEY]
+        if isinstance(items, list):
+            return tuple(items)
+        if isinstance(items, tuple):
+            return tuple(items)
+
+    # 特殊形式でなければそのまま返す
+    return d
+
+
+def _prepare_json(obj: Any) -> Any:
+    # tuple を JSON で識別できる形式に変換（list はそのまま）
+    if isinstance(obj, tuple):
+        return {
+            _TUPLE_MAGIC_KEY: [_prepare_json(item) for item in obj],
+        }
+    if isinstance(obj, list):
+        return [_prepare_json(item) for item in obj]
+    if isinstance(obj, dict):
+        return {k: _prepare_json(v) for k, v in obj.items()}
+    return obj
+
+
+def _try_json_dumps(obj: Any) -> bytes:
+    try:
+        # JSON によるシリアライズを最初に試みる
+        s: str = json.dumps(
+            # obj,
+            _prepare_json(obj),
+            cls=_BytesJsonEncoder,  # bytes 対応エンコーダ
+            ensure_ascii=False,  # Unicode をそのまま出力
+            separators=(",", ":"),  # JSON を最小サイズにする
+        )
+
+        # JSON で成功した場合は識別子を先頭に付与
+        return _JSON_MAGIC + s.encode("utf-8")
+    except Exception:
+        # JSON 化できないオブジェクトは pickle にフォールバック
+        pass
+
+    # pickle によるシリアライズ（最高プロトコル）
+    payload: bytes = pickle.dumps(obj, protocol=pickle.HIGHEST_PROTOCOL)
+
+    # pickle 識別子を先頭に付与
+    return _PICKLE_MAGIC + payload
+
+
+def _loads(payload: bytes) -> Any:
+    # None はそのまま None として扱う
+    if payload is None:
+        return None
+
+    # 空 payload も None とみなす
+    if len(payload) == 0:
+        return None
+
+    # 先頭 1 byte を識別子として取得
+    magic: bytes = payload[:1]
+    body: bytes = payload[1:]
+
+    # JSON フォーマットの場合
+    if magic == _JSON_MAGIC:
+        s: str = body.decode("utf-8")
+        # bytes 復元用の object_hook を指定
+        return json.loads(s, object_hook=_bytes_json_object_hook)
+
+    # pickle フォーマットの場合
+    if magic == _PICKLE_MAGIC:
+        return pickle.loads(body)
+
+    # 識別子が無い旧形式などは pickle として扱う
+    return pickle.loads(payload)
+
+
+def pack_args(
+    args: Tuple[Any, ...],
+) -> bytes:
+    # 位置引数を list に変換してシリアライズ
+    return _try_json_dumps(list(args))
+
+
+def pack_kwargs(
+    kwargs: Dict[str, Any],
+) -> bytes:
+    # キーワード引数を dict としてシリアライズ
+    return _try_json_dumps(kwargs)
+
+
+def unpack_args(payload: bytes) -> Tuple[Any, ...]:
+    # シリアライズされた args を復元
+    obj = _loads(payload)
+
+    # None の場合は空タプル
+    if obj is None:
+        return tuple()
+
+    # 正常系では list → tuple に変換
+    if isinstance(obj, list):
+        return tuple(obj)
+
+    # 想定外の型はエラー
+    raise TypeError("args は list として復元される必要があります。")
+
+
+def unpack_kwargs(payload: bytes) -> Dict[str, Any]:
+    # シリアライズされた kwargs を復元
+    obj = _loads(payload)
+
+    # None の場合は空 dict
+    if obj is None:
+        return {}
+
+    # 正常系では dict をそのまま返す
+    if isinstance(obj, dict):
+        return obj
+    raise TypeError("kwargs は dict として復元される必要があります。")
+
+
+def pack_result(result: Any) -> bytes:
+    # 戻り値をシリアライズ
+    return _try_json_dumps(result)
+
+
+def unpack_result(payload: bytes) -> Any:
+    return _loads(payload)

grpc_frame/device_proxy.py

@@ -0,0 +1,179 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+"""DeviceProxy support for grpc_frame.
+
+This module provides the same entry/register API as
+``ese774_frame.clients.device_proxy`` while constructing gRPC clients.
+
+The public entry points are intentionally kept compatible:
+
+- DeviceProxyEntry
+- register_device_proxy(...)
+- unregister_device_proxy(...)
+- get_device_proxy_entry(...)
+- list_device_proxies()
+- DeviceProxy(...)
+- create_device_proxy(...)
+
+A device package can register direct client classes, for example
+``SyncPixetGrpcClient`` and ``AsyncPixetGrpcClient``.  If direct client
+classes are not registered, DeviceProxy falls back to the generic
+``SyncGrpcClient`` / ``AsyncGrpcClient`` classes.
+"""
+
+from typing import Any, Dict, List, Optional, Type
+
+from grpc_frame.grpc_client import AsyncGrpcClient
+from grpc_frame.grpc_client import SyncGrpcClient
+
+
+class DeviceProxyEntry(object):
+    """DeviceProxy registration entry.
+
+    The field names are kept compatible with ese774_frame.
+    ``api_spec`` and ``object_name`` are retained as metadata for API
+    compatibility and pyi generation.  grpc_frame itself obtains callable
+    methods from Describe RPC, so these fields are not required for runtime
+    method binding.
+    """
+
+    def __init__(
+        self,
+        device_class: str,
+        async_client_cls: Optional[Type[Any]] = None,
+        sync_client_cls: Optional[Type[Any]] = None,
+        api_spec: Optional[list] = None,
+        object_name: Optional[str] = None,
+        default_async_mode: bool = True,
+    ) -> None:
+        self.device_class = device_class
+        self.async_client_cls = async_client_cls
+        self.sync_client_cls = sync_client_cls
+        self.api_spec = api_spec
+        self.object_name = object_name
+        self.default_async_mode = default_async_mode
+
+
+_DEVICE_PROXY_REGISTRY: Dict[str, DeviceProxyEntry] = {}
+
+
+def register_device_proxy(
+    device_class: str,
+    *,
+    async_client_cls: Optional[Type[Any]] = None,
+    sync_client_cls: Optional[Type[Any]] = None,
+    api_spec: Optional[list] = None,
+    object_name: Optional[str] = None,
+    default_async_mode: bool = True,
+    aliases: Optional[List[str]] = None,
+) -> None:
+    """Register a device class for DeviceProxy.
+
+    This signature is compatible with ese774_frame.  For grpc_frame,
+    direct client classes are the normal registration target:
+
+    ``register_device_proxy("MiniPixCtrl", async_client_cls=..., sync_client_cls=...)``
+
+    ``api_spec`` is accepted for compatibility and pyi tooling, but runtime
+    methods are resolved by the gRPC Describe RPC.
+    """
+    if not device_class:
+        raise ValueError("device_class is required")
+
+    if async_client_cls is None and sync_client_cls is None and api_spec is None:
+        raise ValueError("async_client_cls, sync_client_cls, or api_spec is required")
+
+    entry = DeviceProxyEntry(
+        device_class=device_class,
+        async_client_cls=async_client_cls,
+        sync_client_cls=sync_client_cls,
+        api_spec=api_spec,
+        object_name=object_name,
+        default_async_mode=default_async_mode,
+    )
+
+    names = [device_class]
+    if aliases:
+        names.extend(aliases)
+
+    for name in names:
+        _DEVICE_PROXY_REGISTRY[name] = entry
+
+
+def unregister_device_proxy(device_class: str) -> None:
+    """Unregister one DeviceProxy key.
+
+    This follows the ese774_frame behavior: only the specified key is removed.
+    If aliases were registered, remove each alias explicitly when needed.
+    """
+    _DEVICE_PROXY_REGISTRY.pop(device_class, None)
+
+
+def get_device_proxy_entry(device_class: str) -> DeviceProxyEntry:
+    """Return a registered DeviceProxyEntry."""
+    if device_class not in _DEVICE_PROXY_REGISTRY:
+        raise KeyError(
+            f"DeviceProxy is not registered: {device_class}. "
+            "Call register_device_proxy(...) first."
+        )
+    return _DEVICE_PROXY_REGISTRY[device_class]
+
+
+def list_device_proxies() -> List[str]:
+    """Return registered DeviceProxy keys."""
+    return sorted(_DEVICE_PROXY_REGISTRY.keys())
+
+
+def DeviceProxy(
+    device_class: str,
+    *args,
+    async_mode: Optional[bool] = None,
+    **kwargs,
+) -> Any:
+    """Create a client instance from a registered device_class.
+
+    Args:
+        device_class: Registered device class name or alias.
+        *args: Forwarded to the selected client class.
+        async_mode: True for async client, False for sync client, None to use
+            the registration default.
+        **kwargs: Forwarded to the selected client class.
+
+    Returns:
+        Async or sync client instance.
+    """
+    entry = get_device_proxy_entry(device_class)
+
+    if async_mode is None:
+        async_mode = entry.default_async_mode
+
+    if async_mode:
+        client_cls = entry.async_client_cls or AsyncGrpcClient
+        return client_cls(*args, **kwargs)
+
+    client_cls = entry.sync_client_cls or SyncGrpcClient
+    return client_cls(*args, **kwargs)
+
+
+def create_device_proxy(device_class: str):
+    """Create a DeviceProxy factory with fixed device_class.
+
+    This helper is compatible with ese774_frame and is useful for generating
+    package-local entry functions/classes that preserve IDE completion through
+    generated pyi files.
+    """
+
+    def proxy(
+        *args,
+        async_mode: Optional[bool] = None,
+        **kwargs,
+    ) -> Any:
+        return DeviceProxy(
+            device_class,
+            *args,
+            async_mode=async_mode,
+            **kwargs,
+        )
+
+    return proxy

grpc_frame/dispatch_core.py

@@ -0,0 +1,113 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+"""
+Kengo NAKADA
+kengo.nakada@mat.shimane-u.ac.jp
+kengo.nakada@gmail.com
+"""
+
+from __future__ import annotations
+from typing import Any, Dict, List, Optional, Union, Tuple, Callable, Sequence
+
+import inspect
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class MethodInfo:
+    """公開対象メソッドのメタ情報を保持するデータクラスである。
+
+    Attributes:
+        name: メソッド名である。
+        signature: 署名文字列である。取得できない場合は "()" とする。
+    """
+
+    name: str
+    signature: str
+
+
+def list_public_methods(
+    ctrl_obj: Any,
+) -> List[MethodInfo]:
+    """制御オブジェクトの public callable を列挙して MethodInfo の配列を返す関数である。
+
+    本関数は gRPC の Describe 用途を想定し、公開対象を「呼び出し可能な public メンバー」に限定する。
+    ここで property は列挙時に評価され得るため、静的取得で判定し、列挙対象から除外する。
+
+    Args:
+        ctrl_obj: 対象の制御オブジェクトである。
+
+    Returns:
+        List[MethodInfo]:
+            public callable の (name, signature) 一覧である。name 昇順にソートして返す。
+    """
+    # 収集したメソッド情報を格納するリスト
+    methods: List[MethodInfo] = []
+
+    # # BEFORE（旧版の要点：getmembers による列挙）
+    # for name, member in inspect.getmembers(ctrl_obj):
+    #     if name.startswith("_"):
+    #         continue
+
+    #     if not callable(member):
+    #         continue
+
+    #     signature = str(inspect.signature(member))
+    #     methods.append(MethodInfo(name=name, signature=signature))
+
+    # 新版
+    # inspect.getmembers(ctrl_obj) は property を評価し得るため使用しない
+    # dir() により名前一覧のみを取得し、値の評価を伴う走査を避ける
+    for name in dir(ctrl_obj):
+        # public 以外は除外する
+        if name.startswith("_"):
+            continue
+
+        # getattr_static() で descriptor を評価せずに取得する
+        try:
+            static_member = inspect.getattr_static(ctrl_obj, name)
+        except Exception:
+            # 取得不能な名前は列挙対象から外す設計
+            continue
+
+        # property は評価時に副作用（COM 呼び出し等）を生む可能性があるため除外する
+        # staticmethod/classmethod/callable のみを候補として扱う
+        if isinstance(static_member, property):
+            continue
+
+        is_candidate: bool = False
+
+        if isinstance(static_member, staticmethod):
+            is_candidate = True
+        elif isinstance(static_member, classmethod):
+            is_candidate = True
+        else:
+            if callable(static_member):
+                is_candidate = True
+
+        if not is_candidate:
+            continue
+
+        # 実体を取得し、呼び出し可能であることを確認する
+        try:
+            member = getattr(ctrl_obj, name)
+        except Exception:
+            # 実体取得で例外が出るものは列挙対象から外す
+            continue
+
+        if not callable(member):
+            continue
+
+        # callable の引数の形を表す情報、署名
+        # 署名を文字列化する。取得不能なら "()" に丸める。
+        sig: str = ""
+        try:
+            sig = str(inspect.signature(member))
+        except Exception:
+            sig = "()"
+
+        methods.append(MethodInfo(name=name, signature=sig))
+
+    # name 昇順にそろえて返す
+    methods.sort(key=lambda m: m.name)
+    return methods

grpc_frame/event_bus.py

@@ -0,0 +1,181 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+"""
+K.NAKADA, kengo.nakada@gmail.com, kengo.nakada@mat.shimane-u.ac.jp
+
+EventBus: 軽量な in-process イベント配信機構。
+
+- publish: イベントを配信
+- subscribe: イベントを generator で受信
+- スレッド間での待機/通知に Condition を使用
+"""
+
+from __future__ import annotations
+from dataclasses import dataclass
+from typing import Any, Deque, Dict, Iterator, List, Optional
+from collections import deque
+import threading
+import time
+
+
+@dataclass(frozen=True)
+class EventItem:
+    """EventBus が配信するイベント1件のデータ構造。"""
+
+    topic: str
+    payload_obj: Any
+    ts_ns: int
+    source: str
+
+
+class _Subscriber:
+    def __init__(
+        self,
+        topic: str,
+        *,
+        once: bool,
+        source: str,
+    ) -> None:
+        """
+        1トピックの購読状態を保持する内部クラス。
+        Condition + queue で publish/subscribe を同期する。
+        """
+
+        self.topic: str = topic
+        self.once: bool = once
+        self.source: str = source
+        self._cond: threading.Condition = threading.Condition()
+        self._queue: Deque[EventItem] = deque()
+        self._closed: bool = False
+
+    def close(self) -> None:
+        # 待機中の購読者を解除して終了させる
+        with self._cond:
+            self._closed = True
+            self._cond.notify_all()
+
+    def push(self, item: EventItem) -> None:
+        # publish からのイベントをキューへ
+        with self._cond:
+            if self._closed:
+                return
+            self._queue.append(item)
+            self._cond.notify_all()
+
+    def pop_wait(self) -> Optional[EventItem]:
+        # イベントが来るまでブロックして待機
+        with self._cond:
+            while True:
+                if self._closed:
+                    return None
+                if len(self._queue) > 0:
+                    item: EventItem = self._queue.popleft()
+                    return item
+                self._cond.wait()
+
+
+class EventBus:
+    """
+    in-process のイベント配信ハブ。
+
+    - publish: topic に紐づく購読者へ配信
+    - subscribe: generator 形式でイベントを取得
+    """
+
+    def __init__(self) -> None:
+        self._lock: threading.Lock = threading.Lock()
+        self._subscribers: List[_Subscriber] = []
+
+    def publish(
+        self,
+        topic: str,
+        payload_obj: Any,
+        *,
+        source: str = "",
+    ) -> None:
+        """
+        イベントを publish して、該当トピックの購読者へ通知する。
+
+        Args:
+            topic: トピック名
+            payload_obj: 任意の payload
+            source: 発生元識別子
+        """
+        # 配信時刻（ナノ秒）
+        ts_ns: int = time.time_ns()
+        item: EventItem = EventItem(
+            topic=topic,
+            payload_obj=payload_obj,
+            ts_ns=ts_ns,
+            source=source,
+        )
+
+        # 購読者リストのスナップショットを取る（ロック時間最小化）
+        subs_snapshot: List[_Subscriber] = []
+        with self._lock:
+            subs_snapshot = list(self._subscribers)
+
+        # 該当トピックにのみ配信
+        for sub in subs_snapshot:
+            if sub.topic != topic:
+                continue
+            sub.push(item)
+
+    def subscribe(
+        self,
+        topic: str,
+        *,
+        once: bool = False,
+        source: str = "",
+        cancel_event: Optional[threading.Event] = None,
+    ) -> Iterator[EventItem]:
+        """
+        指定トピックを購読し、EventItem を generator で返す。
+
+        Args:
+            topic: 購読するトピック
+            once: True の場合は1件受信したら終了
+            source: 発生元フィルタ（未使用だが拡張用）
+            cancel_event: 外部から購読解除するための Event
+
+        Yields:
+            EventItem
+        """
+        # 購読状態を生成
+        sub: _Subscriber = _Subscriber(
+            topic=topic,
+            once=once,
+            source=source,
+        )
+
+        with self._lock:
+            # 購読者リストに登録
+            self._subscribers.append(sub)
+
+        try:
+            while True:
+                if cancel_event is not None:
+                    if cancel_event.is_set():
+                        break
+
+                # イベントを待機して取得
+                item = sub.pop_wait()
+                if item is None:
+                    break
+
+                yield item
+
+                if sub.once:
+                    break
+
+        finally:
+            # 終了時に購読解除
+            sub.close()
+
+            with self._lock:
+                new_list: List[_Subscriber] = []
+                for s in self._subscribers:
+                    if s is sub:
+                        continue
+                    new_list.append(s)
+                self._subscribers = new_list