Module h2o_wave.server

Functions

app

def app(route: str, mode=None, on_startup: Callable | None = None, on_shutdown: Callable | None = None)

Indicate that a function is a query handler.

The function this decorator is applied to must accept exactly one argument that represents the query context, of type Query or Query

Args

route

The route to listen to. e.g. '/foo' or '/foo/bar/baz'.

mode

The server mode. One of 'unicast' (default),'multicast' or 'broadcast'.

on_startup

A callback to invoke on app startup. Callbacks do not take any arguments, and may be be either standard functions, or async functions.

on_shutdown

A callback to invoke on app shutdown. Callbacks do not take any arguments, and may be be either standard functions, or async functions.

Classes

Auth

class Auth(username: str, subject: str, access_token: str, refresh_token: str, session_id: str)

Represents authentication information for a given query context. Carries valid information only if single sign on is enabled.

Instance variables

var access_token

The access token of the user.

var refresh_token

The refresh token of the user.

var subject

A unique identifier for the user.

var username

The username of the user.

Methods

ensure_fresh_token

async def ensure_fresh_token(self) ‑> str | None

Explicitly refresh OIDC tokens when needed, e.g. during long-running background jobs.

ensure_fresh_token_sync

def ensure_fresh_token_sync(self) ‑> str | None

Explicitly refresh OIDC tokens when needed, e.g. during long-running background jobs - synchronous version. Prefer async version. Use sync only when absolutely necessary - will block your app, making it slow for all users.

Query

class Query(site: AsyncSite, mode: str, auth: Auth, client_id: str, route: str, app_state: Expando, user_state: Expando, client_state: Expando, args: Expando, events: Expando, headers: Dict[str, List[str]])

Represents the query context. The query context is passed to the @app handler function whenever a query arrives from the browser (page load, user interaction events, etc.). The query context contains useful information about the query, including argumentsargs (equivalent to URL query strings) and app-level, user-level and client-level state.

Instance variables

var app

A Expando instance to hold application-specific state.

var args

A Expando instance containing arguments from the active request.

var auth

The authentication / authorization details of the user who initiated this query.

var client

An Expando instance to hold client-specific state.

var events

A Expando instance containing events from the active request.

var headers

Original Websocket HTTP connection headers forwarded from the Wave server to this application.

var mode

The server mode. One of 'unicast' (default),'multicast' or 'broadcast'.

var page

A reference to the current page.

var route

The route served by the server.

var site

A reference to the current site.

var user

A Expando instance to hold user-specific state.

Methods

exec

async def exec(self, executor: concurrent.futures._base.Executor | None, func: Callable, *args: Any, **kwargs: Any) ‑> Any

Execute a function in the background using the specified executor.

To execute a function in-process, use q.run().

Args

executor

The executor to be used. If None, executes the function in-process.

func

The function to to be called.

args

Arguments to be passed to the function.

kwargs

Keywords arguments to be passed to the function.

Returns

The result of the function call.

run

async def run(self, func: Callable, *args: Any, **kwargs: Any) ‑> Any

Execute a function in the background, in-process.

Equivalent to calling q.exec() without an executor.

Args

func

The function to to be called.

args

Arguments to be passed to the function.

kwargs

Keywords arguments to be passed to the function.

Returns

The result of the function call.

sleep

async def sleep(self, delay: float, result=None) ‑> Any

Suspend execution for the specified number of seconds. Always use q.sleep() instead of time.sleep() in Wave apps.

Args

delay

Number of seconds to sleep.

result

Result to return after delay, if any.

Returns

The result argument, if any, as is.

Q

class Q(site: AsyncSite, mode: str, auth: Auth, client_id: str, route: str, app_state: Expando, user_state: Expando, client_state: Expando, args: Expando, events: Expando, headers: Dict[str, List[str]])

Represents the query context. The query context is passed to the @app handler function whenever a query arrives from the browser (page load, user interaction events, etc.). The query context contains useful information about the query, including argumentsargs (equivalent to URL query strings) and app-level, user-level and client-level state.

Instance variables

var app

A Expando instance to hold application-specific state.

var args

A Expando instance containing arguments from the active request.

var auth

The authentication / authorization details of the user who initiated this query.

var client

An Expando instance to hold client-specific state.

var events

A Expando instance containing events from the active request.

var headers

Original Websocket HTTP connection headers forwarded from the Wave server to this application.

var mode

The server mode. One of 'unicast' (default),'multicast' or 'broadcast'.

var page

A reference to the current page.

var route

The route served by the server.

var site

A reference to the current site.

var user

A Expando instance to hold user-specific state.

Methods

exec

async def exec(self, executor: concurrent.futures._base.Executor | None, func: Callable, *args: Any, **kwargs: Any) ‑> Any

Execute a function in the background using the specified executor.

To execute a function in-process, use q.run().

Args

executor

The executor to be used. If None, executes the function in-process.

func

The function to to be called.

args

Arguments to be passed to the function.

kwargs

Keywords arguments to be passed to the function.

Returns

The result of the function call.

run

async def run(self, func: Callable, *args: Any, **kwargs: Any) ‑> Any

Execute a function in the background, in-process.

Equivalent to calling q.exec() without an executor.

Args

func

The function to to be called.

args

Arguments to be passed to the function.

kwargs

Keywords arguments to be passed to the function.

Returns

The result of the function call.

sleep

async def sleep(self, delay: float, result=None) ‑> Any

Suspend execution for the specified number of seconds. Always use q.sleep() instead of time.sleep() in Wave apps.

Args

delay

Number of seconds to sleep.

result

Result to return after delay, if any.

Returns

The result argument, if any, as is.