Let's study Python

Unlock the power of asynchronous programming in Python with the simplicity and efficiency of `asyncio.run`.

Using asyncio.run in Python

Python’s asyncio library is a powerful tool for writing concurrent code using the async and await keywords. It is designed to handle asynchronous I/O operations, making it particularly suitable for network-bound and I/O-bound tasks. One of the key functions in asyncio is asyncio.run(), which simplifies the execution of an asynchronous function from a synchronous context. In this article, we will explore the usage and features of asyncio.run().

What is asyncio.run?

asyncio.run is a high-level function introduced in Python 3.7 to run an asynchronous function. It serves as a modern replacement for lower-level functions like asyncio.get_event_loop() and loop.run_until_complete(). The primary advantage of asyncio.run is its simplicity and ease of use, especially for those who are new to asynchronous programming.

Basic Usage

To understand how asyncio.run works, let’s begin with a basic example. Suppose we have an asynchronous function called main that we want to execute:

import asyncio

async def main():
    print("Hello, asyncio!")
    await asyncio.sleep(1)
    print("Goodbye, asyncio!")

# Running the async function using asyncio.run

In this example:
– We define an asynchronous function main using the async def syntax.
– Inside main, we print a message, wait for one second using await asyncio.sleep(1), and then print another message.
– We use asyncio.run(main()) to execute the main function.

When executed, this code will produce the following output:

Hello, asyncio!
Goodbye, asyncio!

Detailed Explanation

Creating and Executing an Async Function

An asynchronous function in Python is defined using the async keyword. These functions can include await expressions, which pause the function’s execution until the awaited result is available. Here’s a more detailed example:

async def fetch_data():
    print("Fetching data...")
    await asyncio.sleep(2)
    print("Data fetched!")
    return {"data": "sample data"}

async def process_data():
    data = await fetch_data()
    print(f"Processing {data}...")

async def main():
    await process_data()


In this example:
fetch_data is an asynchronous function that simulates a data-fetching operation by sleeping for 2 seconds and then returning a sample dictionary.
process_data is another asynchronous function that awaits the result of fetch_data and then processes it.
main is the top-level asynchronous function that orchestrates the execution of process_data.

Benefits of asyncio.run

  1. Simplicity: asyncio.run abstracts away the complexity of setting up and managing the event loop. You don’t need to worry about creating and closing the loop manually.

  2. Safety: The function ensures that the event loop is properly closed after the asynchronous function completes. This helps prevent resource leaks and other potential issues.

  3. Readability: Code that uses asyncio.run is generally easier to read and understand, especially for those new to asynchronous programming.

Handling Exceptions

When using asyncio.run, any exceptions raised within the asynchronous function are propagated and can be handled using standard try-except blocks. Here’s an example:

async def faulty_function():
    raise ValueError("An error occurred!")

async def main():
        await faulty_function()
    except ValueError as e:
        print(f"Caught an exception: {e}")


In this example, the faulty_function raises a ValueError, which is caught and handled in the main function.


While asyncio.run is highly convenient, it does have some limitations:
– It can only be called once from the main thread. Attempting to call it multiple times will result in a RuntimeError.
– It cannot be called from within another running event loop. If you need to run an asynchronous function from within an existing event loop (e.g., from a Jupyter notebook), you should use await directly or other lower-level asyncio functions.

Advanced Usage

Running Multiple Tasks Concurrently

asyncio.run can be used to run multiple asynchronous tasks concurrently by combining it with asyncio.gather or asyncio.create_task. Here’s an example:

async def task1():
    await asyncio.sleep(1)
    print("Task 1 completed")

async def task2():
    await asyncio.sleep(2)
    print("Task 2 completed")

async def main():
    await asyncio.gather(task1(), task2())


In this example:
task1 and task2 are two asynchronous functions that complete after different delays.
main uses asyncio.gather to run both tasks concurrently. The asyncio.run function then executes main.

Cancelling Tasks

You can also cancel tasks that are running within the event loop. Here’s an example:

async def long_running_task():
        while True:
            print("Task running...")
            await asyncio.sleep(1)
    except asyncio.CancelledError:
        print("Task cancelled")

async def main():
    task = asyncio.create_task(long_running_task())
    await asyncio.sleep(3)
    await task


In this example:
long_running_task is an infinite loop that prints a message every second.
– In main, we create and start the long-running task, let it run for 3 seconds, and then cancel it.


The asyncio.run function is a powerful and convenient way to run asynchronous code in Python. It simplifies the execution of async functions, ensures proper management of the event loop, and enhances readability and maintainability. While it has some limitations, understanding its usage and combining it with other asyncio features allows you to write efficient and concurrent Python programs.

By mastering asyncio.run and other asyncio components, you can leverage the full potential of asynchronous programming in Python, making your code more responsive and capable of handling multiple tasks simultaneously.