Miguel Grinberg
6 years ago
12 changed files with 822 additions and 430 deletions
@ -0,0 +1,290 @@ |
|||
The Socket.IO Client |
|||
==================== |
|||
|
|||
This package contains two Socket.IO clients: |
|||
|
|||
- The :func:`socketio.Client` class creates a client compatible with the |
|||
standard Python library. |
|||
- The :func:`socketio.AsyncClient` class creates a client compatible with |
|||
the ``asyncio`` package. |
|||
|
|||
The methods in the two clients are the same, with the only difference that in |
|||
the ``asyncio`` client most methods are implemented as coroutines. |
|||
|
|||
Installation |
|||
------------ |
|||
|
|||
To install the standard Python client along with its dependencies, use the |
|||
following command:: |
|||
|
|||
pip install "python-socketio[client]" |
|||
|
|||
If instead you plan on using the ``asyncio`` client, then use this:: |
|||
|
|||
pip install "python-socketio[asyncio_client]" |
|||
|
|||
Creating a Client Instance |
|||
-------------------------- |
|||
|
|||
To instantiate an Socket.IO client, simply create an instance of the |
|||
appropriate client class:: |
|||
|
|||
import socketio |
|||
|
|||
# standard Python |
|||
sio = socketio.Client() |
|||
|
|||
# asyncio |
|||
sio = socketio.AsyncClient() |
|||
|
|||
Defining Event Handlers |
|||
----------------------- |
|||
|
|||
To responds to events triggered by the connection or the server, event Handler |
|||
functions must be defined using the ``on`` decorator:: |
|||
|
|||
@sio.on('connect') |
|||
def on_connect(): |
|||
print('I'm connected!') |
|||
|
|||
@sio.on('message') |
|||
def on_message(data): |
|||
print('I received a message!') |
|||
|
|||
@sio.on('my message') |
|||
def on_message(data): |
|||
print('I received a custom message!') |
|||
|
|||
@sio.on('disconnect') |
|||
def on_disconnect(): |
|||
print('I'm disconnected!') |
|||
|
|||
For the ``asyncio`` server, event handlers can be regular functions as above, |
|||
or can also be coroutines:: |
|||
|
|||
@sio.on('message') |
|||
async def on_message(data): |
|||
print('I received a message!') |
|||
|
|||
The argument given to the ``on`` decorator is the event name. The predefined |
|||
events that are supported are ``connect``, ``message`` and ``disconnect``. The |
|||
application can define any other desired event names. |
|||
|
|||
Note that the ``disconnect`` handler is invoked for application initiated |
|||
disconnects, server initiated disconnects, or accidental disconnects, for |
|||
example due to networking failures. In the case of an accidental disconnection, |
|||
the client is going to attempt to reconnect immediately after invoking the |
|||
disconnect handler. As soon as the connection is re-established the connect |
|||
handler will be invoked once again. |
|||
|
|||
The ``data`` argument passed to the ``'message'`` and custom event Handlers |
|||
contains application-specific data provided by the server. |
|||
|
|||
Connecting to a Server |
|||
---------------------- |
|||
|
|||
The connection to a server is established by calling the ``connect()`` |
|||
method:: |
|||
|
|||
sio.connect('http://localhost:5000') |
|||
|
|||
In the case of the ``asyncio`` client, the method is a coroutine:: |
|||
|
|||
await sio.connect('http://localhost:5000') |
|||
|
|||
Emitting Events |
|||
--------------- |
|||
|
|||
The client can emit an event to the server using the ``emit()`` method:: |
|||
|
|||
sio.emit('my message', {'foo': 'bar'}) |
|||
|
|||
Or in the case of ``asyncio``, as a coroutine:: |
|||
|
|||
await sio.emit('my message', {'foo': 'bar'}) |
|||
|
|||
The single argument provided to the method is the data that is passed on |
|||
to the server. The data can be of type ``str``, ``bytes``, ``dict`` or |
|||
``list``. The data included inside dictionaries and lists is also |
|||
constrained to these types. |
|||
|
|||
The ``emit()`` method can be invoked inside an event handler as a response |
|||
to a server event, or in any other part of the application, including in |
|||
background tasks. |
|||
|
|||
For convenience, a ``send()`` method is also provided. This method accepts |
|||
a data element as its only argument, and emits the standard ``message`` |
|||
event with it:: |
|||
|
|||
sio.send('some data') |
|||
|
|||
In the case of ``asyncio``, ``send()`` is a coroutine:: |
|||
|
|||
await sio.send('some data') |
|||
|
|||
Event Callbacks |
|||
--------------- |
|||
|
|||
When a server emits an event to a client, it can optionally provide a |
|||
callback function, to be invoked as a way of acknowledgment that the server |
|||
has processed the event. While this is entirely managed by the server, the |
|||
client can provide a list of return values that are to be passed on to the |
|||
callback function set up by the server. This is achieves simply by returning |
|||
the desired values from the handler function:: |
|||
|
|||
@sio.on('my event', namespace='/chat') |
|||
def my_event_handler(sid, data): |
|||
# handle the message |
|||
return "OK", 123 |
|||
|
|||
Likewise, the client can request a callback function to be invoked after the |
|||
server has processed an event. The :func:`socketio.Server.emit` method has an |
|||
optional ``callback`` argument that can be set to a callable. If this |
|||
argument is given, the callable will be invoked after the server has processed |
|||
the event, and any values returned by the server handler will be passed as |
|||
arguments to this function. |
|||
|
|||
Namespaces |
|||
---------- |
|||
|
|||
The Socket.IO protocol supports multiple logical connections, all multiplexed |
|||
on the same physical connection. Clients can open multiple connections by |
|||
specifying a different *namespace* on each. Namespaces use a path syntax |
|||
starting with a forward slash. A list of namespaces can be given by the client |
|||
in the ``connect()`` call. For example, this example creates two logical |
|||
connections, the default one plus a second connection under the ``/chat`` |
|||
namespace:: |
|||
|
|||
sio.connect('http://localhost:5000', namespaces=['/chat']) |
|||
|
|||
To define event handlers on a namespace, the ``namespace`` argument must be |
|||
added to the ``on`` decorator:: |
|||
|
|||
@sio.on('connect', namespace='/chat') |
|||
def on_connect(): |
|||
print('I'm connected to the /chat namespace!') |
|||
|
|||
Likewise, the client can emit an event to the server on a namespace by |
|||
providing its in the ``emit()`` call:: |
|||
|
|||
sio.emit('my message', {'foo': 'bar'}, namespace='/chat') |
|||
|
|||
If the ``namespaces`` argument of the ``connect()`` call isn't given, any |
|||
namespaces used in event handlers are automatically connected. |
|||
|
|||
Class-Based Namespaces |
|||
---------------------- |
|||
|
|||
As an alternative to the decorator-based event handlers, the event handlers |
|||
that belong to a namespace can be created as methods of a subclass of |
|||
:class:`socketio.ClientNamespace`:: |
|||
|
|||
class MyCustomNamespace(socketio.ClientNamespace): |
|||
def on_connect(self): |
|||
pass |
|||
|
|||
def on_disconnect(self): |
|||
pass |
|||
|
|||
def on_my_event(self, data): |
|||
self.emit('my_response', data) |
|||
|
|||
sio.register_namespace(MyCustomNamespace('/chat')) |
|||
|
|||
For asyncio based severs, namespaces must inherit from |
|||
:class:`socketio.AsyncClientNamespace`, and can define event handlers as |
|||
coroutines if desired:: |
|||
|
|||
class MyCustomNamespace(socketio.AsyncClientNamespace): |
|||
def on_connect(self): |
|||
pass |
|||
|
|||
def on_disconnect(self): |
|||
pass |
|||
|
|||
async def on_my_event(self, data): |
|||
await self.emit('my_response', data) |
|||
|
|||
sio.register_namespace(MyCustomNamespace('/chat')) |
|||
|
|||
When class-based namespaces are used, any events received by the client are |
|||
dispatched to a method named as the event name with the ``on_`` prefix. For |
|||
example, event ``my_event`` will be handled by a method named ``on_my_event``. |
|||
If an event is received for which there is no corresponding method defined in |
|||
the namespace class, then the event is ignored. All event names used in |
|||
class-based namespaces must use characters that are legal in method names. |
|||
|
|||
As a convenience to methods defined in a class-based namespace, the namespace |
|||
instance includes versions of several of the methods in the |
|||
:class:`socketio.Client` and :class:`socketio.AsyncClient` classes that |
|||
default to the proper namespace when the ``namespace`` argument is not given. |
|||
|
|||
In the case that an event has a handler in a class-based namespace, and also a |
|||
decorator-based function handler, only the standalone function handler is |
|||
invoked. |
|||
|
|||
Disconnecting from the Server |
|||
----------------------------- |
|||
|
|||
At any time the client can request to be disconnected from the server by |
|||
invoking the ``disconnect()`` method:: |
|||
|
|||
sio.disconnect() |
|||
|
|||
For the ``asyncio`` client this is a coroutine:: |
|||
|
|||
await sio.disconnect() |
|||
|
|||
Managing Background Tasks |
|||
------------------------- |
|||
|
|||
When a client connection to the server is established, a few background |
|||
tasks will be spawned to keep the connection alive and handle incoming |
|||
events. The application running on the main thread is free to do any |
|||
work, as this is not going to prevent the functioning of the Socket.IO |
|||
client. |
|||
|
|||
If the application does not have anything to do in the main thread and |
|||
just wants to wait until the connection with the server ends, it can call |
|||
the ``wait()`` method:: |
|||
|
|||
sio.wait() |
|||
|
|||
Or in the ``asyncio`` version:: |
|||
|
|||
await sio.wait() |
|||
|
|||
For the convenience of the application, a helper function is provided to |
|||
start a custom background task:: |
|||
|
|||
def my_background_task(my_argument) |
|||
# do some background work here! |
|||
pass |
|||
|
|||
sio.start_background_task(my_background_task, 123) |
|||
|
|||
The arguments passed to this method are the background function and any |
|||
positional or keyword arguments to invoke the function with. |
|||
|
|||
Here is the ``asyncio`` version:: |
|||
|
|||
async def my_background_task(my_argument) |
|||
# do some background work here! |
|||
pass |
|||
|
|||
sio.start_background_task(my_background_task, 123) |
|||
|
|||
Note that this function is not a coroutine, since it does not wait for the |
|||
background function to end. The background function must be a coroutine. |
|||
|
|||
The ``sleep()`` method is a second convenince function that is provided for |
|||
the benefit of applications working with background tasks of their own:: |
|||
|
|||
sio.sleep(2) |
|||
|
|||
Or for ``asyncio``:: |
|||
|
|||
await sio.sleep(2) |
|||
|
|||
The single argument passed to the method is the number of seconds to sleep |
|||
for. |
|||
@ -1,277 +0,0 @@ |
|||
Deployment |
|||
========== |
|||
|
|||
The following sections describe a variety of deployment strategies for |
|||
Socket.IO servers. |
|||
|
|||
aiohttp |
|||
------- |
|||
|
|||
`Aiohttp <http://aiohttp.readthedocs.io/>`_ is a framework with support for HTTP |
|||
and WebSocket, based on asyncio. Support for this framework is limited to Python |
|||
3.5 and newer. |
|||
|
|||
Instances of class ``socketio.AsyncServer`` will automatically use aiohttp |
|||
for asynchronous operations if the library is installed. To request its use |
|||
explicitly, the ``async_mode`` option can be given in the constructor:: |
|||
|
|||
sio = socketio.AsyncServer(async_mode='aiohttp') |
|||
|
|||
A server configured for aiohttp must be attached to an existing application:: |
|||
|
|||
app = web.Application() |
|||
sio.attach(app) |
|||
|
|||
The aiohttp application can define regular routes that will coexist with the |
|||
Socket.IO server. A typical pattern is to add routes that serve a client |
|||
application and any associated static files. |
|||
|
|||
The aiohttp application is then executed in the usual manner:: |
|||
|
|||
if __name__ == '__main__': |
|||
web.run_app(app) |
|||
|
|||
Tornado |
|||
------- |
|||
|
|||
`Tornado <http://www.tornadoweb.org//>`_ is a web framework with support |
|||
for HTTP and WebSocket. Support for this framework requires Python 3.5 and |
|||
newer. Only Tornado version 5 and newer are supported, thanks to its tight |
|||
integration with asyncio. |
|||
|
|||
Instances of class ``socketio.AsyncServer`` will automatically use tornado |
|||
for asynchronous operations if the library is installed. To request its use |
|||
explicitly, the ``async_mode`` option can be given in the constructor:: |
|||
|
|||
sio = socketio.AsyncServer(async_mode='tornado') |
|||
|
|||
A server configured for tornado must include a request handler for |
|||
Engine.IO:: |
|||
|
|||
app = tornado.web.Application( |
|||
[ |
|||
(r"/socketio.io/", socketio.get_tornado_handler(sio)), |
|||
], |
|||
# ... other application options |
|||
) |
|||
|
|||
The tornado application can define other routes that will coexist with the |
|||
Socket.IO server. A typical pattern is to add routes that serve a client |
|||
application and any associated static files. |
|||
|
|||
The tornado application is then executed in the usual manner:: |
|||
|
|||
app.listen(port) |
|||
tornado.ioloop.IOLoop.current().start() |
|||
|
|||
Sanic |
|||
----- |
|||
|
|||
`Sanic <http://sanic.readthedocs.io/>`_ is a very efficient asynchronous web |
|||
server for Python 3.5 and newer. |
|||
|
|||
Instances of class ``socketio.AsyncServer`` will automatically use Sanic for |
|||
asynchronous operations if the framework is installed. To request its use |
|||
explicitly, the ``async_mode`` option can be given in the constructor:: |
|||
|
|||
sio = socketio.AsyncServer(async_mode='sanic') |
|||
|
|||
A server configured for aiohttp must be attached to an existing application:: |
|||
|
|||
app = web.Application() |
|||
sio.attach(app) |
|||
|
|||
The Sanic application can define regular routes that will coexist with the |
|||
Socket.IO server. A typical pattern is to add routes that serve a client |
|||
application and any associated static files. |
|||
|
|||
The Sanic application is then executed in the usual manner:: |
|||
|
|||
if __name__ == '__main__': |
|||
app.run() |
|||
|
|||
Uvicorn, Daphne, and other ASGI servers |
|||
--------------------------------------- |
|||
|
|||
The ``socketio.ASGIApp`` class is an ASGI compatible application that can |
|||
forward Socket.IO traffic to an ``socketio.AsyncServer`` instance:: |
|||
|
|||
sio = socketio.AsyncServer(async_mode='asgi') |
|||
app = socketio.ASGIApp(sio) |
|||
|
|||
The application can then be deployed with any ASGI compatible web server. |
|||
|
|||
Eventlet |
|||
-------- |
|||
|
|||
`Eventlet <http://eventlet.net/>`_ is a high performance concurrent networking |
|||
library for Python 2 and 3 that uses coroutines, enabling code to be written in |
|||
the same style used with the blocking standard library functions. An Socket.IO |
|||
server deployed with eventlet has access to the long-polling and WebSocket |
|||
transports. |
|||
|
|||
Instances of class ``socketio.Server`` will automatically use eventlet for |
|||
asynchronous operations if the library is installed. To request its use |
|||
explicitly, the ``async_mode`` option can be given in the constructor:: |
|||
|
|||
sio = socketio.Server(async_mode='eventlet') |
|||
|
|||
A server configured for eventlet is deployed as a regular WSGI application, |
|||
using the provided ``socketio.Middleware``:: |
|||
|
|||
app = socketio.Middleware(sio) |
|||
import eventlet |
|||
eventlet.wsgi.server(eventlet.listen(('', 8000)), app) |
|||
|
|||
Using Gunicorn with Eventlet |
|||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
|||
|
|||
An alternative to running the eventlet WSGI server as above is to use |
|||
`gunicorn <gunicorn.org>`_, a fully featured pure Python web server. The |
|||
command to launch the application under gunicorn is shown below:: |
|||
|
|||
$ gunicorn -k eventlet -w 1 module:app |
|||
|
|||
Due to limitations in its load balancing algorithm, gunicorn can only be used |
|||
with one worker process, so the ``-w`` option cannot be set to a value higher |
|||
than 1. A single eventlet worker can handle a large number of concurrent |
|||
clients, each handled by a greenlet. |
|||
|
|||
Eventlet provides a ``monkey_patch()`` function that replaces all the blocking |
|||
functions in the standard library with equivalent asynchronous versions. While |
|||
python-socketio does not require monkey patching, other libraries such as |
|||
database drivers are likely to require it. |
|||
|
|||
Gevent |
|||
------ |
|||
|
|||
`Gevent <http://gevent.org/>`_ is another asynchronous framework based on |
|||
coroutines, very similar to eventlet. An Socket.IO server deployed with |
|||
gevent has access to the long-polling transport. If project |
|||
`gevent-websocket <https://bitbucket.org/Jeffrey/gevent-websocket/>`_ is |
|||
installed, the WebSocket transport is also available. |
|||
|
|||
Instances of class ``socketio.Server`` will automatically use gevent for |
|||
asynchronous operations if the library is installed and eventlet is not |
|||
installed. To request gevent to be selected explicitly, the ``async_mode`` |
|||
option can be given in the constructor:: |
|||
|
|||
sio = socketio.Server(async_mode='gevent') |
|||
|
|||
A server configured for gevent is deployed as a regular WSGI application, |
|||
using the provided ``socketio.Middleware``:: |
|||
|
|||
app = socketio.Middleware(sio) |
|||
from gevent import pywsgi |
|||
pywsgi.WSGIServer(('', 8000), app).serve_forever() |
|||
|
|||
If the WebSocket transport is installed, then the server must be started as |
|||
follows:: |
|||
|
|||
from gevent import pywsgi |
|||
from geventwebsocket.handler import WebSocketHandler |
|||
app = socketio.Middleware(sio) |
|||
pywsgi.WSGIServer(('', 8000), app, |
|||
handler_class=WebSocketHandler).serve_forever() |
|||
|
|||
Using Gunicorn with Gevent |
|||
~~~~~~~~~~~~~~~~~~~~~~~~~~ |
|||
|
|||
An alternative to running the gevent WSGI server as above is to use |
|||
`gunicorn <gunicorn.org>`_, a fully featured pure Python web server. The |
|||
command to launch the application under gunicorn is shown below:: |
|||
|
|||
$ gunicorn -k gevent -w 1 module:app |
|||
|
|||
Or to include WebSocket:: |
|||
|
|||
$ gunicorn -k geventwebsocket.gunicorn.workers.GeventWebSocketWorker -w 1 module: app |
|||
|
|||
Same as with eventlet, due to limitations in its load balancing algorithm, |
|||
gunicorn can only be used with one worker process, so the ``-w`` option cannot |
|||
be higher than 1. A single gevent worker can handle a large number of |
|||
concurrent clients through the use of greenlets. |
|||
|
|||
Gevent provides a ``monkey_patch()`` function that replaces all the blocking |
|||
functions in the standard library with equivalent asynchronous versions. While |
|||
python-socketio does not require monkey patching, other libraries such as |
|||
database drivers are likely to require it. |
|||
|
|||
uWSGI |
|||
----- |
|||
|
|||
When using the uWSGI server in combination with gevent, the Socket.IO server |
|||
can take advantage of uWSGI's native WebSocket support. |
|||
|
|||
Instances of class ``socketio.Server`` will automatically use this option for |
|||
asynchronous operations if both gevent and uWSGI are installed and eventlet is |
|||
not installed. To request this asynchronous mode explicitly, the |
|||
``async_mode`` option can be given in the constructor:: |
|||
|
|||
# gevent with uWSGI |
|||
sio = socketio.Server(async_mode='gevent_uwsgi') |
|||
|
|||
A complete explanation of the configuration and usage of the uWSGI server is |
|||
beyond the scope of this documentation. The uWSGI server is a fairly complex |
|||
package that provides a large and comprehensive set of options. It must be |
|||
compiled with WebSocket and SSL support for the WebSocket transport to be |
|||
available. As way of an introduction, the following command starts a uWSGI |
|||
server for the ``latency.py`` example on port 5000:: |
|||
|
|||
$ uwsgi --http :5000 --gevent 1000 --http-websockets --master --wsgi-file latency.py --callable app |
|||
|
|||
Standard Threads |
|||
---------------- |
|||
|
|||
While not comparable to eventlet and gevent in terms of performance, |
|||
the Socket.IO server can also be configured to work with multi-threaded web |
|||
servers that use standard Python threads. This is an ideal setup to use with |
|||
development servers such as `Werkzeug <http://werkzeug.pocoo.org>`_. Only the |
|||
long-polling transport is currently available when using standard threads. |
|||
|
|||
Instances of class ``socketio.Server`` will automatically use the threading |
|||
mode if neither eventlet nor gevent are not installed. To request the |
|||
threading mode explicitly, the ``async_mode`` option can be given in the |
|||
constructor:: |
|||
|
|||
sio = socketio.Server(async_mode='threading') |
|||
|
|||
A server configured for threading is deployed as a regular web application, |
|||
using any WSGI complaint multi-threaded server. The example below deploys an |
|||
Socket.IO application combined with a Flask web application, using Flask's |
|||
development web server based on Werkzeug:: |
|||
|
|||
sio = socketio.Server(async_mode='threading') |
|||
app = Flask(__name__) |
|||
app.wsgi_app = socketio.Middleware(sio, app.wsgi_app) |
|||
|
|||
# ... Socket.IO and Flask handler functions ... |
|||
|
|||
if __name__ == '__main__': |
|||
app.run(threaded=True) |
|||
|
|||
When using the threading mode, it is important to ensure that the WSGI server |
|||
can handle multiple concurrent requests using threads, since a client can have |
|||
up to two outstanding requests at any given time. The Werkzeug server is |
|||
single-threaded by default, so the ``threaded=True`` option is required. |
|||
|
|||
Note that servers that use worker processes instead of threads, such as |
|||
gunicorn, do not support a Socket.IO server configured in threading mode. |
|||
|
|||
Scalability Notes |
|||
----------------- |
|||
|
|||
Socket.IO is a stateful protocol, which makes horizontal scaling more |
|||
difficult. To deploy a cluster of Socket.IO processes hosted on one or |
|||
multiple servers, the following conditions must be met: |
|||
|
|||
- Each Socket.IO process must be able to handle multiple requests |
|||
concurrently. This is required because long-polling clients send two |
|||
requests in parallel. Worker processes that can only handle one request at a |
|||
time are not supported. |
|||
- The load balancer must be configured to always forward requests from a |
|||
client to the same worker process. Load balancers call this *sticky |
|||
sessions*, or *session affinity*. |
|||
- The worker processes need to communicate with each other to coordinate |
|||
complex operations such as broadcasts. This is done through a configured |
|||
message queue. See the section on using message queues for details. |
|||
Loading…
Reference in new issue