aiodrive 4.0

Collection of utilities for working with asynchronous Python code

Aiodrive

Aiodrive is a Python package for working with asynchronous code that is powered by asyncio and that relies on structured concurrency. It provides various utilities for managing tasks, ensuring programs are gracefully terminated, producing and consuming iterators, and coordinating between threads and asynchronous code.

It supports Python 3.12 and later.

Installation

Aiodrive is available on PyPI under the name aiodrive.

API

• Managing multiple awaitables
  • amass()
    Create an asynchronous generator that yields results from awaitables as they complete.
  • gather()
    Concurrently collect results from multiple awaitables.
  • race()
    Wait for the fastest of a given set of awaitables.
  • volatile_task_group()
    Create a task group that automatically terminates when exiting the context.
• Managing individual awaitables
  • GuaranteedTask
    A variant of Task that that guarantees that the provided awaitable is awaited before any cancellation occurs.
  • ShieldContext
    A class for shielding awaitables from cancellation based on the cancellation request count at the time of instantiation.
  • cancel_task()
    Cancel and await the provided task.
  • possibly_await()
    Wait for the given object if it is awaitable, or otherwise return it as is.
  • prime()
    Prime an awaitable such that as much code as possible is executed immediately.
  • primed()
    Decorate the given function such that it returns a primed awaitable.
  • shield()
    Shield an awaitable from cancellation.
  • shield_wait()
    Shield and await a given awaitable.
  • shield_wait_forever()
    Shield and await the provided awaitable indefinitely, ignoring all cancellation requests.
• Managing async iterators
  • auto_aclosing()
    Create an async context manager that calls the aclose method, if any, on the provided object upon exit.
  • auto_closing()
    Create a context manager that calls the close method, if any, on the provided object upon exit.
  • buffer_aiter()
    Create an asynchronous generator that prefetches items from the given async iterable.
  • collect()
    Collect items of an async iterable into a list.
  • ensure_aiter()
    Create an asynchronous iterator from the provided synchrounous or asynchronous iterable.
  • ensure_daemon()
    Create a new awaitable that raises an exception if the given awaitable returns.
  • map()
    Map an iterable or asynchronous iterable to an asynchronous iterable using the given asynchronous mapper function.
  • reduce()
    Reduce the items from the provided asynchronous iterable.
  • zip_concurrently()
    Zip multiple asynchronous iterables together, yielding tuples of items from each iterable.
• Creating context managers
  • DaemonHandle
    A class that manages the awaiting and cancellation of a daemon awaitable.
  • PendingDaemonHandle
    A class that manages the initialization, awaiting and cancellation of a daemon awaitable.
  • bivalent_context_manager()
    Create a function that returns a context manager which can be used both synchronously and asynchronously.
  • cleaned_up()
    Create a context manager that calls the given asynchronous callback when exiting the context.
  • concurrent_contexts()
    Run multiple context managers concurrently.
  • contextualize()
    Transform an awaitable into an asynchronous context manager.
  • suppress()
    Suppress the specified exceptions in an asynchronous context.
  • use_scope()
    Create a context that locally manages the cancellation of the current task.
  • using_pending_daemon_handle()
    Decorate the provided function such that it returns a PendingDaemonHandle.
  • ensure_correct_cancellation()
    Ensure that a CancelledError is raised if the current task was cancelled while inside the context.
• Managing the program
  • handle_signal()
    Register a signal handler that cancels the current task when the signal is received.
  • run()
    Run an awaitable in a new event loop with enforced structured concurrency.
  • wait_for_signal()
    Wait for a signal.
• Working with processes
  • MultiprocessingProcess
    A class for managing asynchronous tasks in a separate process.
  • recv_connection()
    Receive a message from a multiprocessing Connection.
  • run_in_process()
    Run an asynchronous function in a separate process.
  • start_process()
    Start a process.
• Working with threads
  • Latch
    A primitive similar to Event but that can be awaited for both set and reset occurences.
  • ThreadManager
    A class for managing the execution of awaitables in a separate thread that has its own event loop.
  • ThreadsafeCondition
    A thread-safe condition.
  • ThreadsafeLock
    A thread-safe lock.
  • ThreadsafeState
    A thread-safe primitive for storing and watching a state.
  • launch_in_thread_loop_sync()
    Launch an awaitable in a separate thread with its own event loop.
  • launch_in_thread_loop()
    Launch an awaitable in a separate thread with its own event loop.
  • run_async()
    Synchronously run an awaitable.
  • run_in_thread_loop_contextualized()
    Run an awaitable in a separate thread with its own event loop, using a context manager.
  • run_in_thread_loop_sync()
    Run an awaitable in a separate thread with its own event loop.
  • run_in_thread_loop()
    Run an awaitable in a separate thread with its own event loop.
  • to_thread()
    Run a function in a separate thread.
• Creating awaitables
  • checkpoint()
    Check that the current task was not cancelled.
  • repeat_periodically()
    Create an iterator that yields periodically.
  • suspend()
    Wait for the next iteration of the event loop.
  • wait_forever()
    Wait indefinitely.
• Primitives
  • ConcreteAwaitable
    An awaitable created from an __await__ function.
  • FutureState
    A primitive for storing a future's state.
  • Button
    A class that wakes up registered waiters when called.
  • Cargo
    A class that wakes up registered waiters with a value when called with that value.
  • get_event_loop()
    Get the current event loop, if any.
  • set_event_loop()
    Set the current event loop.
• Working with I/O events
  • KqueueEventManager
    Create a context manager for receiving kqueue events.
  • file_blocking()
    Set the blocking mode of a file.
  • file_unbuffered()
    Set a file to unbuffered mode.
  • get_reader()
    Get a StreamReader for the given file.
  • get_writer()
    Get a StreamWriter for the given file.
  • pipe()
    Pipe data from the source to the destination.
  • prompt()
    Prompt the user for input.
  • watch_path()
    Watch a filesystem path.
  • watch_reader()
    Register a callback to be called when a file is ready for reading.
  • watch_writer()
    Register a callback to be called when a file is ready for writing.
• Networking
  • TCPServer
    A TCP server.
• Miscellaneous
  • NestableLock
    A lock that can be held simultaneously by different callers in the same context.

Notes

Unless specified otherwise, the following requirements and guarantees apply:

• There is no implicit cleanup treatment of async generators, which is unlike certain libraries like asyncstdlib. If required, as is the case for certain functions such as buffer_aiter(), generators must be closed explicitly. For example:

  agen = get_some_async_generator()
  
  async with contextlib.aclosing(agen):
    async for item in agen:
      if some_condition:
        break
  
    # The generator may not be exhausted here and will therefore be closed by contextlib.aclosing().
  

• Awaitables provided as arguments to a function are guaranteed to be awaited as long as the function itself is awaited.
• Awaitables provided as arguments are awaited exactly once.
• Awaitables returned by functions may only be awaited once.
• Asynchronous iterator provided as arguments are guaranteed to only have their __anext__() called once at a time.
• Returned asynchronous iterators may only have their __anext__() called once at a time.
• Returned awaitables may be wrapped as tasks using an eager task factory.
• Arguments must belong to the same event loop as the one in which the function or class is used. Classes must be instantiated and used in the same event loop.
• Functions and classes have a well-defined behavior for at least one cancellation. Some functions and classes support an arbitrary number of cancellations.
• The __len__() method of argument iterables, if any, is maintained on the returned iterables whenever possible.