How do you write one decorator that wraps both plain functions and `async def` functions?

## The shape of the problem A decorator that adds a cross-cutting concern — auditing, timing, a permission check, an error tag — is usually written once and then applied to whatever is in the module. Some of those callees are plain functions and some are `async def`. The wrapper cannot be neutral about the difference, because a plain wrapper cannot await and an asynchronous wrapper forces its callers to. ## Branch once, at decoration time Decoration happens exactly once per decorated function, at import. That is the right place to pay for the check: ```python def audited(func): if inspect.iscoroutinefunction(func): @functools.wraps(func) async def wrapper(*args, **kwargs): log(func) return await func(*args, **kwargs) else: @functools.wraps(func) def wrapper(*args, **kwargs): log(func) return func(*args, **kwargs) return wrapper ``` Two bodies, one decorator, and the branch is evaluated once no matter how hot the call path is. Each branch is `functools.wraps`-ed independently. Critically, the asynchronous branch returns something that is *itself* a coroutine function, so the decorated name still answers `True` to `inspect.iscoroutinefunction` and any later layer — a second decorator, a dispatcher, a test helper — sees the truth. The tempting alternative, one wrapper that checks at call time, does not survive contact. A plain `def` wrapper cannot `await`, so at best it returns the coroutine for someone else to await, which means the wrapper's own post-call logic never runs. An `async def` wrapper handles both, but only by making every synchronous callee awaitable, which changes the contract of functions that were never asynchronous and breaks their existing call sites. ## What `inspect.iscoroutinefunction` actually answers It reports whether the object it is handed is a coroutine function — a callable whose code carries the coroutine flag. Three refinements matter in practice: * It sees through `functools.partial`, so a partially-applied coroutine function still reports `True`. * It honours the marker set by `inspect.markcoroutinefunction`, added in 3.12, which lets a synchronous callable that returns a coroutine advertise itself as a coroutine function. * It does **not** follow `__wrapped__`. If somebody already wrapped your callee in a plain `def` pass-through, the check reports `False` and your decorator picks the synchronous branch — a correctness bug caused by a layer you did not write. This is exactly why a decorator that returns a synchronous pass-through around a coroutine function should mark it. On Python 3.14 use `inspect.iscoroutinefunction`. `asyncio.iscoroutinefunction` is deprecated in 3.14 and scheduled for removal, so new code should not reach for it. ## The third kind: async generator functions An `async def` that contains `yield` is not a coroutine function at all — it is an **async generator function**. `inspect.iscoroutinefunction` returns `False` for it, and `inspect.isasyncgenfunction` returns `True`. Awaiting the call is wrong; the result is consumed with `async for`, and a wrapper that wants to preserve streaming has to be an async generator itself that yields as it iterates. A two-branch decorator applied to one of these silently takes the synchronous branch and hands the async generator object through untouched, which sometimes works by accident and sometimes does not. If a decorator will be used on streaming callees, test the async generator case explicitly and add a third branch. ## Callable objects and methods `inspect.iscoroutinefunction` on an instance of a class whose `__call__` is `async def` returns `False`, because the instance itself is not a coroutine function; the check has to look at `type(obj).__call__`. The same caution applies to anything wrapped in `classmethod` or `staticmethod` before reaching your decorator: check the callable you actually received, not the name you think you are decorating. ## Whether to do this at all Supporting both kinds in one decorator costs a branch and a duplicated body, and duplicated bodies drift. Two named decorators, one synchronous and one asynchronous, are frequently the better answer in application code — the caller states which world they are in, and each implementation stays simple. The dual-mode form earns its keep in a shared library that cannot know its callees, or when a single decorator is applied across a codebase that is halfway through an asynchronous migration and the churn of renaming every use is not worth it.