diff options
Diffstat (limited to 'systrace/catapult/telemetry/third_party/websocket-client/README.rst')
| -rw-r--r-- | systrace/catapult/telemetry/third_party/websocket-client/README.rst | 295 |
1 files changed, 183 insertions, 112 deletions
diff --git a/systrace/catapult/telemetry/third_party/websocket-client/README.rst b/systrace/catapult/telemetry/third_party/websocket-client/README.rst index 320342b..22447a8 100644 --- a/systrace/catapult/telemetry/third_party/websocket-client/README.rst +++ b/systrace/catapult/telemetry/third_party/websocket-client/README.rst @@ -2,10 +2,13 @@ websocket-client ================= +**Our repository has moved to https://github.com/websocket-client/websocket-client** + websocket-client module is WebSocket client for python. This provide the low level APIs for WebSocket. All APIs are the synchronous functions. websocket-client supports only hybi-13. + License ============ @@ -14,176 +17,244 @@ License Installation ============= -This module is tested on only Python 2.7. +This module is tested on Python 2.7 and Python 3.x. Type "python setup.py install" or "pip install websocket-client" to install. -This module does not depend on any other module. +.. CAUTION:: + + from v0.16.0, we can install by "pip install websocket-client" for python 3. + +This module depend on + + - six + - backports.ssl_match_hostname for Python 2.x How about Python 3 =========================== -py3( https://github.com/liris/websocket-client/tree/py3 ) branch is for python 3.3. Every test case is passed. -If you are using python3, please check it. +Now, we support python 3 on single source code from version 0.14.0. Thanks, @battlemidget and @ralphbean. + +HTTP Proxy +============= + +Support websocket access via http proxy. +The proxy server must allow "CONNECT" method to websocket port. +Default squid setting is "ALLOWED TO CONNECT ONLY HTTPS PORT". + +Current implementation of websocket-client is using "CONNECT" method via proxy. + + +example + +.. code:: python + + import websocket + ws = websocket.WebSocket() + ws.connect("ws://example.com/websocket", http_proxy_host="proxy_host_name", http_proxy_port=3128) + : + + + +Examples +======== + +Long-lived connection +--------------------- +This example is similar to how WebSocket code looks in browsers using JavaScript. + +.. code:: python + + import websocket + import thread + import time + + def on_message(ws, message): + print message + + def on_error(ws, error): + print error + + def on_close(ws): + print "### closed ###" + + def on_open(ws): + def run(*args): + for i in range(3): + time.sleep(1) + ws.send("Hello %d" % i) + time.sleep(1) + ws.close() + print "thread terminating..." + thread.start_new_thread(run, ()) + + + if __name__ == "__main__": + websocket.enableTrace(True) + ws = websocket.WebSocketApp("ws://echo.websocket.org/", + on_message = on_message, + on_error = on_error, + on_close = on_close) + ws.on_open = on_open + ws.run_forever() -Example -============ -Low Level API example:: +Short-lived one-off send-receive +-------------------------------- +This is if you want to communicate a short message and disconnect immediately when done. + +.. code:: python from websocket import create_connection ws = create_connection("ws://echo.websocket.org/") print "Sending 'Hello, World'..." ws.send("Hello, World") print "Sent" - print "Reeiving..." + print "Receiving..." result = ws.recv() print "Received '%s'" % result ws.close() If you want to customize socket options, set sockopt. -sockopt example: +sockopt example + +.. code:: python from websocket import create_connection - ws = create_connection("ws://echo.websocket.org/". - sockopt=((socket.IPPROTO_TCP, socket.TCP_NODELAY),) ) - - -JavaScript websocket-like API example:: - - import websocket - import thread - import time - - def on_message(ws, message): - print message - - def on_error(ws, error): - print error - - def on_close(ws): - print "### closed ###" - - def on_open(ws): - def run(*args): - for i in range(3): - time.sleep(1) - ws.send("Hello %d" % i) - time.sleep(1) - ws.close() - print "thread terminating..." - thread.start_new_thread(run, ()) - - - if __name__ == "__main__": - websocket.enableTrace(True) - ws = websocket.WebSocketApp("ws://echo.websocket.org/", - on_message = on_message, - on_error = on_error, - on_close = on_close) - ws.on_open = on_open - - ws.run_forever() + ws = create_connection("ws://echo.websocket.org/", + sockopt=((socket.IPPROTO_TCP, socket.TCP_NODELAY),)) -wsdump.py +More advanced: Custom class +--------------------------- +You can also write your own class for the connection, if you want to handle the nitty-gritty details yourself. + +.. code:: python + + from websocket import create_connection, WebSocket + class MyWebSocket(WebSocket): + def recv_frame(self): + frame = super().recv_frame() + print('yay! I got this frame: ', frame) + return frame + + ws = create_connection("ws://echo.websocket.org/", + sockopt=((socket.IPPROTO_TCP, socket.TCP_NODELAY),), class_=MyWebSocket) + + +FAQ ============ -wsdump.py is simple WebSocket test(debug) tool. +How to disable ssl cert verification? +---------------------------------------- -sample for echo.websocket.org:: +Please set sslopt to {"cert_reqs": ssl.CERT_NONE}. - $ wsdump.py ws://echo.websocket.org/ - Press Ctrl+C to quit - > Hello, WebSocket - < Hello, WebSocket - > How are you? - < How are you? +WebSocketApp sample -Usage ---------- +.. code:: python -usage:: - wsdump.py [-h] [-v [VERBOSE]] ws_url + ws = websocket.WebSocketApp("wss://echo.websocket.org") + ws.run_forever(sslopt={"cert_reqs": ssl.CERT_NONE}) -WebSocket Simple Dump Tool +create_connection sample -positional arguments: - ws_url websocket url. ex. ws://echo.websocket.org/ +.. code:: python -optional arguments: - -h, --help show this help message and exit + ws = websocket.create_connection("wss://echo.websocket.org", + sslopt={"cert_reqs": ssl.CERT_NONE}) - -v VERBOSE, --verbose VERBOSE set verbose mode. If set to 1, show opcode. If set to 2, enable to trace websocket module +WebSocket sample -example:: +.. code:: python - $ wsdump.py ws://echo.websocket.org/ - $ wsdump.py ws://echo.websocket.org/ -v - $ wsdump.py ws://echo.websocket.org/ -vv + ws = websocket.WebSocket(sslopt={"cert_reqs": ssl.CERT_NONE}) + ws.connect("wss://echo.websocket.org") + + +How to disable hostname verification. +---------------------------------------- + +Please set sslopt to {"check_hostname": False}. +(since v0.18.0) + +WebSocketApp sample + +.. code:: python + + ws = websocket.WebSocketApp("wss://echo.websocket.org") + ws.run_forever(sslopt={"check_hostname": False}) + +create_connection sample + +.. code:: python + + ws = websocket.create_connection("wss://echo.websocket.org", + sslopt={"check_hostname": False}) + +WebSocket sample + +.. code:: python + + ws = websocket.WebSocket(sslopt={"check_hostname": False}) + ws.connect("wss://echo.websocket.org") -ChangeLog -============ -- v0.12.0 +How to enable `SNI <http://en.wikipedia.org/wiki/Server_Name_Indication>`_? +--------------------------------------------------------------------------- - - support keep alive for WebSocketApp(ISSUE#34) - - fix some SSL bugs(ISSUE#35, #36) - - fix "Timing out leaves websocket library in bad state"(ISSUE#37) - - fix "WebSocketApp.run_with_no_err() silently eats all exceptions"(ISSUE#38) - - WebSocketTimeoutException will be raised for ws/wss timeout(ISSUE#40) - - improve wsdump message(ISSUE#42) - - support fragmentation message(ISSUE#43) - - fix some bugs +SNI support is available for Python 2.7.9+ and 3.2+. It will be enabled automatically whenever possible. -- v0.11.0 - - Only log non-normal close status(ISSUE#31) - - Fix default Origin isn't URI(ISSUE#32) - - fileno support(ISSUE#33) +Sub Protocols. +---------------------------------------- -- v0.10.0 +The server needs to support sub protocols, please set the subprotocol like this. - - allow to set HTTP Header to WebSocketApp(ISSUE#27) - - fix typo in pydoc(ISSUE#28) - - Passing a socketopt flag to the websocket constructor(ISSUE#29) - - websocket.send fails with long data(ISSUE#30) +Subprotocol sample -- v0.9.0 +.. code:: python - - allow to set opcode in WebSocketApp.send(ISSUE#25) - - allow to modify Origin(ISSUE#26) + ws = websocket.create_connection("ws://exapmle.com/websocket", subprotocols=["binary", "base64"]) -- v0.8.0 - - many bug fix - - some performance improvement -- v0.7.0 +wsdump.py +============ - - fixed problem to read long data.(ISSUE#12) - - fix buffer size boundary violation +wsdump.py is simple WebSocket test(debug) tool. -- v0.6.0 +sample for echo.websocket.org:: - - Patches: UUID4, self.keep_running, mask_key (ISSUE#11) - - add wsdump.py tool + $ wsdump.py ws://echo.websocket.org/ + Press Ctrl+C to quit + > Hello, WebSocket + < Hello, WebSocket + > How are you? + < How are you? -- v0.5.2 +Usage +--------- - - fix Echo App Demo Throw Error: 'NoneType' object has no attribute 'opcode (ISSUE#10) +usage:: -- v0.5.1 + wsdump.py [-h] [-v [VERBOSE]] ws_url + +WebSocket Simple Dump Tool - - delete invalid print statement. +positional arguments: + ws_url websocket url. ex. ws://echo.websocket.org/ -- v0.5.0 +optional arguments: + -h, --help show this help message and exit +WebSocketApp + -v VERBOSE, --verbose VERBOSE set verbose mode. If set to 1, show opcode. If set to 2, enable to trace websocket module - - support hybi-13 protocol. +example:: -- v0.4.1 + $ wsdump.py ws://echo.websocket.org/ + $ wsdump.py ws://echo.websocket.org/ -v + $ wsdump.py ws://echo.websocket.org/ -vv - - fix incorrect custom header order(ISSUE#1) - |