{"id":2062,"library":"httpx-ws","title":"HTTPX WebSockets","description":"httpx-ws is a Python library that adds WebSocket client capabilities to the popular HTTPX library. It provides both synchronous and asynchronous APIs for connecting to WebSocket servers and sending/receiving messages, seamlessly integrating with HTTPX's client infrastructure. Currently at version 0.9.0, it maintains an active release cycle with frequent updates and improvements.","status":"active","version":"0.9.0","language":"en","source_language":"en","source_url":"https://github.com/frankie567/httpx-ws","tags":["websockets","http client","async","httpx","asyncio","anyio"],"install":[{"cmd":"pip install httpx-ws","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Core HTTP client library that httpx-ws extends for WebSocket support.","package":"httpx","optional":false},{"reason":"Asynchronous backend for concurrent operations and stream handling.","package":"anyio","optional":false}],"imports":[{"note":"Recommended class-based client API introduced in v0.8.0.","symbol":"WebSocketClient","correct":"from httpx_ws import WebSocketClient"},{"note":"Older function-based async connection API; the class-based client is now preferred.","symbol":"aconnect_ws","correct":"from httpx_ws import aconnect_ws"},{"note":"Older function-based sync connection API; the class-based client is now preferred.","symbol":"connect_ws","correct":"from httpx_ws import connect_ws"},{"symbol":"WebSocketDisconnect","correct":"from httpx_ws import WebSocketDisconnect"}],"quickstart":{"code":"import httpx\nfrom httpx_ws import WebSocketClient, WebSocketDisconnect\nimport asyncio\n\nasync def main():\n    # Connect to a local test WebSocket server (e.g., uvicorn with websockets)\n    # For a real application, replace with your actual WebSocket URL\n    websocket_url = \"ws://localhost:8000/ws\"\n    \n    try:\n        async with httpx.AsyncClient() as client:\n            async with WebSocketClient(websocket_url, client) as websocket:\n                print(f\"Connected to {websocket_url}\")\n                await websocket.send_text(\"Hello, WebSocket!\")\n                print(\"Sent: Hello, WebSocket!\")\n                \n                # Try to receive a response, with a timeout\n                try:\n                    data = await asyncio.wait_for(websocket.receive_text(), timeout=5.0)\n                    print(f\"Received: {data}\")\n                except asyncio.TimeoutError:\n                    print(\"No data received within 5 seconds.\")\n                \n    except* WebSocketDisconnect as e:\n        print(f\"WebSocket disconnected gracefully: {e}\")\n    except ExceptionGroup as eg:\n        # Handle other exceptions wrapped in ExceptionGroup (v0.9.0+)\n        # This ensures all potential wrapped errors are considered\n        print(f\"An ExceptionGroup occurred: {eg}\")\n        for exc in eg.exceptions:\n            if isinstance(exc, WebSocketDisconnect):\n                print(f\"Caught WebSocketDisconnect within ExceptionGroup: {exc}\")\n            else:\n                print(f\"Caught other exception within ExceptionGroup: {exc}\")\n                raise exc # Re-raise if not specifically handled\n    except Exception as e:\n        print(f\"An unexpected error occurred: {e}\")\n\nif __name__ == \"__main__\":\n    asyncio.run(main())","lang":"python","description":"Demonstrates connecting to a WebSocket server using the class-based `WebSocketClient`, sending text, and receiving text. It includes robust error handling for `WebSocketDisconnect` and `ExceptionGroup` (for v0.9.0+). Replace `ws://localhost:8000/ws` with your target WebSocket endpoint. Requires an active WebSocket server running at the specified URL to execute successfully."},"warnings":[{"fix":"Update `try...except` blocks to use the `except*` syntax for specific sub-exceptions (e.g., `except* WebSocketDisconnect`) or catch `ExceptionGroup` and iterate its `exceptions` attribute.","message":"Async exceptions, including `WebSocketDisconnect`, are now wrapped in `ExceptionGroup` when propagating out of the `async with` block for `WebSocketClient` (or `aconnect_ws`).","severity":"breaking","affected_versions":"0.9.0+"},{"fix":"Ensure your project is running on Python 3.10 or a newer compatible version.","message":"Python 3.9 support was dropped in v0.8.0, and Python 3.8 support was dropped in v0.7.0. The library now requires Python 3.10 or newer.","severity":"breaking","affected_versions":"0.7.0, 0.8.0, 0.9.0+"},{"fix":"Migrate from `connect_ws`/`aconnect_ws` functions to `WebSocketClient` for new code and consider refactoring existing code to use the more flexible class-based approach (e.g., `async with httpx.AsyncClient() as client: async with WebSocketClient(url, client) as ws:`).","message":"A new class-based API, `WebSocketClient`, was introduced in v0.8.0 and is now the recommended way to open WebSocket connections, replacing the older `connect_ws`/`aconnect_ws` functions.","severity":"gotcha","affected_versions":"0.8.0+"},{"fix":"If you were directly instantiating `AsyncWebSocketSession` or `WebSocketSession` and passing `subprotocol`, remove this parameter. If using `connect_ws`/`aconnect_ws` or `WebSocketClient`, this change is typically transparent.","message":"The `subprotocol` parameter was removed from `AsyncWebSocketSession` and `WebSocketSession` constructors. Subprotocols are now automatically set from response headers.","severity":"breaking","affected_versions":"0.6.0+"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}