ben
/
earwigbot
mirror of https://github.com/earwig/earwigbot
1
1
Fork 0
Code Releases 3 Activity
A Python robot that edits Wikipedia and interacts with people over IRC https://en.wikipedia.org/wiki/User:EarwigBot
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
393 Commits
2 Branches
3.7 MiB
 
Tree: 4aac14c3e1
Branches Tags
${ item.name }
Create branch ${ searchTerm }
from '4aac14c3e1'
${ noResults }
earwigbot/docs/customizing.rst

239 lines
12 KiB
Raw Blame History 

  1. Customizing

  2. ===========

  3. 

  4. The bot's working directory contains a :file:`commands` subdirectory and a

  5. :file:`tasks` subdirectory. Custom IRC commands can be placed in the former,

  6. whereas custom wiki bot tasks go into the latter. Developing custom modules is

  7. explained in detail in this documentation.

  8. 

  9. Note that custom commands will override built-in commands and tasks with the

  10. same name.

  11. 

  12. :py:class:`~earwigbot.bot.Bot` and :py:class:`~earwigbot.bot.BotConfig`

  13. -----------------------------------------------------------------------

  14. 

  15. :py:class:`earwigbot.bot.Bot` is EarwigBot's main class. You don't have to

  16. instantiate this yourself, but it's good to be familiar with its attributes and

  17. methods, because it is the main way to communicate with other parts of the bot.

  18. A :py:class:`~earwigbot.bot.Bot` object is accessible as an attribute of

  19. commands and tasks (i.e., :py:attr:`self.bot`).

  20. 

  21. The most useful attributes are:

  22. 

  23. - :py:attr:`~earwigbot.bot.Bot.config`: an instance of

  24.   :py:class:`~earwigbot.config.BotConfig`, for accessing the bot's

  25.   configuration data (see below).

  26. 

  27. - :py:attr:`~earwigbot.bot.Bot.commands`: the bot's

  28.   :py:class:`~earwigbot.managers.CommandManager`, which is used internally to

  29.   run IRC commands (through

  30.   :py:meth:`commands.call() <earwigbot.managers.CommandManager.call>`, which

  31.   you shouldn't have to use); you can safely reload all commands with

  32.   :py:meth:`commands.load() <earwigbot.managers._ResourceManager.load>`.

  33. 

  34. - :py:attr:`~earwigbot.bot.Bot.tasks`: the bot's

  35.   :py:class:`~earwigbot.managers.TaskManager`, which can be used to start tasks

  36.   with :py:meth:`tasks.start(task_name, **kwargs)

  37.   <earwigbot.managers.TaskManager.start>`. :py:meth:`tasks.load()

  38.   <earwigbot.managers._ResourceManager.load>` can be used to safely reload all

  39.   tasks.

  40. 

  41. - :py:attr:`~earwigbot.bot.Bot.frontend` /

  42.   :py:attr:`~earwigbot.bot.Bot.watcher`: instances of

  43.   :py:class:`earwigbot.irc.Frontend <earwigbot.irc.frontend.Frontend>` and

  44.   :py:class:`earwigbot.irc.Watcher <earwigbot.irc.watcher.Watcher>`,

  45.   respectively, which represent the bot's connections to these two servers; you

  46.   can, for example, send a message to the frontend with

  47.   :py:meth:`frontend.say(chan, msg)

  48.   <earwigbot.irc.connection.IRCConnection.say>` (more on communicating with IRC

  49.   below).

  50. 

  51. - :py:attr:`~earwigbot.bot.Bot.wiki`: interface with the

  52.   :doc:`Wiki Toolset <toolset>`.

  53. 

  54. - Finally, :py:meth:`~earwigbot.bot.Bot.restart` (restarts IRC components and

  55.   reloads config, commands, and tasks) and :py:meth:`~earwigbot.bot.Bot.stop`

  56.   can be used almost anywhere. Both take an optional "reason" that will be

  57.   logged and used as the quit message when disconnecting from IRC.

  58. 

  59. :py:class:`earwigbot.config.BotConfig` stores configuration information for the

  60. bot. Its docstring explains what each attribute is used for, but essentially

  61. each "node" (one of :py:attr:`config.components`, :py:attr:`wiki`,

  62. :py:attr:`tasks`, :py:attr:`tasks`, or :py:attr:`metadata`) maps to a section

  63. of the bot's :file:`config.yml` file. For example, if :file:`config.yml`

  64. includes something like::

  65. 

  66.     irc:

  67.         frontend:

  68.             nick: MyAwesomeBot

  69.             channels:

  70.                 - "##earwigbot"

  71.                 - "#channel"

  72.                 - "#other-channel"

  73. 

  74. ...then :py:attr:`config.irc["frontend"]["nick"]` will be ``"MyAwesomeBot"``

  75. and :py:attr:`config.irc["frontend"]["channels"]` will be

  76. ``["##earwigbot", "#channel", "#other-channel"]``.

  77. 

  78. Custom IRC commands

  79. -------------------

  80. 

  81. Custom commands are subclasses of :py:class:`earwigbot.commands.BaseCommand`

  82. that override :py:class:`~earwigbot.commands.BaseCommand`'s

  83. :py:meth:`~earwigbot.commands.BaseCommand.process` (and optionally

  84. :py:meth:`~earwigbot.commands.BaseCommand.check`) methods.

  85. 

  86. :py:class:`~earwigbot.commands.BaseCommand`'s docstrings should explain what

  87. each attribute and method is for and what they should be overridden with, but

  88. these are the basics:

  89. 

  90. - Class attribute :py:attr:`~earwigbot.commands.BaseCommand.name` is the name

  91.   of the command. This must be specified.

  92. 

  93. - Class attribute :py:attr:`~earwigbot.commands.BaseCommand.hooks` is a list of

  94.   the "IRC events" that this command might respond to. It defaults to

  95.   ``["msg"]``, but options include ``"msg_private"`` (for private messages

  96.   only), ``"msg_public"`` (for channel messages only), and ``"join"`` (for when

  97.   a user joins a channel). See the afc_status_ plugin for a command that

  98.   responds to other hook types.

  99. 

  100. - Method :py:meth:`~earwigbot.commands.BaseCommand.check` is passed a

  101.   :py:class:`~earwigbot.irc.data.Data` [1]_ object, and should return ``True``

  102.   if you want to respond to this message, or ``False`` otherwise. The default

  103.   behavior is to return ``True`` only if

  104.   :py:attr:`data.is_command` is ``True`` and :py:attr:`data.command` ==

  105.   :py:attr:`~earwigbot.commands.BaseCommand.name`, which is suitable for most

  106.   cases. A common, straightforward reason for overriding is if a command has

  107.   aliases (see chanops_ for an example). Note that by returning ``True``, you

  108.   prevent any other commands from responding to this message.

  109. 

  110. - Method :py:meth:`~earwigbot.commands.BaseCommand.process` is passed the same

  111.   :py:class:`~earwigbot.irc.data.Data` object as

  112.   :py:meth:`~earwigbot.commands.BaseCommand.check`, but only if

  113.   :py:meth:`~earwigbot.commands.BaseCommand.check` returned ``True``. This is

  114.   where the bulk of your command goes. To respond to IRC messages, there are a

  115.   number of methods of :py:class:`~earwigbot.commands.BaseCommand` at your

  116.   disposal. See the the test_ command for a simple example, or look in

  117.   :py:class:`~earwigbot.commands.BaseCommand`'s

  118.   :py:meth:`~earwigbot.commands.BaseCommand.__init__` method for the full list.

  119. 

  120.   The most common ones are :py:meth:`say(chan_or_user, msg)

  121.   <earwigbot.irc.connection.IRCConnection.say>`, :py:meth:`reply(data, msg)

  122.   <earwigbot.irc.connection.IRCConnection.reply>` (convenience function; sends

  123.   a reply to the issuer of the command in the channel it was received),

  124.   :py:meth:`action(chan_or_user, msg)

  125.   <earwigbot.irc.connection.IRCConnection.action>`,

  126.   :py:meth:`notice(chan_or_user, msg)

  127.   <earwigbot.irc.connection.IRCConnection.notice>`, :py:meth:`join(chan)

  128.   <earwigbot.irc.connection.IRCConnection.join>`, and

  129.   :py:meth:`part(chan) <earwigbot.irc.connection.IRCConnection.part>`.

  130. 

  131. It's important to name the command class :py:class:`Command` within the file,

  132. or else the bot might not recognize it as a command. The name of the file

  133. doesn't really matter and need not match the command's name, but this is

  134. recommended for readability.

  135. 

  136. The bot has a wide selection of built-in commands and plugins to act as sample

  137. code and/or to give ideas. Start with test_, and then check out chanops_ and

  138. afc_status_ for some more complicated scripts.

  139. 

  140. Custom bot tasks

  141. ----------------

  142. 

  143. Custom tasks are subclasses of :py:class:`earwigbot.tasks.BaseTask` that

  144. override :py:class:`~earwigbot.tasks.BaseTask`'s

  145. :py:meth:`~earwigbot.tasks.BaseTask.run` (and optionally

  146. :py:meth:`~earwigbot.tasks.BaseTask.setup`) methods.

  147. 

  148. :py:class:`~earwigbot.tasks.BaseTask`'s docstrings should explain what each

  149. attribute and method is for and what they should be overridden with, but these

  150. are the basics:

  151. 

  152. - Class attribute :py:attr:`~earwigbot.tasks.BaseTask.name` is the name of the

  153.   task. This must be specified.

  154. 

  155. - Class attribute :py:attr:`~earwigbot.tasks.BaseTask.number` can be used to

  156.   store an optional "task number", possibly for use in edit summaries (to be

  157.   generated with :py:meth:`~earwigbot.tasks.BaseTask.make_summary`). For

  158.   example, EarwigBot's :py:attr:`config.wiki["summary"]` is

  159.   ``"([[WP:BOT|Bot]]; [[User:EarwigBot#Task $1|Task $1]]): $2"``, which the

  160.   task class's :py:meth:`make_summary(comment)

  161.   <earwigbot.tasks.BaseTask.make_summary>` method will take and replace

  162.   ``$1`` with the task number and ``$2`` with the details of the edit.

  163.   

  164.   Additionally, :py:meth:`~earwigbot.tasks.BaseTask.shutoff_enabled` (which

  165.   checks whether the bot has been told to stop on-wiki by checking the content

  166.   of a particular page) can check a different page for each task using similar

  167.   variables. EarwigBot's :py:attr:`config.wiki["shutoff"]["page"]` is

  168.   ``"User:$1/Shutoff/Task $2"``; ``$1`` is substituted with the bot's username,

  169.   and ``$2`` is substituted with the task number, so, e.g., task #14 checks the

  170.   page ``[[User:EarwigBot/Shutoff/Task 14]].`` If the page's content does *not*

  171.   match :py:attr:`config.wiki["shutoff"]["disabled"]` (``"run"`` by default),

  172.   then shutoff is considered to be *enabled* and

  173.   :py:meth:`~earwigbot.tasks.BaseTask.shutoff_enabled` will return ``True``,

  174.   indicating the task should not run. If you don't intend to use either of

  175.   these methods, feel free to leave this attribute blank.

  176. 

  177. - Method :py:meth:`~earwigbot.tasks.BaseTask.setup` is called *once* with no

  178.   arguments immediately after the task is first loaded. Does nothing by

  179.   default; treat it like an :py:meth:`__init__` if you want

  180.   (:py:meth:`~earwigbot.tasks.BaseTask.__init__` does things by default and a

  181.   dedicated setup method is often easier than overriding

  182.   :py:meth:`~earwigbot.tasks.BaseTask.__init__` and using :py:obj:`super`).

  183. 

  184. - Method :py:meth:`~earwigbot.tasks.BaseTask.run` is called with any number of

  185.   keyword arguments every time the task is executed (by

  186.   :py:meth:`tasks.start(task_name, **kwargs)

  187.   <earwigbot.managers.TaskManager.start>`, usually). This is where the bulk of

  188.   the task's code goes. For interfacing with MediaWiki sites, read up on the

  189.   :doc:`Wiki Toolset <toolset>`.

  190. 

  191. Tasks have access to :py:attr:`config.tasks[task_name]` for config information,

  192. which is a node in :file:`config.yml` like every other attribute of

  193. :py:attr:`bot.config`. This can be used to store, for example, edit summaries,

  194. or templates to append to user talk pages, so that these can be easily changed

  195. without modifying the task itself.

  196. 

  197. It's important to name the task class :py:class:`Task` within the file, or else

  198. the bot might not recognize it as a task. The name of the file doesn't really

  199. matter and need not match the task's name, but this is recommended for

  200. readability.

  201. 

  202. See the built-in wikiproject_tagger_ task for a relatively straightforward

  203. task, or the afc_statistics_ plugin for a more complicated one.

  204. 

  205. .. rubric:: Footnotes

  206. 

  207. .. [1] :py:class:`~earwigbot.irc.data.Data` objects are instances of

  208.        :py:class:`earwigbot.irc.Data <earwigbot.irc.data.Data>` that contain

  209.        information about a single message sent on IRC. Their useful attributes

  210.        are :py:attr:`~earwigbot.irc.data.Data.chan` (channel the message was

  211.        sent from, equal to :py:attr:`~earwigbot.irc.data.Data.nick` if it's a

  212.        private message), :py:attr:`~earwigbot.irc.data.Data.nick` (nickname of

  213.        the sender), :py:attr:`~earwigbot.irc.data.Data.ident` (ident_ of the

  214.        sender), :py:attr:`~earwigbot.irc.data.Data.host` (hostname of the

  215.        sender), :py:attr:`~earwigbot.irc.data.Data.msg` (text of the sent

  216.        message), :py:attr:`~earwigbot.irc.data.Data.is_command` (boolean

  217.        telling whether or not this message is a bot command, e.g., whether it

  218.        is prefixed by ``!``), :py:attr:`~earwigbot.irc.data.Data.command` (if

  219.        the message is a command, this is the name of the command used), and

  220.        :py:attr:`~earwigbot.irc.data.Data.args` (if the message is a command,

  221.        this is a list of the command arguments - for example, if issuing

  222.        "``!part ##earwig Goodbye guys``",

  223.        :py:attr:`~earwigbot.irc.data.Data.args` will equal

  224.        ``["##earwig", "Goodbye", "guys"]``). Note that not all

  225.        :py:class:`~earwigbot.irc.data.Data` objects will have all of these

  226.        attributes: :py:class:`~earwigbot.irc.data.Data` objects generated by

  227.        private messages will, but ones generated by joins will only have

  228.        :py:attr:`~earwigbot.irc.data.Data.chan`,

  229.        :py:attr:`~earwigbot.irc.data.Data.nick`,

  230.        :py:attr:`~earwigbot.irc.data.Data.ident`,

  231.        and :py:attr:`~earwigbot.irc.data.Data.host`.

  232. 

  233. .. _afc_status:         https://github.com/earwig/earwigbot-plugins/blob/develop/commands/afc_status.py

  234. .. _chanops:            https://github.com/earwig/earwigbot/blob/develop/earwigbot/commands/chanops.py

  235. .. _test:               https://github.com/earwig/earwigbot/blob/develop/earwigbot/commands/test.py

  236. .. _wikiproject_tagger: https://github.com/earwig/earwigbot/blob/develop/earwigbot/tasks/wikiproject_tagger.py

  237. .. _afc_statistics:     https://github.com/earwig/earwigbot-plugins/blob/develop/tasks/afc_statistics.py

  238. .. _ident:              http://en.wikipedia.org/wiki/Ident