The Engine.IO Client¶
This package contains two Engine.IO clients:
The
engineio.Client()
class creates a client compatible with the standard Python library.The
engineio.AsyncClient()
class creates a client compatible with theasyncio
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-engineio[client]"
If instead you plan on using the asyncio
client, then use this:
pip install "python-engineio[asyncio_client]"
Creating a Client Instance¶
To instantiate an Engine.IO client, simply create an instance of the appropriate client class:
import engineio
# standard Python
eio = engineio.Client()
# asyncio
eio = engineio.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:
@eio.on('connect')
def on_connect():
print('I'm connected!')
@eio.on('message')
def on_message(data):
print('I received a message!')
@eio.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:
@eio.on('message')
async def on_message(data):
print('I received a message!')
The argument given to the on
decorator is the event name. The events that
are supported are connect
, message
and disconnect
. Note that the
disconnect
handler is invoked for application initiated disconnects,
server initiated disconnects, or accidental disconnects, for example due to
networking failures.
The data
argument passed to the 'message'
event handler contains
application-specific data provided by the server with the event.
Connecting to a Server¶
The connection to a server is established by calling the connect()
method:
eio.connect('http://localhost:5000')
In the case of the asyncio
client, the method is a coroutine:
await eio.connect('http://localhost:5000')
Upon connection, the server assigns the client a unique session identifier.
The applicaction can find this identifier in the sid
attribute:
print('my sid is', eio.sid)
Sending Messages¶
The client can send a message to the server using the send()
method:
eio.send({'foo': 'bar'})
Or in the case of asyncio
, as a coroutine:
await eio.send({'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 send()
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.
Disconnecting from the Server¶
At any time the client can request to be disconnected from the server by
invoking the disconnect()
method:
eio.disconnect()
For the asyncio
client this is a coroutine:
await eio.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 Engine.IO client.
If the application does not have anything to do in the main thread and
just wants to wait until the connection ends, it can call the wait()
method:
eio.wait()
Or in the asyncio
version:
await eio.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
eio.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
eio.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, but the background function is.
The sleep()
method is a second convenience function that is provided for
the benefit of applications working with background tasks of their own:
eio.sleep(2)
Or for asyncio
:
await eio.sleep(2)
The single argument passed to the method is the number of seconds to sleep for.
Debugging and Troubleshooting¶
To help you debug issues, the client can be configured to output logs to the terminal:
import engineio
# standard Python
eio = engineio.Client(logger=True)
# asyncio
eio = engineio.AsyncClient(logger=True)
The logger
argument can be set to True
to output logs to stderr
, or
to an object compatible with Python’s logging
package where the logs should
be emitted to. A value of False
disables logging.
Logging can help identify the cause of connection problems, unexpected disconnections and other issues.