ephaptic 0.1.3__py3-none-any.whl → 0.2.1__py3-none-any.whl

ephaptic/__init__.py

@@ -1,6 +1,8 @@
 from .ephaptic import (
     Ephaptic,
-    active_user
+    active_user,
+    expose,
+    identity_loader,
 )
 
 from .client import (

ephaptic/cli/__init__.py

@@ -0,0 +1,3 @@
+from .__main__ import app
+
+__all__ = ["app"]

ephaptic/cli/__main__.py

@@ -0,0 +1,106 @@
+import sys, os, json, inspect, importlib, typing, typer
+
+from pathlib import Path
+from pydantic import TypeAdapter
+from pydantic.json_schema import models_json_schema
+
+from ephaptic import Ephaptic
+
+app = typer.Typer(help="Ephaptic CLI tool.")
+
+def load_ephaptic(import_name: str) -> Ephaptic:
+    try:
+        from dotenv import load_dotenv; load_dotenv()
+    except: ...
+
+    sys.path.insert(0, os.getcwd())
+
+    if ":" not in import_name:
+        typer.secho(f"Warning: Import name did not specify app name. Defaulting to `app`.", fg=typer.colors.YELLOW)
+        import_name += ":app" # default: expect app to be named `app` inside the file
+
+    module_name, var_name = import_name.split(":", 1)
+
+    try:
+        typer.secho(f"Attempting to import `{var_name}` from `{module_name}`...")
+        module = importlib.import_module(module_name)
+    except ImportError as e:
+        typer.secho(f"Error: Can't import '{module_name}'.\n{e}", fg=typer.colors.RED)
+        raise typer.Exit(1)
+    
+    try:
+        instance = getattr(module, var_name)
+    except AttributeError:
+        typer.secho(f"Error: Variable '{var_name}' not found in module '{module_name}'.", fg=typer.colors.RED)
+        raise typer.Exit(1)
+    
+    if not isinstance(instance, Ephaptic):
+        typer.secho(f"Error: '{var_name}' is not an Ephaptic instance. It is type: {type(instance)}", fg=typer.colors.RED)
+        raise typer.Exit(1)
+    
+    return instance
+
+def create_schema(adapter: TypeAdapter, definitions: dict) -> dict:
+    schema = adapter.json_schema(ref_template='#/definitions/{model}')
+
+    if '$defs' in schema:
+        definitions.update(schema.pop('$defs'))
+
+    if schema.get('type') == 'object' and 'title' in schema:
+        model = schema['title']
+        definitions[model] = schema
+        return { '$ref': f'#/definitions/{model}' }
+    
+    return schema
+
+@app.command()
+def generate(
+    app: str = typer.Argument('app:app', help="The import string. (Default: `app:app`)"),
+    output: Path = typer.Option('schema.json', '--output', '-o', help="Output path for the JSON schema.")
+):
+    ephaptic = load_ephaptic(app)
+
+    typer.secho(f"Found {len(ephaptic._exposed_functions)} functions.", fg=typer.colors.GREEN)
+
+    schema_output = {
+        "methods": {},
+        "definitions": {},
+    }
+
+    for name, func in ephaptic._exposed_functions.items():
+        typer.secho(f"  - {name}")
+
+        hints = typing.get_type_hints(func)
+        sig = inspect.signature(func)
+
+        method_schema = {
+            "args": {},
+            "return": None
+        }
+
+        for param_name in sig.parameters:
+            hint = hints.get(param_name, typing.Any)
+            adapter = TypeAdapter(hint)
+
+            method_schema["args"][param_name] = create_schema(
+                adapter,
+                schema_output["definitions"],
+            )
+
+        return_hint = hints.get("return", typing.Any)
+        if return_hint is not type(None):
+            adapter = TypeAdapter(return_hint)
+            method_schema["return"] = create_schema(
+                adapter,
+                schema_output["definitions"],
+            )
+
+        schema_output["methods"][name] = method_schema
+
+    with open(output, "w") as f:
+        json.dump(schema_output, f, indent=2)
+
+    typer.secho(f"Schema generated to `{output}`.", fg=typer.colors.GREEN, bold=True)
+
+if __name__ == "__main__":
+    app()

ephaptic/ephaptic.py

@@ -1,12 +1,14 @@
 import asyncio
 import msgpack
 import redis.asyncio as redis
+import pydantic
 
 from contextvars import ContextVar
 from .localproxy import LocalProxy
 
 from .transports import Transport
 
+import typing
 from typing import Optional, Callable, Any, List, Set, Dict
 import inspect
 
@@ -65,6 +67,9 @@ class ConnectionManager:
 
 manager = ConnectionManager()
 
+_EXPOSED_FUNCTIONS = {}
+_IDENTITY_LOADER: Optional[Callable] = None
+
 class EphapticTarget:
     def __init__(self, user_ids: list[str]):
         self.user_ids = user_ids
@@ -74,6 +79,14 @@ class EphapticTarget:
             await manager.broadcast(self.user_ids, name, list(args), dict(kwargs))
         return emitter
     
+def expose(func: Callable):
+    _EXPOSED_FUNCTIONS[func.__name__] = func
+    return func
+    
+def identity_loader(func: Callable):
+    _IDENTITY_LOADER = func
+    return func
+
 class Ephaptic:
     _exposed_functions: Dict[str, Callable] = {}
     _identity_loader: Optional[Callable] = None
@@ -91,12 +104,11 @@ class Ephaptic:
 
     @classmethod
     def from_app(cls, app, path="/_ephaptic", redis_url=None):
-        # `app` could be Flask, Quart, FastAPI, etc.
+        # `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]
 
@@ -110,6 +122,9 @@ class Ephaptic:
             case _:
                 raise TypeError(f"Unsupported app type: {module}")
             
+        cls._exposed_functions = _EXPOSED_FUNCTIONS.copy()
+        cls._identity_loader = _IDENTITY_LOADER
+
         return instance
 
             
@@ -177,11 +192,41 @@ class Ephaptic:
 
                     if func_name in self._exposed_functions:
                         target_func = self._exposed_functions[func_name]
+                        sig = inspect.signature(target_func)
+                        try:
+                            bound = sig.bind(*args, **kwargs)
+                            bound.apply_defaults()
+                        except TypeError as e:
+                            await transport.send(msgpack.dumps({"id": call_id, "error": str(e)}))
+                            continue
+
+                        hints = typing.get_type_hints(target_func)
+
+                        errors = []
+
+                        for name, val in bound.arguments.items():
+                            hint = hints.get(name)
+
+                            if hint and inspect.isclass(hint) and issubclass(hint, pydantic.BaseModel):
+                                try:
+                                    bound.arguments[name] = hint.model_validate(val)
+                                except pydantic.ValidationError as e:
+                                    errors.extend(e.errors())
+
+                        if errors:
+                            await transport.send(msgpack.dumps({
+                                "id": call_id,
+                                "error": errors,
+                            }))
+                            continue
+
                         token_transport = _active_transport_ctx.set(transport)
                         token_user = _active_user_ctx.set(current_uid)
 
                         try:
-                            result = await self._async(target_func)(*args, **kwargs)
+                            result = await self._async(target_func)(**bound.arguments)
+                            if isinstance(result, pydantic.BaseModel):
+                                result = result.model_dump()
                             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)}))

{ephaptic-0.1.3.dist-info → ephaptic-0.2.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ephaptic
-Version: 0.1.3
+Version: 0.2.1
 Summary: The Python client/server package for ephaptic.
 Author-email: uukelele <robustrobot11@gmail.com>
 License: MIT License
@@ -33,6 +33,9 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: msgpack>=1.0.0
 Requires-Dist: websockets>=12.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: typer[standard]>=0.20.0
+Requires-Dist: python-dotenv
 Provides-Extra: server
 Requires-Dist: redis; extra == "server"
 Dynamic: license-file
@@ -58,8 +61,6 @@ Dynamic: license-file
 </a>
 
 
-
-
 </div>
 
 ## What is `ephaptic`?
@@ -73,7 +74,7 @@ Dynamic: license-file
 
 Nah, just kidding. It's an RPC framework.
 
-> **ephaptic** — Call your backend straight from your frontend. No JSON. No latency. No middleware.
+> **ephaptic** — Call your backend straight from your frontend. No JSON. Low latency. Invisible middleware.
 
 ## Getting Started
 
@@ -83,7 +84,9 @@ Nah, just kidding. It's an RPC framework.
 
 - 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.**
+- Saved the best for last: it's type-safe. Don't believe me? Try it out for yourself. Simply type hint return values and parameters on the backend, and watch those very Python types transform into interfaces and types on the TypeScript frontend. Plus, you can use Pydantic - which means, for those of you who are FastAPI users, this is going to be great.
+
+What are you waiting for? **Let's go.**
 
 <details>
     <summary>Python</summary>
@@ -125,13 +128,16 @@ Now, how do you expose your function to the frontend?
 
 ```python
 @ephaptic.expose
-async def add(num1, num2):
+async def add(num1: int, num2: int) -> int:
     return num1 + num2
 ```
 
+> [!TIP]
+> If you're experiencing circular imports, feel free to instead import and use the `expose` function from the library instead of the instance. Please note that if you do this, you must define all exposed functions *before* creating the ephaptic instance - this is mainly for people importing RPC functions from another file. The same thing can be done with the global `identity_loader` decorator.
+
 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.
+But what if your code throws an error? No sweat, it just throws up on the frontend, with the error name.
 
 And, want to say something to the frontend?
 
@@ -139,6 +145,13 @@ And, want to say something to the frontend?
 await ephaptic.to(user1, user2).notification("Hello, world!", priority="high")
 ```
 
+To create a schema of your RPC endpoints:
+
+```
+$ ephaptic src.app:app -o schema.json
+```
+
+Pydantic is entirely supported. It's validated for arguments, it's auto-serialized when you return a pydantic model, and your models receive type definitions in the schema.
 
 </details>
 
@@ -148,7 +161,7 @@ await ephaptic.to(user1, user2).notification("Hello, world!", priority="high")
 #### To use with a framework / Vite:
 
 ```
-npm install @ephaptic/client
+$ npm install @ephaptic/client
 ```
 
 Then:
@@ -175,13 +188,28 @@ You can even send auth objects to the server for identity loading.
 const client = connect({ url: '...', auth: { token: window.localStorage.getItem('jwtToken') } })
 ```
 
+And you can load types, too.
+
+```
+$ npm i --save-dev @ephaptic/type-gen
+$ npx @ephaptic/type-gen ./schema.json -o schema.d.ts
+```
+
+```typescript
+import { connect } from "@ephaptic/client";
+import { type EphapticService } from './schema';
+
+const client = connect(...) as unknown as EphapticService;
+```
+
+
 #### 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();
+const client = connect(...);
 </script>
 ```
 

{ephaptic-0.1.3.dist-info → ephaptic-0.2.1.dist-info}/RECORD

@@ -1,16 +1,19 @@
-ephaptic/__init__.py,sha256=1_7Rwb0WCZS2rbOOEVIctFGqF0Kt81JCWR7Mm3Ry4F4,92
-ephaptic/ephaptic.py,sha256=m8gKQ_sjDVkap1EpbimuMvFa74eiRRpWkJd43yph8_c,7355
+ephaptic/__init__.py,sha256=3GmVqhbye3snH7KfnyqIt8t_w6ULnWOvDw07eB13iDA,126
+ephaptic/ephaptic.py,sha256=K9cOUk8guI6IesBACkdUxebI2UXpN-0yJfrhjHUC3iI,9034
 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/cli/__init__.py,sha256=p_mYumuQLr3HZa-6I4QKut6khZv3WQjEX-B-aa4cdEE,44
+ephaptic/cli/__main__.py,sha256=RNEL4c_MkEKV7kY9pswC1ihNToiaVb06t1aZ4dCfk9s,3389
 ephaptic/client/__init__.py,sha256=NeaPIzTFeozP54wlDYHIg_adHP3Z3LWVujsRUlpn4_U,35
 ephaptic/client/client.py,sha256=YYAlzA40xBvWsiDu0Gsd1EBJaqivLR-bSszepWdNODs,4181
 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.3.dist-info/licenses/LICENSE,sha256=kMpJjLKMj6zsAhf4uHApO4q0r31Ye1VyfBOl9cFW13M,1065
-ephaptic-0.1.3.dist-info/METADATA,sha256=Qs74Bl4B09bcz1d3UMlCoEgFSd3aDnU4X7uthC25qLg,6263
-ephaptic-0.1.3.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-ephaptic-0.1.3.dist-info/top_level.txt,sha256=nNhdhcz2o_IuwZ9I2uWQuLZrRmSW0dQVU3qwGrb35Io,9
-ephaptic-0.1.3.dist-info/RECORD,,
+ephaptic-0.2.1.dist-info/licenses/LICENSE,sha256=kMpJjLKMj6zsAhf4uHApO4q0r31Ye1VyfBOl9cFW13M,1065
+ephaptic-0.2.1.dist-info/METADATA,sha256=9-6m-C21Y01fry6UHDGoQ-2LtUqYpI_rOxJZv_fzaGM,7716
+ephaptic-0.2.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+ephaptic-0.2.1.dist-info/entry_points.txt,sha256=lis9vIDIrMVJM43r9ooFkb07KhrX4946duvYru3VfT4,46
+ephaptic-0.2.1.dist-info/top_level.txt,sha256=nNhdhcz2o_IuwZ9I2uWQuLZrRmSW0dQVU3qwGrb35Io,9
+ephaptic-0.2.1.dist-info/RECORD,,

ephaptic-0.2.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+ephaptic = ephaptic.cli:app