websocket-client


Namewebsocket-client JSON
Version 0.47.0 PyPI version JSON
download
home_pagehttps://github.com/websocket-client/websocket-client.git
SummaryWebSocket client for python. hybi13 is supported.
upload_time2018-02-21 23:55:02
maintainer
docs_urlNone
authorliris
requires_python
licenseLGPL
keywords websockets
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            =================
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
============

 - LGPL

Installation
=============

This module is tested on Python 2.7 and Python 3.x.

Type "python setup.py install" or "pip install websocket-client" to install.

.. 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

performance
------------------

 "send" method is too slow on pure python. If you want to get better performace, please install numpy or wsaccel.
You can get the best performance from numpy.


How about Python 3
===========================

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
    try:
        import thread
    except ImportError:
        import _thread as 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()


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("Receiving...")
    result =  ws.recv()
    print("Received '%s'" % result)
    ws.close()

If you want to customize socket options, set sockopt.

sockopt example

.. code:: python

    from websocket import create_connection
    ws = create_connection("ws://echo.websocket.org/",
                            sockopt=((socket.IPPROTO_TCP, socket.TCP_NODELAY),))


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

    import socket
    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, 1),), class_=MyWebSocket)


FAQ
============

How to disable ssl cert verification?
----------------------------------------

Please set sslopt to {"cert_reqs": ssl.CERT_NONE}.

WebSocketApp sample

.. code:: python

    ws = websocket.WebSocketApp("wss://echo.websocket.org")
    ws.run_forever(sslopt={"cert_reqs": ssl.CERT_NONE})

create_connection sample

.. code:: python

    ws = websocket.create_connection("wss://echo.websocket.org",
      sslopt={"cert_reqs": ssl.CERT_NONE})

WebSocket sample

.. code:: python

    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")


How to enable `SNI <http://en.wikipedia.org/wiki/Server_Name_Indication>`_?
---------------------------------------------------------------------------

SNI support is available for Python 2.7.9+ and 3.2+. It will be enabled automatically whenever possible.


Sub Protocols.
----------------------------------------

The server needs to support sub protocols, please set the subprotocol like this.


Subprotocol sample

.. code:: python

    ws = websocket.create_connection("ws://example.com/websocket", subprotocols=["binary", "base64"])



wsdump.py
============

wsdump.py is simple WebSocket test(debug) tool.

sample for echo.websocket.org::

  $ wsdump.py ws://echo.websocket.org/
  Press Ctrl+C to quit
  > Hello, WebSocket
  < Hello, WebSocket
  > How are you?
  < How are you?

Usage
---------

usage::

  wsdump.py [-h] [-v [VERBOSE]] ws_url

WebSocket Simple Dump Tool

positional arguments:
  ws_url                websocket url. ex. ws://echo.websocket.org/

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

example::

  $ wsdump.py ws://echo.websocket.org/
  $ wsdump.py ws://echo.websocket.org/ -v
  $ wsdump.py ws://echo.websocket.org/ -vv

            

Raw data

            {
    "maintainer": "", 
    "docs_url": null, 
    "requires_python": "", 
    "maintainer_email": "", 
    "cheesecake_code_kwalitee_id": null, 
    "keywords": "websockets", 
    "upload_time": "2018-02-21 23:55:02", 
    "author": "liris", 
    "home_page": "https://github.com/websocket-client/websocket-client.git", 
    "github_user": "websocket-client", 
    "download_url": "https://pypi.python.org/packages/c9/bb/8d3dd9063cfe0cd5d03fe6a1f74ddd948f384e9c1eff0eb978f3976a7d27/websocket_client-0.47.0.tar.gz", 
    "platform": "", 
    "version": "0.47.0", 
    "cheesecake_documentation_id": null, 
    "description": "=================\nwebsocket-client\n=================\n\nwebsocket-client module  is WebSocket client for python. This provide the low level APIs for WebSocket. All APIs are the synchronous functions.\n\nwebsocket-client supports only hybi-13.\n\n\nLicense\n============\n\n - LGPL\n\nInstallation\n=============\n\nThis module is tested on Python 2.7 and Python 3.x.\n\nType \"python setup.py install\" or \"pip install websocket-client\" to install.\n\n.. CAUTION::\n\n  from v0.16.0, we can install by \"pip install websocket-client\" for python 3.\n\nThis module depend on\n\n - six\n - backports.ssl_match_hostname for Python 2.x\n\nperformance\n------------------\n\n \"send\" method is too slow on pure python. If you want to get better performace, please install numpy or wsaccel.\nYou can get the best performance from numpy.\n\n\nHow about Python 3\n===========================\n\nNow, we support python 3 on  single source code from version 0.14.0. Thanks, @battlemidget and @ralphbean.\n\nHTTP Proxy\n=============\n\nSupport websocket access via http proxy.\nThe proxy server must allow \"CONNECT\" method to websocket port.\nDefault squid setting is \"ALLOWED TO CONNECT ONLY HTTPS PORT\".\n\nCurrent implementation of websocket-client is using \"CONNECT\" method via proxy.\n\n\nexample\n\n.. code:: python\n\n    import websocket\n    ws = websocket.WebSocket()\n    ws.connect(\"ws://example.com/websocket\", http_proxy_host=\"proxy_host_name\", http_proxy_port=3128)\n\n\n\n\nExamples\n========\n\nLong-lived connection\n---------------------\nThis example is similar to how WebSocket code looks in browsers using JavaScript.\n\n.. code:: python\n\n    import websocket\n    try:\n        import thread\n    except ImportError:\n        import _thread as thread\n    import time\n\n    def on_message(ws, message):\n        print(message)\n\n    def on_error(ws, error):\n        print(error)\n\n    def on_close(ws):\n        print(\"### closed ###\")\n\n    def on_open(ws):\n        def run(*args):\n            for i in range(3):\n                time.sleep(1)\n                ws.send(\"Hello %d\" % i)\n            time.sleep(1)\n            ws.close()\n            print(\"thread terminating...\")\n        thread.start_new_thread(run, ())\n\n\n    if __name__ == \"__main__\":\n        websocket.enableTrace(True)\n        ws = websocket.WebSocketApp(\"ws://echo.websocket.org/\",\n                                  on_message = on_message,\n                                  on_error = on_error,\n                                  on_close = on_close)\n        ws.on_open = on_open\n        ws.run_forever()\n\n\nShort-lived one-off send-receive\n--------------------------------\nThis is if you want to communicate a short message and disconnect immediately when done.\n\n.. code:: python\n\n    from websocket import create_connection\n    ws = create_connection(\"ws://echo.websocket.org/\")\n    print(\"Sending 'Hello, World'...\")\n    ws.send(\"Hello, World\")\n    print(\"Sent\")\n    print(\"Receiving...\")\n    result =  ws.recv()\n    print(\"Received '%s'\" % result)\n    ws.close()\n\nIf you want to customize socket options, set sockopt.\n\nsockopt example\n\n.. code:: python\n\n    from websocket import create_connection\n    ws = create_connection(\"ws://echo.websocket.org/\",\n                            sockopt=((socket.IPPROTO_TCP, socket.TCP_NODELAY),))\n\n\nMore advanced: Custom class\n---------------------------\nYou can also write your own class for the connection, if you want to handle the nitty-gritty details yourself.\n\n.. code:: python\n\n    import socket\n    from websocket import create_connection, WebSocket\n    class MyWebSocket(WebSocket):\n        def recv_frame(self):\n            frame = super().recv_frame()\n            print('yay! I got this frame: ', frame)\n            return frame\n\n    ws = create_connection(\"ws://echo.websocket.org/\",\n                            sockopt=((socket.IPPROTO_TCP, socket.TCP_NODELAY, 1),), class_=MyWebSocket)\n\n\nFAQ\n============\n\nHow to disable ssl cert verification?\n----------------------------------------\n\nPlease set sslopt to {\"cert_reqs\": ssl.CERT_NONE}.\n\nWebSocketApp sample\n\n.. code:: python\n\n    ws = websocket.WebSocketApp(\"wss://echo.websocket.org\")\n    ws.run_forever(sslopt={\"cert_reqs\": ssl.CERT_NONE})\n\ncreate_connection sample\n\n.. code:: python\n\n    ws = websocket.create_connection(\"wss://echo.websocket.org\",\n      sslopt={\"cert_reqs\": ssl.CERT_NONE})\n\nWebSocket sample\n\n.. code:: python\n\n    ws = websocket.WebSocket(sslopt={\"cert_reqs\": ssl.CERT_NONE})\n    ws.connect(\"wss://echo.websocket.org\")\n\n\nHow to disable hostname verification.\n----------------------------------------\n\nPlease set sslopt to {\"check_hostname\": False}.\n(since v0.18.0)\n\nWebSocketApp sample\n\n.. code:: python\n\n    ws = websocket.WebSocketApp(\"wss://echo.websocket.org\")\n    ws.run_forever(sslopt={\"check_hostname\": False})\n\ncreate_connection sample\n\n.. code:: python\n\n    ws = websocket.create_connection(\"wss://echo.websocket.org\",\n      sslopt={\"check_hostname\": False})\n\nWebSocket sample\n\n.. code:: python\n\n    ws = websocket.WebSocket(sslopt={\"check_hostname\": False})\n    ws.connect(\"wss://echo.websocket.org\")\n\n\nHow to enable `SNI <http://en.wikipedia.org/wiki/Server_Name_Indication>`_?\n---------------------------------------------------------------------------\n\nSNI support is available for Python 2.7.9+ and 3.2+. It will be enabled automatically whenever possible.\n\n\nSub Protocols.\n----------------------------------------\n\nThe server needs to support sub protocols, please set the subprotocol like this.\n\n\nSubprotocol sample\n\n.. code:: python\n\n    ws = websocket.create_connection(\"ws://example.com/websocket\", subprotocols=[\"binary\", \"base64\"])\n\n\n\nwsdump.py\n============\n\nwsdump.py is simple WebSocket test(debug) tool.\n\nsample for echo.websocket.org::\n\n  $ wsdump.py ws://echo.websocket.org/\n  Press Ctrl+C to quit\n  > Hello, WebSocket\n  < Hello, WebSocket\n  > How are you?\n  < How are you?\n\nUsage\n---------\n\nusage::\n\n  wsdump.py [-h] [-v [VERBOSE]] ws_url\n\nWebSocket Simple Dump Tool\n\npositional arguments:\n  ws_url                websocket url. ex. ws://echo.websocket.org/\n\noptional arguments:\n  -h, --help                           show this help message and exit\nWebSocketApp\n  -v VERBOSE, --verbose VERBOSE    set verbose mode. If set to 1, show opcode. If set to 2, enable to trace websocket module\n\nexample::\n\n  $ wsdump.py ws://echo.websocket.org/\n  $ wsdump.py ws://echo.websocket.org/ -v\n  $ wsdump.py ws://echo.websocket.org/ -vv\n", 
    "lcname": "websocket-client", 
    "bugtrack_url": null, 
    "github": true, 
    "name": "websocket-client", 
    "license": "LGPL", 
    "github_project": "websocket-client.git", 
    "summary": "WebSocket client for python. hybi13 is supported.", 
    "split_keywords": [
        "websockets"
    ], 
    "author_email": "liris.pp@gmail.com", 
    "urls": [
        {
            "has_sig": false, 
            "upload_time": "2018-02-21T23:55:06", 
            "comment_text": "", 
            "python_version": "3.6", 
            "url": "https://pypi.python.org/packages/9d/fb/f51a03e232e00d6c504dfe815aed090c894ba3f8d3f7fd9612f3e227bf24/websocket_client-0.47.0-py2.py3-none-any.whl", 
            "md5_digest": "1d30cbb890c167a52c510959f467607d", 
            "downloads": 0, 
            "filename": "websocket_client-0.47.0-py2.py3-none-any.whl", 
            "packagetype": "bdist_wheel", 
            "path": "9d/fb/f51a03e232e00d6c504dfe815aed090c894ba3f8d3f7fd9612f3e227bf24/websocket_client-0.47.0-py2.py3-none-any.whl", 
            "size": 200885
        }, 
        {
            "has_sig": false, 
            "upload_time": "2018-02-21T23:55:02", 
            "comment_text": "", 
            "python_version": "source", 
            "url": "https://pypi.python.org/packages/c9/bb/8d3dd9063cfe0cd5d03fe6a1f74ddd948f384e9c1eff0eb978f3976a7d27/websocket_client-0.47.0.tar.gz", 
            "md5_digest": "790b3ecb5364293ad70c59a1b92debb1", 
            "downloads": 0, 
            "filename": "websocket_client-0.47.0.tar.gz", 
            "packagetype": "sdist", 
            "path": "c9/bb/8d3dd9063cfe0cd5d03fe6a1f74ddd948f384e9c1eff0eb978f3976a7d27/websocket_client-0.47.0.tar.gz", 
            "size": 202611
        }
    ], 
    "error": "Could not fetch GitHub repository", 
    "_id": null, 
    "cheesecake_installability_id": null
}