Initial Setup

To create a Plover plugin, first create a Python package with the following directory structure:

plover-my-plugin/
 |-- setup.cfg
 '-- setup.py

setup.py:

#!/usr/bin/env python3

from setuptools import setup

setup()

setup.cfg:

[metadata]
name = plover-my-plugin
keywords = plover plover_plugin

[options]
zip_safe = True
setup_requires =
  setuptools>=30.3.0
install_requires =
  plover>=4.0.0.dev10
packages =
  ...  # Your packages go here
py_modules =
  ...  # Your modules go here

[options.entry_points]
...  # Your plugin components go here

Directory Structure

In terms of the actual plugin code, there are two main options to organize it, a package-based approach and a module-based approach. Some plugins may choose to use a mix of both depending on the complexity.

Package-based Structure

To organize the plugin in a package-based structure, we put all plugin code inside a Python package, which is just a directory with an __init__.py file.

plover-my-plugin/
 |-- plover_my_plugin/
 |    '-- __init__.py
 '-- plover_my_plugin_2/
      '-- __init__.py

For each directory you create under the plugin directory, add an entry to packages in the [options] section of the config file:

[options]
...
packages =
  plover_my_plugin
  plover_my_plugin_2
  ...  # Other packages go here

The advantage of using a package approach is that you can keep all of your plugin code in the same directory for a more complex plugin, but if your plugin is really simple and only needs one module this might be overkill, and in that case it would be better to use the module-based structure:

Module-based Structure

To organize the plugin in a module-based structure, your plugin code can go directly in the plugin directory:

plover-my-plugin/
 '-- my_plugin.py

For each file you add under the plugin directory, add an entry to py_modules in the [options] section of the config file:

[options]
...
py_modules =
  my_plugin
  ...  # Other modules go here

This works best for very simple plugins since there isn’t much of a need for a file hierarchy. However, module names are global, so avoid naming files with common names like util as they may conflict with other Python packages.

Entry Points

The [options.entry_points] section at the bottom of setup.cfg is where you will add entry points for each plugin item you want to add. Each entry point should refer to a certain module, function or class, depending on the plugin type.

The different types of entry points are:

plover.command

Command plugins.

plover.dictionary

Dictionary format plugins.

plover.extension

Extension plugins.

plover.gui.qt.tool

GUI tool plugins. Plugins of this type are only available when the Qt GUI is used.

plover.machine

Machine plugins.

plover.gui.qt.machine_option

Machine configuration GUI widgets. Machine plugins that require configuration in addition to the default keyboard or serial options should have this entry point.

plover.macro

Macro plugins.

plover.meta

Meta plugins.

plover.system

System plugins.

For example, the code below creates a dictionary entry point named custom, and two commands named foo_start and foo_stop:

[options.entry_points]
plover.dictionary =
  custom = plover_my_plugin.dictionary:CustomDictionary
plover.command =
  foo_start = plover_my_plugin.foo_cmd:foo_start
  foo_stop = plover_my_plugin.foo_cmd:foo_stop

Installation

To install your plugin for development, use the command-line plugin installer:

cd plover-my-plugin
plover -s plover_plugins install -e .

Make sure to use the -e flag to mark this package as editable. This allows you to make changes to the plugin code without uninstalling and reinstalling the plugin.

Note

If you make any changes to setup.cfg during development, you will still need to uninstall and reinstall the plugin.