File: README.rst

package info (click to toggle)
python-flask-sockets 0.2.1-4
  • links: PTS, VCS
  • area: main
  • in suites: bookworm, bullseye, sid
  • size: 88 kB
  • sloc: python: 94; makefile: 4
file content (153 lines) | stat: -rw-r--r-- 3,437 bytes parent folder | download | duplicates (4)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
Flask-Sockets
=============

Elegant WebSockets for your Flask apps.

.. image:: http://farm4.staticflickr.com/3689/9755961864_577e32a106_c.jpg


Simple usage of ``route`` decorator:

.. code-block:: python

    from flask import Flask
    from flask_sockets import Sockets


    app = Flask(__name__)
    sockets = Sockets(app)


    @sockets.route('/echo')
    def echo_socket(ws):
        while not ws.closed:
            message = ws.receive()
            ws.send(message)


    @app.route('/')
    def hello():
        return 'Hello World!'


    if __name__ == "__main__":
        from gevent import pywsgi
        from geventwebsocket.handler import WebSocketHandler
        server = pywsgi.WSGIServer(('', 5000), app, handler_class=WebSocketHandler)
        server.serve_forever()


Usage of `Flask blueprints`_:

.. code-block:: python

    from flask import Flask, Blueprint
    from flask_sockets import Sockets


    html = Blueprint(r'html', __name__)
    ws = Blueprint(r'ws', __name__)


    @html.route('/')
    def hello():
        return 'Hello World!'

    @ws.route('/echo')
    def echo_socket(socket):
        while not socket.closed:
            message = socket.receive()
            socket.send(message)


    app = Flask(__name__)
    sockets = Sockets(app)

    app.register_blueprint(html, url_prefix=r'/')
    sockets.register_blueprint(ws, url_prefix=r'/')


    if __name__ == "__main__":
        from gevent import pywsgi
        from geventwebsocket.handler import WebSocketHandler
        server = pywsgi.WSGIServer(('', 5000), app, handler_class=WebSocketHandler)
        server.serve_forever()


Serving WebSockets in Python was really difficult. Now it's not.


Installation
------------

To install Flask-Sockets, simply::

    $ pip install Flask-Sockets


Deployment
----------

A custom Gunicorn worker is included to make deployment as friendly as possible::

    $ gunicorn -k flask_sockets.worker hello:app

Production services are provided by `gevent <http://www.gevent.org>`_
and `gevent-websocket <https://bitbucket.org/noppo/gevent-websocket>`_.

The given example can run standalone as main.

Anything that inserts ``wsgi.websocket`` into the WSGI environ is
supported, but gevent-websocket is recommended.


Development / Testing
---------------------

Because the Werkzeug development server cannot provide the WSGI environ with
a websocket interface, it is not possible to run a Flask app using the standard
``app.run()``.

If you try to, Flask will still try to serve on all the specified routes, and
throw a ``KeyError`` whenever a client tries to connect to a websocket route.

Instead, just use the included gunicorn worker (explained above), or anything that
can insert ``wsgi.websocket`` into the WSGI environ.



WebSocket Interface
-------------------

The websocket interface that is passed into your routes is
`provided by gevent-websocket <https://bitbucket.org/noppo/gevent-websocket>`_.
The basic methods are fairly straightforward — 
``send``, ``receive``, ``send_frame``, and ``close``.


Release History
---------------

v0.2.1
~~~~~~

- Add support of `Flask blueprints`_.


v0.2.0
~~~~~~

- Add request context into the socket handler.
- Fallback to Flask logic if websocket environment is not available.
- Use Flask routing to allow for variables in URL

v0.1.0
~~~~~~

- Initial release.


.. _Flask blueprints: http://flask.pocoo.org/docs/latest/blueprints/