Guidelines:Pywikibot
#wiki-tech on Discord.Pywikibot (PWB) is a MediaWiki bot framework for automating page actions via Python scripts.
Setting up a bot account
- Create a bot account separate from your normal account, if you haven't already.
- Log into your bot account.
- Go to Special:BotPasswords/PWB and tick the following checkboxes. Some checkboxes may only be available to admins—tick whichever ones are available to you.
- High-volume editing
- Edit existing pages
- Edit protected pages
- Create, edit, and move pages
- Upload new files
- Upload, replace, and move files
- Patrol changes to pages
- Rollback changes to pages
- Delete pages, revisions, and log entries
- Click the
Createbutton and record the password shown.
Installing Pywikibot
Windows
- Install git, selecting all the default options in the setup wizard.
- Start PowerShell.
- In PowerShell, type
pythonand hit Enter to open the latest version of Python in the Microsoft Store. Install this version. - Go back to Powershell and install Scoop:
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
Invoke-RestMethod -Uri https://get.scoop.sh | Invoke-Expression
- Install pipx:
scoop install pipx
pipx ensurepath
- Install Pywikibot:
pipx install pywikibot
macOS
- Open Terminal
- Install Homebrew
- Install Python by pasting the following into Terminal and hitting Enter:
brew install python
- Install pipx:
brew install pipx
pipx ensurepath
- Install pywikibot:
pipx install pywikibot
Configuring Pywikibot
Downloading scripts
Now that we've installed Pywikibot, we need to obtain the scripts that allow it to do tasks on-wiki.
- Create a directory for your Pywikibot configuration, for example:
mkdir $HOME/pwbcd $HOME/pwb
- Download and extract the Pywikibot scripts:
git clone --recurse-submodules --branch stable https://gerrit.wikimedia.org/r/pywikibot/core
cp -r core/scripts/* $HOME/.local/pipx/venvs/pywikibot/lib/python3.12/site-packages/pywikibot/scriptsYou may have to change the version number in that last path to match the Python version used by your pipx installation of Pywikibot. You can determine this version with the command
python3 --version.
Adding login information
The next step is to configure Pywikibot to log into Zelda Wiki using your bot account.
- Create a family file for Zelda Wiki:
pwb generate_family_file https://zeldawiki.wiki zeldawiki
- Create user config files:
pwb generate_user_files
You will be prompted to fill in some information. For each prompt, type the following and hit Enter:
Prompt tipsPywikibot prompts often display these options or similar:
([y]es, [N]o, [q]uit)
This syntax is standard for command-line interfaces. What the above means is that you can typeyas a shortcut for yes,nfor no andqfor quit. The capital letter indicates the default option. In the above case, if you hit Enter without typing anything, "No" will be selected.- Family
zeldawiki- Site code
en- Username
- Enter your bot account's username.
- Do you want to add any other projects?
no- Do you want to add a BotPassword?
yes- BotPassword's "bot name"
PWB- BotPassword's "password" for "PWB"
- Paste the BotPassword created above.
- Do you want to select framework setting sections?
None- Do you want to select scripts setting sections?
None
- Log in with Pywikibot:
pwb login
The login is successful if the following message appears:
Logged in on zeldawiki:en as <username>
Using Pywikibot
Pywikibot commands only work when executed from your Pywikibot configuration directory where the bot scripts and wiki/user config are located. Whenever you open a new terminal session, you must change to that directory first:
cd $HOME/pwb
Every once in a while you'll have to re-login:
pwb login
See Manual:Pywikibot/Scripts for the list of scripts you can run. To learn more about how to use a script, type the following command:
pwb <script_name> -help
Typing simply pwb -help will show you command options available for all scripts.
Example commands
Below are some examples of useful Pywikibot commands.
Null-editing all pages using a certain template
pwb touch -transcludes:"Template:BotW Item Properties/Store"
The Template: namespace prefix can be omitted.
Null-editing all pages in a category
pwb touch -cat:"Articles using invalid arguments in template calls"
Replacing text for all pages in a category
pwb replace -pairsfile:pairsfile.txt -cat:"Articles using invalid arguments in template calls"
Where pairsfile.txt is a file in your PWB config directory that looks something like this:
a
b
c
dHere a would be replaced with b and c would be replaced with d.
This command supports regex with the -regex option. Escape special regex characters with a backslash. For example, to match wiki pipe characters you must type \|. Failing to escape pipe characters when using regex replacements can be disastrous given how regex pipes widen matches, often by quite a lot.
The script will show you each edit and ask you to confirm before saving each page. At any point you can tell it to save the rest of the pages without confirmation.
Uploading all files in a folder
pwb upload <path-to-folder> -descfile:descfile.txt -ignorewarn -keep -noverify
Where descfile.txt is a file in the PWB config directory containing the Template:FileInfo that will be added to all the uploads. Fill in whichever fields apply to all files—you can fill in the rest once the files have been uploaded.
