River's tools for writing Python scripts for MediaWiki wikis, including the Fandom wiki farm.
This library was originally known as river_mwclient
, however I renamed it because it has grown beyond the scope of just being tools for myself into a full-fledged library with a lot of utilities that's useful for many people. Thanks to pcj for coming up with the excellent name.
This library can be installed from PyPI:
pip install mwcleric
However, for the most up-to-date version including minor changes you may want to pull directly from the repo if I haven't updated PyPI:
pip install -U git+git://github.com/RheingoldRiver/mwcleric
If you're using PyCharm, press Alt+F12 to open the console and you can install directly to your venv or whatever it's using that way.
Currently, bot passwords are supported; legacy login without bot passwords should also work. If you want to add support for another type of login, I'm happy to merge a PR for it.
If you don't want to log in, you can just create a WikiClient
/ FandomClient
object and never log in; this is fine if you just want to make Cargo queries etc. However, if you want to edit your wiki, you probably will want to log in.
You can specify a username & password directly in the AuthCredentials
constructor, or you can set the name of a user_file
. This user_file will be used as a key to look up either environment variables or a file. If the file doesn't exist, you will be prompted to enter your information.
TL;DR: you can do nothing and just be prompted to enter your information.
If you're editing via crontab or setting up a Discord bot etc, dealing with files can suck, so you can set up environment variables. These are expected to be:
WIKI_USERNAME_%s
WIKI_PASSWORD_%s
If you use bot passwords, the password should be formatted like RheingoldRiver@Python
; your username then @
then the name of your bot password. The password is just your bot password secret.
The interactive method prompts you to enter your username in two parts, first the wiki username, then the bot password name; as well as the bot password secret, and then creates the user configuration file.
The user configuration file is located in the ~/.config/mwcleric
directory on Linux, and in the %HOMEPATH%\.config\mwcleric
directory on Windows. (%HOMEPATH%
typically means C:\Users\[YOUR USERNAME]
).
The name of the file must be formatted as wiki_account_[NAME].json
, where [NAME]
is the variable string you will refer to in the code; for example, wiki_account_bot.json
for the variable string bot
.
If you want, you can also create a configuration file manually in the same directory as your code, which will override your central configuration file in the .config
directory. The file would have to be named in the same way (as described above).
The format of any JSON configuration file is:
{
"username": "ACCOUNT_NAME@BOT_PASSWORD_NAME",
"password": "BOT_PASSWORD_TOKEN"
}
Replace the placeholders (ACCOUNT_NAME
, BOT_PASSWORD_NAME
, and BOT_PASSWORD_TOKEN
) with the actual credentials you want to use.
River wrote an entire blog post about this! See https://river.me/blog/bot-passwords/ for more information.
For people wanting to edit wikis, PageModifier
and TemplateModifier
are the two things most likely to make your life easier. To use them, you subclass and then overwrite methods to modify the page or template as needed, then instantiate the subclass and run.
For PageModifier
, you probably want either update_plaintext
or update_wikitext
, not both.
Changing the syntax of a template in all pages that use it:
from mwcleric.wiki_client import WikiClient
from mwcleric.auth_credentials import AuthCredentials
from mwcleric.template_modifier import TemplateModifierBase
from mwparserfromhell.nodes import Template
credentials = AuthCredentials(user_file="me")
site = WikiClient(site='lol.fandom.com', credentials=credentials)
summary = 'Bot edit'
class TemplateModifier(TemplateModifierBase):
def update_template(self, template: Template):
return
TemplateModifier(site, 'TEMPLATEYOUCAREABOUT',
summary=summary).run()
Notes about the above example:
- The value given to the
user_file
parameter in the constructor ofAuthCredentials
is the same as the user variable string in the names of JSON configuration files. So for the code above, the file would be named, or would have to be named,wiki_account_me.json
. - You are advised to provide a more descriptive summary.
- To instruct the program on how to change the template, you need to implement the
update_template
method of theTemplateModifier
class, typically by calling various methods of the providedtemplate
object. Refer to the MWPFH documentation for more information. - The template name in place of the
TEMPLATEYOUCAREABOUT
uses the same principles as the{{}}
syntax in wikitext.Notice
meansTemplate:Notice
,:Notice
means the main namespace pageNotice
,Module:Thing
means theModule:
namespace pageThing
. - Other parameters to the
TemplateModifier
constructor may be useful.namespace
(the numeric ID, or, in newer mwcleric version, its name) means only pages from the chosen namespace will be read;limit
stops the task after reading the specified number of pages (whether or not any of them needed to be changed) and can help if you want to make sure you implemented your modifier correctly before leaving the bot unattended;lag
specifies the number of seconds to wait between saving edits.
Performing a sitewide find-and-replace in wikitext:
from mwcleric.wiki_client import WikiClient
from mwcleric.auth_credentials import AuthCredentials
from mwcleric.page_modifier import PageModifierBase
credentials = AuthCredentials(user_file="me")
site = WikiClient(site='lol.fandom.com', credentials=credentials)
summary = 'Bot edit'
class PageModifier(PageModifierBase):
def update_plaintext(self, text):
return text
def update_wikitext(self, wikitext):
return
PageModifier(site,
summary=summary).run()
PRs are welcome! So far this repo is mostly Fandom-wiki-centric but it definitely doesn't have to stay that way; though contributions to FandomClient
are also appreciated. Help with documentation & tests is also welcome!