Quellcode durchsuchen

More reference fixes

tags/v0.1^2
Ben Kurtovic vor 12 Jahren
Ursprung
Commit
8d0a50970e
2 geänderte Dateien mit 114 neuen und 106 gelöschten Zeilen
  1. +2
    -2
      docs/tips.rst
  2. +112
    -104
      docs/toolset.rst

+ 2
- 2
docs/tips.rst Datei anzeigen

@@ -37,8 +37,8 @@ Tips
.. rubric:: Footnotes

.. [1] In reality, all this does is call :py:meth:`bot.commands.load()
<earwigbot.commands.BaseCommand.load>` and
:py:meth:`bot.tasks.load() <earwigbot.tasks.BaseTask.load>`!
<earwigbot.managers._ResourceManager.load>` and
:py:meth:`bot.tasks.load() <earwigbot.managers._ResourceManager.load>`!

.. _logging: http://docs.python.org/library/logging.html
.. _!git plugin: https://github.com/earwig/earwigbot-plugins/blob/develop/commands/git.py


+ 112
- 104
docs/toolset.rst Datei anzeigen

@@ -6,12 +6,12 @@ EarwigBot's answer to the `Pywikipedia framework`_ is the Wiki Toolset
:py:attr:`bot.wiki <earwigbot.bot.Bot.wiki>`.

:py:attr:`bot.wiki <earwigbot.bot.Bot.wiki>` provides three methods for the
management of Sites - :py:meth:`~earwigbot.wiki.SiteDB.get_site`,
:py:meth:`~earwigbot.wiki.SiteDB.add_site`, and
:py:meth:`~earwigbot.wiki.SiteDB.remove_site`. Sites are objects that simply
represent a MediaWiki site. A single instance of EarwigBot (i.e. a single
*working directory*) is expected to relate to a single site or group of sites
using the same login info (like all WMF wikis with CentralAuth).
management of Sites - :py:meth:`~earwigbot.wiki.sitesdb.SitesDB.get_site`,
:py:meth:`~earwigbot.wiki.sitesdb.SitesDB.add_site`, and
:py:meth:`~earwigbot.wiki.sitesdb.SitesDB.remove_site`. Sites are objects that
simply represent a MediaWiki site. A single instance of EarwigBot (i.e. a
single *working directory*) is expected to relate to a single site or group of
sites using the same login info (like all WMF wikis with `CentralAuth`_).

Load your default site (the one that you picked during setup) with
``site = bot.wiki.get_site()``.
@@ -28,16 +28,16 @@ load a site with ``site = bot.wiki.get_site(name)``, where ``name`` might be
``site = bot.wiki.get_site(project="wikipedia", lang="en")``). Recall that not
giving any arguments to ``get_site()`` will return the default site.

:py:meth:`~earwigbot.wiki.SiteDB.add_site` is used to add new sites to the sites
database. It may be called with similar arguments as
:py:meth:`~earwigbot.wiki.SiteDB.get_site`, but the difference is important.
:py:meth:`~earwigbot.wiki.SiteDB.get_site` only needs enough information to
identify the site in its database, which is usually just its name; the database
stores all other necessary connection info. With
:py:meth:`~earwigbot.wiki.SiteDB.add_site`, you need to provide enough connection
info so the toolset can successfully access the site's API/SQL databases and
store that information for later. That might not be much; for WMF wikis, you
can usually use code like this::
:py:meth:`~earwigbot.wiki.sitesdb.SitesDB.add_site` is used to add new sites to
the sites database. It may be called with similar arguments as
:py:meth:`~earwigbot.wiki.sitesdb.SitesDB.get_site`, but the difference is
important. :py:meth:`~earwigbot.wiki.sitesdb.SitesDB.get_site` only needs
enough information to identify the site in its database, which is usually just
its name; the database stores all other necessary connection info. With
:py:meth:`~earwigbot.wiki.sitesdb.SitesDB.add_site`, you need to provide enough
connection info so the toolset can successfully access the site's API/SQL
databases and store that information for later. That might not be much; for WMF
wikis, you can usually use code like this::

project, lang = "wikipedia", "es"
try:
@@ -61,90 +61,95 @@ something more like::
sql = {host: "sql.mysite.net", db: db_name}
site = bot.wiki.add_site(base_url=base_url, script_path="/s", sql=sql)

:py:meth:`~earwigbot.wiki.SiteDB.remove_site` does the opposite of
:py:meth:`~earwigbot.wiki.SiteDB.add_site`: give it a site's name or a
project/lang pair like :py:meth:`~earwigbot.wiki.SiteDB.get_site` takes, and
it'll remove that site from the sites database.
:py:meth:`~earwigbot.wiki.sitesdb.SitesDB.remove_site` does the opposite of
:py:meth:`~earwigbot.wiki.sitesdb.SitesDB.add_site`: give it a site's name or a
project/lang pair like :py:meth:`~earwigbot.wiki.sitesdb.SitesDB.get_site`
takes, and it'll remove that site from the sites database.

Sites
~~~~~

:py:class:`earwigbot.wiki.Site` objects provide the following attributes:
:py:class:`earwigbot.wiki.Site <earwigbot.wiki.site.Site>` objects provide the
following attributes:

- :py:attr:`~earwigbot.wiki.Site.name`: the site's name (or "wikiid"), like
``"enwiki"``
- :py:attr:`~earwigbot.wiki.Site.project`: the site's project name, like
- :py:attr:`~earwigbot.wiki.site.Site.name`: the site's name (or "wikiid"),
like ``"enwiki"``
- :py:attr:`~earwigbot.wiki.site.Site.project`: the site's project name, like
``"wikipedia"``
- :py:attr:`~earwigbot.wiki.Site.lang`: the site's language code, like ``"en"``
- :py:attr:`~earwigbot.wiki.Site.domain`: the site's web domain, like
- :py:attr:`~earwigbot.wiki.site.Site.lang`: the site's language code, like
``"en"``
- :py:attr:`~earwigbot.wiki.site.Site.domain`: the site's web domain, like
``"en.wikipedia.org"``

and the following methods:

- :py:meth:`api_query(**kwargs) <earwigbot.wiki.Site.api_query>`: does an API
query with the given keyword arguments as params
- :py:meth:`sql_query(query, params=(), ...) <earwigbot.wiki.Site.sql_query>`:
does an SQL query and yields its results (as a generator)
- :py:meth:`~earwigbot.wiki.Site.get_replag`: returns the estimated database
replication lag (if we have the site's SQL connection info)
- :py:meth:`api_query(**kwargs) <earwigbot.wiki.site.Site.api_query>`: does an
API query with the given keyword arguments as params
- :py:meth:`sql_query(query, params=(), ...)
<earwigbot.wiki.site.Site.sql_query>`: does an SQL query and yields its
results (as a generator)
- :py:meth:`~earwigbot.wiki.site.Site.get_replag`: returns the estimated
database replication lag (if we have the site's SQL connection info)
- :py:meth:`namespace_id_to_name(id, all=False)
<earwigbot.wiki.Site.namespace_id_to_name>`: given a namespace ID, returns
the primary associated namespace name (or a list of all names when ``all`` is
``True``)
<earwigbot.wiki.site.Site.namespace_id_to_name>`: given a namespace ID,
returns the primary associated namespace name (or a list of all names when
``all`` is ``True``)
- :py:meth:`namespace_name_to_id(name)
<earwigbot.wiki.Site.namespace_name_to_id>`: given a namespace name, returns
the associated namespace ID
<earwigbot.wiki.site.Site.namespace_name_to_id>`: given a namespace name,
returns the associated namespace ID
- :py:meth:`get_page(title, follow_redirects=False)
<earwigbot.wiki.Site.get_page>`: returns a ``Page`` object for the given
title (or a :py:class:`~earwigbot.wiki.Category` object if the page's
namespace is "``Category:``")
<earwigbot.wiki.site.Site.get_page>`: returns a ``Page`` object for the given
title (or a :py:class:`~earwigbot.wiki.category.Category` object if the
page's namespace is "``Category:``")
- :py:meth:`get_category(catname, follow_redirects=False)
<earwigbot.wiki.Site.get_category>`: returns a ``Category`` object for the
given title (sans namespace)
- :py:meth:`get_user(username) <earwigbot.wiki.Site.get_user>`: returns a
:py:class:`~earwigbot.wiki.User` object for the given username
<earwigbot.wiki.site.Site.get_category>`: returns a ``Category`` object for
the given title (sans namespace)
- :py:meth:`get_user(username) <earwigbot.wiki.site.Site.get_user>`: returns a
:py:class:`~earwigbot.wiki.user.User` object for the given username

Pages and categories
~~~~~~~~~~~~~~~~~~~~

Create :py:class:`earwigbot.wiki.Page` objects with
:py:meth:`site.get_page(title) <earwigbot.wiki.Site.get_page>`,
:py:meth:`page.toggle_talk() <earwigbot.wiki.Page.toggle_talk>`,
:py:meth:`user.get_userpage() <earwigbot.wiki.User.get_userpage>`, or
:py:meth:`user.get_talkpage() <earwigbot.wiki.User.get_talkpage>`. They provide
the following attributes:

- :py:attr:`~earwigbot.wiki.Page.title`: the page's title, or pagename
- :py:attr:`~earwigbot.wiki.Page.exists`: whether the page exists
- :py:attr:`~earwigbot.wiki.Page.pageid`: an integer ID representing the page
- :py:attr:`~earwigbot.wiki.Page.url`: the page's URL
- :py:attr:`~earwigbot.wiki.Page.namespace`: the page's namespace as an integer
- :py:attr:`~earwigbot.wiki.Page.protection`: the page's current protection
status
- :py:attr:`~earwigbot.wiki.Page.is_talkpage`: ``True`` if the page is a
Create :py:class:`earwigbot.wiki.Page <earwigbot.wiki.page.Page>` objects with
:py:meth:`site.get_page(title) <earwigbot.wiki.site.Site.get_page>`,
:py:meth:`page.toggle_talk() <earwigbot.wiki.page.Page.toggle_talk>`,
:py:meth:`user.get_userpage() <earwigbot.wiki.user.User.get_userpage>`, or
:py:meth:`user.get_talkpage() <earwigbot.wiki.user.User.get_talkpage>`. They
provide the following attributes:

- :py:attr:`~earwigbot.wiki.page.Page.title`: the page's title, or pagename
- :py:attr:`~earwigbot.wiki.page.Page.exists`: whether the page exists
- :py:attr:`~earwigbot.wiki.page.Page.pageid`: an integer ID representing the
page
- :py:attr:`~earwigbot.wiki.page.Page.url`: the page's URL
- :py:attr:`~earwigbot.wiki.page.Page.namespace`: the page's namespace as an
integer
- :py:attr:`~earwigbot.wiki.page.Page.protection`: the page's current
protection status
- :py:attr:`~earwigbot.wiki.page.Page.is_talkpage`: ``True`` if the page is a
talkpage, else ``False``
- :py:attr:`~earwigbot.wiki.Page.is_redirect`: ``True`` if the page is a
- :py:attr:`~earwigbot.wiki.page.Page.is_redirect`: ``True`` if the page is a
redirect, else ``False``

and the following methods:

- :py:meth:`~earwigbot.wiki.Page.reload`: forcibly reload the page's attributes
(emphasis on *reload* - this is only necessary if there is reason to believe
they have changed)
- :py:meth:`toggle_talk(...) <earwigbot.wiki.Page.toggle_talk>`: returns a
- :py:meth:`~earwigbot.wiki.page.Page.reload`: forcibly reload the page's
attributes (emphasis on *reload* - this is only necessary if there is reason
to believe they have changed)
- :py:meth:`toggle_talk(...) <earwigbot.wiki.page.Page.toggle_talk>`: returns a
content page's talk page, or vice versa
- :py:meth:`~earwigbot.wiki.Page.get`: returns page content
- :py:meth:`~earwigbot.wiki.Page.get_redirect_target`: if the page is a
- :py:meth:`~earwigbot.wiki.page.Page.get`: returns page content
- :py:meth:`~earwigbot.wiki.page.Page.get_redirect_target`: if the page is a
redirect, returns its destination
- :py:meth:`~earwigbot.wiki.Page.get_creator`: returns a
:py:class:`~earwigbot.wiki.User` object representing the first user to edit
the page
- :py:meth:`~earwigbot.wiki.page.Page.get_creator`: returns a
:py:class:`~earwigbot.wiki.user.User` object representing the first user to
edit the page
- :py:meth:`edit(text, summary, minor=False, bot=True, force=False)
<earwigbot.wiki.Page.edit>`: replaces the page's content with ``text`` or
creates a new page
<earwigbot.wiki.page.Page.edit>`: replaces the page's content with ``text``
or creates a new page
- :py:meth:`add_section(text, title, minor=False, bot=True, force=False)
<earwigbot.wiki.Page.add_section>`: adds a new section named ``title`` at the
bottom of the page
<earwigbot.wiki.page.Page.add_section>`: adds a new section named ``title``
at the bottom of the page
- :py:meth:`copyvio_check(...)
<earwigbot.wiki.copyvios.CopyvioMixin.copyvio_check>`: checks the page for
copyright violations
@@ -153,51 +158,53 @@ and the following methods:
:py:meth:`~earwigbot.wiki.copyvios.CopyvioMixin.copyvio_check`, but
against a specific URL

Additionally, :py:class:`~earwigbot.wiki.Category` objects (created with
:py:meth:`site.get_category(name) <earwigbot.wiki.Site.get_category>` or
:py:meth:`site.get_page(title) <earwigbot.wiki.Site.get_page>` where ``title``
is in the ``Category:`` namespace) provide the following additional method:
Additionally, :py:class:`~earwigbot.wiki.category.Category` objects (created
with :py:meth:`site.get_category(name) <earwigbot.wiki.site.Site.get_category>`
or :py:meth:`site.get_page(title) <earwigbot.wiki.site.Site.get_page>` where
``title`` is in the ``Category:`` namespace) provide the following additional
method:

- :py:meth:`get_members(use_sql=False, limit=None)
<earwigbot.wiki.Category.get_members>`: returns a list of page titles in the
category (limit is ``50`` by default if using the API)
<earwigbot.wiki.category.Category.get_members>`: returns a list of page
titles in the category (limit is ``50`` by default if using the API)

Users
~~~~~

Create :py:class:`earwigbot.wiki.User` objects with
:py:meth:`site.get_user(name) <earwigbot.wiki.Site.get_user>` or
:py:meth:`page.get_creator() <earwigbot.wiki.Page.get_creator>`. They provide
the following attributes:
Create :py:class:`earwigbot.wiki.User <earwigbot.wiki.user.User>` objects with
:py:meth:`site.get_user(name) <earwigbot.wiki.site.Site.get_user>` or
:py:meth:`page.get_creator() <earwigbot.wiki.page.Page.get_creator>`. They
provide the following attributes:

- :py:attr:`~earwigbot.wiki.User.name`: the user's username
- :py:attr:`~earwigbot.wiki.User.exists`: ``True`` if the user exists, or
- :py:attr:`~earwigbot.wiki.user.User.name`: the user's username
- :py:attr:`~earwigbot.wiki.user.User.exists`: ``True`` if the user exists, or
``False`` if they do not
- :py:attr:`~earwigbot.wiki.User.userid`: an integer ID representing the user
- :py:attr:`~earwigbot.wiki.User.blockinfo`: information about any current
- :py:attr:`~earwigbot.wiki.user.User.userid`: an integer ID representing the
user
- :py:attr:`~earwigbot.wiki.user.User.blockinfo`: information about any current
blocks on the user (``False`` if no block, or a dict of
``{"by": blocking_user, "reason": block_reason,
"expiry": block_expire_time}``)
- :py:attr:`~earwigbot.wiki.User.groups`: a list of the user's groups
- :py:attr:`~earwigbot.wiki.User.rights`: a list of the user's rights
- :py:attr:`~earwigbot.wiki.User.editcount`: the number of edits made by the
user
- :py:attr:`~earwigbot.wiki.User.registration`: the time the user registered as
a :py:obj:`time.struct_time`
- :py:attr:`~earwigbot.wiki.User.emailable`: ``True`` if you can email the
- :py:attr:`~earwigbot.wiki.user.User.groups`: a list of the user's groups
- :py:attr:`~earwigbot.wiki.user.User.rights`: a list of the user's rights
- :py:attr:`~earwigbot.wiki.user.User.editcount`: the number of edits made by
the user
- :py:attr:`~earwigbot.wiki.user.User.registration`: the time the user
registered as a :py:obj:`time.struct_time`
- :py:attr:`~earwigbot.wiki.user.User.emailable`: ``True`` if you can email the
user, ``False`` if you cannot
- :py:attr:`~earwigbot.wiki.User.gender`: the user's gender (``"male"``,
- :py:attr:`~earwigbot.wiki.user.User.gender`: the user's gender (``"male"``,
``"female"``, or ``"unknown"``)

and the following methods:

- :py:meth:`~earwigbot.wiki.User.reload`: forcibly reload the user's attributes
(emphasis on *reload* - this is only necessary if there is reason to believe
they have changed)
- :py:meth:`~earwigbot.wiki.User.get_userpage`: returns a
:py:class:`~earwigbot.wiki.Page` object representing the user's userpage
- :py:meth:`~earwigbot.wiki.User.get_talkpage`: returns a
:py:class:`~earwigbot.wiki.Page` object representing the user's talkpage
- :py:meth:`~earwigbot.wiki.user.User.reload`: forcibly reload the user's
attributes (emphasis on *reload* - this is only necessary if there is reason
to believe they have changed)
- :py:meth:`~earwigbot.wiki.user.User.get_userpage`: returns a
:py:class:`~earwigbot.wiki.page.Page` object representing the user's userpage
- :py:meth:`~earwigbot.wiki.user.User.get_talkpage`: returns a
:py:class:`~earwigbot.wiki.page.Page` object representing the user's talkpage

Additional features
~~~~~~~~~~~~~~~~~~~
@@ -205,8 +212,9 @@ Additional features
Not all aspects of the toolset are covered here. Explore `its code and
docstrings`_ to learn how to use it in a more hands-on fashion. For reference,
:py:attr:`bot.wiki <earwigbot.bot.Bot.wiki>` is an instance of
:py:class:`earwigbot.wiki.SitesDB` tied to the :file:`sites.db` file in the
bot's working directory.
:py:class:`earwigbot.wiki.SitesDB <earwigbot.wiki.sitesdb.SitesDB>` tied to the
:file:`sites.db` file in the bot's working directory.

.. _Pywikipedia framework: http://pywikipediabot.sourceforge.net/
.. _CentralAuth: http://www.mediawiki.org/wiki/Extension:CentralAuth
.. _its code and docstrings: https://github.com/earwig/earwigbot/tree/develop/earwigbot/wiki

Laden…
Abbrechen
Speichern