napari plugin manifest

a napari plugin manifest

Type object
File match napari.yml napari.yaml .napari.yml .napari.yaml
Schema URL https://catalog.lintel.tools/schemas/schemastore/napari-plugin-manifest/latest.json
Source https://github.com/napari/npe2/releases/latest/download/schema.json

Validate with Lintel

npx @lintel/lintel check
Type: object

Properties

name string required

The name of the plugin. Though this field is mandatory, it must match the package name as defined in the python package metadata.

display_name string

User-facing text to display as the name of this plugin. Must be 3-90 characters long and must not begin or end with an underscore, white space, or non-word character. If not provided, the manifest name will be used as the display name.

Default: ""
minLength=3maxLength=90
visibility string

Whether this plugin should be searchable and visible in the built-in plugin installer and the napari hub. By default ('public') all plugins are visible. To prevent your plugin from appearing in search results, change this to 'hidden'.

Default: "public"
Values: "public" "hidden"
icon string

The path to a square PNG icon of at least 128x128 pixels (256x256 for Retina screens). May be one of:

  • a secure (https) URL
  • a path relative to the manifest file, (must be shipped in the sdist)
  • a string in the format {package}:{resource}, where package and resource are arguments to importlib.resources.path(package, resource), (e.g. top_module.some_folder:my_logo.png).

Default: ""
categories Category[]

A list of categories that this plugin belongs to. This is used to help users discover your plugin. Allowed values: [Acquisition, Annotation, Dataset, Image Processing, IO, Measurement, Registration, Segmentation, Simulation, Themes, Transformations, Utilities, Visualization]

schema_version string

A SemVer compatible version string matching the napari plugin schema version that the plugin is compatible with.

Default: "0.2.1"
on_activate string | null

Fully qualified python path to a function that will be called upon plugin activation (e.g. 'my_plugin.some_module:activate'). The activate function can be used to connect command ids to python callables, or perform other side-effects. A plugin will be 'activated' when one of its contributions is requested by the user (such as a widget, or reader).

Default: null
on_deactivate string | null

Fully qualified python path to a function that will be called when a user deactivates a plugin (e.g. 'my_plugin.some_module:deactivate'). This is optional, and may be used to perform any plugin cleanup.

Default: null
contributions object
10 nested properties
commands CommandContribution[] | null
Default: null
readers ReaderContribution[] | null
Default: null
writers WriterContribution[] | null
Default: null
widgets WidgetContribution[] | null
Default: null
sample_data SampleDataGenerator | SampleDataURI[] | null
Default: null
themes ThemeContribution[] | null
Default: null
menus Record<string, MenuCommand | Submenu[]>

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.

submenus SubmenuContribution[] | null
Default: null
keybindings KeyBindingContribution[] | null
Default: null
configuration ConfigurationContribution[]

Configuration options for this plugin.This section can either be a single object, representing a single category ofsettings, or an array of objects, representing multiple categories ofsettings. If there are multiple categories of settings, the Settings editorwill show a submenu in the table of contents for that extension, and the titlekeys will be used for the submenu entry names.

package_metadata PackageMetadata | null

Package metadata following https://packaging.python.org/specifications/core-metadata/. For normal (non-dynamic) plugins, this data will come from the package's setup.cfg

Default: null
npe1_shim boolean

Whether this manifest was created as a shim for an npe1 plugin.

Default: false

Definitions

Category string

Broad plugin categories, values for PluginManifest.categories.

CommandContribution object

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.

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.
id string required

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.

title string required

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'.

python_name string | null

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)

Default: null
short_title string | null

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.

Default: null
category string | null

Category string by which the command may be grouped in the UI.

Default: null
icon string | Icon | null

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.

Default: null
enablement string | null

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.

Default: null
ConfigurationContribution object

A configuration contribution for a plugin.

This enables plugins to provide a schema for their configurables. Configuration contributions are used to generate the settings UI.

title string required

The heading used for this configuration category. Words like "Plugin", "Configuration", and "Settings" are redundant and should not beused in your title.

properties Record<string, object> required

Configuration properties. In the settings UI, your configuration key will be used to namespace and construct a title. Though a plugin can contain multiple categories of settings, each plugin setting must still have its own unique key. Capital letters in your key are used to indicate word breaks. For example, if your key is 'gitMagic.blame.dateFormat', the generated title for the setting will look like 'Blame: Date Format'

ConfigurationProperty object

Configuration for a single property in the plugin settings.

This is a super-set of the JSON Schema (draft 7) specification. https://json-schema.org/understanding-json-schema/reference/index.html

$schema string
Default: "http://json-schema.org/draft-07/schema#"
title string | null
Default: null
description string | null

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. See also markdown_description.

Default: null
default

The default value for this property.

Default: null
multiple_of number | null
Default: null
maximum number | null
Default: null
minimum number | null
Default: null
max_length integer | null
Default: null
min_length integer | null
Default: 0
pattern string | null
Default: null
max_items integer | null
Default: null
min_items integer | null
Default: 0
unique_items boolean
Default: false
max_properties integer | null
Default: null
min_properties integer | null
Default: 0
enum array | null

A list of valid options for this field. If you provide this field,the settings UI will render a dropdown menu.

Default: null
type string | string[]

The type of this variable. Either JSON Schema type names ('array', 'boolean', 'object', ...) or python type names ('list', 'bool', 'dict', ...) may be used, but they will be coerced to JSON Schema types. Numbers, strings, and booleans will be editable in the UI, other types (lists, dicts) may be editable in the UI depending on their content, but maby will only be editable as text in the napari settings file. For boolean entries, the description (or markdownDescription) will be used as the label for the checkbox.

Default: null
format string | null
Default: null
$id string | null
Default: null
examples array | null
Default: null
exclusive_maximum number | null
Default: null
exclusive_minimum number | null
Default: null
contains Draft06JsonSchema | null
Default: null
required string[] | null
Default: null
dependencies object | null
Default: null
property_names Draft06JsonSchema | null
Default: null
const
Default: null
$comment string | null
Default: null
read_only boolean
Default: false
write_only boolean
Default: false
content_media_type string | null
Default: null
content_encoding string | null
Default: null
if Draft07JsonSchema | null
Default: null
then Draft07JsonSchema | null
Default: null
else Draft07JsonSchema | null
Default: null
additional_items boolean | Draft07JsonSchema | null
Default: null
items Draft07JsonSchema | Draft07JsonSchema[] | null
Default: null
additional_properties boolean | Draft07JsonSchema | null
Default: null
properties object | null
Default: null
pattern_properties object | null
Default: null
all_of Draft07JsonSchema[] | null
Default: null
any_of Draft07JsonSchema[] | null
Default: null
one_of Draft07JsonSchema[] | null
Default: null
not Draft07JsonSchema | null
Default: null
description_format string

By default (markdown) your description, will be parsed as CommonMark (with markdown_it) and rendered as rich text. To render as plain text, set this value to plain.

Default: "markdown"
Values: "markdown" "plain"
enum_descriptions string[]

If you provide a list of items under the enum field, you may provide enum_descriptions to add descriptive text for each enum.

enum_descriptions_format string

By default (markdown) your enum_descriptions, will be parsed as CommonMark (with markdown_it) and rendered as rich text. To render as plain text, set this value to plain.

Default: "markdown"
Values: "markdown" "plain"
deprecation_message string | null

If you set deprecationMessage, the setting will get a warning underline with your specified message. It won't show up in the settings UI unless it is configured by the user.

Default: null
deprecation_message_format string

By default (markdown) your deprecation_message, will be parsed as CommonMark (with markdown_it) and rendered as rich text. To render as plain text, set this value to plain.

Default: "markdown"
Values: "markdown" "plain"
edit_presentation string

By default, string settings will be rendered with a single-line editor. To render with a multi-line editor, set this value to multiline.

Default: "singleline"
Values: "singleline" "multiline"
order integer | null

When specified, gives the order of this setting relative to other settings within the same category. Settings with an order property will be placed before settings without this property set; and settings without order will be placed in alphabetical order.

Default: null
pattern_error_message string | null

When restricting string types to a given regular expression with the pattern field, this field may be used to provide a custom error when the pattern does not match.

Default: null
ContributionPoints object
commands CommandContribution[] | null
Default: null
readers ReaderContribution[] | null
Default: null
writers WriterContribution[] | null
Default: null
widgets WidgetContribution[] | null
Default: null
sample_data SampleDataGenerator | SampleDataURI[] | null
Default: null
themes ThemeContribution[] | null
Default: null
menus Record<string, MenuCommand | Submenu[]>

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.

submenus SubmenuContribution[] | null
Default: null
keybindings KeyBindingContribution[] | null
Default: null
configuration ConfigurationContribution[]

Configuration options for this plugin.This section can either be a single object, representing a single category ofsettings, or an array of objects, representing multiple categories ofsettings. If there are multiple categories of settings, the Settings editorwill show a submenu in the table of contents for that extension, and the titlekeys will be used for the submenu entry names.

Draft06JsonSchema object

Model for Draft 6 JSON Schema.

$schema string
Default: "http://json-schema.org/draft-06/schema#"
title string | null
Default: null
description string | null
Default: null
default
Default: null
multiple_of number | null
Default: null
maximum number | null
Default: null
minimum number | null
Default: null
max_length integer | null
Default: null
min_length integer | null
Default: 0
pattern string | null
Default: null
max_items integer | null
Default: null
min_items integer | null
Default: 0
unique_items boolean
Default: false
max_properties integer | null
Default: null
min_properties integer | null
Default: 0
enum array | null
Default: null
type string | string[]
Default: null
format string | null
Default: null
$id string | null
Default: null
examples array | null
Default: null
exclusive_maximum number | null
Default: null
exclusive_minimum number | null
Default: null
contains Draft06JsonSchema | null
Default: null
required string[] | null
Default: null
dependencies object | null
Default: null
property_names Draft06JsonSchema | null
Default: null
const
Default: null
additional_items boolean | Draft06JsonSchema | null
Default: null
items Draft06JsonSchema | Draft06JsonSchema[] | null
Default: null
additional_properties boolean | Draft06JsonSchema | null
Default: null
properties object | null
Default: null
pattern_properties object | null
Default: null
all_of Draft06JsonSchema[] | null
Default: null
any_of Draft06JsonSchema[] | null
Default: null
one_of Draft06JsonSchema[] | null
Default: null
not Draft06JsonSchema | null
Default: null
Draft07JsonSchema object

Model for Draft 7 JSON Schema.

$schema string
Default: "http://json-schema.org/draft-07/schema#"
title string | null
Default: null
description string | null
Default: null
default
Default: null
multiple_of number | null
Default: null
maximum number | null
Default: null
minimum number | null
Default: null
max_length integer | null
Default: null
min_length integer | null
Default: 0
pattern string | null
Default: null
max_items integer | null
Default: null
min_items integer | null
Default: 0
unique_items boolean
Default: false
max_properties integer | null
Default: null
min_properties integer | null
Default: 0
enum array | null
Default: null
type string | string[]
Default: null
format string | null
Default: null
$id string | null
Default: null
examples array | null
Default: null
exclusive_maximum number | null
Default: null
exclusive_minimum number | null
Default: null
contains Draft06JsonSchema | null
Default: null
required string[] | null
Default: null
dependencies object | null
Default: null
property_names Draft06JsonSchema | null
Default: null
const
Default: null
$comment string | null
Default: null
read_only boolean
Default: false
write_only boolean
Default: false
content_media_type string | null
Default: null
content_encoding string | null
Default: null
if Draft07JsonSchema | null
Default: null
then Draft07JsonSchema | null
Default: null
else Draft07JsonSchema | null
Default: null
additional_items boolean | Draft07JsonSchema | null
Default: null
items Draft07JsonSchema | Draft07JsonSchema[] | null
Default: null
additional_properties boolean | Draft07JsonSchema | null
Default: null
properties object | null
Default: null
pattern_properties object | null
Default: null
all_of Draft07JsonSchema[] | null
Default: null
any_of Draft07JsonSchema[] | null
Default: null
one_of Draft07JsonSchema[] | null
Default: null
not Draft07JsonSchema | null
Default: null
Icon object
light string | null
Default: null
dark string | null
Default: null
KeyBindingContribution object
command string required

Identifier of the command to run when keybinding is triggered.

key string required

Key or key sequence (separate simultaneous key presses with a plus-sign e.g. Ctrl+O and sequences with a space e.g. Ctrl+L L for a chord).

mac string | null required

Mac specific key or key sequence.

linux string | null required

Linux specific key or key sequence.

win string | null required

Windows specific key or key sequence.

when string | null required

Condition when the key is active.

MenuCommand object

Contributes a command in a menu.

command string required

Identifier of the command to execute. The command must be declared in the 'commands' section

when string | null

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.

Default: null
group string | null

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'.

Default: null
alt string | null

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

Default: null
PackageMetadata object

Pydantic model for standard python package metadata.

https://www.python.org/dev/peps/pep-0566/ https://packaging.python.org/pattern/core-metadata/

The importlib.metadata provides the metadata() function, but it returns a somewhat awkward email.message.Message object.

name string required

The name of the distribution. The name field is the primary identifier for a distribution.

pattern=^[a-zA-Z0-9][a-zA-Z0-9._-]*[a-zA-Z0-9]$
version string required

A string containing the distribution's version number. This field must be in the format specified in PEP 440.

metadata_version string | string

Version of the file format

Default: "1.0"
dynamic string[] | null

A string containing the name of another core metadata field. The field names Name and Version may not be specified in this field.

Default: null
platform string[] | null

A Platform specification describing an operating system supported by the distribution which is not listed in the “Operating System” Trove classifiers. See “Classifier” below.

Default: null
supported_platform string[] | null

Binary distributions containing a PKG-INFO file will use the Supported-Platform field in their metadata to specify the OS and CPU for which the binary distribution was compiled

Default: null
summary string | null

A one-line summary of what the distribution does.

Default: null
description string | null

A longer description of the distribution that can run to several paragraphs.

Default: null
description_content_type string | null

A string stating the markup syntax (if any) used in the distribution's description, so that tools can intelligently render the description. The type/subtype part has only a few legal values: text/plain, text/x-rst, text/markdown

Default: null
keywords string | null

A list of additional keywords, separated by commas, to be used to assist searching for the distribution in a larger catalog.

Default: null
home_page string | null

A string containing the URL for the distribution's home page.

Default: null
download_url string | null

A string containing the URL from which THIS version of the distribution can be downloaded.

Default: null
author string | null

A string containing the author's name at a minimum; additional contact information may be provided.

Default: null
author_email string | null

A string containing the author's e-mail address. It can contain a name and e-mail address in the legal forms for a RFC-822 From: header.

Default: null
maintainer string | null

A string containing the maintainer's name at a minimum; additional contact information may be provided.

Default: null
maintainer_email string | null

A string containing the maintainer's e-mail address. It can contain a name and e-mail address in the legal forms for a RFC-822 From: header.

Default: null
license string | null

Text indicating the license covering the distribution where the license is not a selection from the “License” Trove classifiers. See “Classifier” below. This field may also be used to specify a particular version of a license which is named via the Classifier field, or to indicate a variation or exception to such a license.

Default: null
classifier string[] | null

Each entry is a string giving a single classification value for the distribution. Classifiers are described in PEP 301, and the Python Package Index publishes a dynamic list of currently defined classifiers.

Default: null
requires_dist string[] | null

The field format specification was relaxed to accept the syntax used by popular publishing tools. Each entry contains a string naming some other distutils project required by this distribution.

Default: null
requires_python string | null

This field specifies the Python version(s) that the distribution is guaranteed to be compatible with. Installation tools may look at this when picking which version of a project to install. The value must be in the format specified in Version specifiers (PEP 440).

Default: null
requires_external string[] | null

The field format specification was relaxed to accept the syntax used by popular publishing tools. Each entry contains a string describing some dependency in the system that the distribution is to be used. This field is intended to serve as a hint to downstream project maintainers, and has no semantics which are meaningful to the distutils distribution.

Default: null
project_url string[] | null

A string containing a browsable URL for the project and a label for it, separated by a comma.

Default: null
provides_extra string[] | null

A string containing the name of an optional feature. Must be a valid Python identifier. May be used to make a dependency conditional on whether the optional feature has been requested.

Default: null
provides_dist string[] | null
Default: null
obsoletes_dist string[] | null
Default: null
ReaderContribution object

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...

command string required

Identifier of the command providing napari_get_reader.

filename_patterns string[] required

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.

accepts_directories boolean

Whether this reader accepts directories

Default: false
SampleDataGenerator object

Contribute a callable command that creates data on demand.

command string required

Identifier of a command that returns layer data tuple. Note that this command cannot return [(None,)].

key string required

A unique key to identify this sample.

display_name string required

String to show in the UI when referring to this sample

SampleDataURI object

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.

key string required

A unique key to identify this sample.

display_name string required

String to show in the UI when referring to this sample

uri string required

Path or URL to a data resource. This URI should be a valid input to io_utils.read

reader_plugin string | null

Name of plugin to use to open URI

Default: null
Submenu object

Contributes a submenu placement in a menu.

submenu string required

Identifier of the submenu to display in this item.The submenu must be declared in the 'submenus' -section

when string | null

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.

Default: null
group string | null

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'.

Default: null
SubmenuContribution object

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.

id string required

Identifier of the menu to display as a submenu.

label string required

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

icon string | Icon | null

(Optional) Icon which is used to represent the command in the UI. Either a file path, an object with file paths for dark and lightthemes, or a theme icon references, like $(zap)

Default: null
ThemeColors object
canvas string | null
Default: null
console string | null
Default: null
background string | null
Default: null
foreground string | null
Default: null
primary string | null
Default: null
secondary string | null
Default: null
highlight string | null
Default: null
text string | null
Default: null
icon string | null
Default: null
warning string | null
Default: null
current string | null
Default: null
ThemeContribution object

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.

id string required

Identifier of the color theme as used in the user settings.

label string required

Label of the color theme as shown in the UI.

type string required

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

Values: "dark" "light"
colors object required
11 nested properties
canvas string | null
Default: null
console string | null
Default: null
background string | null
Default: null
foreground string | null
Default: null
primary string | null
Default: null
secondary string | null
Default: null
highlight string | null
Default: null
text string | null
Default: null
icon string | null
Default: null
warning string | null
Default: null
current string | null
Default: null
syntax_style string | null
Default: null
font_size string

Font size (in points, pt) used in the application.

Default: "9pt"
WidgetContribution object

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().)

command string required

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

display_name string required

Name for the widget, as presented in the UI.

autogenerate boolean

If true, a widget will be autogenerated from the signature of the associated command using magicgui.

Default: false
WriterContribution object

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...

command string required

Identifier of the command providing a writer.

layer_types string[] required

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

filename_extensions string[]

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.

display_name string

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”.

Default: ""