Types used internally in magicgui.


An callback that can be used as a valid argument for widget choices. It takes a categorical widget and returns a ChoicesIterable.

alias of Callable[[CategoricalWidget], Union[Iterable[Tuple[str, Any]], Iterable[Any]]]

class magicgui.types.ChoicesDict[source]

Bases: TypedDict

Dict Type for setting choices in a categorical widget.

choices: Union[Iterable[Tuple[str, Any]], Iterable[Any]]
key: Callable[[Any], str]

An iterable that can be used as a valid argument for widget choices

alias of Union[Iterable[Tuple[str, Any]], Iterable[Any]]


The set of all valid types for widget choices.

alias of Union[enum.EnumMeta, Iterable[Tuple[str, Any]], Iterable[Any], Callable[[CategoricalWidget], Union[Iterable[Tuple[str, Any]], Iterable[Any]]], ChoicesDict]

class magicgui.types.FileDialogMode(value)[source]

Bases: enum.Enum

FileDialog mode options.

  • EXISTING_FILE - returns one existing file.

  • EXISTING_FILES - return one or more existing files.

  • OPTIONAL_FILE - return one file name that does not have to exist.

  • EXISTING_DIRECTORY - returns one existing directory.


A valid file path type

alias of Union[pathlib.Path, str, bytes]


A callback that may be registered for a given return annotation. When called, it will be provided an instance of a FunctionGui, the result of the function that was called, and the return annotation itself.

alias of Callable[[FunctionGui, Any, Type], None]


A function that takes a (value, annotation) argument and returns an optional WidgetTuple

alias of Callable[[Any, Optional[Type]], Optional[Tuple[Union[str, Type[Widget], Type[WidgetProtocol]], WidgetOptions]]]


A Widget class or a WidgetProtocol

alias of Union[Type[Widget], Type[WidgetProtocol]]

class magicgui.types.WidgetOptions[source]

Bases: TypedDict

Recognized options when instantiating a Widget.


this should be improved to be widget-type specific.

allow_multiple: bool
bind: Any
choices: ChoicesType
enabled: bool
gui_only: bool
layout: str
max: float
min: float
mode: str | FileDialogMode
nullable: bool
orientation: str
step: float
text: str
tooltip: str
visible: bool
widget_type: WidgetRef

A generic reference to a WidgetClass as a string, or the class itself.

alias of Union[str, Type[Widget], Type[WidgetProtocol]]


A WidgetClass (or a string representation of one) and a dict of appropriate WidgetOptions.

alias of Tuple[Union[str, Type[Widget], Type[WidgetProtocol]], WidgetOptions]