magicgui.experimental

Experimental

This module contains experimental features that are not yet ready for prime time. All of the features in this module are subject to change without warning or deprecation.

magicgui.experimental.guiclass(cls: T | None = None, *, gui_name: str = 'gui', events_namespace: str = 'events', follow_changes: bool = True, **dataclass_kwargs: Any) -> T | Callable[[T], T]

Turn class into a dataclass with a property (gui_name) that returns a gui.

This decorator is similar to dataclasses.dataclass, but it will also add an events attribute to the class that is an instance of psygnal.SignalGroup (with a signal for each field in the dataclass; see https://psygnal.readthedocs.io/en/latest/dataclasses/ for details), and a gui property that returns a magicgui widget, bound to the values of the dataclass instance.

Note

This decorator is compatible with dataclasses using slots=True, however, there is a potential for a memory leak that the user should be aware of. If you create a guiclass instance, and then store a reference to its gui, and then delete the instance, the gui will still be bound to the instance, preventing it from being garbage collected. To avoid this, you can call unbind_gui_from_instance(gui, instance) before deleting the instance.

Parameters:

• cls (type, default: None ) –

  The class to turn into a dataclass.

• gui_name (str, default: 'gui' ) –

  The name of the property that will return a magicgui widget, by default "gui"

• events_namespace (str, default: 'events' ) –

  The name of the attribute that will be added to the class, by default "events". This attribute will be an instance of psygnal.SignalGroup that will be used to connect events to the class.

• follow_changes (bool, default: True ) –

  If True (default), changes to the dataclass instance will be reflected in the gui, and changes to the gui will be reflected in the dataclass instance.

• dataclass_kwargs (dict, default: {} ) –

  Additional keyword arguments to pass to dataclasses.dataclass.

Returns:

• type –

  The dataclass.

Examples:

>>> @guiclass
... class MyData:
...     x: int = 0
...     y: str = 'hi'
...
...     @button
...     def reset(self):
...         self.x = 0
...         self.y = 'hi'
...
>>> data = MyData()
>>> data.gui.show()

magicgui.experimental.button(func: F | None = None, **button_kwargs: Any) -> F | Callable[[F], F]

Add a method as a button to a guiclass, which calls the decorated method.

Parameters:

• func (callable, default: None ) –

  The method to decorate. If None, returns a decorator that can be applied to a method.

• button_kwargs (dict, default: {} ) –

  Additional keyword arguments to pass to magicgui.widgets.PushButton.

magicgui.experimental.is_guiclass(obj: object) -> TypeGuard[GuiClassProtocol]

Return True if obj is a guiclass or an instance of a guiclass.