ephaptic 0.1.0__py3-none-any.whl

ephaptic/__init__.py

@@ -0,0 +1,7 @@
+from .ephaptic import (
+    Ephaptic,
+)
+
+from .client import (
+    connect
+)

ephaptic/adapters/fastapi_.py

@@ -0,0 +1,30 @@
+from fastapi import FastAPI, WebSocket
+from ..transports.fastapi_ws import FastAPIWebSocketTransport
+
+class FastAPIAdapter:
+    def __init__(self, ephaptic, app: FastAPI, path, manager):
+        self.ephaptic = ephaptic
+
+        @app.websocket(path)
+        async def ephaptic_ws(websocket: WebSocket):
+            await websocket.accept()
+            transport = FastAPIWebSocketTransport(websocket)
+            await self.ephaptic.handle_transport(transport)
+
+        if manager.redis:
+            lifespan = app.router.lifespan_context
+
+            from contextlib import asynccontextmanager
+            import asyncio
+
+            @asynccontextmanager
+            async def ephaptic_lifespan_wrapper(app):
+                asyncio.create_task(manager.start_redis())
+
+                if lifespan:
+                    async with lifespan(app) as state:
+                        yield state
+                else:
+                    yield
+
+            app.router.lifespan_context = ephaptic_lifespan_wrapper

ephaptic/adapters/quart_.py

@@ -0,0 +1,16 @@
+from quart import websocket, Quart
+from ..transports.websocket import WebSocketTransport
+
+class QuartAdapter:
+    def __init__(self, ephaptic, app: Quart, path, manager):
+        self.ephaptic = ephaptic
+
+        @app.websocket(path)
+        async def ephaptic_ws():
+            transport = WebSocketTransport(websocket)
+            await self.ephaptic.handle_transport(transport)
+
+        if manager.redis:
+            @app.before_serving
+            async def start_redis():
+                app.add_background_task(manager.start_redis)

ephaptic/client/__init__.py

@@ -0,0 +1,3 @@
+from .client import (
+    connect
+)

ephaptic/client/client.py

@@ -0,0 +1,114 @@
+import asyncio
+import msgpack
+import websockets
+import logging
+
+from typing import Callable, Any
+import inspect
+
+class EphapticClient:
+    def __init__(self, url: str, auth = None):
+        self.url = url
+        self.auth = auth
+        self.ws = None
+        self._call_id = 0
+        self._pending_calls = {} # id -> asyncio.Future (asyncio.Future is a Python equivalent of a Promise)
+        self._event_handlers = {} # name: str -> Set(Callable)
+        self._listen_task = None
+
+    def _async(self, func: Callable):
+        async def wrapper(*args, **kwargs) -> Any:
+            if inspect.iscoroutinefunction(func):
+                return await func(*args, **kwargs)
+            else:
+                return await asyncio.to_thread(func, *args, **kwargs)
+        return wrapper
+
+    async def connect(self):
+        if self.ws: return
+
+        self.ws = await websockets.connect(self.url)
+
+        payload = {"type": "init"}
+        if self.auth: payload["auth"] = self.auth
+
+        await self.ws.send(msgpack.dumps(payload))
+
+        self._listen_task = asyncio.create_task(self._listener())
+
+    async def _listener(self):
+        try:
+            async for message in self.ws:
+                data = msgpack.loads(message)
+
+                if data.get('id') is not None:
+                    call_id = data['id']
+                    if call_id in self._pending_calls:
+                        future = self._pending_calls.pop(call_id)
+                        if 'error' in data:
+                            future.set_exception(Exception(data['error']))
+                        else:
+                            future.set_result(data.get('result'))
+                
+                elif data.get('type') == 'event':
+                    name = data['name']
+                    payload = data.get('payload', {})
+                    args = payload.get('args', [])
+                    kwargs = payload.get('kwargs', {})
+
+                    if name in self._event_handlers:
+                        for handler in self._event_handlers[name]:
+                            try:
+                                asyncio.create_task(self._async(handler)(*args, **kwargs))
+                                # We don't await it, we want to execute all handlers in parallel.
+                            except Exception as e:
+                                logging.error(f"Error in event handler {name}: {e}")
+        
+        except Exception as e:
+            logging.error(f"Connection error: {e}")
+
+    def on(self, event_name, func):
+        if event_name not in self._event_handlers: self._event_handlers[event_name] = set()
+        self._event_handlers[event_name].add(func)
+
+    def off(self, event_name, func):
+        if event_name not in self._event_handlers: return
+        s = self._event_handlers[event_name]
+        s.discard(func)
+        if not s: del self._event_handlers[event_name]
+
+    def once(self, event_name, func):
+        async def wrapper(*args, **kwargs):
+            self.off(event_name, wrapper)
+            func(*args, **kwargs)
+        self.on(event_name, wrapper)
+
+    def __getattr__(self, name):
+        async def remote_call(*args, **kwargs):
+            if not self.ws: await self.connect()
+
+            self._call_id += 1
+            call_id = self._call_id
+
+            future = asyncio.Future()
+            self._pending_calls[call_id] = future
+
+            payload = {
+                "type": "rpc",
+                "id": call_id,
+                "name": name,
+                "args": args,
+                "kwargs": kwargs,
+            }
+
+            await self.ws.send(msgpack.dumps(payload))
+            return await future
+        
+        return remote_call
+
+
+
+async def connect(url: str = "ws://localhost:8000/_ephaptic", auth = None):
+    client = EphapticClient(url, auth)
+    await client.connect()
+    return client

ephaptic/ephaptic.py

@@ -0,0 +1,200 @@
+import asyncio
+import msgpack
+import redis.asyncio as redis
+
+from contextvars import ContextVar
+from .localproxy import LocalProxy
+
+from .transports import Transport
+
+from typing import Optional, Callable, Any, List, Set, Dict
+import inspect
+
+_active_transport_ctx = ContextVar('active_transport', default=None)
+_active_user_ctx = ContextVar('active_user', default=None)
+
+active_user = LocalProxy(_active_user_ctx.get)
+
+CHANNEL_NAME = "ephaptic:broadcast"
+
+class ConnectionManager:
+    def __init__(self):
+        self.active: Dict[str, Set[Transport]] = {} # Map[user_id, Set[Transport]]
+        self.redis: Optional[redis.Redis] = None
+
+    def init_redis(self, url: str):
+        self.redis = redis.from_url(url)
+
+    def add(self, user_id: str, transport: Transport):
+        if user_id not in self.active: self.active[user_id] = set()
+        self.active[user_id].add(transport)
+
+    def remove(self, user_id: str, transport: Transport):
+        if user_id in self.active:
+            self.active[user_id].discard(transport)
+            if not self.active[user_id]: del self.active[user_id]
+
+    async def broadcast(self, user_ids: List[str], event_name: str, args: list, kwargs: dict):
+        payload = msgpack.dumps({
+            "target_users": user_ids,
+            "type": "event",
+            "name": event_name,
+            "payload": {"args": args, "kwargs": kwargs}
+        })
+
+        if self.redis: await self.redis.publish(CHANNEL_NAME, payload)
+        else: await self._send(user_ids, payload)
+
+    async def _send(self, user_ids: list[str], payload: bytes):
+        for user_id in user_ids:
+            if user_id in self.active:
+                for transport in list(self.active[user_id]):
+                    try:
+                        await transport.send(payload)
+                    except: pass
+
+    async def start_redis(self):
+        if not self.redis: return
+        pubsub = self.redis.pubsub()
+        await pubsub.subscribe(CHANNEL_NAME)
+        async for message in pubsub.listen():
+            if message['type'] == 'message':
+                data = msgpack.loads(message['data'])
+                targets = data.get('target_users', [])
+                await self._send(targets, message['data'])
+
+manager = ConnectionManager()
+
+class EphapticTarget:
+    def __init__(self, user_ids: list[str]):
+        self.user_ids = user_ids
+
+    def __getattr__(self, name: str):
+        async def emitter(*args, **kwargs):
+            await manager.broadcast(self.user_ids, name, list(args), dict(kwargs))
+        return emitter
+    
+class Ephaptic:
+    _exposed_functions: Dict[str, Callable] = {}
+    _identity_loader: Optional[Callable] = None
+
+    def _async(self, func: Callable):
+        async def wrapper(*args, **kwargs) -> Any:
+            if inspect.iscoroutinefunction(func):
+                return await func(*args, **kwargs)
+            else:
+                return await asyncio.to_thread(func, *args, **kwargs)
+        return wrapper
+
+    def __init__(self):
+        ...
+
+    @classmethod
+    def from_app(cls, app, path="/_ephaptic", redis_url=None):
+        # `app` could be Flask, Quart, FastAPI, etc.
+        instance = cls()
+
+        if redis_url:
+            manager.init_redis(redis_url)
+            # TODO: framework-specific hooks for the background listener.
+
+        module = app.__class__.__module__.split(".")[0]
+
+        match module:
+            case "quart":
+                from .adapters.quart_ import QuartAdapter
+                adapter = QuartAdapter(instance, app, path, manager)
+            case "fastapi":
+                from .adapters.fastapi_ import FastAPIAdapter
+                adapter = FastAPIAdapter(instance, app, path, manager)
+            case _:
+                raise TypeError(f"Unsupported app type: {module}")
+
+            
+    def expose(self, func: Callable):
+        self._exposed_functions[func.__name__] = func
+        return func
+    
+    def identity_loader(self, func: Callable):
+        self._identity_loader = func
+        return func
+    
+    def to(self, *args):
+        targets = []
+        for arg in args:
+            if isinstance(arg, list): targets.extend(arg)
+            else: targets.append(arg)
+        return EphapticTarget(targets)
+    
+    def __getattr__(self, name: str):
+        async def emitter(*args, **kwargs):
+            transport: Transport = _active_transport_ctx.get()
+            if not transport:
+                raise RuntimeError(
+                    f".{name}() called outside RPC context."
+                    f"Use .to(...).{name}() to broadcast from background tasks, to specific user(s)."
+                )
+            
+            await transport.send(msgpack.dumps({
+                "type": "event",
+                "name": name,
+                "payload": {"args": list(args), "kwargs": dict(kwargs)},
+            }))
+        
+        return emitter
+    
+    async def handle_transport(self, transport: Transport):
+        current_uid = None
+        try:
+            raw = await transport.receive()
+            init = msgpack.loads(raw)
+
+            if init.get('type') == 'init':
+                try:
+                    if self._identity_loader:
+                        current_uid = await self._async(self._identity_loader)(init.get('auth'))
+                    
+                    if current_uid:
+                        _active_user_ctx.set(current_uid)
+                        manager.add(current_uid, transport)
+                    else:
+                        pass
+                except Exception:
+                    import traceback
+                    traceback.print_exc()
+
+            while True:
+                raw = await transport.receive()
+                data = msgpack.loads(raw)
+
+                if data.get('type') == 'rpc':
+                    call_id = data.get('id')
+                    func_name = data.get('name')
+                    args = data.get('args', [])
+                    kwargs = data.get('kwargs', {}) # Note: Only Python client (currently) sends these, JS client does not.
+
+                    if func_name in self._exposed_functions:
+                        target_func = self._exposed_functions[func_name]
+                        token_transport = _active_transport_ctx.set(transport)
+                        token_user = _active_user_ctx.set(current_uid)
+
+                        try:
+                            result = await self._async(target_func)(*args, **kwargs)
+                            await transport.send(msgpack.dumps({"id": call_id, "result": result}))
+                        except Exception as e:
+                            await transport.send(msgpack.dumps({"id": call_id, "error": str(e)}))
+                        finally:
+                            _active_transport_ctx.reset(token_transport)
+                            _active_user_ctx.reset(token_user)
+                    else:
+                        await transport.send(msgpack.dumps({
+                            "id": call_id, 
+                            "error": f"Function '{func_name}' not found."
+                        }))
+        except asyncio.CancelledError:
+            ...
+        except Exception:
+            import traceback
+            traceback.print_exc()
+        finally:
+            if current_uid: manager.remove(current_uid, transport)

ephaptic/localproxy.py

@@ -0,0 +1,557 @@
+import copy
+import math
+import operator
+import typing as t
+from contextvars import ContextVar
+from functools import partial
+from operator import attrgetter
+
+T = t.TypeVar("T")
+F = t.TypeVar("F", bound=t.Callable[..., t.Any])
+
+
+class Local:
+    """Create a namespace of context-local data. This wraps a
+    :class:`ContextVar` containing a :class:`dict` value.
+
+    This may incur a performance penalty compared to using individual
+    context vars, as it has to copy data to avoid mutating the dict
+    between nested contexts.
+
+    :param context_var: The :class:`~contextvars.ContextVar` to use as
+        storage for this local. If not given, one will be created.
+        Context vars not created at the global scope may interfere with
+        garbage collection.
+
+    .. versionchanged:: 2.0
+        Uses ``ContextVar`` instead of a custom storage implementation.
+    """
+
+    __slots__ = ("__storage",)
+
+    def __init__(
+        self, context_var: t.Optional[ContextVar[t.Dict[str, t.Any]]] = None
+    ) -> None:
+        if context_var is None:
+            # A ContextVar not created at global scope interferes with
+            # Python's garbage collection. However, a local only makes
+            # sense defined at the global scope as well, in which case
+            # the GC issue doesn't seem relevant.
+            context_var = ContextVar(f"contextlocal.Local<{id(self)}>.storage")
+
+        object.__setattr__(self, "_Local__storage", context_var)
+
+    def __iter__(self) -> t.Iterator[t.Tuple[str, t.Any]]:
+        return iter(self.__storage.get({}).items())
+
+    def __call__(
+        self, name: str, *, unbound_message: t.Optional[str] = None
+    ) -> "LocalProxy":
+        """Create a :class:`LocalProxy` that access an attribute on this
+        local namespace.
+
+        :param name: Proxy this attribute.
+        :param unbound_message: The error message that the proxy will
+            show if the attribute isn't set.
+        """
+        return LocalProxy(self, name, unbound_message=unbound_message)
+
+    def __release_local__(self) -> None:
+        self.__storage.set({})
+
+    def __getattr__(self, name: str) -> t.Any:
+        values = self.__storage.get({})
+
+        if name in values:
+            return values[name]
+
+        raise AttributeError(name)
+
+    def __setattr__(self, name: str, value: t.Any) -> None:
+        values = self.__storage.get({}).copy()
+        values[name] = value
+        self.__storage.set(values)
+
+    def __delattr__(self, name: str) -> None:
+        values = self.__storage.get({})
+
+        if name in values:
+            values = values.copy()
+            del values[name]
+            self.__storage.set(values)
+        else:
+            raise AttributeError(name)
+
+
+class LocalStack(t.Generic[T]):
+    """Create a stack of context-local data. This wraps a
+    :class:`ContextVar` containing a :class:`list` value.
+
+    This may incur a performance penalty compared to using individual
+    context vars, as it has to copy data to avoid mutating the list
+    between nested contexts.
+
+    :param context_var: The :class:`~contextvars.ContextVar` to use as
+        storage for this local. If not given, one will be created.
+        Context vars not created at the global scope may interfere with
+        garbage collection.
+
+    .. versionchanged:: 2.0
+        Uses ``ContextVar`` instead of a custom storage implementation.
+
+    .. versionadded:: 0.6.1
+    """
+
+    __slots__ = ("_storage",)
+
+    def __init__(self, context_var: t.Optional[ContextVar[t.List[T]]] = None) -> None:
+        if context_var is None:
+            # A ContextVar not created at global scope interferes with
+            # Python's garbage collection. However, a local only makes
+            # sense defined at the global scope as well, in which case
+            # the GC issue doesn't seem relevant.
+            context_var = ContextVar(f"contextlocal.LocalStack<{id(self)}>.storage")
+
+        self._storage = context_var
+
+    def __release_local__(self) -> None:
+        self._storage.set([])
+
+    def push(self, obj: T) -> t.List[T]:
+        """Add a new item to the top of the stack."""
+        stack = self._storage.get([]).copy()
+        stack.append(obj)
+        self._storage.set(stack)
+        return stack
+
+    def pop(self) -> t.Optional[T]:
+        """Remove the top item from the stack and return it. If the
+        stack is empty, return ``None``.
+        """
+        stack = self._storage.get([])
+
+        if len(stack) == 0:
+            return None
+
+        rv = stack[-1]
+        self._storage.set(stack[:-1])
+        return rv
+
+    @property
+    def top(self) -> t.Optional[T]:
+        """The topmost item on the stack.  If the stack is empty,
+        `None` is returned.
+        """
+        stack = self._storage.get([])
+
+        if len(stack) == 0:
+            return None
+
+        return stack[-1]
+
+    def __call__(
+        self, name: t.Optional[str] = None, *, unbound_message: t.Optional[str] = None
+    ) -> "LocalProxy":
+        """Create a :class:`LocalProxy` that accesses the top of this
+        local stack.
+
+        :param name: If given, the proxy access this attribute of the
+            top item, rather than the item itself.
+        :param unbound_message: The error message that the proxy will
+            show if the stack is empty.
+        """
+        return LocalProxy(self, name, unbound_message=unbound_message)
+
+
+class _ProxyLookup:
+    """Descriptor that handles proxied attribute lookup for
+    :class:`LocalProxy`.
+
+    :param f: The built-in function this attribute is accessed through.
+        Instead of looking up the special method, the function call
+        is redone on the object.
+    :param fallback: Return this function if the proxy is unbound
+        instead of raising a :exc:`RuntimeError`.
+    :param is_attr: This proxied name is an attribute, not a function.
+        Call the fallback immediately to get the value.
+    :param class_value: Value to return when accessed from the
+        ``LocalProxy`` class directly. Used for ``__doc__`` so building
+        docs still works.
+    """
+
+    __slots__ = ("bind_f", "fallback", "is_attr", "class_value", "name")
+
+    def __init__(
+        self,
+        f: t.Optional[t.Callable] = None,
+        fallback: t.Optional[t.Callable] = None,
+        class_value: t.Optional[t.Any] = None,
+        is_attr: bool = False,
+    ) -> None:
+        bind_f: t.Optional[t.Callable[["LocalProxy", t.Any], t.Callable]]
+
+        if hasattr(f, "__get__"):
+            # A Python function, can be turned into a bound method.
+
+            def bind_f(instance: "LocalProxy", obj: t.Any) -> t.Callable:
+                return f.__get__(obj, type(obj))  # type: ignore
+
+        elif f is not None:
+            # A C function, use partial to bind the first argument.
+
+            def bind_f(instance: "LocalProxy", obj: t.Any) -> t.Callable:
+                return partial(f, obj)
+
+        else:
+            # Use getattr, which will produce a bound method.
+            bind_f = None
+
+        self.bind_f = bind_f
+        self.fallback = fallback
+        self.class_value = class_value
+        self.is_attr = is_attr
+
+    def __set_name__(self, owner: "LocalProxy", name: str) -> None:
+        self.name = name
+
+    def __get__(self, instance: "LocalProxy", owner: t.Optional[type] = None) -> t.Any:
+        if instance is None:
+            if self.class_value is not None:
+                return self.class_value
+
+            return self
+
+        try:
+            obj = instance._get_current_object()
+        except RuntimeError:
+            if self.fallback is None:
+                raise
+
+            fallback = self.fallback.__get__(instance, owner)
+
+            if self.is_attr:
+                # __class__ and __doc__ are attributes, not methods.
+                # Call the fallback to get the value.
+                return fallback()
+
+            return fallback
+
+        if self.bind_f is not None:
+            return self.bind_f(instance, obj)
+
+        return getattr(obj, self.name)
+
+    def __repr__(self) -> str:
+        return f"proxy {self.name}"
+
+    def __call__(self, instance: "LocalProxy", *args: t.Any, **kwargs: t.Any) -> t.Any:
+        """Support calling unbound methods from the class. For example,
+        this happens with ``copy.copy``, which does
+        ``type(x).__copy__(x)``. ``type(x)`` can't be proxied, so it
+        returns the proxy type and descriptor.
+        """
+        return self.__get__(instance, type(instance))(*args, **kwargs)
+
+
+class _ProxyIOp(_ProxyLookup):
+    """Look up an augmented assignment method on a proxied object. The
+    method is wrapped to return the proxy instead of the object.
+    """
+
+    __slots__ = ()
+
+    def __init__(
+        self, f: t.Optional[t.Callable] = None, fallback: t.Optional[t.Callable] = None
+    ) -> None:
+        super().__init__(f, fallback)
+
+        def bind_f(instance: "LocalProxy", obj: t.Any) -> t.Callable:
+            def i_op(self: t.Any, other: t.Any) -> "LocalProxy":
+                f(self, other)  # type: ignore
+                return instance
+
+            return i_op.__get__(obj, type(obj))  # type: ignore
+
+        self.bind_f = bind_f
+
+
+def _l_to_r_op(op: F) -> F:
+    """Swap the argument order to turn an l-op into an r-op."""
+
+    def r_op(obj: t.Any, other: t.Any) -> t.Any:
+        return op(other, obj)
+
+    return t.cast(F, r_op)
+
+
+def _identity(o: T) -> T:
+    return o
+
+
+class LocalProxy(t.Generic[T]):
+    """A proxy to the object bound to a context-local object. All
+    operations on the proxy are forwarded to the bound object. If no
+    object is bound, a ``RuntimeError`` is raised.
+
+    :param local: The context-local object that provides the proxied
+        object.
+    :param name: Proxy this attribute from the proxied object.
+    :param unbound_message: The error message to show if the
+        context-local object is unbound.
+
+    Proxy a :class:`~contextvars.ContextVar` to make it easier to
+    access. Pass a name to proxy that attribute.
+
+    .. code-block:: python
+
+        _request_var = ContextVar("request")
+        request = LocalProxy(_request_var)
+        session = LocalProxy(_request_var, "session")
+
+    Proxy an attribute on a :class:`Local` namespace by calling the
+    local with the attribute name:
+
+    .. code-block:: python
+
+        data = Local()
+        user = data("user")
+
+    Proxy the top item on a :class:`LocalStack` by calling the local.
+    Pass a name to proxy that attribute.
+
+    .. code-block::
+
+        app_stack = LocalStack()
+        current_app = app_stack()
+        g = app_stack("g")
+
+    Pass a function to proxy the return value from that function. This
+    was previously used to access attributes of local objects before
+    that was supported directly.
+
+    .. code-block:: python
+
+        session = LocalProxy(lambda: request.session)
+
+    ``__repr__`` and ``__class__`` are proxied, so ``repr(x)`` and
+    ``isinstance(x, cls)`` will look like the proxied object. Use
+    ``issubclass(type(x), LocalProxy)`` to check if an object is a
+    proxy.
+
+    .. code-block:: python
+
+        repr(user)  # <User admin>
+        isinstance(user, User)  # True
+        issubclass(type(user), LocalProxy)  # True
+
+    .. versionchanged:: 2.2.2
+        ``__wrapped__`` is set when wrapping an object, not only when
+        wrapping a function, to prevent doctest from failing.
+
+    .. versionchanged:: 2.2
+        Can proxy a ``ContextVar`` or ``LocalStack`` directly.
+
+    .. versionchanged:: 2.2
+        The ``name`` parameter can be used with any proxied object, not
+        only ``Local``.
+
+    .. versionchanged:: 2.2
+        Added the ``unbound_message`` parameter.
+
+    .. versionchanged:: 2.0
+        Updated proxied attributes and methods to reflect the current
+        data model.
+
+    .. versionchanged:: 0.6.1
+        The class can be instantiated with a callable.
+    """
+
+    __slots__ = ("__wrapped", "_get_current_object")
+
+    _get_current_object: t.Callable[[], T]
+    """Return the current object this proxy is bound to. If the proxy is
+    unbound, this raises a ``RuntimeError``.
+
+    This should be used if you need to pass the object to something that
+    doesn't understand the proxy. It can also be useful for performance
+    if you are accessing the object multiple times in a function, rather
+    than going through the proxy multiple times.
+    """
+
+    def __init__(
+        self,
+        local: t.Union[ContextVar[T], Local, LocalStack[T], t.Callable[[], T]],
+        name: t.Optional[str] = None,
+        *,
+        unbound_message: t.Optional[str] = None,
+    ) -> None:
+        if name is None:
+            get_name = _identity
+        else:
+            get_name = attrgetter(name)  # type: ignore[assignment]
+
+        if unbound_message is None:
+            unbound_message = "object is not bound"
+
+        if isinstance(local, Local):
+            if name is None:
+                raise TypeError("'name' is required when proxying a 'Local' object.")
+
+            def _get_current_object() -> T:
+                try:
+                    return get_name(local)  # type: ignore[return-value]
+                except AttributeError:
+                    raise RuntimeError(unbound_message) from None
+
+        elif isinstance(local, LocalStack):
+
+            def _get_current_object() -> T:
+                obj = local.top  # type: ignore[union-attr]
+
+                if obj is None:
+                    raise RuntimeError(unbound_message)
+
+                return get_name(obj)
+
+        elif isinstance(local, ContextVar):
+
+            def _get_current_object() -> T:
+                try:
+                    obj = local.get()  # type: ignore[union-attr]
+                except LookupError:
+                    raise RuntimeError(unbound_message) from None
+
+                return get_name(obj)
+
+        elif callable(local):
+
+            def _get_current_object() -> T:
+                return get_name(local())  # type: ignore
+
+        else:
+            raise TypeError(f"Don't know how to proxy '{type(local)}'.")
+
+        object.__setattr__(self, "_LocalProxy__wrapped", local)
+        object.__setattr__(self, "_get_current_object", _get_current_object)
+
+    __doc__ = _ProxyLookup(  # type: ignore
+        class_value=__doc__, fallback=lambda self: type(self).__doc__, is_attr=True
+    )
+    __wrapped__ = _ProxyLookup(
+        fallback=lambda self: self._LocalProxy__wrapped, is_attr=True
+    )
+    # __del__ should only delete the proxy
+    __repr__ = _ProxyLookup(  # type: ignore
+        repr, fallback=lambda self: f"<{type(self).__name__} unbound>"
+    )
+    __str__ = _ProxyLookup(str)  # type: ignore
+    __bytes__ = _ProxyLookup(bytes)
+    __format__ = _ProxyLookup()  # type: ignore
+    __lt__ = _ProxyLookup(operator.lt)
+    __le__ = _ProxyLookup(operator.le)
+    __eq__ = _ProxyLookup(operator.eq)  # type: ignore
+    __ne__ = _ProxyLookup(operator.ne)  # type: ignore
+    __gt__ = _ProxyLookup(operator.gt)
+    __ge__ = _ProxyLookup(operator.ge)
+    __hash__ = _ProxyLookup(hash)  # type: ignore
+    __bool__ = _ProxyLookup(bool, fallback=lambda self: False)
+    __getattr__ = _ProxyLookup(getattr)
+    # __getattribute__ triggered through __getattr__
+    __setattr__ = _ProxyLookup(setattr)  # type: ignore
+    __delattr__ = _ProxyLookup(delattr)  # type: ignore
+    __dir__ = _ProxyLookup(dir, fallback=lambda self: [])  # type: ignore
+    # __get__ (proxying descriptor not supported)
+    # __set__ (descriptor)
+    # __delete__ (descriptor)
+    # __set_name__ (descriptor)
+    # __objclass__ (descriptor)
+    # __slots__ used by proxy itself
+    # __dict__ (__getattr__)
+    # __weakref__ (__getattr__)
+    # __init_subclass__ (proxying metaclass not supported)
+    # __prepare__ (metaclass)
+    __class__ = _ProxyLookup(
+        fallback=lambda self: type(self), is_attr=True
+    )  # type: ignore
+    __instancecheck__ = _ProxyLookup(lambda self, other: isinstance(other, self))
+    __subclasscheck__ = _ProxyLookup(lambda self, other: issubclass(other, self))
+    # __class_getitem__ triggered through __getitem__
+    __call__ = _ProxyLookup(lambda self, *args, **kwargs: self(*args, **kwargs))
+    __len__ = _ProxyLookup(len)
+    __length_hint__ = _ProxyLookup(operator.length_hint)
+    __getitem__ = _ProxyLookup(operator.getitem)
+    __setitem__ = _ProxyLookup(operator.setitem)
+    __delitem__ = _ProxyLookup(operator.delitem)
+    # __missing__ triggered through __getitem__
+    __iter__ = _ProxyLookup(iter)
+    __next__ = _ProxyLookup(next)
+    __reversed__ = _ProxyLookup(reversed)
+    __contains__ = _ProxyLookup(operator.contains)
+    __add__ = _ProxyLookup(operator.add)
+    __sub__ = _ProxyLookup(operator.sub)
+    __mul__ = _ProxyLookup(operator.mul)
+    __matmul__ = _ProxyLookup(operator.matmul)
+    __truediv__ = _ProxyLookup(operator.truediv)
+    __floordiv__ = _ProxyLookup(operator.floordiv)
+    __mod__ = _ProxyLookup(operator.mod)
+    __divmod__ = _ProxyLookup(divmod)
+    __pow__ = _ProxyLookup(pow)
+    __lshift__ = _ProxyLookup(operator.lshift)
+    __rshift__ = _ProxyLookup(operator.rshift)
+    __and__ = _ProxyLookup(operator.and_)
+    __xor__ = _ProxyLookup(operator.xor)
+    __or__ = _ProxyLookup(operator.or_)
+    __radd__ = _ProxyLookup(_l_to_r_op(operator.add))
+    __rsub__ = _ProxyLookup(_l_to_r_op(operator.sub))
+    __rmul__ = _ProxyLookup(_l_to_r_op(operator.mul))
+    __rmatmul__ = _ProxyLookup(_l_to_r_op(operator.matmul))
+    __rtruediv__ = _ProxyLookup(_l_to_r_op(operator.truediv))
+    __rfloordiv__ = _ProxyLookup(_l_to_r_op(operator.floordiv))
+    __rmod__ = _ProxyLookup(_l_to_r_op(operator.mod))
+    __rdivmod__ = _ProxyLookup(_l_to_r_op(divmod))
+    __rpow__ = _ProxyLookup(_l_to_r_op(pow))
+    __rlshift__ = _ProxyLookup(_l_to_r_op(operator.lshift))
+    __rrshift__ = _ProxyLookup(_l_to_r_op(operator.rshift))
+    __rand__ = _ProxyLookup(_l_to_r_op(operator.and_))
+    __rxor__ = _ProxyLookup(_l_to_r_op(operator.xor))
+    __ror__ = _ProxyLookup(_l_to_r_op(operator.or_))
+    __iadd__ = _ProxyIOp(operator.iadd)
+    __isub__ = _ProxyIOp(operator.isub)
+    __imul__ = _ProxyIOp(operator.imul)
+    __imatmul__ = _ProxyIOp(operator.imatmul)
+    __itruediv__ = _ProxyIOp(operator.itruediv)
+    __ifloordiv__ = _ProxyIOp(operator.ifloordiv)
+    __imod__ = _ProxyIOp(operator.imod)
+    __ipow__ = _ProxyIOp(operator.ipow)
+    __ilshift__ = _ProxyIOp(operator.ilshift)
+    __irshift__ = _ProxyIOp(operator.irshift)
+    __iand__ = _ProxyIOp(operator.iand)
+    __ixor__ = _ProxyIOp(operator.ixor)
+    __ior__ = _ProxyIOp(operator.ior)
+    __neg__ = _ProxyLookup(operator.neg)
+    __pos__ = _ProxyLookup(operator.pos)
+    __abs__ = _ProxyLookup(abs)
+    __invert__ = _ProxyLookup(operator.invert)
+    __complex__ = _ProxyLookup(complex)
+    __int__ = _ProxyLookup(int)
+    __float__ = _ProxyLookup(float)
+    __index__ = _ProxyLookup(operator.index)
+    __round__ = _ProxyLookup(round)
+    __trunc__ = _ProxyLookup(math.trunc)
+    __floor__ = _ProxyLookup(math.floor)
+    __ceil__ = _ProxyLookup(math.ceil)
+    __enter__ = _ProxyLookup()
+    __exit__ = _ProxyLookup()
+    __await__ = _ProxyLookup()
+    __aiter__ = _ProxyLookup()
+    __anext__ = _ProxyLookup()
+    __aenter__ = _ProxyLookup()
+    __aexit__ = _ProxyLookup()
+    __copy__ = _ProxyLookup(copy.copy)
+    __deepcopy__ = _ProxyLookup(copy.deepcopy)
+    # __getnewargs_ex__ (pickle through proxy not supported)
+    # __getnewargs__ (pickle)
+    # __getstate__ (pickle)
+    # __setstate__ (pickle)
+    # __reduce__ (pickle)
+    # __reduce_ex__ (pickle)

ephaptic/transports/__init__.py

@@ -0,0 +1,5 @@
+from typing import Coroutine
+
+class Transport:
+    async def send(data: bytes): raise NotImplementedError()
+    async def receive() -> bytes: raise NotImplementedError()

ephaptic/transports/fastapi_ws.py

@@ -0,0 +1,8 @@
+from .websocket import WebSocketTransport
+
+class FastAPIWebSocketTransport(WebSocketTransport):
+    async def send(self, data: bytes):
+        await self.ws.send_bytes(data)
+
+    async def receive(self) -> bytes:
+        return await self.ws.receive_bytes()

ephaptic/transports/websocket.py

@@ -0,0 +1,11 @@
+from . import Transport
+
+class WebSocketTransport(Transport):
+    def __init__(self, ws):
+        self.ws = ws
+
+    async def send(self, data: bytes):
+        await self.ws.send(data)
+
+    async def receive(self) -> bytes:
+        return await self.ws.receive()

ephaptic-0.1.0.dist-info/METADATA

@@ -0,0 +1,188 @@
+Metadata-Version: 2.4
+Name: ephaptic
+Version: 0.1.0
+Summary: The Python client/server package for ephaptic.
+Author-email: uukelele <robustrobot11@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2025 ephaptic
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/ephaptic/ephaptic
+Project-URL: Repository, https://github.com/ephaptic/ephaptic
+Project-URL: Issue Tracker, https://github.com/ephaptic/ephaptic/issues
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: msgpack>=1.0.0
+Requires-Dist: websockets>=12.0
+Provides-Extra: server
+Requires-Dist: redis; extra == "server"
+Dynamic: license-file
+
+<div align="center">
+    <a href="https://github.com/ephaptic/ephaptic">
+        <picture>
+            <img src="https://raw.githubusercontent.com/ephaptic/ephaptic/refs/heads/main/.github/assets/logo.png" alt="ephaptic logo" height="200">
+            <!-- <img src="https://avatars.githubusercontent.com/u/248199226?s=256" alt="ephaptic logo" height="200> -->
+        </picture>
+    </a>
+<br>
+<h1>ephaptic</h1>
+<br>
+<a href="https://github.com/ephaptic/ephaptic/blob/main/LICENSE"><img alt="GitHub License" src="https://img.shields.io/github/license/ephaptic/ephaptic?style=for-the-badge&labelColor=%23222222"></a> <img alt="GitHub Actions Workflow Status" src="https://img.shields.io/github/actions/workflow/status/ephaptic/ephaptic/publish-js.yml?style=for-the-badge&label=NPM%20Build%20Status&labelColor=%23222222"> <img alt="GitHub Actions Workflow Status" src="https://img.shields.io/github/actions/workflow/status/ephaptic/ephaptic/publish-python.yml?style=for-the-badge&label=PyPI%20Build%20Status&labelColor=%23222222">
+
+
+</div>
+
+## What is `ephaptic`?
+
+<br>
+
+<blockquote>
+    <b>ephaptic (adj.)</b><br>
+    electrical conduction of a nerve impulse across an ephapse without the mediation of a neurotransmitter.
+</blockquote>
+
+Nah, just kidding. It's an RPC framework.
+
+> **ephaptic** — Call your backend straight from your frontend. No JSON. No latency. No middleware.
+
+## Getting Started
+
+- Ephaptic is designed to be invisible. Write a function on the server, call it on the client. No extra boilerplate.
+
+- Plus, it's horizontally scalable with Redis (optional), and features extremely low latency thanks to [msgpack](https://github.com/msgpack).
+
+- Oh, and the client can also listen to events broadcasted by the server. No, like literally. You just need to add an `eventListener`. Did I mention? Events can be sent to specific targets, specific users - not just anyone online.
+
+What are  you waiting for? **Let's go.**
+
+<details>
+    <summary>Python</summary>
+    
+#### Client:
+
+```
+pip install ephaptic
+```
+
+#### Server:
+
+```
+pip install ephaptic[server]
+```
+
+```python
+from fastapi import FastAPI # or `from quart import Quart`
+from ephaptic import Ephaptic
+
+app = FastAPI() # or `app = Quart(__name__)`
+
+ephaptic = Ephaptic.from_app(app) # Finds which framework you're using, and creates an ephaptic server.
+```
+
+You can also specify a custom path:
+
+```python
+ephaptic = Ephaptic.from_app(app, path="/websocket")
+```
+
+And you can even use Redis for horizontal scaling!
+
+```python
+ephaptic = Ephaptic.from_app(app, redis_url="redis://my-redis-container:6379/0")
+```
+
+Now, how do you expose your function to the frontend?
+
+```python
+@ephaptic.expose
+async def add(num1, num2):
+    return num1 + num2
+```
+
+Yep, it's really that simple.
+
+But what if your code throws an error? No sweat, it just throws up on the frontend with the same details.
+
+And, want to say something to the frontend?
+
+```python
+await ephaptic.to(user1, user2).notification("Hello, world!", priority="high")
+```
+
+
+</details>
+
+<details>
+    <summary>JavaScript/TypeScript — Browser (Svelt, React, Angular, Vite, etc.)</summary>
+
+#### To use with a framework / Vite:
+
+```
+npm install @ephaptic/client
+```
+
+Then:
+
+```typescript
+import { connect } from "@ephaptic/client";
+
+const client = connect(); // Defaults to `/_ephaptic`.
+```
+
+Or, you can use it with a custom URL:
+
+```typescript
+const client = connect({ url: '/ws' });
+```
+
+```typescript
+const client = connect({ url: 'wss://my-backend.deployment/ephaptic' });
+```
+
+You can even send auth objects to the server for identity loading.
+
+```typescript
+const client = connect({ url: '...', auth: { token: window.localStorage.getItem('jwtToken') } })
+```
+
+#### Or, to use in your browser:
+
+```html
+<script type="module">
+import { connect } from 'https://cdn.jsdelivr.net/npm/@ephaptic/client@latest/+esm';
+
+const client = connect();
+</script>
+```
+
+<!-- TODO: Add extended documentation -->
+
+</details>
+
+## [License](https://github.com/ephaptic/ephaptic/blob/main/LICENSE)
+
+---
+
+<p align="center">
+    &copy; ephaptic 2025
+</p>

ephaptic-0.1.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+ephaptic/__init__.py,sha256=rz-zKp0bx6p7K9t3OGgTzYBlA5hZ1q1Gx8l00DzYJ8A,76
+ephaptic/ephaptic.py,sha256=x3DAbAsV3mlikxjX4RT6hx-I9AzmlOIPy8ZwF31ySTs,7318
+ephaptic/localproxy.py,sha256=fJaaskkiD6C2zaOod0F0HNWIbdKs_JMuHFwd0-sdLIM,19477
+ephaptic/adapters/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ephaptic/adapters/fastapi_.py,sha256=yfSbJuA7Tgeh9EhZkfIve0Uj-cOZmTBljlBsCRKh2EE,1007
+ephaptic/adapters/quart_.py,sha256=MBo9g6h_zI63mL4aGdrvV5yEXsHaOd0Iv5J8SAPHBoA,537
+ephaptic/client/__init__.py,sha256=NeaPIzTFeozP54wlDYHIg_adHP3Z3LWVujsRUlpn4_U,35
+ephaptic/client/client.py,sha256=nM54QgdD55w2J5wEWRjOogJQEE5_XmACrWKdikpNvZM,3863
+ephaptic/transports/__init__.py,sha256=kSAlgvm8sV9nHHu61LTjjTpv4bweah90xvFrwQMDQtQ,169
+ephaptic/transports/fastapi_ws.py,sha256=X0PMRcwM-KDpKA-zXShGTFhD1kHMSqrx3PBBKZtQ1W0,258
+ephaptic/transports/websocket.py,sha256=jwgclSDSq0lQCvgwjwUXe9MzPk7NH0FdmsLhWxYBh-4,261
+ephaptic-0.1.0.dist-info/licenses/LICENSE,sha256=kMpJjLKMj6zsAhf4uHApO4q0r31Ye1VyfBOl9cFW13M,1065
+ephaptic-0.1.0.dist-info/METADATA,sha256=Fca5koF2PY6a6LwdIG7FLpJMqMvlj1hXR4hmYQ2c6CI,5892
+ephaptic-0.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+ephaptic-0.1.0.dist-info/top_level.txt,sha256=nNhdhcz2o_IuwZ9I2uWQuLZrRmSW0dQVU3qwGrb35Io,9
+ephaptic-0.1.0.dist-info/RECORD,,

ephaptic-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

ephaptic-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 ephaptic
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ephaptic-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+ephaptic