python/lib/websocket/websocket/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.9.0
 130
 131   - allow to set opcode in WebSocketApp.send(ISSUE#25)
 132   - allow to modify Origin(ISSUE#26)
 133
 134 - v0.8.0
 135
 136   - many bug fix
 137   - some performance improvement
 138
 139 - v0.7.0
 140
 141   - fixed problem to read long data.(ISSUE#12)
 142   - fix buffer size boundary violation
 143
 144 - v0.6.0
 145
 146   - Patches: UUID4, self.keep_running, mask_key (ISSUE#11)
 147   - add wsdump.py tool
 148
 149 - v0.5.2
 150
 151   - fix Echo App Demo Throw Error: 'NoneType' object has no attribute 'opcode  (ISSUE#10)
 152
 153 - v0.5.1
 154
 155   - delete invalid print statement.
 156
 157 - v0.5.0
 158
 159   - support hybi-13 protocol.
 160
 161 - v0.4.1
 162
 163   - fix incorrect custom header order(ISSUE#1)
 164