Demote the existing alternatives to asyncio.TaskGroup and asyncio.timeout to the low level api docs

what do people think about demoting as_completed, gather, and, create_task in favor of TaskGroup; and demoting wait_for, wait, and, shield in favor of asyncio.timeout

eg out of the high level api index and label them as low level asyncio features

currently the new high level features are missing from the high-level index see: TaskGroup missing from API Index · Issue #95180 · python/cpython · GitHub

Without knowing the APIs well (though I’ve used them on occasion), isn’t this merely promoting an object-oriented API over the flat functions?

I don’t see anything wrong with having simple function-only APIs as well as rich OO APIs (e.g. the random module).

The only real exception would be if most people who use the function API get it wrong, and the fix is to move to the OO API (rather than updating the functions in some way). I think it should be possible to write vast quantities of Python code without having to directly use object members - just passing them around as values.

TaskGroup and asyncio.timeout aren’t just OOP alternatives and work somewhat differently than their pre-existing alternatives in that they do not leak tasks or suppress outside cancellation

In this thread I’m not suggesting to remove any features, just drop them from the high level features index because really they are lower level tools

I’d certainly like to get away from dividing the two categories of API by OO vs functional

The only real exception would be if most people who use the function API get it wrong, and the fix is to move to the OO API

And, yes that has been my experience when seeing these functions used

1 Like

I think it should be possible to write vast quantities of Python code without having to directly use object members - just passing them around as values.

I’m not sure quite what you mean. You could implement a “function” based TaskGroup with:

@contextlib.asynccontextmanager
async def create_task_group():
    async with asyncio.TaskGroup() as tg:
        def start_soon(async_fn, *args, **kwargs):
            coro = async_fn(*args, **kwargs)
            try:
                tg.create_task(coro)
            except:
                coro.close()
                raise

        yield start_soon

timeout is similar:

@contextlib.asynccontextmanager
async def timeout(when):
    async with asyncio.timeout(when) as timer:
        def reschedule():
            timer.reschedule(when)

        yield reschedule