Caching helpers.expects_arguments to cut signature introspection on element-heavy pages

[maybites]

Upon a claude session to improve the render speed for my node graph based on nicegui it proposed the following:

Observation. When building a page with many elements, a large share of Python-side render time is spent in inspect.signature(), called via helpers.expects_arguments(). The path is: every .props() / .classes() / .style() mutation writes to the element's observable dict, which fires its change handler; that handler goes through events.handle_event(), which calls helpers.expects_arguments(handler) to decide whether to invoke the handler with or without arguments. expects_arguments runs inspect.signature(handler) on every call. Since each element typically carries several prop/style/class mutations during construction, this fires a very large number of times on a dense page — and the handlers themselves are a small, fixed set of functions whose signatures never change, so the same booleans are recomputed thousands of times. inspect.signature() is comparatively expensive (it walks __code__, builds Parameter objects, resolves kinds/defaults), so this dominates a profile of element construction even though the answer is effectively constant.

Fix. expects_arguments(func) is a pure function of func, and handler identities are stable for the process lifetime, so memoizing on the function object is safe. We wrap it with functools.lru_cache(maxsize=None) at startup: the first call per distinct handler runs the real inspect.signature(), every subsequent call is a dict lookup. The cache fills near-instantly (the handler set is tiny) and turns nearly all the introspection calls into hash lookups. In a render-heavy scenario this gave a measurable end-to-end speedup with no behavioural change.

What would make this easier upstream. Adding @functools.cache directly to helpers.expects_arguments would make this a one-line, framework-wide win — it's a pure, hot, low-cardinality lookup, exactly the shape functools.cache is for. More broadly, handle_event could resolve the "expects arguments" decision once per handler rather than per call (e.g. cached at the point a handler is registered), since it cannot change between invocations. Either approach removes the per-mutation inspect.signature() cost without callers needing a startup monkeypatch.

from __future__ import annotations

from functools import lru_cache

_applied = False


def apply_nicegui_patches() -> None:
    """Apply all NiceGUI startup patches. Idempotent."""
    global _applied
    if _applied:
        return
    _cache_expects_arguments()
    _applied = True


def _cache_expects_arguments() -> None:
    """Memoize ``nicegui.helpers.expects_arguments``.

    Why
    ---
    On a 200-node graph this fires ~135,000 times (≈674 per node), recomputing
    the same booleans. Memoizing on the handler object turns all-but-the-first
    call per handler into a dict lookup.

    Measured: 200-node render 2.44s → 1.74s (≈1.41×, −0.7s). 

    Upstream: not cached on NiceGUI ``main`` as of 2026-06; complements the
    ``.props/.classes/.style`` update-cost work in zauberzeug/nicegui#338.
    Candidate for an upstream ``functools.cache`` PR.
    """
    import nicegui.events as events
    import nicegui.helpers as helpers

    original = getattr(helpers, "expects_arguments", None)
    if original is None or not callable(original):
        raise RuntimeError(
            "NiceGUI patch target 'nicegui.helpers.expects_arguments' is missing or not "
            "callable — the NiceGUI internals changed. Review haywire.ui.nicegui_patches "
            "against the installed NiceGUI version before removing this guard."
        )

    # handle_event resolves the function as ``helpers.expects_arguments`` (an
    # attribute lookup on the helpers package each call), so patching the
    # package attribute is sufficient. We also patch the ``events.helpers``
    # binding defensively in case the resolution path changes.
    if getattr(events, "helpers", None) is not helpers:
        raise RuntimeError(
            "NiceGUI patch assumption broken: nicegui.events.helpers is not the "
            "nicegui.helpers package. Review haywire.ui.nicegui_patches."
        )

    cached = lru_cache(maxsize=None)(original)
    helpers.expects_arguments = cached  # type: ignore[attr-defined]

If this sounds like a reasonable feature, I am happy to (let claude) do a PR

[falkoschindler]

Thanks for the careful write-up, @maybites! The diagnosis is spot on. The path you describe is exactly right: every .props()/.classes()/.style() mutation goes through ObservableCollection._handle_change, which calls events.handle_event() for each registered change handler, which in turn calls helpers.expects_arguments() and runs a fresh inspect.signature() every time. For dense pages that's a lot of recomputation of a value that never changes per handler.

A couple of things to consider before we settle on a fix, though.

functools.cache / lru_cache(maxsize=None) would leak. The cache key is the handler object, and the assumption that "the handler set is tiny" doesn't hold framework-wide:

• The internal _update handlers are bound methods, one per Props/Style/Classes instance — so it's one distinct key per element per collection, not a small fixed set. An unbounded cache pins each of those (and through them their collection objects) for the whole process lifetime, so they're never garbage-collected after the element/client is deleted.
• handle_event is the central dispatch for all events, including user on_click/on_change lambdas, closures, and partials. An unbounded cache pins those forever too, along with whatever they captured.

In a short script that's invisible, but NiceGUI is a long-running server with clients connecting/disconnecting and pages rebuilding, so this grows without bound. The codebase already works hard to avoid exactly this (the weakref in Props._element, unsubscribe_on_delete "to prevent memory leaks", etc.), so I'd rather not introduce a global maxsize=None cache. (A WeakKeyDictionary wouldn't help either — bound methods are recreated on each access and collected immediately, so weak keys would evict instantly and never hit.)

There's already a precedent for the better approach. The Event system (nicegui/event.py) resolves this decision exactly once at subscribe time and stores it on the Callback (expect_args), then calls the handler with/without args from that stored bool — no per-fire introspection. Extending that same "resolve once at registration" pattern to the observable / handle_event path keeps things consistent and avoids the leak entirely.

So my preference order would be:

1. Resolve expects_arguments once when a handler is registered (in ObservableCollection.__init__/on_change) and use the stored bool in _handle_change. Slightly more code, but leak-free and consistent with Callback.expect_args.
2. If a near-one-line framework-wide win is preferred, a bounded lru_cache(maxsize=...) on expects_arguments — the per-element fires are consecutive, so even a small cache captures most of the benefit while capping memory.

If you're up for a PR, option 1 would be very welcome — happy to review. Thanks again for profiling this and raising it!

[maybites]

The PR has landed: #6108 - looking forward to your feedback