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](https://alembic.sqlalchemy.org/en/latest/index.html) 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](https://alembic.sqlalchemy.org/en/latest/branches.html#creating-a-labeled-base-revision).

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`