bacommon.docui.routes package

Type-safe routes and local-actions layered over doc-ui v2.

The doc-ui wire format is string based (request paths, arg dicts, local-action names). The classes here let first-party code work purely in dataclasses instead; the modules alongside define the routes for individual doc-ui domains and are shared by whichever ends (client and/or server) author or handle that domain’s pages.

class bacommon.docui.routes.DocUILocalActionBase

Bases: object

A local-action in a doc-ui domain, with args as dataclass fields.

The local-action analogue of DocUIRoute: each named action a domain’s client-side controller exposes is an @ioprepped dataclass inheriting from that domain’s family class (a direct child of this class).

attach(response: bacommon.docui.v2.Response) → None

Have a response run this local-action when first received.

classmethod from_name_and_args(name: str, args: dict) → Self

Return the local-action in this family matching a name + args.

Should be called on a family class. Raises DocUIRouteError if there is no match.

classmethod get_action_types() → tuple[type[DocUILocalActionBase], ...]

Return all concrete local-actions in this family.

Must be overridden by each family class; see get_route_types().

classmethod get_name() → str

Return the wire name for this local-action.

classmethod get_press_sound() → PressSound

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

Actions that stay on the page click (the default); override to return SWISH for ones that go somewhere (open a window or popup). A press whose action has default_sound off plays nothing either way.

local(*, close_window: bool = False, default_sound: bool = True, sets: Sequence[DocUIStateAssign] | None = None) → bacommon.docui.v2.Local

Return an action running this local-action immediately.

Any sets are applied to the pressing page’s state first.

classmethod press_sound_for_name(name: str) → PressSound

The press sound for the local-action in this family named so.

Should be called on a family class. Unknown names click.

class bacommon.docui.routes.DocUIRoute

Bases: object

A page in a doc-ui domain, with its args as dataclass fields.

Doc-ui (v2) requests are a path string plus a dict of args on the wire. A route is a type-safe stand-in for one: each page a domain offers is an @ioprepped dataclass inheriting from that domain’s family class (itself a direct child of this class). The dataclass’ fields are the page’s args; its path and request-method are given as keywords on its class line (class Foo(FooFamily, path='/foo', method=POST)).

Page code never touches the path or args dict directly: authoring goes through the browse() and replace() verbs and handling goes through from_request() (generally called on one’s behalf by a controller or request-handler base class).

Paths within a family are a closed set; anything variable belongs in args (no /item/<id> style paths). Routes are keyed on path and method, so a page and the POST that submits it can share a path.

browse(*, default_sound: bool = True, sets: Sequence[DocUIStateAssign] | None = None, state: DocUIState | None = None, layout: bacommon.docui.v2.WindowLayout | None = None, scroll_edge_style: bacommon.docui.v2.ScrollEdgeStyle | None = None) → bacommon.docui.v2.Browse

Return an action browsing to this route in a new window.

The pressing page’s state goes along with the request, with any sets applied to it. Pass state to send some other state entirely; generally what a different page expects. The window opens at layout, or at get_window_layout() if not given, with scroll_edge_style (or its layout’s default if not given). (Its viewer pane, if any, is up to each page; see viewer.)

classmethod from_request(request: bacommon.docui.v2.Request) → Self

Return the route in this family that a request maps to.

Should be called on a family class. Raises DocUIRouteError if the request does not map to a route in the family.

classmethod get_method() → bacommon.docui.v2.RequestMethod

Return the request method for this route.

classmethod get_path() → str

Return the request path for this route.

classmethod get_route_types() → tuple[type[DocUIRoute], ...]

Return all concrete routes in this family.

Must be overridden by each family class. A family generally defines a union alias of its routes (which also gives handlers assert_never exhaustiveness) and returns family_members() of it here.

get_source_request() → bacommon.docui.v2.Request | None

Return the request we were built from, if we were.

Unlike request(), which only ever describes the route itself, this carries whatever else rode along with the request (page state, trigger). Something forwarding an incoming route elsewhere as-is wants those to go along too.

get_state(state_type: type[S]) → S | None

Return page state that arrived with the request for us.

Only routes built from requests have any, and only when the page the request was fired from had state of this type; anything else gives None. State is always optional input, so callers need a story for that.

get_trigger() → str | None

State key of the input whose change fired our request, if any.

classmethod get_window_layout() → bacommon.docui.v2.WindowLayout

The layout windows browsing to this route open with.

browse() uses this unless told otherwise, so a route whose page is best shown at some layout declares it once rather than at every link.

Defaults to WIDE, which is the same size at every ui-scale, so a one-off page (a confirmation, a dialog) never ends up as a big mostly-empty window. LARGE, which grows to fill more of the screen at medium/large ui-scale, is for pages built to use that room (store listings and the like), and they ask for it explicitly.

replace(*, default_sound: bool = True, sets: Sequence[DocUIStateAssign] | None = None, state: DocUIState | None = None) → bacommon.docui.v2.Replace

Return an action replacing the current page with this route.

See browse() for sets and state.

request() → bacommon.docui.v2.Request

Return the wire request for this route.

exception bacommon.docui.routes.DocUIRouteError

Bases: Exception

A request or local-action could not be mapped to a typed form.

class bacommon.docui.routes.DocUIState

Bases: object

Values belonging to a doc-ui page, as dataclass fields.

Where route args say which page something is, state is what the user is in the middle of on it: the values its input rows show and edit plus anything else it wants handed back (a draft being composed, say). A page declares its state once and the client sends the current values along with every request fired from that page, so individual links need only say what they change.

Subclasses are @ioprepped dataclasses declaring a globally unique id on their class line (class Foo(DocUIState, state_id='mydomain.foo')). The id rides along with the values so that state arriving at a page expecting some other type reads as no state at all instead of being mis-decoded. Field storage names must not start with an underscore.

State is always optional input; a page must be able to make do without any (see DocUIRoute.get_state).

classmethod assign(field: Callable[[Self], V], value: V) → DocUIStateAssign

classmethod assign(field: Callable[[Self], V | None], value: V) → DocUIStateAssign

Return an assignment of a value to one of our fields.

For passing as sets when creating actions: route.replace(sets=[MyState.assign(lambda s: s.color, c)]). The value is type-checked against the field. (The second overload is what lets a plain E be assigned to an E | None field: mypy settles the type variable from the value before it looks at the lambda.)

classmethod assign_locally(*assigns: DocUIStateAssign, default_sound: bool = True) → bacommon.docui.v2.Local

Return an action assigning values with no request involved.

The values simply go out with whatever the page sends next.

classmethod assign_on_return(*assigns: DocUIStateAssign, default_sound: bool = True) → bacommon.docui.v2.Local

Return an action closing the window, handing values back.

For a picker opened in a window of its own: the window closes and the values are assigned into the state of the page returned to (which must hold our state type; the client checks), which then refreshes with them.

classmethod checkbox_row(field: Callable[[Self], bool], *, label: LangStrSpec | None = None, title: LangStrSpec | None = None, subtitle: LangStrSpec | None = None, title_align: bacommon.docui.v2.HAlign | None = None, footnote: LangStrSpec | None = None, on_change: bacommon.docui.v2.Action | None = None, disabled: bool = False, debug: bool = False) → bacommon.docui.v2.CheckboxRow

Return a checkbox row editing one of our (bool) fields.

disabled shows it dimmed and not toggleable (still selectable).

classmethod choice_row(field: Callable[[Self], E], *, choice_label: Callable[[E], LangStrSpec], choices: Sequence[E] | None = None, disabled_choices: Collection[E] = (), label: LangStrSpec | None = None, title: LangStrSpec | None = None, subtitle: LangStrSpec | None = None, title_align: bacommon.docui.v2.HAlign | None = None, footnote: LangStrSpec | None = None, on_change: bacommon.docui.v2.Action | None = None, disabled: bool = False, debug: bool = False) → bacommon.docui.v2.ChoiceRow

classmethod choice_row(field: Callable[[Self], E | None], *, choice_label: Callable[[E], LangStrSpec], none_label: LangStrSpec, choices: Sequence[E] | None = None, disabled_choices: Collection[E] = (), label: LangStrSpec | None = None, title: LangStrSpec | None = None, subtitle: LangStrSpec | None = None, title_align: bacommon.docui.v2.HAlign | None = None, footnote: LangStrSpec | None = None, on_change: bacommon.docui.v2.Action | None = None, disabled: bool = False, debug: bool = False) → bacommon.docui.v2.ChoiceRow

classmethod choice_row(field: Callable[[Self], str], *, choices: Sequence[tuple[str, LangStrSpec]], disabled_choices: Collection[str] = (), label: LangStrSpec | None = None, title: LangStrSpec | None = None, subtitle: LangStrSpec | None = None, title_align: bacommon.docui.v2.HAlign | None = None, footnote: LangStrSpec | None = None, on_change: bacommon.docui.v2.Action | None = None, disabled: bool = False, debug: bool = False) → bacommon.docui.v2.ChoiceRow

classmethod choice_row(field: Callable[[Self], str | None], *, choices: Sequence[tuple[str, LangStrSpec]], none_label: LangStrSpec, disabled_choices: Collection[str] = (), label: LangStrSpec | None = None, title: LangStrSpec | None = None, subtitle: LangStrSpec | None = None, title_align: bacommon.docui.v2.HAlign | None = None, footnote: LangStrSpec | None = None, on_change: bacommon.docui.v2.Action | None = None, disabled: bool = False, debug: bool = False) → bacommon.docui.v2.ChoiceRow

Return a choice row editing one of our enum or str fields.

For an enum field, choice_label gives each option’s display text; write it as a match ending in assert_never so a new enum member can’t go unlabeled. choices narrows/reorders the options shown (default: every member, in definition order).

For a str field there is no closed set to be exhaustive over, so choices instead defines the options as (value, label) pairs, in display order; choice_label does not apply. The state’s current value should be among them (a value that isn’t shows as the first option).

disabled_choices lists options to show greyed out and unpickable (enum members, or str values, matching how choices are given) – each must be one of the options. disabled instead disables the whole row: shown dimmed with its menu unopenable (still selectable).

A field typed E | None / str | None gets a ‘nothing’ option too, listed first, whose display text is none_label – required for such fields and not allowed for others. The type checker enforces the required halves of all this via the overloads; what it can’t express (a stray none_label or choice_label) is checked here at runtime along with the rest.

classmethod color_row(field: Callable[[Self], tuple[float, float, float]], *, label: LangStrSpec | None = None, title: LangStrSpec | None = None, subtitle: LangStrSpec | None = None, title_align: bacommon.docui.v2.HAlign | None = None, footnote: LangStrSpec | None = None, on_change: bacommon.docui.v2.Action | None = None, disabled: bool = False, debug: bool = False) → bacommon.docui.v2.ColorRow

Return a color row editing one of our rgb fields.

The field must be typed tuple[float, float, float] (0-1 components). on_change fires when the picker closes with a changed color, not per intermediate change. disabled shows it dimmed with its picker unopenable (still selectable).

classmethod decode(data: dict | None) → Self | None

Return state of this type from its wire form, if that it be.

Returns None for no data, data for some other state type, or data that fails to decode. State comes from clients and is always optional, so none of those are errors.

encode() → dict

Return the wire form of this state (for Page.state etc.).

classmethod get_keys() → set[str]

Return the wire keys of all of our fields.

classmethod get_state_id() → str

Return the wire id for this state type.

classmethod key(field: Callable[[Self], Any]) → str

Return the wire key for a field, given a lambda fetching it.

MyState.key(lambda s: s.some_field)

classmethod number_row(field: Callable[[Self], float], *, min_value: float, max_value: float, increment: float, as_percent: bool = False, decimals: int = 0, label: LangStrSpec | None = None, title: LangStrSpec | None = None, subtitle: LangStrSpec | None = None, title_align: bacommon.docui.v2.HAlign | None = None, footnote: LangStrSpec | None = None, on_change: bacommon.docui.v2.Action | None = None, disabled: bool = False, debug: bool = False) → bacommon.docui.v2.NumberRow

Return a ‘-‘/’+’ number row editing one of our float fields.

on_change fires on each press that changes the value. disabled shows it dimmed and not adjustable (still selectable). See bacommon.docui.v2.NumberRow.

classmethod slider_row(field: Callable[[Self], float], *, min_value: float, max_value: float, increment: float, as_percent: bool = False, decimals: int = 2, label: LangStrSpec | None = None, title: LangStrSpec | None = None, subtitle: LangStrSpec | None = None, title_align: bacommon.docui.v2.HAlign | None = None, footnote: LangStrSpec | None = None, on_change: bacommon.docui.v2.Action | None = None, on_drag: bacommon.docui.v2.Local | None = None, drag_interval: float = 0.25, drag_delay: float = 0.0, disabled: bool = False, debug: bool = False) → bacommon.docui.v2.SliderRow

Return a slider row editing one of our float fields.

on_change fires for a settled value (release, or a run of key/controller steps going quiet); on_drag – a local action, built via MyAction().local() – fires during a drag (key/controller steps included) at the throttled cadence drag_interval / drag_delay describe, reading the live value from the page’s state. disabled shows it dimmed and not adjustable (still selectable). See bacommon.docui.v2.SliderRow.

classmethod text_input_row(field: Callable[[Self], str], *, label: LangStrSpec | None = None, title: LangStrSpec | None = None, subtitle: LangStrSpec | None = None, title_align: bacommon.docui.v2.HAlign | None = None, footnote: LangStrSpec | None = None, description: LangStrSpec | None = None, max_chars: int = 64, on_change: bacommon.docui.v2.Action | None = None, on_submit: bacommon.docui.v2.Action | None = None, disabled: bool = False, debug: bool = False) → bacommon.docui.v2.TextInputRow

Return a text-input row editing one of our (str) fields.

disabled shows it dimmed and not editable (still selectable).

class bacommon.docui.routes.DocUIStateAssign(state_type: type[DocUIState], key: str, value: Any)

Bases: object

A value to be assigned into a page’s state.

Create these via DocUIState.assign().

key: str

state_type: type[DocUIState]

value: Any

class bacommon.docui.routes.NoLocalActions

Bases: DocUILocalActionBase

Stock local-action family for domains that have none.

Pair with typing.Never as the local-action type arg.

classmethod get_action_types() → tuple[type[DocUILocalActionBase], ...]

Return all concrete local-actions in this family.

Must be overridden by each family class; see get_route_types().

class bacommon.docui.routes.PressSound(*values)

Bases: Enum

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

See get_press_sound().

CLICK = 'click'

The standard click, for actions that stay on the page.

NONE = 'none'

Nothing (the action handles any sound itself).

SWISH = 'swish'

The standard ui swish, for actions that go somewhere – open a window or a popup, say – like a browse does.

bacommon.docui.routes.family_members(alias: Any) → tuple[Any, ...]

Return the classes making up a family’s union alias.

Handles the degenerate single-member case, where the ‘union’ is simply the one class.

bacommon.docui.routes.validate_page_state(page: bacommon.docui.v2.Page) → None

Make sure a page’s use of its state hangs together.

Checks that everything referring to the page’s state by key (input rows, sets on actions) names a real field of the state type the page declares. Those are all produced by type-checked calls, but nothing static ties them to the same state type as the page’s, so that part gets checked here. Pages whose state is of no type known to us (third party ones, say) are left alone.

Submodules

bacommon.docui.routes.classiccharacterpreview module

Routes for the classic character-preview doc-ui domain.

A character being tried out in a game (sent there from its builder page; see the game’s character-preview session): the profile editor for it, as a player who picks the character will see it. Saving changes nothing stored anywhere; it answers with the character as edited for the preview session to carry on with.

bacommon.docui.routes.classiccharacterpreview.AnyCharacterPreviewLocalAction

alias of Saved

class bacommon.docui.routes.classiccharacterpreview.CharacterPreviewLocalAction

Bases: DocUILocalActionBase

Family class for classic character-preview local-actions.

classmethod get_action_types() → tuple[type[DocUILocalActionBase], ...]

Return all concrete local-actions in this family.

Must be overridden by each family class; see get_route_types().

class bacommon.docui.routes.classiccharacterpreview.CharacterPreviewRoute

Bases: DocUIRoute

Family class for classic character-preview routes.

classmethod get_route_types() → tuple[type[DocUIRoute], ...]

Return all concrete routes in this family.

Must be overridden by each family class. A family generally defines a union alias of its routes (which also gives handlers assert_never exhaustiveness) and returns family_members() of it here.

classmethod get_window_layout() → WindowLayout

The layout windows browsing to this route open with.

browse() uses this unless told otherwise, so a route whose page is best shown at some layout declares it once rather than at every link.

Defaults to WIDE, which is the same size at every ui-scale, so a one-off page (a confirmation, a dialog) never ends up as a big mostly-empty window. LARGE, which grows to fill more of the screen at medium/large ui-scale, is for pages built to use that room (store listings and the like), and they ask for it explicitly.

class bacommon.docui.routes.classiccharacterpreview.Edit(preview_id: str)

Bases: CharacterPreviewRoute

The profile editor for a previewed character.

The draft being composed rides along as page state (the profile editor’s own: ProfileDraft).

preview_id: str

The preview’s id, as the game was given it with the character.

class bacommon.docui.routes.classiccharacterpreview.Save(preview_id: str)

Bases: CharacterPreviewRoute

Save the editor’s draft; answered with Saved.

preview_id: str

class bacommon.docui.routes.classiccharacterpreview.Saved(preview_id: str, character: str)

Bases: CharacterPreviewLocalAction

The previewed character was edited; here it is as it now stands.

character: str

The character, in the form the game was first given it.

preview_id: str

bacommon.docui.routes.classicchest module

Routes for the classic chest doc-ui domain.

One chest slot: what’s in it, its prize odds and its unlock wait, with buttons to open it (now, for tokens, or once unlocked) or to watch an ad to cut the wait. Opening answers with the chest’s contents and the open animation as client-effects.

class bacommon.docui.routes.classicchest.AdWatched(slot: int)

Bases: ChestRoute

The player watched an ad to reduce a chest’s wait.

Answered like Open if that unlocked it; otherwise with the slot as it now stands.

slot: int

class bacommon.docui.routes.classicchest.ChestLocalAction

Bases: DocUILocalActionBase

Family class for classic chest local-actions.

classmethod get_action_types() → tuple[type[DocUILocalActionBase], ...]

Return all concrete local-actions in this family.

Must be overridden by each family class; see get_route_types().

class bacommon.docui.routes.classicchest.ChestRoute

Bases: DocUIRoute

Family class for classic chest routes.

classmethod get_route_types() → tuple[type[DocUIRoute], ...]

Return all concrete routes in this family.

Must be overridden by each family class. A family generally defines a union alias of its routes (which also gives handlers assert_never exhaustiveness) and returns family_members() of it here.

classmethod get_window_layout() → WindowLayout

The layout windows browsing to this route open with.

browse() uses this unless told otherwise, so a route whose page is best shown at some layout declares it once rather than at every link.

Defaults to WIDE, which is the same size at every ui-scale, so a one-off page (a confirmation, a dialog) never ends up as a big mostly-empty window. LARGE, which grows to fill more of the screen at medium/large ui-scale, is for pages built to use that room (store listings and the like), and they ask for it explicitly.

class bacommon.docui.routes.classicchest.GetTokens

Bases: ChestLocalAction

Offer to get more tokens (not enough to open a chest now).

classmethod get_press_sound() → PressSound

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

Actions that stay on the page click (the default); override to return SWISH for ones that go somewhere (open a window or popup). A press whose action has default_sound off plays nothing either way.

class bacommon.docui.routes.classicchest.Open(slot: int, token_payment: int)

Bases: ChestRoute

Open a chest, paying any tokens its wait currently costs.

Answered with its contents and the open animation.

slot: int

token_payment: int

Tokens the player agreed to pay (0 for an unlocked chest). The open fails if the cost has since changed.

class bacommon.docui.routes.classicchest.Root(slot: int, ad_ready: bool = False, open_me: bool = False)

Bases: ChestRoute

A chest slot: its chest (if any) and what can be done with it.

The two flags are things only the client knows, so it states them when asking.

ad_ready: bool = False

Whether an ad is ready to show right now (so a ‘watch an ad to reduce the wait’ button can work).

open_me: bool = False

Whether to remind about opening early with tokens (the player can switch the reminder off).

slot: int

Which slot (0-based).

class bacommon.docui.routes.classicchest.StopReminding(slot: int)

Bases: ChestLocalAction

Stop reminding about opening chests early; re-show the slot.

slot: int

class bacommon.docui.routes.classicchest.WatchAd(slot: int)

Bases: ChestLocalAction

Show an ad; once watched, ask for AdWatched.

slot: int

bacommon.docui.routes.classichost module

Routes for the classic host doc-ui domain.

Pages a game host serves its connected clients over the game connection (see bacommon.hostui): the defaults classic hosts ship with. Hosts may serve other routes of their own alongside these.

class bacommon.docui.routes.classichost.ClassicHostRoute

Bases: DocUIRoute

Family class for classic host routes.

classmethod get_route_types() → tuple[type[DocUIRoute], ...]

Return all concrete routes in this family.

Must be overridden by each family class. A family generally defines a union alias of its routes (which also gives handlers assert_never exhaustiveness) and returns family_members() of it here.

class bacommon.docui.routes.classichost.KickVote(client_id: int | None = None)

Bases: ClassicHostRoute

Start or follow a vote to kick someone.

Clients open this with client_id set to whoever they chose to kick; without one it shows any vote in progress.

client_id: int | None = None

class bacommon.docui.routes.classichost.KickVoteCast(yes: bool)

Bases: ClassicHostRoute

Vote in the kick vote in progress.

yes: bool

class bacommon.docui.routes.classichost.KickVoteStart(client_id: int)

Bases: ClassicHostRoute

Start a vote to kick a client.

client_id: int

class bacommon.docui.routes.classichost.Stats

Bases: ClassicHostRoute

Who is in the party and how their connections are doing.

bacommon.docui.routes.classicinbox module

Routes for the classic inbox doc-ui domain.

The inbox lists an account’s messages (rewards, notices, tournament results) as cards; responding to one – claiming a reward, accepting or declining – posts back and gets the updated list in return.

class bacommon.docui.routes.classicinbox.InboxLocalAction

Bases: DocUILocalActionBase

Family class for classic inbox local-actions.

classmethod get_action_types() → tuple[type[DocUILocalActionBase], ...]

Return all concrete local-actions in this family.

Must be overridden by each family class; see get_route_types().

class bacommon.docui.routes.classicinbox.InboxRoute

Bases: DocUIRoute

Family class for classic inbox routes.

classmethod get_route_types() → tuple[type[DocUIRoute], ...]

Return all concrete routes in this family.

Must be overridden by each family class. A family generally defines a union alias of its routes (which also gives handlers assert_never exhaustiveness) and returns family_members() of it here.

classmethod get_window_layout() → WindowLayout

The layout windows browsing to this route open with.

browse() uses this unless told otherwise, so a route whose page is best shown at some layout declares it once rather than at every link.

Defaults to WIDE, which is the same size at every ui-scale, so a one-off page (a confirmation, a dialog) never ends up as a big mostly-empty window. LARGE, which grows to fill more of the screen at medium/large ui-scale, is for pages built to use that room (store listings and the like), and they ask for it explicitly.

class bacommon.docui.routes.classicinbox.OpenUrl(url: str)

Bases: InboxLocalAction

Open a url in the platform’s browser.

url: str

class bacommon.docui.routes.classicinbox.Respond(entry_id: str, positive: bool = True)

Bases: InboxRoute

Respond to one message (claim it, accept or decline it, etc.).

Answered with the updated inbox, with any effects of the response (reward animations, sounds) attached. Shares the inbox’s own path so the client treats the answer as the same page updated (holding its scroll position) rather than a new one.

entry_id: str

The message.

positive: bool = True

Whether this is the message’s positive response (claim, accept, ok) as opposed to its negative one (decline).

class bacommon.docui.routes.classicinbox.Root(debug: bool = False)

Bases: InboxRoute

The inbox: every message, newest first.

debug: bool = False

Draw bounds and other debug bits.

class bacommon.docui.routes.classicinbox.TourneyScores(tournament_id: str)

Bases: InboxLocalAction

Show a tournament’s final standings.

classmethod get_press_sound() → PressSound

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

Actions that stay on the page click (the default); override to return SWISH for ones that go somewhere (open a window or popup). A press whose action has default_sound off plays nothing either way.

tournament_id: str

bacommon.docui.routes.classicleaguepresidency module

Routes for the classic league-presidency doc-ui domain.

bacommon.docui.routes.classicleaguepresidency.AnyLeaguePresidencyLocalAction

alias of GetTokens

class bacommon.docui.routes.classicleaguepresidency.BidState(bid: int = 0)

Bases: DocUIState

The presidency page’s state: the bid being composed.

Clients that speak page state carry this; older ones carry the same value as the bid arg on the routes.

bid: int = 0

class bacommon.docui.routes.classicleaguepresidency.GetTokens

Bases: LeaguePresidencyLocalAction

Show the get-tokens window.

class bacommon.docui.routes.classicleaguepresidency.LeaguePresidencyLocalAction

Bases: DocUILocalActionBase

Family class for classic league-presidency local-actions.

classmethod get_action_types() → tuple[type[DocUILocalActionBase], ...]

Return all concrete local-actions in this family.

Must be overridden by each family class; see get_route_types().

class bacommon.docui.routes.classicleaguepresidency.LeaguePresidencyRoute

Bases: DocUIRoute

Family class for classic league-presidency routes.

classmethod get_route_types() → tuple[type[DocUIRoute], ...]

Return all concrete routes in this family.

Must be overridden by each family class. A family generally defines a union alias of its routes (which also gives handlers assert_never exhaustiveness) and returns family_members() of it here.

classmethod get_window_layout() → WindowLayout

The layout windows browsing to this route open with.

browse() uses this unless told otherwise, so a route whose page is best shown at some layout declares it once rather than at every link.

Defaults to WIDE, which is the same size at every ui-scale, so a one-off page (a confirmation, a dialog) never ends up as a big mostly-empty window. LARGE, which grows to fill more of the screen at medium/large ui-scale, is for pages built to use that room (store listings and the like), and they ask for it explicitly.

class bacommon.docui.routes.classicleaguepresidency.Root(bid: int = 0, debug: bool = False, season: str | None = None)

Bases: LeaguePresidencyRoute

The presidency page for the account’s current league.

bid: int = 0

The bid being composed (the page’s +/- buttons adjust this). Only meaningful for clients without page state; others carry it in BidState.

debug: bool = False

Draw bounds and other debug bits.

season: str | None = None

Season the client was looking at when it opened us. Not currently used (the page always shows the current season).

class bacommon.docui.routes.classicleaguepresidency.SubmitBid(bid: int = 0, debug: bool = False)

Bases: LeaguePresidencyRoute

Submit a bid.

bid: int = 0

See Root.bid.

debug: bool = False

bacommon.docui.routes.classicstore module

Routes for the classic store and inventory doc-ui domains.

The store and inventory are two domains served by a single set of pages (the inventory is essentially the store filtered to owned things plus player-profiles), so they share one route family. Each has its own local-actions.

class bacommon.docui.routes.classicstore.EditProfile(profile: str)

Bases: InventoryLocalAction

Open the (legacy) profile editor on an existing profile.

classmethod get_press_sound() → PressSound

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

Actions that stay on the page click (the default); override to return SWISH for ones that go somewhere (open a window or popup). A press whose action has default_sound off plays nothing either way.

profile: str

class bacommon.docui.routes.classicstore.GetTokens

Bases: StoreLocalAction

Show the get-tokens window.

class bacommon.docui.routes.classicstore.InventoryLocalAction

Bases: DocUILocalActionBase

Family class for classic inventory local-actions.

classmethod get_action_types() → tuple[type[DocUILocalActionBase], ...]

Return all concrete local-actions in this family.

Must be overridden by each family class; see get_route_types().

class bacommon.docui.routes.classicstore.NewProfile

Bases: InventoryLocalAction

Open the (legacy) profile editor on a new profile.

classmethod get_press_sound() → PressSound

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

Actions that stay on the page click (the default); override to return SWISH for ones that go somewhere (open a window or popup). A press whose action has default_sound off plays nothing either way.

class bacommon.docui.routes.classicstore.ProfileCharacter

Bases: StoreRoute

(Inventory) pick the profile editor’s character.

Opened from the editor, whose ProfileDraft comes along as page state; picking one hands it back to the editor (see assign_on_return()).

classmethod get_window_layout() → WindowLayout

The layout windows browsing to this route open with.

browse() uses this unless told otherwise, so a route whose page is best shown at some layout declares it once rather than at every link.

Defaults to WIDE, which is the same size at every ui-scale, so a one-off page (a confirmation, a dialog) never ends up as a big mostly-empty window. LARGE, which grows to fill more of the screen at medium/large ui-scale, is for pages built to use that room (store listings and the like), and they ask for it explicitly.

class bacommon.docui.routes.classicstore.ProfileDelete(profile_name: str)

Bases: StoreRoute

(Inventory) delete a stored profile.

profile_name: str

class bacommon.docui.routes.classicstore.ProfileDeleteConfirm(profile_name: str)

Bases: StoreRoute

(Inventory) confirm deleting a stored profile.

Replaces the editor’s page in its window; its draft rides along as page state, so cancelling goes back to the editor with it intact.

classmethod get_window_layout() → WindowLayout

The layout windows browsing to this route open with.

browse() uses this unless told otherwise, so a route whose page is best shown at some layout declares it once rather than at every link.

Defaults to WIDE, which is the same size at every ui-scale, so a one-off page (a confirmation, a dialog) never ends up as a big mostly-empty window. LARGE, which grows to fill more of the screen at medium/large ui-scale, is for pages built to use that room (store listings and the like), and they ask for it explicitly.

profile_name: str

class bacommon.docui.routes.classicstore.ProfileDraft(color: tuple[float, float, float], highlight: tuple[float, float, float], name: str = '', character: str = '', icon: str = '')

Bases: DocUIState

The profile editor’s working profile.

Page state for the editor and its save: what the user has composed so far. A request with no draft at all (the first visit) gets one built from the stored profile, or fresh defaults when creating; an empty name, character or icon means the same for that field.

character: str = ''

color: tuple[float, float, float]

highlight: tuple[float, float, float]

icon: str = ''

name: str = ''

class bacommon.docui.routes.classicstore.ProfileEdit(profile_name: str | None = None)

Bases: StoreRoute

(Inventory) the cloud player-profile editor.

The draft being composed rides along as ProfileDraft page state; the route itself only says which stored profile (if any) is being edited.

classmethod get_window_layout() → WindowLayout

The layout windows browsing to this route open with.

browse() uses this unless told otherwise, so a route whose page is best shown at some layout declares it once rather than at every link.

Defaults to WIDE, which is the same size at every ui-scale, so a one-off page (a confirmation, a dialog) never ends up as a big mostly-empty window. LARGE, which grows to fill more of the screen at medium/large ui-scale, is for pages built to use that room (store listings and the like), and they ask for it explicitly.

profile_name: str | None = None

Stored profile being edited, or None when creating one.

class bacommon.docui.routes.classicstore.ProfileGlobalUpgrade(profile_name: str)

Bases: StoreRoute

(Inventory) offer to upgrade a cloud profile to a global one.

Says whether the name can be had and what it costs. Like ProfileDeleteConfirm, it replaces the editor’s page in its window with the editor’s draft riding along as page state.

classmethod get_window_layout() → WindowLayout

The layout windows browsing to this route open with.

browse() uses this unless told otherwise, so a route whose page is best shown at some layout declares it once rather than at every link.

Defaults to WIDE, which is the same size at every ui-scale, so a one-off page (a confirmation, a dialog) never ends up as a big mostly-empty window. LARGE, which grows to fill more of the screen at medium/large ui-scale, is for pages built to use that room (store listings and the like), and they ask for it explicitly.

profile_name: str

class bacommon.docui.routes.classicstore.ProfileGlobalUpgradeBuy(profile_name: str, ticket_cost: int)

Bases: StoreRoute

(Inventory) upgrade a cloud profile to a global one.

profile_name: str

ticket_cost: int

The price the offer page showed; a changed price is refused rather than silently charged.

class bacommon.docui.routes.classicstore.ProfileIcon

Bases: StoreRoute

(Inventory) pick the profile editor’s icon.

Works as ProfileCharacter does: the editor’s ProfileDraft comes along as page state and the pick is handed back to it.

classmethod get_window_layout() → WindowLayout

The layout windows browsing to this route open with.

browse() uses this unless told otherwise, so a route whose page is best shown at some layout declares it once rather than at every link.

Defaults to WIDE, which is the same size at every ui-scale, so a one-off page (a confirmation, a dialog) never ends up as a big mostly-empty window. LARGE, which grows to fill more of the screen at medium/large ui-scale, is for pages built to use that room (store listings and the like), and they ask for it explicitly.

class bacommon.docui.routes.classicstore.ProfileMigrate(profiles_only: bool = False, debug: bool = False)

Bases: StoreRoute

(Inventory) copy the account’s legacy profiles into cloud ones.

Requested by the ‘Converting profiles…’ page the root shows while a migration is due; redirects back to the root afterward (carrying the root’s view arguments along).

debug: bool = False

See Root.debug.

profiles_only: bool = False

See Root.profiles_only.

class bacommon.docui.routes.classicstore.ProfileSave(profile_name: str | None = None)

Bases: StoreRoute

(Inventory) save the editor’s draft (its ProfileDraft).

profile_name: str | None = None

See ProfileEdit.profile_name.

class bacommon.docui.routes.classicstore.Purchase(purchase_id: str, debug: bool = False)

Bases: StoreRoute

Purchase options for a single item.

debug: bool = False

purchase_id: str

class bacommon.docui.routes.classicstore.PurchaseConfirm(purchase_id: str, purchase_method: PurchaseMethod, debug: bool = False)

Bases: StoreRoute

Actually purchase an item.

debug: bool = False

purchase_id: str

purchase_method: PurchaseMethod

class bacommon.docui.routes.classicstore.PurchaseMethod(*values)

Bases: Enum

How to purchase something.

GOLD_PASS = 'g'

PURPLE_TICKETS = 'p'

TICKETS = 'k'

TOKENS = 't'

class bacommon.docui.routes.classicstore.RestorePurchases

Bases: StoreLocalAction

Kick off a platform purchase-restore.

class bacommon.docui.routes.classicstore.Root(debug: bool = False, is_refresh: bool = False, legacy_profiles: bool = False, profiles_only: bool = False, unlockreqs: list[str] | None = None)

Bases: StoreRoute

The main store/inventory listing.

debug: bool = False

Draw bounds and other debug bits.

classmethod get_window_layout() → WindowLayout

The layout windows browsing to this route open with.

browse() uses this unless told otherwise, so a route whose page is best shown at some layout declares it once rather than at every link.

Defaults to WIDE, which is the same size at every ui-scale, so a one-off page (a confirmation, a dialog) never ends up as a big mostly-empty window. LARGE, which grows to fill more of the screen at medium/large ui-scale, is for pages built to use that room (store listings and the like), and they ask for it explicitly.

is_refresh: bool = False

Set on the page’s own refresh button. One-time-use; the server does not carry it into further links.

legacy_profiles: bool = False

(Inventory) the client is showing its locally-spliced legacy profiles; omit cloud profile rows.

profiles_only: bool = False

(Inventory) render only the profiles section (the in-game profile browser).

unlockreqs: list[str] | None = None

Legacy purchase ids required to unlock something; when provided, only items providing those are shown.

class bacommon.docui.routes.classicstore.ShowCloudProfiles

Bases: InventoryLocalAction

Switch the inventory to cloud profiles.

class bacommon.docui.routes.classicstore.ShowLegacyProfiles

Bases: InventoryLocalAction

Switch the inventory to the client’s legacy profiles.

class bacommon.docui.routes.classicstore.SpawnBot(name: str)

Bases: InventoryLocalAction

Spawn a character in the main-menu background.

name: str

Internal appearance name of the character.

class bacommon.docui.routes.classicstore.StoreLocalAction

Bases: DocUILocalActionBase

Family class for classic store local-actions.

classmethod get_action_types() → tuple[type[DocUILocalActionBase], ...]

Return all concrete local-actions in this family.

Must be overridden by each family class; see get_route_types().

class bacommon.docui.routes.classicstore.StoreRoute

Bases: DocUIRoute

Family class for classic store/inventory routes.

classmethod get_route_types() → tuple[type[DocUIRoute], ...]

Return all concrete routes in this family.

Must be overridden by each family class. A family generally defines a union alias of its routes (which also gives handlers assert_never exhaustiveness) and returns family_members() of it here.

bacommon.docui.routes.docuitest module

Routes for the doc-ui test domain.

class bacommon.docui.routes.docuitest.Animation

Bases: TestRoute

Decorations animated by keyframe client-effects.

class bacommon.docui.routes.docuitest.BoundsTests

Bases: TestRoute

Button-style bounds tests.

class bacommon.docui.routes.docuitest.ButtonGrids(debug: bool = False)

Bases: TestRoute

Grid button rows: columns, cells, alignment and navigation.

Browse to it at several layouts; grids reflow to fit each width.

debug: bool = False

class bacommon.docui.routes.docuitest.CloudMsgTestGet

Bases: TestRoute

A page fetched through our cloud connection via GET.

class bacommon.docui.routes.docuitest.CloudMsgTestPost

Bases: TestRoute

A page fetched through our cloud connection via POST.

class bacommon.docui.routes.docuitest.ControlRowKind(*values)

Bases: Enum

Kinds of control row (for NavTest).

BUTTON = 'button'

CHECKBOX = 'checkbox'

CHOICE = 'choice'

COLOR = 'color'

NUMBER = 'number'

SLIDER = 'slider'

TEXT_INPUT = 'text'

class bacommon.docui.routes.docuitest.Depictions(debug: bool = False)

Bases: TestRoute

Depiction tests.

debug: bool = False

class bacommon.docui.routes.docuitest.DisplayItems(debug: bool = False)

Bases: TestRoute

Display-item tests.

debug: bool = False

class bacommon.docui.routes.docuitest.EmptyPage

Bases: TestRoute

A page with nothing on it.

class bacommon.docui.routes.docuitest.Flavor(*values)

Bases: Enum

Something to pick from on the widgets test page.

CHOCOLATE = 'c'

MINT = 'm'

STRAWBERRY = 's'

VANILLA = 'v'

class bacommon.docui.routes.docuitest.LiveTimes

Bases: TestRoute

Time-varying text (countdowns, elapsed times) that ticks itself.

class bacommon.docui.routes.docuitest.Names(debug: bool = False)

Bases: TestRoute

Name depiction tests (basic and capsule forms).

debug: bool = False

class bacommon.docui.routes.docuitest.NavTest(kind: ControlRowKind = ControlRowKind.CHECKBOX)

Bases: TestRoute

A button row, then one control row of some kind as the last row.

For checking directional navigation on control rows: down from the last row should reach the toolbars, left should reach the back button, and right from a row’s rightmost control should do nothing.

kind: ControlRowKind = 'checkbox'

class bacommon.docui.routes.docuitest.NinePatch(debug: bool = False)

Bases: TestRoute

9-patch image tests (stretched and tile-fit, tinted).

debug: bool = False

class bacommon.docui.routes.docuitest.Root(debug: bool = False, test_effects: bool = False, test_action: bool = False)

Bases: TestRoute

The root test page.

debug: bool = False

Draw bounds and other debug bits.

test_action: bool = False

Have the response include a local-action.

test_effects: bool = False

Have the response include some client-effects.

class bacommon.docui.routes.docuitest.Sections(debug: bool = False)

Bases: TestRoute

Sections: headings, notes, backings and spacing between them.

debug: bool = False

classmethod get_window_layout() → WindowLayout

The layout windows browsing to this route open with.

browse() uses this unless told otherwise, so a route whose page is best shown at some layout declares it once rather than at every link.

Defaults to WIDE, which is the same size at every ui-scale, so a one-off page (a confirmation, a dialog) never ends up as a big mostly-empty window. LARGE, which grows to fill more of the screen at medium/large ui-scale, is for pages built to use that room (store listings and the like), and they ask for it explicitly.

class bacommon.docui.routes.docuitest.ShowVolume

Bases: TestLocalAction

Show the volume slider’s live value (fired while dragging).

class bacommon.docui.routes.docuitest.Size(*values)

Bases: Enum

Something else to pick from on the widgets test page.

L = 'l'

M = 'm'

S = 's'

XL = 'x'

class bacommon.docui.routes.docuitest.Slow

Bases: TestRoute

A page that takes a while to load.

class bacommon.docui.routes.docuitest.Test2

Bases: TestRoute

A second simple page.

class bacommon.docui.routes.docuitest.TestAction(testparam: int)

Bases: TestLocalAction

Show a message proving we got here.

testparam: int

class bacommon.docui.routes.docuitest.TestLocalAction

Bases: DocUILocalActionBase

Family class for doc-ui test local-actions.

classmethod get_action_types() → tuple[type[DocUILocalActionBase], ...]

Return all concrete local-actions in this family.

Must be overridden by each family class; see get_route_types().

class bacommon.docui.routes.docuitest.TestRoute

Bases: DocUIRoute

Family class for doc-ui test routes.

classmethod get_route_types() → tuple[type[DocUIRoute], ...]

Return all concrete routes in this family.

Must be overridden by each family class. A family generally defines a union alias of its routes (which also gives handlers assert_never exhaustiveness) and returns family_members() of it here.

classmethod get_window_layout() → WindowLayout

The layout windows browsing to this route open with.

browse() uses this unless told otherwise, so a route whose page is best shown at some layout declares it once rather than at every link.

Defaults to WIDE, which is the same size at every ui-scale, so a one-off page (a confirmation, a dialog) never ends up as a big mostly-empty window. LARGE, which grows to fill more of the screen at medium/large ui-scale, is for pages built to use that room (store listings and the like), and they ask for it explicitly.

class bacommon.docui.routes.docuitest.TextImages(debug: bool = False)

Bases: TestRoute

Text-with-images tests.

debug: bool = False

class bacommon.docui.routes.docuitest.TextWrapping(debug: bool = False)

Bases: TestRoute

Titles, subtitles and footnotes word-wrapped to their columns.

debug: bool = False

class bacommon.docui.routes.docuitest.TimedActions(val: int = 5)

Bases: TestRoute

A page that counts down via timed-actions and then closes.

val: int = 5

class bacommon.docui.routes.docuitest.Viewers(case: str = '')

Bases: TestRoute

Live viewer tests: good cases and bad data, one shown at a time.

The page’s own controls switch cases, and the pane’s style and side (page state), in place.

case: str = ''

Which case the viewer pane shows (a test-page case name; unknown names show the first).

classmethod get_window_layout() → WindowLayout

The layout windows browsing to this route open with.

browse() uses this unless told otherwise, so a route whose page is best shown at some layout declares it once rather than at every link.

Defaults to WIDE, which is the same size at every ui-scale, so a one-off page (a confirmation, a dialog) never ends up as a big mostly-empty window. LARGE, which grows to fill more of the screen at medium/large ui-scale, is for pages built to use that room (store listings and the like), and they ask for it explicitly.

class bacommon.docui.routes.docuitest.WebTestGet

Bases: TestRoute

A page fetched from a web server via GET.

class bacommon.docui.routes.docuitest.WebTestPost

Bases: TestRoute

A page fetched from a web server via POST.

class bacommon.docui.routes.docuitest.WideFit(over: bool = False, wide_over: bool = False, layout: WindowLayout = WindowLayout.WIDE)

Bases: TestRoute

A row exactly as big as wide pages get (browse at each layout).

It should fill the page’s height and width with no scrolling, at every ui-scale; with over / wide_over set it’s a hair taller / wider, which should scroll (at small ui-scale, only on the smallest screens: windows there fill the screen, so the page sizes are minimums). layout says which wide layout it’s being shown in (browse at that one): wide and wider pages are the same height everywhere, wide-tall ones depend on the ui-scale and wide-taller ones on the screen too; wider’s width follows the screen, so there’s no width to overflow there.

layout: WindowLayout = 'w'

over: bool = False

wide_over: bool = False

class bacommon.docui.routes.docuitest.WidgetTestState(plain: bool = False, live: bool = False, checked_disabled: bool = True, unchecked_disabled: bool = False, presses: int = 0, text_short: str = '', text_medium: str = 'Some text', text_long: str = '', text_live: str = '', text_disabled: str = 'Not editable', flavor: Flavor = Flavor.VANILLA, flavor_live: Flavor = Flavor.VANILLA, size: Size = Size.M, size_long: Size = Size.M, topping: Flavor | None = None, difficulty: str = 'normal', region: str | None = None, flavor_disabled: Flavor = Flavor.CHOCOLATE, topping_disabled: Flavor | None = None, difficulty_disabled: str = 'hard', region_disabled: str | None = 'eu', volume: float = 0.5, volume_disabled: float = 0.3, series_length: float = 7.0, series_length_disabled: float = 5.0, tint: tuple[float, float, float] = (0.5, 0.25, 1.0), tint_disabled: tuple[float, float, float] = (1.0, 0.6, 0.1), spacing_top_demo: bool = False, spacing_bottom_demo: bool = False, bands_demo: bool = False)

Bases: DocUIState

State for the widgets test page.

bands_demo: bool = False

checked_disabled: bool = True

Disabled checkboxes (selectable; not toggleable), one checked and one not.

difficulty: str = 'normal'

Choices over an arbitrary string set (the page defines the options, not an enum); plain and optional.

difficulty_disabled: str = 'hard'

flavor: Flavor = 'v'

Choices, plain and live.

flavor_disabled: Flavor = 'c'

Disabled choice rows (selectable; menus won’t open), one of each form: enum, optional enum, str, optional str.

flavor_live: Flavor = 'v'

live: bool = False

A checkbox that re-requests the page when changed.

plain: bool = False

A checkbox with no on-change action.

presses: int = 0

Nothing shows or edits this directly; it simply rides along (and gets bumped by a button).

region: str | None = None

region_disabled: str | None = 'eu'

series_length: float = 7.0

A number-row value shaped like a series length – 1-21 by 2.

series_length_disabled: float = 5.0

A disabled number row (selectable; not adjustable).

size: Size = 'm'

Short choice labels (a compact button) and an absurdly long one.

size_long: Size = 'm'

spacing_bottom_demo: bool = False

spacing_top_demo: bool = False

Checkboxes on rows demonstrating control-row spacing and header / footer bands (they drive nothing).

text_disabled: str = 'Not editable'

A disabled text input (selectable; not editable).

text_live: str = ''

A text input that re-requests the page when an edit is committed.

text_long: str = ''

text_medium: str = 'Some text'

text_short: str = ''

Text inputs with labels of assorted lengths.

tint: tuple[float, float, float] = (0.5, 0.25, 1.0)

An rgb color, edited via the color-picker popup.

tint_disabled: tuple[float, float, float] = (1.0, 0.6, 0.1)

A disabled color row (selectable; picker won’t open).

topping: Flavor | None = None

An optional choice – a ‘nothing’ option ahead of the flavors.

topping_disabled: Flavor | None = None

unchecked_disabled: bool = False

volume: float = 0.5

A slider value shaped like the sound-settings ones – 0-1 by 0.05.

volume_disabled: float = 0.3

A disabled slider (selectable; not adjustable).

class bacommon.docui.routes.docuitest.Widgets(debug: bool = False)

Bases: TestRoute

Control rows and page state.

debug: bool = False

class bacommon.docui.routes.docuitest.WindowLayouts(debug: bool = False, layout: WindowLayout | None = None, viewer_side: ViewerSide | None = None)

Bases: TestRoute

Assorted rows for judging window layouts (browse to it at each).

Control rows, titles and button rows at every alignment, and long rows, which in a narrow column scroll within it.

debug: bool = False

layout: WindowLayout | None = None

The layout we’re being browsed to at, for the page to name (the browse sets the actual layout; this is just for show).

viewer_side: ViewerSide | None = None

Which side the page’s viewer pane sits on at viewer layouts, or None for a page with no viewer (its rows then span the window). Ignored at other layouts.