kaylee/kayleevc/plugins/__init__.py

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


class PluginBase():
    """Base class for Kaylee plugins

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

    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 get_handler(self, text):
        """Return a handler for the given text

        This method returns a Handler object which handles the command when
        called.  If the plugin does not recognize the command at all, this
        method must return None instead.  The method must also return None 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.
        """
        return None


class Handler:
    """Base class for Kaylee plugin handlers

    Plugins should subclass this for their own command handlers.
    """

    def __init__(self, confidence):
        """Initialize the handler

        The confidence with which this handler will handle the command must be
        passed as ``confidence``, a floating-point number in (0, 1].  A
        confidence of 1 indicates that the handler is definitely supposed to
        handle the command it was created for.  Values between 0 and 1 may be
        used to indicate that the plugin may be able to handle the command,
        but it was misunderstood by the speech recognition system.
        """
        self.confidence = confidence

    def __call__(self, tts):
        """Handle the command

        When called, ``tts`` is a function which takes a string as its only
        parameter and passes it to Kaylee's configured text-to-speech system.
        """