How do you make one decorator work both as @retry and as @retry(times=3)?

### The problem A decorator that takes options is called before it ever sees the function; a bare decorator receives the function directly. Those are two different calling conventions arriving at the same name, so a single object that serves both has to work out which one happened. It is a common request for decorators with all-default options, where forcing every caller to type `@retry()` for no benefit feels like a papercut. ### The canonical shape ```python import functools def retry(func=None, *, times=3): if func is None: # called with options return functools.partial(retry, times=times) @functools.wraps(func) # called with the function def wrapper(*args, **kwargs): for attempt in range(1, times + 1): try: return func(*args, **kwargs) except OSError: if attempt == times: raise return wrapper ``` Trace both paths: * `@retry` evaluates `retry(plan_route)`. `func` is the function, not `None`, so the wrapper is built and returned — the two-level path. * `@retry(times=5)` evaluates `retry(times=5)` with `func` left at its default `None`, which returns `functools.partial(retry, times=5)`. That partial is itself callable, so the `@` machinery calls it with the function, re-entering `retry` as `retry(plan_route, times=5)` and taking the first path. * `@retry()` behaves exactly like the options form with no options — which is why the dual form is strictly more permissive, never less. `functools.partial` is doing one narrow job here: it produces a callable that remembers the options and forwards them on the second call. Anything else with that property works; the point of the idiom is the re-entry, not the type. ### The same thing without partial ```python def retry(func=None, *, times=3): def decorator(f): @functools.wraps(f) def wrapper(*args, **kwargs): ... return wrapper return decorator if func is None else decorator(func) ``` This version defines the wrapper once and decides at the end whether to hand back the decorator or apply it immediately. Many reviewers prefer it because the three levels stay visible and there is no re-entrant call to reason about; the partial version is shorter and keeps a single definition of the signature. ### Why the bare `*` matters more than the trick does Making the options keyword-only is the load-bearing part. With `def retry(func=None, *, times=3)` the only thing that can ever arrive positionally is the function being decorated, so "is `func` `None`?" is an exact test rather than a guess. Drop the `*` and allow `@retry(3)`, and the positional slot now means two different things depending on the caller — at which point people reach for a `callable()` sniff on the first argument, which is where this pattern earns its bad reputation. That sniff is genuinely unsafe. Classes are callable, so an option whose value is an exception type, a class, a factory function, or any instance defining `__call__` passes `callable()` and is misidentified as the decoration target. `callable(ValueError)` is `True`. The failure is silent: the decorator quietly wraps the option instead of the function, and the wrapped name misbehaves at a call site far from the decoration. Making options keyword-only removes the ambiguity structurally instead of trying to detect it. ### The costs you are accepting The dual form obscures the signature for readers and for static analysis: the first parameter is either a function or absent, and the return type is either a decorator or a wrapped function. Type checkers need overloads to describe it precisely, and the branch is one more thing to test — both spellings need coverage, or one path rots. It also produces a subtly worse error when someone passes an option positionally by mistake, because the "function" branch will be taken with a non-callable. ### Testing the branch you did not write first Both spellings are separate code paths through one function, and a codebase that uses only the bare form will happily carry a broken options branch for a year. Two decorated functions in a test module - one written `@retry`, one written `@retry(times=5)` - cover the split for the cost of four lines, and they also pin the keyword-only signature: if someone later drops the `*`, the test that passes an option positionally starts wrapping the wrong object and fails loudly instead of silently. ### When to bother Supporting both spellings is worth it for a decorator used in hundreds of places, where the bare form is the overwhelmingly common one and the options are a rare escape hatch. For an internal decorator used in a dozen places, pick one spelling, document it, and let the missing-parentheses error teach the rule. The failure mode of choosing wrong is small in either direction; the failure mode of a `callable()` sniff is a bug that ships.