Guidelines:Pywikibot: Difference between revisions

From Zelda Wiki, the Zelda encyclopedia
Jump to navigation Jump to search
VisualWikitext
No edit summary
 
(18 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://aka.ms/getwinget Install winget]</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>Install Python by pasting the following into Powershell and hitting Enter:
<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>
  <syntaxhighlight lang="powershell">winget install -e --id Python.Python.3.11</syntaxhighlight>
<li>Go back to Powershell and install [https://scoop.sh Scoop]:
  <syntaxhighlight lang="PowerShell">Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser</syntaxhighlight>
<syntaxhighlight lang="PowerShell">Invoke-RestMethod -Uri https://get.scoop.sh | Invoke-Expression</syntaxhighlight>
</li>
</li>
<li>Install git:
<li>Install [http://pipx.pypa.io pipx]:
  <syntaxhighlight lang="powershell">winget install -e --id Git.Git</syntaxhighlight>
  <syntaxhighlight lang="shell">scoop install pipx</syntaxhighlight>
<syntaxhighlight lang="shell">pipx ensurepath</syntaxhighlight>
</li>
</li>
<li>Install Pywikibot:
<li>Install Pywikibot:
  <syntaxhighlight lang="shell">git clone --recursive --branch stable https://gerrit.wikimedia.org/r/pywikibot/core.git pywikibot</syntaxhighlight>
  <syntaxhighlight lang="shell">pipx install pywikibot</syntaxhighlight>
</li>
<li>Change to the <code>pywikibot</code> base directory:
<syntaxhighlight lang="shell">cd pywikibot</syntaxhighlight>
</li>
</li>
</ol>
</ol>
Line 48: Line 49:
  <syntaxhighlight lang="shell">brew install python</syntaxhighlight>
  <syntaxhighlight lang="shell">brew install python</syntaxhighlight>
</li>
</li>
<li>Install git:
<li>Install [http://pipx.pypa.io pipx]:
  <syntaxhighlight lang="shell">brew install git</syntaxhighlight>
  <syntaxhighlight lang="shell">brew install pipx</syntaxhighlight>
</li>
  <syntaxhighlight lang="shell">pipx ensurepath</syntaxhighlight>
<li>Install Pywikibot:
  <syntaxhighlight lang="shell">git clone --recursive --branch stable https://gerrit.wikimedia.org/r/pywikibot/core.git pywikibot</syntaxhighlight>
</li>
</li>
<li>Change to the <code>pywikibot</code> base directory:
<li>Install pywikibot:
  <syntaxhighlight lang="shell">cd pywikibot</syntaxhighlight>
  <syntaxhighlight lang="shell">pipx install pywikibot</syntaxhighlight>
</li>
</li>
</ol>
</ol>


==Configuring Pywikibot==
==Configuring Pywikibot==
===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]].
<ol>
<ol>
<li>Create a {{MediaWiki|Manual:Pywikibot/Use on third-party wikis|family file}} for {{SITENAME}}:
<li>Create a {{MediaWiki|Manual:Pywikibot/Use on third-party wikis|family file}} for {{SITENAME}}:
  <syntaxhighlight lang="shell">python pwb.py generate_family_file https://zeldawiki.wiki zeldawiki</syntaxhighlight>
  <syntaxhighlight lang="shell">pwb generate_family_file https://zeldawiki.wiki zeldawiki</syntaxhighlight>
</li>
</li>
<li>Create user config files:
<li>Create user config files:
  <syntaxhighlight lang="shell">python pwb.py generate_user_files</syntaxhighlight>
  <syntaxhighlight lang="shell">pwb generate_user_files</syntaxhighlight>
You will be prompted to fill in some information. For each prompt, type the following and hit Enter:
You will be prompted to fill in some information. For each prompt, type the following and hit Enter:
{{Collapsible
{{Collapsible
Line 88: 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 95: Line 96:
<pre>Logged in on zeldawiki:en as <username></pre>
<pre>Logged in on zeldawiki:en as <username></pre>


The above message may be preceded by the following errors and warnings which can be ignored:
===Downloading scripts===
{{Collapsible
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. -->
|header= Ignore these
<ol>
|frame= true
<li>Create a directory for your Pywikibot configuration, for example:
|content=  
<syntaxhighlight lang="shell">mkdir $HOME/pwb</syntaxhighlight>
<pre>
<syntaxhighlight lang="shell">cd $HOME/pwb</syntaxhighlight>
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.
</li>
WARNING: API warning (login): Fetching a token via "action=login" is deprecated. Use "action=query&meta=tokens&type=login" instead.
<li>Download and extract the Pywikibot scripts:
ERROR: Received incorrect login token. Forcing re-login.
<syntaxhighlight lang="shell">git clone --recurse-submodules --branch stable https://gerrit.wikimedia.org/r/pywikibot/core</syntaxhighlight>
</pre>
<syntaxhighlight lang="shell">cp -r core/scripts/* $HOME/.local/pipx/venvs/pywikibot/lib/python3.12/site-packages/pywikibot/scripts</syntaxhighlight>
...It's unfortunate that PWB works this way—it's not very considerate of the user experience.  
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 only works from the Pywikibot base directory. Whenever you open a new terminal session, you must change to the base directory. For example:
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:
{{Tabs
  <syntaxhighlight lang="shell">cd $HOME/pwb</syntaxhighlight>
|tab1= Windows (PowerShell)
|content1=
<syntaxhighlight lang="powershell">cd ~\pywikibot</syntaxhighlight>
|tab2= macOS
|content2=
  <syntaxhighlight lang="shell">cd ~/pywikibot</syntaxhighlight>
}}


See {{MediaWiki|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:  
Every once in a while you'll have to re-login:
<syntaxhighlight lang="shell">python pwb.py <command-name> -help</syntaxhighlight>
<syntaxhighlight lang="shell">pwb login</syntaxhighlight>


Typing simply <code>python pwb.py -help</code> will show you command options available for all scripts.
See {{MediaWiki|Manual:Pywikibot/Scripts}} for the list of scripts you can run. To learn more about how to use a script, type the following command:
<syntaxhighlight lang="shell">pwb <script_name> -help</syntaxhighlight>


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


==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">python pwb.py 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">python pwb.py 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">python pwb.py replace -pt:0 -pairsfile:replace.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>replace.txt</code> is a file in the PWB base directory that looks something like this:
Where <code>pairsfile.txt</code> is a file in your PWB config directory that looks something like this:
<syntaxhighlight lang="txt" line>
<syntaxhighlight lang="txt" line>
a
a
Line 150: 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 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.
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
Guidelines:Getting Started
Getting Involved
Discord
Discord
Zelda Wiki:Knight Challenges
Knight Challenges
Zelda Wiki:Image Requests
Image Requests
https://trello.com/b/ToL30iNx/wiki-projects
Trello
Guidelines:Main
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"