From fb6736b46fe272c7f87fd330353a636d8c9d6241 Mon Sep 17 00:00:00 2001 From: dpedu Date: Sat, 8 Aug 2015 16:29:23 -0700 Subject: [PATCH] Update docs --- docs/api/modulebase.rst | 3 +- docs/builder/Dockerfile | 16 +++- docs/module_guide/_module_guide.rst | 121 +++++++++++++++++++++++++++- 3 files changed, 136 insertions(+), 4 deletions(-) diff --git a/docs/api/modulebase.rst b/docs/api/modulebase.rst index 3cf64b3..5fb9520 100644 --- a/docs/api/modulebase.rst +++ b/docs/api/modulebase.rst @@ -1,7 +1,8 @@ :mod:`ModuleBase` --- Base class for Bot modules ================================================ -yabba blahblah blahblah +All bot modules should extend this class. ``ModuleBase`` includes helper methods +to integrate modules with the bot for smooth running. .. automodule:: pyircbot.modulebase :members: diff --git a/docs/builder/Dockerfile b/docs/builder/Dockerfile index 0c8a4f6..b6a3aed 100644 --- a/docs/builder/Dockerfile +++ b/docs/builder/Dockerfile @@ -2,6 +2,20 @@ FROM ubuntu:trusty COPY start /start -RUN apt-get update ; apt-get install -y python3 python3-sphinx python3-setuptools python3-dev python3-requests python3-pip python3-yaml python3-lxml make wget unzip libmysqlclient-dev ; pip3 install pytz praw ; cd /tmp ; wget https://github.com/jgarzik/python-bitcoinrpc/archive/master.zip ; unzip master.zip ; cd python-bitcoinrpc-master/ ; python3 setup.py install ; cd /tmp ; wget https://github.com/dpedu/MySQL-for-Python-3/archive/master.zip -O mysqldb.zip ; unzip mysqldb.zip ; cd MySQL-for-Python-3-master/ ; python3 setup.py install ; chmod +x /start ; mkdir /tmp/docs +RUN apt-get update ; \ + apt-get install -y python3 python3-sphinx python3-setuptools python3-dev python3-requests python3-pip python3-yaml python3-lxml make wget unzip libmysqlclient-dev ; \ + pip3 install pytz praw ; \ + cd /tmp ; \ + wget https://github.com/jgarzik/python-bitcoinrpc/archive/master.zip ; \ + unzip master.zip ; \ + cd python-bitcoinrpc-master/ ; \ + python3 setup.py install ; \ + cd /tmp ; \ + wget https://github.com/dpedu/MySQL-for-Python-3/archive/master.zip -O mysqldb.zip ; \ + unzip mysqldb.zip ; \ + cd MySQL-for-Python-3-master/ ; \ + python3 setup.py install ; \ + chmod +x /start ; \ + mkdir /tmp/docs CMD /start diff --git a/docs/module_guide/_module_guide.rst b/docs/module_guide/_module_guide.rst index 657fc15..5d0b22e 100644 --- a/docs/module_guide/_module_guide.rst +++ b/docs/module_guide/_module_guide.rst @@ -1,4 +1,121 @@ +************************ Module Developer's Guide -======================== +************************ -TODO: Developing modules \ No newline at end of file +Modules consist of a single python file, named for the module. For example, EchoExample.py + +Getting Started +=============== + +All modules should inherit from the base class +:doc:`ModuleBase `, and should be named matching their python +file's name. + +.. code-block:: python + + from pyircbot.modulebase import ModuleBase,ModuleHook + class EchoExample(ModuleBase): + +The class's ``__init__`` method accepts 2 args - a reference to the bot's API +and what the bot has decided to name this module. These are passed to +ModuleBase. Module's init method should be as quick as possible. The bot loads +modules one after the other so a long delay slows bot startup. + +.. code-block:: python + + def __init__(self, bot, moduleName): + ModuleBase.__init__(self, bot, moduleName); + +If your module has a config file - EchoExample.json - it can be loaded by +calling :py:meth:`pyircbot.modulebase.ModuleBase.loadConfig`: + +.. code-block:: python + + self.loadConfig() + print(self.config) + +In ``__init__``, the module lists what hooks it wants to listen for. Hooks are +executed when the corresponding IRC protocol command is received. + +.. code-block:: python + + self.hooks=[ModuleHook("PRIVMSG", self.echo)] + +Then, a handler for this hook: + +.. code-block:: python + + def echo(self, args, prefix, trailing): + +The handler is passed the data sent by the irc server. What these are can vary, +but the format is the same. ``args`` is the list of arguments the IRC server +sent. ``prefix`` is the sender. ``trailing`` is arbitrary data associated with +the event. In the case of PRIVMSG: args has one entry - the channel name or +nick the message was in/from. Prefix is a user's nick string, in the format of: +NickName!username@ip. Trailing is message content. Since the module describe +above echos messages, let's do that: + +.. code-block:: python + + self.bot.act_PRIVMSG(args[0], trailing) + +This sends a PRIVMSG to the originating channel or nick, with the same msg +content that was received. + +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 +shutdown handler is needed to ensure a clean shutdown. + +.. code-block:: python + + def ondisable(self): + """Called when the module should be disabled. Your module should do any sort + of clean-up operations here like ending child threads or saving data files. + """ + pass + +Advanced Usage +============== + +Check out the helper methods that :doc:`ModuleBase ` offers. + +Refer to existing modules for helper methods from elsewhere in PyIRCBot. + +:doc:`PyIRCBot ` has some useful methods: + +- :py:meth:`pyircbot.pyircbot.PyIRCBot.messageHasCommand` +- :py:meth:`pyircbot.pyircbot.PyIRCBot.getDataPath` +- :py:meth:`pyircbot.pyircbot.PyIRCBot.getmodulebyname` + + +Inter-module Communication +-------------------------- + +In the list above, :py:meth:`pyircbot.pyircbot.PyIRCBot.getmodulebyname` can be +used to retrieve a reference to another loaded module. This is simply the +instance of the other module's class. + +But what if you wanted a module to find another by type? For example, a module +providing a cache API could provide a service called "cache". Modules that use +a cache API to function could find this module - or another that's functionally +equivalent. + +Modules providing a service state so like: + +.. code-block:: python + + def __init__(self, bot, moduleName): + ModuleBase.__init__(self, bot, moduleName); + self.services=["cache"] + +Then, another module can find this one by using either +:py:meth:`pyircbot.pyircbot.PyIRCBot.getmodulesbyservice` or +:py:meth:`pyircbot.pyircbot.PyIRCBot.getBestModuleForService` and passing the +name "cache". The first returns a list of all modules offering the "cache" +service, the second returns an arbitrary module returning cache if more that +one is found. + +**PyIRCBot does NOT automatically handle inter-module communication. Meaning, +modules providing a service should be loaded before modules requiring the +service. Modules using a service MUST BE unloaded before the service module +is unloaded.**