The least they could have done is sugared it to something that isn't "def", like "gen" or "defgen"

Unless I'm misunderstanding your comment they do, it's `async def` to denote a coroutine.

They're referring to generator functions. They typically open a resource and then use a for load to read (for example) a line at a time and yield it. once you yield, control returns to the caller (like a return) but subsequent calls to next on the returned expression pick back up at the yield point. So function calls maintain state-behind-the-scenes. It's not just a simple call-and-return model anymore.

To me this violates a core principle: the principle of least surprise. It completely changes how I have to reason about function execution, especially if there are conditionals and different yields.

It's the buried `yield` in a loop somewhere, magically changing your function into a generator, that can be confusing – it's on the original coder to have the docstring say `"""Generator yielding records from DB."""` or something.