Add strict parameter to cpu_bound and io_bound to propagate cancellation

[calebgregory]

Closes #5925

Summary

_run silently returns None when the app is stopping, the executor is shut down, or the task is cancelled — violating the declared -> R return type. This causes two problems:

1. Callers cannot distinguish a legitimate None return value from a cancellation
2. Code that trusts the R return type hits downstream TypeErrors at runtime when R is non-optional

This PR adds a strict keyword parameter (default False) to cpu_bound and io_bound:

• strict=True → raises run.CancelledError (subclass of asyncio.CancelledError) instead of returning None; return type is R
• Default / strict=False → preserves current runtime behavior; return type is honestly R | None

Literal-based overloads let the type checker narrow the return type based on the value of strict.

Note: This is a breaking type-level change. The default return type is now R | None, so consumers will see new mypy errors where they previously did not. Runtime behavior is unchanged for callers that do not pass strict.

Test plan

• Existing test_run.py tests pass (no behavioral regression)
• New test_returns_none_when_app_is_stopping — verifies default behavior returns None (parametrized across cpu_bound and io_bound)
• New test_strict_raises_when_app_is_stopping — verifies strict=True raises run.CancelledError (parametrized across cpu_bound and io_bound)
• ruff check and autopep8 clean

Co-Authored-By: Claude Opus 4.6 (1M context) noreply@anthropic.com

[petergaultney]

is there a strong reason to prefer a subclass vs just re-raising the existing exception... I suppose the one weird issue would be creating one in the first if strict pre-check.

But I'm generally hesitant to make new exceptions, and especially so when they have the same name as an underlying one. 🤔

[calebgregory]

I appreciate the hesitancy to make new exceptions. I think that's why I had the impulse to name this one nicegui.run.CancelledError to match asyncio's name. But maybe it's better to give it a distinct name anyway, to prevent confusion.

I agree that raising a new asyncio.CancelledError() when the app is shutting down would be strange.

Defining the exception in nicegui.run offers some code-as-documentation + some consumer-convenience:

import asyncio
from nicegui import run

try:
    run.cpu_bound(..., strict=True)
except asyncio.CancelledError:
    ...

vs.

from nicegui import run

try:
    run.cpu_bound(..., strict=True)
except run.CancelledError:
    ...

[petergaultney]

this looks pretty good to me. I have the one question about the exception definition, but no very strong preference there.

[falkoschindler]

Thanks for the PR, @calebgregory! The issue is real and the fix direction makes sense.

However, we're running into a mypy limitation with the current approach: you can't place additional keyword arguments between P.args and P.kwargs. That's why mypy reports "Arguments not allowed after ParamSpec.args" on every signature that mixes strict with ParamSpec.

We can work around this with overloads — using ParamSpec for the default (non-strict) overload and Callable[..., R] for the strict=True overload. That preserves argument type-checking for the default case. But strict=True loses ParamSpec checking, which is unfortunate since strict=True is meant to become the recommended mode (and eventually the default after the next major release).

Do you have ideas for how to keep ParamSpec argument checking in the strict=True case? Some options we've considered but aren't thrilled with:

• Separate functions (e.g. cpu_bound_strict) instead of a parameter — preserves ParamSpec but clutters the API
• A wrapper/decorator that converts the return type — might be too clever
• Waiting for PEP 612 extensions that allow extra kwargs alongside ParamSpec — not available yet

Open to other ideas if you see a cleaner way to thread this needle.