https://github.com/purplesyringa/gevent-ws
A free MIT-licensed websocket library for gevent
https://github.com/purplesyringa/gevent-ws
gevent server websocket websocket-server
Last synced: about 1 year ago
JSON representation
A free MIT-licensed websocket library for gevent
- Host: GitHub
- URL: https://github.com/purplesyringa/gevent-ws
- Owner: purplesyringa
- License: mit
- Created: 2020-02-24T14:37:25.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2020-05-11T17:32:16.000Z (about 6 years ago)
- Last Synced: 2025-04-02T19:04:19.548Z (about 1 year ago)
- Topics: gevent, server, websocket, websocket-server
- Language: Python
- Size: 23.4 KB
- Stars: 3
- Watchers: 1
- Forks: 4
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# gevent-ws
A fast, MIT-licensed alternative to the abandoned non-free (as in freedom) [gevent-websocket](https://gitlab.com/noppo/gevent-websocket).
## Why?
It's MIT-licensed, so it can be included to almost all software (both open-source and closed-source) without any licensing issues, as opposed to *gevent-websocket*. And it's several times faster!
## Installation
*gevent-ws* can be installed from PyPI and GitHub.
### PyPI
```shell
$ pip3 install gevent-ws
```
### GitHub
```shell
$ git clone https://github.com/imachug/gevent-ws.git
$ cd gevent-ws
$ python3 setup.py install
```
## Example
### A simple echo server
```python3
from gevent.pywsgi import WSGIServer
from gevent_ws import WebSocketHandler
def app(env, start_response):
ws = env["wsgi.websocket"]
while True:
msg = ws.receive()
if msg is None:
break
ws.send(msg)
return [b"Bye"]
server = WSGIServer(("", 8080), app, handler_class=WebSocketHandler)
server.serve_forever()
```
### Both HTTP and websocket on a single port
```python3
from gevent.pywsgi import WSGIServer
from gevent_ws import WebSocketHandler
def app(env, start_response):
if "wsgi.websocket" in env:
ws = env["wsgi.websocket"]
while True:
msg = ws.receive()
if msg is None:
break
ws.send(msg)
return [b"Bye"]
else:
start_response("200 OK", [
("Content-Type", "text/html, charset=utf-8")
])
return [
b"""
const ws = new WebSocket("ws://127.0.0.1:8080/");
ws.onopen = () => {
ws.send("Hello, world!");
};
ws.onmessage = e => {
ws.send(e.data);
};
"""
]
server = WSGIServer(("", 8080), app, handler_class=WebSocketHandler)
server.serve_forever()
```
## Docs
### `gevent_ws.WebSocketHandler`
The main class. Pass it to `gevent.pywsgi.WSGIServer` as `handler_class`.
### `gevent_ws.WebSocket`
You get this object by accessing `wsgi.websocket` property of the environment object. If it exists, it's a websocket connection; if it doesn't, it's an HTTP request. You can use `"wsgi.websocket" in env` to check this and route the request correctly.
### `gevent_ws.WebSocket.receive()`
Waits for a message and returns it, either as `str` or `bytes`. Blocks. May return `None` if the connection is closed or an `OSError` if the socket can't be read from.
### `gevent_ws.WebSocket.receive_nowait()`
Returns the message if it's available (the format is the same as in `receive()`) or `None` if no message is in the queue. May return `None` or raise `OSError` (see `receive()`).
### `gevent_ws.WebSocket.send(message)`
Sends a message to the other party. `message` can be either `str` or `bytes`. May raise `EOFError` if the connection is closed or `OSError` if the message can't be sent for some other reason.
### `gevent_ws.WebSocket.close(status=1000)`
Closes the websocket. Status `1000` (the default one) means that the connection is closed cleanly. Check [RFC](https://tools.ietf.org/html/rfc6455#section-7.4) for more status codes.
### `gevent_ws.WebSocket.set_max_message_length(length)`
Set maximum incoming message size (in bytes). 10 MiB is the default value.
### `gevent_ws.WebSocket.closed`
A boolean showing whether the connection is closed (by any of the two parties) or is being closed.
### `gevent_ws.WebSocket.status`
The close status code sent by the other party. `None` if the socket was closed by the client, the server didn't return the error code or the connection was aborted abnormally.