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 #