Coroutines and await Semantics

### The call and the body are two separate events For an ordinary function, `f()` means "run the body now and hand me the result". For a function defined with `async def`, the call means something quite different: CPython creates a **coroutine object** wrapping a fresh, not-yet-started frame and returns it immediately. Not one statement of the body has executed. That single fact explains most of the confusion beginners have with asyncio. ```pycon >>> import asyncio, inspect >>> async def ping(): ... print("running") ... return "pong" ... >>> c = ping() # nothing printed >>> inspect.iscoroutine(c) True >>> asyncio.run(c) running 'pong' ``` The vocabulary matters in an interview. `ping` is the coroutine *function* (`inspect.iscoroutinefunction(ping)` is `True`); `c` is the coroutine *object* (`inspect.iscoroutine(c)` is `True`). Its type is `types.CoroutineType`, and it is registered with `collections.abc.Coroutine`, which itself extends `collections.abc.Awaitable`. ### What actually runs the body A coroutine object is a *driveable* frame, not a scheduled unit of work. Something has to push it forward: * `await c` inside another coroutine - the awaiting coroutine hands control down into `c` and resumes when it finishes. * `asyncio.run(c)` - starts an event loop, wraps the coroutine and drives it to completion. * Handing it to the running loop as a task, which is the topic of scheduling and belongs to its own subject. At the lowest level, a coroutine is driven exactly like a generator: `c.send(None)` advances it to its next suspension point, and when it finishes it raises `StopIteration` whose `value` is the return value. `asyncio` never asks you to do that by hand, but knowing it demystifies both the machinery and the error messages. ### The never-awaited warning If a coroutine object is finalized without ever having been started, CPython warns: ``` RuntimeWarning: coroutine 'refresh' was never awaited ``` Three things about it are worth knowing. First, it is a **warning, not an exception**: the program keeps running, and the work silently never happens - which is why this bug reaches production. Second, it fires from the object's finalizer, so it appears whenever the object is collected; with plain refcounting that is usually right away, but a reference held in a container or a cycle can push it to interpreter shutdown, far from the call site. Third, running under Python's development mode (`-X dev`) surfaces warnings that are otherwise filtered, and `sys.set_coroutine_origin_tracking_depth(n)` makes CPython record where the coroutine was created so the warning can point at the guilty line. The two common causes are a forgotten `await` inside an async function, and calling an async function from ordinary synchronous code, where there is no `await` available at all. The second one is the real design constraint: sync callers cannot consume coroutines, so the only bridge is a top-level `asyncio.run` or an already-running loop. ### Coroutine objects are single use Once a coroutine has run to completion its frame is exhausted. Awaiting it again raises `RuntimeError: cannot reuse already awaited coroutine`. If you need to run the same work twice, call the coroutine function twice to get two objects. This trips people who try to build a "retryable" value by storing one coroutine object and awaiting it in a loop; store the *function* and its arguments instead, and call it each attempt. A related tidy-up: if you deliberately want to discard a coroutine you created but will not run, `c.close()` finalizes it quietly and suppresses the warning. That is rare and is usually a smell - the honest fix is not to create it. ### Bridging from synchronous code Because `await` is only legal inside a coroutine function, a synchronous caller has no way to consume a coroutine object at all. The supported bridge is `asyncio.run(c)`, which starts a loop, drives the coroutine to completion, tidies up and returns the result - and which must not be called while a loop is already running in that thread. Inside code that is already async, the answer is simply `await`. Recognising which of the two situations you are in is most of what separates a confident asyncio answer from a hopeful one, because the never-awaited warning is exactly what you get when a synchronous function calls an async one and quietly drops the object on the floor. ### Why the language was designed this way Separating creation from execution is what makes `await` a *marked* suspension point. Because building the coroutine is free and side-effect-free, the caller decides when and how the work runs, and every place a coroutine can pause is visible in the source as an `await`. The cost is exactly the failure mode above: an expression that looks like a call but performs no work, and a warning instead of an error when you forget the second half.