Creating a Plugin
A Plugin for Scipion is a Python module that have some extra requirements. Each Plugin contains classes for protocols, viewers, wizards, etc…allowing to use the functionality of a given EM package within the Scipion framework. Prior to version XXX, the plugins code was not completely isolated, it was under the scipion/pyworkflow/em/packages folder and hosted in the same central repository.
For the release XXX ("the pluginization"), we worked hard to make the entire system more de-centralized and more standard. For that we re-factored the plugins to make them standard Python modules and host their code in independent repositories and with the possibility different release cycles.
This document is organized in two main parts: (1) Explanation of the structure of a plugin as a Python module and the required submodules and functionality for Scipion. (2) Necessary files structure and the process for distributing a Plugin in the Python de-facto repository PyPI.
Similar to style guides, conventions are about consistency. Consistency is crucial for a project such as Scipion and its distributed nature. Despite the final decision is up to the developer of a package, we STRONGLY recommend the following conventions:
-
Repository name: scipion-em-packagename
-
Python package name: scipion-em-packagename
-
Python module with package code: packagename
This means that it will be a folder named scipion-em-package with the structure of a standard Python package (explained below in the second part) and it will contains a folder package that is a Python module with functions and classes required by Scipion (explained below).
The files and folders structure follows the convention established for Python modules. For example, the Relion plugin has the following structure:
$ cd ~/work/development/scipion-em-plugins/scipion-em-relion
$ tree
.
├── LICENSE
└── relion
├── __init__.py
├── bibtex.py
├── constants.py
├── convert
│ ├── __init__.py
│ ├── convert.py
│ └── dataimport.py
├── protocols
│ ├── __init__.py
│ ├── protocol_autopick.py
│ ├── protocol_autopick_v2.py
│ ├── protocol_base.py
│ ├── protocol_center_averages.py
│ ├── protocol_classify2d.py
│ ├── protocol_classify3d.py
│ ├── protocol_create_mask3d.py
│ ├── ...
├── tests
│ ├── __init__.py
│ ├── test_convert_relion.py
│ ├── test_protocols_relion.py
│ └── test_workflow_relion.py
├── viewers.py
└── wizards.py
Scipion plugins are usually composed by the following submodules:
-
__init__.py: This file is required in Python modules and it is executed when the module is imported. Additionally, a Plugin class should be defined (subclass from pyworkflow.em.Plugin) and it should be registered in the Domain to define this module as a Scipion plugin. -
protocols: In this submodule all the protocols of the plugin should be implemented. Usually a plugin provides many protocols, so the most common case is to have a submodule folder with its own
__init__.pyand one .py file per each protocol class. -
viewers: A plugin can also define viewers for existing objects or new protocols. Since many built-in viewers are provided by Scipion, plugins do not define many viewers, so a viewers.py will serve as submodule.
-
wizards: Wizards need to be defined for protocols/parameters, but many base classes are already provided. Here again the
wizards.pysubmodule is usually enough. -
tests: We strongly recommend to follow Test-Driven-Development, so this is the place where all plugin tests should go. It is important to create different test cases from the beginning of the plugin development.
-
bibtex.py: This submodule is not supposed to be imported directly, it should contain the bibtex string literal as the Python doc string. Scipion will take care of parse the bibtex reference and incorporate into the plugin module.
-
logo.png