client.rst (3100B)
1 Client 2 ====== 3 4 .. currentmodule:: websockets 5 6 Why does the client close the connection prematurely? 7 ----------------------------------------------------- 8 9 You're exiting the context manager prematurely. Wait for the work to be 10 finished before exiting. 11 12 For example, if your code has a structure similar to:: 13 14 async with connect(...) as websocket: 15 asyncio.create_task(do_some_work()) 16 17 change it to:: 18 19 async with connect(...) as websocket: 20 await do_some_work() 21 22 How do I access HTTP headers? 23 ----------------------------- 24 25 Once the connection is established, HTTP headers are available in 26 :attr:`~client.WebSocketClientProtocol.request_headers` and 27 :attr:`~client.WebSocketClientProtocol.response_headers`. 28 29 How do I set HTTP headers? 30 -------------------------- 31 32 To set the ``Origin``, ``Sec-WebSocket-Extensions``, or 33 ``Sec-WebSocket-Protocol`` headers in the WebSocket handshake request, use the 34 ``origin``, ``extensions``, or ``subprotocols`` arguments of 35 :func:`~client.connect`. 36 37 To override the ``User-Agent`` header, use the ``user_agent_header`` argument. 38 Set it to :obj:`None` to remove the header. 39 40 To set other HTTP headers, for example the ``Authorization`` header, use the 41 ``extra_headers`` argument:: 42 43 async with connect(..., extra_headers={"Authorization": ...}) as websocket: 44 ... 45 46 In the :mod:`threading` API, this argument is named ``additional_headers``:: 47 48 with connect(..., additional_headers={"Authorization": ...}) as websocket: 49 ... 50 51 How do I force the IP address that the client connects to? 52 ---------------------------------------------------------- 53 54 Use the ``host`` argument of :meth:`~asyncio.loop.create_connection`:: 55 56 await websockets.connect("ws://example.com", host="192.168.0.1") 57 58 :func:`~client.connect` accepts the same arguments as 59 :meth:`~asyncio.loop.create_connection`. 60 61 How do I close a connection? 62 ---------------------------- 63 64 The easiest is to use :func:`~client.connect` as a context manager:: 65 66 async with connect(...) as websocket: 67 ... 68 69 The connection is closed when exiting the context manager. 70 71 How do I reconnect when the connection drops? 72 --------------------------------------------- 73 74 Use :func:`~client.connect` as an asynchronous iterator:: 75 76 async for websocket in websockets.connect(...): 77 try: 78 ... 79 except websockets.ConnectionClosed: 80 continue 81 82 Make sure you handle exceptions in the ``async for`` loop. Uncaught exceptions 83 will break out of the loop. 84 85 How do I stop a client that is processing messages in a loop? 86 ------------------------------------------------------------- 87 88 You can close the connection. 89 90 Here's an example that terminates cleanly when it receives SIGTERM on Unix: 91 92 .. literalinclude:: ../../example/faq/shutdown_client.py 93 :emphasize-lines: 10-13 94 95 How do I disable TLS/SSL certificate verification? 96 -------------------------------------------------- 97 98 Look at the ``ssl`` argument of :meth:`~asyncio.loop.create_connection`. 99 100 :func:`~client.connect` accepts the same arguments as 101 :meth:`~asyncio.loop.create_connection`.