bauiv1lib.docui package

Functionality for using doc-ui on top of bauiv1.

Threading design

Doc-ui deliberately offloads as much processing as possible to background threads, keeping logic-thread work to the bare minimum (instantiating widgets and running actions/effects). A request’s whole journey — controller fulfillment (including cloud/web round-trips), response validation, asset-package resolution (marshalled to the logic thread only for the async resolve await itself), l-string decode, and full page prep — runs via DocUIController._process_request_in_bg on a capped, self-retiring background thread (see _bgrunner), kept off the shared threadpool because this prep is long and blocking (an asset-package construct/download can tie a thread up for seconds). Only the final prepped page is pushed back to the logic thread for widget instantiation.

Code called from that flow (controller fulfill_request overrides especially) should preserve this: do the heavy lifting where you are called (the bg thread) rather than pushing work to the logic thread, and never assume logic-thread context without checking.

class bauiv1lib.docui.DocUIController

Bases: object

Manages interactions between DocUI clients and servers.

Can include logic to handle all requests locally or can submit them to be handled by some server or can do some combination thereof.

class ErrorType(*values)

Bases: Enum

Types of errors that can occur in request processing.

COMMUNICATION_ERROR = 'communication'

GENERIC = 'generic'

NEED_UPDATE = 'need_update'

NOT_SIGNED_IN = 'not_signed_in'

UNDER_CONSTRUCTION = 'under_construction'

create_window(request: DocUIRequest | DocUIRoute, *, transition: str | None = 'in_right', origin_widget: bui.Widget | None = None, auxiliary_style: bool = True, uiopenstateid: str | None = None, suppress_win_extra_type_warning: bool = False, layout: bacommon.docui.v2.WindowLayout | None = None) → DocUIWindow

Create a new window to handle a request.

The window opens at layout; if not given, a route’s own get_window_layout(), or else the wide layout (the same default routes use).

error_response(request: DocUIRequest, error_type: ErrorType = ErrorType.GENERIC, custom_message: str | None = None) → DocUIResponse

Build a simple error message page.

A message is included based on error_type. Pass custom_message to override this.

Messages are language-agnostic (bundled-package strings), so error pages localize like any other doc-ui content; a custom_message shows verbatim (untranslated).

fulfill_request(request: DocUIRequest) → DocUIResponse

Handle request fulfillment.

Expected to be overridden by child classes.

Be aware that this will always be called in a background thread.

This method is expected to always return a response, even in the case of errors. Use error_response() to translate error conditions to responses.

The one exception to this rule (no pun intended) is the efro.error.CleanError exception. This can be raised as a quick and dirty way to show custom error messages. The code raise CleanError('Something broke.') will have the same effect as return self.error_response(custom_message='Something broke.').

fulfill_request_web(request: DocUIRequest | DocUIRoute, url: str) → DocUIResponse

Fulfill a request by sending it to a webserver.

get_cache_key_extra() → str | None

Extra identity for response caching.

Cached responses are keyed by controller class, request, account and locale. A controller whose instance state changes what it returns for a given request must declare that state here; otherwise two instances differing in it share one cache entry and briefly show each other’s pages.

Return None to opt out of caching entirely, which is the right answer when a response depends on state that cannot be summarized as a string.

get_local_action_press_sound(name: str) → PressSound

What a button plays when pressed to run a local-action.

Given the local-action’s name. The default clicks; typed controllers answer per local-action type (see bacommon.docui.routes.DocUILocalActionBase.get_press_sound()).

get_page_state_poll_interval() → float | None

How often to call poll_page_state() (None = never).

For client-local pages mirroring values that can change behind their back (fullscreen toggled by a hotkey, say). Polling runs while a window shows a page that has state and isn’t waiting on a request.

classmethod get_window_extra_type_id() → str

Return a string suitable for the window_extra_type_id arg to auxiliary_window_activate().

This ensures your doc-ui window is identified distinctly from other doc-ui windows for navigation purposes.

get_window_toolbar_visibility() → Literal['menu_full', 'menu_minimal']

Which toolbar our windows show.

Everything by default. Settings-style pages reachable mid-game typically return 'menu_minimal' unless bauiv1.in_main_menu(), as the classic settings windows do.

local_action(action: DocUILocalAction) → None

Do something locally on behalf of the doc-ui.

Controller classes can override this to expose named actions that can be triggered by doc-ui button presses, responses, etc.

Of course controllers can also perform arbitrary local actions alongside their normal request fulfillment; this is simply a way to do so without needing to provide actual ui pages alongside.

Be very careful and focused with what you expose here, especially if your doc-ui pages are coming from untrusted sources. Generally things like launching or joining games are good candidates for local actions.

poll_page_state(window: DocUIWindow) → dict

Current values for (some of) a window’s page state.

Called every get_page_state_poll_interval() seconds. Return wire-form values keyed as in the state (see bacommon.docui.routes.DocUIState.key()); any differing from what the page holds are pushed into it, updating the controls showing them without rebuilding anything.

replace(win: DocUIWindow, request: DocUIRequest, *, origin_widget: bui.Widget | None = None, is_refresh: bool = False) → None

Kick off a request to replace existing window contents.

A refresh (is_refresh) saves the window’s shared state first, as a replace action does, so the rebuilt page comes back with the same selection. Without it, a refresh kicked off directly (a local action re-rendering its page, say) restores whatever was saved last – often from when the window opened.

restore(win: DocUIWindow, *, last_response: DocUIResponse | None, has_had_response: bool) → DocUIWindow

Restore a window from previous state.

May immediately display old results or may kick off a new request.

restore_window_shared_state(window: DocUIWindow, state: dict) → None

Called when a window shared state is being restored.

run_action(window: DocUIWindow, widgetid: str | None, action: bacommon.docui.v2.Action | None, is_timed: bool = False, trigger: str | None = None) → None

Called when a button is pressed in a doc-ui.

(Or when a timed action fires, or when an input row with an on-change action changes; trigger is its state key then.)

save_window_shared_state(window: DocUIWindow, state: dict) → None

Called when a window shared state is being saved.

class bauiv1lib.docui.DocUILocalAction(name: str, args: dict, widget: bui.Widget | None, window: DocUIWindow, trigger: str | None = None)

Bases: object

Context for a local-action.

args: dict

name: str

state(statetype: type[T]) → T | None

The window’s current page state, as a given state type.

None if the page has no state or its state is of some other type. Input rows write their values here as they change, so this is the live value for an action fired mid-interaction (a slider’s on_drag, say).

trigger: str | None = None

State key of the input row whose change fired us, if that is what did.

widget: bui.Widget | None

window: DocUIWindow

class bauiv1lib.docui.DocUIWindow(controller: DocUIController, request: DocUIRequest, *, transition: str | None = 'in_right', origin_widget: bui.Widget | None = None, auxiliary_style: bool = True, restored: bool = False, uiopenstateid: str | None = None, suppress_win_extra_type_warning: bool = False, has_had_response: bool = False, layout: bacommon.docui.v2.WindowLayout | None = None)

Bases: MainWindow

Window showing doc-ui content.

anim_targets

Our page’s client-effect-animatable widgets.

property column_insets: tuple[float, float]

Extra left/right insets narrowing where content is laid out (within screen_margins) to a column.

get_main_window_shared_state_id() → str | None

Provide a custom id for window shared state.

Unlike MainWindowState, which is used to save and restore a single main-window instance, shared-state is intended to hold values that can apply to multiple instances of a window.

By default, shared state uses the window class as an index (so is shared by all windows of the same class), but this method can be overridden to provide more distinct states. For example, a store-page main-window class might want to keep distinct states for different sub-pages it can display instead of having a single state for the whole class.

Note that shared state only persists for the current run of the app.

get_main_window_state() → MainWindowState

Return a WindowState to recreate this specific window.

Used to gracefully return to a window from another window or ui system.

lock_ui(origin_widget: Widget | None = None) → None

Stop UI interactions during some operation.

property locked: bool

Are we locked?

main_window_do_restore_shared_state(state: dict) → None

Restore state from the provided shared state dict.

Can be overridden by subclasses to restore custom data.

main_window_do_save_shared_state(state: dict) → None

Save state into the provided shared state dict.

Can be overridden by subclasses to save custom data.

main_window_should_preserve_selection() → bool

Whether this window should auto-save/restore selection.

If enabled, selection will be stored in the window’s shared state. See get_main_window_shared_state_id() for more info about main-window shared-state.

The default value of None results in a warning to explicitly override this (as the implicit default will change from False to True after api 9 support ends).

main_window_should_scroll_to_restored_selection(widget: Widget) → bool

Whether restoring selection to widget should scroll to it.

By default a restored selection is scrolled into view (show buffers and all). Windows that restore their scroll positions exactly can return False when the widget is already back where it was, so the restore doesn’t nudge it toward the center.

on_main_window_close() → None

Called before transitioning out a main window.

A good opportunity to save window state/etc.

property page_state: dict | None

Current state values for the page we are showing, if any.

This is the wire form; things knowing the type of state they expect can decode it via that type.

property request: DocUIRequest

The current request.

Should only be accessed from the logic thread while the ui is unlocked.

request_for_action(request: bacommon.docui.v2.Request, *, sets: dict | None, state: dict | None, trigger: str | None = None) → bacommon.docui.v2.Request

Return an action’s request as it should actually go out.

Requests fired from a page carry that page’s current state: what the action explicitly provides if anything, or otherwise ours with the action’s sets applied.

property screen_margins: tuple[float, float, float, float]

Screen margins (left, right, bottom, top) our scroll extends into beyond its standard scroll-width/height area.

property scroll_height: float

Height of our scroll area.

property scroll_width: float

Width of our scroll area.

set_last_response(response: DocUIResponse, success: bool, *, redisplay: bool = False) → None

Set a response to a request.

Pass redisplay when this is an old response being shown again (pending a refresh) rather than a new arrival.

set_page_state_values(values: dict, *, push: bool = True) → None

Assign values into our page’s state.

With push, input rows showing those values are updated to match (input rows reporting their own changes have no need).

unlock_ui() → None

Resume normal UI interactions.

window_describe() → str

Describe this window in a line, for diagnostics.

Used by the ui cleanup check to say where a leaked object lived (a window’s own leak report, and that of any widget-owning object created inside it). Subclasses can add what identifies them: a doc-ui window names its controller and page.

class bauiv1lib.docui.TypedDocUIController

Bases: DocUIController, Generic

A controller working in type-safe routes and local-actions.

Where a plain DocUIController deals in request paths, arg dicts, and local-action names, this deals purely in the dataclasses a domain defines for such things (see bacommon.docui.routes). Pass the domain’s route and local-action unions as type args, point get_route_type() and get_local_action_type() at the matching family classes, and implement fulfill_route() and run_local_action().

final fulfill_request(request: DocUIRequest) → DocUIResponse

Handle request fulfillment.

Expected to be overridden by child classes.

Be aware that this will always be called in a background thread.

This method is expected to always return a response, even in the case of errors. Use error_response() to translate error conditions to responses.

The one exception to this rule (no pun intended) is the efro.error.CleanError exception. This can be raised as a quick and dirty way to show custom error messages. The code raise CleanError('Something broke.') will have the same effect as return self.error_response(custom_message='Something broke.').

fulfill_route(route: RouteT) → DocUIResponse

Handle fulfillment for a route.

The type-safe equivalent of fulfill_request(); the same rules apply (called in a background thread; should always return a response).

fulfill_unrouted_request(request: bacommon.docui.v2.Request, error: str) → DocUIResponse

Handle a request that maps to none of our routes.

The default shows error. Controllers fronting a server should generally forward the request as-is here instead; a server is free to grow pages (or arg values) that older clients have no routes for, and those should keep working.

get_local_action_press_sound(name: str) → PressSound

What a button plays when pressed to run a local-action.

Given the local-action’s name. The default clicks; typed controllers answer per local-action type (see bacommon.docui.routes.DocUILocalActionBase.get_press_sound()).

classmethod get_local_action_type() → type[DocUILocalActionBase]

Return the family class for the local-actions we handle.

Domains with no local-actions can leave this as is and pass typing.Never as their local-action type arg.

classmethod get_route_type() → type[DocUIRoute]

Return the family class for the routes we handle.

get_window_route(window: DocUIWindow) → RouteT | None

Return the route a window is showing, if it maps to one.

final local_action(action: DocUILocalAction) → None

Do something locally on behalf of the doc-ui.

Controller classes can override this to expose named actions that can be triggered by doc-ui button presses, responses, etc.

Of course controllers can also perform arbitrary local actions alongside their normal request fulfillment; this is simply a way to do so without needing to provide actual ui pages alongside.

Be very careful and focused with what you expose here, especially if your doc-ui pages are coming from untrusted sources. Generally things like launching or joining games are good candidates for local actions.

run_local_action(action: ActionT, context: DocUILocalAction) → None

Do something locally on behalf of the doc-ui.

The type-safe equivalent of local_action(); the same cautions apply. The original action is passed as context for access to the originating widget and window.

Subpackages

• bauiv1lib.docui.prep package