AnyIO

AnyIO is an asynchronous networking and concurrency library that works on top of either asyncio or Trio. It implements Trio-like structured concurrency (SC) on top of asyncio and works in harmony with the native SC of Trio itself.

Applications and libraries written against AnyIO’s API will run unmodified on either asyncio or Trio. AnyIO can also be adopted into a library or application incrementally – bit by bit, no full refactoring necessary. It will blend in with the native libraries of your chosen backend.

To find out why you might want to use AnyIO’s APIs instead of asyncio’s, you can read about it here.

Documentation

View full documentation at: https://anyio.readthedocs.io/

Features

AnyIO offers the following functionality:

• Task groups (nurseries in trio terminology)

• High-level networking (TCP, UDP and UNIX sockets)

  • Happy eyeballs algorithm for TCP connections (more robust than that of asyncio on Python 3.8)

  • async/await style UDP sockets (unlike asyncio where you still have to use Transports and Protocols)

• A versatile API for byte streams and object streams

• Inter-task synchronization and communication (locks, conditions, events, semaphores, object streams)

• Worker threads

• Subprocesses

• Subinterpreter support for code parallelization (on Python 3.13 and later)

• Asynchronous file I/O (using worker threads)

• Signal handling

• Asynchronous version of the functools module

AnyIO also comes with its own pytest plugin which also supports asynchronous fixtures. It even works with the popular Hypothesis library.

Security contact information

To report a security vulnerability, please use the Tidelift security contact. Tidelift will coordinate the fix and disclosure.

The manual

• The basics
  • Installation
  • Running async programs
  • Backend specific options
  • Using native async libraries
• Creating and managing tasks
  • Starting and initializing tasks
  • Handling multiple errors in a task group
  • Context propagation
  • Differences with asyncio.TaskGroup
  • Asyncio call graph introspection support
• Cancellation and timeouts
  • Differences between asyncio and AnyIO cancellation semantics
  • Timeouts
  • Shielding
  • Finalization
  • Specifying the reason for cancellation
  • Avoiding cancel scope stack corruption
• Using synchronization primitives
  • Events
  • Semaphores
  • Locks
  • Conditions
  • Capacity limiters
  • Resource guards
  • Queues
• Streams
  • Memory object streams
  • Stapled streams
  • Buffered byte streams
  • Text streams
  • File streams
  • TLS streams
• Using typed attributes
  • Defining your own typed attributes
• Using sockets and streams
  • Working with TCP sockets
  • Working with UNIX sockets
  • Working with UDP sockets
  • Working with UNIX datagram sockets
  • Wrapping existing sockets as streams or listeners
  • Abstracting remote connections using Connectables
• Working with threads
  • Running a function in a worker thread
  • Calling asynchronous code from a worker thread
  • Calling synchronous code from a worker thread
  • Accessing the event loop from a foreign thread
  • Running code from threads using blocking portals
  • Context propagation
  • Adjusting the default maximum worker thread count
  • Reacting to cancellation in worker threads
• Using subprocesses
  • Running one-shot commands
  • Working with processes
  • Running functions in worker processes
• Working with subinterpreters
  • Running a function in a worker interpreter
  • Limitations
• Asynchronous file I/O support
  • Asynchronous path operations
• Asynchronous Temporary File and Directory
  • Temporary File
  • Named Temporary File
  • Spooled Temporary File
  • Temporary Directory
  • Low-Level Temporary File and Directory Creation
• Receiving operating system signals
  • Handling KeyboardInterrupt and SystemExit
• Context manager mix-in classes
  • When should I use the contextmanager mix-in classes?
  • Inheriting context manager classes
• Testing with AnyIO
  • Creating asynchronous tests
  • Specifying the backends to run on
  • Asynchronous fixtures
  • Using async fixtures with higher scopes
  • Built-in utility fixtures
  • Technical details
• API reference
  • Event loop
  • Asynchronous resources
  • Typed attributes
  • Timeouts and cancellation
  • Task groups
  • Running code in worker threads
  • Running code in subinterpreters
  • Running code in worker processes
  • Running asynchronous code from other threads
  • Async file I/O
  • Temporary files and directories
  • Context manager mix-in classes
  • Streams and stream wrappers
  • Sockets and networking
  • Subprocesses
  • Synchronization
  • Operating system signals
  • Asynchronous functools
  • Low level operations
  • Testing and debugging
  • Exceptions
• Migrating from AnyIO 3 to AnyIO 4
  • The non-standard exception group class was removed
  • Task groups now wrap single exceptions in groups
  • Syntax for type annotated memory object streams has changed
  • Event loop factories instead of event loop policies
• Migrating from AnyIO 2 to AnyIO 3
  • Asynchronous functions converted to synchronous
  • Starting tasks
  • Blocking portal changes
  • Synchronization primitives
  • Threading functions moved
• Why you should be using AnyIO APIs instead of asyncio APIs
  • Design problems with task management
  • Design problems with cancellation
  • Design problems with asyncio queues
  • Design problems with the streams API
  • Design problems with the thread API
  • Design problems with signal handling APIs
  • Missing file I/O and async path support
  • Features not in asyncio which you might be interested in
• Frequently Asked Questions
  • Why is Curio not supported as a backend?
  • Why is Twisted not supported as a backend?
• Getting help
• Reporting bugs
• Contributing to AnyIO
  • Making a pull request on Github
• Version history