napari / napari-plugin-devtools

A repo with tools and services for napari plugin developers

napari

multi-dimensional image viewer for python

napari is a fast, interactive, multi-dimensional image viewer for Python. It's designed for browsing, annotating, and analyzing large multi-dimensional images. It's built on top of Qt (for the GUI), vispy (for performant GPU-based rendering), and the scientific Python stack (numpy, scipy).

We're developing napari in the open! But the project is in an alpha stage, and there will still likely be breaking changes with each release. You can follow progress on this repository, test out new versions as we release them, and contribute ideas and code.

If you want to refer to our documentation, please go to napari.org. If you want to contribute to it, please refer to the contributing section below.

We're working on tutorials, but you can also quickly get started by looking below.

installation

It is recommended to install napari into a virtual environment, like this:

conda create -y -n napari-env -c conda-forge python=3.9
conda activate napari-env
python -m pip install "napari[all]"

If you prefer conda over pip, you can replace the last line with: conda install -c conda-forge napari pyqt

See here for the full installation guide.

simple example

(The examples below require the scikit-image package to run. We just use data samples from this package for demonstration purposes. If you change the examples to use your own dataset, you may not need to install this package.)

From inside an IPython shell, you can open up an interactive viewer by calling

from skimage import data
import napari

viewer = napari.view_image(data.cells3d(), channel_axis=1, ndisplay=3)

To use napari from inside a script, use napari.run():

from skimage import data
import napari

viewer = napari.view_image(data.cells3d(), channel_axis=1, ndisplay=3)
napari.run()  # start the "event loop" and show the viewer

features

Check out the scripts in our examples folder to see some of the functionality we're developing!

napari supports six main different layer types, Image, Labels, Points, Vectors, Shapes, and Surface, each corresponding to a different data type, visualization, and interactivity. You can add multiple layers of different types into the viewer and then start working with them, adjusting their properties.

All our layer types support n-dimensional data and the viewer provides the ability to quickly browse and visualize either 2D or 3D slices of the data.

napari also supports bidirectional communication between the viewer and the Python kernel, which is especially useful when launching from jupyter notebooks or when using our built-in console. Using the console allows you to interactively load and save data from the viewer and control all the features of the viewer programmatically.

You can extend napari using custom shortcuts, key bindings, and mouse functions.

tutorials

For more details on how to use napari checkout our tutorials. These are still a work in progress, but we'll be updating them regularly.

mission, values, and roadmap

For more information about our plans for napari you can read our mission and values statement, which includes more details on our vision for supporting a plugin ecosystem around napari. You can see details of the project roadmap here.

contributing

Contributions are encouraged! Please read our contributing guide to get started. Given that we're in an early stage, you may want to reach out on our Github Issues before jumping in.

If you want to contribute or edit to our documentation, please go to napari/docs.

code of conduct

napari has a Code of Conduct that should be honored by everyone who participates in the napari community.

governance

You can learn more about how the napari project is organized and managed from our governance model, which includes information about, and ways to contact the @napari/steering-council and @napari/core-devs.

citing napari

If you find napari useful please cite this repository using its DOI as follows:

napari contributors (2019). napari: a multi-dimensional image viewer for python. doi:10.5281/zenodo.3555620

Note this DOI will resolve to all versions of napari. To cite a specific version please find the DOI of that version on our zenodo page. The DOI of the latest version is in the badge at the top of this page.

help

We're a community partner on the image.sc forum and all help and support requests should be posted on the forum with the tag napari. We look forward to interacting with you there.

Bug reports should be made on our github issues using the bug report template. If you think something isn't working, don't hesitate to reach out - it is probably us and not you!

institutional and funding partners

napari-plugin-devtools's Issues

suppress Traceback & AssertionError for plugin errors

Currently, the CLI prints the full Traceback and AssertionError when a package is incompatible with napari.

What I get

When purposefully mis-spelling Framework :: napari to be Framework :: napar, I get the following when trying to validate the package...

(base) √ napari-hdf5-labels-io % npd --validate-package  

Traceback (most recent call last):
  File "/Users/justin.kiggins/opt/anaconda3/bin/npd", line 8, in <module>
    sys.exit(main())
  File "/Users/justin.kiggins/opt/anaconda3/lib/python3.8/site-packages/napari_plugin_devtools/__main__.py", line 25, in main
    validate_packages('dist')
  File "/Users/justin.kiggins/opt/anaconda3/lib/python3.8/site-packages/napari_plugin_devtools/validation.py", line 36, in validate_packages
    assert (
AssertionError: Classifier Framework :: napari must be specified for the plugin to be discovered

Displaying the Traceback here is confusing because it seems like there is an error in the CLI tool itself

What I expected

(base) √ napari-hdf5-labels-io % npd --validate-package  
Woops! You must specify "Framework :: napari" as a classifier for napari to recognize this package as containing napari plugins, but it was not found. 

The following classifiers were found:

        'Development Status :: 4 - Beta',
        'Intended Audience :: Developers',
        'Framework :: napar',
        'Topic :: Software Development :: Testing',
        'Programming Language :: Python',
        'Programming Language :: Python :: 3',
        'Programming Language :: Python :: 3.7',
        'Programming Language :: Python :: 3.8',
        'Programming Language :: Python :: 3.9',
        'Operating System :: OS Independent',
        'License :: OSI Approved :: GNU General Public License v3 (GPLv3)',

Update your classifiers to include "Framework :: napari", then rebuild the package.

A proposed solution

I would recommend the following...

1. capture AssertionErrors with try/except blocks
2. where possible provide additional guidance and context to the user, as in the example above
3. use exit(1) or a more appropriate exit code (is there a better one?) to exit so that CI/CD pipelines still throw an error

suppress Qt warning?

npd yields a warning about Qt versions for napari. This does not seem strictly necessary. Can we drop it?

(base) √ ~ % npd --help
/Users/justin.kiggins/opt/anaconda3/lib/python3.8/site-packages/napari/_qt/__init__.py:37: UserWarning: 
    napari was tested with QT library `>=5.12.3`.
    The version installed is 5.9.7. Please report any issues with this
    specific QT version at https://github.com/Napari/napari/issues.
    
  warn(message=warn_message)
usage: npd [-h] [--validate-packages] [--validate-functions]

optional arguments:
  -h, --help            show this help message and exit
  --validate-packages   validate the build packages is marked as napari plugin
  --validate-functions  validate the build packages is marked as napari plugin

pytest using napari crashes

Hi napari plugin devtools folks,

I'm trying to write tests for my napari plugin and such a test:

import napari
viewer = napari.Viewer(show=False)

fails in the github CI with this error:

Error: Process completed with exit code 134.

I've also tried with make_napari_viewer fixtures as done in napari tests, but the error is persistend. I assume I presume I'm calling tests in a wrong way...
Is there somewhere an example test showing us plugin developers how to write a test involving the napari GUI?

Any hint is appreciated!

Thanks,
Robert

installation instructions in README

the README does not contain installation instructions

refinements to syntax (feedback requested)

Love the first implementation of this tool!!

I think we have an opportunity to improve the syntax of the tool with two key changes:

1. give plugin developers more fine-grained control over the functionality
2. anticipating that this tool may expand its functionality in the future beyond just plugin validation by "bucketing" functionality

As a first pass at a proposal...

plugin validation

all functionality related to validating a plugin would be contained under npd validate

• npd validate --help would display help on validating plugins
• npd validate alone would EITHER display "help" OR run all validation checks with sensible defaults

plugin validation: packages

• npd validate -p/--package=<target> would perform package-level validation of a specific target file (a filepath or URL to a source distribution or wheel).
• npd validate -p/--package If no target is defined, it would default to validating all package assets found in dist/ (that is, the current functionality of npd --validate-package)

plugin validation: hooks

• npd validate -h/--hook=<specification> would perform validation of a particular hook specification
• npd validate -h/--hook If no target is defined, it would perform validation on all hook implementations that the CLI tool is aware of (current functionality of npd --validate-functions would become npd validate --hook=napari_experimental_provide_function)

display help

npd or npd --help

• shows help for the npd command line tool (see #6)

Thoughts? @tlambert03? @sofroniewn? @ziyangczi ?

UXR findings

suggestions findings from UXR sessions:
1: having one validation command to run instead of specifics at the very high level
2: build packages for people
3: when run validate commands, include package name both including-only and -e filter
4: have an explicit checklist on failure scenarios

archive?

should we archive this repo?

`npd` alone doesn't give the user any feedback

Once I installed the tool, I ran npd at the command line expecting to see some guidance on usage, but it just stopped without any useful guidance (except for a warning about Qt versions).

What happened

(base) √ ~ % npd
/Users/justin.kiggins/opt/anaconda3/lib/python3.8/site-packages/napari/_qt/__init__.py:37: UserWarning: 
    napari was tested with QT library `>=5.12.3`.
    The version installed is 5.9.7. Please report any issues with this
    specific QT version at https://github.com/Napari/napari/issues.
    
  warn(message=warn_message)

What I expected

Some guidance on usage, similar to npd --help