pydantic-socketio 0.1.0__py3-none-any.whl

pydantic_socketio/__init__.py

@@ -0,0 +1,16 @@
+# first import everything from socketio
+from socketio import *  # type: ignore # noqa: F403
+
+from .pydantic_socketio import (
+    BaseClient as BaseClient,
+    Client as Client,
+    AsyncClient as AsyncClient,
+    BaseServer as BaseServer,
+    Server as Server,
+    AsyncServer as AsyncServer,
+    monkey_patch as monkey_patch,
+)
+
+from .fastapi_socketio import (
+    FastAPISocketIO as FastAPISocketIO,
+)

pydantic_socketio/fastapi_socketio.py

@@ -0,0 +1,40 @@
+from typing import TYPE_CHECKING, Optional
+
+if TYPE_CHECKING:
+    from fastapi import FastAPI
+
+from . import AsyncServer, ASGIApp
+
+
+class FastAPISocketIO(AsyncServer):
+    """
+    Pydantic SocketIO server for FastAPI. This class is a subclass of AsyncServer
+    and is used to create a SocketIO server that can be mounted on a FastAPI app.
+    It also adds `sio` to the FastAPI app state.
+    """
+
+    def __init__(
+        self,
+        app: Optional["FastAPI"] = None,
+        socketio_path: str = "socket.io",
+        **kwargs,
+    ) -> None:
+        # disable socketio CORS handling and let fastapi CORS handle it
+        super().__init__(cors_allowed_origins=[], async_mode="asgi", **kwargs)
+        self.socketio_path = socketio_path
+        if app:
+            self.integrate(app)
+
+    def integrate(self, app: "FastAPI"):
+        """Integrate the FastAPISocketIO server with a FastAPI app."""
+        try:
+            from fastapi import FastAPI
+        except ImportError:
+            raise ImportError(
+                "FastAPI is not installed. Please install FastAPI to use FastAPISocketIO."
+            )
+        assert isinstance(app, FastAPI), "app must be a FastAPI instance"
+        self.sio_app = ASGIApp(socketio_server=self, socketio_path=self.socketio_path)
+        app.mount("/" + self.socketio_path, self.sio_app)
+        app.state.sio = self
+        self.fastapi_app = app

pydantic_socketio/pydantic_socketio.py

@@ -0,0 +1,174 @@
+import functools
+import inspect
+import logging
+from typing import Any, Callable, Optional, Union
+
+from pydantic import validate_call, ValidationError
+from pydantic_core import to_jsonable_python
+from socketio import (
+    AsyncServer as OldAsyncServer,
+    Server as OldServer,
+    Client as OldClient,
+    AsyncClient as OldAsyncClient,
+)
+from socketio.base_server import BaseServer as OldBaseServer
+from socketio.base_client import BaseClient as OldBaseClient
+
+
+# Save the original functions
+_old_server_on = OldBaseServer.on
+_old_server_emit = OldServer.emit
+_old_server_emit_async = OldAsyncServer.emit
+_old_client_on = OldBaseClient.on
+_old_client_emit = OldClient.emit
+_old_client_emit_async = OldAsyncClient.emit
+
+
+module_logger = logging.getLogger(__name__)
+module_logger.addHandler(logging.NullHandler())
+
+
+def _wrapper(
+    handler: Callable,
+    old_on: Callable,
+    self: Union[OldBaseClient, OldBaseServer],
+    event: str,
+    *args,
+    **kwargs,
+):
+    """Wrap the handler to validate the input using pydantic"""
+    validated_handler = validate_call(handler)
+    if event in ["connect", "disconnect"]:
+        # For connect and disconnect events, convert ValidationError
+        # to TypeError, so that socketio can handle it properly
+        if inspect.iscoroutinefunction(validated_handler):
+
+            @functools.wraps(validated_handler)
+            async def wrapped_handler(*args, **kwargs):  # type: ignore
+                try:
+                    return await validated_handler(*args, **kwargs)
+                except ValidationError as e:
+                    raise TypeError from e
+        else:
+
+            @functools.wraps(validated_handler)
+            def wrapped_handler(*args, **kwargs):
+                try:
+                    return validated_handler(*args, **kwargs)
+                except ValidationError as e:
+                    raise TypeError from e
+    else:
+        wrapped_handler = validated_handler  # type: ignore
+
+    # Register the wrapped handler
+    old_on(self, event, wrapped_handler, *args, **kwargs)
+    return wrapped_handler
+
+
+class BaseServer(OldBaseServer):
+    """BaseServer with pydantic validation."""
+
+    def on(
+        self: OldBaseServer,
+        event: str,
+        handler: Optional[Callable] = None,
+        *args,
+        **kwargs,
+    ) -> Callable:
+        if handler is None:
+            # invoked as a decorator
+            return functools.partial(
+                _wrapper,
+                old_on=_old_server_on,
+                self=self,
+                event=event,
+                *args,
+                **kwargs,
+            )
+        else:
+            # not invoked as a decorator, but as a function
+            return _wrapper(handler, _old_server_on, self, event, *args, **kwargs)
+
+
+class Server(BaseServer, OldServer):
+    """Server with pydantic validation and data conversion."""
+
+    def emit(
+        self: OldServer,
+        event: str,
+        data: Any = None,
+        to: Optional[str] = None,
+        *args,
+        **kwargs,
+    ):
+        return _old_server_emit(
+            self, event=event, data=to_jsonable_python(data), to=to, *args, **kwargs
+        )
+
+
+class AsyncServer(BaseServer, OldAsyncServer):
+    """AsyncServer with pydantic validation and data conversion."""
+
+    async def emit(
+        self: OldAsyncServer,
+        event: str,
+        data: Any = None,
+        to: Optional[str] = None,
+        *args,
+        **kwargs,
+    ):
+        return await _old_server_emit_async(
+            self, event=event, data=to_jsonable_python(data), to=to, *args, **kwargs
+        )
+
+
+class BaseClient(OldBaseClient):
+    """BaseClient with pydantic validation."""
+
+    def on(
+        self: OldBaseClient,
+        event: str,
+        handler: Optional[Callable] = None,
+        *args,
+        **kwargs,
+    ) -> Callable:
+        if handler is None:
+            # invoked as a decorator
+            return functools.partial(
+                _wrapper,
+                old_on=_old_client_on,
+                self=self,
+                event=event,
+                *args,
+                **kwargs,
+            )
+        else:
+            # not invoked as a decorator, but as a function
+            return _wrapper(handler, _old_client_on, self, event, *args, **kwargs)
+
+
+class Client(BaseClient, OldClient):
+    """Client with pydantic validation and data conversion."""
+
+    def emit(self: OldClient, event: str, data: Any = None, *args, **kwargs):
+        return _old_client_emit(self, event, to_jsonable_python(data), *args, **kwargs)
+
+
+class AsyncClient(BaseClient, OldAsyncClient):
+    """AsyncClient with pydantic validation and data conversion."""
+
+    async def emit(self: OldAsyncClient, event: str, data: Any = None, *args, **kwargs):
+        return await _old_client_emit_async(
+            self, event, to_jsonable_python(data), *args, **kwargs
+        )
+
+
+def monkey_patch():
+    module_logger.debug("Monkey patching")
+    OldBaseServer.on = BaseServer.on
+    OldServer.emit = Server.emit
+    OldAsyncServer.emit = AsyncServer.emit
+    OldBaseClient.on = BaseClient.on
+    OldClient.emit = Client.emit
+    OldAsyncClient.emit = AsyncClient.emit
+    module_logger.debug("Monkey patched")

pydantic_socketio-0.1.0.dist-info/METADATA

@@ -0,0 +1,165 @@
+Metadata-Version: 2.4
+Name: pydantic-socketio
+Version: 0.1.0
+Summary: Pydantic-enhanced SocketIO with FastAPI integration support.
+Project-URL: homepage, https://github.com/atomiechen/Pydantic-SocketIO
+Project-URL: issues, https://github.com/atomiechen/Pydantic-SocketIO/issues
+Project-URL: changelog, https://github.com/atomiechen/Pydantic-SocketIO/blob/main/CHANGELOG.md
+Author-email: Atomie CHEN <atomic_cwh@163.com>
+License-File: LICENSE
+Keywords: fastapi,pydantic,socketio
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.8
+Requires-Dist: pydantic>=2.10.6
+Requires-Dist: python-socketio>=5.12.1
+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'
+Provides-Extra: docs
+Requires-Dist: python-socketio[docs]>=5.12.1; extra == 'docs'
+Provides-Extra: fastapi
+Requires-Dist: fastapi[standard]>=0.115.11; extra == 'fastapi'
+Description-Content-Type: text/markdown
+
+# Pydantic-SocketIO
+
+A Pydantic-enhanced SocketIO library for Python, with FastAPI integration.
+
+
+## Features
+
+⭐️ **Pydantic-Enhanced SocketIO**: Drop-in replacements for the original [python-socketio](https://github.com/miguelgrinberg/python-socketio) server and client (sync and async), with built-in Pydantic validation for event data. You can also easily monkey patch this validation to the original `socketio` server and client.
+
+🪐 **Easy Integration with FastAPI**: Seamlessly integrates `Socket.IO` with FastAPI, allowing you to manage event-driven communication effortlessly.
+
+
+## Installation
+
+```sh
+pip install pydantic-socketio
+```
+
+
+## Usage
+
+### Recommended: Pydantic-Enhanced SocketIO Server and Client
+
+Drop-in replacements for the original [python-socketio](https://github.com/miguelgrinberg/python-socketio) server and client are provided. 
+
+The enhanced SocketIO server with Pydantic validation:
+
+```python
+from pydantic import BaseModel
+import pydantic_socketio
+
+class ChatMessage(BaseModel):
+    role: str
+    content: str
+
+# Create an enhanced SocketIO server; use AsyncServer for async server
+sio = pydantic_socketio.Server()
+
+# Define an event with Pydantic validation
+@sio.event
+def message(data: ChatMessage):
+    print(f"Received chat message from {data.role}: {data.content}")
+    data.content = data.content.upper()
+    print(f"Sending uppercase message: {data.content}")
+    # Emit an event with Pydantic model without any additional conversion
+    sio.emit("message", data)
+
+# `on` decorator is also supported
+@sio.on("custom_event")
+def handle_custom_event(data: int):
+    ...
+```
+
+The enhanced SocketIO client with Pydantic validation:
+
+```python
+import pydantic_socketio
+
+# Create an enhanced SocketIO client; use AsyncClient for async client
+sio = pydantic_socketio.Client()
+
+@sio.event
+def ping(data: int):
+    ...
+
+@sio.on("pong")
+def handle_pong(data: int):
+    ...
+```
+
+
+### Alternative: Monkey Patching for Original SocketIO
+
+Alternatively, if you want to apply Pydantic validation to the original [python-socketio](https://github.com/miguelgrinberg/python-socketio) server and client without replacing them, you can use the `monkey_patch()` method:
+
+```python
+from pydantic_socketio import monkey_patch
+import socketio
+
+# Apply monkey patch to the original socketio server and client
+monkey_patch()
+
+# Now, you can use the original socketio server and client with Pydantic validation
+sio = socketio.Server()
+
+@sio.event
+def ping(data: int):
+    print(f"Received ping: {data}")
+    data += 1
+    print(f"Sending pong: {data}")
+    sio.emit("poing", data)
+```
+
+
+### FastAPI Integration
+
+You can easily integrate the enhanced socketio server with FastAPI by using FastAPISocketIO:
+
+```python
+from fastapi import FastAPI
+from pydantic_socketio import FastAPISocketIO
+
+app = FastAPI()
+
+@app.get("/")
+async def root():
+    return {"message": "Hello World"}
+...
+
+# Create a FastAPI socketio server
+sio = FastAPISocketIO(app)
+
+@sio.event
+async def ping(data: int):
+    print(f"Received ping: {data}")
+    data += 1
+    print(f"Sending pong: {data}")
+    await sio.emit("pong", data)
+...
+```
+
+You can also integrate the SocketIO server manually after FastAPI initialization:
+
+```python
+from fastapi import FastAPI
+from pydantic_socketio import FastAPISocketIO
+
+sio = FastAPISocketIO()
+...
+app = FastAPI()
+...
+
+# Integrate the SocketIO server to FastAPI
+sio.integrate(app)
+```
+
+## License
+
+[Pydantic-SocketIO](https://github.com/atomiechen/Pydantic-SocketIO) © 2025 by [Atomie CHEN](https://github.com/atomiechen) is licensed under the [MIT License](https://github.com/atomiechen/Pydantic-SocketIO/blob/main/LICENSE).

pydantic_socketio-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+pydantic_socketio/__init__.py,sha256=Sl-HYhhteo4mFOIU2xc2bw341hAnnj5ZfpD1VMpr5mc,405
+pydantic_socketio/fastapi_socketio.py,sha256=OcwzFzZTnoKqpCGX7SyaBYqq2rL3MCKgRQXURM3Yt30,1397
+pydantic_socketio/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pydantic_socketio/pydantic_socketio.py,sha256=EVFQitiDaoB_aDm4iNHsVSK_TF1q5BBRAAQgjo8qYiM,5202
+pydantic_socketio-0.1.0.dist-info/METADATA,sha256=5NRp_PspYZTHwCgMkcCaEIHE1acF7BWvgC61IrD1a1U,4787
+pydantic_socketio-0.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+pydantic_socketio-0.1.0.dist-info/licenses/LICENSE,sha256=SpSDGxJCTumVhMVOPkFg_x6q01lPcU6KsYh_7DhwJg0,1068
+pydantic_socketio-0.1.0.dist-info/RECORD,,

pydantic_socketio-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

pydantic_socketio-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Atomie CHEN
+
+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.