ephaptic 0.2.2__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

@@ -1,4 +1,4 @@
-import sys, os, json, inspect, importlib, typing, typer
+import sys, os, json, inspect, importlib, typing, typer, subprocess as sp
 
 from pathlib import Path
 from pydantic import TypeAdapter
@@ -16,8 +16,8 @@ def load_ephaptic(import_name: str) -> Ephaptic:
     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
+        typer.secho(f"Warning: Import name did not specify client name. Defaulting to `client`.", fg=typer.colors.YELLOW)
+        import_name += ":client" # default: expect client to be named `client` inside the file
 
     module_name, var_name = import_name.split(":", 1)
 
@@ -35,7 +35,7 @@ def load_ephaptic(import_name: str) -> Ephaptic:
         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)
+        typer.secho(f"Error: '{var_name}' is not an Ephaptic client. It is type: {type(instance)}", fg=typer.colors.RED)
         raise typer.Exit(1)
     
     return instance
@@ -53,17 +53,37 @@ def create_schema(adapter: TypeAdapter, definitions: dict) -> dict:
     
     return schema
 
+def run_subprocess():
+    cmd = [sys.executable]
+    cmd += [arg for arg in sys.argv if arg not in {'--watch', '-w'}]
+    sp.run(cmd)
+
 @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.")
+    client: str = typer.Argument('client:client', help="The import string for the Ephaptic client."),
+    output: Path = typer.Option('schema.json', '--output', '-o', help="Output path for the JSON schema."),
+    watch: bool = typer.Option(False, '--watch', '-w', help="Watch for changes in `.py` files and regenerate schema file automatically."),
 ):
-    ephaptic = load_ephaptic(app)
+    if watch:
+        import watchfiles
+        
+        cwd = os.getcwd()
+        typer.secho(f"Watching for changes ({cwd})...",  fg=typer.colors.GREEN)
+
+        run_subprocess()
+
+        for changes in watchfiles.watch(cwd):
+            if any(f.endswith('.py') for _, f in changes):
+                typer.secho("Detected changes, regenerating...")
+                run_subprocess()
+
+    ephaptic = load_ephaptic(client)
 
     typer.secho(f"Found {len(ephaptic._exposed_functions)} functions.", fg=typer.colors.GREEN)
 
     schema_output = {
         "methods": {},
+        "events": {},
         "definitions": {},
     }
 
@@ -97,8 +117,24 @@ 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():
+        old = output.read_text()
+        if old == new:
+            return
+
     with open(output, "w") as f:
-        json.dump(schema_output, f, indent=2)
+        f.write(new)
 
     typer.secho(f"Schema generated to `{output}`.", fg=typer.colors.GREEN, bold=True)
 

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.2.dist-info → ephaptic-0.2.4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ephaptic
-Version: 0.2.2
+Version: 0.2.4
 Summary: The Python client/server package for ephaptic.
 Author-email: uukelele <robustrobot11@gmail.com>
 License: MIT License
@@ -36,6 +36,7 @@ Requires-Dist: websockets>=12.0
 Requires-Dist: pydantic>=2.0
 Requires-Dist: typer[standard]>=0.20.0
 Requires-Dist: python-dotenv
+Requires-Dist: watchfiles
 Provides-Extra: server
 Requires-Dist: redis; extra == "server"
 Dynamic: license-file
@@ -91,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
@@ -132,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.
 
@@ -147,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
@@ -191,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
@@ -202,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">
@@ -212,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.2.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=RNEL4c_MkEKV7kY9pswC1ihNToiaVb06t1aZ4dCfk9s,3389
+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.2.dist-info/licenses/LICENSE,sha256=kMpJjLKMj6zsAhf4uHApO4q0r31Ye1VyfBOl9cFW13M,1065
-ephaptic-0.2.2.dist-info/METADATA,sha256=FvhGA1GURxKF9pygzB9SQ7uuKaDCYq3mxQ6UfLMpZIg,7757
-ephaptic-0.2.2.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-ephaptic-0.2.2.dist-info/entry_points.txt,sha256=lis9vIDIrMVJM43r9ooFkb07KhrX4946duvYru3VfT4,46
-ephaptic-0.2.2.dist-info/top_level.txt,sha256=nNhdhcz2o_IuwZ9I2uWQuLZrRmSW0dQVU3qwGrb35Io,9
-ephaptic-0.2.2.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,,