magicgui type registration#

magicgui uses type hints to infer the appropriate widget type for a given function parameter. It allows third party packages (like napari) to register support for their types using register_type(). napari registers a number of types, additionally specifying, where appropriate:

  • widget type for the parameter type

  • function for updating inputs for the widget

  • return callback, for return types

This enables magicgui widgets to be easily created via type annotations.

Note

This page provides implementation details on napari-specific type registration in magicgui and is aimed at napari developers.

For information about using magicgui (for users and plugin developers) see Creating widgets.

Registration details#

napari types are either registered via the @register_type decorator when they are defined or in napari/types.py. For the full list of types registered, see Parameter annotations.

Layer types#

The ‘layer’ types registered are Layer and its subclasses, and <LayerType>Data types. All these types provide a choices callable when they are registered with magicgui. This means that annotating with these types creates a CategoricalWidget, which will have a dropdown selection whose options will be updated via the choices callable.

This callable is either get_layers_data or get_layers. These functions retrieve the closest parent Viewer of the native CategoricalWidget widget and returns a list of Layer or tuple of format ('layer name', <LayerType>Data). This callable is set to the choices attribute of the CategoricalWidget in its reset_choices() method and thus gets called via CategoricalWidget’s choices setter. napari add_dock_widget() checks if the dock widget has a reset_choices attribute and if so, connects it to layer events.

Note that magicgui ContainerWidget’s will call reset_choices on all subwidgets. This means that when the dock widget is a ContainerWidget, any subwidgets (e.g., CategoricalWidgets) are updated whenever layers change. Note that add_dock_widget() will connect any existing reset_choices widget attribute to layer events for all widgets, not just magicgui widgets.

The ‘layer’ types also specify a return_callback function that adds the layer to the closest parent Viewer of the native widget when a ‘layer’ type is a return annotation.

Viewer type#

Viewer differs from the layer types. napari simply specifies that the closest parent Viewer (technically a public proxy of the Viewer that prevents private attribute access) be bound to the widget (technically it’s bound to a hidden child EmptyWidget). This allows the Viewer to be used in the magicgui widget.

Note

When widget is not a magicgui widget, the Viewer is provided via a wrapper napari adds around widget contributions.

Generalization of magicgui type annotation#

napari generalizes magicgui type annotation behaviour beyond magicgui widgets, to all actions via app-model providers and processors. See Dependency injection and result processing for details.