Extending spreads

Setting up a development environment

The easiest way to work on spreads is to install it to an editable virtual Python environment using the virtualenv tool and installing spreads into it using pip with the -e option. This option allows the virtual environment to treat a spreads repository checked out from git as a live installation.

For example, on a Debian-based system, assuming the git repository for spreads is checked out to ./spreads:

virtualenv spreadsenv
cd spreadsenv
source ./bin/activate
# The following dependencies are not pulled in automatically by
# setuptools
pip install cffi
pip install jpegtran-cffi
pip install -e ../spreads

Other prerequisite packages you may require include:

libffi-dev libjpeg8-dev libturbojpeg

Adding support for new devices

To support new devices, you have to subclass DevicePlugin in your module and add it as an entry point for the spreadsplug.devices namespace to your package’s setup.py. In it, you override and implement the features supported by your device. Take a look at the plugin for CHDK-based cameras and the relevant part of spreads’ setup.py for a reference implementation.

Devices have to implement a yield_devices<spreads.plugin.DevicePlugin.yield_devices> method that scans the system for supported devices and returns fully instantiated device objects for those.

Declaring available configuration options for plugins

Device drivers (as well as all plugins) can implement the configuration_templates<spreads.plugin.SpreadsPlugin.configuration_template> method that returns a dictionary of setting keys and PluginOption<spreads.plugin.PluginOption> objects. These options will be visible across all supported interfaces and also be read from the configuration file and command-line arguments.

Extending spreads built-in commands

You can extend all of spread’s built-in commands with your own code. To do, you just have to inherit from the HookPlugin class and one of the available mixin classes (at the moment these are CaptureHooksMixin<spreads.plugin.CaptureHooksMixin>, TriggerHooksMixin<spreads.plugin.TriggerHooksMixin>, ProcessHookMixin<spreads.plugin.ProcessHookMixin>, OutputHookMixin<spreads.plugin.OutputHookMixin>). You then have to implement each of the required methods for the mixins of your choice.

Furthermore, you have to add an entry point for that class in the spreadsplug.hooks namespace in your package’s setup.py file. For a list of available hooks and their options, refer to the API documentation. Example implementations can be found on GitHub

See also

module spreads.plugin, module spreads.util

Adding new commands

You can also add entirely new commands to the application. Simply subclass HookPlugin and SubcommandHookMixin<spreads.plugin.SubcommandHookMixin>, implement the add_command_parser classmethod and add your new class as an entry point to the spreadsplug.hooks namespace. See the web and gui plugins for examples of plugins that add custom subcommands.