jenkins-bot has submitted this change and it was merged.
Change subject: [FEAT] bot: Explain and document Bot classes
......................................................................
[FEAT] bot: Explain and document Bot classes
There are a lot of different `Bot` classes and it might be confusing which
class does what and how they are supposed to be used. This is a first attempt
in explaining them.
Change-Id: I09b4751290e743aa2d7e2526a58f382b31c78ee7
---
M pywikibot/bot.py
1 file changed, 45 insertions(+), 1 deletion(-)
Approvals:
John Vandenberg: Looks good to me, approved
jenkins-bot: Verified
diff --git a/pywikibot/bot.py b/pywikibot/bot.py
index 6c334b6..dae9760 100644
--- a/pywikibot/bot.py
+++ b/pywikibot/bot.py
@@ -1,5 +1,49 @@
# -*- coding: utf-8 -*-
-"""User-interface related functions for building bots."""
+"""
+User-interface related functions for building bots.
+
+This module supports several different bot classes which could be used in
+conjunction. Each bot should subclass at least one of these four classes:
+
+* L{BaseBot}: Basic bot class in case where the site is handled differently,
+ like working on two sites in parallel.
+* L{SingleSiteBot}: Bot class which should only be run on a single site. They
+ usually store site specific content and thus can't be easily run when the
+ generator returns a page on another site. It has a property C{site} which
+ can also be changed. If the generator returns a page of a different site
+ it'll skip that page.
+* L{MultipleSitesBot}: Bot class which supports to be run on multiple sites
+ without the need to manually initialize it every time. It is not possible
to
+ set the C{site} property and it's deprecated to request it. Instead site of
+ the current page should be used. And out of C{run} that sit isn't defined.
+* L{Bot}: The previous base class which should be avoided. This class is mainly
+ used for bots which work with wikibase or together with an image
repository.
+
+Additionally there is the L{CurrentPageBot} class which automatically sets the
+current page to the page treated. It is recommended to use this class and to
+use C{treat_page} instead of C{treat} and C{put_current} instead of C{userPut}.
+It by default subclasses the C{BaseBot} class.
+
+With L{CurrentPageBot} it's possible to subclass one of the following classes
to
+filter the pages which are ultimately handled by C{treat_page}:
+
+* L{ExistingPageBot}: Only handle pages which do exist.
+* L{CreatingPageBot}: Only handle pages which do not exist.
+* L{RedirectPageBot}: Only handle pages which are redirect pages.
+* L{NoRedirectPageBot}: Only handle pages which are not redirect pages.
+* L{FollowRedirectPageBot}: If the generator returns a redirect page it'll
+ follow the redirect and instead work on the redirected class.
+
+It is possible to combine filters by subclassing multiple of them. They are
+new-style classes so when a class is first subclassing L{ExistingPageBot} and
+then L{FollowRedirectPageBot} it will also work on pages which do not exist
when
+a redirect pointed to that. If the order is inversed it'll first follow them
and
+then check whether they exist.
+
+Additionally there is the L{AutomaticTWSummaryBot} which subclasses
+L{CurrentPageBot} and automatically defines the summary when C{put_current} is
+used.
+"""
#
# (C) Pywikibot team, 2008-2015
#
--
To view, visit https://gerrit.wikimedia.org/r/237990
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings
Gerrit-MessageType: merged
Gerrit-Change-Id: I09b4751290e743aa2d7e2526a58f382b31c78ee7
Gerrit-PatchSet: 1
Gerrit-Project: pywikibot/core
Gerrit-Branch: master
Gerrit-Owner: XZise <commodorefabia...@gmx.de>
Gerrit-Reviewer: John Vandenberg <jay...@gmail.com>
Gerrit-Reviewer: Ladsgroup <ladsgr...@gmail.com>
Gerrit-Reviewer: jenkins-bot <>
_______________________________________________
MediaWiki-commits mailing list
MediaWiki-commits@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
