README.rst
1Flask-Sockets
2=============
3
4Elegant WebSockets for your Flask apps.
5
6.. image:: http://farm4.staticflickr.com/3689/9755961864_577e32a106_c.jpg
7
8
9Simple usage of ``route`` decorator:
10
11.. code-block:: python
12
13 from flask import Flask
14 from flask_sockets import Sockets
15
16
17 app = Flask(__name__)
18 sockets = Sockets(app)
19
20
21 @sockets.route('/echo')
22 def echo_socket(ws):
23 while not ws.closed:
24 message = ws.receive()
25 ws.send(message)
26
27
28 @app.route('/')
29 def hello():
30 return 'Hello World!'
31
32
33 if __name__ == "__main__":
34 from gevent import pywsgi
35 from geventwebsocket.handler import WebSocketHandler
36 server = pywsgi.WSGIServer(('', 5000), app, handler_class=WebSocketHandler)
37 server.serve_forever()
38
39
40Usage of `Flask blueprints`_:
41
42.. code-block:: python
43
44 from flask import Flask, Blueprint
45 from flask_sockets import Sockets
46
47
48 html = Blueprint(r'html', __name__)
49 ws = Blueprint(r'ws', __name__)
50
51
52 @html.route('/')
53 def hello():
54 return 'Hello World!'
55
56 @ws.route('/echo')
57 def echo_socket(socket):
58 while not socket.closed:
59 message = socket.receive()
60 socket.send(message)
61
62
63 app = Flask(__name__)
64 sockets = Sockets(app)
65
66 app.register_blueprint(html, url_prefix=r'/')
67 sockets.register_blueprint(ws, url_prefix=r'/')
68
69
70 if __name__ == "__main__":
71 from gevent import pywsgi
72 from geventwebsocket.handler import WebSocketHandler
73 server = pywsgi.WSGIServer(('', 5000), app, handler_class=WebSocketHandler)
74 server.serve_forever()
75
76
77Serving WebSockets in Python was really difficult. Now it's not.
78
79
80Installation
81------------
82
83To install Flask-Sockets, simply::
84
85 $ pip install Flask-Sockets
86
87
88Deployment
89----------
90
91A custom Gunicorn worker is included to make deployment as friendly as possible::
92
93 $ gunicorn -k flask_sockets.worker hello:app
94
95Production services are provided by `gevent <http://www.gevent.org>`_
96and `gevent-websocket <https://bitbucket.org/noppo/gevent-websocket>`_.
97
98The given example can run standalone as main.
99
100Anything that inserts ``wsgi.websocket`` into the WSGI environ is
101supported, but gevent-websocket is recommended.
102
103
104Development / Testing
105---------------------
106
107Because the Werkzeug development server cannot provide the WSGI environ with
108a websocket interface, it is not possible to run a Flask app using the standard
109``app.run()``.
110
111If you try to, Flask will still try to serve on all the specified routes, and
112throw a ``KeyError`` whenever a client tries to connect to a websocket route.
113
114Instead, just use the included gunicorn worker (explained above), or anything that
115can insert ``wsgi.websocket`` into the WSGI environ.
116
117
118
119WebSocket Interface
120-------------------
121
122The websocket interface that is passed into your routes is
123`provided by gevent-websocket <https://bitbucket.org/noppo/gevent-websocket>`_.
124The basic methods are fairly straightforward —
125``send``, ``receive``, ``send_frame``, and ``close``.
126
127
128Release History
129---------------
130
131v0.2.1
132~~~~~~
133
134- Add support of `Flask blueprints`_.
135
136
137v0.2.0
138~~~~~~
139
140- Add request context into the socket handler.
141- Fallback to Flask logic if websocket environment is not available.
142- Use Flask routing to allow for variables in URL
143
144v0.1.0
145~~~~~~
146
147- Initial release.
148
149
150.. _Flask blueprints: http://flask.pocoo.org/docs/latest/blueprints/
151
152
153
154
