asyncio -- Asynchronous I/O scheduler for writing concurrent code. ================================================================== .. This document was autogenerated by Sphinx-autoapi from a .pyi stub or a source code file. .. Do not edit this file, instead edit the source file and run Sphinx to update. .. Source: docs/stubs/asyncio/__init__.pyi .. py:module:: asyncio .. autoapi-nested-parse:: Asynchronous I/O scheduler for writing concurrent code. |see_cpython_module| `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 -------------- Classes ------- .. autoapisummary:: asyncio.Event asyncio.Lock asyncio.Loop asyncio.Server asyncio.Stream asyncio.Task asyncio.ThreadSafeFlag Functions --------- .. autoapisummary:: asyncio.create_task asyncio.current_task asyncio.gather asyncio.get_event_loop asyncio.new_event_loop asyncio.open_connection asyncio.run asyncio.sleep asyncio.sleep_ms asyncio.start_server asyncio.wait_for asyncio.wait_for_ms Module Contents --------------- .. py:class:: Event Create a new event which can be used to synchronise tasks. Events start in the cleared state. .. py:method:: clear() -> None Clear the event. .. py:method:: is_set() -> bool Returns ``True`` if the event is set, ``False`` otherwise. .. py:method:: set() -> None 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`. .. py:method:: wait() -> Coroutine[_typeshed.Incomplete, Any, Any] Wait for the event to be set. If the event is already set then it returns immediately. This is a coroutine. .. py:class:: 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. .. py:method:: acquire() -> Coroutine[None, Any, Any] 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. .. py:method:: locked() -> bool Returns ``True`` if the lock is locked, otherwise ``False``. .. py:method:: release() -> _typeshed.Incomplete 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. .. py:class:: Loop This represents the object which schedules and runs tasks. It cannot be created, use `get_event_loop` instead. .. py:method:: call_exception_handler(context) -> _typeshed.Incomplete Call the current exception handler. The argument *context* is passed through and is a dictionary containing keys: ``'message'``, ``'exception'``, ``'future'``. .. py:method:: close() -> None Close the event loop. .. py:method:: create_task(coro) -> Task Create a task from the given *coro* and return the new `Task` object. .. py:method:: default_exception_handler(context) -> _typeshed.Incomplete The default exception handler that is called. .. py:method:: get_exception_handler() -> None Get the current exception handler. Returns the handler, or ``None`` if no custom handler is set. .. py:method:: run_forever() -> _typeshed.Incomplete Run the event loop until `stop()` is called. .. py:method:: run_until_complete(awaitable) -> _typeshed.Incomplete Run the given *awaitable* until it completes. If *awaitable* is not a task then it will be promoted to one. .. py:method:: set_exception_handler(handler) -> None Set the exception handler to call when a Task raises an exception that is not caught. The *handler* should accept two arguments: ``(loop, context)``. .. py:method:: stop() -> None Stop the event loop. .. py:class:: 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. .. py:method:: close() -> None Close the server. .. py:method:: wait_closed() -> Coroutine[None, Any, Any] Wait for the server to close. This is a coroutine. .. py:class:: Stream 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. .. py:method:: close() -> None Close the stream. .. py:method:: drain() -> Coroutine[_typeshed.Incomplete, Any, Any] Drain (write) all buffered output data out to the stream. This is a coroutine. .. py:method:: get_extra_info(v) -> _typeshed.Incomplete Get extra information about the stream, given by *v*. The valid values for *v* are: ``peername``. .. py:method:: read(n=-1) -> Coroutine[_typeshed.Incomplete, Any, Any] 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. .. py:method:: readexactly(n) -> Coroutine[bytes, Any, Any] 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. .. py:method:: readinto(buf) -> Coroutine[int, Any, Any] 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. .. py:method:: readline() -> Coroutine[_typeshed.Incomplete, Any, Any] Read a line and return it. This is a coroutine. .. py:method:: wait_closed() -> Coroutine[None, Any, Any] Wait for the stream to close. This is a coroutine. .. py:method:: write(buf) -> _typeshed.Incomplete 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. .. py:class:: Task 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. .. py:method:: cancel() -> None 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``. .. py:class:: ThreadSafeFlag Create 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. .. py:method:: clear() -> None Clear the flag. This may be used to ensure that a possibly previously-set flag is clear before waiting for it. .. py:method:: set() -> None Set the flag. If there is a task waiting on the flag, it will be scheduled to run. .. py:method:: wait() -> Coroutine[_typeshed.Incomplete, Any, Any] 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. .. py:function:: create_task(coro) -> Task Create a new task from the given coroutine and schedule it to run. Returns the corresponding `Task` object. .. py:function:: current_task() -> Task Return the `Task` object associated with the currently running task. .. py:function:: gather(*awaitables, return_exceptions=False) -> Coroutine[List, Any, Any] 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. .. py:function:: get_event_loop() -> _typeshed.Incomplete Return the event loop used to schedule and run tasks. See `Loop`. .. py:function:: new_event_loop() -> _typeshed.Incomplete 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. .. py:function:: open_connection(host, port, ssl=None) -> Coroutine[Tuple, Any, Any] 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. .. py:function:: run(coro) -> _typeshed.Incomplete Create a new task from the given coroutine and run it until it completes. Returns the value returned by *coro*. .. py:function:: sleep(t) -> Coroutine[_typeshed.Incomplete, Any, Any] Sleep for *t* seconds (can be a float). This is a coroutine. .. py:function:: sleep_ms(t) -> Coroutine[_typeshed.Incomplete, Any, Any] Sleep for *t* milliseconds. This is a coroutine, and a MicroPython extension. .. py:function:: start_server(callback, host, port, backlog=5, ssl=None) -> Coroutine[Server, Any, Any] 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. .. py:function:: wait_for(awaitable, timeout) -> Coroutine[_typeshed.Incomplete, Any, Any] 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. .. py:function:: wait_for_ms(awaitable, timeout) -> Coroutine[_typeshed.Incomplete, Any, Any] Similar to `wait_for` but *timeout* is an integer in milliseconds. This is a coroutine, and a MicroPython extension.