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
[[Unpack
[TypeVarTuple
]],Awaitable
[TypeVar
(T_Retval
)]]) – a coroutine functionargs (
Unpack
[TypeVarTuple
]) – positional arguments tofunc
backend (
str
) – name of the asynchronous event loop implementation – currently eitherasyncio
ortrio
backend_options (
dict
[str
,Any
] |None
) – keyword arguments to call the backendrun()
implementation with (documented here)
- Return type:
TypeVar
(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.
- async anyio.sleep_forever()
Pause the current task until it’s cancelled.
This is a shortcut for
sleep(math.inf)
. :rtype:None
Added in version 3.1.
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
- 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=<object object>)
Return the value of the given typed extra attribute.
- Parameters:
attribute (
Any
) – the attribute (member of aTypedAttributeSet
) to look fordefault (
object
) – 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
- Return type:
- property extra_attributes: Mapping[T_Attr, Callable[[], T_Attr]]
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.move_on_after(delay, shield=False)
Create a cancel scope with a deadline that expires after the given delay.
- Parameters:
- Return type:
- Returns:
a cancel scope
- anyio.fail_after(delay, shield=False)
Create a context manager which raises a
TimeoutError
if does not finish in time.- Parameters:
- Returns:
a context manager that yields a cancel scope
- Return type:
- 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 (or
float('inf')
if there is no deadline in effect, orfloat('-inf')
if the current scope has been cancelled)- Return type:
- class anyio.CancelScope(*, deadline: float = inf, shield: bool = False)
Bases:
object
Wraps a unit of work that can be made separately cancellable.
- Parameters:
deadline – The time (clock value) when this scope is cancelled automatically
shield –
True
to shield the cancel scope from external cancellation
- property cancelled_caught: bool
True
if this scope suppressed a cancellation exception it itself raised.This is typically used to check if any work was interrupted, or to see if the scope was cancelled due to its deadline being reached. The value will, however, only be
True
if the cancellation was triggered by the scope itself (and not an outer scope).
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
Note
On asyncio, support for eager task factories is considered to be experimental. In particular, they don’t follow the usual semantics of new tasks being scheduled on the next iteration of the event loop, and may thus cause unexpected behavior in code that wasn’t written with such semantics in mind.
- abstract async start(func, *args, name=None)
Start a new task and wait until it signals for readiness.
- Parameters:
- Return type:
- Returns:
the value passed to
task_status.started()
- Raises:
RuntimeError – if the task finishes without calling
task_status.started()
Added in version 3.0.
- abstract start_soon(func, *args, name=None)
Start a new task in this task group.
- Parameters:
- Return type:
Added in version 3.0.
Running code in worker threads
- async anyio.to_thread.run_sync(func, *args, abandon_on_cancel=False, cancellable=None, 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
[[Unpack
[TypeVarTuple
]],TypeVar
(T_Retval
)]) – a callableargs (
Unpack
[TypeVarTuple
]) – positional arguments for the callableabandon_on_cancel (
bool
) –True
to abandon the thread (leaving it to run unchecked on own) if the host task is cancelled,False
to ignore cancellations in the host task until the operation has completed in the worker threadcancellable (
bool
|None
) – deprecated alias ofabandon_on_cancel
; will overrideabandon_on_cancel
if both parameters are passedlimiter (
CapacityLimiter
|None
) – capacity limiter to use to limit the total amount of threads running (if omitted, the default limiter is used)
- Return type:
TypeVar
(T_Retval
)- Returns:
an awaitable that yields the return value of the function.
- anyio.to_thread.current_default_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
Running code in worker processes
- async anyio.to_process.run_sync(func, *args, cancellable=False, limiter=None)
Call the given function with the given arguments in a worker process.
If the
cancellable
option is enabled and the task waiting for its completion is cancelled, the worker process running it will be abruptly terminated using SIGKILL (orterminateProcess()
on Windows).- Parameters:
func (
Callable
[[Unpack
[TypeVarTuple
]],TypeVar
(T_Retval
)]) – a callableargs (
Unpack
[TypeVarTuple
]) – positional arguments for the callablecancellable (
bool
) –True
to allow cancellation of the operation while it’s runninglimiter (
CapacityLimiter
|None
) – capacity limiter to use to limit the total amount of processes running (if omitted, the default limiter is used)
- Return type:
TypeVar
(T_Retval
)- Returns:
an awaitable that yields the return value of the function.
- anyio.to_process.current_default_process_limiter()
Return the capacity limiter that is used by default to limit the number of worker processes.
- Return type:
- Returns:
a capacity limiter object
Running asynchronous code from other threads
- anyio.from_thread.run(func, *args)
Call a coroutine function from a worker thread.
- anyio.from_thread.run_sync(func, *args)
Call a function in the event loop thread from a worker thread.
- anyio.from_thread.check_cancelled()
Check if the cancel scope of the host task’s running the current worker thread has been cancelled.
If the host task’s current cancel scope has indeed been cancelled, the backend-specific cancellation exception will be raised.
- Raises:
RuntimeError – if the current thread was not spawned by
to_thread.run_sync()
- Return type:
- anyio.from_thread.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()
.- Parameters:
- Return type:
- Returns:
a context manager that yields a blocking portal
Changed in version 3.0: Usage as a context manager is now required.
- class anyio.from_thread.BlockingPortal
Bases:
object
An object 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.
- start_task(func, *args, name=None)
Start a task in the portal’s task group and wait until it signals for readiness.
This method works the same way as
abc.TaskGroup.start()
.- Parameters:
- Returns:
a tuple of (future, task_status_value) where the
task_status_value
is the value passed totask_status.started()
from within the target function- Return type:
tuple[concurrent.futures.Future[T_Retval], Any]
Added in version 3.0.
- start_task_soon(func, *args, name=None)
Start 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:
- 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
- Return type:
concurrent.futures.Future[T_Retval]
Added in version 3.0.
- 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()
.
- 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 (
AbstractAsyncContextManager
[TypeVar
(T_co
, covariant=True)]) – an asynchronous context manager- Return type:
AbstractContextManager
[TypeVar
(T_co
, covariant=True)]- Returns:
a synchronous context manager
Added in version 2.1.
- class anyio.from_thread.BlockingPortalProvider(backend='asyncio', backend_options=None)
Bases:
object
A manager for a blocking portal. Used as a context manager. The first thread to enter this context manager causes a blocking portal to be started with the specific parameters, and the last thread to exit causes the portal to be shut down. Thus, there will be exactly one blocking portal running in this context as long as at least one thread has entered this context manager.
The parameters are the same as for
run()
.- Parameters:
Added in version 4.4.
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()
.
- anyio.wrap_file(file)
Wrap an existing file as an asynchronous file.
- class anyio.AsyncFile(fp)
Bases:
AsyncResource
,Generic
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 open_file(...) as f: async for line in f: print(line)
- class anyio.Path(*args)
Bases:
object
An asynchronous version of
pathlib.Path
.This class cannot be substituted for
pathlib.Path
orpathlib.PurePath
, but it is compatible with theos.PathLike
interface.It implements the Python 3.10 version of
pathlib.Path
interface, except for the deprecatedlink_to()
method.Some methods may be unavailable or have limited functionality, based on the Python version:
from_uri()
(available on Python 3.13 or later)full_match()
(available on Python 3.13 or later)is_junction()
(available on Python 3.12 or later)match()
(thecase_sensitive
paramater is only available on Python 3.13 or later)relative_to()
(thewalk_up
parameter is only available on Python 3.12 or later)walk()
(available on Python 3.12 or later)
Any methods that do disk I/O need to be awaited on. These methods are:
Additionally, the following methods return an async iterator yielding
Path
objects:
Streams and stream wrappers
- anyio.create_memory_object_stream(max_buffer_size: float = 0, item_type: object = None) tuple[MemoryObjectSendStream[T_Item], MemoryObjectReceiveStream[T_Item]]
Create a memory object stream.
The stream’s item type can be annotated like
create_memory_object_stream[T_Item]()
.- Parameters:
max_buffer_size – number of items held in the buffer until
send()
starts blockingitem_type –
old way of marking the streams with the right generic type for static typing (does nothing on AnyIO 4)
Deprecated since version 4.0: Use
create_memory_object_stream[YourItemType](...)
instead.
- Returns:
a tuple of (send stream, receive stream)
- class anyio.abc.UnreliableObjectReceiveStream
Bases:
Generic
[T_co
],AsyncResource
,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:
TypeVar
(T_co
, covariant=True)
- class anyio.abc.UnreliableObjectSendStream
Bases:
Generic
[T_contra
],AsyncResource
,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 (
TypeVar
(T_contra
, contravariant=True)) – 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.abc.UnreliableObjectStream
Bases:
UnreliableObjectReceiveStream
[T_Item
],UnreliableObjectSendStream
[T_Item
]A bidirectional message stream which does not guarantee the order or reliability of message delivery.
- class anyio.abc.ObjectReceiveStream
Bases:
UnreliableObjectReceiveStream
[T_co
]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:
UnreliableObjectSendStream
[T_contra
]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:
ObjectReceiveStream
[T_Item
],ObjectSendStream
[T_Item
],UnreliableObjectStream
[T_Item
]A bidirectional message stream which guarantees the order and reliability of message delivery.
- class anyio.abc.ByteReceiveStream
Bases:
AsyncResource
,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.Note
Implementors of this interface should not return an empty
bytes
object, and users should ignore them.- 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
- class anyio.abc.ByteSendStream
Bases:
AsyncResource
,TypedAttributeProvider
An interface for sending bytes to a single peer.
- class anyio.abc.ByteStream
Bases:
ByteReceiveStream
,ByteSendStream
A bidirectional byte stream.
- class anyio.abc.Listener
Bases:
Generic
[T_co
],AsyncResource
,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 start tasks to handle them.
- Parameters:
- Return type:
- anyio.abc.AnyUnreliableByteReceiveStream
alias of
UnreliableObjectReceiveStream
[bytes
] |ByteReceiveStream
- anyio.abc.AnyUnreliableByteSendStream
alias of
UnreliableObjectSendStream
[bytes
] |ByteSendStream
- anyio.abc.AnyUnreliableByteStream
alias of
UnreliableObjectStream
[bytes
] |ByteStream
- anyio.abc.AnyByteReceiveStream
alias of
ObjectReceiveStream
[bytes
] |ByteReceiveStream
- anyio.abc.AnyByteSendStream
alias of
ObjectSendStream
[bytes
] |ByteSendStream
- anyio.abc.AnyByteStream
alias of
ObjectStream
[bytes
] |ByteStream
- class anyio.streams.buffered.BufferedByteReceiveStream(receive_stream)
Bases:
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: Mapping[Any, Callable[[], Any]]
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.Note
Implementors of this interface should not return an empty
bytes
object, and users should ignore them.- 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
- class anyio.streams.file.FileStreamAttribute
Bases:
TypedAttributeSet
- class anyio.streams.file.FileReadStream(file)
Bases:
_BaseFileStream
,ByteReceiveStream
A byte stream that reads from a file in the file system.
- Parameters:
file (
BinaryIO
) – a file that has been opened for reading in binary mode
Added in version 3.0.
- async classmethod from_path(path)
Create a file read stream by opening the given file.
- Parameters:
- Return type:
- async receive(max_bytes=65536)
Receive at most
max_bytes
bytes from the peer.Note
Implementors of this interface should not return an empty
bytes
object, and users should ignore them.- 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 seek(position, whence=0)
Seek the file to the given position.
See also
Note
Not all file descriptors are seekable.
- class anyio.streams.file.FileWriteStream(file)
Bases:
_BaseFileStream
,ByteSendStream
A byte stream that writes to a file in the file system.
- Parameters:
file (
BinaryIO
) – a file that has been opened for writing in binary mode
Added in version 3.0.
- async classmethod from_path(path, append=False)
Create a file write stream by opening the given file for writing.
- Parameters:
- Return type:
- class anyio.streams.memory.MemoryObjectReceiveStream(_state)
Bases:
Generic
[T_co
],ObjectReceiveStream
[T_co
]- 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:
MemoryObjectReceiveStream
[TypeVar
(T_co
, covariant=True)]- Returns:
the cloned stream
- close()
Close the stream.
This works the exact same way as
aclose()
, but is provided as a special case for the benefit of synchronous callbacks.- Return type:
- 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:
TypeVar
(T_co
, covariant=True)
- receive_nowait()
Receive the next item if it can be done without waiting.
- Return type:
TypeVar
(T_co
, covariant=True)- 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
- statistics()
Return statistics about the current state of this stream. :rtype:
MemoryObjectStreamStatistics
Added in version 3.0.
- class anyio.streams.memory.MemoryObjectSendStream(_state)
Bases:
Generic
[T_contra
],ObjectSendStream
[T_contra
]- 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:
MemoryObjectSendStream
[TypeVar
(T_contra
, contravariant=True)]- Returns:
the cloned stream
- close()
Close the stream.
This works the exact same way as
aclose()
, but is provided as a special case for the benefit of synchronous callbacks.- Return type:
- async send(item)
Send an item to the stream.
If the buffer is full, this method blocks until there is again room in the buffer or the item can be sent directly to a receiver.
- Parameters:
item (
TypeVar
(T_contra
, contravariant=True)) – the item to send- Raises:
ClosedResourceError – if this send stream has been closed
BrokenResourceError – if the stream has been closed from the receiving end
- Return type:
- send_nowait(item)
Send an item immediately if it can be done without waiting.
- Parameters:
item (
TypeVar
(T_contra
, contravariant=True)) – 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:
- statistics()
Return statistics about the current state of this stream. :rtype:
MemoryObjectStreamStatistics
Added in version 3.0.
- class anyio.streams.memory.MemoryObjectStreamStatistics(current_buffer_used, max_buffer_size, open_send_streams, open_receive_streams, tasks_waiting_send, tasks_waiting_receive)
Bases:
NamedTuple
-
tasks_waiting_receive:
int
number of tasks blocked on
MemoryObjectReceiveStream.receive()
-
tasks_waiting_send:
int
number of tasks blocked on
MemoryObjectSendStream.send()
-
tasks_waiting_receive:
- class anyio.streams.stapled.MultiListener(listeners)
Bases:
Generic
[T_Stream
],Listener
[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: Mapping[Any, Callable[[], Any]]
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 start tasks to handle them.
- Parameters:
- Return type:
- class anyio.streams.stapled.StapledByteStream(send_stream, receive_stream)
Bases:
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: Mapping[Any, Callable[[], Any]]
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.Note
Implementors of this interface should not return an empty
bytes
object, and users should ignore them.- 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
[T_Item
],ObjectStream
[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: Mapping[Any, Callable[[], Any]]
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:
TypeVar
(T_Item
)
- async send(item)
Send an item to the peer(s).
- Parameters:
item (
TypeVar
(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:
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: Mapping[Any, Callable[[], Any]]
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:
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: Mapping[Any, Callable[[], Any]]
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:
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: Mapping[Any, Callable[[], Any]]
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:
TypedAttributeSet
Contains Transport Layer Security related attributes.
ciphers shared by the client during the TLS handshake (
None
if this is the client side)
- class anyio.streams.tls.TLSStream(transport_stream, standard_compatible, _ssl_object, _read_bio, _write_bio)
Bases:
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: Mapping[Any, Callable[[], Any]]
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.Note
Implementors of this interface should not return an empty
bytes
object, and users should ignore them.- 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 (
bool
|None
) –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 (
str
|None
) – host name of the peer (if host name checking is desired)ssl_context (
SSLContext
|None
) – 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)
-
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: Mapping[Any, Callable[[], Any]]
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 static handle_handshake_error(exc, stream)
Handle an exception raised during the TLS handshake.
This method does 3 things:
Forcefully closes the original stream
Logs the exception (unless it was a cancellation exception) using the
anyio.streams.tls
loggerReraises the exception if it was a base exception or a cancellation exception
- Parameters:
exc (
BaseException
) – the exceptionstream (
Union
[ObjectStream
[bytes
],ByteStream
]) – the original stream
- Return type:
- async serve(handler, task_group=None)
Accept incoming connections as they come in and start 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
remote_host
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 (
Union
[str
,IPv4Address
,IPv6Address
]) – the IP address or host name to connect toremote_port (
int
) – port on the target host to connect tolocal_host (
Union
[str
,IPv4Address
,IPv6Address
,None
]) – the interface address or name to bind the socket to before connectingtls (
bool
) –True
to do a TLS handshake with the connected stream and return aTLSStream
insteadssl_context (
SSLContext
|None
) – the SSL context object to use (if omitted, a default context is created)tls_standard_compatible (
bool
) – IfTrue
, 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 (
str
|None
) – host name to check the server certificate against (defaults to the value ofremote_host
)happy_eyeballs_delay (
float
) – delay (in seconds) before starting the next connection attempt
- Return type:
- 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, 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 iflocal_host
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.
- Parameters:
- Return type:
- Returns:
a listener object
Changed in version 3.0: If a socket already exists on the file system in the given path, it will be removed first.
- async anyio.create_udp_socket(family=AddressFamily.AF_UNSPEC, *, 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, 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, an 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_readable(obj)
Wait until the given object has data to be read.
On Unix systems,
obj
must either be an integer file descriptor, or else an object with a.fileno()
method which returns an integer file descriptor. Any kind of file descriptor can be passed, though the exact semantics will depend on your kernel. For example, this probably won’t do anything useful for on-disk files.On Windows systems,
obj
must either be an integerSOCKET
handle, or else an object with a.fileno()
method which returns an integerSOCKET
handle. File descriptors aren’t supported, and neither are handles that refer to anything besides aSOCKET
.On backends where this functionality is not natively provided (asyncio
ProactorEventLoop
on Windows), it is provided using a separate selector thread which is set to shut down when the interpreter shuts down.Warning
Don’t use this on raw sockets that have been wrapped by any higher level constructs like socket streams!
- Parameters:
obj (
object
) – an object with a.fileno()
method or an integer handle- Raises:
ClosedResourceError – if the object was closed while waiting for the object to become readable
BusyResourceError – if another task is already waiting for the object to become readable
- Return type:
- anyio.wait_socket_readable(sock)
Deprecated since version 4.7.0: Use
wait_readable()
instead.Wait until the given socket has data to be read.
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)
Deprecated since version 4.7.0: Use
wait_writable()
instead.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:
- anyio.wait_writable(obj)
Wait until the given object can be written to.
- Parameters:
obj (
FileDescriptorLike
) – an object with a.fileno()
method or an integer handle- Raises:
ClosedResourceError – if the object was closed while waiting for the object to become writable
BusyResourceError – if another task is already waiting for the object to become writable
- Return type:
See also
See the documentation of
wait_readable()
for the definition ofobj
and notes on backend compatibility.Warning
Don’t use this on raw sockets that have been wrapped by any higher level constructs like socket streams!
- class anyio.abc.SocketAttribute
Bases:
TypedAttributeSet
- class anyio.abc.SocketStream
Bases:
ByteStream
,_SocketProvider
Transports bytes over a socket.
Supports all relevant extra attributes from
SocketAttribute
.
- class anyio.abc.SocketListener
Bases:
Listener
[SocketStream
],_SocketProvider
Listens to incoming socket connections.
Supports all relevant extra attributes from
SocketAttribute
.- abstract async accept()
Accept an incoming connection.
- Return type:
- async serve(handler, task_group=None)
Accept incoming connections as they come in and start tasks to handle them.
- Parameters:
handler (
Callable
[[SocketStream
],Any
]) – a callable that will be used to handle each accepted connectiontask_group (
TaskGroup
|None
) – the task group that will be used to start tasks for handling each accepted connection (if omitted, an ad-hoc task group will be created)
- Return type:
- class anyio.abc.UDPSocket
Bases:
UnreliableObjectStream
[tuple
[bytes
,tuple
[str
,int
]]],_SocketProvider
Represents an unconnected UDP socket.
Supports all relevant extra attributes from
SocketAttribute
.
- class anyio.abc.ConnectedUDPSocket
Bases:
UnreliableObjectStream
[bytes
],_SocketProvider
Represents an connected UDP socket.
Supports all relevant extra attributes from
SocketAttribute
.
- class anyio.abc.UNIXSocketStream
Bases:
SocketStream
- abstract async receive_fds(msglen, maxfds)
Receive file descriptors along with a message from the peer.
Subprocesses
- async anyio.run_process(command, *, input=None, stdout=-1, stderr=-1, check=True, cwd=None, env=None, startupinfo=None, creationflags=0, start_new_session=False, pass_fds=(), user=None, group=None, extra_groups=None, umask=-1)
Run an external command in a subprocess and wait until it completes.
See also
- Parameters:
command (
Union
[str
,bytes
,PathLike
[str
],PathLike
[bytes
],Sequence
[Union
[str
,bytes
,PathLike
[str
],PathLike
[bytes
]]]]) – either a string to pass to the shell, or an iterable of strings containing the executable name or path and its argumentsinput (
bytes
|None
) – bytes passed to the standard input of the subprocessstdout (
Union
[int
,IO
[Any
],None
]) – one ofsubprocess.PIPE
,subprocess.DEVNULL
, a file-like object, or Nonestderr (
Union
[int
,IO
[Any
],None
]) – one ofsubprocess.PIPE
,subprocess.DEVNULL
,subprocess.STDOUT
, a file-like object, or Nonecheck (
bool
) – ifTrue
, raiseCalledProcessError
if the process terminates with a return code other than 0cwd (
Union
[str
,bytes
,PathLike
[str
],PathLike
[bytes
],None
]) – If notNone
, change the working directory to this before running the commandenv (
Mapping
[str
,str
] |None
) – if notNone
, this mapping replaces the inherited environment variables from the parent processstartupinfo (
Any
) – an instance ofsubprocess.STARTUPINFO
that can be used to specify process startup parameters (Windows only)creationflags (
int
) – flags that can be used to control the creation of the subprocess (seesubprocess.Popen
for the specifics)start_new_session (
bool
) – iftrue
the setsid() system call will be made in the child process prior to the execution of the subprocess. (POSIX only)pass_fds (
Sequence
[int
]) – sequence of file descriptors to keep open between the parent and child processes. (POSIX only)user (
str
|int
|None
) – effective user to run the process as (Python >= 3.9, POSIX only)group (
str
|int
|None
) – effective group to run the process as (Python >= 3.9, POSIX only)extra_groups (
Iterable
[str
|int
] |None
) – supplementary groups to set in the subprocess (Python >= 3.9, POSIX only)umask (
int
) – if not negative, this umask is applied in the child process before running the given command (Python >= 3.9, POSIX only)
- 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, cwd=None, env=None, startupinfo=None, creationflags=0, start_new_session=False, pass_fds=(), user=None, group=None, extra_groups=None, umask=-1)
Start an external command in a subprocess.
See also
- Parameters:
command (
Union
[str
,bytes
,PathLike
[str
],PathLike
[bytes
],Sequence
[Union
[str
,bytes
,PathLike
[str
],PathLike
[bytes
]]]]) – either a string to pass to the shell, or an iterable of strings containing the executable name or path and its argumentsstdin (
Union
[int
,IO
[Any
],None
]) – one ofsubprocess.PIPE
,subprocess.DEVNULL
, a file-like object, orNone
stdout (
Union
[int
,IO
[Any
],None
]) – one ofsubprocess.PIPE
,subprocess.DEVNULL
, a file-like object, orNone
stderr (
Union
[int
,IO
[Any
],None
]) – one ofsubprocess.PIPE
,subprocess.DEVNULL
,subprocess.STDOUT
, a file-like object, orNone
cwd (
Union
[str
,bytes
,PathLike
[str
],PathLike
[bytes
],None
]) – If notNone
, the working directory is changed before executingenv (
Mapping
[str
,str
] |None
) – If env is notNone
, it must be a mapping that defines the environment variables for the new processcreationflags (
int
) – flags that can be used to control the creation of the subprocess (seesubprocess.Popen
for the specifics)startupinfo (
Any
) – an instance ofsubprocess.STARTUPINFO
that can be used to specify process startup parameters (Windows only)start_new_session (
bool
) – iftrue
the setsid() system call will be made in the child process prior to the execution of the subprocess. (POSIX only)pass_fds (
Sequence
[int
]) – sequence of file descriptors to keep open between the parent and child processes. (POSIX only)user (
str
|int
|None
) – effective user to run the process as (POSIX only)group (
str
|int
|None
) – effective group to run the process as (POSIX only)extra_groups (
Iterable
[str
|int
] |None
) – supplementary groups to set in the subprocess (POSIX only)umask (
int
) – if not negative, this umask is applied in the child process before running the given command (POSIX only)
- Return type:
- Returns:
an asynchronous process object
- class anyio.abc.Process
Bases:
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. :rtype:None
See also
- abstract property returncode: int | None
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 (
Signals
) – the signal number (e.g.signal.SIGHUP
)- Return type:
- abstract property stderr: ByteReceiveStream | None
The stream for the standard error output of the process.
- abstract property stdin: ByteSendStream | None
The stream for the standard input of the process.
- abstract property stdout: ByteReceiveStream | None
The stream for the standard output of the process.
Synchronization
- class anyio.Event
Bases:
object
- statistics()
Return statistics about the current state of this event.
- Return type:
- class anyio.Lock(*, fast_acquire: bool = False)
Bases:
object
- acquire_nowait()
Acquire the lock, without blocking.
- Raises:
WouldBlock – if the operation would block
- Return type:
- statistics()
Return statistics about the current state of this lock. :rtype:
LockStatistics
Added in version 3.0.
- class anyio.Condition(lock=None)
Bases:
object
- acquire_nowait()
Acquire the underlying lock, without blocking.
- Raises:
WouldBlock – if the operation would block
- Return type:
- statistics()
Return statistics about the current state of this condition. :rtype:
ConditionStatistics
Added in version 3.0.
- class anyio.Semaphore(initial_value, *, max_value=None, fast_acquire=False)
Bases:
object
- acquire_nowait()
Acquire the underlying lock, without blocking.
- Raises:
WouldBlock – if the operation would block
- Return type:
- statistics()
Return statistics about the current state of this semaphore. :rtype:
SemaphoreStatistics
Added in version 3.0.
- class anyio.CapacityLimiter(total_tokens: float)
Bases:
object
- async acquire()
Acquire a token for the current task, waiting if necessary for one to become available.
- Return type:
- 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:
- async acquire_on_behalf_of(borrower)
Acquire a token, waiting if necessary for one to become available.
- acquire_on_behalf_of_nowait(borrower)
Acquire a token without waiting for one to become available.
- Parameters:
borrower (
object
) – the entity borrowing a token- Raises:
WouldBlock – if there are no tokens available for borrowing
- Return type:
- 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:
- 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:
- statistics()
Return statistics about the current state of this limiter. :rtype:
CapacityLimiterStatistics
Added in version 3.0.
- class anyio.ResourceGuard(action='using')
Bases:
object
A context manager for ensuring that a resource is only used by a single task at a time.
Entering this context manager while the previous has not exited it yet will trigger
BusyResourceError
.- Parameters:
action (
str
) – the action to guard against (visible in theBusyResourceError
when triggered, e.g. “Another task is already {action} this resource”)
Added in version 4.1.
- class anyio.ConditionStatistics(tasks_waiting, lock_statistics)
Bases:
object
- Variables:
lock_statistics (LockStatistics) – statistics of the underlying
Lock
- class anyio.CapacityLimiterStatistics(borrowed_tokens, total_tokens, borrowers, tasks_waiting)
Bases:
object
- Variables:
borrowed_tokens (int) – number of tokens currently borrowed by tasks
total_tokens (float) – total number of available tokens
borrowers (tuple) – tasks or other objects currently holding tokens borrowed from this limiter
tasks_waiting (int) – number of tasks waiting on
acquire()
oracquire_on_behalf_of()
Operating system signals
- anyio.open_signal_receiver(*signals)
Start receiving operating system signals.
- Parameters:
signals (
Signals
) – 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.
Warning
On asyncio, this permanently replaces any previous signal handler for the given signals, as set via
add_signal_handler()
.
Low level operations
- async anyio.lowlevel.checkpoint()
Check for cancellation and allow the scheduler to switch to another task.
Equivalent to (but more efficient than):
await checkpoint_if_cancelled() await cancel_shielded_checkpoint()
- Return type:
Added in version 3.0.
- async anyio.lowlevel.checkpoint_if_cancelled()
Enter a checkpoint if the enclosing cancel scope has been cancelled.
This does not allow the scheduler to switch to a different task. :rtype:
None
Added in version 3.0.
- async anyio.lowlevel.cancel_shielded_checkpoint()
Allow the scheduler to switch to another task but without checking for cancellation.
Equivalent to (but potentially more efficient than):
with CancelScope(shield=True): await checkpoint()
- Return type:
Added in version 3.0.
- class anyio.lowlevel.RunVar(name, default=_NoValueSet.NO_VALUE_SET)
Bases:
Generic
[T
]Like a
ContextVar
, except scoped to the running event loop.
Testing and debugging
- class anyio.TaskInfo(id, parent_id, name, coro)
Bases:
object
Represents an asynchronous task.
- Variables:
- anyio.get_current_task()
Return the current task.
- Return type:
- Returns:
a representation of the current task
- 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 unusable 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.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.