ibid.plugins
– Plugin registration¶
Plugins are added to Ibid by placing a module inside ibid.plugins
.
To do anything, the plugin must contain classes extending
Processor
.
-
class
ibid.plugins.
Processor
¶ Base class for Ibid plugins. Processors receive
Events
and (optionally) do things with them. Plugins extend Processor to implement features. Each Processor occupies a single slot in the event processing queue, and can request specific types of events through the class attributes.The Processor doesn’t need to be instantiated, Ibid discovers all Processors defined in a plugin at load time.
-
usage
¶ String: each line should be a BNF description of a function in the Processor. Leading and trailing whitespace in each line is ignored, as are empty lines.
Default:
None
-
features
¶ List: Strings naming each feature that this Processor is part of. Used in locating “usage” strings for on-line documentation.
The “description” string located inside a module-level features dict maps feature names to help strings.
Default: empty
-
permission
¶ String: The name of the permission that
authorise()
methods in this Processor require.Default:
None
-
permissions
¶ List of Strings: The names of permissions that
authorise()
methods in this Processor check directly (usingauth_responses()
).Default: empty
-
event_types
¶ A tuple of
Event
type strings that the Processor wishes to receive.Default is only messages:
('message',)
-
addressed
¶ Boolean flag: Whether to only receive events where the bot is addressed (i.e. private chat or addressed in a channel).
Default:
True
-
processed
¶ Boolean flag: Whether to receive events that are already marked as having been processed.
Default:
False
-
priority
¶ Integer: The weight of a Processor. Negative numbers put a Processor earlier in the queue, positive later.
Values in the range of -1000 to 1900 are sane, but outside of those, events will not behave normally, as pre-processing occurs between -2000 and -1000 and logging happens at 1900.
Default: 0 unless
processed
isTrue
, then 1500
-
autoload
¶ Boolean flag: Whether to load the plugin or not.
Default:
True
-
setup
(self)¶ Runs once on startup and on every configuration reload. Use it for setting up your Processor.
If you implement it, call
super()
.
-
shutdown
(self)¶ Runs once on shutdown. Use it for cleaning up.
-
process
(self, event)¶ This is the core of a Processor, where events get dispatched.
event is the
ibid.event.Event
to process.
-
Decorators¶
-
ibid.plugins.
handler
()¶ Decorator that makes a method receive all events.
First parameter to the wrapped method will be the event object:
@handler def handle(self, event): event.addresponse(u'Did you see that? I handled an event')
-
ibid.plugins.
match
(regex, version='clean', simple=True)¶ Decorator that makes a method receive message events matching regular expression string regex.
The regex will be matched, with
re.I
,re.UNICODE
andre.DOTALL
modes. You should anchor both sides of it. If simple is true (default), the regex will be modified to match the whole string (^
and$
are added), a space in the regex will match any sequence of whitespace, and the following shortcuts are available for common regex fragments (which are captured as arguments):Selector expands to {alpha}
[a-zA-Z]+
{any}
.+
{chunk}
\S+
{digits}
\d+
{number}
\d*\.?\d+
{url}
url_regex()
{word}
\w+
Using simple regexes where they are applicable can make them much more readable.
Any match groups or selectors in the regex will be passed as parameters to the decorated method, after the event object:
@match(r'(?:foo|bar) {chunk}') def foo(self, event, parameter): event.addresponse(u'Foo: %s', parameter)
The above match is equivalent to this non-simple version:
@match(r'^(?:foo|bar)\s+(\S+)$', simple=False)
Optionally you can specify keyword arguments, which will get passed on to the function. The syntax is
{keyword:selector}
, where the keywords will get passed onto the decorated method:@match(r'I am {nick:chunk} on {network:chunk}') def register(self, event, network, nick): pass
The above match is equivalent to this non-simple version:
@match(r'^I\s+am\s+(?P<nick>\S+)\s+on\s+(?P<network>\S+)$', simple=False)
Note that you cannot mix positional and keyword arguments. All your selectors must either be named, or all be unnamed.
version can be set to one of:
'clean'
- The default, and almost always what you want. The bot name and intervening punctuation are removed from the front of the message, if the bot was addressed. Trailing punctuation and surrounding whitespace is stripped.
'raw'
- The message as the bot saw it.
'deaddressed'
- The bot name and intervening punctuation are removed from the front of the message, if the bot was addressed.
'stripped'
- Trailing punctuation and surrounding whitespace is stripped.
De-address Don’t de-address Strip 'clean'
'stripped'
Don’t strip 'deaddressed'
'raw'
Decorator that requires
Processor.permission
for the user that would trigger this method.fallthrough sets the failure mode. If
True
, the next Procesor will be called in the hope of finding another one that’ll handle it. If one is never found or fallthrough isFalse
, an error message will be returned byibid.plugins.core.Complain
:permission = 'awesome' @authorise() @match(r'^do\s+awesome\s+things$') def method(self, event): event.addresponse(u'Yes sir, you are awesome!')
-
ibid.plugins.
periodic
([interval=0, config_key=None, initial_delay=60])¶ Decorator that runs the method every interval seconds, from timer events. The method won’t be called until initial_delay seconds have passed since startup.
If config_key is set to a string, the
IntOption
of that name will be used to setinterval
. This is done inProcessor.setup()
so if you override that, be sure to call super.
Other Functions¶
-
ibid.plugins.
auth_responses
(event, permission)¶ If the event sender has the permission permission, return
True
.If not, the event will be marked as having failed authorisation. If no other Processor processes the event, an error message will be returned by
ibid.plugins.core.Complain
.This is used internally by
@authorise()
, but you can call it directly if you need more complex permission handling than@authorise()
allows for.When you use this, you should ensure that permission is listed in
Processor.permission
orProcessor.permissions
.
RPC¶
-
class
ibid.plugins.
RPC
¶ All methods named with the prefix
remote_
will be exposed via Ibid’s various RPC mechanisms (including the web interface).It is common to extend both
Processor
and RPC in the same class. The handlers can then wrap around theremote_
methods, to provide the same features over IM and RPC.Note
The RPC code is still experimental and not widely used. Don’t be surprised if it doesn’t work.