Callable | Awaitable in Lifecycle Handlers

[AlePiccin]

Summary

Several lifecycle registration APIs currently accept Callable | Awaitable, for example:

• app.on_startup(...)
• app.on_shutdown(...)
• app.on_connect(...)
• app.on_disconnect(...)
• app.on_delete(...)
• the corresponding client.on_* hooks

After reviewing the codebase, I found that we only pass a direct Awaitable in two places, both in tests:

• tests/test_lifecycle.py#L91:
  app.on_startup(startup_async())
• tests/test_lifecycle.py#L94:
  app.on_shutdown(shutdown_async())

Every other usage I found passes a callable:

• regular functions
• async functions
• lambdas
• wrapper callables

So the Awaitable side of the API appears to be barely used, and only in two easy-to-fix cases.

---

Current API Shape

In the original code, the lifecycle registration methods accept Callable | Awaitable:

def on_connect(self, handler: Callable | Awaitable) -> None:
    self._connect_handlers.append(handler)

def on_disconnect(self, handler: Callable | Awaitable) -> None:
    self._disconnect_handlers.append(handler)

def on_delete(self, handler: Callable | Awaitable) -> None:
    self._delete_handlers.append(handler)

def on_startup(self, handler: Callable | Awaitable) -> None:
    self._startup_handlers.append(handler)

def on_shutdown(self, handler: Callable | Awaitable) -> None:
    self._shutdown_handlers.append(handler)

That broader type then leaks into execution paths like this:

  for t in self._startup_handlers:
      self.safe_invoke(t)

and:

    async def stop(self) -> None:
        """Stop NiceGUI. (For internal use only.)"""
        self._state = State.STOPPING
        for t in self._shutdown_handlers:
            if isinstance(t, Awaitable):
                await t
            else:
                result = t(self) if len(inspect.signature(t).parameters) == 1 else t()
                if helpers.is_coroutine_function(t):
                    await result
        self._state = State.STOPPED

This means the implementation has to keep supporting both:

• "a handler I can call"
• "an awaitable object that was already created elsewhere"

———

Where We Actually Pass an Awaitable

I found only these two direct uses:

app.on_startup(startup_async())
app.on_shutdown(shutdown_async())

Source:

• tests/test_lifecycle.py#L89
• tests/test_lifecycle.py#L94:94

The equivalent callable versions already exist right next to them:

app.on_startup(startup_async)
app.on_shutdown(shutdown_async)

So the current Awaitable support is not only rarely used, but also unnecessary in the codebase as it stands.

———

Why This Feels Wrong

1. Lifecycle hooks are conceptually handlers, not already-created awaitables

A lifecycle registration API reads like "register something to be invoked later". That strongly suggests a callable contract.

Passing an already-created awaitable means:

• it was created earlier
• it may capture state too early
• it is one-shot
• it is not reusable

That is especially awkward for hooks like on_connect, on_disconnect, and on_delete, which can run many times.

2. Awaitable makes the API broader than the real use case

For repeated lifecycle hooks, accepting Awaitable is arguably the wrong abstraction:

• a callable can be invoked repeatedly
• an awaitable object cannot

So for connect / disconnect / delete, the type is not just unnecessary, but misleading.

3. It complicates the implementation

Because the API accepts both shapes, execution code has to
branch:

  if isinstance(t, Awaitable):
      ...
  else:
      result = t

This adds complexity in:

• nicegui/app/app.py
• potentially future helper abstractions around handler
  invocation

If these APIs were callable-only, the control flow would become simpler and easier to reason about.

4. It weakens the mental model

For users and maintainers, this is easier to explain:

• lifecycle hooks register functions
• those functions may be sync or async

That is much clearer than:

• lifecycle hooks register either functions or already-created awaitables

———

Why Changing This Looks Safe

From the current codebase review:

• direct Awaitable registration appears only in 2 test lines
• both cases are trivial to rewrite
• all other usages already pass callables

The fixes are straightforward:

app.on_startup(startup_async)
app.on_shutdown(shutdown_async)

instead of:

app.on_startup(startup_async())
app.on_shutdown(shutdown_async())

So the internal migration cost looks very low.

The benefits are:

• clearer contract
• simpler implementation
• less special-casing
• better match with how the codebase is already used
• fewer surprising one-shot awaitable semantics

In short: the current type is broader than the actual need, barely exercised in practice, and easy to remove from internal usages.
———

Questions for Maintainers

I think these are the right questions to ask before changing the API:

1. Was Callable | Awaitable intentionally designed as public API flexibility, or did it just emerge from implementation convenience?
2. Do we know of real user code depending on app.on_startup(coro()) or app.on_shutdown(coro())?
3. If no meaningful external usage exists, why keep the broader contract?
4. For repeated hooks like on_connect / on_disconnect / on_delete, is accepting an already-created awaitable actually something we want to support at all?

———

Recommendation

I would recommend:

1. Decide whether Awaitable support is intentionally public
   API.
2. If not, narrow lifecycle hooks to callable-only.
3. Update the two test cases.
4. Simplify invocation code accordingly.

Given the current repository usage, this looks like a small change with a good clarity payoff.

I'd be happy to submit an PR.

[falkoschindler]

See PR #5879 🚀

[falkoschindler]

I'm closing this feature request as completed in version 3.10.0. ✔️