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

Recommended release procedure

Initial release

For your first release of Orange add-on:

1. make sure code is ready
2. make sure your documentation is ready, that index explains what add-on is and does and how can be installed and used
3. compare your setup.py with one of Biolab's add-ons (like bioinformatics add-on)
   1. make sure entry points (hooks) are defined properly
   2. package must have keyword orange add-on for it to be displayed on add-ons list
4. prepare README.rst file which should be included in setup.py as long description of the package – this will be used on the list of add-ons, it is useful that there is some link to documentation in there
5. commit everything
6. increase version in setup.py (commit message is often just Version bump.)
7. commit
8. tag the commit with (hg tag <version string>)
9. push to Bitbucket
10. register on ReadTheDocs and import your new Python pacage
    1. for tags use also orange and data mining
11. on Bitbucket enable service integration with ReadTheDocs for your package repository, so that every time you push to the repository, documentation will be rebuilt
12. publish package on PyPi (you will be prompted to register an account, if you do not have one)
    1. python setup.py register
    2. python setup.py sdist upload
    3. python2.6 setup.py bdist_egg upload
    4. python2.7 setup.py bdist_egg upload
13. In around one hour it should be visible on add-ons list.

Subsequent releases

When a new release is ready:

1. increase version in setup.py (commit message is often just Version bump.)
2. commit
3. tag the commit with (hg tag <version string>)
4. push to Bitbucket
5. python setup.py register
6. python setup.py sdist upload
7. python2.6 setup.py bdist_egg upload
8. python2.7 setup.py bdist_egg upload