Desarrollando con asyncio
*************************

La programación asincrónica es diferente a la programación
"secuencial" clásica.

Esta página enumera errores y trampas comunes y explica cómo
evitarlos.


Modo Depuración
===============

Por defecto asyncio se ejecuta en modo producción. Para facilitar el
desarrollo asyncio tiene un *modo depuración*.

Hay varias maneras de habilitar el modo depuración de asyncio:

* Definiendo la variable de entorno "PYTHONASYNCIODEBUG" a "1".

* Usando Modo de Desarrollo de Python.

* Pasando "debug=True" a "asyncio.run()".

* Invocando "loop.set_debug()".

Además de habilitar el modo depuración, considere también:

* definir el nivel de log del asyncio logger a "logging.DEBUG", por
  ejemplo el siguiente fragmento de código puede ser ejecutado al
  inicio de la aplicación:

     logging.basicConfig(level=logging.DEBUG)

* configurando el módulo "warnings" para mostrar advertencias
  "ResourceWarning". Una forma de hacerlo es usando la opción "-W"
  "default" de la línea de comandos.

Cuando el modo depuración está habilitado:

* asyncio comprueba las corrutinas que no son esperadas y las
  registra; esto mitiga la dificultad de las "esperas olvidadas".

* Muchas APIs asyncio que no son seguras para hilos (como los métodos
  "loop.call_soon()" y "loop.call_at()") generan una excepción si son
  llamados desde un hilo equivocado.

* El tiempo de ejecución del selector E/S es registrado si tarda
  demasiado tiempo en realizar una operación E/S.

* Los callbacks que tardan más de 100ms son registrados. El atributo
  "loop.slow_callback_duration" puede ser usado para definir la
  duración mínima de ejecución en segundos considerada como "lenta".


Concurrencia y Multihilo
========================

Un bucle de eventos se ejecuta en un hilo (generalmente el hilo
principal) y ejecuta todos los callbacks y las Tareas en su hilo.
Mientras una Tarea está ejecutándose en el bucle de eventos, ninguna
otra Tarea puede ejecutarse en el mismo hilo. Cuando una Tarea ejecuta
una expresión "await", la Tarea en ejecución se suspende y el bucle de
eventos ejecuta la siguiente Tarea.

Para programar un *callback* desde otro hilo del SO, se debe usar el
método "loop.call_soon_threadsafe()". Ejemplo:

   loop.call_soon_threadsafe(callback, *args)

Casi ningún objeto asyncio es seguro entre hilos (*thread safe*), lo
cual generalmente no es un problema a no ser que haya código que
trabaje con ellos desde fuera de una Tarea o un callback. Si tal
código necesita llamar a la API de asyncio de bajo nivel, se debe usar
el método "loop.call_soon_threadsafe()", por ejemplo:

   loop.call_soon_threadsafe(fut.cancel)

Para programar un objeto de corrutina desde una hilo diferente del
sistema operativo se debe usar la función
"run_coroutine_threadsafe()". Esta retorna un
"concurrent.futures.Future" para acceder al resultado:

   async def coro_func():
        return await asyncio.sleep(1, 42)

   # Later in another OS thread:

   future = asyncio.run_coroutine_threadsafe(coro_func(), loop)
   # Wait for the result:
   result = future.result()

Para manejar señales y ejecutar subprocesos, el bucle de eventos debe
ser ejecutado en el hilo principal.

El método "loop.run_in_executor()" puede ser usado con un
"concurrent.futures.ThreadPoolExecutor" para ejecutar código
bloqueante en un hilo diferente del sistema operativo sin bloquear el
hilo del sistema operativo en el que el bucle de eventos está siendo
ejecutado.

There is currently no way to schedule coroutines or callbacks directly
from a different process (such as one started with "multiprocessing").
The Métodos del bucle de eventos section lists APIs that can read from
pipes and watch file descriptors without blocking the event loop. In
addition, asyncio's Subprocess APIs provide a way to start a process
and communicate with it from the event loop. Lastly, the
aforementioned "loop.run_in_executor()" method can also be used with a
"concurrent.futures.ProcessPoolExecutor" to execute code in a
different process.


Ejecutando Código Bloqueante
============================

Código bloqueante (dependiente de la CPU) no debe ser ejecutado
directamente. Por ejemplo, si una función realiza un cálculo intensivo
de CPU durante 1 segundo, todas las Tareas y operaciones de
Entrada/Salida (IO) concurrentes se retrasarían 1 segundo.

Un ejecutor puede ser usado para ejecutar una tarea en un hilo
diferente o incluso en un proceso diferente para evitar bloquear el
hilo del sistema operativo con el bucle de eventos. Consulte el método
"loop.run_in_executor()" para más detalles.


Logueando
=========

asyncio usa el módulo "logging" y todo el logueo es realizado mediante
el logger ""asyncio"".

El nivel de log por defecto es "logging.INFO", el cual puede ser
fácilmente ajustado:

   logging.getLogger("asyncio").setLevel(logging.WARNING)

Network logging can block the event loop. It is recommended to use a
separate thread for handling logs or use non-blocking IO. For example,
see Tratar con gestores que bloquean.


Detectar corrutinas no esperadas
================================

Cuando una función de corrutina es invocada, pero no esperada (por
ejemplo "coro()" en lugar de "await coro()") o la corrutina no es
programada con "asyncio.create_task()", asyncio emitirá una
"RuntimeWarning":

   import asyncio

   async def test():
       print("never scheduled")

   async def main():
       test()

   asyncio.run(main())

Salida:

   test.py:7: RuntimeWarning: coroutine 'test' was never awaited
     test()

Salida en modo depuración:

   test.py:7: RuntimeWarning: coroutine 'test' was never awaited
   Coroutine created at (most recent call last)
     File "../t.py", line 9, in <module>
       asyncio.run(main(), debug=True)

     < .. >

     File "../t.py", line 7, in main
       test()
     test()

La solución habitual es esperar la corrutina o llamar a la función
"asyncio.create_task()":

   async def main():
       await test()


Detectar excepciones nunca recuperadas
======================================

Si un "Future.set_exception()" es invocado pero el objeto Futuro nunca
es esperado, la excepción nunca será propagada al código del usuario.
En este caso, asyncio emitiría un mensaje de registro cuando el objeto
Futuro fuera recolectado como basura.

Ejemplo de una excepción no manejada:

   import asyncio

   async def bug():
       raise Exception("not consumed")

   async def main():
       asyncio.create_task(bug())

   asyncio.run(main())

Salida:

   Task exception was never retrieved
   future: <Task finished coro=<bug() done, defined at test.py:3>
     exception=Exception('not consumed')>

   Traceback (most recent call last):
     File "test.py", line 4, in bug
       raise Exception("not consumed")
   Exception: not consumed

Habilita el modo depuración para obtener el seguimiento de pila
(*traceback*) donde la tarea fue creada:

   asyncio.run(main(), debug=True)

Salida en modo depuración:

   Task exception was never retrieved
   future: <Task finished coro=<bug() done, defined at test.py:3>
       exception=Exception('not consumed') created at asyncio/tasks.py:321>

   source_traceback: Object created at (most recent call last):
     File "../t.py", line 9, in <module>
       asyncio.run(main(), debug=True)

   < .. >

   Traceback (most recent call last):
     File "../t.py", line 4, in bug
       raise Exception("not consumed")
   Exception: not consumed
