#18 Revise plugin API

As it stands, the plugin API is a bit primitive. Many plugins have to do some work twice: first to determine if they can handle a command, then again if they actually get to handle it. For example, the shell plugin parses numbers from the voice command twice, then checks whether the command was matched with or without numbers twice. A better API would only require this to be done once.

Also, when a plugin determines that it can handle a command, then while handling it finds that it is unable to do so, an exception should be raised rather than the handler function returning False. This is after all an exceptional scenario (for example, a media player was closed between command matching and handling, a very short span of time).

To this end, I propose a new plugin API which will solve these problems. The confidence method will be replaced with a new method, get_handler, which still only takes the text as a parameter. This new method returns a handler object (which should be an instance of a subclass of the new Handler class). This object can be compared based on its confidence attribute; and can be called with no parameters, which must handle the sentence or raise an exception. The old handle method of the plugin is thus no longer required and will be removed. Handlers may take extra parameters to their __init__ methods of course, which allows e.g. the shell plugin to only parse numbers once.

If Plugin.get_handler is absolutely certain that it cannot handle a given command, it should return None instead of a handler object. This is equivalent to returning 0 in the old API.

This new API requires changes to the handling of built-in TTS functionality. Before this it was handled by a GObject signal emitted by the Plugin object and handled by the Kaylee object. This new architecture would require moving the signal to the Handler class and connecting the signal each time we handle a command. This sounds cumbersome. Further, I’m unsure why I’m using a GObject signal for this when a plain old Python function call could be used instead.

Considering these points, I’ve decided that Handler.__call__ should take a text-to-speech function as its parameter. This has the benefit of making it harder for plugins to speak when not handling a command.

In the first comment for this issue, I said that plugins should raise exceptions if they can’t handle a command they said they could. I realize that this exception must be a particular one to ensure that other exceptions raised by Handlers are not silenced. This new exception will be called kayleevc.plugins.HandlerFailure.

Fully implemented and ported as of 654d386e45.