A Python robot that edits Wikipedia and interacts with people over IRC https://en.wikipedia.org/wiki/User:EarwigBot
Você não pode selecionar mais de 25 tópicos Os tópicos devem começar com uma letra ou um número, podem incluir traços ('-') e podem ter até 35 caracteres.

README.rst 9.7 KiB

5 anos atrás
5 anos atrás
12 anos atrás
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208
  1. EarwigBot
  2. =========
  3. EarwigBot_ is a Python_ robot that edits Wikipedia_ and interacts with people
  4. over IRC_. This file provides a basic overview of how to install and setup the
  5. bot; more detailed information is located in the ``docs/`` directory (available
  6. online at PyPI_).
  7. History
  8. -------
  9. Development began, based on `Pywikibot`_, in early 2009. Approval for its
  10. first task, a `copyright violation detector`_, was carried out in May, and the
  11. bot has been running consistently ever since (with the exception of Jan/Feb 2011).
  12. It currently handles `several ongoing tasks`_ ranging from statistics generation
  13. to category cleanup, and on-demand tasks such as WikiProject template tagging.
  14. Since it started running, the bot has made over 250,000 edits.
  15. A project to rewrite it from scratch began in early April 2011, thus moving
  16. away from the Pywikibot framework and allowing for less overall code, better
  17. integration between bot parts, and easier maintenance.
  18. Installation
  19. ------------
  20. This package contains the core ``earwigbot``, abstracted enough that it should
  21. be usable and customizable by anyone running a bot on a MediaWiki site. Since
  22. it is component-based, the IRC components can be disabled if desired. IRC
  23. commands and bot tasks specific to `my instance of EarwigBot`_ that I don't
  24. feel the average user will need are available from the repository
  25. `earwigbot-plugins`_.
  26. It's recommended to run the bot's unit tests before installing. Run ``python
  27. setup.py test`` from the project's root directory. Note that some
  28. tests require an internet connection, and others may take a while to run.
  29. Coverage is currently rather incomplete.
  30. Latest release (v0.3)
  31. ~~~~~~~~~~~~~~~~~~~~~
  32. EarwigBot is available from the `Python Package Index`_, so you can install the
  33. latest release with ``pip install earwigbot`` (`get pip`_).
  34. If you get an error while pip is installing dependencies, you may be missing
  35. some header files. For example, on Ubuntu, see `this StackOverflow post`_.
  36. You can also install it from source [1]_ directly::
  37. curl -Lo earwigbot.tgz https://github.com/earwig/earwigbot/tarball/v0.3
  38. tar -xf earwigbot.tgz
  39. cd earwig-earwigbot-*
  40. python setup.py install
  41. cd ..
  42. rm -r earwigbot.tgz earwig-earwigbot-*
  43. Development version
  44. ~~~~~~~~~~~~~~~~~~~
  45. You can install the development version of the bot from ``git`` by using
  46. setuptools's ``develop`` command [1]_, probably on the ``develop`` branch which
  47. contains (usually) working code. ``master`` contains the latest release.
  48. EarwigBot uses `git flow`_, so you're free to browse by tags or by new features
  49. (``feature/*`` branches)::
  50. git clone git://github.com/earwig/earwigbot.git earwigbot
  51. cd earwigbot
  52. python setup.py develop
  53. Setup
  54. -----
  55. The bot stores its data in a "working directory", including its config file and
  56. databases. This is also the location where you will place custom IRC commands
  57. and bot tasks, which will be explained later. It doesn't matter where this
  58. directory is, as long as the bot can write to it.
  59. Start the bot with ``earwigbot path/to/working/dir``, or just ``earwigbot`` if
  60. the working directory is the current directory. It will notice that no
  61. ``config.yml`` file exists and take you through the setup process.
  62. There is currently no way to edit the ``config.yml`` file from within the bot
  63. after it has been created, but YAML is a very straightforward format, so you
  64. should be able to make any necessary changes yourself. Check out the
  65. `explanation of YAML`_ on Wikipedia for help.
  66. After setup, the bot will start. This means it will connect to the IRC servers
  67. it has been configured for, schedule bot tasks to run at specific times, and
  68. then wait for instructions (as commands on IRC). For a list of commands, say
  69. "``!help``" (commands are messages prefixed with an exclamation mark).
  70. You can stop the bot at any time with Control+C, same as you stop a normal
  71. Python program, and it will try to exit safely. You can also use the
  72. "``!quit``" command on IRC.
  73. Customizing
  74. -----------
  75. The bot's working directory contains a ``commands`` subdirectory and a
  76. ``tasks`` subdirectory. Custom IRC commands can be placed in the former,
  77. whereas custom wiki bot tasks go into the latter. Developing custom modules is
  78. explained below, and in more detail through the bot's documentation on PyPI_
  79. (or in the ``docs/`` dir).
  80. Note that custom commands will override built-in commands and tasks with the
  81. same name.
  82. ``Bot`` and ``BotConfig``
  83. ~~~~~~~~~~~~~~~~~~~~~~~~~
  84. `earwigbot.bot.Bot`_ is EarwigBot's main class. You don't have to instantiate
  85. this yourself, but it's good to be familiar with its attributes and methods,
  86. because it is the main way to communicate with other parts of the bot. A
  87. ``Bot`` object is accessible as an attribute of commands and tasks (i.e.,
  88. ``self.bot``).
  89. `earwigbot.config.BotConfig`_ stores configuration information for the bot. Its
  90. docstring explains what each attribute is used for, but essentially each "node"
  91. (one of ``config.components``, ``wiki``, ``irc``, ``commands``, ``tasks``, and
  92. ``metadata``) maps to a section of the bot's ``config.yml`` file. For example,
  93. if ``config.yml`` includes something like::
  94. irc:
  95. frontend:
  96. nick: MyAwesomeBot
  97. channels:
  98. - "##earwigbot"
  99. - "#channel"
  100. - "#other-channel"
  101. ...then ``config.irc["frontend"]["nick"]`` will be ``"MyAwesomeBot"`` and
  102. ``config.irc["frontend"]["channels"]`` will be ``["##earwigbot", "#channel",
  103. "#other-channel"]``.
  104. Custom IRC commands
  105. ~~~~~~~~~~~~~~~~~~~
  106. Custom commands are subclasses of `earwigbot.commands.Command`_ that override
  107. ``Command``'s ``process()`` (and optionally ``check()``, ``setup()``, or
  108. ``unload()``) methods.
  109. The bot has a wide selection of built-in commands and plugins to act as sample
  110. code and/or to give ideas. Start with test_, and then check out chanops_ and
  111. afc_status_ for some more complicated scripts.
  112. Custom bot tasks
  113. ~~~~~~~~~~~~~~~~
  114. Custom tasks are subclasses of `earwigbot.tasks.Task`_ that override ``Task``'s
  115. ``run()`` (and optionally ``setup()`` or ``unload()``) methods.
  116. See the built-in wikiproject_tagger_ task for a relatively straightforward
  117. task, or the afc_statistics_ plugin for a more complicated one.
  118. The Wiki Toolset
  119. ----------------
  120. EarwigBot's answer to the `Pywikipedia framework`_ is the Wiki Toolset
  121. (``earwigbot.wiki``), which you will mainly access through ``bot.wiki``.
  122. ``bot.wiki`` provides three methods for the management of Sites -
  123. ``get_site()``, ``add_site()``, and ``remove_site()``. Sites are objects that
  124. simply represent a MediaWiki site. A single instance of EarwigBot (i.e. a
  125. single *working directory*) is expected to relate to a single site or group of
  126. sites using the same login info (like all WMF wikis with CentralAuth).
  127. Load your default site (the one that you picked during setup) with
  128. ``site = bot.wiki.get_site()``.
  129. Not all aspects of the toolset are covered in the docs. Explore `its code and
  130. docstrings`_ to learn how to use it in a more hands-on fashion. For reference,
  131. ``bot.wiki`` is an instance of ``earwigbot.wiki.SitesDB`` tied to the
  132. ``sites.db`` file in the bot's working directory.
  133. Footnotes
  134. ---------
  135. - Questions, comments, or suggestions about the documentation? `Let me know`_
  136. so I can improve it for other people.
  137. .. [1] ``python setup.py install``/``develop`` may require root, or use the
  138. ``--user`` switch to install for the current user only.
  139. .. _EarwigBot: https://en.wikipedia.org/wiki/User:EarwigBot
  140. .. _Python: https://python.org/
  141. .. _Wikipedia: https://en.wikipedia.org/
  142. .. _IRC: https://en.wikipedia.org/wiki/Internet_Relay_Chat
  143. .. _PyPI: https://packages.python.org/earwigbot
  144. .. _Pywikibot: https://www.mediawiki.org/wiki/Manual:Pywikibot
  145. .. _copyright violation detector: https://en.wikipedia.org/wiki/Wikipedia:Bots/Requests_for_approval/EarwigBot_1
  146. .. _several ongoing tasks: https://en.wikipedia.org/wiki/User:EarwigBot#Tasks
  147. .. _my instance of EarwigBot: https://en.wikipedia.org/wiki/User:EarwigBot
  148. .. _earwigbot-plugins: https://github.com/earwig/earwigbot-plugins
  149. .. _Python Package Index: https://pypi.python.org/pypi/earwigbot
  150. .. _get pip: https://pypi.python.org/pypi/pip
  151. .. _this StackOverflow post: https://stackoverflow.com/questions/6504810/how-to-install-lxml-on-ubuntu/6504860#6504860
  152. .. _git flow: https://nvie.com/posts/a-successful-git-branching-model/
  153. .. _explanation of YAML: https://en.wikipedia.org/wiki/YAML
  154. .. _earwigbot.bot.Bot: https://github.com/earwig/earwigbot/blob/develop/earwigbot/bot.py
  155. .. _earwigbot.config.BotConfig: https://github.com/earwig/earwigbot/blob/develop/earwigbot/config.py
  156. .. _earwigbot.commands.Command: https://github.com/earwig/earwigbot/blob/develop/earwigbot/commands/__init__.py
  157. .. _test: https://github.com/earwig/earwigbot/blob/develop/earwigbot/commands/test.py
  158. .. _chanops: https://github.com/earwig/earwigbot/blob/develop/earwigbot/commands/chanops.py
  159. .. _afc_status: https://github.com/earwig/earwigbot-plugins/blob/develop/commands/afc_status.py
  160. .. _earwigbot.tasks.Task: https://github.com/earwig/earwigbot/blob/develop/earwigbot/tasks/__init__.py
  161. .. _wikiproject_tagger: https://github.com/earwig/earwigbot/blob/develop/earwigbot/tasks/wikiproject_tagger.py
  162. .. _afc_statistics: https://github.com/earwig/earwigbot-plugins/blob/develop/tasks/afc_statistics.py
  163. .. _its code and docstrings: https://github.com/earwig/earwigbot/tree/develop/earwigbot/wiki
  164. .. _Let me know: ben.kurtovic@gmail.com