Skip to content

magicgui.magic_factory#

magicgui.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.type_map._magicgui.MagicFactory #

Bases: partial, Generic[_FGuiVar]

Factory function that returns a FunctionGui instance.

While this can be used directly, (see example below) the preferred usage is via the magicgui.magic_factory decorator.

Examples:

>>> def func(x: int, y: str):
...     pass
...
>>> factory = MagicFactory(function=func, labels=False)
>>> # factory accepts all the same arguments as magicgui()
>>> widget1 = factory(call_button=True)
>>> # can also override magic_kwargs that were provided when creating the factory
>>> widget2 = factory(auto_call=True, labels=True)

__name__: str property #

Pass function name.

__call__(*args, **kwargs) #

Call the wrapped _magicgui and return a FunctionGui.

__getattr__(name) #

Allow accessing FunctionGui attributes without mypy error.

__new__(function, *args, magic_class=FunctionGui, widget_init=None, **keywords) #

Create new MagicFactory.

__repr__() #

Return string repr.