flaschengeist/docs/plugin_development.md

Plugin Development

File Structure

- your_plugin/
    - __init__.py
    - ...
    - migrations/ (optional)
        - ...
- setup.cfg

The basic layout of a plugin is quite simple, you will only need the setup.cfg or setup.py and the package containing your plugin code, at lease a __init__.py file with your Plugin class.

If you use custom database tables you need to provide a migrations directory within your package, see next section.

Database Tables / Migrations

To allow upgrades of installed plugins, the database is versioned and handled through Alembic migrations. Each plugin, which uses custom database tables, is represented as an other base. So you could simply follow the Alembic tutorial on how to work with multiple bases.

A quick overview on how to work with migrations for your plugin:

$ flaschengeist db revision -m "Create my super plugin" \
  --head=base --branch-label=myplugin_name --version-path=your/plugin/migrations

This would add a new base named myplugin_name, which should be the same as the pypi name of you plugin. If your tables depend on an other plugin or a specific base version you could of cause add

--depends-on=VERSION

or

--depends-on=other_plugin

Plugin Removal and Database Tables

As generic downgrades are most often hard to write, your plugin is not required to provide such functionallity. For Flaschengeist only instable versions provide meaningful downgrade migrations down to the latest stable version.

So this means if you do not provide downgrades you must at lease provide a series of migrations toward removal of the database tables in case the users wants to delete the plugin.

(base) ----> 1.0 <----> 1.1 <----> 1.2
              |         
              --> removal

After the removal step the database is stamped to to "remove" your

Useful Hooks

There are some predefined hooks, which might get handy for you.

For more information, please refer to

• flaschengeist.utils.hook.HookBefore and
• flaschengeist.utils.hook.HookAfter