ephaptic 0.1.0__tar.gz

ephaptic-0.1.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,149 @@
+<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/ephaptic/__init__.py

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

ephaptic-0.1.0/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-0.1.0/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-0.1.0/ephaptic/client/__init__.py

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

ephaptic-0.1.0/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