Skip to content

Framework 2.7

Jump to bottom Edit New page
Innocent Bystander edited this page Aug 27, 2015 · 71 revisions

Releases:

This page summarises the most important changes that are implemented in Framework 2.7. Further technical information is always available in the linked pull requests.

Table of Contents

Bot Administrators

Core Commands

Bots always load with a default set of Core Commands

Access Control with Tags

Access to specific commands can be granted and removed via the conversations and users tagging functions. A much more detailed explanation of this feature is available at Access Control with Tags

Bot will Auto-create Private Channels

config["autocreate-1to1" has been changed from default off to default on. Plugins (e.g. mentions, subscribe) and some commands (e.g. /bot help) that rely on creating private chat channels will now ```automatically create new hangouts``` when required. Users can always /bot optout (as usual) or you can configure the bot to its older behaviour by setting "autocreate-1to1": false in config.json

Faster and More Responsive Sinks

  • Slack plugin upgraded to use new sinks, featuring near-real-time message exchange - does not require reconfiguration
  • API plugin upgraded to use new sinks and support return of command output /bot ping, /bot convfilter and /bot convusers directly from the web request - does not require reconfiguration
  • Google Scripts sink upgraded to use new sinks - does not require reconfiguration
  • Github Push Listener upgraded to use new sinks - does not require reconfiguration
  • GitLab Push Listener upgraded to use new sinks - does not require reconfiguration
  • The sinks.generic.SimpleMessagePoster sink is now superseded by the faster and more flexible sinks.generic.AsyncMessagePoster - this a drop-in replacement for any configured sink module in config["jsonrpc"]. Essentially, just copy and replace the text in your config.json and restart the bot.
    The older sinks.generic.SimpleMessagePoster will continue to work but will no longer be officially supported

Dynamically Load/Unload Plugins

Plugin Control Commands - experimental commands to temporarily load and unload plugins without the need for a bot restart.

  • These commands do not change your config["plugins"] configuration, and thus any changes will not be reflected at the next bot restart - this may change in future versions.
  • As of 2.7, all first-party plugins have been upgraded to use the new aiohttp.web-based sinks and asyncio.tasks features - this makes all the base plugins compatible with plugin control commands.
  • Custom third-party plugins that uses the threaded model are incompatible with plugin control commands and cannot be unloaded/reloaded - this is due to platform limitations. Please notify the plugin developer if you would like to have them implement support for these functions.

Plugins and Sinks Enhancements

Please see the Plugins and Sinks section on the linked pull request.

Developers

Deprecation and Planned Obsolescence

  • No functions or features are obsoleted for this release
  • The following Message Sending functions are soft-deprecated and will raise [DEPRECATED] DEBUG notices in the log if they are used:
    • bot.send_message_parsed(), bot.send_message_segments(), bot.send_html_to_conversation() - replace with bot.coro_send_message()
  • The following Message Sending functions are hard-deprecated and will raise [DEPRECATED] WARNINGS in the logger and on console if they are used:
  • The Pre-2.4 Plugin Pattern is hard-deprecated and continued usage will raise [DEPRECATED] WARNINGS in the logger and on console if they are used
    • PLUGIN DEVELOPERS: Please migrate plugins that are older than the 2.4 pattern.

2.7.2 and above

Retrieving Hangups Conversation

bot.get_hangups_conversation() has been implemented as a complementary function to bot.get_hangups_user()

This change enhances the output of bot.list_conversations(), which is no longer subject to the hangups protocol limitation of returning only 35 most recent conversations.

Unknown/Blocked Command Responses

To facilitate greater customisation of the bot response to unknown/blocked commands, the decorators @command.register_unknown and @command.register_blocked can be used to register alternate commands to handle the default responses.

The default responses are registered via the commands.basic module for unknown commands and blocked commands

To override the defaults, use these decorators in a plugin - note: these default responses are not subject to de-registration even if the original plugin is unloaded/reloaded.

2.7 and above

Plugins

System Plugins

Core Commands are implemented via the same functionality as standard plugins. Permamem and Tagging are now an integral part of the framework.

Controlled Shutdown

During bot exit/disconnection, the bot will attempt to unload all plugins sequentially - this includes de-registering commands, handlers, shared objects and cancelling running asyncio-related tasks.

Unittests and Examples

All unittest_* and example_* plugins are deactivated by default.

Testing Tools

Framework 2.7 contains several enhancements suitable for plugin and framework developers.

Runtime Control of Plugins

The introduction of Plugin Control Commands allows developers to dynamically load and unload plugins while the bot is running. This can be used to test plugins without having to restart the bot.

Customisable Python Logging

You can override the default python logging handlers by specifying a customised logging configuration dictionary in config["logging.system"].

A working example is provided in this comment on the original pull request.

Redirection of Logs to Chat

In an effort to reduce the usage of the print command, plugins have been standardised to rely on the internal python logging facilities, which offers a consistently-formatted output that can be further modified by the use of log handlers and filters. This is demonstrated in the Logger to Chat Message feature that allows log messages from specific modules to be sent to Hangouts conversations as a message.

Users and Conversations Tagging

The new framework officially introduces the functionality and commands for Users and Conversations Tagging

Single-threaded Parallelism

The new framework introduces more asyncio-friendly mechanisms for implementing web listeners and scheduled tasks.

Long-running asyncio.task
  • A long-running function can be decorated with @asyncio.coroutine and supplied to plugins.register_asyncio_task(coroutine_function, [<extra arguments>]) - a reference to bot is always the first argument passed to the coroutine.
  • The latest source code for the BotAlive plugin can used as a reference for implementing this feature - this plugin previously used threads, so it can also serve as an upgrade guide.
aiohttp.web-based Sinks
  • Previously, BaseBotRequestHandler was the de-facto standard class to inherit from to implement a sink. It relied on a threaded web-server model to implement http listeners to receive incoming request. The interaction between the asyncio event loop and threads made this a slow (1-2 seconds) process per request. This is resolved via the drop-in replacement AsyncRequestHandler which runs in the same event loop as the bot, making request processing much more responsive.
  • The calling convention differs slightly, whereas old request handlers based on BaseBotRequestHandler relied on the threadmanager and start_listening, a customised request handler class that inherits from AsyncRequestHandler simply needs to be passed to aiohttp_start
  • AsyncMessagePoster is a drop-in replacement for bots running SimpleMessagePoster via config["jsonrpc"]. In 2.7, it is now the default sample sink as well in the base config.json.
  • Related updates (which can also be used as examples):

HTML Response via API Plugin

The new API plugin supports the return of a custom html-formatted response from commands that support it. The command must return a suitable response to be sent to the remote client. As shown in this code diff, add the line after the command completes: 

return { "api.response" : "<content>" }

Documentation

Some pages on the wiki has been renamed, and/or converted into MediaWiki format (which has auto-generated TOCs). please refer to the Documentation section on the linked pull request.

Plugin List | Developer Reference: [ Intro | Plugins | Sinks | In-built Functionality | [Configuration] (Configuration) ]

# ## ###

Clone this wiki locally