zndraw-socketio 0.1.0__py3-none-any.whl → 0.1.1__py3-none-any.whl

zndraw_socketio/__init__.py

@@ -1,13 +1,35 @@
 from .wrapper import (
     AsyncClientWrapper as AsyncClientWrapper,
+)
+from .wrapper import (
     AsyncServerWrapper as AsyncServerWrapper,
+)
+from .wrapper import (
     AsyncSimpleClientWrapper as AsyncSimpleClientWrapper,
-    Depends as Depends,
+)
+from .wrapper import (
     EventContext as EventContext,
+)
+from .wrapper import (
     SimpleClientWrapper as SimpleClientWrapper,
+)
+from .wrapper import (
     SioRequest as SioRequest,
+)
+from .wrapper import (
     SyncClientWrapper as SyncClientWrapper,
+)
+from .wrapper import (
     SyncServerWrapper as SyncServerWrapper,
+)
+from .wrapper import (
     get_event_name as get_event_name,
+)
+from .wrapper import (
     wrap as wrap,
 )
+
+try:
+    from fastapi import Depends as Depends
+except ImportError:
+    from zndraw_socketio.params import Depends as Depends

zndraw_socketio/wrapper.py

@@ -50,11 +50,6 @@ try:
 except ImportError:
     from zndraw_socketio.params import _DependsBase as _DependsClass
 
-try:
-    from fastapi import Depends
-except ImportError:
-    from zndraw_socketio.params import Depends
-
 try:
     from fastapi import Request
 except ImportError:

zndraw_socketio-0.1.1.dist-info/METADATA

@@ -0,0 +1,114 @@
+Metadata-Version: 2.4
+Name: zndraw-socketio
+Version: 0.1.1
+Summary: Typed wrapper for python-socketio with Pydantic validation and dependency injection.
+Project-URL: homepage, https://github.com/pythonFZ/zndraw-socketio
+Project-URL: issues, https://github.com/pythonFZ/zndraw-socketio/issues
+Author-email: Atomie CHEN <atomic_cwh@163.com>, Fabian Zills <fabian.zills@web.de>
+License-File: LICENSE
+Keywords: pydantic,socketio,typed,wrapper,zndraw
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Requires-Dist: pydantic>=2.10.6
+Requires-Dist: python-socketio>=5.12.1
+Requires-Dist: typing-extensions>=4.13.0
+Provides-Extra: asyncio-client
+Requires-Dist: python-socketio[asyncio-client]>=5.12.1; extra == 'asyncio-client'
+Provides-Extra: client
+Requires-Dist: python-socketio[client]>=5.12.1; extra == 'client'
+Description-Content-Type: text/markdown
+
+# ZnDraw SocketIO
+This package provides an opinionated typed interface to the python-socketio library using pydantic models.
+
+```python
+from zndraw_socketio import Wrapper
+from pydantic import BaseModel
+import socketio
+
+sio = Wrapper(socketio.AsyncClient()) # can be server as well
+```
+
+## Emit Pattern
+```python
+class Ping(BaseModel):
+    message: str
+
+# kwargs are passed to socketio's emit method
+# emits {"message": "Hello, World!"} to "ping"
+await sio.emit(Ping(message="Hello, World!"), **kwargs)
+# emits {"message": "Hello, World!"} to "my-ping"
+await sio.emit("my-ping", Ping(message="Hello, World!"), **kwargs)
+# standard sio behaviour
+await sio.emit("event", {"payload": ...})
+```
+
+## Call / RPC Pattern
+```python
+class Pong(BaseModel):
+    reply: str
+
+# emits {"message": "Hello, World!"} to "ping" and receives Pong(reply=...) in return
+response = await sio.call(Ping(message="Hello, World!"), response_model=Pong)
+assert isinstance(response, Pong)
+# emits {"message": "Hello, World!"} to "my-ping" and receives Pong(reply=...) in return
+response = await sio.call("my-ping", Ping(message="Hello, World!"), response_model=Pong)
+assert isinstance(response, Pong)
+# standard sio behaviour
+response = await sio.call("event", {"payload": ...})
+# standard response obj, typically dict
+```
+
+## Event Names
+By default, the event name is the class name in snake_case. You can customize it by setting the `event_name` attribute.
+
+```python
+class CustomEvent(Event):
+    ...
+
+assert CustomEvent.event_name == "custom_event"
+```
+
+you can override it like this:
+
+```python
+from typing import ClassVar
+
+class CustomEvent(Event):
+    event_name: ClassVar[str] = "my_custom_event"
+```
+
+## Union Return Types
+You might want to return `Response|ErrorResponse` from an event handler.
+
+> [!NOTE]
+> If your responses share fields, it is recommended to add a discriminator field to avoid ambiguity.
+
+
+```python
+class ProblemDetail(BaseModel):
+    """RFC 9457 Problem Details.
+
+    https://www.rfc-editor.org/rfc/rfc9457.html
+    """
+    kind: Literal["error"] = "error" # The discriminator (nod needed in this example)
+    type: str = "about:blank"
+    title: str
+    status: int
+    detail: str | None = None
+    instance: str | None = None
+
+class Response(BaseModel):
+    kind: Literal["response"] = "response" # The discriminator (not needed in this example)
+    data: str
+
+class ServerRequest(BaseModel):
+    query: str
+
+
+response_model = ... # do we need typing Annotated here?
+
+response = await sio.call(ServerRequest(query="..."), response_model=response_model)
+```

zndraw_socketio-0.1.1.dist-info/RECORD

@@ -0,0 +1,8 @@
+zndraw_socketio/__init__.py,sha256=KER2gbnWyWq_OfjcZ7EEWJwFxLKgCmPp4e2IPL2EDtM,783
+zndraw_socketio/params.py,sha256=kQvr0rLz5-ug0bGKlvhxPHfLiDIoMvUVWEGJotpPCjM,1338
+zndraw_socketio/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+zndraw_socketio/wrapper.py,sha256=sfhbFv2tzu47xV8T5rSVHLQFSqtAaa39-uk9q6MgQ9E,50662
+zndraw_socketio-0.1.1.dist-info/METADATA,sha256=42ZNuCbjRUpDR6wW2IoIgdhrZycM7gsReiEWC5IkY0o,3533
+zndraw_socketio-0.1.1.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+zndraw_socketio-0.1.1.dist-info/licenses/LICENSE,sha256=Ry21YmIoh82aAQa8oBStENUpHqywNGoW6f5Q8ahU5HE,1085
+zndraw_socketio-0.1.1.dist-info/RECORD,,

{zndraw_socketio-0.1.0.dist-info → zndraw_socketio-0.1.1.dist-info}/licenses/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 Atomie CHEN
+Copyright (c) 2026 zndraw-socketio contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

zndraw_socketio-0.1.0.dist-info/METADATA

@@ -1,212 +0,0 @@
-Metadata-Version: 2.4
-Name: zndraw-socketio
-Version: 0.1.0
-Summary: Typed wrapper for python-socketio with Pydantic validation and dependency injection.
-Project-URL: homepage, https://github.com/pythonFZ/zndraw-socketio
-Project-URL: issues, https://github.com/pythonFZ/zndraw-socketio/issues
-Author-email: Atomie CHEN <atomic_cwh@163.com>, Fabian Zills <fabian.zills@web.de>
-License-File: LICENSE
-Keywords: pydantic,socketio,typed,wrapper,zndraw
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Operating System :: OS Independent
-Classifier: Programming Language :: Python :: 3
-Requires-Python: >=3.10
-Requires-Dist: pydantic>=2.10.6
-Requires-Dist: python-socketio>=5.12.1
-Requires-Dist: typing-extensions>=4.13.0
-Provides-Extra: asyncio-client
-Requires-Dist: python-socketio[asyncio-client]>=5.12.1; extra == 'asyncio-client'
-Provides-Extra: client
-Requires-Dist: python-socketio[client]>=5.12.1; extra == 'client'
-Description-Content-Type: text/markdown
-
-# zndraw-socketio
-
-Typed wrapper for [python-socketio](https://github.com/miguelgrinberg/python-socketio) with Pydantic validation and dependency injection.
-
-
-## Installation
-
-```sh
-pip install zndraw-socketio
-```
-
-Optional extras for client transports:
-
-```sh
-pip install zndraw-socketio[client]
-pip install zndraw-socketio[asyncio-client]
-```
-
-
-## Usage
-
-### Wrap any socketio instance
-
-```python
-import socketio
-from pydantic import BaseModel
-from zndraw_socketio import wrap
-
-class Ping(BaseModel):
-    message: str
-
-class Pong(BaseModel):
-    reply: str
-
-# Wrap any existing socketio instance
-tsio = wrap(socketio.AsyncClient())
-
-# Emit with automatic event name derivation (Ping -> "ping")
-await tsio.emit(Ping(message="Hello, World!"))
-
-# Emit with explicit event name
-await tsio.emit("my-ping", Ping(message="Hello, World!"))
-
-# Call with typed response
-response = await tsio.call(Ping(message="Hello"), response_model=Pong)
-# response is typed as Pong
-```
-
-### Handler registration with validation
-
-```python
-# Event name derived from model class (Ping -> "ping")
-@tsio.on(Ping)
-async def handle_ping(data: Ping) -> Pong:
-    return Pong(reply=data.message)
-
-# Or use function name as event name
-@tsio.event
-async def ping(data: Ping) -> Pong:
-    return Pong(reply=data.message)
-```
-
-### Union response types
-
-```python
-from typing import Annotated, Literal
-from pydantic import BaseModel, Discriminator
-
-class Success(BaseModel):
-    kind: Literal["success"] = "success"
-    data: str
-
-class Error(BaseModel):
-    kind: Literal["error"] = "error"
-    message: str
-
-# Simple union
-response = await tsio.call(request, response_model=Success | Error)
-
-# Discriminated union
-ResponseType = Annotated[Success | Error, Discriminator("kind")]
-response = await tsio.call(request, response_model=ResponseType)
-```
-
-### Custom event names
-
-```python
-from typing import ClassVar
-
-class CustomEvent(BaseModel):
-    event_name: ClassVar[str] = "my_custom_event"
-    data: str
-
-# Uses "my_custom_event" instead of "custom_event"
-await tsio.emit(CustomEvent(data="hello"))
-```
-
-### Exception handlers
-
-```python
-from zndraw_socketio import wrap, EventContext
-
-tsio = wrap(socketio.AsyncServer(async_mode="asgi"))
-
-@tsio.exception_handler(ValueError)
-async def handle_value_error(ctx: EventContext, exc: ValueError):
-    return {"error": "value_error", "message": str(exc)}
-
-# Namespace-specific
-@tsio.exception_handler(ValueError, namespace="/chat")
-async def handle_chat_error(ctx: EventContext, exc: ValueError):
-    return {"error": "chat_error", "message": str(exc)}
-```
-
-### Dependency injection
-
-```python
-from typing import Annotated
-from fastapi import Depends
-from zndraw_socketio import wrap
-
-async def get_redis():
-    return my_redis_pool
-
-RedisDep = Annotated[AsyncRedis, Depends(get_redis)]
-
-tsio = wrap(socketio.AsyncServer(async_mode="asgi"))
-
-@tsio.on(RoomLeave)
-async def room_leave(sid: str, data: RoomLeave, redis: RedisDep) -> RoomLeaveResponse:
-    await redis.delete(f"presence:{data.room_id}:{sid}")
-    return RoomLeaveResponse(status="ok")
-```
-
-When FastAPI is not installed, import `Depends` from `zndraw_socketio`:
-
-```python
-from zndraw_socketio import Depends
-```
-
-### FastAPI integration
-
-```python
-import socketio
-from typing import Annotated
-from fastapi import FastAPI, Depends
-from zndraw_socketio import wrap, AsyncServerWrapper
-
-app = FastAPI()
-tsio = wrap(socketio.AsyncServer(async_mode="asgi"))
-
-SioServer = Annotated[AsyncServerWrapper, Depends(tsio)]
-
-@app.post("/notify")
-async def notify(server: SioServer):
-    await server.emit("notification", {"msg": "hello"})
-    return {"status": "sent"}
-
-combined_app = socketio.ASGIApp(tsio, app)
-```
-
-### SimpleClient support
-
-```python
-tsio = wrap(socketio.SimpleClient())
-tsio.connect("http://localhost:5000")
-
-tsio.emit(Ping(message="Hello"))
-response = tsio.call(Ping(message="Hello"), response_model=Pong)
-event_name, data = tsio.receive(response_model=Pong)
-tsio.disconnect()
-```
-
-## Supported socketio types
-
-`wrap()` auto-detects the socketio instance type:
-
-| socketio type | Wrapper class |
-|---|---|
-| `AsyncClient` | `AsyncClientWrapper` |
-| `AsyncServer` | `AsyncServerWrapper` |
-| `Client` | `SyncClientWrapper` |
-| `Server` | `SyncServerWrapper` |
-| `SimpleClient` | `SimpleClientWrapper` |
-| `AsyncSimpleClient` | `AsyncSimpleClientWrapper` |
-
-
-## License
-
-MIT License

zndraw_socketio-0.1.0.dist-info/RECORD

@@ -1,8 +0,0 @@
-zndraw_socketio/__init__.py,sha256=eRrJNRHjGEBsBFUc1gOBE4p9j9-g-K5o4Ao5whz6OLU,455
-zndraw_socketio/params.py,sha256=kQvr0rLz5-ug0bGKlvhxPHfLiDIoMvUVWEGJotpPCjM,1338
-zndraw_socketio/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-zndraw_socketio/wrapper.py,sha256=Lsjopx8X2ikCfg4NIXAmBvRmhcgcBqSVNmao8lI4QXM,50767
-zndraw_socketio-0.1.0.dist-info/METADATA,sha256=r0uoZMxmNAylGJOHDm4u8w_8qr-9gEJgVbMKifpX5_Y,5338
-zndraw_socketio-0.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-zndraw_socketio-0.1.0.dist-info/licenses/LICENSE,sha256=SpSDGxJCTumVhMVOPkFg_x6q01lPcU6KsYh_7DhwJg0,1068
-zndraw_socketio-0.1.0.dist-info/RECORD,,