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) → 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.

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.

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 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.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.

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.ProfileDelete(profile_name: str)

Bases: StoreRoute

(Inventory) delete a stored profile.

profile_name: str

class bacommon.docui.routes.classicstore.ProfileDraft(color: tuple[float, float, float], highlight: tuple[float, float, float], name: str = '', character: 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 or character means the same for that field.

character: str = ''

color: tuple[float, float, float]

highlight: tuple[float, float, float]

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.

profile_name: str | None = None

Stored profile being edited, or None when creating one.

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.

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.BoundsTests

Bases: TestRoute

Button-style bounds tests.

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.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.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.

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.

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

Bases: TestRoute

Text-with-images tests.

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.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)

Bases: TestRoute

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

It should fill the page’s height (wide and wider) and width (wide) with no scrolling, at every ui-scale; with over / wide_over set it’s a hair taller / wider, which should scroll.

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)

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