A Python robot that edits Wikipedia and interacts with people over IRC https://en.wikipedia.org/wiki/User:EarwigBot
選択できるのは25トピックまでです。 トピックは、先頭が英数字で、英数字とダッシュ('-')を使用した35文字以内のものにしてください。

toolset.rst 11 KiB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222
  1. The Wiki Toolset
  2. ================
  3. EarwigBot's answer to the `Pywikipedia framework`_ is the Wiki Toolset
  4. (:py:mod:`earwigbot.wiki`), which you will mainly access through
  5. :py:attr:`bot.wiki <earwigbot.bot.Bot.wiki>`.
  6. :py:attr:`bot.wiki <earwigbot.bot.Bot.wiki>` provides three methods for the
  7. management of Sites - :py:meth:`~earwigbot.wiki.sitesdb.SitesDB.get_site`,
  8. :py:meth:`~earwigbot.wiki.sitesdb.SitesDB.add_site`, and
  9. :py:meth:`~earwigbot.wiki.sitesdb.SitesDB.remove_site`. Sites are objects that
  10. simply represent a MediaWiki site. A single instance of EarwigBot (i.e. a
  11. single *working directory*) is expected to relate to a single site or group of
  12. sites using the same login info (like all WMF wikis with `CentralAuth`_).
  13. Load your default site (the one that you picked during setup) with
  14. ``site = bot.wiki.get_site()``.
  15. Dealing with other sites
  16. ~~~~~~~~~~~~~~~~~~~~~~~~
  17. *Skip this section if you're only working with one site.*
  18. If a site is *already known to the bot* (meaning that it is stored in the
  19. :file:`sites.db` file, which includes just your default wiki at first), you can
  20. load a site with ``site = bot.wiki.get_site(name)``, where ``name`` might be
  21. ``"enwiki"`` or ``"frwiktionary"`` (you can also do
  22. ``site = bot.wiki.get_site(project="wikipedia", lang="en")``). Recall that not
  23. giving any arguments to ``get_site()`` will return the default site.
  24. :py:meth:`~earwigbot.wiki.sitesdb.SitesDB.add_site` is used to add new sites to
  25. the sites database. It may be called with similar arguments as
  26. :py:meth:`~earwigbot.wiki.sitesdb.SitesDB.get_site`, but the difference is
  27. important. :py:meth:`~earwigbot.wiki.sitesdb.SitesDB.get_site` only needs
  28. enough information to identify the site in its database, which is usually just
  29. its name; the database stores all other necessary connection info. With
  30. :py:meth:`~earwigbot.wiki.sitesdb.SitesDB.add_site`, you need to provide enough
  31. connection info so the toolset can successfully access the site's API/SQL
  32. databases and store that information for later. That might not be much; for WMF
  33. wikis, you can usually use code like this::
  34. project, lang = "wikipedia", "es"
  35. try:
  36. site = bot.wiki.get_site(project=project, lang=lang)
  37. except earwigbot.SiteNotFoundError:
  38. # Load site info from http://es.wikipedia.org/w/api.php:
  39. site = bot.wiki.add_site(project=project, lang=lang)
  40. This works because EarwigBot assumes that the URL for the site is
  41. ``"//{lang}.{project}.org"`` and the API is at ``/w/api.php``; this might
  42. change if you're dealing with non-WMF wikis, where the code might look
  43. something more like::
  44. project, lang = "mywiki", "it"
  45. try:
  46. site = bot.wiki.get_site(project=project, lang=lang)
  47. except earwigbot.SiteNotFoundError:
  48. # Load site info from http://mysite.net/mywiki/it/s/api.php:
  49. base_url = "http://mysite.net/" + project + "/" + lang
  50. db_name = lang + project + "_p"
  51. sql = {host: "sql.mysite.net", db: db_name}
  52. site = bot.wiki.add_site(base_url=base_url, script_path="/s", sql=sql)
  53. :py:meth:`~earwigbot.wiki.sitesdb.SitesDB.remove_site` does the opposite of
  54. :py:meth:`~earwigbot.wiki.sitesdb.SitesDB.add_site`: give it a site's name or a
  55. project/lang pair like :py:meth:`~earwigbot.wiki.sitesdb.SitesDB.get_site`
  56. takes, and it'll remove that site from the sites database.
  57. Sites
  58. ~~~~~
  59. :py:class:`earwigbot.wiki.Site <earwigbot.wiki.site.Site>` objects provide the
  60. following attributes:
  61. - :py:attr:`~earwigbot.wiki.site.Site.name`: the site's name (or "wikiid"),
  62. like ``"enwiki"``
  63. - :py:attr:`~earwigbot.wiki.site.Site.project`: the site's project name, like
  64. ``"wikipedia"``
  65. - :py:attr:`~earwigbot.wiki.site.Site.lang`: the site's language code, like
  66. ``"en"``
  67. - :py:attr:`~earwigbot.wiki.site.Site.domain`: the site's web domain, like
  68. ``"en.wikipedia.org"``
  69. and the following methods:
  70. - :py:meth:`api_query(**kwargs) <earwigbot.wiki.site.Site.api_query>`: does an
  71. API query with the given keyword arguments as params
  72. - :py:meth:`sql_query(query, params=(), ...)
  73. <earwigbot.wiki.site.Site.sql_query>`: does an SQL query and yields its
  74. results (as a generator)
  75. - :py:meth:`~earwigbot.wiki.site.Site.get_replag`: returns the estimated
  76. database replication lag (if we have the site's SQL connection info)
  77. - :py:meth:`namespace_id_to_name(id, all=False)
  78. <earwigbot.wiki.site.Site.namespace_id_to_name>`: given a namespace ID,
  79. returns the primary associated namespace name (or a list of all names when
  80. ``all`` is ``True``)
  81. - :py:meth:`namespace_name_to_id(name)
  82. <earwigbot.wiki.site.Site.namespace_name_to_id>`: given a namespace name,
  83. returns the associated namespace ID
  84. - :py:meth:`get_page(title, follow_redirects=False)
  85. <earwigbot.wiki.site.Site.get_page>`: returns a ``Page`` object for the given
  86. title (or a :py:class:`~earwigbot.wiki.category.Category` object if the
  87. page's namespace is "``Category:``")
  88. - :py:meth:`get_category(catname, follow_redirects=False)
  89. <earwigbot.wiki.site.Site.get_category>`: returns a ``Category`` object for
  90. the given title (sans namespace)
  91. - :py:meth:`get_user(username) <earwigbot.wiki.site.Site.get_user>`: returns a
  92. :py:class:`~earwigbot.wiki.user.User` object for the given username
  93. Pages and categories
  94. ~~~~~~~~~~~~~~~~~~~~
  95. Create :py:class:`earwigbot.wiki.Page <earwigbot.wiki.page.Page>` objects with
  96. :py:meth:`site.get_page(title) <earwigbot.wiki.site.Site.get_page>`,
  97. :py:meth:`page.toggle_talk() <earwigbot.wiki.page.Page.toggle_talk>`,
  98. :py:meth:`user.get_userpage() <earwigbot.wiki.user.User.get_userpage>`, or
  99. :py:meth:`user.get_talkpage() <earwigbot.wiki.user.User.get_talkpage>`. They
  100. provide the following attributes:
  101. - :py:attr:`~earwigbot.wiki.page.Page.site`: the page's corresponding
  102. :py:class:`~earwigbot.wiki.site.Site` object
  103. - :py:attr:`~earwigbot.wiki.page.Page.title`: the page's title, or pagename
  104. - :py:attr:`~earwigbot.wiki.page.Page.exists`: whether the page exists
  105. - :py:attr:`~earwigbot.wiki.page.Page.pageid`: an integer ID representing the
  106. page
  107. - :py:attr:`~earwigbot.wiki.page.Page.url`: the page's URL
  108. - :py:attr:`~earwigbot.wiki.page.Page.namespace`: the page's namespace as an
  109. integer
  110. - :py:attr:`~earwigbot.wiki.page.Page.protection`: the page's current
  111. protection status
  112. - :py:attr:`~earwigbot.wiki.page.Page.is_talkpage`: ``True`` if the page is a
  113. talkpage, else ``False``
  114. - :py:attr:`~earwigbot.wiki.page.Page.is_redirect`: ``True`` if the page is a
  115. redirect, else ``False``
  116. and the following methods:
  117. - :py:meth:`~earwigbot.wiki.page.Page.reload`: forcibly reloads the page's
  118. attributes (emphasis on *reload* - this is only necessary if there is reason
  119. to believe they have changed)
  120. - :py:meth:`toggle_talk(...) <earwigbot.wiki.page.Page.toggle_talk>`: returns a
  121. content page's talk page, or vice versa
  122. - :py:meth:`~earwigbot.wiki.page.Page.get`: returns page content
  123. - :py:meth:`~earwigbot.wiki.page.Page.get_redirect_target`: if the page is a
  124. redirect, returns its destination
  125. - :py:meth:`~earwigbot.wiki.page.Page.get_creator`: returns a
  126. :py:class:`~earwigbot.wiki.user.User` object representing the first user to
  127. edit the page
  128. - :py:meth:`edit(text, summary, minor=False, bot=True, force=False)
  129. <earwigbot.wiki.page.Page.edit>`: replaces the page's content with ``text``
  130. or creates a new page
  131. - :py:meth:`add_section(text, title, minor=False, bot=True, force=False)
  132. <earwigbot.wiki.page.Page.add_section>`: adds a new section named ``title``
  133. at the bottom of the page
  134. - :py:meth:`copyvio_check(...)
  135. <earwigbot.wiki.copyvios.CopyvioMixin.copyvio_check>`: checks the page for
  136. copyright violations
  137. - :py:meth:`copyvio_compare(url, ...)
  138. <earwigbot.wiki.copyvios.CopyvioMixin.copyvio_compare>`: checks the page like
  139. :py:meth:`~earwigbot.wiki.copyvios.CopyvioMixin.copyvio_check`, but
  140. against a specific URL
  141. Additionally, :py:class:`~earwigbot.wiki.category.Category` objects (created
  142. with :py:meth:`site.get_category(name) <earwigbot.wiki.site.Site.get_category>`
  143. or :py:meth:`site.get_page(title) <earwigbot.wiki.site.Site.get_page>` where
  144. ``title`` is in the ``Category:`` namespace) provide the following additional
  145. method:
  146. - :py:meth:`get_members(use_sql=False, limit=None)
  147. <earwigbot.wiki.category.Category.get_members>`: returns a list of page
  148. titles in the category (limit is ``50`` by default if using the API)
  149. Users
  150. ~~~~~
  151. Create :py:class:`earwigbot.wiki.User <earwigbot.wiki.user.User>` objects with
  152. :py:meth:`site.get_user(name) <earwigbot.wiki.site.Site.get_user>` or
  153. :py:meth:`page.get_creator() <earwigbot.wiki.page.Page.get_creator>`. They
  154. provide the following attributes:
  155. - :py:attr:`~earwigbot.wiki.user.User.name`: the user's username
  156. - :py:attr:`~earwigbot.wiki.user.User.exists`: ``True`` if the user exists, or
  157. ``False`` if they do not
  158. - :py:attr:`~earwigbot.wiki.user.User.userid`: an integer ID representing the
  159. user
  160. - :py:attr:`~earwigbot.wiki.user.User.blockinfo`: information about any current
  161. blocks on the user (``False`` if no block, or a dict of
  162. ``{"by": blocking_user, "reason": block_reason,
  163. "expiry": block_expire_time}``)
  164. - :py:attr:`~earwigbot.wiki.user.User.groups`: a list of the user's groups
  165. - :py:attr:`~earwigbot.wiki.user.User.rights`: a list of the user's rights
  166. - :py:attr:`~earwigbot.wiki.user.User.editcount`: the number of edits made by
  167. the user
  168. - :py:attr:`~earwigbot.wiki.user.User.registration`: the time the user
  169. registered as a :py:obj:`time.struct_time`
  170. - :py:attr:`~earwigbot.wiki.user.User.emailable`: ``True`` if you can email the
  171. user, ``False`` if you cannot
  172. - :py:attr:`~earwigbot.wiki.user.User.gender`: the user's gender (``"male"``,
  173. ``"female"``, or ``"unknown"``)
  174. and the following methods:
  175. - :py:meth:`~earwigbot.wiki.user.User.reload`: forcibly reloads the user's
  176. attributes (emphasis on *reload* - this is only necessary if there is reason
  177. to believe they have changed)
  178. - :py:meth:`~earwigbot.wiki.user.User.get_userpage`: returns a
  179. :py:class:`~earwigbot.wiki.page.Page` object representing the user's userpage
  180. - :py:meth:`~earwigbot.wiki.user.User.get_talkpage`: returns a
  181. :py:class:`~earwigbot.wiki.page.Page` object representing the user's talkpage
  182. Additional features
  183. ~~~~~~~~~~~~~~~~~~~
  184. Not all aspects of the toolset are covered here. Explore `its code and
  185. docstrings`_ to learn how to use it in a more hands-on fashion. For reference,
  186. :py:attr:`bot.wiki <earwigbot.bot.Bot.wiki>` is an instance of
  187. :py:class:`earwigbot.wiki.SitesDB <earwigbot.wiki.sitesdb.SitesDB>` tied to the
  188. :file:`sites.db` file in the bot's working directory.
  189. .. _Pywikipedia framework: http://pywikipediabot.sourceforge.net/
  190. .. _CentralAuth: http://www.mediawiki.org/wiki/Extension:CentralAuth
  191. .. _its code and docstrings: https://github.com/earwig/earwigbot/tree/develop/earwigbot/wiki