diff options
| -rw-r--r-- | README.md | 60 | ||||
| -rw-r--r-- | docs/source/examples.rst | 47 | ||||
| -rw-r--r-- | docs/source/faq.rst | 33 |
3 files changed, 94 insertions, 46 deletions
@@ -38,7 +38,6 @@ You can use either `python setup.py install` or `pip install websocket-client` to install. This module is tested on Python 2.7 and Python 3.4+. Python 3 support was first introduced in version 0.14.0, but is a work in progress. - ## Usage Tips Check out the documentation's FAQ for additional guidelines: @@ -46,29 +45,20 @@ Check out the documentation's FAQ for additional guidelines: ### Performance -The "send" and "validate_utf8" methods are very slow in pure Python. -If you want to get better performance, please install both numpy and wsaccel. +The `send` and `validate_utf8` methods are very slow in pure Python. You can +disable UTF8 validation in this library (and receive a performance enhancement) +with the `skip_utf8_validation` parameter. If you want to get better +performance, please install both numpy and wsaccel, and import them into your +project files - these other libraries will automatically be used when available. Note that wsaccel can sometimes cause other issues. -### HTTP proxy - -This project supports WebSocket connections over a HTTP proxy. The proxy server -must allow "CONNECT" method to websocket port. The default squid proxy setting -is "ALLOWED TO CONNECT ONLY HTTPS PORT". +### Long-lived Connection -The current implementation of websocket-client is using the "CONNECT" method via -proxy. Here is an example of using a proxy: - -```python -import websocket -ws = websocket.WebSocket() -ws.connect("ws://example.com/websocket", http_proxy_host="proxy_host_name", http_proxy_port=3128) -``` - -### Long-lived connection - -This example is similar to how WebSocket code looks in browsers using -JavaScript. +Most real-world WebSockets situations involve longer-lived connections. +The WebSocketApp `run_forever` loop automatically tries to reconnect when a +connection is lost, and provides a variety of event-based connection controls. +The project documentation has +[additional examples](https://websocket-client.readthedocs.io/en/latest/examples.html) ```python import websocket @@ -97,21 +87,24 @@ def on_open(ws): print("thread terminating...") thread.start_new_thread(run, ()) - if __name__ == "__main__": websocket.enableTrace(True) ws = websocket.WebSocketApp("ws://echo.websocket.org/", + on_open = on_open, 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 +### Short-lived Connection This is if you want to communicate a short message and disconnect -immediately when done. +immediately when done. For example, if you want to confirm that a WebSocket +server is running and responds properly to a specific request. +The project documentation has +[additional examples](https://websocket-client.readthedocs.io/en/latest/examples.html) ```python from websocket import create_connection @@ -133,23 +126,6 @@ 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. - -```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) -``` - ### Acknowledgements Thanks to @battlemidget and @ralphbean for helping migrate this project to diff --git a/docs/source/examples.rst b/docs/source/examples.rst index 038181a..a11bb23 100644 --- a/docs/source/examples.rst +++ b/docs/source/examples.rst @@ -241,6 +241,26 @@ Disabling SSL or Hostname Verification See the relevant :ref:`FAQ` page for instructions. +Using a Custom Class +-------------------------------- + +You can also write your own class for the connection, if you want to handle +the nitty-gritty connection details yourself. + +:: + + 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) + + Setting Timeout Value -------------------------------- @@ -299,7 +319,11 @@ Connecting through a HTTP proxy The example below show how to connect through a HTTP proxy. Note that this library does support authentication to a proxy using the ``http_proxy_auth`` -parameter. +parameter. Be aware that the current implementation of websocket-client uses +the "CONNECT" method, and the proxy server must allow the "CONNECT" method. For +example, the squid proxy only allows the "CONNECT" method +`on HTTPS ports <https://wiki.squid-cache.org/Features/HTTPS#CONNECT_tunnel>`_ +by default. **WebSocket proxy example** @@ -353,7 +377,7 @@ message opcodes as part of the protocol. These can serve as a way to keep a long-lived connection active even if data is not being transmitted. However, if a blocking event is happening, there may be some issues with ping/pong. The below examples demonstrate how ping and pong can be sent by this library. You -can getaddition debugging information by using +can get additional debugging information by using `Wireshark <https://www.wireshark.org/>`_ to view the ping and pong messages being sent. In order for Wireshark to identify the WebSocket protocol properly, it should observe the initial HTTP @@ -380,9 +404,9 @@ This type of connection does not automatically respond to a "ping" with a "pong" **WebSocketApp ping/pong example** -This example, and run_forever in general, is better for long-lived connections. +This example, and ``run_forever()`` in general, is better for long-lived connections. If a server needs a regular ping to keep the connection alive, this is probably -the option you will want to use. The run_forever connection will automatically +the option you will want to use. The ``run_forever()`` function will automatically send a "pong" when it receives a "ping", per the specification. :: @@ -401,3 +425,18 @@ send a "pong" when it receives a "ping", per the specification. wsapp = websocket.WebSocketApp("wss://stream.meetup.com/2/rsvps", on_message=on_message, on_ping=on_ping, on_pong=on_pong) wsapp.run_forever(ping_interval=10, ping_timeout=60) + +Real-world Examples +========================= + +Other projects that depend on websocket-client may be able to illustrate more +complex use cases for this library. A few of the projects using websocket-client +are listed below: + +- `https://github.com/slackapi/python-slack-sdk <https://github.com/slackapi/python-slack-sdk>`_ +- `https://github.com/wee-slack/wee-slack <https://github.com/wee-slack/wee-slack>`_ +- `https://github.com/aluzzardi/wssh/ <https://github.com/aluzzardi/wssh/>`_ +- `https://github.com/invisibleroads/socketIO-client <https://github.com/invisibleroads/socketIO-client>`_ +- `https://github.com/Ape/samsungctl <https://github.com/Ape/samsungctl>`_ +- `https://github.com/xchwarze/samsung-tv-ws-api <https://github.com/xchwarze/samsung-tv-ws-api>`_ +- `https://github.com/andresriancho/websocket-fuzzer <https://github.com/andresriancho/websocket-fuzzer>`_ diff --git a/docs/source/faq.rst b/docs/source/faq.rst index 797d94f..eadacad 100644 --- a/docs/source/faq.rst +++ b/docs/source/faq.rst @@ -2,6 +2,39 @@ FAQ ### +Why is this library slow? +=========================== + +The ``send`` and ``validate_utf8`` methods are very slow in pure Python. +If you want to get better performance, please install both numpy and wsaccel. +Note that wsaccel can sometimes cause other issues. + +How to solve the "connection is already closed" error? +=========================================================== + +The WebSocketConnectionClosedException, which returns the message "Connection +is already closed.", occurs when a WebSocket function such as ``send()`` or +``recv()`` is called but the WebSocket connection is already closed. One way +to handle exceptions in Python is by using +`a try/except <https://docs.python.org/3/tutorial/errors.html#handling-exceptions>`_ +statement, which allows you to control what your program does if the WebSocket +connection is closed when you try to use it. In order to properly carry out +further functions with your WebSocket connection after the connection has +closed, you will need to reconnect the WebSocket, using ``connect()`` or +``create_connection()`` (from the _core.py file). The WebSocketApp ``run_forever()`` +function automatically tries to reconnect when the connection is lost. + +What's going on with the naming of this library? +================================================== + +To install this library, you use ``pip3 install websocket-client``, while ``import +websocket`` imports this library, and PyPi lists the package as +``websocket_client``. Why is it so confusing? To see the original issue about +the choice of ``import websocket``, see +`issue #60 <https://github.com/websocket-client/websocket-client/issues/60>`_ +and to read about websocket-client vs. websocket_client, see +`issue #147 <https://github.com/websocket-client/websocket-client/issues/147>`_ + How to disable ssl cert verification? ======================================= |