API reference¶
Event loop¶
-
anyio.
run
(func, *args, backend='asyncio', backend_options=None)¶ Run the given coroutine function in an asynchronous event loop.
The current thread must not be already running an event loop.
- Parameters
func (
Callable
[…,Coroutine
[Any
,Any
, +T_Retval]]) – a coroutine functionargs – positional arguments to
func
backend (
str
) – name of the asynchronous event loop implementation – one ofasyncio
,curio
andtrio
backend_options (
Optional
[Dict
[str
,Any
]]) – keyword arguments to call the backendrun()
implementation with (documented here)
- Return type
+T_Retval
- Returns
the return value of the coroutine function
- Raises
RuntimeError – if an asynchronous event loop is already running in this thread
LookupError – if the named backend is not found
-
anyio.
get_all_backends
()¶ Return a tuple of the names of all built-in backends.
-
anyio.
get_cancelled_exc_class
()¶ Return the current async library’s cancellation exception class.
- Return type
-
async
anyio.
sleep
(delay)¶ Pause the current task for the specified duration.
Asynchronous resources¶
-
async
anyio.
aclose_forcefully
(resource)¶ Close an asynchronous resource in a cancelled scope.
Doing this closes the resource without waiting on anything.
- Parameters
resource (
AsyncResource
) – the resource to close- Return type
Typed attributes¶
-
anyio.
typed_attribute
()¶ Return a unique object, used to mark typed attributes.
-
class
anyio.
TypedAttributeSet
¶ Bases:
object
Superclass for typed attribute collections.
Checks that every public attribute of every subclass has a type annotation.
-
class
anyio.
TypedAttributeProvider
¶ Bases:
object
Base class for classes that wish to provide typed extra attributes.
-
extra
(attribute, default=undefined)¶ Return the value of the given typed extra attribute.
- Parameters
attribute – the attribute (member of a
TypedAttributeSet
) to look fordefault – the value that should be returned if no value is found for the attribute
- Raises
TypedAttributeLookupError – if the search failed and no default value was given
-
property
extra_attributes
¶ A mapping of the extra attributes to callables that return the corresponding values.
If the provider wraps another provider, the attributes from that wrapper should also be included in the returned mapping (but the wrapper may override the callables from the wrapped instance).
-
Timeouts and cancellation¶
-
anyio.
open_cancel_scope
(*, shield=False)¶ Open a cancel scope.
- Parameters
shield (
bool
) –True
to shield the cancel scope from external cancellation- Return type
- Returns
a cancel scope
-
anyio.
move_on_after
(delay, *, shield=False)¶ Create an async context manager which is exited if it does not complete within the given time.
- Parameters
- Returns
an asynchronous context manager that yields a cancel scope
- Return type
-
anyio.
fail_after
(delay, *, shield=False)¶ Create an async context manager which raises an exception if does not finish in time.
- Parameters
- Returns
an asynchronous context manager that yields a cancel scope
- Return type
- Raises
TimeoutError – if the block does not complete within the allotted time
-
anyio.
current_effective_deadline
()¶ Return the nearest deadline among all the cancel scopes effective for the current task.
- Returns
a clock value from the event loop’s internal clock (
float('inf')
if there is no deadline in effect)- Return type
Task groups¶
-
class
anyio.abc.
TaskGroup
¶ Bases:
object
Groups several asynchronous tasks together.
- Variables
cancel_scope (CancelScope) – the cancel scope inherited by all child tasks
Threads¶
-
async
anyio.
run_sync_in_worker_thread
(func, *args, cancellable=False, limiter=None)¶ Call the given function with the given arguments in a worker thread.
If the
cancellable
option is enabled and the task waiting for its completion is cancelled, the thread will still run its course but its return value (or any raised exception) will be ignored.- Parameters
func (
Callable
[…, ~T_Retval]) – a callableargs – positional arguments for the callable
cancellable (
bool
) –True
to allow cancellation of the operationlimiter (
Optional
[CapacityLimiter
]) – capacity limiter to use to limit the total amount of threads running (if omitted, the default limiter is used)
- Return type
~T_Retval
- Returns
an awaitable that yields the return value of the function.
-
anyio.
run_async_from_thread
(func, *args)¶ Call a coroutine function from a worker thread.
-
anyio.
current_default_worker_thread_limiter
()¶ Return the capacity limiter that is used by default to limit the number of concurrent threads.
- Return type
- Returns
a capacity limiter object
-
anyio.
create_blocking_portal
()¶ Create a portal for running functions in the event loop thread from external threads.
Use this function in asynchronous code when you need to allow external threads access to the event loop where your asynchronous code is currently running.
- Return type
-
anyio.
start_blocking_portal
(backend='asyncio', backend_options=None)¶ Start a new event loop in a new thread and run a blocking portal in its main task.
The parameters are the same as for
run()
.
-
class
anyio.abc.
BlockingPortal
¶ Bases:
object
An object tied that lets external threads run code in an asynchronous event loop.
-
call
(func, *args)¶ Call the given function in the event loop thread.
If the callable returns a coroutine object, it is awaited on.
- Parameters
func – any callable
- Raises
RuntimeError – if the portal is not running or if this method is called from within the event loop thread
-
spawn_task
(func, *args)¶ Spawn a task in the portal’s task group.
The task will be run inside a cancel scope which can be cancelled by cancelling the returned future.
- Parameters
- Return type
Future
- Returns
a future that resolves with the return value of the callable if the task completes successfully, or with the exception raised in the task
- Raises
RuntimeError – if the portal is not running or if this method is called from within the event loop thread
New in version 2.1.
-
async
stop
(cancel_remaining=False)¶ Signal the portal to shut down.
This marks the portal as no longer accepting new calls and exits from
sleep_until_stopped()
.
-
stop_from_external_thread
(cancel_remaining=False)¶ Signal the portal to stop and wait for the event loop thread to finish.
-
wrap_async_context_manager
(cm)¶ Wrap an async context manager as a synchronous context manager via this portal.
Spawns a task that will call both
__aenter__()
and__aexit__()
, stopping in the middle until the synchronous context manager exits.- Parameters
cm (
AsyncContextManager
[+T_co]) – an asynchronous context manager- Return type
ContextManager
[+T_co]- Returns
a synchronous context manager
New in version 2.1.
-
Async file I/O¶
-
async
anyio.
open_file
(file, mode='r', buffering=- 1, encoding=None, errors=None, newline=None, closefd=True, opener=None)¶ Open a file asynchronously.
The arguments are exactly the same as for the builtin
open()
.- Return type
- Returns
an asynchronous file object
-
class
anyio.
AsyncFile
(fp)¶ Bases:
anyio.abc.AsyncResource
An asynchronous file object.
This class wraps a standard file object and provides async friendly versions of the following blocking methods (where available on the original file object):
read
read1
readline
readlines
readinto
readinto1
write
writelines
truncate
seek
tell
flush
All other methods are directly passed through.
This class supports the asynchronous context manager protocol which closes the underlying file at the end of the context block.
This class also supports asynchronous iteration:
async with await anyio.open_file(...) as f: async for line in f: print(line)
-
property
wrapped
¶ The wrapped file object.
Streams and stream wrappers¶
-
anyio.
create_memory_object_stream
(max_buffer_size=0, item_type=None)¶ Create a memory object stream.
- Parameters
max_buffer_size – number of items held in the buffer until
send()
starts blockingitem_type – type of item, for marking the streams with the right generic type for static typing (not used at run time)
- Returns
a tuple of (send stream, receive stream)
-
class
anyio.abc.
UnreliableObjectReceiveStream
¶ Bases:
Generic
[typing.T_Item
],anyio.abc.AsyncResource
,anyio.TypedAttributeProvider
An interface for receiving objects.
This interface makes no guarantees that the received messages arrive in the order in which they were sent, or that no messages are missed.
Asynchronously iterating over objects of this type will yield objects matching the given type parameter.
-
abstract async
receive
()¶ Receive the next item.
- Raises
ClosedResourceError – if the receive stream has been explicitly closed
EndOfStream – if this stream has been closed from the other end
BrokenResourceError – if this stream has been rendered unusable due to external causes
- Return type
~T_Item
-
abstract async
-
class
anyio.abc.
UnreliableObjectSendStream
¶ Bases:
Generic
[typing.T_Item
],anyio.abc.AsyncResource
,anyio.TypedAttributeProvider
An interface for sending objects.
This interface makes no guarantees that the messages sent will reach the recipient(s) in the same order in which they were sent, or at all.
-
abstract async
send
(item)¶ Send an item to the peer(s).
- Parameters
item (~T_Item) – the item to send
- Raises
ClosedResourceError – if the send stream has been explicitly closed
BrokenResourceError – if this stream has been rendered unusable due to external causes
- Return type
-
abstract async
-
class
anyio.abc.
UnreliableObjectStream
¶ Bases:
Generic
[typing.T_Item
],anyio.abc.streams.UnreliableObjectReceiveStream
[typing.T_Item
],anyio.abc.streams.UnreliableObjectSendStream
[typing.T_Item
]A bidirectional message stream which does not guarantee the order or reliability of message delivery.
-
class
anyio.abc.
ObjectReceiveStream
¶ Bases:
Generic
[typing.T_Item
],anyio.abc.streams.UnreliableObjectReceiveStream
[typing.T_Item
]A receive message stream which guarantees that messages are received in the same order in which they were sent, and that no messages are missed.
-
class
anyio.abc.
ObjectSendStream
¶ Bases:
Generic
[typing.T_Item
],anyio.abc.streams.UnreliableObjectSendStream
[typing.T_Item
]A send message stream which guarantees that messages are delivered in the same order in which they were sent, without missing any messages in the middle.
-
class
anyio.abc.
ObjectStream
¶ Bases:
Generic
[typing.T_Item
],anyio.abc.streams.ObjectReceiveStream
[typing.T_Item
],anyio.abc.streams.ObjectSendStream
[typing.T_Item
],anyio.abc.streams.UnreliableObjectStream
[typing.T_Item
]A bidirectional message stream which guarantees the order and reliability of message delivery.
-
class
anyio.abc.
ByteReceiveStream
¶ Bases:
anyio.abc.AsyncResource
,anyio.TypedAttributeProvider
An interface for receiving bytes from a single peer.
Iterating this byte stream will yield a byte string of arbitrary length, but no more than 65536 bytes.
-
abstract async
receive
(max_bytes=65536)¶ Receive at most
max_bytes
bytes from the peer.- Parameters
max_bytes (
int
) – maximum number of bytes to receive- Return type
- Returns
the received bytes
- Raises
EndOfStream – if this stream has been closed from the other end
-
abstract async
-
class
anyio.abc.
ByteSendStream
¶ Bases:
anyio.abc.AsyncResource
,anyio.TypedAttributeProvider
An interface for sending bytes to a single peer.
-
class
anyio.abc.
ByteStream
¶ Bases:
anyio.abc.ByteReceiveStream
,anyio.abc.ByteSendStream
A bidirectional byte stream.
-
class
anyio.abc.
Listener
(*args, **kwds)¶ Bases:
Generic
[typing.T_Stream
],anyio.abc.AsyncResource
,anyio.TypedAttributeProvider
An interface for objects that let you accept incoming connections.
-
abstract async
serve
(handler, task_group=None)¶ Accept incoming connections as they come in and spawn tasks to handle them.
- Parameters
- Return type
-
abstract async
-
anyio.abc.
AnyUnreliableByteReceiveStream
= typing.Union[anyio.abc.UnreliableObjectReceiveStream[bytes], anyio.abc.ByteReceiveStream]¶ Union type; Union[X, Y] means either X or Y.
To define a union, use e.g. Union[int, str]. Details:
The arguments must be types and there must be at least one.
None as an argument is a special case and is replaced by type(None).
Unions of unions are flattened, e.g.:
Union[Union[int, str], float] == Union[int, str, float]
Unions of a single argument vanish, e.g.:
Union[int] == int # The constructor actually returns int
Redundant arguments are skipped, e.g.:
Union[int, str, int] == Union[int, str]
When comparing unions, the argument order is ignored, e.g.:
Union[int, str] == Union[str, int]
When two arguments have a subclass relationship, the least derived argument is kept, e.g.:
class Employee: pass class Manager(Employee): pass Union[int, Employee, Manager] == Union[int, Employee] Union[Manager, int, Employee] == Union[int, Employee] Union[Employee, Manager] == Employee
Similar for object:
Union[int, object] == object
You cannot subclass or instantiate a union.
You can use Optional[X] as a shorthand for Union[X, None].
-
anyio.abc.
AnyUnreliableByteSendStream
= typing.Union[anyio.abc.UnreliableObjectSendStream[bytes], anyio.abc.ByteSendStream]¶ Union type; Union[X, Y] means either X or Y.
To define a union, use e.g. Union[int, str]. Details:
The arguments must be types and there must be at least one.
None as an argument is a special case and is replaced by type(None).
Unions of unions are flattened, e.g.:
Union[Union[int, str], float] == Union[int, str, float]
Unions of a single argument vanish, e.g.:
Union[int] == int # The constructor actually returns int
Redundant arguments are skipped, e.g.:
Union[int, str, int] == Union[int, str]
When comparing unions, the argument order is ignored, e.g.:
Union[int, str] == Union[str, int]
When two arguments have a subclass relationship, the least derived argument is kept, e.g.:
class Employee: pass class Manager(Employee): pass Union[int, Employee, Manager] == Union[int, Employee] Union[Manager, int, Employee] == Union[int, Employee] Union[Employee, Manager] == Employee
Similar for object:
Union[int, object] == object
You cannot subclass or instantiate a union.
You can use Optional[X] as a shorthand for Union[X, None].
-
anyio.abc.
AnyUnreliableByteStream
= typing.Union[anyio.abc.UnreliableObjectStream[bytes], anyio.abc.ByteStream]¶ Union type; Union[X, Y] means either X or Y.
To define a union, use e.g. Union[int, str]. Details:
The arguments must be types and there must be at least one.
None as an argument is a special case and is replaced by type(None).
Unions of unions are flattened, e.g.:
Union[Union[int, str], float] == Union[int, str, float]
Unions of a single argument vanish, e.g.:
Union[int] == int # The constructor actually returns int
Redundant arguments are skipped, e.g.:
Union[int, str, int] == Union[int, str]
When comparing unions, the argument order is ignored, e.g.:
Union[int, str] == Union[str, int]
When two arguments have a subclass relationship, the least derived argument is kept, e.g.:
class Employee: pass class Manager(Employee): pass Union[int, Employee, Manager] == Union[int, Employee] Union[Manager, int, Employee] == Union[int, Employee] Union[Employee, Manager] == Employee
Similar for object:
Union[int, object] == object
You cannot subclass or instantiate a union.
You can use Optional[X] as a shorthand for Union[X, None].
-
anyio.abc.
AnyByteReceiveStream
= typing.Union[anyio.abc.ObjectReceiveStream[bytes], anyio.abc.ByteReceiveStream]¶ Union type; Union[X, Y] means either X or Y.
To define a union, use e.g. Union[int, str]. Details:
The arguments must be types and there must be at least one.
None as an argument is a special case and is replaced by type(None).
Unions of unions are flattened, e.g.:
Union[Union[int, str], float] == Union[int, str, float]
Unions of a single argument vanish, e.g.:
Union[int] == int # The constructor actually returns int
Redundant arguments are skipped, e.g.:
Union[int, str, int] == Union[int, str]
When comparing unions, the argument order is ignored, e.g.:
Union[int, str] == Union[str, int]
When two arguments have a subclass relationship, the least derived argument is kept, e.g.:
class Employee: pass class Manager(Employee): pass Union[int, Employee, Manager] == Union[int, Employee] Union[Manager, int, Employee] == Union[int, Employee] Union[Employee, Manager] == Employee
Similar for object:
Union[int, object] == object
You cannot subclass or instantiate a union.
You can use Optional[X] as a shorthand for Union[X, None].
-
anyio.abc.
AnyByteSendStream
= typing.Union[anyio.abc.ObjectSendStream[bytes], anyio.abc.ByteSendStream]¶ Union type; Union[X, Y] means either X or Y.
To define a union, use e.g. Union[int, str]. Details:
The arguments must be types and there must be at least one.
None as an argument is a special case and is replaced by type(None).
Unions of unions are flattened, e.g.:
Union[Union[int, str], float] == Union[int, str, float]
Unions of a single argument vanish, e.g.:
Union[int] == int # The constructor actually returns int
Redundant arguments are skipped, e.g.:
Union[int, str, int] == Union[int, str]
When comparing unions, the argument order is ignored, e.g.:
Union[int, str] == Union[str, int]
When two arguments have a subclass relationship, the least derived argument is kept, e.g.:
class Employee: pass class Manager(Employee): pass Union[int, Employee, Manager] == Union[int, Employee] Union[Manager, int, Employee] == Union[int, Employee] Union[Employee, Manager] == Employee
Similar for object:
Union[int, object] == object
You cannot subclass or instantiate a union.
You can use Optional[X] as a shorthand for Union[X, None].
-
anyio.abc.
AnyByteStream
= typing.Union[anyio.abc.ObjectStream[bytes], anyio.abc.ByteStream]¶ Union type; Union[X, Y] means either X or Y.
To define a union, use e.g. Union[int, str]. Details:
The arguments must be types and there must be at least one.
None as an argument is a special case and is replaced by type(None).
Unions of unions are flattened, e.g.:
Union[Union[int, str], float] == Union[int, str, float]
Unions of a single argument vanish, e.g.:
Union[int] == int # The constructor actually returns int
Redundant arguments are skipped, e.g.:
Union[int, str, int] == Union[int, str]
When comparing unions, the argument order is ignored, e.g.:
Union[int, str] == Union[str, int]
When two arguments have a subclass relationship, the least derived argument is kept, e.g.:
class Employee: pass class Manager(Employee): pass Union[int, Employee, Manager] == Union[int, Employee] Union[Manager, int, Employee] == Union[int, Employee] Union[Employee, Manager] == Employee
Similar for object:
Union[int, object] == object
You cannot subclass or instantiate a union.
You can use Optional[X] as a shorthand for Union[X, None].
-
class
anyio.streams.buffered.
BufferedByteReceiveStream
(receive_stream)¶ Bases:
anyio.abc.ByteReceiveStream
Wraps any bytes-based receive stream and uses a buffer to provide sophisticated receiving capabilities in the form of a byte stream.
-
property
extra_attributes
¶ A mapping of the extra attributes to callables that return the corresponding values.
If the provider wraps another provider, the attributes from that wrapper should also be included in the returned mapping (but the wrapper may override the callables from the wrapped instance).
-
async
receive
(max_bytes=65536)¶ Receive at most
max_bytes
bytes from the peer.- Parameters
max_bytes (
int
) – maximum number of bytes to receive- Return type
- Returns
the received bytes
- Raises
EndOfStream – if this stream has been closed from the other end
-
async
receive_exactly
(nbytes)¶ Read exactly the given amount of bytes from the stream.
- Parameters
nbytes (
int
) – the number of bytes to read- Return type
- Returns
the bytes read
- Raises
IncompleteRead – if the stream was closed before the requested amount of bytes could be read from the stream
-
async
receive_until
(delimiter, max_bytes)¶ Read from the stream until the delimiter is found or max_bytes have been read.
- Parameters
delimiter (
bytes
) – the marker to look for in the streammax_bytes (
int
) – maximum number of bytes that will be read before raisingDelimiterNotFound
- Return type
- Returns
the bytes read (not including the delimiter)
- Raises
IncompleteRead – if the stream was closed before the delimiter was found
DelimiterNotFound – if the delimiter is not found within the bytes read up to the maximum allowed
-
property
-
class
anyio.streams.memory.
MemoryObjectReceiveStream
(_state)¶ Bases:
Generic
[typing.T_Item
],anyio.abc.ObjectReceiveStream
[typing.T_Item
]-
clone
()¶ Create a clone of this receive stream.
Each clone can be closed separately. Only when all clones have been closed will the receiving end of the memory stream be considered closed by the sending ends.
- Return type
- Returns
the cloned stream
-
async
receive
()¶ Receive the next item.
- Raises
ClosedResourceError – if the receive stream has been explicitly closed
EndOfStream – if this stream has been closed from the other end
BrokenResourceError – if this stream has been rendered unusable due to external causes
- Return type
~T_Item
-
async
receive_nowait
()¶ Receive the next item if it can be done without waiting.
- Return type
~T_Item
- Returns
the received item
- Raises
ClosedResourceError – if this send stream has been closed
EndOfStream – if the buffer is empty and this stream has been closed from the sending end
WouldBlock – if there are no items in the buffer and no tasks waiting to send
-
-
class
anyio.streams.memory.
MemoryObjectSendStream
(_state)¶ Bases:
Generic
[typing.T_Item
],anyio.abc.ObjectSendStream
[typing.T_Item
]-
clone
()¶ Create a clone of this send stream.
Each clone can be closed separately. Only when all clones have been closed will the sending end of the memory stream be considered closed by the receiving ends.
- Return type
- Returns
the cloned stream
-
async
send
(item)¶ Send an item to the peer(s).
- Parameters
item (~T_Item) – the item to send
- Raises
ClosedResourceError – if the send stream has been explicitly closed
BrokenResourceError – if this stream has been rendered unusable due to external causes
- Return type
-
async
send_nowait
(item)¶ Send an item immediately if it can be done without waiting.
- Parameters
item (~T_Item) – the item to send
- Raises
ClosedResourceError – if this send stream has been closed
BrokenResourceError – if the stream has been closed from the receiving end
WouldBlock – if the buffer is full and there are no tasks waiting to receive
- Return type
-
-
class
anyio.streams.stapled.
MultiListener
(listeners)¶ Bases:
Generic
[typing.T_Stream
],anyio.abc.Listener
[typing.T_Stream
]Combines multiple listeners into one, serving connections from all of them at once.
Any MultiListeners in the given collection of listeners will have their listeners moved into this one.
Extra attributes are provided from each listener, with each successive listener overriding any conflicting attributes from the previous one.
- Parameters
listeners (Sequence[Listener[T_Stream]]) – listeners to serve
-
property
extra_attributes
¶ A mapping of the extra attributes to callables that return the corresponding values.
If the provider wraps another provider, the attributes from that wrapper should also be included in the returned mapping (but the wrapper may override the callables from the wrapped instance).
-
async
serve
(handler, task_group=None)¶ Accept incoming connections as they come in and spawn tasks to handle them.
- Parameters
- Return type
-
class
anyio.streams.stapled.
StapledByteStream
(send_stream, receive_stream)¶ Bases:
anyio.abc.ByteStream
Combines two byte streams into a single, bidirectional byte stream.
Extra attributes will be provided from both streams, with the receive stream providing the values in case of a conflict.
- Parameters
send_stream (ByteSendStream) – the sending byte stream
receive_stream (ByteReceiveStream) – the receiving byte stream
-
property
extra_attributes
¶ A mapping of the extra attributes to callables that return the corresponding values.
If the provider wraps another provider, the attributes from that wrapper should also be included in the returned mapping (but the wrapper may override the callables from the wrapped instance).
-
async
receive
(max_bytes=65536)¶ Receive at most
max_bytes
bytes from the peer.- Parameters
max_bytes (
int
) – maximum number of bytes to receive- Return type
- Returns
the received bytes
- Raises
EndOfStream – if this stream has been closed from the other end
-
async
send
(item)¶ Send the given bytes to the peer.
-
class
anyio.streams.stapled.
StapledObjectStream
(send_stream, receive_stream)¶ Bases:
Generic
[typing.T_Item
],anyio.abc.ObjectStream
[typing.T_Item
]Combines two object streams into a single, bidirectional object stream.
Extra attributes will be provided from both streams, with the receive stream providing the values in case of a conflict.
- Parameters
send_stream (ObjectSendStream) – the sending object stream
receive_stream (ObjectReceiveStream) – the receiving object stream
-
property
extra_attributes
¶ A mapping of the extra attributes to callables that return the corresponding values.
If the provider wraps another provider, the attributes from that wrapper should also be included in the returned mapping (but the wrapper may override the callables from the wrapped instance).
-
async
receive
()¶ Receive the next item.
- Raises
ClosedResourceError – if the receive stream has been explicitly closed
EndOfStream – if this stream has been closed from the other end
BrokenResourceError – if this stream has been rendered unusable due to external causes
- Return type
~T_Item
-
async
send
(item)¶ Send an item to the peer(s).
- Parameters
item (~T_Item) – the item to send
- Raises
ClosedResourceError – if the send stream has been explicitly closed
BrokenResourceError – if this stream has been rendered unusable due to external causes
- Return type
-
class
anyio.streams.text.
TextReceiveStream
(transport_stream, encoding='utf-8', errors='strict')¶ Bases:
anyio.abc.ObjectReceiveStream
[str
]Stream wrapper that decodes bytes to strings using the given encoding.
Decoding is done using
IncrementalDecoder
which returns any completely received unicode characters as soon as they come in.- Parameters
transport_stream (
Union
[ObjectReceiveStream
[bytes
],ByteReceiveStream
]) – any bytes-based receive streamencoding (
InitVar
) – character encoding to use for decoding bytes to strings (defaults toutf-8
)errors (
InitVar
) – handling scheme for decoding errors (defaults tostrict
; see the codecs module documentation for a comprehensive list of options)
-
property
extra_attributes
¶ A mapping of the extra attributes to callables that return the corresponding values.
If the provider wraps another provider, the attributes from that wrapper should also be included in the returned mapping (but the wrapper may override the callables from the wrapped instance).
-
async
receive
()¶ Receive the next item.
- Raises
ClosedResourceError – if the receive stream has been explicitly closed
EndOfStream – if this stream has been closed from the other end
BrokenResourceError – if this stream has been rendered unusable due to external causes
- Return type
-
class
anyio.streams.text.
TextSendStream
(transport_stream, encoding='utf-8', errors='strict')¶ Bases:
anyio.abc.ObjectSendStream
[str
]Sends strings to the wrapped stream as bytes using the given encoding.
- Parameters
transport_stream (AnyByteSendStream) – any bytes-based send stream
encoding (str) – character encoding to use for encoding strings to bytes (defaults to
utf-8
)errors (str) – handling scheme for encoding errors (defaults to
strict
; see the codecs module documentation for a comprehensive list of options)
-
property
extra_attributes
¶ A mapping of the extra attributes to callables that return the corresponding values.
If the provider wraps another provider, the attributes from that wrapper should also be included in the returned mapping (but the wrapper may override the callables from the wrapped instance).
-
async
send
(item)¶ Send an item to the peer(s).
- Parameters
item (
str
) – the item to send- Raises
ClosedResourceError – if the send stream has been explicitly closed
BrokenResourceError – if this stream has been rendered unusable due to external causes
- Return type
-
class
anyio.streams.text.
TextStream
(transport_stream, encoding='utf-8', errors='strict')¶ Bases:
anyio.abc.ObjectStream
[str
]A bidirectional stream that decodes bytes to strings on receive and encodes strings to bytes on send.
Extra attributes will be provided from both streams, with the receive stream providing the values in case of a conflict.
- Parameters
transport_stream (AnyByteStream) – any bytes-based stream
encoding (str) – character encoding to use for encoding/decoding strings to/from bytes (defaults to
utf-8
)errors (str) – handling scheme for encoding errors (defaults to
strict
; see the codecs module documentation for a comprehensive list of options)
-
property
extra_attributes
¶ A mapping of the extra attributes to callables that return the corresponding values.
If the provider wraps another provider, the attributes from that wrapper should also be included in the returned mapping (but the wrapper may override the callables from the wrapped instance).
-
async
receive
()¶ Receive the next item.
- Raises
ClosedResourceError – if the receive stream has been explicitly closed
EndOfStream – if this stream has been closed from the other end
BrokenResourceError – if this stream has been rendered unusable due to external causes
- Return type
-
async
send
(item)¶ Send an item to the peer(s).
- Parameters
item (
str
) – the item to send- Raises
ClosedResourceError – if the send stream has been explicitly closed
BrokenResourceError – if this stream has been rendered unusable due to external causes
- Return type
-
class
anyio.streams.tls.
TLSAttribute
¶ Bases:
anyio.TypedAttributeSet
Contains Transport Layer Security related attributes.
-
peer_certificate
: Optional[Dict[str, Union[str, tuple]]] = <object object>¶ the peer certificate in dictionary form (see
ssl.SSLSocket.getpeercert()
for more information)
ciphers shared between both ends of the TLS connection
-
ssl_object
: ssl.SSLObject = <object object>¶ the
SSLObject
used for encryption
-
-
class
anyio.streams.tls.
TLSStream
(transport_stream, standard_compatible, _ssl_object, _read_bio, _write_bio)¶ Bases:
anyio.abc.ByteStream
A stream wrapper that encrypts all sent data and decrypts received data.
This class has no public initializer; use
wrap()
instead. All extra attributes fromTLSAttribute
are supported.- Variables
transport_stream (AnyByteStream) – the wrapped stream
-
property
extra_attributes
¶ A mapping of the extra attributes to callables that return the corresponding values.
If the provider wraps another provider, the attributes from that wrapper should also be included in the returned mapping (but the wrapper may override the callables from the wrapped instance).
-
async
receive
(max_bytes=65536)¶ Receive at most
max_bytes
bytes from the peer.- Parameters
max_bytes (
int
) – maximum number of bytes to receive- Return type
- Returns
the received bytes
- Raises
EndOfStream – if this stream has been closed from the other end
-
async
send
(item)¶ Send the given bytes to the peer.
-
async
send_eof
()¶ Send an end-of-file indication to the peer.
You should not try to send any further data to this stream after calling this method. This method is idempotent (does nothing on successive calls).
- Return type
-
async
unwrap
()¶ Does the TLS closing handshake.
- Return type
Tuple
[Union
[ObjectStream
[bytes
],ByteStream
],bytes
]- Returns
a tuple of (wrapped byte stream, bytes left in the read buffer)
-
async classmethod
wrap
(transport_stream, *, server_side=None, hostname=None, ssl_context=None, standard_compatible=True)¶ Wrap an existing stream with Transport Layer Security.
This performs a TLS handshake with the peer.
- Parameters
transport_stream (
Union
[ObjectStream
[bytes
],ByteStream
]) – a bytes-transporting stream to wrapserver_side (
Optional
[bool
]) –True
if this is the server side of the connection,False
if this is the client side (if omitted, will be set toFalse
ifhostname
has been provided,False
otherwise). Used only to create a default context when an explicit context has not been provided.hostname (
Optional
[str
]) – host name of the peer (if host name checking is desired)ssl_context (
Optional
[SSLContext
]) – the SSLContext object to use (if not provided, a secure default will be created)standard_compatible (
bool
) – ifFalse
, skip the closing handshake when closing the connection, and don’t raise an exception if the peer does the same
- Raises
SSLError – if the TLS handshake fails
- Return type
-
class
anyio.streams.tls.
TLSListener
(listener, ssl_context, standard_compatible=True, handshake_timeout=30)¶ Bases:
anyio.abc.Listener
[anyio.streams.tls.TLSStream
]A convenience listener that wraps another listener and auto-negotiates a TLS session on every accepted connection.
If the TLS handshake times out or raises an exception,
handle_handshake_error()
is called to do whatever post-mortem processing is deemed necessary.Supports only the
standard_compatible
extra attribute.- Parameters
listener (Listener) – the listener to wrap
ssl_context (
SSLContext
) – the SSL context objectstandard_compatible (
bool
) – a flag passed through toTLSStream.wrap()
handshake_timeout (
float
) – time limit for the TLS handshake (passed tofail_after()
)
-
property
extra_attributes
¶ A mapping of the extra attributes to callables that return the corresponding values.
If the provider wraps another provider, the attributes from that wrapper should also be included in the returned mapping (but the wrapper may override the callables from the wrapped instance).
-
async
serve
(handler, task_group=None)¶ Accept incoming connections as they come in and spawn tasks to handle them.
- Parameters
- Return type
Sockets and networking¶
-
async
anyio.
connect_tcp
(remote_host, remote_port, *, local_host=None, tls=False, ssl_context=None, tls_standard_compatible=True, tls_hostname=None, happy_eyeballs_delay=0.25)¶ Connect to a host using the TCP protocol.
This function implements the stateless version of the Happy Eyeballs algorithm (RFC 6555). If
address
is a host name that resolves to multiple IP addresses, each one is tried until one connection attempt succeeds. If the first attempt does not connected within 250 milliseconds, a second attempt is started using the next address in the list, and so on. On IPv6 enabled systems, an IPv6 address (if available) is tried first.When the connection has been established, a TLS handshake will be done if either
ssl_context
ortls_hostname
is notNone
, or iftls
isTrue
.- Parameters
remote_host – the IP address or host name to connect to
remote_port – port on the target host to connect to
local_host – the interface address or name to bind the socket to before connecting
tls –
True
to do a TLS handshake with the connected stream and return aTLSStream
insteadssl_context – the SSL context object to use (if omitted, a default context is created)
tls_standard_compatible – If
True
, performs the TLS shutdown handshake before closing the stream and requires that the server does this as well. Otherwise,SSLEOFError
may be raised during reads from the stream. Some protocols, such as HTTP, require this option to beFalse
. Seewrap_socket()
for details.tls_hostname – host name to check the server certificate against (defaults to the value of
remote_host
)happy_eyeballs_delay – delay (in seconds) before starting the next connection attempt
- Returns
a socket stream object if no TLS handshake was done, otherwise a TLS stream
- Raises
OSError – if the connection attempt fails
-
async
anyio.
connect_unix
(path)¶ Connect to the given UNIX socket.
Not available on Windows.
- Parameters
- Return type
- Returns
a socket stream object
-
async
anyio.
create_tcp_listener
(*, local_host=None, local_port=0, family=<AddressFamily.AF_UNSPEC: 0>, backlog=65536, reuse_port=False)¶ Create a TCP socket listener.
- Parameters
local_port (
int
) – port number to listen onlocal_host (
Union
[str
,IPv4Address
,IPv6Address
,None
]) – IP address of the interface to listen on. If omitted, listen on all IPv4 and IPv6 interfaces. To listen on all interfaces on a specific address family, use0.0.0.0
for IPv4 or::
for IPv6.family (
Literal
[<AddressFamily.AF_UNSPEC: 0>, <AddressFamily.AF_INET: 2>, <AddressFamily.AF_INET6: 10>]) – address family (used ifinterface
was omitted)backlog (
int
) – maximum number of queued incoming connections (up to a maximum of 2**16, or 65536)reuse_port (
bool
) –True
to allow multiple sockets to bind to the same address/port (not supported on Windows)
- Return type
- Returns
a list of listener objects
-
async
anyio.
create_unix_listener
(path, *, mode=None, backlog=65536)¶ Create a UNIX socket listener.
Not available on Windows.
-
async
anyio.
create_udp_socket
(family=<AddressFamily.AF_UNSPEC: 0>, *, local_host=None, local_port=0, reuse_port=False)¶ Create a UDP socket.
If
port
has been given, the socket will be bound to this port on the local machine, making this socket suitable for providing UDP based services.- Parameters
family (
Literal
[<AddressFamily.AF_UNSPEC: 0>, <AddressFamily.AF_INET: 2>, <AddressFamily.AF_INET6: 10>]) – address family (AF_INET
orAF_INET6
) – automatically determined fromlocal_host
if omittedlocal_host (
Union
[str
,IPv4Address
,IPv6Address
,None
]) – IP address or host name of the local interface to bind tolocal_port (
int
) – local port to bind toreuse_port (
bool
) –True
to allow multiple sockets to bind to the same address/port (not supported on Windows)
- Return type
- Returns
a UDP socket
-
async
anyio.
create_connected_udp_socket
(remote_host, remote_port, *, family=<AddressFamily.AF_UNSPEC: 0>, local_host=None, local_port=0, reuse_port=False)¶ Create a connected UDP socket.
Connected UDP sockets can only communicate with the specified remote host/port, and any packets sent from other sources are dropped.
- Parameters
remote_host (
Union
[str
,IPv4Address
,IPv6Address
]) – remote host to set as the default targetremote_port (
int
) – port on the remote host to set as the default targetfamily (
Literal
[<AddressFamily.AF_UNSPEC: 0>, <AddressFamily.AF_INET: 2>, <AddressFamily.AF_INET6: 10>]) – address family (AF_INET
orAF_INET6
) – automatically determined fromlocal_host
orremote_host
if omittedlocal_host (
Union
[str
,IPv4Address
,IPv6Address
,None
]) – IP address or host name of the local interface to bind tolocal_port (
int
) – local port to bind toreuse_port (
bool
) –True
to allow multiple sockets to bind to the same address/port (not supported on Windows)
- Return type
- Returns
a connected UDP socket
-
async
anyio.
getaddrinfo
(host, port, *, family=0, type=0, proto=0, flags=0)¶ Look up a numeric IP address given a host name.
Internationalized domain names are translated according to the (non-transitional) IDNA 2008 standard.
Note
4-tuple IPv6 socket addresses are automatically converted to 2-tuples of (host, port), unlike what
socket.getaddrinfo()
does.- Parameters
- Return type
List
[Tuple
[AddressFamily
,SocketKind
,int
,str
,Tuple
[str
,int
]]]- Returns
list of tuples containing (family, type, proto, canonname, sockaddr)
See also
-
anyio.
getnameinfo
(sockaddr, flags=0)¶ Look up the host name of an IP address.
- Parameters
- Return type
- Returns
a tuple of (host name, service name)
See also
-
anyio.
wait_socket_readable
(sock)¶ Wait until the given socket has data to be read.
This does NOT work on Windows when using the asyncio backend with a proactor event loop (default on py3.8+).
Warning
Only use this on raw sockets that have not been wrapped by any higher level constructs like socket streams!
- Parameters
sock (
socket
) – a socket object- Raises
ClosedResourceError – if the socket was closed while waiting for the socket to become readable
BusyResourceError – if another task is already waiting for the socket to become readable
- Return type
-
anyio.
wait_socket_writable
(sock)¶ Wait until the given socket can be written to.
This does NOT work on Windows when using the asyncio backend with a proactor event loop (default on py3.8+).
Warning
Only use this on raw sockets that have not been wrapped by any higher level constructs like socket streams!
- Parameters
sock (
socket
) – a socket object- Raises
ClosedResourceError – if the socket was closed while waiting for the socket to become writable
BusyResourceError – if another task is already waiting for the socket to become writable
- Return type
-
class
anyio.abc.
SocketAttribute
¶ Bases:
anyio.TypedAttributeSet
-
class
anyio.abc.
SocketStream
¶ Bases:
Generic
[typing.T_SockAddr
],anyio.abc.ByteStream
,anyio.abc.sockets._SocketProvider
[typing.T_SockAddr
]Transports bytes over a socket.
Supports all relevant extra attributes from
SocketAttribute
.
-
class
anyio.abc.
SocketListener
¶ Bases:
Generic
[typing.T_SockAddr
],anyio.abc.streams.Listener
[anyio.abc.sockets.SocketStream
[typing.T_SockAddr
]],anyio.abc.sockets._SocketProvider
[typing.T_SockAddr
]Listens to incoming socket connections.
Supports all relevant extra attributes from
SocketAttribute
.-
abstract async
accept
()¶ Accept an incoming connection.
- Return type
SocketStream
[~T_SockAddr]
-
async
serve
(handler, task_group=None)¶ Accept incoming connections as they come in and spawn tasks to handle them.
- Parameters
- Return type
-
abstract async
-
class
anyio.abc.
UDPSocket
¶ Bases:
anyio.abc.streams.UnreliableObjectStream
[Tuple
[bytes
,Tuple
[str
,int
]]],anyio.abc.sockets._SocketProvider
[Tuple
[str
,int
]]Represents an unconnected UDP socket.
Supports all relevant extra attributes from
SocketAttribute
.
-
class
anyio.abc.
ConnectedUDPSocket
¶ Bases:
anyio.abc.streams.UnreliableObjectStream
[bytes
],anyio.abc.sockets._SocketProvider
[Tuple
[str
,int
]]Represents an connected UDP socket.
Supports all relevant extra attributes from
SocketAttribute
.
Subprocesses¶
-
async
anyio.
run_process
(command, *, input=None, stdout=- 1, stderr=- 1, check=True)¶ Run an external command in a subprocess and wait until it completes.
See also
- Parameters
command (
Union
[str
,Sequence
[str
]]) – either a string to pass to the shell, or an iterable of strings containing the executable name or path and its argumentsinput (
Optional
[bytes
]) – bytes passed to the standard input of the subprocessstdout (
int
) – eithersubprocess.PIPE
orsubprocess.DEVNULL
stderr (
int
) – one ofsubprocess.PIPE
,subprocess.DEVNULL
orsubprocess.STDOUT
check (
bool
) – ifTrue
, raiseCalledProcessError
if the process terminates with a return code other than 0
- Return type
- Returns
an object representing the completed process
- Raises
CalledProcessError – if
check
isTrue
and the process exits with a nonzero return code
-
async
anyio.
open_process
(command, *, stdin=- 1, stdout=- 1, stderr=- 1)¶ Start an external command in a subprocess.
See also
- Parameters
command (
Union
[str
,Sequence
[str
]]) – either a string to pass to the shell, or an iterable of strings containing the executable name or path and its argumentsstdin (
int
) – eithersubprocess.PIPE
orsubprocess.DEVNULL
stdout (
int
) – eithersubprocess.PIPE
orsubprocess.DEVNULL
stderr (
int
) – one ofsubprocess.PIPE
,subprocess.DEVNULL
orsubprocess.STDOUT
- Return type
- Returns
an asynchronous process object
-
class
anyio.abc.
Process
¶ Bases:
anyio.abc.AsyncResource
An asynchronous version of
subprocess.Popen
.-
abstract
kill
()¶ Kills the process.
On Windows, this calls
TerminateProcess()
. On POSIX systems, this sendsSIGKILL
to the process.See also
- Return type
-
abstract property
returncode
¶ The return code of the process. If the process has not yet terminated, this will be
None
.
-
abstract
send_signal
(signal)¶ Send a signal to the subprocess.
See also
- Parameters
signal (
int
) – the signal number (e.g.signal.SIGHUP
)- Return type
-
abstract property
stderr
¶ The stream for the standard error output of the process.
- Return type
-
abstract property
stdin
¶ The stream for the standard input of the process.
- Return type
-
abstract property
stdout
¶ The stream for the standard output of the process.
- Return type
-
abstract
terminate
()¶ Terminates the process, gracefully if possible.
On Windows, this calls
TerminateProcess()
. On POSIX systems, this sendsSIGTERM
to the process.See also
- Return type
-
abstract
Synchronization¶
-
anyio.
create_semaphore
(value)¶ Create an asynchronous semaphore.
-
anyio.
create_event
()¶ Create an asynchronous event object.
- Return type
- Returns
an event object
-
anyio.
create_condition
(lock=None)¶ Create an asynchronous condition.
-
anyio.
create_capacity_limiter
(total_tokens)¶ Create a capacity limiter.
-
class
anyio.abc.
CapacityLimiter
¶ Bases:
object
-
abstract async
acquire
()¶ Acquire a token for the current task, waiting if necessary for one to become available.
- Return type
-
abstract async
acquire_nowait
()¶ Acquire a token for the current task without waiting for one to become available.
- Raises
WouldBlock – if there are no tokens available for borrowing
- Return type
-
abstract async
acquire_on_behalf_of
(borrower)¶ Acquire a token, waiting if necessary for one to become available.
- Parameters
borrower – the entity borrowing a token
- Return type
-
abstract async
acquire_on_behalf_of_nowait
(borrower)¶ Acquire a token without waiting for one to become available.
- Parameters
borrower – the entity borrowing a token
- Raises
WouldBlock – if there are no tokens available for borrowing
- Return type
-
abstract property
available_tokens
¶ The number of tokens currently available to be borrowed
- Return type
-
abstract property
borrowed_tokens
¶ The number of tokens that have currently been borrowed.
- Return type
-
abstract async
release
()¶ Release the token held by the current task. :raises RuntimeError: if the current task has not borrowed a token from this limiter.
- Return type
-
abstract async
release_on_behalf_of
(borrower)¶ Release the token held by the given borrower.
- Raises
RuntimeError – if the borrower has not borrowed a token from this limiter.
- Return type
-
abstract async
set_total_tokens
(value)¶ Set the total number of tokens.
If the total number of tokens is increased, the proportionate number of tasks waiting on this limiter will be granted their tokens.
-
abstract async
Operating system signals¶
-
anyio.
open_signal_receiver
(*signals)¶ Start receiving operating system signals.
- Parameters
signals (
int
) – signals to receive (e.g.signal.SIGINT
)- Return type
- Returns
an asynchronous context manager for an asynchronous iterator which yields signal numbers
Warning
Windows does not support signals natively so it is best to avoid relying on this in cross-platform applications.
Compatibility¶
-
async
anyio.
maybe_async
(__obj)¶ Await on the given object if necessary.
This function is intended to bridge the gap between AnyIO 2.x and 3.x where some functions and methods were converted from coroutine functions into regular functions.
- Returns
the result of awaiting on the object if coroutine, or the object itself otherwise
New in version 2.2.
-
anyio.
maybe_async_cm
(cm)¶ Wrap a regular context manager as an async one if necessary.
This function is intended to bridge the gap between AnyIO 2.x and 3.x where some functions and methods were changed to return regular context managers instead of async ones.
- Parameters
cm (
Union
[ContextManager
[~T],AsyncContextManager
[~T]]) – a regular or async context manager- Return type
- Returns
an async context manager
New in version 2.2.
Testing and debugging¶
-
async
anyio.
get_current_task
()¶ Return the current task.
- Return type
- Returns
a representation of the current task
-
async
anyio.
get_running_tasks
()¶ Return a list of running tasks in the current event loop.
Exceptions¶
-
exception
anyio.
BrokenResourceError
¶ Bases:
Exception
Raised when trying to use a resource that has been rendered unusuable due to external causes (e.g. a send stream whose peer has disconnected).
-
exception
anyio.
BusyResourceError
(action)¶ Bases:
Exception
Raised when two tasks are trying to read from or write to the same resource concurrently.
-
exception
anyio.
ClosedResourceError
¶ Bases:
Exception
Raised when trying to use a resource that has been closed.
-
exception
anyio.
DelimiterNotFound
(max_bytes)¶ Bases:
Exception
Raised during
receive_until()
if the maximum number of bytes has been read without the delimiter being found.
-
exception
anyio.
EndOfStream
¶ Bases:
Exception
Raised when trying to read from a stream that has been closed from the other end.
-
exception
anyio.
ExceptionGroup
¶ Bases:
BaseException
Raised when multiple exceptions have been raised in a task group.
-
exception
anyio.
IncompleteRead
¶ Bases:
Exception
Raised during
receive_exactly()
orreceive_until()
if the connection is closed before the requested amount of bytes has been read.
-
exception
anyio.
TypedAttributeLookupError
¶ Bases:
LookupError
Raised by
extra()
when the given typed attribute is not found and no default value has been given.