magicgui.type_map

Widget	Description
get_widget_class	Return a Widget subclass for the value/annotation.
register_type	Register a widget_type to be used for all parameters with type type_.
type_registered	Context manager that temporarily registers a widget type for a given type_.
type2callback	Return any callbacks that have been registered for type_.
TypeMap	Storage for mapping from types to widgets and callbacks.

magicgui.type_map.get_widget_class = _GLOBAL_TYPE_MAP.get_widget_class module-attribute

magicgui.type_map.register_type = _GLOBAL_TYPE_MAP.register_type module-attribute

magicgui.type_map.type_registered = _GLOBAL_TYPE_MAP.type_registered module-attribute

magicgui.type_map.type2callback = _GLOBAL_TYPE_MAP.type2callback module-attribute

magicgui.type_map.TypeMap

Storage for mapping from types to widgets and callbacks.

copy()

Return a copy of the type map.

create_widget(value=Undefined, annotation=None, name='', param_kind='POSITIONAL_OR_KEYWORD', label=None, gui_only=False, app=None, widget_type=None, options=None, is_result=False, raise_on_unknown=True)

Create and return appropriate widget subclass.

This factory function can be used to create a widget appropriate for the provided value and/or annotation provided. See Type Mapping Docs for details on how the widget type is determined from type annotations.

Parameters:

• value (Any, default: Undefined ) –

  The starting value for the widget, by default None

• annotation (Any, default: None ) –

  The type annotation for the parameter represented by the widget, by default None.

• name (str, default: '' ) –

  The name of the parameter represented by this widget. by default ""

• param_kind (str, default: 'POSITIONAL_OR_KEYWORD' ) –

  The :attr:inspect.Parameter.kind represented by this widget. Used in building signatures from multiple widgets, by default "POSITIONAL_OR_KEYWORD"

• label (str, default: None ) –

  A string to use for an associated Label widget (if this widget is being shown in a Container widget, and labels are on). By default, name will be used. Note: name refers the name of the parameter, as might be used in a signature, whereas label is just the label for that widget in the GUI.

• gui_only (bool, default: False ) –

  Whether the widget should be considered "only for the gui", or if it should be included in any widget container signatures, by default False

• app (str, default: None ) –

  The backend to use, by default None

• widget_type (str or Type[WidgetProtocol] or None, default: None ) –

  A class implementing a widget protocol or a string with the name of a magicgui widget type (e.g. "Label", "PushButton", etc...). If provided, this widget type will be used instead of the type autodetermined from value and/or annotation above.

• options (dict, default: None ) –

  Dict of options to pass to the Widget constructor, by default dict()

• is_result (boolean, default: False ) –

  Whether the widget belongs to an input or an output. By default, an input is assumed.

• raise_on_unknown (bool, default: True ) –

  Raise exception if no widget is found for the given type, by default True

Returns:

• Widget –

  An instantiated widget subclass

Raises:

• TypeError –

  If the provided or autodetected widget_type does not implement any known widget protocols

Examples:

from magicgui.widgets import create_widget

# create a widget from a string value
wdg = create_widget(value="hello world")
assert wdg.value == "hello world"

# create a widget from a string annotation
wdg = create_widget(annotation=str)
assert wdg.value == ""

get_widget_class(value=Undefined, annotation=Undefined, options=None, is_result=False, raise_on_unknown=True)

Return a Widget subclass for the value/annotation.

Parameters:

• value (Any, default: Undefined ) –

  A python value. Will be used to determine the widget type if an annotation is not explicitly provided by default None

• annotation (Optional[Type], default: Undefined ) –

  A type annotation, by default None

• options (dict, default: None ) –

  Options to pass when constructing the widget, by default {}

• is_result (bool, default: False ) –

  Identifies whether the returned widget should be tailored to an input or to an output.

• raise_on_unknown (bool, default: True ) –

  Raise exception if no widget is found for the given type, by default True

Returns:

• Tuple[WidgetClass, dict] –

  The WidgetClass, and dict that can be used for params. dict may be different than the options passed in.

global_instance() staticmethod

Get the global type map.

magic_factory(function=None, *, layout='vertical', scrollable=False, labels=True, tooltips=True, call_button=None, auto_call=False, result_widget=False, main_window=False, app=None, persist=False, widget_init=None, raise_on_unknown=False, **param_options)

Return a MagicFactory for function.

magic_factory is nearly identical to the magicgui decorator with the following differences:

1. Whereas magicgui returns a FunctionGui instance, magic_factory returns a callable that returns a FunctionGui instance. (Technically, it returns an instance of MagicFactory which you behaves exactly like a functools.partial for a FunctionGui instance.)
2. magic_factory adds a widget_init method: a callable that will be called immediately after the FunctionGui instance is created. This can be used to add additional widgets to the layout, or to connect signals to the widgets.

Important

Whereas decorating a function with magicgui will immediately create a widget instance, magic_factory will not create a widget instance until the decorated object is called. This is often what you want in a library, whereas magicgui is useful for rapid, interactive development.

Parameters:

• function (Callable, default: None ) –

  The function to decorate. Optional to allow bare decorator with optional arguments. by default None

• layout (str, default: 'vertical' ) –

  The type of layout to use. Must be horizontal or vertical by default "vertical".

• scrollable (bool, default: False ) –

  Whether to enable scroll bars or not. If enabled, scroll bars will only appear along the layout direction, not in both directions.

• labels (bool, default: True ) –

  Whether labels are shown in the widget. by default True

• tooltips (bool, default: True ) –

  Whether tooltips are shown when hovering over widgets. by default True

• call_button (bool or str, default: None ) –

  If True, create an additional button that calls the original function when clicked. If a str, set the button text. If None (the default), it defaults to True when auto_call is False, and False otherwise.

• auto_call (bool, default: False ) –

  If True, changing any parameter in either the GUI or the widget attributes will call the original function with the current settings. by default False

• result_widget (bool, default: False ) –

  Whether to display a LineEdit widget the output of the function when called, by default False

• main_window (bool, default: False ) –

  Whether this widget should be treated as the main app window, with menu bar, by default False.

• app (Application or str, default: None ) –

  A backend to use, by default None (use the default backend.)

• persist (bool, default: False ) –

  If True, when parameter values change in the widget, they will be stored to disk and restored when the widget is loaded again with persist = True. Call magicgui._util.user_cache_dir() to get the default cache location. By default False.

• widget_init (callable, default: None ) –

  A function that will be called with the newly created widget instance as its only argument. This can be used to customize the widget after it is created. by default None.

• raise_on_unknown (bool, default: False ) –

  If True, raise an error if magicgui cannot determine widget for function argument or return type. If False, ignore unknown types. By default False.

• param_options (dict of dict, default: {} ) –

  Any additional keyword arguments will be used as parameter-specific widget options. Keywords must match the name of one of the arguments in the function signature, and the value must be a dict of keyword arguments to pass to the widget constructor.

Returns:

• result ( MagicFactory or Callable[[F], MagicFactory] ) –

  If function is not None (such as when this is used as a bare decorator), returns a MagicFactory instance. If function is None such as when arguments are provided like magic_factory(auto_call=True), then returns a function that can be used as a decorator.

Examples:

>>> @magic_factory
... def my_function(a: int = 1, b: str = "hello"):
...     pass
>>> my_widget = my_function()
>>> my_widget.show()
>>> my_widget.a.value == 1  # True
>>> my_widget.b.value = "world"

magicgui(function=None, *, layout='vertical', scrollable=False, labels=True, tooltips=True, call_button=None, auto_call=False, result_widget=False, main_window=False, app=None, persist=False, raise_on_unknown=False, **param_options)

Return a FunctionGui for function.

Parameters:

• function (Callable, default: None ) –

  The function to decorate. Optional to allow bare decorator with optional arguments. by default None

• layout (str, default: 'vertical' ) –

  The type of layout to use. Must be horizontal or vertical by default "vertical".

• scrollable (bool, default: False ) –

  Whether to enable scroll bars or not. If enabled, scroll bars will only appear along the layout direction, not in both directions.

• labels (bool, default: True ) –

  Whether labels are shown in the widget. by default True

• tooltips (bool, default: True ) –

  Whether tooltips are shown when hovering over widgets. by default True

• call_button (bool or str, default: None ) –

  If True, create an additional button that calls the original function when clicked. If a str, set the button text. If None (the default), it defaults to True when auto_call is False, and False otherwise.

• auto_call (bool, default: False ) –

  If True, changing any parameter in either the GUI or the widget attributes will call the original function with the current settings. by default False

• result_widget (bool, default: False ) –

  Whether to display a LineEdit widget the output of the function when called, by default False

• main_window (bool, default: False ) –

  Whether this widget should be treated as the main app window, with menu bar, by default False.

• app (Application or str, default: None ) –

  A backend to use, by default None (use the default backend.)

• persist (bool, default: False ) –

  If True, when parameter values change in the widget, they will be stored to disk and restored when the widget is loaded again with persist = True. Call magicgui._util.user_cache_dir() to get the default cache location. By default False.

• raise_on_unknown (bool, default: False ) –

  If True, raise an error if magicgui cannot determine widget for function argument or return type. If False, ignore unknown types. By default False.

• param_options (dict[str, dict], default: {} ) –

  Any additional keyword arguments will be used as parameter-specific options. Keywords must match the name of one of the arguments in the function signature, and the value must be a dict of keyword arguments to pass to the widget constructor.

Returns:

• result ( FunctionGui or Callable[[F], FunctionGui] ) –

  If function is not None (such as when this is used as a bare decorator), returns a FunctionGui instance, which is a list-like container of autogenerated widgets corresponding to each parameter in the function. If function is None such as when arguments are provided like magicgui(auto_call=True), then returns a function that can be used as a decorator.

Examples:

>>> @magicgui
... def my_function(a: int = 1, b: str = "hello"):
...     pass
>>> my_function.show()
>>> my_function.a.value == 1  # True
>>> my_function.b.value = "world"

match_return_type(type_)

Check simple type mappings for result widgets.

match_type(type_, default=None)

Check simple type mappings.

register_type(type_=None, *, widget_type=None, return_callback=None, **options)

Register a widget_type to be used for all parameters with type type_.

Note: registering a Union (or Optional) type effectively registers all types in the union with the arguments.

Parameters:

• type_ (type, default: None ) –

  The type for which a widget class or return callback will be provided.

• widget_type (WidgetRef, default: None ) –

  A widget class from the current backend that should be used whenever type_ is used as the type annotation for an argument in a decorated function, by default None

• return_callback (ReturnCallback | None, default: None ) –

  If provided, whenever type_ is declared as the return type of a decorated function, return_callback(widget, value, return_type) will be called whenever the decorated function is called... where widget is the Widget instance, and value is the return value of the decorated function.

• options (Any, default: {} ) –

  key value pairs where the keys are valid dict

Raises:

• ValueError –

  If none of widget_type, return_callback, bind or choices are provided.

type2callback(type_)

Return any callbacks that have been registered for type_.

Parameters:

• type_ (type) –

  The type_ to look up.

Returns:

• list of callable –

  Where a return callback accepts two arguments (gui, value) and does something.

type_registered(type_, *, widget_type=None, return_callback=None, **options)

Context manager that temporarily registers a widget type for a given type_.

When the context is exited, the previous widget type associations for type_ is restored.

Parameters:

• type_ (_T) –

  The type for which a widget class or return callback will be provided.

• widget_type (Optional[WidgetRef], default: None ) –

  A widget class from the current backend that should be used whenever type_ is used as the type annotation for an argument in a decorated function, by default None

• return_callback (ReturnCallback | None, default: None ) –

  If provided, whenever type_ is declared as the return type of a decorated function, return_callback(widget, value, return_type) will be called whenever the decorated function is called... where widget is the Widget instance, and value is the return value of the decorated function.

• options (Any, default: {} ) –

  key value pairs where the keys are valid dict