Flask-uWSGI-WebSocket

High-performance WebSockets for your Flask apps powered by uWSGI. Low-level uWSGI WebSocket APIaccess and flexible high-level abstractions for building complex WebSocketapplications with Flask. Supports several different concurrency modelsincluding Gevent. Inspired by Flask-Sockets.

from flask import Flask
from flask_uwsgi_websocket import GeventWebSocket

app = Flask(__name__)
websocket = GeventWebSocket(app)

@websocket.route('/echo')
def echo(ws):
    while True:
        msg = ws.receive()
        ws.send(msg)

if __name__ == '__main__':
    app.run(gevent=100)

Installation

Preferred method of installation is via pip:

$ pip install Flask-uWSGI-WebSocket

Installing uWSGI

Of course you'll also need uWSGI (with SSL support, at minimum). It can also beinstalled with pip:

$ pip install uwsgi

If that fails or you need to enable the asyncio plugin, read on.

uWSGI on Mac OS X

On some versions of Mac OS X, OpenSSL headers are no longer included. If youuse Homebrew, install OpenSSL and ensure they are available:

$ brew install openssl && brew link openssl --force

This should ensure pip can install uWSGI:

$ LDFLAGS="-L/usr/local/lib" pip install uwsgi --no-use-wheel

If you plan to use the asyncio plugin, you'll need to ensure that it's enabledwhen uWSGI is compiled. You can use UWSGI_PROFILE to do this. With Homebrew Python 3.5 installed:

$ LDFLAGS="-L/usr/local/lib" CFLAGS="-I/usr/local/include/python3.5m" UWSGI_PROFLILE="asyncio" pip3 install uwsgi --no-use-wheel

uWSGI on Linux

If your Linux distribution includes uWSGI with specific plugins, that is manytimes your best bet. If that fails or you'd prefer to compile uWSGI yourself,you'll need to ensure that the requisite build tools, OpenSSL headers, etc areinstalled:

$ apt-get install build-essential libssl-dev python3-dev python3-venv

According to the uWSGI asyncio docs, UWSGI_PROFILEand greenlet.h location should be specified.

If you are installing uWSGI into a virtualenv, the process is:

$ python3 -m venv pyvenv
$ . pyvenv/bin/activate
(pyvenv)$ pip install greenlet

Now, greenlet.h should be available at $VIRTUAL_ENV/include/site/python3.5. To build with pip:

$ mkdir -p $VIRTUAL_ENV/include/site/python3.5/greenlet
$ ln -s ../greenlet.h $VIRTUAL_ENV/include/site/python3.5/greenlet/
$ CFLAGS="-I$VIRTUAL_ENV/include/site/python3.5" UWSGI_PROFILE="asyncio" pip install uwsgi --no-use-wheel

Deployment

You can use uWSGI's built-in HTTP router to get up and running quickly:

$ uwsgi --master --http :8080 --http-websockets --wsgi echo:app

...which is what app.run does after wrapping your Flask app:

app.run(debug=True, host='localhost', port=8080, master=true, processes=8)

uWSGI supports several concurrency models, in particular it has nice supportfor Gevent. If you want to use Gevent, importflask_uwsgi_websocket.GeventWebSocket and configure uWSGI to use thegevent loop engine:

$ uwsgi --master --http :8080 --http-websockets --gevent 100 --wsgi echo:app

...or:

app.run(debug=True, gevent=100)

Note that you cannot use multiple threads with gevent loop engine.

To enable asyncio instead:

$ uwsgi --master --http :5000 --http-websockets --asyncio 100 --greenlet --wsgi chat:app

...or:

app.run(debug=True, asyncio=100, greenlet=True)

For production you'll probably want to run uWSGI behind Haproxy or Nginx,instead of using the built-int HTTP router. Explore the uWSGI documentation to learn moreabout the various concurrency and deployment options.

Development

It's possible to take advantage of Flask's interactive debugger by installingWerkzeug's DebuggedApplication middleware:

from werkzeug.debug import DebuggedApplication
app.wsgi_app = DebuggedApplication(app.wsgi_app, True)

...and running uWSGI with only a single worker:

$ uwsgi --master --http :8080 --http-websockets --wsgi-file --workers 1 --threads 8 app.py

If you use app.run(debug=True) or export FLASK_UWSGI_DEBUG,Flask-uWSGI-Websocket will do this automatically for you.

Examples

There are several examples available here.

API

WebSocket

Applies WebSocketMiddleware to your Flask App, allowing you to decorateroutes with the route method, turning them into WebSocket handlers.

Additionally monkey-patches app.run, to run your app directly in uWSGI.

route(url)

run(debug, host, port, **kwargs)**kwargs are passed to uWSGI as command line arguments.

WebSocketMiddleware

WebSocket Middleware which automatically performs WebSocket handshake andpasses WebSocketClient instances to your route.

WebSocketClient

Exposes the uWSGI WebSocket API.

recv() (alias WebSocket.receive())

recv_nb()

send(msg)

send_binary(msg)

recv_nb()

send_from_sharedarea(id, pos)

send_binary_from_sharedarea(id, pos)

GeventWebSocket

Fancier WebSocket abstraction that takes advantage of Gevent loop engine.Requires uWSGI to be run with --uwsgi option.

GeventWebSocketMiddleware

Automatically performs WebSocket handshake and passes aGeventWebSocketClient instance to your route.

GeventWebSocketClient

WebSocket client abstraction with fully non-blocking methods.

receive()

send(msg)

close()

connected

AsyncioWebSocket

Fancier WebSocket abstraction that takes advantage of Asyncio loop engine.Requires uWSGI to be run with --asyncio and --greenlet option.

AsyncioWebSocketMiddleware

Automatically performs WebSocket handshake and passes a AsyncioWebSocketClient instance to your route.

AsyncioWebSocketClient

WebSocket client abstraction with asyncio coroutines.

coroutine a_recv() (alias receive(), recv())

coroutine a_send(msg) (alias send())

recv_nb() (should be useless)

send_nb() (should be useless)

close()

connected

Advanced Usage

Normally websocket routes happen outside of the normal request context. You canget a request context in your websocket handler by usingapp.request_context:

app = Flask(__name__)
ws = GeventWebSocket(app)

@ws.route('/websocket')
def websocket(ws):
    with app.request_context(ws.environ):
        print request.args