Guidelines:Pywikibot
#wiki-tech on Discord.Pywikibot (PWB) is a collection of Python scripts that allows users to perform actions against several pages with a single command.
Setting up a bot account
- If you haven't already, create a bot account separate from your normal 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
- Hit the
Createbutton and record the password shown on the next page.
Installing Pywikibot
Windows
- Install winget
- Start PowerShell
- Install Python by pasting the following into Powershell and hitting Enter:
winget install -e --id Python.Python.3.11
- Install git:
winget install -e --id Git.Git
- Install Pywikibot:
git clone --recursive --branch stable https://gerrit.wikimedia.org/r/pywikibot/core.git pywikibot
- Change to the
pywikibotbase directory:cd pywikibot
macOS
- Open Terminal
- Install Homebrew
- Install Python by pasting the following into Terminal and hitting Enter:
brew install python
- Install git:
brew install git
- Install Pywikibot:
git clone --recursive --branch stable https://gerrit.wikimedia.org/r/pywikibot/core.git pywikibot
- Change to the
pywikibotbase directory:cd pywikibot
Configuring Pywikibot
- Create a family file for Zelda Wiki:
python pwb.py generate_family_file https://zeldawiki.wiki zeldawiki
- Create user config files:
python pwb.py 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:
python pwb.py login
The login is successful if the following message appears:
Logged in on zeldawiki:en as <username>
The above message may be preceded by the following errors and warnings which can be ignored:
WARNING: API warning (main): Subscribe to the mediawiki-api-announce mailing list at <https://lists.wikimedia.org/postorius/lists/mediawiki-api-announce.lists.wikimedia.org/> for notice of API deprecations and breaking changes. WARNING: API warning (login): Fetching a token via "action=login" is deprecated. Use "action=query&meta=tokens&type=login" instead. ERROR: Received incorrect login token. Forcing re-login....It's unfortunate that PWB works this way—it's not very considerate of the user experience.
Using Pywikibot
Pywikibot only works from the Pywikibot base directory. Whenever you open a new terminal session, you must change to the base directory. For example:
cd ~\pywikibot
cd ~/pywikibot
See Manual:Pywikibot/Scripts for the list of scripts you can run. To learn more about how to use a script, you can type the following command:
python pwb.py <command-name> -help
Typing simply python pwb.py -help will show you command options available for all scripts.
By default, PWB waits for 10 seconds before editing the next page. To remove this wait period, add -pt:0 to the command.
Example commands
Below are some examples of some useful Pywikibot commands.
Null-editing all pages using a certain template
python pwb.py touch -pt:0 -transcludes:"Template:BotW Item Properties/Store"
The Template: namespace prefix can be omitted.
Null-editing all pages in a category
python pwb.py touch -pt:0 -cat:"Articles using invalid arguments in template calls"
Replacing text for all pages in a category
python pwb.py replace -pt:0 -pairsfile:replace.txt -cat:"Articles using invalid arguments in template calls"
Where replace.txt is a file in the PWB base 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, \| will match pipe characters. Failing to escape pipe characters when using regex replacements can be quite disastrous.
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
python pwb.py upload <path-to-folder> -pt:0 -descfile:descfile.txt -ignorewarn -keep -noverify
Where descfile.txt is a file in the PWB base 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.
