1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
|
Getting Started
===============
.. currentmodule:: trio_websocket
Installation
------------
This library supports Python ≥3.5. The easiest installation method is to use
PyPI.
::
$ pip3 install trio-websocket
You can also install from source. Visit `the project's GitHub page <https://github.com/python-trio/trio-websocket/>`__, where you can clone the repository or download a Zip file.
Change into the project directory and run the following command.
::
$ pip3 install .
If you want to contribute to development of the library, also see
:ref:`developer-installation`.
.. _client-example:
Client Example
--------------
This example briefly demonstrates how to create a WebSocket client.
.. code-block:: python
:linenos:
import trio
from trio_websocket import open_websocket_url
async def main():
try:
async with open_websocket_url('wss://localhost/foo') as ws:
await ws.send_message('hello world!')
message = await ws.get_message()
logging.info('Received message: %s', message)
except OSError as ose:
logging.error('Connection attempt failed: %s', ose)
trio.run(main)
The function :func:`open_websocket_url` is a context manager that automatically
connects and performs the WebSocket handshake before entering the block. This
ensures that the connection is usable before ``ws.send_message(…)`` is called.
The context manager yields a :class:`WebSocketConnection` instance that is used
to send and receive messages. The context manager also closes the connection
before exiting the block.
For more details and examples, see :ref:`websocket-clients`.
.. _server-example:
Server Example
---------------
This example briefly demonstrates how to create a WebSocket server. This server
is an *echo server*, i.e. it responds to each incoming message by sending back
an identical message.
.. code-block:: python
:linenos:
import trio
from trio_websocket import serve_websocket, ConnectionClosed
async def echo_server(request):
ws = await request.accept()
while True:
try:
message = await ws.get_message()
await ws.send_message(message)
except ConnectionClosed:
break
async def main():
await serve_websocket(echo_server, '127.0.0.1', 8000, ssl_context=None)
trio.run(main)
The function :func:`serve_websocket` requires a function that can handle each
incoming connection. This handler function receives a
:class:`WebSocketRequest` object that the server can use to inspect the client's
handshake. Next, the server accepts the request in order to complete the
handshake and receive a :class:`WebSocketConnection` instance that can be used
to send and receive messages.
For more details and examples, see :ref:`websocket-servers`.
|
