[](https://websocket-client.readthedocs.io/)
[](https://github.com/websocket-client/websocket-client/actions/workflows/build.yml)
[](https://codecov.io/gh/websocket-client/websocket-client)
[](https://pepy.tech/project/websocket-client)
[](https://pypi.org/project/websocket_client/)
[](https://opensource.org/licenses/Apache-2.0)
[](https://github.com/psf/black)
# websocket-client
websocket-client is a WebSocket client for Python. It provides access
to low level APIs for WebSockets. websocket-client implements version
[hybi-13](https://tools.ietf.org/html/draft-ietf-hybi-thewebsocketprotocol-13)
of the WebSocket protocol. This client does not currently support the
permessage-deflate extension from
[RFC 7692](https://tools.ietf.org/html/rfc7692).
## Documentation
This project's documentation can be found at
[https://websocket-client.readthedocs.io/](https://websocket-client.readthedocs.io/)
## Contributing
Please see the [contribution guidelines](https://github.com/websocket-client/websocket-client/blob/master/CONTRIBUTING.md)
## Installation
You can use `pip install websocket-client` to install, or `pip install -e .`
to install from a local copy of the code. This module is tested on Python 3.8+.
There are several optional dependencies that can be installed to enable
specific websocket-client features.
- To install `python-socks` for proxy usage and `wsaccel` for a minor performance boost, use:
`pip install websocket-client[optional]`
- To install `websockets` to run unit tests using the local echo server, use:
`pip install websocket-client[test]`
- To install `Sphinx` and `sphinx_rtd_theme` to build project documentation, use:
`pip install websocket-client[docs]`
While not a strict dependency, [rel](https://github.com/bubbleboy14/registeredeventlistener)
is useful when using `run_forever` with automatic reconnect. Install rel with `pip install rel`.
Footnote: Some shells, such as zsh, require you to escape the `[` and `]` characters with a `\`.
## Usage Tips
Check out the documentation's FAQ for additional guidelines:
[https://websocket-client.readthedocs.io/en/latest/faq.html](https://websocket-client.readthedocs.io/en/latest/faq.html)
Known issues with this library include lack of WebSocket Compression
support (RFC 7692) and [minimal threading documentation/support](https://websocket-client.readthedocs.io/en/latest/threading.html).
## Performance
The `send` and `validate_utf8` methods can sometimes be bottleneck.
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, install wsaccel. While
websocket-client does not depend on wsaccel, it will be used if
available. wsaccel doubles the speed of UTF8 validation and
offers a very minor 10% performance boost when masking the
payload data as part of the `send` process. Numpy used to
be a suggested performance enhancement alternative, but
[issue #687](https://github.com/websocket-client/websocket-client/issues/687)
found it didn't help.
## Examples
Many more examples are found in the
[examples documentation](https://websocket-client.readthedocs.io/en/latest/examples.html).
### Long-lived Connection
Most real-world WebSockets situations involve longer-lived connections.
The WebSocketApp `run_forever` loop will automatically try to reconnect
to an open WebSocket connection when a network
connection is lost if it is provided with:
- a `dispatcher` argument (async dispatcher like rel or pyevent)
- a non-zero `reconnect` argument (delay between disconnection and attempted reconnection)
`run_forever` provides a variety of event-based connection controls
using callbacks like `on_message` and `on_error`.
`run_forever` **does not automatically reconnect** if the server
closes the WebSocket gracefully (returning
[a standard websocket close code](https://www.rfc-editor.org/rfc/rfc6455.html#section-7.4.1)).
[This is the logic](https://github.com/websocket-client/websocket-client/pull/838#issuecomment-1228454826) behind the decision.
Customizing behavior when the server closes
the WebSocket should be handled in the `on_close` callback.
This example uses [rel](https://github.com/bubbleboy14/registeredeventlistener)
for the dispatcher to provide automatic reconnection.
```python
import websocket
import _thread
import time
import rel
def on_message(ws, message):
print(message)
def on_error(ws, error):
print(error)
def on_close(ws, close_status_code, close_msg):
print("### closed ###")
def on_open(ws):
print("Opened connection")
if __name__ == "__main__":
websocket.enableTrace(True)
ws = websocket.WebSocketApp("wss://api.gemini.com/v1/marketdata/BTCUSD",
on_open=on_open,
on_message=on_message,
on_error=on_error,
on_close=on_close)
ws.run_forever(dispatcher=rel, reconnect=5) # Set dispatcher to automatic reconnection, 5 second reconnect delay if connection closed unexpectedly
rel.signal(2, rel.abort) # Keyboard Interrupt
rel.dispatch()
```
### Short-lived Connection
This is if you want to communicate a short message and disconnect
immediately when done. For example, if you want to confirm that a WebSocket
server is running and responds properly to a specific request.
```python
from websocket import create_connection
ws = create_connection("ws://echo.websocket.events/")
print(ws.recv())
print("Sending 'Hello, World'...")
ws.send("Hello, World")
print("Sent")
print("Receiving...")
result = ws.recv()
print("Received '%s'" % result)
ws.close()
```
Raw data
{
"_id": null,
"home_page": "https://github.com/websocket-client/websocket-client.git",
"name": "websocket-client",
"maintainer": "engn33r",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "websocket.client@proton.me",
"keywords": "websockets client",
"author": "liris",
"author_email": "liris.pp@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/e6/30/fba0d96b4b5fbf5948ed3f4681f7da2f9f64512e1d303f94b4cc174c24a5/websocket_client-1.8.0.tar.gz",
"platform": null,
"description": "[](https://websocket-client.readthedocs.io/)\n[](https://github.com/websocket-client/websocket-client/actions/workflows/build.yml)\n[](https://codecov.io/gh/websocket-client/websocket-client)\n[](https://pepy.tech/project/websocket-client)\n[](https://pypi.org/project/websocket_client/)\n[](https://opensource.org/licenses/Apache-2.0)\n[](https://github.com/psf/black)\n\n# websocket-client\n\nwebsocket-client is a WebSocket client for Python. It provides access\nto low level APIs for WebSockets. websocket-client implements version\n[hybi-13](https://tools.ietf.org/html/draft-ietf-hybi-thewebsocketprotocol-13)\nof the WebSocket protocol. This client does not currently support the\npermessage-deflate extension from\n[RFC 7692](https://tools.ietf.org/html/rfc7692).\n\n## Documentation\n\nThis project's documentation can be found at\n[https://websocket-client.readthedocs.io/](https://websocket-client.readthedocs.io/)\n\n## Contributing\n\nPlease see the [contribution guidelines](https://github.com/websocket-client/websocket-client/blob/master/CONTRIBUTING.md)\n\n## Installation\n\nYou can use `pip install websocket-client` to install, or `pip install -e .`\nto install from a local copy of the code. This module is tested on Python 3.8+.\n\nThere are several optional dependencies that can be installed to enable\nspecific websocket-client features.\n- To install `python-socks` for proxy usage and `wsaccel` for a minor performance boost, use:\n `pip install websocket-client[optional]`\n- To install `websockets` to run unit tests using the local echo server, use:\n `pip install websocket-client[test]`\n- To install `Sphinx` and `sphinx_rtd_theme` to build project documentation, use:\n `pip install websocket-client[docs]`\n\nWhile not a strict dependency, [rel](https://github.com/bubbleboy14/registeredeventlistener)\nis useful when using `run_forever` with automatic reconnect. Install rel with `pip install rel`.\n\nFootnote: Some shells, such as zsh, require you to escape the `[` and `]` characters with a `\\`.\n\n## Usage Tips\n\nCheck out the documentation's FAQ for additional guidelines:\n[https://websocket-client.readthedocs.io/en/latest/faq.html](https://websocket-client.readthedocs.io/en/latest/faq.html)\n\nKnown issues with this library include lack of WebSocket Compression\nsupport (RFC 7692) and [minimal threading documentation/support](https://websocket-client.readthedocs.io/en/latest/threading.html).\n\n## Performance\n\nThe `send` and `validate_utf8` methods can sometimes be bottleneck.\nYou can disable UTF8 validation in this library (and receive a\nperformance enhancement) with the `skip_utf8_validation` parameter.\nIf you want to get better performance, install wsaccel. While\nwebsocket-client does not depend on wsaccel, it will be used if\navailable. wsaccel doubles the speed of UTF8 validation and\noffers a very minor 10% performance boost when masking the\npayload data as part of the `send` process. Numpy used to\nbe a suggested performance enhancement alternative, but\n[issue #687](https://github.com/websocket-client/websocket-client/issues/687)\nfound it didn't help.\n\n## Examples\n\nMany more examples are found in the\n[examples documentation](https://websocket-client.readthedocs.io/en/latest/examples.html).\n\n### Long-lived Connection\n\nMost real-world WebSockets situations involve longer-lived connections.\nThe WebSocketApp `run_forever` loop will automatically try to reconnect\nto an open WebSocket connection when a network\nconnection is lost if it is provided with:\n\n- a `dispatcher` argument (async dispatcher like rel or pyevent)\n- a non-zero `reconnect` argument (delay between disconnection and attempted reconnection)\n\n`run_forever` provides a variety of event-based connection controls\nusing callbacks like `on_message` and `on_error`.\n`run_forever` **does not automatically reconnect** if the server\ncloses the WebSocket gracefully (returning\n[a standard websocket close code](https://www.rfc-editor.org/rfc/rfc6455.html#section-7.4.1)).\n[This is the logic](https://github.com/websocket-client/websocket-client/pull/838#issuecomment-1228454826) behind the decision.\nCustomizing behavior when the server closes\nthe WebSocket should be handled in the `on_close` callback.\nThis example uses [rel](https://github.com/bubbleboy14/registeredeventlistener)\nfor the dispatcher to provide automatic reconnection.\n\n```python\nimport websocket\nimport _thread\nimport time\nimport rel\n\ndef on_message(ws, message):\n print(message)\n\ndef on_error(ws, error):\n print(error)\n\ndef on_close(ws, close_status_code, close_msg):\n print(\"### closed ###\")\n\ndef on_open(ws):\n print(\"Opened connection\")\n\nif __name__ == \"__main__\":\n websocket.enableTrace(True)\n ws = websocket.WebSocketApp(\"wss://api.gemini.com/v1/marketdata/BTCUSD\",\n on_open=on_open,\n on_message=on_message,\n on_error=on_error,\n on_close=on_close)\n\n ws.run_forever(dispatcher=rel, reconnect=5) # Set dispatcher to automatic reconnection, 5 second reconnect delay if connection closed unexpectedly\n rel.signal(2, rel.abort) # Keyboard Interrupt\n rel.dispatch()\n```\n\n### Short-lived Connection\n\nThis is if you want to communicate a short message and disconnect\nimmediately when done. For example, if you want to confirm that a WebSocket\nserver is running and responds properly to a specific request.\n\n```python\nfrom websocket import create_connection\n\nws = create_connection(\"ws://echo.websocket.events/\")\nprint(ws.recv())\nprint(\"Sending 'Hello, World'...\")\nws.send(\"Hello, World\")\nprint(\"Sent\")\nprint(\"Receiving...\")\nresult = ws.recv()\nprint(\"Received '%s'\" % result)\nws.close()\n```\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "WebSocket client for Python with low level API options",
"version": "1.8.0",
"project_urls": {
"Documentation": "https://websocket-client.readthedocs.io/",
"Download": "https://github.com/websocket-client/websocket-client/releases",
"Homepage": "https://github.com/websocket-client/websocket-client.git",
"Source": "https://github.com/websocket-client/websocket-client/"
},
"split_keywords": [
"websockets",
"client"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "5a8444687a29792a70e111c5c477230a72c4b957d88d16141199bf9acb7537a3",
"md5": "231ed16db351208bcbe6defc20f466ad",
"sha256": "17b44cc997f5c498e809b22cdf2d9c7a9e71c02c8cc2b6c56e7c2d1239bfa526"
},
"downloads": -1,
"filename": "websocket_client-1.8.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "231ed16db351208bcbe6defc20f466ad",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 58826,
"upload_time": "2024-04-23T22:16:14",
"upload_time_iso_8601": "2024-04-23T22:16:14.422737Z",
"url": "https://files.pythonhosted.org/packages/5a/84/44687a29792a70e111c5c477230a72c4b957d88d16141199bf9acb7537a3/websocket_client-1.8.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "e630fba0d96b4b5fbf5948ed3f4681f7da2f9f64512e1d303f94b4cc174c24a5",
"md5": "9cffbda9eefb0a17e9c4cda3b7884493",
"sha256": "3239df9f44da632f96012472805d40a23281a991027ce11d2f45a6f24ac4c3da"
},
"downloads": -1,
"filename": "websocket_client-1.8.0.tar.gz",
"has_sig": false,
"md5_digest": "9cffbda9eefb0a17e9c4cda3b7884493",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 54648,
"upload_time": "2024-04-23T22:16:16",
"upload_time_iso_8601": "2024-04-23T22:16:16.976512Z",
"url": "https://files.pythonhosted.org/packages/e6/30/fba0d96b4b5fbf5948ed3f4681f7da2f9f64512e1d303f94b4cc174c24a5/websocket_client-1.8.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-23 22:16:16",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "websocket-client",
"github_project": "websocket-client",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"lcname": "websocket-client"
}
JSON
