invoke - Chirp

_internal.invoke

module

Invoke helpers — call sync or async handlers uniformly.

Chirp handlers can bedef or async def. Any code that calls a user-provided handler must handle both cases. This module provides…

Invoke helpers — call sync or async handlers uniformly.

Chirp handlers can bedef or async def. Any code that calls a user-provided handler must handle both cases. This module provides a single helper so the sync/async check lives in exactly one place.

Sync handlers run inasyncio.to_threadto avoid blocking the event loop (critical for CPU-bound work and free-threading scaling).

Usage::

from chirp._internal.invoke import invoke

result = await invoke(handler, *args, **kwargs)

_internal.invoke

Name	Type	Default	Description
`type`		—
`qualified_name`		—
`element_type`		—
`description`		—
`source_file`		—
`line_number`		—
`is_autodoc`		—
`autodoc_element`		—
`_autodoc_template`		—
`_autodoc_url_path`		—
`_autodoc_page_type`		—
`title`		—
`doc_content_hash`		—

Symbols on this page

function take_handler_runtime_context

Return and clear the worker-thread runtime snapshot from the last sync invoke.

async function invoke

Call a handler and await the result if it's a coroutine.

When is_async is provided (from a compiled InvokePlan), the per-request inspect.iscoroutinefunctioncall is…

take_handler_runtime_context

function

def take_handler_runtime_context() -> contextvars.Context | None

Return and clear the worker-thread runtime snapshot from the last sync invoke.

No parameters.

invoke

function async

async def invoke(handler: Any, *args: Any, is_async: bool | None = None, inline_sync: bool = False, **kwargs: Any) -> Any

Call a handler and await the result if it's a coroutine.

When is_async is provided (from a compiled InvokePlan), the per-request inspect.iscoroutinefunctioncall is skipped entirely.

When inline_sync is True and the handler is synchronous, it runs on the event loop thread instead ofasyncio.to_thread— useful for lightweight handlers where the thread-dispatch overhead exceeds the work itself.

Sync handlers dispatched to a worker thread run inside a copy_context() snapshot taken on the event-loop thread (preserving OTel/request context) and stash a post-handler worker snapshot for streaming capture viatake_handler_runtime_context().

Parameters

Name	Type	Default
`handler`	`Any`	—
`*args`	`Any`	—
`is_async`	`bool \| None`	`None`
`inline_sync`	`bool`	`False`
`**kwargs`	`Any`	—

View source · /home/runner/work/chirp/chirp/site/../src/chirp/_internal/invoke.py:1