Skip to content

API Reference

Runtime action definition.

Parameters:

Name Type Description Default
id str

Action identifier.

Identifier must abide by these rules:

  • Must be unique in its Model
  • The first and last characters must be ascii lowercase [a-z]
  • Other characters must be ascii lowercase or dash [a-z-]
 required
cb Callable[[], Any]

Callback to execute when action is requested.

 <function passthrough at 0x7f6249606e50>
enabled bool

Whether the action is enabled.

 True
visible bool

Whether the action is visible in the menu.

 True
menu tuple[str, ...]

Menu labels hierarchy.

The root menu is represented by an empty tuple ().

 ()
label str | None

Display name.

 None
group str | None

A group under menu.

Items under the same menu can be grouped together. Groups are represented by separators.

 None
icon Traversable | None

Path to an icon.

Icons are displayed alongside the label, if supported by the menu builder.

 None
desc str | None

Short description.

Displayed as a menu tooltip.

 None 
deserialize(config: dict[str, Any]) -> Self

Deserialize config into a new instance.

Action wrapper, returned by Model.iter.

Parameters:

Name Type Description Default
inner ForwardRef
None 
menu: tuple[str, ...]

path: tuple[str, ...]

Group wrapper, returned by Model.iter.

Parameters:

Name Type Description Default
inner ForwardRef
None
menu ForwardRef
None 
path: tuple[str, ...]

Menu wrapper, returned by Model.iter.

Parameters:

Name Type Description Default
inner ForwardRef
None 
menu: tuple[str, ...]

path: tuple[str, ...]

Menu node definition.

Parameters:

Name Type Description Default
label str

Display name.

 required
menu tuple[str, ...]

Menu labels hierarchy.

The root menu is represented by an empty tuple ().

 ()
group str | None

A group under menu.

Items under the same menu can be grouped together. Groups are represented by menu separators.

 None
icon Traversable | None

Path to an icon.

Icons are displayed alongside the label, if supported by the menu builder.

 None
desc str | None

Short description.

Displayed as a menu tooltip.

 None 
deserialize(config: dict[str, Any]) -> Self

Deserialize config into a new instance.

is_configured() -> bool

Whether this menu has any configuration beside menu and label.

Model()

The main Action and Menu storage abstraction.

add_action(action: Action) -> None

Add action to model.

add_menu(menu: Menu) -> None

Add menu to model.

get_action(id: str) -> Action

Return Action with given id in model.

Raises:

Type Description
KeyError

id not found.

 
iter(
    menu: tuple[str, ...] = (),
    *,
    sort_key: MenuSortKey | None = None,
    recursive: bool = False
) -> Iterator[ItemGroup | ItemMenu | ItemAction]

Iter menu items.

Parameters:

Name Type Description Default
menu tuple[str, ...]

The start menu. An empty tuple () (the default), starts at the top.

 ()
sort_key MenuSortKey | None

Customize the sort order of menu items.

 None
recursive bool

Iter sub-menus in depth-first search.

 False 
deserialize(
    config: dict[str, Any],
    model: Model,
    root_keys: tuple[str, ...] | None = None,
) -> None

Deserialize config and add its content to the model.

Parameters:

Name Type Description Default
config dict[str, Any]

A dict containing a configuration of menus and actions.

 required
model Model

Target model.

 required
root_keys tuple[str, ...] | None

The sequence of keys that lead to the root configuration structure. For example, a [tool.myapp.mymenu] table (("tool", "myapp", "mymenu")) in pyproject.toml.

 None 
load(
    fp: SupportsRead[bytes],
    model: Model,
    root_keys: tuple[str, ...] | None = None,
) -> None

Load fp and deserialize its content to model.

Parameters:

Name Type Description Default
fp SupportsRead[bytes]

a .read()-supporting file-like object containing a TOML document.

 required
model Model

Target model.

 required
root_keys tuple[str, ...] | None

The sequence of keys that lead to the root configuration structure. For example, a [tool.myapp.mymenu] table (("tool", "myapp", "mymenu")) in pyproject.toml.

 None 
loads(s: str, model: Model, root_keys: tuple[str, ...] | None = None) -> None

Load s and deserialize its content to model.

Parameters:

Name Type Description Default
s str

a str containing a TOML document.

 required
model Model

Target model.

 required
root_keys tuple[str, ...] | None

The sequence of keys that lead to the root configuration structure. For example, a [tool.myapp.mymenu] table (("tool", "myapp", "mymenu")) in pyproject.toml.

 None

TextMenuBuilder render options.

ASCII = _Render(
    child="|-- ",
    last_child="`-- ",
    menu="|   ",
    empty="    ",
    group_suffix=" ---",
)

UTF8 = _Render(
    child="├── ",
    last_child="└── ",
    menu="│   ",
    empty="    ",
    group_suffix=" ───",
)

TextMenuBuilder(
    model: Model,
    *,
    root_menu: str | None = None,
    sort_key: MenuSortKey | None = None,
    render: Render = ASCII
)

Text menu builder.

build() -> str

Build menu.

QMenuBuilder(
    model: Model, *, root_menu: QMenu | str, sort_key: MenuSortKey | None = None
)

Qt Menu Builder.

build() -> QMenu

Build menu.