ephaptic 0.2.3__py3-none-any.whl → 0.2.4__py3-none-any.whl

ephaptic/__init__.py

@@ -3,6 +3,7 @@ from .ephaptic import (
     active_user,
     expose,
     identity_loader,
+    event,
 )
 
 from .client import (

ephaptic/cli/__main__.py

@@ -83,6 +83,7 @@ def generate(
 
     schema_output = {
         "methods": {},
+        "events": {},
         "definitions": {},
     }
 
@@ -116,6 +117,15 @@ def generate(
 
         schema_output["methods"][name] = method_schema
 
+    for name, model in ephaptic._exposed_events.items():
+        typer.secho(f"  - {name}")
+        adapter = TypeAdapter(model)
+
+        schema_output["events"][name] = create_schema(
+            adapter,
+            schema_output["definitions"],
+        )
+
     new = json.dumps(schema_output, indent=2)
 
     if output.exists():

ephaptic/ephaptic.py

@@ -1,4 +1,5 @@
 import asyncio
+from warnings import deprecated
 import msgpack
 import redis.asyncio as redis
 import pydantic
@@ -71,12 +72,23 @@ class ConnectionManager:
 manager = ConnectionManager()
 
 _EXPOSED_FUNCTIONS = {}
+_EXPOSED_EVENTS = {}
 _IDENTITY_LOADER: Optional[Callable] = None
 
 class EphapticTarget:
     def __init__(self, user_ids: list[str]):
         self.user_ids = user_ids
 
+    async def emit(self, event_instance: pydantic.BaseModel):
+        event_name = event_instance.__class__.__name__
+        payload = event_instance.model_dump(mode='json')
+        await manager.broadcast(
+            self.user_ids,
+            event_name,
+            args=[],
+            kwargs=payload,
+        )
+
     def __getattr__(self, name: str):
         async def emitter(*args, **kwargs):
             await manager.broadcast(self.user_ids, name, list(args), dict(kwargs))
@@ -90,8 +102,13 @@ def identity_loader(func: Callable):
     _IDENTITY_LOADER = func
     return func
 
+def event(model: typing.Type[pydantic.BaseModel]):
+    _EXPOSED_EVENTS[model.__name__] = model
+    return model
+
 class Ephaptic:
     _exposed_functions: Dict[str, Callable] = {}
+    _exposed_events: Dict[str, typing.Type[pydantic.BaseModel]]
     _identity_loader: Optional[Callable] = None
 
     def _async(self, func: Callable):
@@ -125,8 +142,9 @@ class Ephaptic:
             case _:
                 raise TypeError(f"Unsupported app type: {module}")
             
-        cls._exposed_functions = _EXPOSED_FUNCTIONS.copy()
-        cls._identity_loader = _IDENTITY_LOADER
+        instance._exposed_functions = _EXPOSED_FUNCTIONS.copy()
+        instance._exposed_events = _EXPOSED_EVENTS.copy()
+        instance._identity_loader = _IDENTITY_LOADER
 
         return instance
 
@@ -135,6 +153,10 @@ class Ephaptic:
         self._exposed_functions[func.__name__] = func
         return func
     
+    def event(self, model: typing.Type[pydantic.BaseModel]):
+        self._exposed_events[model.__name__] = model
+        return model
+    
     def identity_loader(self, func: Callable):
         self._identity_loader = func
         return func
@@ -147,6 +169,7 @@ class Ephaptic:
         return EphapticTarget(targets)
     
     def __getattr__(self, name: str):
+        @deprecated("Use `emit` and the new (typed) event system instead.")
         async def emitter(*args, **kwargs):
             transport: Transport = _active_transport_ctx.get()
             if not transport:
@@ -163,6 +186,24 @@ class Ephaptic:
         
         return emitter
     
+    async def emit(self, event_instance: pydantic.BaseModel):
+        event_name = event_instance.__class__.__name__
+        payload = event_instance.model_dump(mode='json')
+        transport: Transport = _active_transport_ctx.get()
+        if not transport:
+            raise RuntimeError(
+                f".emit({event_name}) called outside RPC context."
+                f"Use .to(...).emit({event_name}) to broadcast from background tasks, to specific user(s)."
+            )
+        
+        # NOTE: There is slight duplication here and in the EphapticTarget. Perhaps make these functions internally route to EphapticTargets but pass the transport to use?
+        
+        await transport.send(msgpack.dumps({
+            'type': 'event',
+            'name': event_name,
+            'payload': {'args': [], 'kwargs': payload}
+        }))
+    
     async def handle_transport(self, transport: Transport):
         current_uid = None
         try:

{ephaptic-0.2.3.dist-info → ephaptic-0.2.4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ephaptic
-Version: 0.2.3
+Version: 0.2.4
 Summary: The Python client/server package for ephaptic.
 Author-email: uukelele <robustrobot11@gmail.com>
 License: MIT License
@@ -92,16 +92,16 @@ What are you waiting for? **Let's go.**
 <details>
     <summary>Python</summary>
     
-#### Client:
+<h4>Client:</h4>
 
 ```
-pip install ephaptic
+$ pip install ephaptic
 ```
 
-#### Server:
+<h4>Server:</h4>
 
 ```
-pip install ephaptic[server]
+$ pip install ephaptic[server]
 ```
 
 ```python
@@ -133,7 +133,7 @@ async def add(num1: int, num2: int) -> int:
     return num1 + num2
 ```
 
-###### If you're trying to expose functions statelessly, e.g. in a different file, 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 - easily done by simply placing your import line above the ephaptic constructor. The same thing can be done with the global `identity_loader` decorator.
+<h5>If you're trying to expose functions statelessly, e.g. in a different file, feel free to instead import and use the <code>expose</code> function from the library instead of the instance. Please note that if you do this, you must define all exposed functions <i>before</i> creating the ephaptic instance - easily done by simply placing your import line above the ephaptic constructor. The same thing can be done with the global <code>identity_loader</code> decorator.</h5>
 
 Yep, it's really that simple.
 
@@ -148,17 +148,32 @@ 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
+$ ephaptic src.app:app -o schema.json # --watch to run in background and auto-reload on file change.
 ```
 
 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.
 
+To receive authentication objects and handle them:
+
+```python
+from ephaptic import identity_loader
+
+@identity_loader
+async def load_identity(auth): # You can use synchronous functions here too.
+    jwt = auth.get("token")
+    if not jwt: return None # unauthorized
+    ... # app logic to retrieve user ID
+    return user_id
+```
+
+From here, you can use <code>ephaptic.active_user</code> within any exposed function, and it will give you the current active user ID / whatever else your identity loading function returns. (This is also how <code>ephaptic.to</code> works.)
+
 </details>
 
 <details>
-    <summary>JavaScript/TypeScript — Browser (Svelt, React, Angular, Vite, etc.)</summary>
+    <summary>JavaScript/TypeScript — Browser (Svelte, React, Angular, Vite, etc.)</summary>
 
-#### To use with a framework / Vite:
+<h4>To use with a framework / Vite:</h4>
 
 ```
 $ npm install @ephaptic/client
@@ -192,7 +207,7 @@ And you can load types, too.
 
 ```
 $ npm i --save-dev @ephaptic/type-gen
-$ npx @ephaptic/type-gen ./schema.json -o schema.d.ts
+$ npx @ephaptic/type-gen ./schema.json -o schema.d.ts # --watch to auto-reload upon changes
 ```
 
 ```typescript
@@ -203,7 +218,7 @@ const client = connect(...) as unknown as EphapticService;
 ```
 
 
-#### Or, to use in your browser:
+<h4>Or, to use in your browser:</h4>
 
 ```html
 <script type="module">
@@ -213,10 +228,10 @@ const client = connect(...);
 </script>
 ```
 
-<!-- TODO: Add extended documentation -->
-
 </details>
 
+See more in the [docs](https://ephaptic.github.io/ephaptic/tutorial).
+
 ## [License](https://github.com/ephaptic/ephaptic/blob/main/LICENSE)
 
 ---

{ephaptic-0.2.3.dist-info → ephaptic-0.2.4.dist-info}/RECORD

@@ -1,19 +1,19 @@
-ephaptic/__init__.py,sha256=3GmVqhbye3snH7KfnyqIt8t_w6ULnWOvDw07eB13iDA,126
-ephaptic/ephaptic.py,sha256=9PKqiUKWl5MWlBvqsVbpsEfBmJmZJFes0RbbeqFkX4I,10224
+ephaptic/__init__.py,sha256=QIEfepOHMtM6Lrxg4AwZ28gEj0D5TY2UP8MGlrAb-DI,137
+ephaptic/ephaptic.py,sha256=UtT3_KD5SQcVFZxW5I3rAuDkXaRkMhIYQDl8d1njwDQ,11904
 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=fbfEGUnufc7vO65ZHnCV7YSshlHyif1c3kzR7vSp9GM,4218
+ephaptic/cli/__main__.py,sha256=79FQgQtsq09pWV-G-98oqGx7mYuVLvw42kUbNzEJvvA,4499
 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.2.3.dist-info/licenses/LICENSE,sha256=kMpJjLKMj6zsAhf4uHApO4q0r31Ye1VyfBOl9cFW13M,1065
-ephaptic-0.2.3.dist-info/METADATA,sha256=ZokQJXZp3r4icuY3F8IRpqALNpEZXrCOLkgv8l2lHvk,7783
-ephaptic-0.2.3.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-ephaptic-0.2.3.dist-info/entry_points.txt,sha256=lis9vIDIrMVJM43r9ooFkb07KhrX4946duvYru3VfT4,46
-ephaptic-0.2.3.dist-info/top_level.txt,sha256=nNhdhcz2o_IuwZ9I2uWQuLZrRmSW0dQVU3qwGrb35Io,9
-ephaptic-0.2.3.dist-info/RECORD,,
+ephaptic-0.2.4.dist-info/licenses/LICENSE,sha256=kMpJjLKMj6zsAhf4uHApO4q0r31Ye1VyfBOl9cFW13M,1065
+ephaptic-0.2.4.dist-info/METADATA,sha256=x3-a9_RDMcsnYPrQWYW0HaX3YwwZcEFuoqryONFYIUk,8533
+ephaptic-0.2.4.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+ephaptic-0.2.4.dist-info/entry_points.txt,sha256=lis9vIDIrMVJM43r9ooFkb07KhrX4946duvYru3VfT4,46
+ephaptic-0.2.4.dist-info/top_level.txt,sha256=nNhdhcz2o_IuwZ9I2uWQuLZrRmSW0dQVU3qwGrb35Io,9
+ephaptic-0.2.4.dist-info/RECORD,,