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
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
|
.. _aiohttp-client-websockets:
WebSockets Client
=================
.. highlight:: python
.. module:: aiohttp.websocket_client
.. versionadded:: 0.15
:mod:`aiohttp` works with client websockets out-of-the-box.
You have to use the :func:`ws_connect()` coroutine for client
websocket connection. It accepts a *url* as a first parameter and returns
:class:`ClientWebSocketResponse`, with that object you can communicate with
websocket server using response's methods:
.. code-block:: python
ws = yield from aiohttp.ws_connect(
'http://webscoket-server.org/endpoint')
while True:
msg = yield from ws.receive()
if msg.tp == aiohttp.MsgType.text:
if msg.data == 'close':
yield from ws.close()
break
else:
ws.send_str(msg.data + '/answer')
elif msg.tp == aiohttp.MsgType.closed:
break
elif msg.tp == aiohttp.MsgType.error:
break
If you prefer to establish *websocket client connection* from
:class:`~aiohttp.client.ClientSession` object please use
:meth:`aiohttp.client.ClientSession.ws_connect` coroutine::
session = aiohttp.ClientSession()
ws = yield from session.ws_connect(
'http://webscoket-server.org/endpoint')
You **must** use the only websocket task for both reading (e.g ``yield
from ws.receive()``) and writing but may have multiple writer tasks
which can only send data asynchronously (by ``yield from
ws.send_str('data')`` for example).
ClientWebSocketResponse
-----------------------
To connect to a websocket server you have to use the
`aiohttp.ws_connect()` function, do not create an instance of class
:class:`ClientWebSocketResponse` manually.
.. coroutinefunction:: ws_connect(url, *, protocols=(), \
timeout=10.0, connector=None,\
ws_response_class=ClientWebSocketResponse,\
autoclose=True, autoping=True, loop=None)
This function creates a websocket connection, checks the response and
returns a :class:`ClientWebSocketResponse` object. In case of failure
it may raise a :exc:`~aiohttp.errors.WSServerHandshakeError` exception.
:param str url: Websocket server url
:param tuple protocols: Websocket protocols
:param float timeout: Timeout for websocket read. 10 seconds by default
:param obj connector: object :class:`TCPConnector`
:param ws_response_class: WebSocketResponse class implementation.
``ClientWebSocketResponse`` by default.
.. versionadded:: 0.16
:param bool autoclose: Automatically close websocket connection
on close message from server. If `autoclose` is
False them close procedure has to be handled manually
:param bool autoping: Automatically send `pong` on `ping` message from server
:param loop: :ref:`event loop<asyncio-event-loop>` used
for processing HTTP requests.
If param is ``None`` :func:`asyncio.get_event_loop`
used for getting default event loop, but we strongly
recommend to use explicit loops everywhere.
.. class:: ClientWebSocketResponse()
Class for handling client-side websockets.
.. attribute:: closed
Read-only property, ``True`` if :meth:`close` has been called of
:const:`~aiohttp.websocket.MSG_CLOSE` message has been received from peer.
.. attribute:: protocol
Websocket *subprotocol* chosen after :meth:`start` call.
May be ``None`` if server and client protocols are
not overlapping.
.. method:: exception()
Returns exception if any occurs or returns None.
.. method:: ping(message=b'')
Send :const:`~aiohttp.websocket.MSG_PING` to peer.
:param message: optional payload of *ping* message,
:class:`str` (converted to *UTF-8* encoded bytes)
or :class:`bytes`.
.. method:: send_str(data)
Send *data* to peer as :const:`~aiohttp.websocket.MSG_TEXT` message.
:param str data: data to send.
:raise TypeError: if data is not :class:`str`
.. method:: send_bytes(data)
Send *data* to peer as :const:`~aiohttp.websocket.MSG_BINARY` message.
:param data: data to send.
:raise TypeError: if data is not :class:`bytes`,
:class:`bytearray` or :class:`memoryview`.
.. coroutinemethod:: close(*, code=1000, message=b'')
A :ref:`coroutine<coroutine>` that initiates closing handshake by sending
:const:`~aiohttp.websocket.MSG_CLOSE` message. It waits for
close response from server. It add timeout to `close()` call just wrap
call with `asyncio.wait()` or `asyncio.wait_for()`.
:param int code: closing code
:param message: optional payload of *pong* message,
:class:`str` (converted to *UTF-8* encoded bytes)
or :class:`bytes`.
.. coroutinemethod:: receive()
A :ref:`coroutine<coroutine>` that waits upcoming *data*
message from peer and returns it.
The coroutine implicitly handles
:const:`~aiohttp.websocket.MSG_PING`,
:const:`~aiohttp.websocket.MSG_PONG` and
:const:`~aiohttp.websocket.MSG_CLOSE` without returning the
message.
It process *ping-pong game* and performs *closing handshake* internally.
:return: :class:`~aiohttp.websocket.Message`, `tp` is types of
`~aiohttp.MsgType`
.. disqus::
|
