Contributions Reference

Contributions are a set of static declarations that you make in the contributions field of the Plugin Manifest. Your extension registers Contributions to extend various functionalities within napari. Here is a list of all available Contributions:

• commands

• readers

• writers

• widgets

• sample_data

• themes

• menus

• submenus

• configurations

You may add as many contributions as you’d like to a single manifest. For clarity, the following examples include only the specific contribution that is being discussed.

contributions.commands

Tip

This contribution accepts 1 schema types

1. CommandContribution

Contribute a command (a python callable) consisting of a unique id, a title and (optionally) a python_name that points to a fully qualified python callable. If a python_name is not included in the manifest, it must be registered during activation with register_command.

Note, some other contributions (e.g. readers, writers and widgets) will point to a specific command. The command itself (i.e. the callable python object) will always appear in the contributions.commands section, but those contribution types may add additional contribution-specific metadata.

Future Plans

Command contributions will eventually include an icon, category, and enabled state. Enablement is expressed with when clauses, that capture a conditional expression determining whether the command should be enabled or not, based on the current state of the program. (i.e. “If the active layer is a Labels layer”)

Commands will eventually be availble in a Command Palette (accessible with a hotkey) but they can also show in other menus.

Fields

• commands.id : A unique identifier used to reference this command. While this may look like a python fully qualified name this does not refer to a python object; this identifier is specific to napari. It must begin with the name of the package, and include only alphanumeric characters, plus dashes and underscores.

• commands.title : User facing title representing the command. This might be used, for example, when searching in a command palette. Examples: ‘Generate lily sample’, ‘Read tiff image’, ‘Open gaussian blur widget’.

• commands.python_name : (Optional: default=None). Fully qualified name to a callable python object implementing this command. This usually takes the form of {obj.__module__}:{obj.__qualname__} (e.g. my_package.a_module:some_function)

• commands.short_title : (Optional: default=None). Short title by which the command is represented in the UI. Menus pick either title or short_title depending on the context in which they show commands.

• commands.category : (Optional: default=None). Category string by which the command may be grouped in the UI.

• commands.icon : (Optional: default=None). Icon used to represent this command in the UI, on buttons or in menus. Can be a single string or two different options for light and dark themes. These values may be:

  • a string in format {package}:{resource}, where package andresource are arguments to importlib.resources.path(package, resource) (e.g. my_plugin.some_module:my_logo.png). This resource must be shippedwith the wheel, e.g. via the package-data entry in pyproject.toml)
  • a superqt fonticon key, such as 'fa6s.arrow_down' (though note that plugins are expected to depend on any fonticon libraries they use, e.g. fonticon-fontawesome6)

  • commands.enablement : (Optional: default=None). Expression which must evaluate as true to enable the command in the UI (menu and keybindings). Does not prevent executing the command by other means, like the execute_command api.

Commands example

yaml

contributions:
  commands:
  - id: example-plugin.hello_world
    title: Hello World

toml

[contributions]
commands = [
    { id = "example-plugin.hello_world", title = "Hello World" },
]

contributions.readers

Tip

This contribution accepts 1 schema types

1. ReaderContribution

Contribute a file reader.

Readers may be associated with specific filename_patterns (e.g. “.tif”, “.zip”) and are invoked whenever viewer.open('some/path') is used on the command line, or when a user opens a file in the graphical user interface by dropping a file into the canvas, or using File -> Open...

See the Readers Guide for more details on implementing this contribution.

Fields

• readers.command : Identifier of the command providing napari_get_reader.

• readers.filename_patterns : List of filename patterns (for fnmatch) that this reader can accept. Reader will be tried only if fnmatch(filename, pattern) == True. Use ['*'] to match all filenames.

• readers.accepts_directories : (Optional: default=False). Whether this reader accepts directories

Readers example

yaml

contributions:
  commands:
  - id: example-plugin.read_xyz
    title: Read ".xyz" files
    python_name: example_plugin.some_module:get_reader
  readers:
  - command: example-plugin.read_xyz
    filename_patterns:
    - '*.xyz'
    accepts_directories: false

toml

[[contributions.commands]]
id = "example-plugin.read_xyz"
title = "Read \".xyz\" files"
python_name = "example_plugin.some_module:get_reader"

[[contributions.readers]]
command = "example-plugin.read_xyz"
filename_patterns = [
    "*.xyz",
]
accepts_directories = false

contributions.writers

Tip

This contribution accepts 1 schema types

1. WriterContribution

Contribute a layer writer.

Writers accept data from one or more layers and write them to file. Writers declare support for writing one or more layer_types, may be associated with specific filename_patterns (e.g. “*.tif”, “*.zip”) and are invoked whenever viewer.layers.save('some/path.ext') is used on the command line, or when a user requests to save one or more layers in the graphical user interface with File -> Save Selected Layer(s)... or Save All Layers...

See the Writers Guide for more details on implementing this contribution.

Fields

• writers.command : Identifier of the command providing a writer.

• writers.layer_types : List of layer type constraints. These determine what layers (or combinations thereof) this writer handles.

• writers.filename_extensions : (Optional: default=None). List of filename extensions compatible with this writer. The first entry is used as the default if necessary. Empty by default. When empty, any filename extension is accepted.

• writers.display_name : (Optional: default=). Brief text used to describe this writer when presented. Empty by default. When present, this string is presented in the save dialog along side the plugin name and may be used to distinguish the kind of writer for the user. E.g. “lossy” or “lossless”.

Writers example

yaml

contributions:
  commands:
  - id: example-plugin.write_points
    title: Save points layer to csv
    python_name: example_plugin.some_module:write_points
  writers:
  - command: example-plugin.write_points
    layer_types:
    - points
    filename_extensions:
    - .csv

toml

[[contributions.commands]]
id = "example-plugin.write_points"
title = "Save points layer to csv"
python_name = "example_plugin.some_module:write_points"

[[contributions.writers]]
command = "example-plugin.write_points"
layer_types = [
    "points",
]
filename_extensions = [
    ".csv",
]

contributions.widgets

Tip

This contribution accepts 1 schema types

1. WidgetContribution

Contribute a widget that can be added to the napari viewer.

Widget contributions point to a command that, when called, returns a widget instance; this includes functions that return a widget instance, (e.g. those decorated with magicgui.magic_factory) and subclasses of either QtWidgets.QWidget or magicgui.widgets.Widget.

Optionally, autogenerate may be used to create a widget (using magicgui) from a command. (In this case, the command needn’t return a widget instance; it can be any function suitable as an argument to magicgui.magicgui().)

See the Widgets Guide for more details on implementing this contribution.

Fields

• widgets.command : Identifier of a command that returns a widget instance. Or, if autogenerate is True, any command suitable as an argument to magicgui.magicgui().

• widgets.display_name : Name for the widget, as presented in the UI.

• widgets.autogenerate : (Optional: default=False). If true, a widget will be autogenerated from the signature of the associated command using magicgui.

Widgets example

yaml

contributions:
  commands:
  - id: example-plugin.my_widget
    title: Open my widget
    python_name: example_plugin.some_module:MyWidget
  - id: example-plugin.threshold_widget
    title: Make threshold widget with magic_factory
    python_name: example_plugin.some_module:widget_factory
  - id: example-plugin.do_threshold
    title: Perform threshold on image, return new image
    python_name: example_plugin.some_module:threshold
  widgets:
  - command: example-plugin.my_widget
    display_name: Wizard
  - command: example-plugin.threshold_widget
    display_name: Threshold
  - command: example-plugin.do_threshold
    display_name: Threshold
    autogenerate: true

toml

[contributions]
widgets = [
    { command = "example-plugin.my_widget", display_name = "Wizard" },
    { command = "example-plugin.threshold_widget", display_name = "Threshold" },
    { command = "example-plugin.do_threshold", display_name = "Threshold", autogenerate = true },
]

[[contributions.commands]]
id = "example-plugin.my_widget"
title = "Open my widget"
python_name = "example_plugin.some_module:MyWidget"

[[contributions.commands]]
id = "example-plugin.threshold_widget"
title = "Make threshold widget with magic_factory"
python_name = "example_plugin.some_module:widget_factory"

[[contributions.commands]]
id = "example-plugin.do_threshold"
title = "Perform threshold on image, return new image"
python_name = "example_plugin.some_module:threshold"

contributions.sample_data

Tip

This contribution accepts 0 schema types

Sample Data example

yaml

contributions:
  commands:
  - id: example-plugin.data.fractal
    title: Create fractal image
    python_name: example_plugin.some_module:create_fractal
  sample_data:
  - command: example-plugin.data.fractal
    key: fractal
    display_name: Fractal
  - key: napari
    display_name: Tabueran Kiribati
    uri: https://en.wikipedia.org/wiki/Napari#/media/File:Tabuaeran_Kiribati.jpg

toml

[[contributions.commands]]
id = "example-plugin.data.fractal"
title = "Create fractal image"
python_name = "example_plugin.some_module:create_fractal"

[[contributions.sample_data]]
command = "example-plugin.data.fractal"
key = "fractal"
display_name = "Fractal"

[[contributions.sample_data]]
key = "napari"
display_name = "Tabueran Kiribati"
uri = "https://en.wikipedia.org/wiki/Napari#/media/File:Tabuaeran_Kiribati.jpg"

contributions.themes

Tip

This contribution accepts 1 schema types

1. ThemeContribution

Contribute a color theme to napari.

You must specify an id, label, and whether the theme is a dark theme or a light theme type so napari can derive matching icons and fallback colors. Any color keys omitted from the theme contribution will use the default napari dark/light theme colors for the selected base theme.

Fields

• themes.id : Identifier of the color theme as used in the user settings.

• themes.label : Label of the color theme as shown in the UI.

• themes.type : Base theme type, used for icons and filling in unprovided colors. Must be either 'dark' or 'light'.

• themes.syntax_style : (Optional: default=None). Optional Pygments syntax style for napari’s built-in console. If omitted, the base theme’s style is used.

• themes.colors : Theme colors. Valid keys include: canvas, console, background, foreground, primary, secondary, highlight, text, icon, warning, error, current. All keys are optional and omitted keys inherit from the selected base theme.

Color values can be defined via:

• named colors: "black", "azure"

• hexadecimal values: "0x000", "#FFFFFF", "7fffd4"

• RGB/RGBA tuples: (255, 255, 255), (255, 255, 255, 0.5)

• RGB/RGBA strings: "rgb(255, 255, 255)", "rgba(255, 255, 255, 0.5)"

• HSL strings: "hsl(270, 60%, 70%)", "hsl(270, 60%, 70%, .5)"

• themes.font_size : (Optional: default=9pt). Font size (in points, pt) used in the application.

Themes example

yaml

contributions:
  themes:
  - id: monokai
    label: Monokai
    type: dark
    syntax_style: monokai
    colors:
      canvas: black
      console: black
      background: '#272822'
      foreground: '#75715e'
      primary: '#cfcfc2'
      secondary: '#f8f8f2'
      highlight: '#e6db74'
      text: '#a1ef34'
      icon: '#a1ef34'
      warning: '#f92672'
      error: '#f55'
      current: '#66d9ef'

toml

[[contributions.themes]]
id = "monokai"
label = "Monokai"
type = "dark"
syntax_style = "monokai"

[contributions.themes.colors]
canvas = "black"
console = "black"
background = "#272822"
foreground = "#75715e"
primary = "#cfcfc2"
secondary = "#f8f8f2"
highlight = "#e6db74"
text = "#a1ef34"
icon = "#a1ef34"
warning = "#f92672"
error = "#f55"
current = "#66d9ef"

contributions.menus

Tip

This contribution accepts 2 schema types

Add menu items to existing napari menus.A menu item can be a command, such as open a widget, or a submenu.Using menu items, nested hierarchies can be created within napari menus.This allows you to organize your plugin’s contributions withinnapari’s menu structure.

1. MenuCommand

See the Menus Guide for more details on implementing this contribution.

Fields

• menus.command : Identifier of the command to execute. The command must be declared in the ‘commands’ section

• menus.when : (Optional: default=None). Condition which must be true to show this item in the menu. Note that when clauses apply to menus and enablement clauses to commands. The enablement applies to all menus and even keybindings while the when only applies to a single menu.

• menus.group : (Optional: default=None). The group property defines sorting and grouping of menu items. The 'navigation' group is special: it will always be sorted to the top/beginning of a menu. By default, the order inside a group depends on the title. The group-local order of a menu item can be specified by appending @ to the group identifier: e.g. group: 'myGroup@2'.

• menus.alt : (Optional: default=None). Identifier of an alternative command to execute. It will be shown and invoked when pressing Alt while opening a menu.The command must be declared in the ‘commands’ section

2. Submenu

See the Menus Guide for more details on implementing this contribution.

Fields

• menus.when : (Optional: default=None). Condition which must be true to show this item in the menu. Note that when clauses apply to menus and enablement clauses to commands. The enablement applies to all menus and even keybindings while the when only applies to a single menu.

• menus.group : (Optional: default=None). The group property defines sorting and grouping of menu items. The 'navigation' group is special: it will always be sorted to the top/beginning of a menu. By default, the order inside a group depends on the title. The group-local order of a menu item can be specified by appending @ to the group identifier: e.g. group: 'myGroup@2'.

• menus.submenu : Identifier of the submenu to display in this item.The submenu must be declared in the ‘submenus’ -section

Menus example

yaml

contributions:
  menus:
    napari/layers/segment:
    - submenu: threshold
    - command: example-plugin.all_thresholds
    threshold:
    - command: example-plugin.threshold_otsu
    - command: example-plugin.threshold_li

toml

[contributions.menus]
"napari/layers/segment" = [
    { submenu = "threshold" },
    { command = "example-plugin.all_thresholds" },
]
threshold = [
    { command = "example-plugin.threshold_otsu" },
    { command = "example-plugin.threshold_li" },
]

contributions.submenus

Tip

This contribution accepts 1 schema types

1. SubmenuContribution

Contributes a submenu that can contain menu items or other submenus.

Submenus allow you to organize menu items into hierarchical structures. Each submenu defines an id, label, and optional icon that can be referenced by menu items to create nested menu structures.

Fields

• submenus.id : Identifier of the menu to display as a submenu.

• submenus.label : The label of the menu item which leads to this submenu.

• submenus.icon : (Optional: default=None). Icon used to represent this command in the UI, on buttons or in menus. Can be a single string or two different options for light and dark themes. These values may be:

  • a string in format {package}:{resource}, where package andresource are arguments to importlib.resources.path(package, resource) (e.g. my_plugin.some_module:my_logo.png). This resource must be shippedwith the wheel, e.g. via the package-data entry in pyproject.toml)
  • a superqt fonticon key, such as 'fa6s.arrow_down' (though note that plugins are expected to depend on any fonticon libraries they use, e.g. fonticon-fontawesome6)

Submenus example

yaml

contributions:
  submenus:
  - id: threshold
    label: Thresholding

toml

[contributions]
submenus = [
    { id = "threshold", label = "Thresholding" },
]

contributions.configurations

Configuration options for this plugin, keyed by a configuration key. A plugin can contribute multiple categories of settings by declaring multiple entries here; each shows up as its own submenu in the Settings editor, headed by that entry’s title. Each configuration key must be a valid, non-reserved Python identifier that does not begin with an underscore, and must be unique within the manifest, since it is used verbatim as the attribute name for that setting’s category on the generated settings model (e.g. get_plugin_settings('plugin-name').<configuration-key>.<property-key>).

See the Configurations Guide for more details on implementing this contribution.

Fields

• configurations.title : The heading used for this configuration category, displayed in the settings UI. Words like “Plugin”, “Configuration”, and “Settings” are redundant and should not be used in your title. Unlike the key under which this contribution is declared in contributions.configurations, the title is display text only and does not need to be unique.

• configurations.properties : Configuration properties, keyed by a property key that is local to this configuration contribution. Each property key must be a valid, non-reserved Python identifier that does not begin with an underscore, since it is used verbatim as the attribute name for that setting on the generated settings model (e.g. get_plugin_settings('plugin-name').<configuration-key>.<property-key>). Property keys only need to be unique within this configuration contribution, not across the whole plugin.

ConfigurationProperty fields

Configuration for a single property in the plugin settings.

This is a subset of the JSON Schema (draft 2020-12) specification. https://json-schema.org/draft/2020-12/ with some additional fields for the settings UI.

Fields

• title : (required) The title of this configuration property. This will be displayed in the settings UI as the label for this property.

• type : (required) The type of this variable. Either a JSON Schema type name (‘boolean’, ‘integer’, ‘number’, ‘string’) or a python type name (‘bool’, ‘int’, ‘float’, ‘str’) may be used, but it will be coerced to a JSON Schema type. For boolean entries, the description will be used as the label for the checkbox.

• default : (required) The default value for this property.

• description : Your description appears after the title and before the input field, except for booleans, where the description is used as the label for the checkbox

• enum : A list of valid options for this field. If you provide this field,the settings UI will render a dropdown menu. Enum members must be of the same type as the type field.

• minimum : The inclusive lower bound: the value must be greater than or equal to this number. Only valid for integer or number types.

• maximum : The inclusive upper bound: the value must be less than or equal to this number. Only valid for integer or number types.

• exclusive_maximum : The exclusive upper bound: the value must be strictly less than this number. Only valid for integer or number types.

• exclusive_minimum : The exclusive lower bound: the value must be strictly greater than this number. Only valid for integer or number types.

• multiple_of : Restricts the value to an integer multiple of this number (e.g. multiple_of: 5 allows 0, 5, 10, …). Only valid for integer or number types.

• max_length : The maximum allowed length, in characters, of a string value. Only valid for the string type.

• min_length : The minimum allowed length, in characters, of a string value. Only valid for the string type.

Configurations example

yaml

contributions:
  configurations:
    pre_processing_widget:
      title: Pre-processing Widget
      properties:
        colormap:
          title: Default colormap
          type: string
          default: gray
          description: Colormap applied to output images.
          enum:
          - gray
          - green
          - viridis
        gamma:
          title: Gamma correction
          type: number
          default: 1.0
          description: Gamma value applied to output images.
          minimum: 0.1
          maximum: 2.0
    reader:
      title: Reader
      properties:
        max_size_mb:
          title: Max in-memory image size (MB)
          type: integer
          default: 512
          description: Images larger than this are lazy-loaded via dask instead of
            being loaded eagerly.
          minimum: 1
          maximum: 4096
        auto_contrast:
          title: Auto-contrast on open
          type: boolean
          default: true
          description: Turn on auto-contrast on all opened layers.

toml

[contributions.configurations.pre_processing_widget]
title = "Pre-processing Widget"

[contributions.configurations.pre_processing_widget.properties.colormap]
title = "Default colormap"
type = "string"
default = "gray"
description = "Colormap applied to output images."
enum = [
    "gray",
    "green",
    "viridis",
]

[contributions.configurations.pre_processing_widget.properties.gamma]
title = "Gamma correction"
type = "number"
default = 1.0
description = "Gamma value applied to output images."
minimum = 0.1
maximum = 2.0

[contributions.configurations.reader]
title = "Reader"

[contributions.configurations.reader.properties.max_size_mb]
title = "Max in-memory image size (MB)"
type = "integer"
default = 512
description = "Images larger than this are lazy-loaded via dask instead of being loaded eagerly."
minimum = 1
maximum = 4096

[contributions.configurations.reader.properties.auto_contrast]
title = "Auto-contrast on open"
type = "boolean"
default = true
description = "Turn on auto-contrast on all opened layers."