types

App-model types.

Action

Bases: CommandRule, Generic[P, R]

An Action is a callable object with menu placement, keybindings, and metadata.

This is the "complete" representation of a command. Including a pointer to the actual callable object, as well as any additional menu and keybinding rules. Most commands and menu items will be represented by Actions, and registered using register_action.

CommandRule

Bases: _BaseModel

Data representing a command and its presentation.

Presentation of contributed commands depends on the containing menu. The Command Palette, for instance, prefixes commands with their category, allowing for easy grouping. However, the Command Palette doesn't show icons nor disabled commands. Menus, on the other hand, shows disabled items as grayed out, but don't show the category label.

Icon

Bases: _BaseModel

Icons used to represent commands, or submenus.

May provide both a light and dark variant. If only one is provided, it is used in all theme types.

KeyBinding

KeyBinding(*, parts: list[SimpleKeyBinding])

KeyBinding. May be a multi-part "Chord" (e.g. 'Ctrl+K Ctrl+C').

This is the primary representation of a fully resolved keybinding. For consistency in the downstream API, it should be preferred to SimpleKeyBinding, even when there is only a single part in the keybinding (i.e. when it is not a chord.)

Chords (two separate keypress actions) are expressed as a string by separating the two keypress codes with a space. For example, 'Ctrl+K Ctrl+C'.

Parameters:

Name	Type	Description	Default
parts	List[SimpleKeyBinding]	The parts of the keybinding. There must be at least one part.	required

Source code in src/app_model/types/_keys/_keybindings.py

def __init__(self, *, parts: list[SimpleKeyBinding]) -> None:
    self.parts = parts

part0 property

part0: SimpleKeyBinding

Return the first part of this keybinding.

All keybindings have at least one part.

from_int classmethod

from_int(key_int: int, os: OperatingSystem | None = None) -> KeyBinding

Create a KeyBinding from an integer.

Source code in src/app_model/types/_keys/_keybindings.py

@classmethod
def from_int(cls, key_int: int, os: OperatingSystem | None = None) -> "KeyBinding":
    """Create a KeyBinding from an integer."""
    # a multi keybinding is represented as an integer
    # with the first_part in the lowest 16 bits,
    # the second_part in the next 16 bits, etc.
    first_part = key_int & 0x0000FFFF
    chord_part = (key_int & 0xFFFF0000) >> 16
    if chord_part != 0:
        return cls(
            parts=[
                SimpleKeyBinding.from_int(first_part, os),
                SimpleKeyBinding.from_int(chord_part, os),
            ]
        )
    return cls(parts=[SimpleKeyBinding.from_int(first_part, os)])

from_str classmethod

from_str(key_str: str) -> KeyBinding

Parse a string into a SimpleKeyBinding.

Source code in src/app_model/types/_keys/_keybindings.py

@classmethod
def from_str(cls, key_str: str) -> "KeyBinding":
    """Parse a string into a SimpleKeyBinding."""
    parts = [SimpleKeyBinding.from_str(part) for part in key_str.split()]
    return cls(parts=parts)

to_int

to_int(os: OperatingSystem | None = None) -> int

Convert this KeyBinding to an integer representation.

Source code in src/app_model/types/_keys/_keybindings.py

def to_int(self, os: OperatingSystem | None = None) -> int:
    """Convert this KeyBinding to an integer representation."""
    if len(self.parts) > 2:  # pragma: no cover
        raise NotImplementedError(
            "Cannot represent chords with more than 2 parts as int"
        )
    os = OperatingSystem.current() if os is None else os
    parts = [part.to_int(os) for part in self.parts]
    if len(parts) == 2:
        return KeyChord(*parts)
    return parts[0]

to_text

to_text(os: OperatingSystem | None = None, use_symbols: bool = False, joinchar: str = '+') -> str

Get a text representation of this KeyBinding.

Optionally, the string representation can be constructed with symbols like ↵ for Enter or OS specific ones like ⌘ for Meta on MacOS. If no symbols should be used, the string representation will use the OS specific names for the keys like Cmd for Meta or Option for Ctrl on MacOS.

Also, a join character can be defined. By default + is used.

Source code in src/app_model/types/_keys/_keybindings.py

def to_text(
    self,
    os: OperatingSystem | None = None,
    use_symbols: bool = False,
    joinchar: str = "+",
) -> str:
    """Get a text representation of this KeyBinding.

    Optionally, the string representation can be constructed with symbols
    like ↵ for Enter or OS specific ones like ⌘ for Meta on MacOS. If no symbols
    should be used, the string representation will use the OS specific names
    for the keys like `Cmd` for Meta or `Option` for Ctrl on MacOS.

    Also, a join character can be defined. By default `+` is used.
    """
    return " ".join(
        part.to_text(os=os, use_symbols=use_symbols, joinchar=joinchar)
        for part in self.parts
    )

validate classmethod

validate(v: Any) -> KeyBinding

Validate a SimpleKeyBinding.

Source code in src/app_model/types/_keys/_keybindings.py

@classmethod
def validate(cls, v: Any) -> "KeyBinding":
    """Validate a SimpleKeyBinding."""
    if isinstance(v, KeyBinding):
        return v
    if isinstance(v, SimpleKeyBinding):
        return cls(parts=[v])
    if isinstance(v, int):
        return cls.from_int(v)
    if isinstance(v, str):
        return cls.from_str(v)
    raise TypeError("invalid keybinding")  # pragma: no cover

KeyBindingRule

Bases: _BaseModel

Data representing a keybinding and when it should be active.

This model lacks a corresponding command. That gets linked up elsewhere, such as below in Action.

Values can be expressed as either a string (e.g. "Ctrl+O") or an integer, using combinations of KeyMod and KeyCode, (e.g. KeyMod.CtrlCmd | KeyCode.KeyO).

KeyBindingSource

Bases: IntEnum

Keybinding source enum.

KeyChord

KeyChord(first_part: int, second_part: int)

Bases: int

KeyChord is an integer combination of two key combos.

It could be two KeyCombo KeyCode, or int.

Parameters:

Name	Type	Description	Default
first_part	KeyCombo | int	The first part of the chord.	required
second_part	KeyCombo | int	The second part of the chord.	required

Source code in src/app_model/types/_keys/_key_codes.py

def __init__(self, first_part: int, second_part: int):
    self._first_part = first_part
    self._second_part = second_part

KeyCode

Bases: IntEnum

Virtual Key Codes, the integer value does not hold any inherent meaning.

This is the primary internal representation of a key.

from_event_code classmethod

from_event_code(event_code: int) -> KeyCode

Return the KeyCode associated with the given event code.

Returns KeyCode.UNKNOWN if no KeyCode is associated with the event code.

Source code in src/app_model/types/_keys/_key_codes.py

@classmethod
def from_event_code(cls, event_code: int) -> 'KeyCode':
    """Return the `KeyCode` associated with the given event code.

    Returns `KeyCode.UNKNOWN` if no `KeyCode` is associated with the event code.
    """
    return _EVENTCODE_TO_KEYCODE.get(event_code, KeyCode.UNKNOWN)

from_string classmethod

from_string(string: str) -> KeyCode

Return the KeyCode associated with the given string.

Returns KeyCode.UNKNOWN if no KeyCode is associated with the string.

Source code in src/app_model/types/_keys/_key_codes.py

@classmethod
def from_string(cls, string: str) -> 'KeyCode':
    """Return the `KeyCode` associated with the given string.

    Returns `KeyCode.UNKNOWN` if no `KeyCode` is associated with the string.
    """
    return keycode_from_string(string)

os_name

os_name(os: Optional[OperatingSystem] = None) -> str

Get a string representation of this KeyCode using the OS specific naming for the key.

This differs from __str__ since with it a normalized representation (constant to all OSes) is given. Sometimes these representations coincide but not always! Some examples: * KeyCode.Enter is represented by Enter (__str__ represents it as Enter) * KeyCode.Meta is represented by Win on Windows, Super on Linux and Cmd on MacOS (__str__ represents it as Meta)

If no OS is given, the current detected one is used.

Source code in src/app_model/types/_keys/_key_codes.py

def os_name(self, os: Optional[OperatingSystem] = None) -> str:
    """Get a string representation of this `KeyCode` using the OS specific naming for the key.

    This differs from `__str__` since with it a normalized representation (constant to all OSes) is given.
    Sometimes these representations coincide but not always! Some examples:
        * `KeyCode.Enter` is represented by `Enter` (`__str__` represents it as `Enter`)
        * `KeyCode.Meta` is represented by `Win` on Windows, `Super` on Linux and `Cmd` on MacOS
        (`__str__` represents it as `Meta`)

    If no OS is given, the current detected one is used.
    """
    os = OperatingSystem.current() if os is None else os
    return keycode_to_os_name(self, os)

os_symbol

os_symbol(os: Optional[OperatingSystem] = None) -> str

Get a string representation of this KeyCode using a symbol/OS specific symbol.

Some examples: * KeyCode.Enter is represented by ↵ * KeyCode.Meta is represented by ⊞ on Windows, Super on Linux and ⌘ on MacOS

If no OS is given, the current detected one is used.

Source code in src/app_model/types/_keys/_key_codes.py

def os_symbol(self, os: Optional[OperatingSystem] = None) -> str:
    """Get a string representation of this `KeyCode` using a symbol/OS specific symbol.

    Some examples:
        * `KeyCode.Enter` is represented by `↵`
        * `KeyCode.Meta` is represented by `⊞` on Windows, `Super` on Linux and `⌘` on MacOS

    If no OS is given, the current detected one is used.
    """
    os = OperatingSystem.current() if os is None else os
    return keycode_to_os_symbol(self, os)

KeyCombo

KeyCombo(modifiers: KeyMod, key: KeyCode = KeyCode.UNKNOWN)

Bases: int

KeyCombo is an integer combination of one or more.

KeyMod and KeyCode.

Source code in src/app_model/types/_keys/_key_codes.py

def __init__(self, modifiers: KeyMod, key: KeyCode = KeyCode.UNKNOWN):
    self._modifiers = modifiers
    self._key = key

KeyMod

Bases: IntFlag

A Flag indicating keyboard modifiers.

MenuItem

Bases: MenuItemBase

Combination of a Command and conditions for menu presentation.

This object is mostly constructed by register_action right before menu item registration.

MenuItemBase

Bases: _BaseModel

Data representing where and when a menu item should be shown.

MenuRule

Bases: MenuItemBase

A MenuRule defines a menu location and conditions for presentation.

It does not define an actual command. That is done in either MenuItem or Action.

OperatingSystem

Bases: Enum

Operating system enum.

is_linux property

is_linux: bool

Returns True if the current operating system is Linux.

is_mac property

is_mac: bool

Returns True if the current operating system is MacOS.

is_windows property

is_windows: bool

Returns True if the current operating system is Windows.

current staticmethod

current() -> OperatingSystem

Return the current operating system as enum.

Source code in src/app_model/types/_constants.py

@staticmethod
def current() -> "OperatingSystem":
    """Return the current operating system as enum."""
    return _CURRENT

ScanCode

Bases: IntEnum

Scan codes for the keyboard.

https://en.wikipedia.org/wiki/Scancode

These are the scan codes required to conform to the W3C specification for KeyboardEvent.code

A scan code is a hardware-specific code that is generated by the keyboard when a key is pressed or released. It represents the physical location of a key on the keyboard and is unique to each key. A key code, on the other hand, is a higher-level representation of a keypress or key release event. They are associated with characters, functions, or actions rather than hardware locations. As an example, the left and right control keys have the same key code (KeyCode.Ctrl) but different scan codes (LeftControl and RightControl).

https://w3c.github.io/uievents-code/

commented out lines represent keys that are optional and may be used by implementations to support special keyboards (such as multimedia or legacy keyboards).

from_string classmethod

from_string(string: str) -> ScanCode

Return the KeyCode associated with the given string.

Returns ScanCode.UNIDENTIFIED if no match is found.

Source code in src/app_model/types/_keys/_key_codes.py

@classmethod
def from_string(cls, string: str) -> 'ScanCode':
    """Return the KeyCode associated with the given string.

    Returns ScanCode.UNIDENTIFIED if no match is found.
    """
    return scancode_from_string(string)

SimpleKeyBinding

Bases: BaseModel

Represent a simple combination modifier(s) and a key, e.g. Ctrl+A.

from_int classmethod

from_int(key_int: int, os: OperatingSystem | None = None) -> SimpleKeyBinding

Create a SimpleKeyBinding from an integer.

Source code in src/app_model/types/_keys/_keybindings.py

@classmethod
def from_int(
    cls, key_int: int, os: OperatingSystem | None = None
) -> "SimpleKeyBinding":
    """Create a SimpleKeyBinding from an integer."""
    ctrl_cmd = bool(key_int & KeyMod.CtrlCmd)
    win_ctrl = bool(key_int & KeyMod.WinCtrl)
    shift = bool(key_int & KeyMod.Shift)
    alt = bool(key_int & KeyMod.Alt)

    os = OperatingSystem.current() if os is None else os
    ctrl = win_ctrl if os.is_mac else ctrl_cmd
    meta = ctrl_cmd if os.is_mac else win_ctrl
    key = key_int & 0x000000FF  # keycode mask

    return cls(ctrl=ctrl, shift=shift, alt=alt, meta=meta, key=key)

from_str classmethod

from_str(key_str: str) -> SimpleKeyBinding

Parse a string into a SimpleKeyBinding.

Source code in src/app_model/types/_keys/_keybindings.py

@classmethod
def from_str(cls, key_str: str) -> "SimpleKeyBinding":
    """Parse a string into a SimpleKeyBinding."""
    mods, remainder = _parse_modifiers(key_str.strip())
    key = KeyCode.from_string(remainder)
    return cls(**mods, key=key)

is_modifier_key

is_modifier_key() -> bool

Return true if this is a modifier key.

Source code in src/app_model/types/_keys/_keybindings.py

def is_modifier_key(self) -> bool:
    """Return true if this is a modifier key."""
    return self.key in (
        KeyCode.Alt,
        KeyCode.Shift,
        KeyCode.Ctrl,
        KeyCode.Meta,
        KeyCode.UNKNOWN,
    )

to_int

to_int(os: OperatingSystem | None = None) -> int

Convert this SimpleKeyBinding to an integer representation.

Source code in src/app_model/types/_keys/_keybindings.py

def to_int(self, os: OperatingSystem | None = None) -> int:
    """Convert this SimpleKeyBinding to an integer representation."""
    os = OperatingSystem.current() if os is None else os
    mods: KeyMod = KeyMod.NONE
    if self.ctrl:
        mods |= KeyMod.WinCtrl if os.is_mac else KeyMod.CtrlCmd
    if self.shift:
        mods |= KeyMod.Shift
    if self.alt:
        mods |= KeyMod.Alt
    if self.meta:
        mods |= KeyMod.CtrlCmd if os.is_mac else KeyMod.WinCtrl
    return mods | (self.key or 0)

to_text

to_text(os: OperatingSystem | None = None, use_symbols: bool = False, joinchar: str = '+') -> str

Get a user-facing string representation of this SimpleKeyBinding.

Optionally, the string representation can be constructed with symbols like ↵ for Enter or OS specific ones like ⌘ for Meta on MacOS. If no symbols should be used, the string representation will use the OS specific names for the keys like Cmd for Meta or Option for Ctrl on MacOS.

Also, a join character can be defined. By default + is used.

Source code in src/app_model/types/_keys/_keybindings.py

def to_text(
    self,
    os: OperatingSystem | None = None,
    use_symbols: bool = False,
    joinchar: str = "+",
) -> str:
    """Get a user-facing string representation of this SimpleKeyBinding.

    Optionally, the string representation can be constructed with symbols
    like ↵ for Enter or OS specific ones like ⌘ for Meta on MacOS. If no symbols
    should be used, the string representation will use the OS specific names
    for the keys like `Cmd` for Meta or `Option` for Ctrl on MacOS.

    Also, a join character can be defined. By default `+` is used.
    """
    os = OperatingSystem.current() if os is None else os
    keybinding_elements = [*self._mods2keycodes()]
    if self.key:
        keybinding_elements.append(self.key)

    return joinchar.join(
        kbe.os_symbol(os=os) if use_symbols else kbe.os_name(os=os)
        for kbe in keybinding_elements
    )

StandardKeyBinding

Bases: Enum

to_keybinding_rule

to_keybinding_rule() -> KeyBindingRule

Return KeyBindingRule for this StandardKeyBinding.

Source code in src/app_model/types/_keys/_standard_bindings.py

def to_keybinding_rule(self) -> "KeyBindingRule":
    """Return KeyBindingRule for this StandardKeyBinding."""
    from .._keybinding_rule import KeyBindingRule

    return KeyBindingRule(**_STANDARD_KEY_MAP[self])

SubmenuItem

Bases: MenuItemBase

Point to another Menu that will be displayed as a submenu.

ToggleRule

Bases: _BaseModel

More detailed description of a toggle rule.