asyncio

Core

exception asyncio.core.CancelledError

Injected into a task when calling Task.cancel()

exception asyncio.core.InvalidStateError

Can be raised in situations like setting a result value for a task object that already has a result value set.

class asyncio.core.Loop

Class representing the event loop

call_exception_handler()

Call the current exception handler. The argument context is passed through and is a dictionary containing keys: 'message', 'exception', 'future'

close()

Close the event loop.

create_task()

Create a task from the given coro and return the new Task object.

default_exception_handler(context)

The default exception handler that is called.

get_exception_handler()

Get the current exception handler. Returns the handler, or None if no custom handler is set.

run_forever()

Run the event loop until Loop.stop() is called.

run_until_complete()

Run the given awaitable until it completes. If awaitable is not a task then it will be promoted to one.

set_exception_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)

stop()

Stop the event loop

exception asyncio.core.TimeoutError

Raised when waiting for a task longer than the specified timeout.

asyncio.core.create_task(coro)

Create a new task from the given coroutine and schedule it to run.

Returns the corresponding Task object.

asyncio.core.current_task()

Return the Task object associated with the currently running task.

asyncio.core.get_event_loop(runq_len=0, waitq_len=0)

Return the event loop used to schedule and run tasks. See Loop.

asyncio.core.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.core.run(coro)

Create a new task from the given coroutine and run it until it completes.

Returns the value returned by coro.

asyncio.core.run_until_complete(main_task=None)

Run the given main_task until it completes.

asyncio.core.sleep(t)

Sleep for t seconds

This is a coroutine.

asyncio.core.sleep_ms(t, sgen=<asyncio.core.SingletonGenerator object>)

Sleep for t milliseconds.

This is a coroutine, and a MicroPython extension.

Events

class asyncio.event.Event

Create a new event which can be used to synchronize tasks. Events start in the cleared state.

clear()

Clear the event.

is_set()

Returns True if the event is set, False otherwise.

set()

Set the event. Any tasks waiting on the event will be scheduled to run.

async wait()

Wait for the event to be set. If the event is already set then it returns immediately.

This is a coroutine.

Functions

async asyncio.funcs.gather(*aws, return_exceptions=False)

Run all aws awaitables concurrently. Any aws that are not tasks are promoted to tasks.

Returns a list of return values of all aws

async asyncio.funcs.wait_for(aw, timeout, sleep=<function sleep>)

Wait for the aw awaitable to complete, but cancel if it takes longer than timeout seconds. If aw 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.

Returns the return value of aw.

This is a coroutine.

asyncio.funcs.wait_for_ms(aw, timeout)

Similar to wait_for but timeout is an integer in milliseconds.

This is a coroutine, and a MicroPython extension.

Locks

class asyncio.lock.Lock

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

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

locked()

Returns True if the lock is locked, otherwise False.

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 and the lock becomes unlocked.

Streams

class asyncio.stream.Server

This represents the server class returned from start_server. It can be used in an async with statement to close the server upon exit.

close()

Close the server.

async wait_closed()

Wait for the server to close.

This is a coroutine.

class asyncio.stream.Stream(s, e={})

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

async aclose()

Wait for the stream to close.

This is a coroutine.

async drain()

Drain (write) all buffered output data out to the stream.

This is a coroutine.

get_extra_info(v)

Get extra information about the stream, given by v. The valid values for v are: peername.

async read(n)

Read up to n bytes and return them.

This is a coroutine.

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

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

async readline()

Read a line and return it.

This is a coroutine.

async wait_closed()

Wait for the stream to close.

This is a coroutine.

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.

asyncio.stream.StreamReader

alias of Stream

asyncio.stream.StreamWriter

alias of Stream

async asyncio.stream.open_connection(host, port)

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.

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.

async asyncio.stream.start_server(cb, host, port, backlog=5)

Start a TCP server on the given host and port. The cb callback will be called with incoming, accepted connections, and be passed 2 arguments: reader writer streams for the connection.

Returns a Server object.

This is a coroutine.

Tasks

class asyncio.task.Task(coro, globals=None)

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

cancel()

Cancel the task by injecting a CancelledError into it. The task may or may not ignore this exception.

done()

Whether the task is complete.