tools/telemetry/third_party/websocket-client/README.rst

   1 =================
   2 websocket-client
   3 =================
   4
   5 websocket-client module  is WebSocket client for python. This provide the low level APIs for WebSocket. All APIs are the synchronous functions.
   6
   7 websocket-client supports only hybi-13.
   8
   9 License
  10 ============
  11
  12  - LGPL
  13
  14 Installation
  15 =============
  16
  17 This module is tested on only Python 2.7.
  18
  19 Type "python setup.py install" or "pip install websocket-client" to install.
  20
  21 This module does not depend on any other module.
  22
  23 How about Python 3
  24 ===========================
  25
  26 py3( https://github.com/liris/websocket-client/tree/py3 ) branch is for python 3.3. Every test case is passed.
  27 If you are using python3, please check it.
  28
  29 Example
  30 ============
  31
  32 Low Level API example::
  33
  34     from websocket import create_connection
  35     ws = create_connection("ws://echo.websocket.org/")
  36     print "Sending 'Hello, World'..."
  37     ws.send("Hello, World")
  38     print "Sent"
  39     print "Reeiving..."
  40     result =  ws.recv()
  41     print "Received '%s'" % result
  42     ws.close()
  43
  44 If you want to customize socket options, set sockopt.
  45
  46 sockopt example:
  47
  48     from websocket import create_connection
  49     ws = create_connection("ws://echo.websocket.org/".
  50                             sockopt=((socket.IPPROTO_TCP, socket.TCP_NODELAY),) )
  51
  52
  53 JavaScript websocket-like API example::
  54
  55   import websocket
  56   import thread
  57   import time
  58
  59   def on_message(ws, message):
  60       print message
  61
  62   def on_error(ws, error):
  63       print error
  64
  65   def on_close(ws):
  66       print "### closed ###"
  67
  68   def on_open(ws):
  69       def run(*args):
  70           for i in range(3):
  71               time.sleep(1)
  72               ws.send("Hello %d" % i)
  73           time.sleep(1)
  74           ws.close()
  75           print "thread terminating..."
  76       thread.start_new_thread(run, ())
  77
  78
  79   if __name__ == "__main__":
  80       websocket.enableTrace(True)
  81       ws = websocket.WebSocketApp("ws://echo.websocket.org/",
  82                                   on_message = on_message,
  83                                   on_error = on_error,
  84                                   on_close = on_close)
  85       ws.on_open = on_open
  86
  87       ws.run_forever()
  88
  89
  90 wsdump.py
  91 ============
  92
  93 wsdump.py is simple WebSocket test(debug) tool.
  94
  95 sample for echo.websocket.org::
  96
  97   $ wsdump.py ws://echo.websocket.org/
  98   Press Ctrl+C to quit
  99   > Hello, WebSocket
 100   < Hello, WebSocket
 101   > How are you?
 102   < How are you?
 103
 104 Usage
 105 ---------
 106
 107 usage::
 108   wsdump.py [-h] [-v [VERBOSE]] ws_url
 109
 110 WebSocket Simple Dump Tool
 111
 112 positional arguments:
 113   ws_url                websocket url. ex. ws://echo.websocket.org/
 114
 115 optional arguments:
 116   -h, --help                           show this help message and exit
 117
 118   -v VERBOSE, --verbose VERBOSE    set verbose mode. If set to 1, show opcode. If set to 2, enable to trace websocket module
 119
 120 example::
 121
 122   $ wsdump.py ws://echo.websocket.org/
 123   $ wsdump.py ws://echo.websocket.org/ -v
 124   $ wsdump.py ws://echo.websocket.org/ -vv
 125
 126 ChangeLog
 127 ============
 128
 129 - v0.12.0
 130
 131   - support keep alive for WebSocketApp(ISSUE#34)
 132   - fix some SSL bugs(ISSUE#35, #36)
 133   - fix "Timing out leaves websocket library in bad state"(ISSUE#37)
 134   - fix "WebSocketApp.run_with_no_err() silently eats all exceptions"(ISSUE#38)
 135   - WebSocketTimeoutException will be raised for ws/wss timeout(ISSUE#40)
 136   - improve wsdump message(ISSUE#42)
 137   - support fragmentation message(ISSUE#43)
 138   - fix some bugs
 139
 140 - v0.11.0
 141
 142   - Only log non-normal close status(ISSUE#31)
 143   - Fix default Origin isn't URI(ISSUE#32)
 144   - fileno support(ISSUE#33)
 145
 146 - v0.10.0
 147
 148   - allow to set HTTP Header to WebSocketApp(ISSUE#27)
 149   - fix typo in pydoc(ISSUE#28)
 150   - Passing a socketopt flag to the websocket constructor(ISSUE#29)
 151   - websocket.send fails with long data(ISSUE#30)
 152
 153
 154 - v0.9.0
 155
 156   - allow to set opcode in WebSocketApp.send(ISSUE#25)
 157   - allow to modify Origin(ISSUE#26)
 158
 159 - v0.8.0
 160
 161   - many bug fix
 162   - some performance improvement
 163
 164 - v0.7.0
 165
 166   - fixed problem to read long data.(ISSUE#12)
 167   - fix buffer size boundary violation
 168
 169 - v0.6.0
 170
 171   - Patches: UUID4, self.keep_running, mask_key (ISSUE#11)
 172   - add wsdump.py tool
 173
 174 - v0.5.2
 175
 176   - fix Echo App Demo Throw Error: 'NoneType' object has no attribute 'opcode  (ISSUE#10)
 177
 178 - v0.5.1
 179
 180   - delete invalid print statement.
 181
 182 - v0.5.0
 183
 184   - support hybi-13 protocol.
 185
 186 - v0.4.1
 187
 188   - fix incorrect custom header order(ISSUE#1)
 189