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