wiki:AddOns

Version 12 (modified by mitar, 2 years ago) (diff)

Add-ons

Structure

Add-on is a  Python package. The structure of an add-ons repository is as follows, package name being a name of a directory of the add-on's Python package, often lowercased addonname:

orange-addonname/
    COPYING
    LICENSE
    setup.py
    docs/
        Makefile
        rst/
            conf.py
            index.rst
    _packagename/
        datasets/
        widgets/
            __init__.py
            ...
        __init__.py
        ...
    src/

docs contains reST documentation of the add-on. src possible contains C/C++ source code. datasets any additional datasets add-on might use.

Package name starts with _ to signify it is for internal use only. Add-ons register through setuptools' entry points (hooks) into Orange namespace. Use relative imports to access other modules inside the package, if possible.

setup.py, Makefile, and conf.py as prepared in Biolab's add-ons can be used to get a good starting point for a new add-on.

Entry points (hooks)

The following  entry points are defined and used by Orange:

orange.addons
Entry point to register add-on into Orange namespace.
orange.widgets
Entry point to add add-on's widgets to Orange canvas.
orange.data.io.search_paths
Entry point to add add-on's datasets' directory to search path for loading datasets.

Example:

ENTRY_POINTS = {
    'orange.addons': (
        'foobar = _packagename',
    ),
    'orange.widgets': (
        'Foobar = _packagename.widgets',
    ),
    'orange.data.io.search_paths': (
        'packagename = _packagename:datasets',
    ),
}

These entry points will inject add-on under Orange.foobar namespace. So _packagename.baz will be accessible as Orange.foobar.baz.

Widgets will be available under category named Foobar.

And function datasets will be called to retrieve additional search paths.

For example, accordingly to above entry point definition, it could be defined (or just exposed) in _packagename/__init__.py as:

import pkg_resources

def datasets():
    yield ('foobar', pkg_resources.resource_filename(__name__, 'datasets'))

This would add datasets in _packagename/datasets/ to the search path, with prefix foobar. So:

data = Orange.data.Table("foobar:baz.tab")

would load _packagename/datasets/baz.tab file.

Distribution

Add-ons should be distributed through  PyPi. If done so (and keyword orange add-on is used for the package), they will be displayed among available add-ons on Orange webpage.

Care should be taken that add-ons work also as Python eggs. They should be uploaded for Python 2.6 and 2.7 to PyPi (along the add-on's source package) for add-on to be available for install through Orange Canvas.

Installation

Installation using pip is recommended and should be supported by an add-on. Other way of installing is simply by putting add-on's Python egg into user's add-ons dir (add-ons subdirectory of Orange homedir).