Update docs

This commit is contained in:
dave 2017-07-02 15:24:14 -07:00
parent e9349091bd
commit 6cd8911502
2 changed files with 57 additions and 20 deletions

View File

@ -13,7 +13,7 @@ file's name.
.. code-block:: python .. code-block:: python
from pyircbot.modulebase import ModuleBase, hook from pyircbot.modulebase import ModuleBase, hook, command
class EchoExample(ModuleBase): class EchoExample(ModuleBase):
The class's ``__init__`` method accepts 2 args - a reference to the bot's API The class's ``__init__`` method accepts 2 args - a reference to the bot's API
@ -47,7 +47,7 @@ In order to make your module respond to various IRC commands, pyircbot uses a
system of "hooks", which can be defined using decorators or programmatically. system of "hooks", which can be defined using decorators or programmatically.
Note: in this case, "commands" refers to IRC protocol commands such as PRIVMSG, Note: in this case, "commands" refers to IRC protocol commands such as PRIVMSG,
KICK, JOIN, etc. Pyircbot also provides some meta-events that are accessed in KICK, JOIN, etc. Pyircbot also provides some meta-events that are accessed in
the same way. The complete list of supported commands can be seen in the source the same way. The complete list of supported hooks can be seen in the source
of :py:meth:`pyircbot.irccore.IRCCore.initHooks`. of :py:meth:`pyircbot.irccore.IRCCore.initHooks`.
The easiest method is to use the ``hook`` decorator on any function your want The easiest method is to use the ``hook`` decorator on any function your want
@ -59,7 +59,7 @@ called when an IRC command is received.
def echo(self, event): def echo(self, event):
The handler is passed and IRCEvent object containing the data sent by the irc The handler is passed and IRCEvent object containing the data sent by the irc
server. The values of these are can vary, but the format is alwaysthe same. server. The values of these are can vary, but the format is always the same.
``event.args`` is the list of arguments the IRC server sent. ``event.prefix`` ``event.args`` is the list of arguments the IRC server sent. ``event.prefix``
is the sender, parsed. ``trailing`` is arbitrary data associated is the sender, parsed. ``trailing`` is arbitrary data associated
@ -83,6 +83,17 @@ Since the module described above echos messages, let's do that:
This sends a PRIVMSG to the originating channel or nick, with the same msg This sends a PRIVMSG to the originating channel or nick, with the same msg
content that was received. content that was received.
Alternatively, if your module needs to respond to chat-based commands, a
similar decorator :py:class:`pyircbot.modulebase.command`. can be used:
.. code-block:: python
@command("echo")
def echo2(self, cmd, msg):
# If the message was ".echo bob asdf", cmd.args would look like:
# ["bob", "asdf"]
self.bot.act_PRIVMSG(msg.args[0], msg.trailing)
Beyond this, a module's class can import or do anything python can to deliver Beyond this, a module's class can import or do anything python can to deliver
responses. For modules that use threads or connect to external services, a responses. For modules that use threads or connect to external services, a
shutdown handler is needed to ensure a clean shutdown. shutdown handler is needed to ensure a clean shutdown.

View File

@ -120,21 +120,23 @@ ATTR_COMMAND_HOOK = "__tag_commands"
class hook(object): class hook(object):
""" """
Decorator for calling module methods in response to IRC actions. Example: Decorator for calling module methods in response to IRC actions. Example:
```
@hook("PRIVMSG") .. code-block:: python
def mymyethod(self, message):
print("IRC server sent PRIVMSG") @hook("PRIVMSG")
``` def mymyethod(self, message):
print("IRC server sent PRIVMSG")
This stores a list of IRC actions each function is tagged for in method.__tag_hooks. This attribute is scanned This stores a list of IRC actions each function is tagged for in method.__tag_hooks. This attribute is scanned
during module init and appropriate hooks are set up. during module init and appropriate hooks are set up.
:param args: irc protocol event to listen for. See :py:meth:`pyircbot.irccore.IRCCore.initHooks` for a complete list
:type args: str
""" """
def __init__(self, *args): def __init__(self, *args):
self.commands = args self.commands = args
def __call__(self, func): def __call__(self, func):
"""
"""
if not hasattr(func, ATTR_ACTION_HOOK): if not hasattr(func, ATTR_ACTION_HOOK):
setattr(func, ATTR_ACTION_HOOK, list(self.commands)) setattr(func, ATTR_ACTION_HOOK, list(self.commands))
else: else:
@ -159,16 +161,29 @@ class irchook(object):
class command(irchook): class command(irchook):
""" """
Decorating for calling module methods in response to IRC actions. Example: Decorator for calling module methods when a command is parsed from chat
```
@hook("PRIVMSG") .. code-block:: python
def mymyethod(self, message):
print("IRC server sent PRIVMSG") @command("ascii")
``` def cmd_ascii(self, cmd, msg):
This stores a list of IRC actions each function is tagged for in method.__tag_hooks. This attribute is scanned print("Somebody typed .ascii with params {} in channel {}".format(str(cmd.args), msg.args[0]))
This stores a list of IRC actions each function is tagged for in method.__tag_commands. This attribute is scanned
during module init and appropriate hooks are set up. during module init and appropriate hooks are set up.
:param keywords: commands to listen for
:type keywords: str
:param require_args: only match if trailing data is passed with the command used
:type require_args: bool
:param allow_private: enable matching in private messages
:type allow_private: bool
""" """
prefix = "." prefix = "."
"""
Hotkey that must appear before commands
"""
def __init__(self, *keywords, require_args=False, allow_private=False): def __init__(self, *keywords, require_args=False, allow_private=False):
self.keywords = keywords self.keywords = keywords
@ -177,12 +192,23 @@ class command(irchook):
self.parsed_cmd = None self.parsed_cmd = None
def call(self, method, msg): def call(self, method, msg):
"""
Internal use. Triggers the hooked function
"""
if len(getargspec(method).args) == 3: if len(getargspec(method).args) == 3:
method(self.parsed_cmd, msg) return method(self.parsed_cmd, msg)
else: else:
method(self.parsed_cmd) return method(self.parsed_cmd)
def validate(self, msg, bot): def validate(self, msg, bot):
"""
Test a message and return true if matched.
:param msg: message to test against
:type msg: pyircbot.irccore.IRCEvent
:param bot: reference to main pyircbot
:type bot: pyircbot.pyircbot.PyIRCBot
"""
if not self.allow_private and msg.args[0] == "#": if not self.allow_private and msg.args[0] == "#":
return False return False
for keyword in self.keywords: for keyword in self.keywords: