{"library":"simple-websocket","title":"Simple WebSocket","description":"simple-websocket is a Python library offering a collection of WebSocket servers and clients, supporting both traditional (synchronous) and asynchronous (asyncio) workflows. It simplifies WebSocket communication for standalone applications and integration into larger web frameworks like Flask or ASGI. The project is actively maintained with regular releases, with the latest being 1.1.0.","status":"active","version":"1.1.0","language":"en","source_language":"en","source_url":"https://github.com/miguelgrinberg/simple-websocket","tags":["websocket","networking","server","client","asyncio","synchronous","real-time"],"install":[{"cmd":"pip install simple-websocket","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Requires Python 3.6 or newer for execution.","package":"Python","optional":false}],"imports":[{"note":"For creating a synchronous WebSocket server.","symbol":"Server","correct":"from simple_websocket import Server"},{"note":"For creating an asynchronous WebSocket server (asyncio).","symbol":"AioServer","correct":"from simple_websocket import AioServer"},{"note":"For creating a synchronous WebSocket client.","symbol":"Client","correct":"from simple_websocket import Client"},{"note":"For creating an asynchronous WebSocket client (asyncio).","symbol":"AioClient","correct":"from simple_websocket import AioClient"},{"note":"Exception raised when a WebSocket connection is closed, useful for graceful handling.","symbol":"ConnectionClosed","correct":"from simple_websocket import ConnectionClosed"},{"note":"Avoid confusion with the `websockets` library, which is a different package with a similar purpose but a distinct API.","wrong":"import websockets","symbol":"websockets (another library)","correct":"from simple_websocket import Client"}],"quickstart":{"code":"import time\nimport threading\nfrom simple_websocket import Client, Server, ConnectionClosed\n\ndef run_server():\n    print(\"Starting synchronous WebSocket echo server on ws://localhost:8765\")\n    server = Server('ws://localhost:8765')\n    while True:\n        try:\n            print(\"Server: Waiting for connection...\")\n            client_ws = server.accept()\n            print(\"Server: Client connected!\")\n            while True:\n                try:\n                    message = client_ws.receive()\n                    print(f\"Server received: {message}\")\n                    client_ws.send(f\"Echo: {message}\")\n                except ConnectionClosed:\n                    print(\"Server: Client disconnected.\")\n                    break\n        except ConnectionClosed:\n            print(\"Server: Server closed or error.\")\n            break\n\ndef run_client():\n    print(\"Starting synchronous WebSocket client...\")\n    time.sleep(1) # Give server time to start\n    try:\n        client = Client('ws://localhost:8765')\n        print(\"Client connected!\")\n        for i in range(3):\n            message = f\"Hello from client {i+1}\"\n            print(f\"Client sending: {message}\")\n            client.send(message)\n            response = client.receive()\n            print(f\"Client received: {response}\")\n            time.sleep(0.5)\n        client.close()\n        print(\"Client disconnected.\")\n    except ConnectionClosed:\n        print(\"Client: Connection closed prematurely.\")\n    except Exception as e:\n        print(f\"Client error: {e}\")\n\nif __name__ == '__main__':\n    server_thread = threading.Thread(target=run_server)\n    server_thread.daemon = True # Allows main program to exit even if thread is running\n    server_thread.start()\n\n    run_client()\n\n    print(\"Main program finished.\")\n","lang":"python","description":"This example demonstrates a basic synchronous WebSocket echo server and client. The server listens for connections, echoes received messages, and handles client disconnections. The client connects, sends a few messages, receives echoes, and then disconnects."},"warnings":[{"fix":"Consult the official 'CHANGES.md' on GitHub for detailed migration steps. Adapt your code to the new API if necessary.","message":"Version 1.0.0 introduced significant changes. Review the CHANGES.md file on the GitHub repository when upgrading from pre-1.0.0 versions to avoid compatibility issues.","severity":"breaking","affected_versions":"<1.0.0 to 1.0.0+"},{"fix":"Wrap WebSocket communication (e.g., `receive()`, `send()`) in a `try...except ConnectionClosed:` block and implement appropriate cleanup logic.","message":"When developing WebSocket servers, it is crucial to handle the `ConnectionClosed` exception gracefully. This exception is raised when a client disconnects, allowing your server logic to clean up resources or stop processing for that specific client.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure your server is configured for WSS (WebSocket Secure) with a valid SSL/TLS certificate, and clients connect using `wss://`.","message":"For production deployments, always use secure WebSocket connections (`wss://`) instead of insecure ones (`ws://`). Browsers, proxies, and firewalls often block or restrict `ws://` connections, leading to connection failures or security vulnerabilities.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Refer to your proxy server's documentation for WebSocket configuration. For Nginx, this typically involves `proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection \"upgrade\";`","message":"If your WebSocket server is behind a reverse proxy (e.g., Nginx, Apache), the proxy must be explicitly configured to correctly handle the WebSocket upgrade headers (`Upgrade` and `Connection`). Misconfiguration will prevent WebSocket connections from establishing.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Implement robust authentication and authorization checks at the application layer, potentially during the initial HTTP handshake and for subsequent messages.","message":"The WebSocket protocol itself does not provide inherent mechanisms for authentication or authorization. Application-level security (e.g., tokens, sessions, origin validation) must be implemented separately to secure your WebSocket connections and data.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-05T00:00:00.000Z","next_check":"2026-07-04T00:00:00.000Z"}