Plugins

You can easily extends python-droit using plugins. They define custom input and output sub-rules. If you don't know what a rule or sub-rule is I recommend to read How to create Droit Databases first. Here is a summary extracted from this article:

Droit XML and Droit Database Script are Droit Databases. They contain a list of "rules". Each rule has input sub-rules and output sub-rules. The input sub-rules determine what user-inputs the rule fits to. If a user-input fits to the input sub-rules the rule will be selected by python-droit. Usually the best fitting rule will be use for the output. Therefore the output sub-rules of this rule will be evaluated.

Example rule:

• rule
  • input sub-rules
    • If the user-input contains "i"
    • If the user-input contains "am"
    • And there is a another word which has to be read in as variable "name"
  • output sub-rules
    • return the text "hi "
    • and append the variable "name"

What's the job of a plugin?

Sub-rules are evaluated by plugins. [Some standard plugins] are always included in the python-droit plugin folder. As you can write your own plugins or download plugins other people made you are able to [extend the sub-rules]. The name of the folder a plugin is located in specifies the name of the input sub-rule respectively the name of the output plugin.

Where are plugins located?

Usually plugins are located within the droit/plugins/input or droit/plugins/output folder. The folder structure looks like this:

plugins
----- input
----- ----- text
----- ----- ----- main.py
----- ----- srtx
----- ----- ----- main.py
----- ----- inp
----- ----- ----- main.py
----- output
----- ----- math
----- ----- ----- main.py

However you can load plugins from a plugins folder that isn't located within the droit folder by loading them using droit.tools.loadPlugins(location='path/to/plugins/folder/') (view docs) and add them to a DroitResourcePackage which has to be passed to useRules() and formatOut() using the rpack parameter.

Any folder containing plugins must be called plugins and contain the sub-folders input and output. Each plugin has it's own folder which defines the plugins name. Each plugin folder has to contain a file called main.py.

If you want to view some example plugins just have a look at the standard plugins that are already included with python-droit.

Writing an input plugin

Let's have a look at the SRTX input plugin. The SRTX sub-rule checks whether one of the given values is equal to the user-input.

# main.py - plugins.input - SRTX plugin for python-droit

def block(userinput, inputRules, block, rpack):
	passRule = False
	variables = []
	rankMod = 0

	if(len(inputRules) == 1 and inputRules[0].tag == block):
		if(userinput.rawInput in inputRules[0].children):
			passRule = True
	
	return passRule, variables, rankMod

When running an input sub-rule the function block() from main.py at plugins/input/nameofsubrule will be called. The function block always takes four parameter:

• userinput (a DroitUserinput object)
• inputRules (a list of DroitRuleInOut input rules)
• block (the name of this block)
• rpack (a DroitResourcePackage object)

How does this plugin work?
At first there is an if-statement which checks whether there is only one input sub-rule in the current rule and whether this sub-rule is SRTX. In the second if-statement it checks whether the raw user-input is included in the values of the sub-rule. If so the variable passRule is set to True.

passRule is a boolean variable and the first one of the tuple of three variables to be returned by the block() function. When it is set to True it tells Droit that the condition of this sub-rules is met. If the sub-rule is used more than one time in a rule the function block() has to check whether the condition of every sub-rule of it's type is met. To do so you can use a loop scanning each item of inputRules.

variables is a list of variables that were read in by the sub-rule. The INP sub-rule e.g. uses it. In this example an empty list is returned.

rankMod specifies how relevant the plugin is. Usually it is set to zero. The higher rankMod is the more likely a rule is to be used for output.

Writing an output plugin

Output plugins work different due to the fact that their task is different. While input plugins check whether the user-input meets some conditions the output plugins produce some kind of output. This can be anything from returning some text to sending an email. We will now have a look at the rand plugin. It makes it possible to return one of several strings chosen randomly.

# main.py - plugins.output - rand plugin for python-droit
import random

def text(data, rpack):
    rint = random.randint(0, len(data) - 1)
    return data[rint]

Here is an example of how to use this plugin:

SRTX!whats you name->EVAL!rand.text("my name is droit","i'm droit")

Output plugins can contain multiple functions. Any function from main.py can be called using the EVAL sub-rule: EVAL!plugin.function(param1,param2,...)
Any function that can be called like this has the parameters data and rpack and returns a string.
data is a list containing all given parameters. Parameters are either a variable or a string.
rpack is a DroitResourcePackage object.
The string which is returned will be appended to the output string returned by formatOut().