kaylee/kayleevc/plugins/pluginbase.py

# This is part of Kaylee
# -- this code is licensed GPLv3
# Copyright 2015-2017 Clayton G. Hobbs
# Portions Copyright 2013 Jezra

from gi.repository import GObject


class PluginBase(GObject.Object):
    """Base class for Kaylee plugins

    Each Kaylee plugin module must define a subclass of this class, named
    ``Plugin``.
    """

    __gsignals__ = {
        'tts' : (GObject.SIGNAL_RUN_LAST, GObject.TYPE_NONE,
                (GObject.TYPE_STRING,))
    }

    def __init__(self, config, name):
        """Initialize the plugin

        All strings to be included in the corpus should be elements of
        ``corpus_strings`` by the end of __init__'s execution.  Note however
        that the words required for number support are automatically included,
        so they need not be listed explicitly on a per-plugin basis.
        """
        super().__init__()
        self.config = config
        self.name = name
        self.options = config.plugins[name]
        self.corpus_strings = set()

    def confidence(self, text):
        """Return the confidence (0-1) with which this plugin can handle text

        This method must return 1 if the command is definitely supposed to be
        handled by this plugin (text is exactly a sentence configured to
        perform some action) and must return 0 if the command is not recognized
        at all.  The method must also return 0 if the command is recognized,
        but for some reason would not perform any action currently, e.g. "pause
        music" when no music player is running.  Intermediate values may be
        used to indicate that text may be a command this plugin should handle,
        but was misunderstood by the speech recognition system.
        """
        return 0

    def handle(self, text):
        """Process a recognized voice command

        This method must return True if the command was handled by the plugin,
        and False otherwise.  If the plugin wants to speak some words to the
        user, it can do so by emitting a ``tts`` signal with the words to be
        spoken as its parameter.
        """
        return False