Help:Bots

The printable version is no longer supported and may have rendering errors. Please update your browser bookmarks and please use the default browser print function instead.

Bots (short for robots) are external tools that access the wiki in any manner other than the usual web interface. MediaWiki has an application programming interface (API) for this purpose. This API is a protocol external tools can use to request data from a MediaWiki wiki or perform changes to it.

The term "bot" is somewhat confusing. It may refer to anything that accesses the API, from advanced global find-and-replace tools (such as AutoWikiBrowser, known as AWB) to frameworks that let users perform a broad variety of automated tasks (such as Pywikibot, known as PWB). AWB and PWB, mentioned above, are the most popular tools referred to as "bots". If you wish to use either (or both), visit the respective pages for details.

Most regular users shouldn't need to run bots. Moreover, running a bot may require programming knowledge. Automated changes to wikis should be coordinated with local admins or other staff.

Best practices

These practices are courteous to your fellow wiki editors and allow the bot operator to more easily track down and fix any errors made by their bot.

Bot user accounts

If you intend to automate a lot of changes, you should create a separate bot account. It's a good idea to name it so it's clear it's a bot, and that it's your bot. The easiest way to do so is to take your username and append "Bot" for the name of the bot account.

If you want to run a bot on a wiki, you should notify your wiki manager (or a bureaucrat, if there is one). They can add your bot to the bot user group.

Having a separate bot account is helpful for a few reasons. First, it lets the bot operator more easily recognize and revert their bot's edits if needed, without accidentally reverting any edits made by their primary account. Bot accounts can also be added to the bot user group. By default, API edits by bot users are hidden in recent changes, which reduces clutter on that page. Users can toggle showing bot edits in RC with the "Show/hide bots" option or the equivalent filter in the new RC interface. If recent changes are showing edits by bot accounts, any such edits will be marked with b, like minor edits are marked with m.

Edit summaries

Bots should be configured to leave summaries for the actions they perform. For example, the summary could say, "Replaced Template:Old with Template:New", or "Trimming trailing whitespace". Summaries generally help users see at a glance what changes are being made to pages, and for bot edits, summaries also help track down and revert errors.

Choosing between AutoWikiBrowser (AWB) or Pywikibot (PWB)

When getting started with automation, one of the first decisions you must make is which bot tool to use. For most users, the choice is between AutoWikiBrowser (AWB), and Pywikibot (PWB). While many people use both, depending on the task, each tool has its pros and cons.

AWB

Pros:

Has a GUI instead of requiring to do everything through a command-line interface.
Easier setup & lower barrier to entry as a result.
Better at doing complex find-and-replace operations.

Cons:

Limited selection of generators, so editing lists of pages with complex criteria sometimes requires several steps.
AWB only has Windows executables, and needs Wine to run on Mac and Linux.

PWB

Pros:

Can delete, move, and create pages easily instead of just editing.
Once you are familiar with the command line interface & available options, it's fewer clicks to accomplish some of the tasks that both tools can do.
Can use a wider variety of page list generators.
Can be run on most operating systems without requiring extra tools.

Cons:

More difficult to set up and more difficult to learn.
Harder to preview changes before making them.

Custom bot development

Some advanced users choose to create their own bots and scripts to interact with the wiki. Such tools can be written in many languages, often JavaScript (to run in the browser) and Python (to work with PWB, or the mwclient and mwparserfromhell libraries). See the MediaWiki.org page on API clients for more information.

PyWikiBot

For all of those who are interested in using PWB. Here's a step-by-step guide:

Download Python. Should be a python 3.x version.

Check if Python was added to your windows path. ;C:\Python3x

To permanently modify the default environment variables, click Start and search for ‘edit environment variables’, or open System properties, Advanced system settings and click the Environment Variables button. In this dialog, you can add or modify User and System variables. To change System variables, you need non-restricted access to your machine (i.e. Administrator rights).

Download Request. This is a python module required for PWB.

From now on you need CMD, the windows command line. Install the "request" module via python setup.py install. You can change the directory with cd to go wherever you unpacked the "request" setup.py.

Download PWB and unpack it somewhere (e.g. under C:/Programs/PWB)

Create an empty file called "dota2_family.py" in C:/Programs/PWB/pywikibot/families/ and paste in the following content:

# -*- coding: utf-8 -*-

from pywikibot import family
from pywikibot.tools import deprecated

class Family(family.Family):  # noqa: D101

    name = 'dota2'
    langs = {
            'en': 'dota2.fandom.com',
            'pt': 'dota2.fandom.com',
            'ru': 'dota2.fandom.com',
            'zh': 'dota2.fandom.com',
        }

    def scriptpath(self, code):
        return {
            'en': '',
            'pt': '/pt',
            'ru': '/ru',
            'zh': '/zh',
        }[code]

    def protocol(self, code):
        return 'HTTPS'

Run python generate_user_files.py from your PWB folder via CMD. Follow the instructions.

Optionally delete the two example files.

Open the user-config.py and do some modifications: These were my modifications. Of course you are neither admin (sysop) on every page, nor do you have a need for listing all of languages. Just take what you need.

# If you use either of these functions to define the family to work on by
# default (the ‘family’ variable below), you must place the function call
# before the definition of the ‘family’ variable.
family = 'dota2'

# The language code of the site we're working on.
mylang = 'en'

# The dictionary usernames should contain a username for each site where you
# have a bot account. If you have a unique username for all languages of a
# family , you can use '*'

password_file = "user-password.py"

usernames['dota2']['en'] = u'Username'
usernames['dota2']['pt'] = u'Username'
usernames['dota2']['ru'] = u'Username'
usernames['dota2']['zh'] = u'Username'
sysopnames['dota2']['en'] = u'Username'
sysopnames['dota2']['pt'] = u'Username'
sysopnames['dota2']['ru'] = u'Username'
sysopnames['dota2']['zh'] = u'Username'

Set up a new bot access here: Special:BotPasswords

Create a new password file called user-password.py in the folder with the following content. Replace <Text> with the details you defined for the bot access:

("<Username>", BotPassword("<Botname>", "<Botpassword>"))

Done, you can make a checkrun with such a command. It will list all pages that contain "Slar" (e.g. Slark and Slardar):

python pwb.py listpages -format:3 -titleregex:'Slar' -start:!

AutoWikiBot

mwclient

Official documentation: Read the Docs

mwclient is a more lightweight alternative to PyWikiBot. It does not come with preinstalled scripts.

Download Python (any version >2.7 should work).
Install mwclient by entering pip3 install mwclient (pip install mwclient if you are using Python 2.x)
Create a new text file and save it with the .py extension.
Write your script in the file you just created.
Run it by entering python3 path/to/your/file.py (python path/to/your/file.py for Python version 2.x)

Explanation

The mwclient module is based around the Site() object. This object needs to be setup at the beginning of your script:

import mwclient


site = mwclient.Site('dota2.gamepedia.com', path='/')

To authenticate yourself you use the Site.login() method. The needed bot account can be created from Special:BotPasswords.

site.login('bot_user_name', 'bot_password')

From there you can use the the methods explained in the documentation.

Example

import mwclient


site = mwclient.Site('dota2.gamepedia.com', path='/')
site.login('bot_user_name', 'bot_password')


page = site.Pages['Evil Geniuses']
text = page.text()
text = text.replace('Arteezy', 'Fear')
page.save(text, summary='Bot: Arteezy left the team.')