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
  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-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.
