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

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`#

Contribute a command (a python callable) consisting of a unique id, a title and (optionally) a python_path that points to a fully qualified python callable. If a python_path 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. These may be superqt fonticon keys, 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`#

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`#

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`#

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 2 schema types

1. Sample Data Function#

Contribute a callable command that creates data on demand.

See the Sample Data Guide for more details on implementing this contribution.

Fields

sample_data.command : Identifier of a command that returns layer data tuple.
sample_data.key : A unique key to identify this sample.
sample_data.display_name : String to show in the UI when referring to this sample

2. Sample Data URI#

Contribute a URI to static local or remote data. This can be data included in the plugin package, or a URL to remote data. The URI must be readable by either napari’s builtin reader, or by a plugin that is included/required.

See the Sample Data Guide for more details on implementing this contribution.

Fields

sample_data.key : A unique key to identify this sample.
sample_data.display_name : String to show in the UI when referring to this sample
sample_data.uri : Path or URL to a data resource. This URI should be a valid input to io_utils.read
sample_data.reader_plugin : (Optional: default=None). Name of plugin to use to open URI

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`#

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 (such that the rest of napari changes to match your theme). Any color keys omitted from the theme contribution will use the default napari dark/light theme colors.

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).
themes.colors : Theme colors. Valid keys include: canvas, console, background, foreground, primary, secondary, highlight, text, icon, warning, current. All keys are optional. Color values can be defined via:
- name: "Black", "azure"
- hexadecimal value: "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 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'
      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"
current = "#66d9ef"

Contributions Reference#

contributions.commands#

Commands example#

contributions.readers#

Readers example#

contributions.writers#

Writers example#

contributions.widgets#

Widgets example#

contributions.sample_data#

1. Sample Data Function#

2. Sample Data URI#

Sample Data example#

contributions.themes#

Themes example#

`contributions.commands`#

`contributions.readers`#

`contributions.writers`#

`contributions.widgets`#

`contributions.sample_data`#

`contributions.themes`#