How to understand asyncio.gather return_exceptions=False?

[DeaD_EyE]

In the documentation it's described as:

If return_exceptions is False (default), the first raised exception is immediately propagated to the task that awaits on gather(). Other awaitables in the aws sequence won’t be cancelled and will continue to run.

Explained with my own words: If a awaitable raises an error, you won't get results back, the tasks are not cancelled, but the caller have to catch the error.

If return_exceptions is True, exceptions are treated the same as successful results, and aggregated in the result list.

Here both versions explained with code:

import asyncio, time


async def fn1(x):
    await asyncio.sleep(3)
    print(f"fn1 is called with x={x}")
    return f"Hello from fn1: {x}"


async def raise_error(y):
    await asyncio.sleep(2)
    print(f"raise_error is called with y={y}")
    raise asyncio.TimeoutError() # <- function exits here
    # no result
    return f"Hello from raise_error"


async def main():
    print("start:",time.ctime())
    print("return_exceptions=False")
    try:
        result1 = await asyncio.gather(
            fn1("First call"), # <- 1st result
            raise_error("Second call"), # <- here is the error
            fn1("Third call"), # <- 3rd result
            return_exceptions=False, # <- don't return result, if an exception was raised
            # but tasks are not canceled. You can see it with the print function, that
            # fn1 is still called, but you won't get a return value from gather
            )
    except Exception as e:
        print("Catched Exception from gather")
        print("We don't get the result back, but the tasks are not canceled")
    
    # result1 does not exist
    try:
        print('Result1', result1)
    except NameError:
        print('As expected you get a NameError, result1 does not exist')
    
    print()
    print('Sleeping 2 seconds')
    await asyncio.sleep(2)
    print()
    print('return_exceptions=True')
    
    result2 = await asyncio.gather(
            fn1("First call"), # <- 1st result
            raise_error("Second call"), # <- here is the error
            fn1("Third call"), # <- 3rd result will evaluated aswell
            return_exceptions=True, # <- return exceptions as results
        )
    print("result2:", result2)
    await asyncio.sleep(2)
    print("end:",time.ctime())
    


asyncio.run(main())