Plugins

The emtelliPro Python SDK supports plugins based on signals; different parts of the SDK will emit signals, and listen for responses from plugin functions subscribed to the signals.

Examples for subscribing to signals are provided in the examples/plugin directory.

How to design a plugin

There are two important aspects of designing a plugin: discovery, and registration. First, the SDK needs to find the plugin, and then it will register it with the necessary hooks in the SDK (in this case, the hooks will be the signals).

Discovery

For the SDK to find the plugin, it must contain a emtellipro.plugins entry point in its setup.py. For example, in the demo plugin provided in examples/plugin, we have

setup(
    ...,
    entry_points={
        'emtellipro.plugins': 'demo = demo_package',
    },
    ...
)

In this case the plugin package name is demo_package and that is what will be used as the plugin name when the SDK clients are used.

The SDK’s plugin loading code will find all installed packages with an emtellipro.plugins entry point and will load them.

Registration

After discovering the plugins, the SDK will register them so the signal-handling code will know which functions to call when signals are emitted. To do this, the plugin must define a register() function which should attach signal receivers to specific signals, and which may perform any other setup necessary for the plugin.

In the example plugin, we have the following registration function which attaches receivers to the get_result_modifiers and get_text_encryptors signals. The result_receiver and encryptor_receiver functions are defined elsewhere in the plugin.

# in the package's __init__.py
from emtellipro import signals

def register():
    """
    This will be called by ``emtellipro.plugins.enable_plugins()`` to attach
    receivers to signals.
    """
    signals.get_result_modifiers.connect(result_receiver)
    signals.get_text_encryptors.connect(encryptor_receiver)

Available signals

Signals are present in the emtellipro.plugins.signals package, and may be imported from there, or using

from emtellipro import signals

Signals that begin with get_ are used for discovering functions which will be called on a particular data (as described below for each specific signal). Receivers for these signals must return functions which will themselves be used for modifying data; receivers may return a function, a list of functions, or None.

Currently, the available signals are the following

get_result_modifiers

This signal will be emitted as soon as a processing result is received from the emtelliPro API. The receiver of this signal will be given the result format (e.g. 'emtellipro-json-2') as the first argument and must return either None, a function, or a list of functions. If the returned value is not None, the functions returned will be called in order on the result from the API to provide a modified result that will be used for the rest of the processing in the SDK.

The functions modifying the processing result will receive as input a string and must return a string containing data in the same format as the input (i.e. if the data contains JSON, it must return JSON in the same result format).

get_text_encryptors

This signal will be emitted by the database saving code used by the database client to allow encrypting or otherwise modifying text before it is sent to the database. Receivers of this signal will be given a text type, and can return functions which encrypt the given text type.

Options for text type are 'location', 'found_entity', 'document'. If you don’t wish to handle the different types differently, you may ignore the text type provided.

Encryption functions will be provided with a list of strings and must return a list of strings back (the two strings must have the same length). The strings will be the values of multiple texts that will be stored in the appropriate text columns in the database.