Framework 2.7

Release Status: In Staging, Estimated Release: 2015-08-16/17

Related Pull Request: https://github.com/hangoutsbot/hangoutsbot/pull/300

This page summarises the most important changes that are implemented in Framework 2.7. For further information, please refer to the related pull request.

Table of Contents Bot Administrators Core Commands Access Control with Tags Bot will Auto-create Private Channels Faster and More Responsive Sinks Dynamically Load/Unload Plugins Plugins and Sinks Enhancements Developers Deprecation Notices System Plugins Testing Tools Usage of Python Logging Facilities Users and Conversations Tagging Single-threaded Parallelism Long-running asyncio.task aiohttp.web-based Sinks HTML Response via API Plugin Documentation

Bot Administrators

Core Commands

Bots always come 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
• 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 Notices

• 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:
  • bot.external_send_message(), bot.external_send_message_parsed() - replace with bot.coro_send_message()
  • bot.send_html_to_user() - replace with bot.coro_send_to_user()
  • send_html_to_user_or_conversation - replace with combination of bot.coro_send_message() and bot.coro_send_to_user()
• 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.

System Plugins

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

Testing Tools

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.

Usage of Python Logging Facilities

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
  • As shown in the linked code, sinks configured via config["jsonrpc"] will be loaded differently based on which class the request handler is inherited from.
• 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.
• Other updates and examples:
  • Slack - code diff
  • API - code diff
  • Google Script Sink - code diff
  • The webbridge library - code diff

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.