django-sockets 1.0.0__tar.gz

django_sockets-1.0.0/LICENSE

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

django_sockets-1.0.0/PKG-INFO

@@ -0,0 +1,191 @@
+Metadata-Version: 2.1
+Name: django_sockets
+Version: 1.0.0
+Summary: Simplified Django websocket processes designed to work with cloud caches
+Author-email: Connor Makowski <conmak@mit.edu>
+Project-URL: Homepage, https://github.com/connor-makowski/django_sockets
+Project-URL: Bug Tracker, https://github.com/connor-makowski/django_sockets/issues
+Project-URL: Documentation, https://connor-makowski.github.io/django_sockets/django_sockets.html
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: django>=5.0.0
+Requires-Dist: asgiref>=3.0.0
+Requires-Dist: redis>=5.0.0
+Requires-Dist: msgpack>=1.0.0
+
+# Django Sockets
+[![PyPI version](https://badge.fury.io/py/django_sockets.svg)](https://badge.fury.io/py/django_sockets)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Simplified Django websocket processes designed to work with cloud caches (valkey|redis on single|distributed|serverless)
+
+# Setup
+
+### General
+
+Make sure you have Python 3.10.x (or higher) installed on your system. You can download it [here](https://www.python.org/downloads/).
+
+### Installation
+
+```
+pip install django_sockets
+```
+
+### Other Requirements
+
+- Make sure a cache (valkey or redis) is setup and accessible from your server.
+
+    - To run one locally (using docker) for testing, you can use the following command:
+
+        ```bash
+        docker run -d -p 6379:6379 --name django_sockets_cache valkey/valkey:7
+        ```
+
+    - To run the container after it has been created, you can use the following command:
+
+        ```bash
+        docker start django_sockets_cache
+        ```
+
+    - To kill the container later, you can use the following command:
+
+        ```bash
+        docker kill django_sockets_cache
+        ```
+
+# Usage
+
+Low level docs: https://connor-makowski.github.io/django_sockets/django_sockets.html
+
+## Implement in a Django Project
+
+### TODO
+
+## Examples Without Django
+
+### Example Subscribing & Broadcasting
+```py
+from django_sockets.sockets import BaseSocketServer
+import asyncio, time
+
+DJANGO_SOCKETS_CONFIG = {
+    "hosts": [
+        {"address": f"redis://0.0.0.0:6379"}
+    ],
+}
+
+# Override the send method to print the data being sent
+# instead of sending it over a non existent websocket connection
+async def send(ws_data):
+    print("WS SENDING:", ws_data)
+
+
+# Create a receive queue to simulate receiving messages from a websocket client
+base_receive = asyncio.Queue()
+# Create a base socket server with a scope of {}
+base_socket_server = BaseSocketServer(scope={}, receive=base_receive.get, send=send, config=DJANGO_SOCKETS_CONFIG)
+# Start the listeners for the base socket server
+base_socket_server.start_listeners()
+# Subscribe to the test_channel
+base_socket_server.subscribe("test_channel")
+# Broadcast a message to the test_channel
+base_socket_server.broadcast("test_channel", "test message")
+# Give the async functions a small amount of time to complete
+time.sleep(.5)
+
+
+#=> Output:
+#=> WS SENDING: {'type': 'websocket.send', 'text': '"test message"'}
+```
+
+### Example Handle Websocket Messages
+```py
+from django_sockets.sockets import BaseSocketServer
+import asyncio, time
+
+DJANGO_SOCKETS_CONFIG = {
+    "hosts": [
+        {"address": f"redis://0.0.0.0:6379"}
+    ],
+}
+
+class CustomSocketServer(BaseSocketServer):
+    def receive(self, data):
+        """
+        When a data message is received from a websocket client:
+            - Print the data
+            - Broadcast the data to a channel (the same channel that the socket server is subscribed to)
+
+        Normally you would want to override the receive method to do any server side processing of the data that is received
+        then broadcast any changes back to relevant channels.
+        """
+        print("WS RECEIVED: ", data)
+        print(f"BROADCASTING TO '{self.scope['username']}'")
+        self.broadcast(self.scope['username'], data)
+
+    def connect(self):
+        """
+        When the websocket connects, subscribe to the channel of the user.
+
+        This is an important method to override if you want to subscribe to a channel when a user frist connects.
+
+        Otherwise, you can always subscribe to a channel based on the data that is received in the receive method.
+        """
+        print(f"CONNECTED")
+        print(f"SUSCRIBING TO '{self.scope['username']}'")
+        self.subscribe(self.scope['username'])
+
+# Override the send method to print the data being sent
+async def send(data):
+    """
+    Normally you would not override the send method, but since we are not actually sending data over a websocket connection
+    we are just going to print the data that would be sent.
+
+    This is useful for testing the socket server without having to actually send data over a websocket connection
+
+    Note: This only sends the first 64 characters of the data
+    """
+    print("WS SENDING:", str(data)[:64])
+
+# Create a receive queue to simulate receiving messages from a websocket client
+custom_receive = asyncio.Queue()
+# Create a custom socket server defined above with a scope of {'username':'adam'}, the custom_receive queue, and the send method defined above
+custom_socket_server = CustomSocketServer(scope={'username':'adam'}, receive=custom_receive.get, send=send)
+# Start the listeners for the custom socket server
+#    - Websocket Listener - Listens for websocket messages
+#    - Broadcast Listener - Listens for messages that were broadcasted to a channel that the socket server is subscribed to
+custom_socket_server.start_listeners()
+# Give the async functions a small amount of time to complete
+time.sleep(.1)
+# Simulate a WS connection request
+custom_receive.put_nowait({'type': 'websocket.connect'})
+# Give the async functions a small amount of time to complete
+time.sleep(.1)
+# Simulate a message being received from a WS client
+# This will call the receive method which is defined above
+custom_receive.put_nowait({'type': 'websocket.receive', 'text': '{"data": "test"}'})
+# Give the async functions a small amount of time to complete
+time.sleep(.1)
+# Simulate a WS disconnect request
+custom_receive.put_nowait({'type': 'websocket.disconnect'})
+# Give the async functions a small amount of time to complete
+time.sleep(.1)
+# Simulate a message being received from a WS client after the connection has been closed
+# This will not do anything since the connection has been closed and the listeners have been killed
+custom_receive.put_nowait({'type': 'websocket.receive', 'text': '{"data_after_close": "test"}'})
+# Give the async functions a small amount of time to complete
+time.sleep(.1)
+
+#=> Output:
+#=> WS SENDING: {'type': 'websocket.accept'}
+#=> CONNECTED
+#=> SUSCRIBING TO 'adam'
+#=> WS RECEIVED:  {'data': 'test'}
+#=> BROADCASTING TO 'adam'
+#=> WS SENDING: {'type': 'websocket.send', 'text': '{"data": "test"}'}
+
+```

django_sockets-1.0.0/README.md

@@ -0,0 +1,172 @@
+# Django Sockets
+[![PyPI version](https://badge.fury.io/py/django_sockets.svg)](https://badge.fury.io/py/django_sockets)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Simplified Django websocket processes designed to work with cloud caches (valkey|redis on single|distributed|serverless)
+
+# Setup
+
+### General
+
+Make sure you have Python 3.10.x (or higher) installed on your system. You can download it [here](https://www.python.org/downloads/).
+
+### Installation
+
+```
+pip install django_sockets
+```
+
+### Other Requirements
+
+- Make sure a cache (valkey or redis) is setup and accessible from your server.
+
+    - To run one locally (using docker) for testing, you can use the following command:
+
+        ```bash
+        docker run -d -p 6379:6379 --name django_sockets_cache valkey/valkey:7
+        ```
+
+    - To run the container after it has been created, you can use the following command:
+
+        ```bash
+        docker start django_sockets_cache
+        ```
+
+    - To kill the container later, you can use the following command:
+
+        ```bash
+        docker kill django_sockets_cache
+        ```
+
+# Usage
+
+Low level docs: https://connor-makowski.github.io/django_sockets/django_sockets.html
+
+## Implement in a Django Project
+
+### TODO
+
+## Examples Without Django
+
+### Example Subscribing & Broadcasting
+```py
+from django_sockets.sockets import BaseSocketServer
+import asyncio, time
+
+DJANGO_SOCKETS_CONFIG = {
+    "hosts": [
+        {"address": f"redis://0.0.0.0:6379"}
+    ],
+}
+
+# Override the send method to print the data being sent
+# instead of sending it over a non existent websocket connection
+async def send(ws_data):
+    print("WS SENDING:", ws_data)
+
+
+# Create a receive queue to simulate receiving messages from a websocket client
+base_receive = asyncio.Queue()
+# Create a base socket server with a scope of {}
+base_socket_server = BaseSocketServer(scope={}, receive=base_receive.get, send=send, config=DJANGO_SOCKETS_CONFIG)
+# Start the listeners for the base socket server
+base_socket_server.start_listeners()
+# Subscribe to the test_channel
+base_socket_server.subscribe("test_channel")
+# Broadcast a message to the test_channel
+base_socket_server.broadcast("test_channel", "test message")
+# Give the async functions a small amount of time to complete
+time.sleep(.5)
+
+
+#=> Output:
+#=> WS SENDING: {'type': 'websocket.send', 'text': '"test message"'}
+```
+
+### Example Handle Websocket Messages
+```py
+from django_sockets.sockets import BaseSocketServer
+import asyncio, time
+
+DJANGO_SOCKETS_CONFIG = {
+    "hosts": [
+        {"address": f"redis://0.0.0.0:6379"}
+    ],
+}
+
+class CustomSocketServer(BaseSocketServer):
+    def receive(self, data):
+        """
+        When a data message is received from a websocket client:
+            - Print the data
+            - Broadcast the data to a channel (the same channel that the socket server is subscribed to)
+
+        Normally you would want to override the receive method to do any server side processing of the data that is received
+        then broadcast any changes back to relevant channels.
+        """
+        print("WS RECEIVED: ", data)
+        print(f"BROADCASTING TO '{self.scope['username']}'")
+        self.broadcast(self.scope['username'], data)
+
+    def connect(self):
+        """
+        When the websocket connects, subscribe to the channel of the user.
+
+        This is an important method to override if you want to subscribe to a channel when a user frist connects.
+
+        Otherwise, you can always subscribe to a channel based on the data that is received in the receive method.
+        """
+        print(f"CONNECTED")
+        print(f"SUSCRIBING TO '{self.scope['username']}'")
+        self.subscribe(self.scope['username'])
+
+# Override the send method to print the data being sent
+async def send(data):
+    """
+    Normally you would not override the send method, but since we are not actually sending data over a websocket connection
+    we are just going to print the data that would be sent.
+
+    This is useful for testing the socket server without having to actually send data over a websocket connection
+
+    Note: This only sends the first 64 characters of the data
+    """
+    print("WS SENDING:", str(data)[:64])
+
+# Create a receive queue to simulate receiving messages from a websocket client
+custom_receive = asyncio.Queue()
+# Create a custom socket server defined above with a scope of {'username':'adam'}, the custom_receive queue, and the send method defined above
+custom_socket_server = CustomSocketServer(scope={'username':'adam'}, receive=custom_receive.get, send=send)
+# Start the listeners for the custom socket server
+#    - Websocket Listener - Listens for websocket messages
+#    - Broadcast Listener - Listens for messages that were broadcasted to a channel that the socket server is subscribed to
+custom_socket_server.start_listeners()
+# Give the async functions a small amount of time to complete
+time.sleep(.1)
+# Simulate a WS connection request
+custom_receive.put_nowait({'type': 'websocket.connect'})
+# Give the async functions a small amount of time to complete
+time.sleep(.1)
+# Simulate a message being received from a WS client
+# This will call the receive method which is defined above
+custom_receive.put_nowait({'type': 'websocket.receive', 'text': '{"data": "test"}'})
+# Give the async functions a small amount of time to complete
+time.sleep(.1)
+# Simulate a WS disconnect request
+custom_receive.put_nowait({'type': 'websocket.disconnect'})
+# Give the async functions a small amount of time to complete
+time.sleep(.1)
+# Simulate a message being received from a WS client after the connection has been closed
+# This will not do anything since the connection has been closed and the listeners have been killed
+custom_receive.put_nowait({'type': 'websocket.receive', 'text': '{"data_after_close": "test"}'})
+# Give the async functions a small amount of time to complete
+time.sleep(.1)
+
+#=> Output:
+#=> WS SENDING: {'type': 'websocket.accept'}
+#=> CONNECTED
+#=> SUSCRIBING TO 'adam'
+#=> WS RECEIVED:  {'data': 'test'}
+#=> BROADCASTING TO 'adam'
+#=> WS SENDING: {'type': 'websocket.send', 'text': '{"data": "test"}'}
+
+```

django_sockets-1.0.0/django_sockets/broadcaster.py

@@ -0,0 +1,99 @@
+import asyncio, logging
+
+from .pubsub import PubSubLayer
+from .utils import ensure_loop_running, get_config
+
+logger = logging.getLogger(__name__)
+
+
+class Broadcaster:
+    def __init__(self, *args, loop=None, config=None, **kwargs):
+        self.__loop__ = ensure_loop_running(loop)
+        self.pubsub_layer = self.__get_pubsub_layer__(config=config)
+        self.__usable__ = self.pubsub_layer is not None
+
+    # Sync Functions
+    def broadcast(self, channel: str, data: [dict | list]):
+        """
+        Broadcast data to a specific channel or all channels that this socket server is subscribed to.
+
+        Requires:
+
+        - channel: str = The channel to broadcast the data to
+        - data: [dict|list] = The data to broadcast to the channel
+            - Note: This data must be JSON serializable
+        """
+        asyncio.run_coroutine_threadsafe(
+            self.async_broadcast(channel, data), self.__loop__
+        )
+
+    def subscribe(self, channel: str):
+        """
+        Subscribe to a channel to receive data from broadcasts
+
+        Requires:
+
+        - channel: str = The channel to subscribe to
+        """
+        asyncio.run_coroutine_threadsafe(
+            self.async_subscribe(channel), self.__loop__
+        )
+
+    # Async Functions
+    async def async_broadcast(self, channel: str, data):
+        """
+        Broadcast data to a channel where all relevant clients will receive the data
+        and send it to the client
+
+        Requires:
+
+        - channel: str = The channel to broadcast the data to
+        - data: [dict|list] = The data to broadcast to the channel
+            - Note: This data must be JSON serializable
+        """
+        self.__warn_on_not_usable__()
+        await self.pubsub_layer.send(str(channel), data)
+
+    async def async_subscribe(self, channel: str):
+        """
+        Subscribe to a channel to receive data from broadcasts
+
+        Requires:
+
+        - channel: str = The channel to subscribe to
+        """
+        self.__warn_on_not_usable__()
+        await self.pubsub_layer.subscribe(str(channel))
+
+    async def async_receive_broadcast(self):
+        """
+        Receive a broadcast from a channel that this socket server is subscribed to
+
+        Returns:
+
+        - channel: str = The channel that the data was broadcasted to
+        - data: [dict|list] = The data that was broadcasted to the channel
+            - Note: This data must be JSON serializable
+        """
+        data = await self.pubsub_layer.receive()
+        return data["channel"], data["data"]
+
+    # Internal Methods
+    def __get_pubsub_layer__(self, config=None):
+        """
+        A method to get the PubSubLayer given the settings.DJANGO_SOCKETS_CONFIG
+        """
+        config = get_config(config)
+        if "hosts" in config:
+            return PubSubLayer(**config)
+        return None
+
+    def __warn_on_not_usable__(self):
+        """
+        Warn the user if the broadcaster is not usable
+        """
+        if not self.__usable__:
+            logger.log(
+                logging.ERROR,
+                "No hosts provided in settings.DJANGO_SOCKETS_CONFIG. Broadcasting / Subscribing is not possible.",
+            )

django_sockets-1.0.0/django_sockets/middleware.py

@@ -0,0 +1,56 @@
+from .utils import database_sync_to_async
+
+def get_anonymous_user_obj():
+    try:
+        return AnonymousUser()
+    except:
+        pass
+    try:
+        from django.contrib.auth.models import AnonymousUser
+        return AnonymousUser()
+    except:
+        pass
+    return None
+    
+def get_drf_token_obj():
+    try:
+        return Token
+    except:
+        pass
+    try:
+        from rest_framework.authtoken.models import Token
+        return Token
+    except:
+        pass
+    return None
+
+@database_sync_to_async
+def get_drf_user(user_token):
+    if user_token is not None:
+        try:
+            token = get_drf_token_obj().objects.get(key=user_token)
+            return token.user
+        except:
+            pass
+    return get_anonymous_user_obj()
+
+
+def get_query_arg(query_string, arg, default=None):
+    try:
+        return (
+            dict((x.split("=") for x in query_string.decode().split("&")))
+        ).get(arg, default)
+    except:
+        return None
+
+
+class DRFTokenAuthMiddleware:
+    def __init__(self, app):
+        self.app = app
+
+    async def __call__(self, scope, receive, send):
+        scope = dict(scope)
+        scope["user"] = await get_drf_user(
+            get_query_arg(scope["query_string"], "user_token")
+        )
+        return await self.app(scope, receive, send)