Manual:Pywikibot/Use on third-party wikis

The pywikibot may be used to do all kind of things that are important for the maintenance of a MediaWiki project. When this software is to be used outside of the Wikimedia projects, some configuration needs to be done.

Some non-Wikimedia projects, or families, are already supported. These can be found in the (core) /  (compat) folder.

Using the existing files as examples, it should be easy to adapt the bot to your own project. For a shorter set of instructions, see the Quick Start Guide which might have your bot up and running quickly. If you have any problems, you can come back on this page.

user-config.py file
The  must have a username defined for a wiki, especially if the bot does edit actions on it. The following three lines must be add to the :

Now save  again.

Family file
If there is no family file for the wiki that you are going to use the bot on, then you need to create one. The username must be manually added after creation of a family.

AutoFamily
In core it is possible to define a AutoFamily in the  and doesn't require an additional family file, but doesn't allow as much configuration freedom. There is no AutoFamily configuration in compat.

To add a family with the name 'mhwp' or 'w3c' the following lines can be added: It adds  at the end of the URL if it doesn't end with. So if your wiki does something different (like the W3C example) simply use the complete URL to the. The text must begin with  or   to be detected as an AutoFamily. Usernames can be defined as usual but there are no such thing as languages.

Script to generate family file
The  in the root directory of both versions automatically generates a family file and stores it in the family repository. Given the URL it queries the page and extracts the location of api.php from it. If it succeeds you can login to your wiki using  (core)/  (compat) (make sure you have already created the account on the wiki!). If that fails, then you will need to modify the existing files below, or create a new file, in a text editor.

Manually in core
Save the file in the  (core) folder, with a name such as _family.py where sitename is the name of site you have chosen (for example,  ).

The basis looks something like this:

If the wiki is configured like the official WMF wikis, this is the least amount of code required. Important is that the class is named  and that the constructor (  doesn't require any additional parameters (apart from  ). If a wiki does support multiple languages it is possible to define them in the   dictionary.

This assumes that the api.php is in the directory /w/ (in that example the full URL would be  http://wiki.kerbalspaceprogram.com/w/api.php ). If this is not the case and for example the api.php is in  http://example.com/mediawiki/api.php  the  method of   has to be overwritten. It does not return the domain and can be dependent on the language/code:

Manually in compat
Save the file in the  folder, with a name such as _family.py where sitename is the name of site you have chosen (for example,  ).

Follow the sections below in order (each section makes the following section easier).

You must have the correct details as described in the sections below.

Potential problems:
 * errors in the custom namespaces mean the family file won't work properly (though you'll get a warning when you login?)
 * an error in specifying index.php will prevent you logging in;
 * an error in specifying api.php seems likely to lead to problems, since the wiki is accessed via API.

The  file in the families folder offers considerable documentation of the options available to family files. In fact,  is a simple 'prototype' family file. You can just copy  to _family.py, then open up the _family.py file in a text editor, and tweak it per the instructions below.

index.php

 * Note, several family files do not have this in the file, for example, battlestarwiki_family.py

You must have a correct index.php path in your private family file created above. To check if you have the correct path for your index.php, test which address redirects to your wiki's homepage - probably one of these:
 * wikidomainname.org/wiki/index.php
 * wikidomainname.org/w/index.php
 * wikidomainname.org/mw/index.php
 * wikidomainname.org/index.php

(You may be able to guess from the address of a regular wiki page, but you need to check it - e.g. a wiki page may be wikidomainname.org/randompage but the correct path may be 'w/index.php' - this occurs at fr.ekopedia.org for example.)

Near the end of your family.py file, you find something similar to this. You shouldn't modify or remove the "/w" there but define your own scriptpath method in your private family file as necessary:

api.php

 * Note, several family files in the pywikibot family folder do not have this in the file, for example, battlestarwiki_family.py

You must have a correct API.php path in family.py. Previously this needed to be corrected but variables now allow it to find the path from the scriptpath added in the step above.

The API.php file is found in the same place as index.php. Test this by navigating to for example:
 * your.domain.org/wiki/api.php

or
 * your.domain.org/w/api.php

or
 * your.domain.org/mw/api.php

or
 * your.domain.org/api.php

The correct address will give you an auto-generated MediaWiki API documentation page (the important thing is that it confirms you have the correct address).

The api is defined like this:

There is nothing here that needs to be changed.

Custom Namespaces

 * Note, several family files in the pywikibot family folder do not have this in the file, for example, battlestarwiki_family.py

A wiki can feature custom namespaces in addition to the standard namespaces, i.e.,  ,  , etc... If it is the case and you want to handle those pages with your bot, you have to specify them.

Adding a custom namespace to a family file is not well documented in the  file. The Uncyclopedia example below has some examples using custom namespaces, but the addition of these namespaces to your family file requires knowing the numerical ID of each namespace.

Finding the details you need: Start with the api URL (which you found above) and add this string to the end: ?action=query&meta=siteinfo&siprop=general|namespaces|namespacealiases|statistics

...so your address might look something like:


 * http://your.domain.org/wiki/api.php?action=query&meta=siteinfo&siprop=general|namespaces|namespacealiases|statistics

The resulting page will list the information about your namespaces that you need for the family file, including the numerical ID.

explains two ways to list namespaces:

1. Changing a specific language's namespace:

2. Changing an entire batch of languages at once:

When adding custom namespaces you must use the second style. The first method only works because  already exists. With custom namespaces, they do not, so you must use the second style, including the curly braces, even if you only have one language. For example, suppose you have a News namespace, and your Wiki only operates in English:

If you do not use this format, the family file will not work, the resulting error message will not help - it will ask you to create a  file, even if that file already exists and works correctly.

Custom User Groups & Permissions
Pywikibot assumes that the Wiki it is running on uses the standard, default user groups and that each group is assigned the usual permissions. This means that it may refuse to do things that its account would allow, and it may attempt to do things that its account is not allowed to do (these attempts will fail, so this is not a security issue).

The fact that it will attempt things it is not allowed to do is minor, but the inability to perform certain actions (e.g. deleting pages) without being in the "Sysop" group can be a sizable limitation. If the bot account has such permissions without being in the "Sysop" group (being part of some other, non-standard group), the only known work-around is the edit Wikipedia.py itself. This file controls most bot actions, and is found in the main folder Pywikibot has been installed to.

In the _getUserData function within Wikipedia.py, a pair of lines like this exists: In version 2008-10-29T19:21:05.438703Z 6043, this is line 4705 and 4706, but that line number may be different, even very different, in other versions. Using the Find function of your text editor to find " " (to find the function definition) is recommended.

In order to get the rights listed in the second line, the first line must be changed to recognize your custom user group (note: if your custom user-group has some, but not all of those rights, changing this will not give you those rights - it will simply let Pywikibot attempt to exercise them if you direct it to. Doing so is strongly not recommended as the program's behavior in such a case is undefined). The exact name of the user group can be found by logging in manually as the bot, and viewing the HTML code of any Wiki page. Near the top, a line as follows should appear: Where the ellipsis is replaced by a list of the groups that the bot is a member of. Choose the one that matches the custom user group that gives you the rights that you are attempting to exercise, and replace Sysop in the above code from Wikipedia.py with that name. This should activate those rights for Pywikibot.

LDAP Authentication
If your site uses LDAP Authentication you will need to set the ldapDomain in your family file:

Configuring custom families folder
If you create your own family files, you may not want to mix them with those provided by Pywikibot. You can put your custom family files into their own folder, and configure your script to look for them. To do that the easiest way is to edit the user-config.py and add all directories in which the family files are via. All families in the files ending with  are available then.

Via  it is also possible to just add one family file which doesn't has to follow the filename convention.

Running the Pywiki Bot
Refer to Manual:Pywikibot/Basic use on how to run the bot.

Example: Mozilla wiki
The Mozilla Foundation's wiki, wiki.mozilla.org, is a very simple example because it is only available in one language.

This is the contents of. Hints for you to write your own family specification are underlined.

Example: Starwars
This is the content of the Starwars wiki at wikia. The file is located at.

Here explains how to configure the Pywiki bot to work at this site.

Example: Memory Alpha
memoryalpha_family.py is the "family" definition of Memory Alpha, www.memory-alpha.org, a Star Trek wiki. This specification is a little bit more difficult because it has several languages.

Example: Uncyclopedia
The various Uncyclopedias are slightly more awkward as not all are hosted at the same domain or under the same name. Domain names and paths must be specified individually. Just over half are Wikia-hosted; exceptions include fi: hu: ja: ko: no: pt: sv: and zh-tw:. Many have their own registered domain names and many use custom namespaces.

The approaches which work for an Uncyclopædia or a Memory Alpha project typically can be adapted to other Wikia.

''Note: There have been subsequent updates and changes, see botwiki:python:uncyclopedia_family.py or wikia:uncyclopedia:es:Usuario:Chixpy/uncyclopedia_family.py for more current versions of the Uncyclopedia interwiki bot configuration. There are also unresolved issues in which some interwiki languages are not available from all Uncyclopedia projects or point to incorrect/inconsistent destinations; proceed with caution.''

Language
For a single-language site, the language specified does not matter as long as it is consistent between the user-config.py and families/foo_family.py

Login failed. Wrong password?
Pywikibot does not report anything more useful than success, failure, or host connection failure. If possible, try accessing the web server logs (Apache uses access_log by default) and take a look at the URL strings.

You could also try running login.py in 'very verbose' mode, i.e.:. This will dump a lot of information, including possibly the html code from the server, so you can see exactly what is going on. (however this option does run the risk of possibly revealing some security sensitive info so be careful...)

Make sure your scriptpath, the relative path to your api.php and index.php files, is defined appropriately for your wiki in your families file:

If this does not help, add a line like

to your user-config.py file.

See the mozilla configuration for clues.

Bot doesn't want to stay logged in
If you are able to log in with, but the bot doesn't seem to want to remember your credentials no matter what you should consider using a password file.

Add the line to your. The secretsfile should be made only readable by the user who executes the bot (for Unix it's usually the the mode 600), that file has to be UTF8 encoded (or ASCII if it only consists of ASCII characters). Each line contains a tuple with 2 to 4 values (compat doesn't support the option with 3 values): It'll select the last applicable entry, so the values should be ordered from most generic to least generic. If no language is given it'll use that password on all languages of that family and if family is also not given it'll choose that password if the username is matching.

This is not the same as the tip above, which is for HTTP AUTH BASIC-protected wikis.

Possible issue with SVN pywikipedia, custom URL schemes, and/or MediaWiki in XAMPP
My particular difficulty with  (from SVN rev 9509, with Python 2.6.something and MW 1.17) is that it initially logs in just fine, but   immediately after says:

You are not logged in on :.

when clearly I just did. There is nothing unusual in the output of. Yet none of the other bot scripts are able to use the credentials which should have been cached by. Since I'm using it with non-Wikimedia wiki, using a custom (short) URL scheme, with the wiki running on Windows (XAMPP), and with all those strikes against it, I'm not about to call this a bug. But  certainly isn't remembering the login cookie as advertised. Annoying, because I was trying to loop through a thousand plus images with  and being asked a password for each one. The workaround above works.

Mismatched interwiki configuration
In some projects (such as Uncyclopedia), each language operates as an independent wiki. This may mean that interwiki tables differ from one individual wiki to another within the same project. Interwiki.py is built on the assumption that, if outbound interlanguage links are available at all from a language, the list of available link-destination languages and the destination URL for each will match perfectly across all wikis in the project.

This leads to some potential pitfalls:
 * If one language is missing outbound language interwiki support entirely, one must avoid giving pywikibot an account on that wiki (in user-config.py) in order to ensure that interwiki.py leaves that one language wiki untouched.
 * If one language is using a valid but incomplete interwiki table, running interwiki.py on that language wiki will create broken links. Unlike the case where one language is missing project-wide, there is no clean and easy workaround.
 * If a language in a project has been forked (not just mirrored), the interwiki for each individual language pair will point to only one of the multiple forks. Verify the wiki your bot is looking at is the same one that is being linked from the wiki you're editing - otherwise the bot will delete some valid links as "page does not exist".

Customisation of namespaces
Some projects use non-standard extensions to provide Special:Interwiki and Special:Namespaces lists; where available, these lists should be checked against the configuration files to detect any additional namespace customisations.

Short URL rewrites
If your site uses short URL rewrites, you may have to add "/api.php" to the blacklists, Otherwise, your bot scripts will not be able to access api.php.

Check your rewrite conditions in your Apache conf file, and make an appropriate addition.

Bot & private wikis
Some wikis require logging in into mediawiki before being able to view any wikipage. If you have any such site, add to your custom family file :

Fixing Permission Denied problems Creating page via API Unknown Error. API Error code:permissiondenied Information:Permission denied Your wiki may require users to be part of a particular group in order to edit pages. If so, login to your wiki as an administrator and use Special:UserRights to put your bot into the proper group(s) to avoid API permission problems.

Bot & HTTP auth
Some sites will require password identication to access the HTML pages at the site. If you have any such site, add lines to your user-config.py of the following form: