Guidelines:Pywikibot: Difference between revisions

From Zelda Wiki, the Zelda encyclopedia
Jump to navigation Jump to search
No edit summary
 
(7 intermediate revisions by the same user not shown)
Line 3: Line 3:
{{Hatnote|If you have questions about the use of Pywikibot on {{SITENAME}}, please let us know in {{Discord|channel= wiki-tech}}.}}
{{Hatnote|If you have questions about the use of Pywikibot on {{SITENAME}}, please let us know in {{Discord|channel= wiki-tech}}.}}


'''Pywikibot''' (PWB) is a collection of Python scripts that allows users to perform {{MediaWiki|API:Main page|actions}} against several pages with a single command.
'''{{MediaWiki|Manual:Pywikibot|Pywikibot}}''' (PWB) is a MediaWiki bot framework for automating {{MediaWiki|API:Main page|page actions}} via {{MediaWiki|Manual:Pywikibot/Scripts|Python scripts}}.


==Setting up a bot account==
==Setting up a bot account==
<ol>
<ol>
<li>If you haven't already, create a [[Guidelines:Bots#Creating a Bot Account|bot account]] separate from your normal account.</li>
<li>Create a [[Guidelines:Bots#Creating a Bot Account|bot account]] separate from your normal account, if you haven't already.</li>
<li>Log into your bot account.</li>
<li>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.
<li>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
* High-volume editing
Line 19: Line 20:
* Delete pages, revisions, and log entries
* Delete pages, revisions, and log entries
</li>
</li>
<li>Hit the <code>Create</code> button and record the password shown on the next page.</li>
<li>Click the <code>Create</code> button and record the password shown.</li>
</ol>
</ol>


Line 25: Line 26:
===Windows===
===Windows===
<ol>
<ol>
<li>[https://git-scm.com/download/win Install git] (the default options in the setup wizard are fine)</li>
<li>[https://git-scm.com/download/win Install git], selecting all the default options in the setup wizard.</li>
<li>[https://learn.microsoft.com/en-us/powershell/scripting/windows-powershell/starting-windows-powershell Start PowerShell]</li>
<li>[https://learn.microsoft.com/en-us/powershell/scripting/windows-powershell/starting-windows-powershell Start PowerShell].</li>
<li>In PowerShell, type <code>python</code> and hit Enter to open the latest version of Python in the Microsoft Store. Install this version.</li>
<li>In PowerShell, type <code>python</code> and hit Enter to open the latest version of Python in the Microsoft Store. Install this version.</li>
<li>Go back to Powershell and install [https://scoop.sh Scoop]:
<li>Go back to Powershell and install [https://scoop.sh Scoop]:
Line 58: Line 59:


==Configuring 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.
<ol>
<li>Create a directory for your Pywikibot configuration, for example:
<syntaxhighlight lang="shell">mkdir ~/pwb</syntaxhighlight>
</li>
<li>Download and extract the Pywikibot scripts:
<syntaxhighlight lang="shell">git clone --recurse-submodules --branch stable https://gerrit.wikimedia.org/r/pywikibot/core</syntaxhighlight>
<syntaxhighlight lang="shell">cp -r core/scripts/* .</syntaxhighlight>
</li>
</ol>
===Adding login information===
===Adding login information===
The next step is to configure Pywikibot to log into Zelda Wiki using your [[Guidelines:Bots#Creating a Bot Account|bot account]].
The next step is to configure Pywikibot to log into Zelda Wiki using your [[Guidelines:Bots#Creating a Bot Account|bot account]].
Line 100: Line 89:
</li>
</li>
<li>Log in with Pywikibot:
<li>Log in with Pywikibot:
  <syntaxhighlight lang="shell">python pwb.py login</syntaxhighlight>
  <syntaxhighlight lang="shell">pwb login</syntaxhighlight>
</li>
</li>
</ol>
</ol>
Line 106: Line 95:
The login is successful if the following message appears:  
The login is successful if the following message appears:  
<pre>Logged in on zeldawiki:en as <username></pre>
<pre>Logged in on zeldawiki:en as <username></pre>
===Downloading scripts===
Now that we've installed Pywikibot, we need to obtain the scripts that allow it to do tasks on-wiki. <!-- I don't undestand *why* they're not included in the pip package but whatever. -->
<ol>
<li>Create a directory for your Pywikibot configuration, for example:
<syntaxhighlight lang="shell">mkdir $HOME/pwb</syntaxhighlight>
<syntaxhighlight lang="shell">cd $HOME/pwb</syntaxhighlight>
</li>
<li>Download and extract the Pywikibot scripts:
<syntaxhighlight lang="shell">git clone --recurse-submodules --branch stable https://gerrit.wikimedia.org/r/pywikibot/core</syntaxhighlight>
<syntaxhighlight lang="shell">cp -r core/scripts/* $HOME/.local/pipx/venvs/pywikibot/lib/python3.12/site-packages/pywikibot/scripts</syntaxhighlight>
You may have to change the version number in that last path to match the Python version used by your <kbd>pipx</kbd> installation of Pywikibot. You can determine this version with the command <code>python3 --version</code>.<!-- Technically pipx list would be a better command but python --version will work on the assumption that pywikibot was just installed. -->
</li>
</ol>


==Using Pywikibot==
==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:
Pywikibot commands only work when executed from your Pywikibot configuration directory. Whenever you open a new terminal session, you must change to that directory first:
  <syntaxhighlight lang="shell">cd ~/pwb</syntaxhighlight>
  <syntaxhighlight lang="shell">cd $HOME/pwb</syntaxhighlight>


Every once in a while you'll have to re-login:
Every once in a while you'll have to re-login:
Line 118: Line 121:


Typing simply <code>pwb -help</code> will show you command options available for all scripts.
Typing simply <code>pwb -help</code> will show you command options available for all scripts.
By default, PWB waits for 10 seconds before saving each page. To remove this wait period, add <code>-pt:0</code> to the command.


==Example commands==
==Example commands==
Below are some examples of some useful Pywikibot commands.
Below are some examples of useful Pywikibot commands.


====Null-editing all pages using a certain template====
====Null-editing all pages using a certain template====
<syntaxhighlight lang="shell">pwb touch -pt:0 -transcludes:"Template:BotW Item Properties/Store"</syntaxhighlight>
<syntaxhighlight lang="shell">pwb touch -transcludes:"Template:BotW Item Properties/Store"</syntaxhighlight>


The <code>Template:</code> namespace prefix can be omitted.
The <code>Template:</code> namespace prefix can be omitted.


====Null-editing all pages in a category====
====Null-editing all pages in a category====
<syntaxhighlight lang="shell">pwb touch -pt:0 -cat:"Articles using invalid arguments in template calls"</syntaxhighlight>
<syntaxhighlight lang="shell">pwb touch -cat:"Articles using invalid arguments in template calls"</syntaxhighlight>


====Replacing text for all pages in a category====
====Replacing text for all pages in a category====
<syntaxhighlight lang="shell">pwb replace -pt:0 -pairsfile:pairsfile.txt -cat:"Articles using invalid arguments in template calls"</syntaxhighlight>
<syntaxhighlight lang="shell">pwb replace -pairsfile:pairsfile.txt -cat:"Articles using invalid arguments in template calls"</syntaxhighlight>


Where <code>pairsfile.txt</code> is a file in your PWB config directory that looks something like this:
Where <code>pairsfile.txt</code> is a file in your PWB config directory that looks something like this:
Line 145: Line 146:
Here <code>a</code> would be replaced with <code>b</code> and <code>c</code> would be replaced with <code>d</code>.
Here <code>a</code> would be replaced with <code>b</code> and <code>c</code> would be replaced with <code>d</code>.


This command supports regex with the <code>regex</code> option. Escape special regex characters with a backslash. For example, <code>\|</code> will match pipe characters. Failing to escape pipe characters when using regex replacements can be quite disastrous.  
This command supports regex with the <code>-regex</code> option. Escape special regex characters with a backslash. For example, to match wiki pipe characters you must type <code>\|</code>. 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.
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====
====Uploading all files in a folder====
<syntaxhighlight lang="shell">python pwb.py upload <path-to-folder> -pt:0 -descfile:descfile.txt -ignorewarn -keep -noverify</syntaxhighlight>
<syntaxhighlight lang="shell">pwb upload <path-to-folder> -descfile:descfile.txt -ignorewarn -keep -noverify</syntaxhighlight>


Where <code>descfile.txt</code> 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.
Where <code>descfile.txt</code> 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.


{{Guidelines Nav}}
{{Guidelines Nav}}

Latest revision as of 19:52, 3 May 2024

Main Page
ZW Logo Horizontal.svg
Guidelines:Getting Started
Getting Involved.png
Getting Involved
Discord
Discord Logo.svg
Discord
Zelda Wiki:Knight Challenges
Knight Challenges Icon.png
Knight Challenges
Zelda Wiki:Image Requests
Gimp Logo.svg
Image Requests
https://trello.com/b/ToL30iNx/wiki-projects
Trello Logo.png
Trello
Guidelines:Main
Guidelines Icon.png
Guidelines
If you have questions about the use of Pywikibot on Zelda Wiki, please let us know in #wiki-tech on Discord.

Pywikibot (PWB) is a MediaWiki bot framework for automating page actions via Python scripts.

Setting up a bot account

  1. Create a bot account separate from your normal account, if you haven't already.
  2. Log into your bot account.
  3. 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
  4. Click the Create button and record the password shown.

Installing Pywikibot

Windows

  1. Install git, selecting all the default options in the setup wizard.
  2. Start PowerShell.
  3. In PowerShell, type python and hit Enter to open the latest version of Python in the Microsoft Store. Install this version.
  4. Go back to Powershell and install Scoop: 
    Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

    Invoke-RestMethod -Uri https://get.scoop.sh | Invoke-Expression
  5. Install pipx: 
    scoop install pipx

    pipx ensurepath
  6. Install Pywikibot: 
    pipx install pywikibot

macOS

  1. Open Terminal
  2. Install Homebrew
  3. Install Python by pasting the following into Terminal and hitting Enter: 
    brew install python
  4. Install pipx: 
    brew install pipx

    pipx ensurepath
  5. Install pywikibot: 
    pipx install pywikibot

Configuring Pywikibot

Adding login information

The next step is to configure Pywikibot to log into Zelda Wiki using your bot account.

  1. Create a family file for Zelda Wiki: 
    pwb generate_family_file https://zeldawiki.wiki zeldawiki
  2. 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 tips

    Pywikibot 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 type y as a shortcut for yes, n for no and q for 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
  3. Log in with Pywikibot: 
    pwb login

The login is successful if the following message appears: 

Logged in on zeldawiki:en as <username>

Downloading scripts

Now that we've installed Pywikibot, we need to obtain the scripts that allow it to do tasks on-wiki.

  1. Create a directory for your Pywikibot configuration, for example: 
    mkdir $HOME/pwb

    cd $HOME/pwb
  2. 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/scripts

    You 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.

Using Pywikibot

Pywikibot commands only work when executed from your Pywikibot configuration directory. 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
d

Here 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.

Retrieved from "https://zeldawiki.wiki/w/index.php?title=Guidelines:Pywikibot&oldid=1144618"