README.chromium
1Name: Python websocket-client
2Short Name: websocket-client
3URL: https://github.com/liris/websocket-client
4Version: 0.41.0
5Revision: 83419000cb50a732bf3fc479cb0a9be097af212a
6Date: Fri Feb 3rd 03:14:01 2017 EST
7License: LGPL-3.0
8License File: NOT_SHIPPED
9Security Critical: no
10
11Description:
12
13websocket-client module is WebSocket client for python. This provide the low
14level APIs for WebSocket. All APIs are the synchronous functions.
15
16Used by the python code in devtools-auto to communicate with a running Chrome instance.
17
18Local Modifications:
19None.
20
README.rst
1=================
2websocket-client
3=================
4
5**Our repository has moved to https://github.com/websocket-client/websocket-client**
6
7websocket-client module is WebSocket client for python. This provide the low level APIs for WebSocket. All APIs are the synchronous functions.
8
9websocket-client supports only hybi-13.
10
11
12License
13============
14
15 - LGPL
16
17Installation
18=============
19
20This module is tested on Python 2.7 and Python 3.x.
21
22Type "python setup.py install" or "pip install websocket-client" to install.
23
24.. CAUTION::
25
26 from v0.16.0, we can install by "pip install websocket-client" for python 3.
27
28This module depend on
29
30 - six
31 - backports.ssl_match_hostname for Python 2.x
32
33How about Python 3
34===========================
35
36Now, we support python 3 on single source code from version 0.14.0. Thanks, @battlemidget and @ralphbean.
37
38HTTP Proxy
39=============
40
41Support websocket access via http proxy.
42The proxy server must allow "CONNECT" method to websocket port.
43Default squid setting is "ALLOWED TO CONNECT ONLY HTTPS PORT".
44
45Current implementation of websocket-client is using "CONNECT" method via proxy.
46
47
48example
49
50.. code:: python
51
52 import websocket
53 ws = websocket.WebSocket()
54 ws.connect("ws://example.com/websocket", http_proxy_host="proxy_host_name", http_proxy_port=3128)
55 :
56
57
58
59Examples
60========
61
62Long-lived connection
63---------------------
64This example is similar to how WebSocket code looks in browsers using JavaScript.
65
66.. code:: python
67
68 import websocket
69 import thread
70 import time
71
72 def on_message(ws, message):
73 print message
74
75 def on_error(ws, error):
76 print error
77
78 def on_close(ws):
79 print "### closed ###"
80
81 def on_open(ws):
82 def run(*args):
83 for i in range(3):
84 time.sleep(1)
85 ws.send("Hello %d" % i)
86 time.sleep(1)
87 ws.close()
88 print "thread terminating..."
89 thread.start_new_thread(run, ())
90
91
92 if __name__ == "__main__":
93 websocket.enableTrace(True)
94 ws = websocket.WebSocketApp("ws://echo.websocket.org/",
95 on_message = on_message,
96 on_error = on_error,
97 on_close = on_close)
98 ws.on_open = on_open
99 ws.run_forever()
100
101
102Short-lived one-off send-receive
103--------------------------------
104This is if you want to communicate a short message and disconnect immediately when done.
105
106.. code:: python
107
108 from websocket import create_connection
109 ws = create_connection("ws://echo.websocket.org/")
110 print "Sending 'Hello, World'..."
111 ws.send("Hello, World")
112 print "Sent"
113 print "Receiving..."
114 result = ws.recv()
115 print "Received '%s'" % result
116 ws.close()
117
118If you want to customize socket options, set sockopt.
119
120sockopt example
121
122.. code:: python
123
124 from websocket import create_connection
125 ws = create_connection("ws://echo.websocket.org/",
126 sockopt=((socket.IPPROTO_TCP, socket.TCP_NODELAY),))
127
128
129More advanced: Custom class
130---------------------------
131You can also write your own class for the connection, if you want to handle the nitty-gritty details yourself.
132
133.. code:: python
134
135 from websocket import create_connection, WebSocket
136 class MyWebSocket(WebSocket):
137 def recv_frame(self):
138 frame = super().recv_frame()
139 print('yay! I got this frame: ', frame)
140 return frame
141
142 ws = create_connection("ws://echo.websocket.org/",
143 sockopt=((socket.IPPROTO_TCP, socket.TCP_NODELAY),), class_=MyWebSocket)
144
145
146FAQ
147============
148
149How to disable ssl cert verification?
150----------------------------------------
151
152Please set sslopt to {"cert_reqs": ssl.CERT_NONE}.
153
154WebSocketApp sample
155
156.. code:: python
157
158 ws = websocket.WebSocketApp("wss://echo.websocket.org")
159 ws.run_forever(sslopt={"cert_reqs": ssl.CERT_NONE})
160
161create_connection sample
162
163.. code:: python
164
165 ws = websocket.create_connection("wss://echo.websocket.org",
166 sslopt={"cert_reqs": ssl.CERT_NONE})
167
168WebSocket sample
169
170.. code:: python
171
172 ws = websocket.WebSocket(sslopt={"cert_reqs": ssl.CERT_NONE})
173 ws.connect("wss://echo.websocket.org")
174
175
176How to disable hostname verification.
177----------------------------------------
178
179Please set sslopt to {"check_hostname": False}.
180(since v0.18.0)
181
182WebSocketApp sample
183
184.. code:: python
185
186 ws = websocket.WebSocketApp("wss://echo.websocket.org")
187 ws.run_forever(sslopt={"check_hostname": False})
188
189create_connection sample
190
191.. code:: python
192
193 ws = websocket.create_connection("wss://echo.websocket.org",
194 sslopt={"check_hostname": False})
195
196WebSocket sample
197
198.. code:: python
199
200 ws = websocket.WebSocket(sslopt={"check_hostname": False})
201 ws.connect("wss://echo.websocket.org")
202
203
204How to enable `SNI <http://en.wikipedia.org/wiki/Server_Name_Indication>`_?
205---------------------------------------------------------------------------
206
207SNI support is available for Python 2.7.9+ and 3.2+. It will be enabled automatically whenever possible.
208
209
210Sub Protocols.
211----------------------------------------
212
213The server needs to support sub protocols, please set the subprotocol like this.
214
215
216Subprotocol sample
217
218.. code:: python
219
220 ws = websocket.create_connection("ws://exapmle.com/websocket", subprotocols=["binary", "base64"])
221
222
223
224wsdump.py
225============
226
227wsdump.py is simple WebSocket test(debug) tool.
228
229sample for echo.websocket.org::
230
231 $ wsdump.py ws://echo.websocket.org/
232 Press Ctrl+C to quit
233 > Hello, WebSocket
234 < Hello, WebSocket
235 > How are you?
236 < How are you?
237
238Usage
239---------
240
241usage::
242
243 wsdump.py [-h] [-v [VERBOSE]] ws_url
244
245WebSocket Simple Dump Tool
246
247positional arguments:
248 ws_url websocket url. ex. ws://echo.websocket.org/
249
250optional arguments:
251 -h, --help show this help message and exit
252WebSocketApp
253 -v VERBOSE, --verbose VERBOSE set verbose mode. If set to 1, show opcode. If set to 2, enable to trace websocket module
254
255example::
256
257 $ wsdump.py ws://echo.websocket.org/
258 $ wsdump.py ws://echo.websocket.org/ -v
259 $ wsdump.py ws://echo.websocket.org/ -vv
260
261