asynchronous I/O scheduler for writing concurrent code
asyncio — asynchronous I/O scheduler
This module implements a subset of the corresponding CPython module, as described below. For more information, refer to the original CPython documentation: asyncio
Example:
import asyncio
async def blink(led, period_ms):
while True:
led.on()
await asyncio.sleep_ms(5)
led.off()
await asyncio.sleep_ms(period_ms)
async def main(led1, led2):
asyncio.create_task(blink(led1, 700))
asyncio.create_task(blink(led2, 400))
await asyncio.sleep_ms(10_000)
# Running on a pyboard
from pyb import LED
asyncio.run(main(LED(1), LED(2)))
# Running on a generic board
from machine import Pin
asyncio.run(main(Pin(1), Pin(2)))Core functions
asyncio.create_task
asyncio.create_task(coro)Create a new task from the given coroutine and schedule it to run.
Returns the corresponding Task object.
asyncio.current_task
asyncio.current_task()Return the Task object associated with the currently running task.
asyncio.run
asyncio.run(coro)Create a new task from the given coroutine and run it until it completes.
Returns the value returned by coro.
asyncio.sleep
asyncio.sleep(t)Sleep for t seconds (can be a float).
This is a coroutine.
asyncio.sleep_ms
asyncio.sleep_ms(t)Sleep for t milliseconds.
This is a coroutine, and a MicroPython extension.
Additional functions
asyncio.wait_for
asyncio.wait_for(awaitable, timeout)Wait for the awaitable to complete, but cancel it if it takes longer than timeout seconds. If awaitable is not a task then a task will be created from it.
If a timeout occurs, it cancels the task and raises asyncio.TimeoutError:
this should be trapped by the caller. The task receives
asyncio.CancelledError which may be ignored or trapped using try...except
or try...finally to run cleanup code.
Returns the return value of awaitable.
This is a coroutine.
asyncio.wait_for_ms
asyncio.wait_for_ms(awaitable, timeout)Similar to wait_for but timeout is an integer in milliseconds.
This is a coroutine, and a MicroPython extension.
asyncio.gather
asyncio.gather(*awaitables, return_exceptions=False)Run all awaitables concurrently. Any awaitables that are not tasks are promoted to tasks.
Returns a list of return values of all awaitables.
This is a coroutine.
class Task
asyncio.Task
class asyncio.TaskThis object wraps a coroutine into a running task. Tasks can be waited on
using await task, which will wait for the task to complete and return
the return value of the task.
Tasks should not be created directly, rather use create_task to create them.
Task.cancel
Task.cancel()Cancel the task by injecting asyncio.CancelledError into it. The task may
ignore this exception. Cleanup code may be run by trapping it, or via
try ... finally.
class Event
asyncio.Event
class asyncio.EventCreate a new event which can be used to synchronise tasks. Events start in the cleared state.
Event.is_set
Event.is_set()Returns True if the event is set, False otherwise.
Event.set
Event.set()Set the event. Any tasks waiting on the event will be scheduled to run.
Note: This must be called from within a task. It is not safe to call this from an IRQ, scheduler callback, or other thread. See ThreadSafeFlag.
Event.clear
Event.clear()Clear the event.
Event.wait
Event.wait()Wait for the event to be set. If the event is already set then it returns immediately.
This is a coroutine.
class ThreadSafeFlag
asyncio.ThreadSafeFlag
class asyncio.ThreadSafeFlagCreate a new flag which can be used to synchronise a task with code running outside the asyncio loop, such as other threads, IRQs, or scheduler callbacks. Flags start in the cleared state.
ThreadSafeFlag.set
ThreadSafeFlag.set()Set the flag. If there is a task waiting on the flag, it will be scheduled to run.
ThreadSafeFlag.clear
ThreadSafeFlag.clear()Clear the flag. This may be used to ensure that a possibly previously-set flag is clear before waiting for it.
ThreadSafeFlag.wait
ThreadSafeFlag.wait()Wait for the flag to be set. If the flag is already set then it returns
immediately. The flag is automatically reset upon return from wait.
A flag may only be waited on by a single task at a time.
This is a coroutine.
class Lock
asyncio.Lock
class asyncio.LockCreate a new lock which can be used to coordinate tasks. Locks start in the unlocked state.
In addition to the methods below, locks can be used in an async with statement.
Lock.locked
Lock.locked()Returns True if the lock is locked, otherwise False.
Lock.acquire
Lock.acquire()Wait for the lock to be in the unlocked state and then lock it in an atomic way. Only one task can acquire the lock at any one time.
This is a coroutine.
Lock.release
Lock.release()Release the lock. If any tasks are waiting on the lock then the next one in the queue is scheduled to run and the lock remains locked. Otherwise, no tasks are waiting an the lock becomes unlocked.
TCP stream connections
asyncio.open_connection
asyncio.open_connection(host, port, ssl=None)Open a TCP connection to the given host and port. The host address will be
resolved using socket.getaddrinfo, which is currently a blocking call.
If ssl is a ssl.SSLContext object, this context is used to create the transport;
if ssl is True, a default context is used.
Returns a pair of streams: a reader and a writer stream.
Will raise a socket-specific OSError if the host could not be resolved or if
the connection could not be made.
This is a coroutine.
asyncio.start_server
asyncio.start_server(callback, host, port, backlog=5, ssl=None)Start a TCP server on the given host and port. The callback will be called with incoming, accepted connections, and be passed 2 arguments: reader and writer streams for the connection.
If ssl is a ssl.SSLContext object, this context is used to create the transport.
Returns a Server object.
This is a coroutine.
asyncio.Stream
class asyncio.StreamThis represents a TCP stream connection. To minimise code this class implements
both a reader and a writer, and both StreamReader and StreamWriter alias to
this class.
Stream.get_extra_info
Stream.get_extra_info(v)Get extra information about the stream, given by v. The valid values for v are:
peername.
Stream.close
Stream.close()Close the stream.
Stream.wait_closed
Stream.wait_closed()Wait for the stream to close.
This is a coroutine.
Stream.read
Stream.read(n=-1)Read up to n bytes and return them. If n is not provided or -1 then read all bytes until EOF. The returned value will be an empty bytes object if EOF is encountered before any bytes are read.
This is a coroutine.
Stream.readinto
Stream.readinto(buf)Read up to n bytes into buf with n being equal to the length of buf.
Return the number of bytes read into buf.
This is a coroutine, and a MicroPython extension.
Stream.readexactly
Stream.readexactly(n)Read exactly n bytes and return them as a bytes object.
Raises an EOFError exception if the stream ends before reading n bytes.
This is a coroutine.
Stream.readline
Stream.readline()Read a line and return it.
This is a coroutine.
Stream.write
Stream.write(buf)Accumulated buf to the output buffer. The data is only flushed when Stream.drain is called. It is recommended to call Stream.drain immediately after calling this function.
Stream.drain
Stream.drain()Drain (write) all buffered output data out to the stream.
This is a coroutine.
asyncio.Server
class asyncio.ServerThis represents the server class returned from start_server. It can be used
in an async with statement to close the server upon exit.
Server.close
Server.close()Close the server.
Server.wait_closed
Server.wait_closed()Wait for the server to close.
This is a coroutine.
Event Loop
asyncio.get_event_loop
asyncio.get_event_loop()Return the event loop used to schedule and run tasks. See Loop.
asyncio.new_event_loop
asyncio.new_event_loop()Reset the event loop and return it.
Note: since MicroPython only has a single event loop this function just resets the loop’s state, it does not create a new one.
asyncio.Loop
class asyncio.LoopThis represents the object which schedules and runs tasks. It cannot be created, use get_event_loop instead.
Loop.create_task
Loop.create_task(coro)Create a task from the given coro and return the new Task object.
Loop.run_forever
Loop.run_forever()Run the event loop until stop() is called.
Loop.run_until_complete
Loop.run_until_complete(awaitable)Run the given awaitable until it completes. If awaitable is not a task then it will be promoted to one.
Loop.stop
Loop.stop()Stop the event loop.
Loop.close
Loop.close()Close the event loop.
Loop.set_exception_handler
Loop.set_exception_handler(handler)Set the exception handler to call when a Task raises an exception that is not
caught. The handler should accept two arguments: (loop, context).
Loop.get_exception_handler
Loop.get_exception_handler()Get the current exception handler. Returns the handler, or None if no
custom handler is set.
Loop.default_exception_handler
Loop.default_exception_handler(context)The default exception handler that is called.
Loop.call_exception_handler
Loop.call_exception_handler(context)Call the current exception handler. The argument context is passed through and
is a dictionary containing keys: 'message', 'exception', 'future'.