Support hypercorn and Trio?

[nazarewk]

I would like to use NiceGUI with Trio instead of asyncio. This means implementing hypercorn in addition to uvicorn, because the latter does not plan to support Trio

[falkoschindler]

Interesting. I can well imagine to add a hypercorn argument to ui.run that starts a hypercorn server instead of uvicorn. That's something we should look into after completing v1.0.

[burnpanck]

Has this been tried by someone? I had the luxury of being able to work exclusively with trio in the past, and got accustomed to expect clear and understandable behaviour. When I had a library like the MongoDB async driver, I was still able to work around with trio_asyncio, but got accustomed to silent swallowing of exceptions, behaviour after leaving a scope and things like that. Now, I'm a happy user of nicegui and since my libraries are all written in anyio, I decided to just run everything under asyncio, hoping to avoid some of the trio_asyncio hassles. However, now that I have an application combining three asyncio-native libaries (nicegui via uvicorn, MongoDB driver, and bleak), asyncio really showed it's teeth. I have completely unpredictable behaviour, probably some silent failure and I wish I had a trio loop. I'd be willing to do some legwork here if there is hope that this succeeds...

[rodja]

@burnpanck thanks for your willingness to contribute. From the FastAPI docs:

Starlette (and FastAPI) are based on AnyIO, which makes it compatible with both Python's standard library asyncio and Trio.

So a good first task would be a pull request which ensures that NiceGUI also uses AnyIO.

[evnchn]

@falkoschindler should we split the thread into another one that discusses explicitly about Hypercorn, and one that explicitly about Trio?

[burnpanck]

I very much disagree. If you look at your own search, the vast majority is just asyncio.sleep. That is an extremely easy replace to anyio.sleep with zero backwards compatibility issues. The few other uses of asyncio I have seen in your search don't seem to use any asyncio-specific functionality either. Indeed, nicegui should not need to interact with the event loop too much anyway. All the asynchronicity ultimately comes from the interaction with the frontend via FastAPI. nicegui has no direct need to block on I/O. Even FastAPI itself uses anyio, because it also does not directly blocks on I/O. Instead, only the underlying ASGI worker does the actual I/O. So it a) should be almost trivial to convert nicegui to anyio, and b) it's very reasonable to do so.

[evnchn]

Well, still it is outside of my skill set, so you may want to try it.

[falkoschindler]

should we split the thread into another one that discusses explicitly about Hypercorn, and one that explicitly about Trio?

I'm not sure. But I guess if there's need for discussion on both topics - and if they are sufficiently unrelated -, separate threads would make sense.

[evnchn]

I think, Hypercorn is pretty dead as an idea, as you can see in #4476

I mean, we have to compromise WebSocket for HTTP long polling for HTTP2, and HTTP3 just doesn't work and we can't use WebTransport either with python-socketio not supporting it.

So maybe dedicate this thread for discussion with anyio then.

[evnchn]

TL;DR: Full asyncio -> anyio Migration Feasibility

A full migration from asyncio to anyio is possible but requires significant architectural refactoring of NiceGUI's core task management. The effort is estimated at ~2-3 days + extensive testing, with high overall risk.

Three Blockers

1. background_tasks.py -- Fire-and-forget task creation from sync code doesn't map to anyio's structured concurrency (task groups are scoped, don't expose task objects, can't be called from sync code). Needs a full rewrite into a queue-based "task nursery."
2. slot.py -- Uses asyncio.tasks.all_tasks() for pruning stale slot stacks. anyio has no global task enumeration. Needs manual task tracking tied to the nursery rewrite.
3. page.py -- Races two asyncio.Task objects with asyncio.wait(FIRST_COMPLETED) and cancels the loser. No direct anyio equivalent. Needs restructuring with cancel scopes and events.

What's Easy

Simple primitives (asyncio.sleep, Event, wait_for, gather, iscoroutine) have near-drop-in anyio replacements and can be migrated independently.

What Stays

run.py cpu_bound (process pool management with BrokenProcessPool recovery) has no good anyio equivalent and would keep asyncio.

Recommendation

If proceeding: rewrite background_tasks.py first (everything depends on it), then slot.py, then page.py, then migrate simple primitives. If deferring the risky parts, the simple primitives can be migrated independently while files needing asyncio.Task/CancelledError keep both imports.

---

Full technical report (click to expand)

Technical Report: Full Migration from asyncio to anyio

Context

GitHub Discussion #184 requests migrating NiceGUI from asyncio to anyio to enable Trio compatibility. anyio is already a transitive dependency via Starlette/FastAPI.

Verdict

A full migration -- removing import asyncio from every file -- is possible but requires a significant architectural refactor of NiceGUI's core task management. It is blocked by 3 fundamental patterns that don't map to anyio's structured concurrency model. Below is an analysis of each blocker and what it would take to resolve them.

---

Blocker 1: Fire-and-forget task creation (background_tasks.py)

Current pattern:
background_tasks.create(coroutine) is the central mechanism for launching async work. It is called from sync code throughout the codebase (event handlers, UI callbacks, timers, etc.) and relies on:

• core.loop.create_task() -- requires a stored event loop reference
• task.add_done_callback() -- for exception forwarding and cleanup
• task.cancel() / task.done() / task.cancelled() / task.get_name() -- for shutdown orchestration
• set[asyncio.Task] -- for tracking all running tasks to prevent GC

Why anyio can't do this:
anyio uses structured concurrency via task groups (async with create_task_group() as tg). Task groups:

• Are scoped -- all tasks must complete before the block exits
• Only accept tg.start_soon() from within the async context, not from sync code
• Don't expose task objects -- no cancel/done/result/add_done_callback
• Cancel ALL tasks if ANY task raises an unhandled exception

Resolution path:
Build a persistent "task nursery" with a memory object stream (queue):

startup:  long-lived task group reads from queue
create(): pushes coroutine onto the queue (from sync code via anyio.from_thread or direct enqueue)
per-task: wrap in try/except for exception isolation
cancel:   track per-task CancelScope objects in a dict, cancel via scope
shutdown: close the queue, let task group drain

This is a full rewrite of background_tasks.py and affects every caller.

---

Blocker 2: Task introspection (slot.py)

Current pattern:

• id(asyncio.current_task()) maps async tasks to UI slot stacks
• asyncio.tasks.all_tasks() enumerates ALL running tasks to prune stale stacks

Why anyio can't do this:

• anyio.get_current_task() returns TaskInfo with .id -- this CAN replace asyncio.current_task()
• asyncio.tasks.all_tasks() has NO anyio equivalent -- anyio doesn't track running tasks globally

Resolution path:
Maintain a manual active_task_ids: set[int] in the task nursery (Blocker 1). Update it when tasks start/finish. prune_stacks() checks against this set. Feasible once Blocker 1 is resolved.

---

Blocker 3: Task racing (page.py)

Current pattern:

await asyncio.wait([task, task_wait_for_connection],
                   timeout=self.response_timeout,
                   return_when=asyncio.FIRST_COMPLETED)
if not task_wait_for_connection.done() and not task.done():
    task_wait_for_connection.cancel()
    task.cancel()

Races two running asyncio.Task objects, cancels the loser, inspects the winner's result.

Why anyio can't do this:

• asyncio.wait() with FIRST_COMPLETED has no direct anyio equivalent
• anyio doesn't expose task objects -- task.done(), task.result(), task.cancel() don't exist

Resolution path:
Restructure using a task group with events:

async with anyio.create_task_group() as tg:
    with anyio.move_on_after(response_timeout):
        result_event = anyio.Event()
        connection_event = anyio.Event()
        tg.start_soon(wait_for_result_and_signal, result_event)
        tg.start_soon(wait_for_connection_and_signal, connection_event)
        # first event fires -> cancel scope exits -> other task cancelled

Requires rethinking how page rendering coordinates task completion.

---

Other asyncio patterns across the codebase

Pattern	Files	anyio replacement	Effort
asyncio.sleep()	8 files, 15 calls	anyio.sleep() -- drop-in	Trivial
asyncio.Event() one-shot	6 files	anyio.Event() -- drop-in	Trivial
asyncio.Event() with .clear()	4 files	Recreate event instead of clearing	Low
asyncio.wait_for()	6 files	anyio.fail_after() context manager	Low
asyncio.gather()	4 files	anyio.create_task_group()	Medium
asyncio.Future	1 file	anyio.Event() + result holder	Low
asyncio.CancelledError	8 files	anyio.get_cancelled_exc_class() (verbose but works)	Low
asyncio.Task type hints	10 files	Needs task wrapper type or TYPE_CHECKING	Medium
isinstance(x, asyncio.Task)	4 files	Custom task wrapper or duck typing	Medium
asyncio.iscoroutine()	2 files	inspect.iscoroutine()	Trivial
loop.run_in_executor(thread_pool)	1 file	anyio.to_thread.run_sync()	Medium
loop.run_in_executor(process_pool)	1 file	No good anyio equivalent (custom executor + BrokenProcessPool recovery)	Keeps asyncio

---

Effort Estimate for Full Migration

Component	Effort	Risk
Simple primitives (sleep, Event, wait_for, gather)	Low	Low
Resettable Events (dialog, outbox, client)	Medium	Medium
background_tasks.py rewrite (task nursery + queue)	High	High
page.py task racing rewrite	High	High
slot.py manual task tracking	Medium	Medium
run.py io_bound -> anyio.to_thread	Medium	Medium
Replace all asyncio.CancelledError	Low	Low
Replace asyncio.Task types everywhere	Medium	Medium
Total	~2-3 days + extensive testing	High overall

---

Recommendation

The full migration touches NiceGUI's deepest infrastructure -- how it manages async tasks, how pages render, and how slot stacks track UI hierarchy. The high-risk components (background_tasks.py, page.py) are among the most critical and hardest-to-test parts of the framework.

If you want to proceed with a full migration, the implementation order should be:

1. Rewrite background_tasks.py (queue-based task nursery) -- everything else depends on this
2. Update slot.py to use manual task tracking from the nursery
3. Rewrite page.py task racing with cancel scopes
4. Migrate all simple primitives (sleep, Event, wait_for, gather, Future)
5. Replace asyncio.CancelledError with anyio.get_cancelled_exc_class()
6. Migrate run.py io_bound to anyio.to_thread.run_sync()
7. Clean up remaining asyncio.Task type usage
8. Note: run.py cpu_bound keeps asyncio (process pool management)

If you want to defer the risky parts, the simple primitives (sleep, Event, wait_for, gather) can be migrated independently. Files that also need asyncio for Task/CancelledError would keep both imports.

[evnchn]

Yeah nah I don't think it's possible.

[burnpanck]

Ah, those AI tools. The analysis of all uses of asyncio is very helpful. The conclusion however, IMHO, is just plain wrong.
In particular, I disagree with its analysis in the following points:

Blocker 1

Why anyio can't do this [...]. Task groups:

• Are scoped -- all tasks must complete before the block exits

Correct and valuable.

• Only accept tg.start_soon() from within the async context, not from sync code

Plain wrong. tg.start_soon() can be called from sync code.

• Don't expose task objects -- no cancel/done/result/add_done_callback

Mostly wrong. You cancel via cancel scopes, and done/result/callbacks would be easily added in a 5-line generic task wrapper (though usually not needed when working with structured concurrency).

Cancel ALL tasks if ANY task raises an unhandled exception

This is a feature. Add try/catch in that 5-line wrapper and think of where those exceptions should go in the first place, rather than just swallowing.

Conclusion: Easily implemented with a small generic task wrapper. No need for a queue, no need for a separate task management worker, just instantiate that "app nursery/task-group" at the main lifecycle of the application. (That said, fire-and-forget tasks really make reasoning about code races much worse and are usually a sign of bad design, and with structured concurrency usually easily avoided).

Blocker 2

As the AI tool notes, can very feasibly implemented in that generic task wrapper if really needed. But: prune_stacks is exactly one of those design smells that can be avoided by structured concurrency.

Blocker 3

Looking at that relevant section, the two tasks that are raced are started right before. Indeed, the 1:1 re-implementation makes use of a task-group/nursery for those two tasks, which includes a cancel scope. Timeouts are much nicer to implement anyway. So the workaround implementation looks roughly like this:

async with anyio.create_task_group() as tg:
  try:
    with Client() as client:
      with anyio.CancelScope() as response_scope:
        async def wait_for_connection():
          await client._waiting_for_connection.wait()
          response_scope.cancel()
        tg.start_soon(wait_for_connection())
        with anyio.fail_after(response_timeout):
          result = await func(...)
  finally:
    tg.cancel_scope.cancel()

This implementation a) doesn't make use of fire-and-forget tasks, b) cancels the result generation when a new connection comes in rather than leaking that task with an ignored result (in the current implementation), c) actually wrapps all use of client within it's context rather than mis-nesting contexts (violating structure) and d) might end up being shorter than the current implementation (though the above sketch is still missing a few things from the original).

[evnchn]

Unfortunately I genuinely do not have experience with anyio and unable to fact check the AI opinion.

I must thank you for your clarification. I think you lead the pack for anyio understanding, so perhaps I'll ask for your clarification as time goes on, if you don't mind.