Pywikibot

From Gamepedia Help Wiki
Jump to: navigation, search

Pywikibot, or PWB is one of the common bots available to users. This article will serve as a comprehensive guide for how to set up and run Pywikibot on Gamepedia wikis for Windows-based operating systems.

First-time setup[edit | edit source]

  1. Download Python on your computer. You should probably get the latest version, but any 3.x version will work. From the download links, using one labelled as an "installer" will make things easier. After it's downloaded, install Python by running that file.
  2. Download Requests. This is a Python module that PWB needs in order to run. Extract the zip file somewhere - it doesn't matter where, as long as you know how to get back to it. You should also rename the folder to have an easy-to-type name. The next step will cover installing it.
  3. Open Command Prompt (Windows+r, then type cmd into the run menu, or search for "command prompt" from your start menu).
    1. From here, use the cd command to navigate to where you extracted the file in the previous step, specifically, the folder which has the setup.py file. For me, I renamed the extracted folder to simply "requests", and left it in my Downloads folder, so I would type: cd Downloads\requests.
    2. Now run the setup file by typing in python setup.py install (if you get the message "'python' is not recognized as an internal or external command" then use py setup.py install instead). If you receive the message "error: can't create or remove files in install directory", then you need to run command prompt in administrator mode. Find command prompt in your start menu, then right-click and select "run as administrator". Repeat steps 3.1 and 3.2 from here.
  4. Download Pywikibot and extract the contents somewhere (I put mine in C:\Program Files\PWB, but anywhere is fine as long as you can use cd to get to it, as in step 3.1). This folder will be referred to as your main pywikibot folder.

Creating and using a bot password[edit | edit source]

Figure 1: Bot name (green), account name (blue), and bot password (red)
  1. Create a bot account. To do this, create a new Gamepedia/Twitch account. Bot account names should make it reasonably clear that the account is a bot and who it belongs to, such as Widowbot, Cadsbot, or MrBot5. Then talk to the the administration of the wiki(s) you intend to use the bot on about giving the account bot rights.
  2. Go to Special:BotPasswords on any wiki while logged into the bot account. Type a name for this bot into the box and hit Create (for simplicity, you can just use the bot's name). Here you will see a list of permissions. Most bots will only need "High-volume editing", "Edit existing pages", and "Create, edit, and move pages". Check these and others if you need them, and hit the Create button at the bottom of the page. You should get a screen similar to that on the right. The password here is only used for logging into your bot via external programs - when logging in through the browser, use its normal password.
  3. Navigate to your PWB files, and create a file called user-password.py. Open it with any text editing program and fill it in as follows:
("account name", BotPassword("bot name", "bot password"))

For example, using Figure 1:

("MrBot5", BotPassword("testbot", "qscnb8pdpoisgibe8trfa59mv8ug1tat"))
It is not necessary to save this password if you aren't comfortable doing so, but you will have to type the password out every time you give the bot a command otherwise. You can add more users and passwords to this list by adding another line (no commas or other separators). Assume everything in this file is case-sensitive, including names.

Creating a family file[edit | edit source]

Family files define the wiki(s) that you are working on. Each wiki you intend to use PWB on requires its own family file. In your main Pywikibot directory, navigate to a folder named "pywikibot", and then a folder inside that called "families". Create a new python file for the initial wiki you want to work on. The name of the file doesn't matter, as long as it ends with _family.py, but it should be one that's easy for you to remember and use, such as "ark_family.py" or "minecraft_family.py". Copy and paste the following code, changing mentions of "ark" to the wiki you wish to use:

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

from pywikibot import family
from pywikibot.tools import deprecated

class Family(family.Family):
    def __init__(self):
        family.Family.__init__(self)
        self.name = 'ark'
        self.langs = {
            'en': 'ark.gamepedia.com',
            #'es': 'ark-es.gamepedia.com',
            #'fr': 'ark-fr.gamepedia.com',
            #'ptbr': 'ark-ptbr.gamepedia.com',
        }

    def scriptpath(self, code):
        return {
            'en': '',
            #'es': '',
            #'fr': '',
            #'ptbr': '',
        }[code]

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

The alternate language wikis are commented out here, but show you how to add them to the family file if your wiki family has multiple languages. For other languages, refer to the List of ISO 639-1 codes

Setting up your user-config[edit | edit source]

  1. Return to command prompt, and use cd to navigate to your main pywikibot folder and type in py generate_user_files.py and follow the instructions.
  2. Your main pywikibot folder should now contain a file called user-config.py. Open it with any text editor. Near the top, you should find a section like this:
# 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 = 'ark'

# 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 '*'
usernames['ark']['en'] = u'MrBot5'
After modifying this section to contain your password file and any other wikis/families you might use the bot on, it should look something like this:
# 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 = 'ark'

# 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['ark']['en'] = u'MrBot5'
usernames['ark']['es'] = u'MrBot5'
usernames['ark']['fr'] = u'MrBot5'
usernames['ark']['ptbr'] = u'MrBot5'
sysopnames['ark']['en'] = u'Mr_Pie_5'
usernames['astroneer']['en'] = u'MrBot5'
sysopnames is used for bot actions on accounts that have administrator rights. Setting them up follows the same processes we've used so far, but with the bot password being created for an account name with appropriate rights. While you can have as many usernames as you want, PWB will not allow you to have more than one line of sysopnames.

Logging in[edit | edit source]

After saving all the files in the previous steps, you should be ready to log your bot in for the first time. Return to command prompt and cd to your main pywikibot folder and type in py pwb.py login. If everything was done correctly, you should successfully log in and be ready to start running scripts.

Possible issues and solutions
  • "can't open file pwb.py. No such file or directory." - You cd-ed to the wrong place in command prompt. Check your path.
  • "Login failed (Aborted)" followed by a password prompt - Your user-password.py file is either incorrect or improperly formatted. Refer to the examples and check your password. If you closed the browser window that showed your password, you may need to return to Special:Botpasswords and reset it if you didn't record it elsewhere.

Using Pywikibot[edit | edit source]

Open command prompt (you may need to do so in administrator mode) and cd to your main pywikibot directory. You can run a script by typing py pwb.py scriptname followed by any relevant arguments for that script, which can be seen by typing py pwb.py scriptname -help.

An example script command, py pwb.py redirect double -always will resolve all double redirects on a wiki, not asking for confirmation each time.

To view all the scripts available, find the "scripts" folder in your main pywikibot folder.

Using Pywikibot on multiple wikis and languages[edit | edit source]

During the setup, we set one wiki and language code as your defaults. Whenever you run scripts, Pywikibot will attempt to use these unless you tell it otherwise.

  1. Create a new family file for the new wiki. If the wiki is in the same family but a different language than one of your existing families, you can add it to that family file instead.
  2. Add the new family to your user-config.py file. Find this part of the file:
usernames['ark']['en'] = u'MrBot5'
add a new entry to it, so it looks something like this:
usernames['ark']['en'] = u'MrBot5'
usernames['astroneer']['en'] = u'MrBot5'

When using scripts, add the wiki family, language, and username as command line arguments, if any of them differ from the default. For example, say or default wiki is Ark in English using the account MrBot5, our command of py pwb.py redirect do would automatically use all of these. But say I want to run the same script on Astroneer in Spanish using the account SenorBot5. Assuming I already set up an astroneer family file, updated my user-config.py to include this family file and account name, and added SenorBot5's password to user-passwords.py, my command would be py pwb.py redirect do -family:astroneer -lang:es -user:SenorBot5. But if I want to just do Astroneer in English (my default), using MrBot5 (also my default), then I can just do py pwb.py redirect do -family:astroneer.

Additional help[edit | edit source]

If you got stuck at some point during this guide, please leave a comment on the Discussion page.

FAQ[edit | edit source]

How do I make PWB not pause for 10s between pages?

Add -pt:0 as an argument to your command. It can go in any order. pt stands for "put_throttle."

I can't delete pages. What's going on?

Assuming your account has admin/sysop on your wiki, you probably need to have a sysopname set up in your user_config. Remember, you can have as many usernames as you want for a wiki, but only one sysopname! (The variable is still called "sysopnames" with an S at the end, though.

I was moving some pages and the console suddenly just exploded into an error message. What happened?

You hit the rate limit. Normal bots have a higher rate limit than normal users, but they still have one, and it's pretty low for moving pages. If you have an admin account, set that up as a sysop account and use it to move pages without rate limit.

See also[edit | edit source]