Update docs
This commit is contained in:
parent
e9349091bd
commit
6cd8911502
|
@ -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.
|
||||||
|
|
|
@ -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:
|
||||||
|
|
Loading…
Reference in New Issue