Help:Pywikibot

First-time setup

Note: If using Python 3.4 or above, you will have pip installed, you can install packages automatically via command line with "pip install <package>" where <package> would be "Requests" or "Pywikibot", i.e. "pip install Requests". Find help with this on the pip website.

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 (meaning "change directory") 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 py setup.py install. 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:\Users\username\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.

Adding your bot password to PWB

To use PWB with your bot, you will have to generate special, bot password. This password is only used for logging into your bot via external programs - when logging in through the browser, use its normal password.

After generating your bot password, 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

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's 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:

from __future__ import absolute_import, division, unicode_literals

from pywikibot import family
from pywikibot.tools import deprecated

class Family(family.Family):

    name = 'ark'
    langs = {
        'en': 'ark.fandom.com',
        #'es': 'ark.fandom.com',
        #'fr': 'ark.fandom.com',
        #'ptbr': 'ark.fandom.com',
    }

    def scriptpath(self, code):
        return {
            'en': '',
            'es': '/es',
            'fr': '/fr',
            'ptbr': '/pt-br',
        }[code]

    @deprecated('APISite.version()')
    def version(self, code):
        return '1.39.3'

    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, see this page.

Setting up your user-config

1. Return to command prompt, and use cd to navigate to your main Pywikibot folder, then to the pywikibot folder itself and locate the scripts folder. Then 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'

If you added your password in the setup, there will also be a section about a passwords file under the language. The usernames section can also be modified with the * wildcard so that you don't need to add more lines for every wiki and language you want to work on, like so:

#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['*']['*'] = u'MrBot5'
sysopnames['*']['*'] = u'Mr_Pie_5'

sysopnames is used for bot actions on accounts that have administrator rights and it's not necessary to make the bot work. 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 per family.

Logging in

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 navigated to the wrong place with cd in the 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.
• "Username '<USERNAME>' does not have read permissions on <FAMILY>:<LANG>." - Most likely the account is still new and not yet autoconfirmed (automatically granted 4 days after account creation).

Using Pywikibot

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

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.

To add a new wiki, 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.

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 our default wiki is Ark in English using the account MrBot5, our command of py pwb.py redirect double 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 double -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 double -family:astroneer.

Additional help

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

Walkthrough example to get a bot that can read a page

This example will use the .ipynb python file format as it allows for cell-by-cell splitting of code and markdown documentation. Lots of the code would still be applicable outside of an .ipynb file. This example will also use pip to install the required files and run everything from a bespoke folder directory, instead of navigating directly to where pywikibot was installed.

First off, make sure you have the required packages installed. The %s at the beginning will ensure we don't re-acquire the files, but check they are there.

Pre-requisites to run

  %pip install pywikibot
  %pip install Requests

User configuration (username/password)

Next, let's create a user configuration for the bot to use. We'll create the files separately from our main ipynb file as these files are what the pywikibot will look for.

wiki_name = "<name>" # Change this to match your wiki, i.e. if accessing domo.fandom.com - the "<name>" variable becomes "domo". 
language = "en" # Choose your language
screenName = "<screenName>" # Username used on Fandom, i.e. a user "Roger" may make a Fandom account called "Roger Bot", use "Roger Bot". 
botName = "<botName>" # Bot name that you choose via Special:BotPasswords, i.e. "Roger_community_bot"

# Create the user-config.py file required by pywikibot, we'll create a separate file for this so pywikibot can find it.
config_text = f"""
usernames['{wiki_name}']['{language}'] = '{screenName}@{botName}' # Note this is a combination of two names. The Special:BotPasswords page will tell you what to put here.

# Put password into config manually - this is better practice
password_file = 'password.py'
"""

# Populate the PASSWORD information here, NOTE: older accounts may need to use a combination of {botName}@<Password> here.
# As mentioned above, it's better to split the password out, but for the purpose of this guide, this is included in a python cell.
credentials = "('{screenName}', BotPassword('{botName}', '<Password>'))" # For new passwords/accounts, expect this to just be the text after the "@".
with open("password.py", "w") as f:
    f.write(credentials.format(botName=botName, screenName=screenName, language=language, wiki_name=wiki_name))
print("password.py created!")

with open("user-config.py", "w") as f:
    f.write(config_text.format(wiki_name=wiki_name, language=language, botName=botName, screenName=screenName))
print("user-config.py created!")

Creating the family file

Now that pywikibot can impersonate (this is why we want a separate account) our bot user, we can generate our "family" file - which will direct the bot to the community it's going to update.

# Generate the contents of the family file, this uses the wiki_name variable set above
family_file = """
from pywikibot import family

class Family(family.Family):
    name = '{wiki_name}'
    langs = {{
        'en': '{wiki_name}.fandom.com'
    }}

    def scriptpath(self, code):
        return '/'

    def apipath(self, code):
        return '/api.php'
"""


# Name the file after the Fandom wiki you want to go for, if I want the domo.fandom.com wiki, I would have "<name>" as "domo"
family_file_name = "families/<name>.py" 
os.makedirs(os.path.dirname(family_file_name), exist_ok=True) # Create the directory if it didn't already exist.

# Create local directory to help the wikibot find the domo family. The wiki bot expects the family files in a "families" directory.
with open(family_file_name, "w") as f:
    f.write(family_file.format(wiki_name=wiki_name))
print("Fandom family file created!")

Move working directory for pywikibot to the local directory

Since we're doing this in an .ipynb and not local to the pywikibot installation, we'll need to set the config/running directory to our local directory.

import os

# Set the pywikibot directory to be one level up on the active file path which gives it visibility of the local user-config, password file and families.
os.environ["PYWIKIBOT_DIR"] = os.path.abspath("../")

# Confirm for debugging
os.environ["PYWIKIBOT_DIR"]

Logging in via bot

Now that we've set everything up, we can actually log in and get access to the wiki we want.

Note that if you get errors with logging in, check the screen name configurations in the user-config.

import pywikibot

# wiki_name comes from variables above, i.e. domo.fandom.com this wiki_name variable would be "domo"
site = pywikibot.Site("en", wiki_name)
site.login()
print("Logged in to the wiki successfully!")

Add throttle.ctrl

It's possible that you'll be restricted from using the bot without a throttle.ctrl file for the pywikibot to edit. Note that we don't actually need to populate it, we just need it to exist and the pywikibot can configure itself.

# Create a throttle.ctrl if not already existent to help with rate limiting - Fandom may limit usage if we don't set this.
if not (os.path.realpath("throttle.ctrl")):
    with open("throttle.ctrl", "w") as f:
        f.Write()  # creates an empty file
    print("throttle.ctrl file created!")

Reading content from a wiki page

Now everything else is set up, we can log in and we have limiters on what we're accessing, we can read a page!

# Choose the page you want to pull data from - all communities should have a "main page" so let's use that.
page_title = "Main Page"

# Grab the page object containing the data
page = pywikibot.Page(site, page_title)
print(page.text[:5000])  # Print first 5000 characters

Note that if you see something like: #REDIRECT [[Domo Wiki]] You can easily view the content of the main page by changing the "page_title" to be "Domo Wiki" (case sensitive)

FAQ

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

• Help:Logging in to third-party tools
• Pywikibot manual on Mediawiki

Further help and feedback

• Browse and search other help pages at Help:Contents
• Check Fandom Community Central for sources of further help and support
• Check Contacting Fandom for how to report any errors or unclear steps in this article