Using pywikibot as library¶
Pywikibot provides bot classes to develop your own script easily. Here is a minimal example script which shows their usage:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 | import pywikibot
from pywikibot import pagegenerators
from pywikibot.bot import ExistingPageBot
class MyBot(ExistingPageBot):
update_options = {
'text': 'This is a test text',
'summary': 'Bot: a bot test edit with Pywikbot.',
}
def treat_page(self):
"""Load the given page, do some changes, and save it."""
text = self.current_page.text
text += '\n' + self.opt.text
self.put_current(text, summary=self.opt.summary)
def main():
"""Parse command line arguments and invoke bot."""
options = {}
gen_factory = pagegenerators.GeneratorFactory()
# Option parsing
local_args = pywikibot.handle_args(args) # global options
local_args = gen_factory.handle_args(local_args) # generators options
for arg in local_args:
opt, sep, value = arg.partition(':')
if opt in ('-summary', '-text'):
options[opt[1:]] = value
MyBot(generator=gen_factory.getCombinedGenerator(), **options).run()
if __name == '__main__':
main()
|
The script can be invoked from commandline like:
python mybot -site:wikipedia:test -page:Sandbox -text:"A text added to the sandbox"
Explanations:
- 1-3
Import necessary framework code parts
- 5
The bot is derived from ExistingPageBot. All pages from generator which does not exists are skipped.
- 7
Every Bot has an always option which autoconfirms any changes if set to True. To expand all available options of a bot and set the default values of them, use
update_options
attribute or updateavailable_options
like it is shown in BasicBot below.- 12
All changes for each page are made in this method.
- 14
currentpage
is the currentpywikibot.Page
object from generator.- 15
All bot options which are passed to the bot class when instantiating it are accessable via opt attribute.
opt.always
,opt.text
andopt.summary
are all available options for this bot class.- 16
Save the changes to the live wiki.
- 18
Parse command line options inside this function.
- 20
A dict which holds all options for the bot.
- 21
pywikibot.pagegenerators.GeneratorFactory
supports generators and filter options.- 23
Pywikibot provides global options like site specification or a simulate switch to prevent live wiki changes.
- 24
Generators and filter options of
pywikibot.pagegenerators
are parsed here.- 25
Local options which are are available for the current bot are parsed in this loop.
- 29
Create the bot passing keyword only parameters and run it.
Basic script¶
scripts.basic
is a more advanced sample script and shipped
with the scripts folder. Here is the content:
#!/usr/bin/python
"""
An incomplete sample script.
This is not a complete bot; rather, it is a template from which simple
bots can be made. You can rename it to mybot.py, then edit it in
whatever way you want.
Use global -simulate option for test purposes. No changes to live wiki
will be done.
The following parameters are supported:
-always The bot won't ask for confirmation when putting a page
-text: Use this text to be added; otherwise 'Test' is used
-replace: Don't add text but replace it
-top Place additional text on top of the page
-summary: Set the action summary message for the edit.
All settings can be made either by giving option with the command line
or with a settings file which is scripts.ini by default. If you don't
want the default values you can add any option you want to change to
that settings file below the [basic] section like:
[basic] ; inline comments starts with colon
# This is a commend line. Assignments may be done with '=' or ':'
text: A text with line break and
continuing on next line to be put
replace: yes ; yes/no, on/off, true/false and 1/0 is also valid
summary = Bot: My first test edit with pywikibot
Every script has its own section with the script name as header.
In addition the following generators and filters are supported but
cannot be set by settings file:
¶ms;
"""
#
# (C) Pywikibot team, 2006-2021
#
# Distributed under the terms of the MIT license.
#
import pywikibot
from pywikibot import pagegenerators
from pywikibot.bot import (
AutomaticTWSummaryBot,
ConfigParserBot,
ExistingPageBot,
NoRedirectPageBot,
SingleSiteBot,
)
# This is required for the text that is shown when you run this script
# with the parameter -help.
docuReplacements = {'¶ms;': pagegenerators.parameterHelp} # noqa: N816
class BasicBot(
# Refer pywikobot.bot for generic bot classes
SingleSiteBot, # A bot only working on one site
ConfigParserBot, # A bot which reads options from scripts.ini setting file
# CurrentPageBot, # Sets 'current_page'. Process it in treat_page method.
# # Not needed here because we have subclasses
ExistingPageBot, # CurrentPageBot which only treats existing pages
NoRedirectPageBot, # CurrentPageBot which only treats non-redirects
AutomaticTWSummaryBot, # Automatically defines summary; needs summary_key
):
"""
An incomplete sample bot.
:ivar summary_key: Edit summary message key. The message that should be
used is placed on /i18n subdirectory. The file containing these
messages should have the same name as the caller script (i.e. basic.py
in this case). Use summary_key to set a default edit summary message.
:type summary_key: str
"""
summary_key = 'basic-changing'
update_options = {
'replace': False, # delete old text and write the new text
'summary': None, # your own bot summary
'text': 'Test', # add this text from option. 'Test' is default
'top': False, # append text on top of the page
}
def treat_page(self) -> None:
"""Load the given page, do some changes, and save it."""
text = self.current_page.text
################################################################
# NOTE: Here you can modify the text in whatever way you want. #
################################################################
# If you find out that you do not want to edit this page, just return.
# Example: This puts Text on a page.
# Retrieve your private option
# Use your own text or use the default 'Test'
text_to_add = self.opt.text
if self.opt.replace:
# replace the page text
text = text_to_add
elif self.opt.top:
# put text on top
text = text_to_add + text
else:
# put text on bottom
text += text_to_add
# if summary option is None, it takes the default i18n summary from
# i18n subdirectory with summary_key as summary key.
self.put_current(text, summary=self.opt.summary)
def main(*args: str) -> None:
"""
Process command line arguments and invoke bot.
If args is an empty list, sys.argv is used.
:param args: command line arguments
"""
options = {}
# Process global arguments to determine desired site
local_args = pywikibot.handle_args(args)
# This factory is responsible for processing command line arguments
# that are also used by other scripts and that determine on which pages
# to work on.
gen_factory = pagegenerators.GeneratorFactory()
# Process pagegenerators arguments
local_args = gen_factory.handle_args(local_args)
# Parse your own command line arguments
for arg in local_args:
arg, sep, value = arg.partition(':')
option = arg[1:]
if option in ('summary', 'text'):
if not value:
pywikibot.input('Please enter a value for ' + arg)
options[option] = value
# take the remaining options as booleans.
# You will get a hint if they aren't pre-defined in your bot class
else:
options[option] = True
# The preloading option is responsible for downloading multiple
# pages from the wiki simultaneously.
gen = gen_factory.getCombinedGenerator(preload=True)
if gen:
# pass generator and private options to the bot
bot = BasicBot(generator=gen, **options)
bot.run() # guess what it does
else:
pywikibot.bot.suggest_help(missing_generator=True)
if __name__ == '__main__':
main()
Note
Please also see the documentation at Create your own script