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.

customizing.rst 12 KiB

12 jaren geleden
12 jaren geleden
12 jaren geleden
12 jaren geleden
12 jaren geleden
12 jaren geleden
12 jaren geleden
12 jaren geleden
12 jaren geleden
12 jaren geleden
12 jaren geleden
12 jaren geleden
12 jaren geleden
12 jaren geleden
12 jaren geleden
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238
  1. Customizing
  2. ===========
  3. The bot's working directory contains a :file:`commands` subdirectory and a
  4. :file:`tasks` subdirectory. Custom IRC commands can be placed in the former,
  5. whereas custom wiki bot tasks go into the latter. Developing custom modules is
  6. explained in detail in this documentation.
  7. Note that custom commands will override built-in commands and tasks with the
  8. same name.
  9. :py:class:`~earwigbot.bot.Bot` and :py:class:`~earwigbot.bot.BotConfig`
  10. -----------------------------------------------------------------------
  11. :py:class:`earwigbot.bot.Bot` is EarwigBot's main class. You don't have to
  12. instantiate this yourself, but it's good to be familiar with its attributes and
  13. methods, because it is the main way to communicate with other parts of the bot.
  14. A :py:class:`~earwigbot.bot.Bot` object is accessible as an attribute of
  15. commands and tasks (i.e., :py:attr:`self.bot`).
  16. The most useful attributes are:
  17. - :py:attr:`~earwigbot.bot.Bot.config`: an instance of
  18. :py:class:`~earwigbot.config.BotConfig`, for accessing the bot's
  19. configuration data (see below).
  20. - :py:attr:`~earwigbot.bot.Bot.commands`: the bot's
  21. :py:class:`~earwigbot.managers.CommandManager`, which is used internally to
  22. run IRC commands (through
  23. :py:meth:`commands.call() <earwigbot.managers.CommandManager.call>`, which
  24. you shouldn't have to use); you can safely reload all commands with
  25. :py:meth:`commands.load() <earwigbot.managers._ResourceManager.load>`.
  26. - :py:attr:`~earwigbot.bot.Bot.tasks`: the bot's
  27. :py:class:`~earwigbot.managers.TaskManager`, which can be used to start tasks
  28. with :py:meth:`tasks.start(task_name, **kwargs)
  29. <earwigbot.managers.TaskManager.start>`. :py:meth:`tasks.load()
  30. <earwigbot.managers._ResourceManager.load>` can be used to safely reload all
  31. tasks.
  32. - :py:attr:`~earwigbot.bot.Bot.frontend` /
  33. :py:attr:`~earwigbot.bot.Bot.watcher`: instances of
  34. :py:class:`earwigbot.irc.Frontend <earwigbot.irc.frontend.Frontend>` and
  35. :py:class:`earwigbot.irc.Watcher <earwigbot.irc.watcher.Watcher>`,
  36. respectively, which represent the bot's connections to these two servers; you
  37. can, for example, send a message to the frontend with
  38. :py:meth:`frontend.say(chan, msg)
  39. <earwigbot.irc.connection.IRCConnection.say>` (more on communicating with IRC
  40. below).
  41. - :py:attr:`~earwigbot.bot.Bot.wiki`: interface with the
  42. :doc:`Wiki Toolset <toolset>`.
  43. - Finally, :py:meth:`~earwigbot.bot.Bot.restart` (restarts IRC components and
  44. reloads config, commands, and tasks) and :py:meth:`~earwigbot.bot.Bot.stop`
  45. can be used almost anywhere. Both take an optional "reason" that will be
  46. logged and used as the quit message when disconnecting from IRC.
  47. :py:class:`earwigbot.config.BotConfig` stores configuration information for the
  48. bot. Its docstrings explains what each attribute is used for, but essentially
  49. each "node" (one of :py:attr:`config.components`, :py:attr:`wiki`,
  50. :py:attr:`tasks`, :py:attr:`tasks`, or :py:attr:`metadata`) maps to a section
  51. of the bot's :file:`config.yml` file. For example, if :file:`config.yml`
  52. includes something like::
  53. irc:
  54. frontend:
  55. nick: MyAwesomeBot
  56. channels:
  57. - "##earwigbot"
  58. - "#channel"
  59. - "#other-channel"
  60. ...then :py:attr:`config.irc["frontend"]["nick"]` will be ``"MyAwesomeBot"``
  61. and :py:attr:`config.irc["frontend"]["channels"]` will be
  62. ``["##earwigbot", "#channel", "#other-channel"]``.
  63. Custom IRC commands
  64. -------------------
  65. Custom commands are subclasses of :py:class:`earwigbot.commands.BaseCommand`
  66. that override :py:class:`~earwigbot.commands.BaseCommand`'s
  67. :py:meth:`~earwigbot.commands.BaseCommand.process` (and optionally
  68. :py:meth:`~earwigbot.commands.BaseCommand.check`) methods.
  69. :py:class:`~earwigbot.commands.BaseCommand`'s docstrings should explain what
  70. each attribute and method is for and what they should be overridden with, but
  71. these are the basics:
  72. - Class attribute :py:attr:`~earwigbot.commands.BaseCommand.name` is the name
  73. of the command. This must be specified.
  74. - Class attribute :py:attr:`~earwigbot.commands.BaseCommand.hooks` is a list of
  75. the "IRC events" that this command might respond to. It defaults to
  76. ``["msg"]``, but options include ``"msg_private"`` (for private messages
  77. only), ``"msg_public"`` (for channel messages only), and ``"join"`` (for when
  78. a user joins a channel). See the afc_status_ plugin for a command that
  79. responds to other hook types.
  80. - Method :py:meth:`~earwigbot.commands.BaseCommand.check` is passed a
  81. :py:class:`~earwigbot.irc.data.Data` [1]_ object, and should return ``True``
  82. if you want to respond to this message, or ``False`` otherwise. The default
  83. behavior is to return ``True`` only if
  84. :py:attr:`data.is_command` is ``True`` and :py:attr:`data.command` ==
  85. :py:attr:`~earwigbot.commands.BaseCommand.name`, which is suitable for most
  86. cases. A common, straightforward reason for overriding is if a command has
  87. aliases (see chanops_ for an example). Note that by returning ``True``, you
  88. prevent any other commands from responding to this message.
  89. - Method :py:meth:`~earwigbot.commands.BaseCommand.process` is passed the same
  90. :py:class:`~earwigbot.irc.data.Data` object as
  91. :py:meth:`~earwigbot.commands.BaseCommand.check`, but only if
  92. :py:meth:`~earwigbot.commands.BaseCommand.check` returned ``True``. This is
  93. where the bulk of your command goes. To respond to IRC messages, there are a
  94. number of methods of :py:class:`~earwigbot.commands.BaseCommand` at your
  95. disposal. See the the test_ command for a simple example, or look in
  96. :py:class:`~earwigbot.commands.BaseCommand`'s
  97. :py:meth:`~earwigbot.commands.BaseCommand.__init__` method for the full list.
  98. The most common ones are :py:meth:`say(chan_or_user, msg)
  99. <earwigbot.irc.connection.IRCConnection.say>`, :py:meth:`reply(data, msg)
  100. <earwigbot.irc.connection.IRCConnection.reply>` (convenience function; sends
  101. a reply to the issuer of the command in the channel it was received),
  102. :py:meth:`action(chan_or_user, msg)
  103. <earwigbot.irc.connection.IRCConnection.action>`,
  104. :py:meth:`notice(chan_or_user, msg)
  105. <earwigbot.irc.connection.IRCConnection.notice>`, :py:meth:`join(chan)
  106. <earwigbot.irc.connection.IRCConnection.join>`, and
  107. :py:meth:`part(chan) <earwigbot.irc.connection.IRCConnection.part>`.
  108. It's important to name the command class :py:class:`Command` within the file,
  109. or else the bot might not recognize it as a command. The name of the file
  110. doesn't really matter and need not match the command's name, but this is
  111. recommended for readability.
  112. The bot has a wide selection of built-in commands and plugins to act as sample
  113. code and/or to give ideas. Start with test_, and then check out chanops_ and
  114. afc_status_ for some more complicated scripts.
  115. Custom bot tasks
  116. ----------------
  117. Custom tasks are subclasses of :py:class:`earwigbot.tasks.BaseTask` that
  118. override :py:class:`~earwigbot.tasks.BaseTask`'s
  119. :py:meth:`~earwigbot.tasks.BaseTask.run` (and optionally
  120. :py:meth:`~earwigbot.tasks.BaseTask.setup`) methods.
  121. :py:class:`~earwigbot.tasks.BaseTask`'s docstrings should explain what each
  122. attribute and method is for and what they should be overridden with, but these
  123. are the basics:
  124. - Class attribute :py:attr:`~earwigbot.tasks.BaseTask.name` is the name of the
  125. task. This must be specified.
  126. - Class attribute :py:attr:`~earwigbot.tasks.BaseTask.number` can be used to
  127. store an optional "task number", possibly for use in edit summaries (to be
  128. generated with :py:meth:`~earwigbot.tasks.BaseTask.make_summary`). For
  129. example, EarwigBot's :py:attr:`config.wiki["summary"]` is
  130. ``"([[WP:BOT|Bot]]; [[User:EarwigBot#Task $1|Task $1]]): $2"``, which the
  131. task class's :py:meth:`make_summary(comment)
  132. <earwigbot.tasks.BaseTask.make_summary>` method will take and replace
  133. ``$1`` with the task number and ``$2`` with the details of the edit.
  134. Additionally, :py:meth:`~earwigbot.tasks.BaseTask.shutoff_enabled` (which
  135. checks whether the bot has been told to stop on-wiki by checking the content
  136. of a particular page) can check a different page for each task using similar
  137. variables. EarwigBot's :py:attr:`config.wiki["shutoff"]["page"]` is
  138. ``"User:$1/Shutoff/Task $2"``; ``$1`` is substituted with the bot's username,
  139. and ``$2`` is substituted with the task number, so, e.g., task #14 checks the
  140. page ``[[User:EarwigBot/Shutoff/Task 14]].`` If the page's content does *not*
  141. match :py:attr:`config.wiki["shutoff"]["disabled"]` (``"run"`` by default),
  142. then shutoff is considered to be *enabled* and
  143. :py:meth:`~earwigbot.tasks.BaseTask.shutoff_enabled` will return ``True``,
  144. indicating the task should not run. If you don't intend to use either of
  145. these methods, feel free to leave this attribute blank.
  146. - Method :py:meth:`~earwigbot.tasks.BaseTask.setup` is called *once* with no
  147. arguments immediately after the task is first loaded. Does nothing by
  148. default; treat it like an :py:meth:`__init__` if you want
  149. (:py:meth:`~earwigbot.tasks.BaseTask.__init__` does things by default and a
  150. dedicated setup method is often easier than overriding
  151. :py:meth:`~earwigbot.tasks.BaseTask.__init__` and using :py:obj:`super`).
  152. - Method :py:meth:`~earwigbot.tasks.BaseTask.run` is called with any number of
  153. keyword arguments every time the task is executed (by
  154. :py:meth:`tasks.start(task_name, **kwargs)
  155. <earwigbot.managers.TaskManager.start>`, usually). This is where the bulk of
  156. the task's code goes. For interfacing with MediaWiki sites, read up on the
  157. :doc:`Wiki Toolset <toolset>`.
  158. Tasks have access to :py:attr:`config.tasks[task_name]` for config information,
  159. which is a node in :file:`config.yml` like every other attribute of
  160. :py:attr:`bot.config`. This can be used to store, for example, edit summaries,
  161. or templates to append to user talk pages, so that these can be easily changed
  162. without modifying the task itself.
  163. It's important to name the task class :py:class:`Task` within the file, or else
  164. the bot might not recognize it as a task. The name of the file doesn't really
  165. matter and need not match the task's name, but this is recommended for
  166. readability.
  167. See the built-in wikiproject_tagger_ task for a relatively straightforward
  168. task, or the afc_statistics_ plugin for a more complicated one.
  169. .. rubric:: Footnotes
  170. .. [1] :py:class:`~earwigbot.irc.data.Data` objects are instances of
  171. :py:class:`earwigbot.irc.Data <earwigbot.irc.data.Data>` that contain
  172. information about a single message sent on IRC. Their useful attributes
  173. are :py:attr:`~earwigbot.irc.data.Data.chan` (channel the message was
  174. sent from, equal to :py:attr:`~earwigbot.irc.data.Data.nick` if it's a
  175. private message), :py:attr:`~earwigbot.irc.data.Data.nick` (nickname of
  176. the sender), :py:attr:`~earwigbot.irc.data.Data.ident` (ident_ of the
  177. sender), :py:attr:`~earwigbot.irc.data.Data.host` (hostname of the
  178. sender), :py:attr:`~earwigbot.irc.data.Data.msg` (text of the sent
  179. message), :py:attr:`~earwigbot.irc.data.Data.is_command` (boolean
  180. telling whether or not this message is a bot command, e.g., whether it
  181. is prefixed by ``!``), :py:attr:`~earwigbot.irc.data.Data.command` (if
  182. the message is a command, this is the name of the command used), and
  183. :py:attr:`~earwigbot.irc.data.Data.args` (if the message is a command,
  184. this is a list of the command arguments - for example, if issuing
  185. "``!part ##earwig Goodbye guys``",
  186. :py:attr:`~earwigbot.irc.data.Data.args` will equal
  187. ``["##earwig", "Goodbye", "guys"]``). Note that not all
  188. :py:class:`~earwigbot.irc.data.Data` objects will have all of these
  189. attributes: :py:class:`~earwigbot.irc.data.Data` objects generated by
  190. private messages will, but ones generated by joins will only have
  191. :py:attr:`~earwigbot.irc.data.Data.chan`,
  192. :py:attr:`~earwigbot.irc.data.Data.nick`,
  193. :py:attr:`~earwigbot.irc.data.Data.ident`,
  194. and :py:attr:`~earwigbot.irc.data.Data.host`.
  195. .. _afc_status: https://github.com/earwig/earwigbot-plugins/blob/develop/commands/afc_status.py
  196. .. _chanops: https://github.com/earwig/earwigbot/blob/develop/earwigbot/commands/chanops.py
  197. .. _test: https://github.com/earwig/earwigbot/blob/develop/earwigbot/commands/test.py
  198. .. _wikiproject_tagger: https://github.com/earwig/earwigbot/blob/develop/earwigbot/tasks/wikiproject_tagger.py
  199. .. _afc_statistics: https://github.com/earwig/earwigbot-plugins/blob/develop/tasks/afc_statistics.py
  200. .. _ident: http://en.wikipedia.org/wiki/Ident