Manual:Pywikibot

In your own language: de - fr - it - nl - pl - pt - sv -


 * If you need more help on setting up your pywikipediabot you can come for help on #pywikipediabot @ freenode server or use the pywikipediabot mailing list.

The Python Wikipediabot Framework is a set of bot scripts to do things on Wikipedia or other Mediawiki projects. It has been written by several people using the language Python. On this page, we give the general information for people who want to use the bot software.

Download
To use a bot you will have to download the bot software as well as Python version 2.3 or higher.

Python is already present on some distributions of Unix, and need not be included then (although it might be necessary to update it if you have a very old version). In all other cases, it can be found at http://www.python.org/download/. Python can be run on all common platforms (Unix, Linux, Mac, Windows). Download and install Python.

The bot software itself can be found at Sourceforge. At http://sourceforge.net/projects/pywikipediabot/ you can download it as a package, but this is often an outdated version. (See Current version below)

Once you have the bot software, all you have to do is download it to your computer, it does not need any further installation. (To work in Python25 http://www.python.org/download/, the files must be downloaded into the Python25 folder).

Current version
A much more up-to-date version (at most ca. 24 hours old) can be retrieved via CVS (or via http://sourceforge.net/cvs/?group_id=93107 if you don't have any CVS client installed, but that requires one to download every file separately. In the long run, the best method would be to use CVS). On Unix this is standard, for Windows TortoiseCVS is advised. See for a tutorial on how to setup TortoiseCVS. To check out the bot via the Unix like command line tools use the following commands: $ cvs -d :pserver:anonymous@pywikipediabot.cvs.sourceforge.net:/cvsroot/pywikipediabot login Password: (no password, simply press enter here) $ cvs -d :pserver:anonymous@pywikipediabot.cvs.sourceforge.net:/cvsroot/pywikipediabot co pywikipedia

If you have cygwin installed on Windows, simply run this single command: $ cvs -d :pserver:anonymous@pywikipediabot.cvs.sourceforge.net:/cvsroot/pywikipediabot co pywikipedia The files will typically be put in C:\cygwin\home\(username)\pywikipedia

If you type pwd (present working directory) at the cygwin command line, it will say something like /home/(username) - so that's how you know where to find the files.

For non command line tools, here is the neccessary information:

Bot mailing list
It is probably a good idea to subscribe to the bot mailing list (see http://sourceforge.net/mail/?group_id=93107). Every time a file of the bot software is changed, a mail is sent to the list, so you know when you need to update to the new version.

Configuring for Wikipedia
Open a text editor.

Type this line: mylang = 'xx' xx here is the code for the language code you are working on, "en" is english.

Save the text file as, saving the text file in the folder with all of the other .py files you downloaded.

Your  file needs to specify the bot's username.

For example, if you want to work on the Swedish Wikipedia, and you have created a bot account with username "ExampleBot", add this line to :

usernames['wikipedia']['sv'] = u'ExampleBot'

The u in front of the username stands for Unicode. It is important if your username contains non-ASCII characters. If you are working on more than one wiki, you can also specify several usernames, e.g. usernames['wikipedia']['de'] = u'BeispielBot' usernames['wikipedia']['en'] = u'ExampleBot' usernames['wiktionary']['de'] = u'BeispielBot'

Now save the file again.

Configure for other wiki pages
Open notepad or another text editor.

Type this line: mylang = 'xx' xx here is the code for the language code you are working on, "en" is english.

Then type: family = 'sitename' where "sitename" is the name of the site you're working on.

Currently, this can be wiktionary, wikibooks, wikiquote, as well as some non-Wikimedia projects like wikitravel (the full list is found in the families folder).

If you work on WikiMedia Commons, specify  both as language and as family:

mylang='commons' family='commons' usernames['commons']['commons']='UserBot'

If your wiki is not listed in the families folder, create your own families .py file, see Pywikipedia bot on non-Wikimedia projects

Your  file needs to specify the bot's username.

For example, if you want to work on the English Memory Alpha, and you have created a bot account with username "ExampleBot", add this line to :

usernames['memoryalpha']['en'] = u'ExampleBot'

So in summary the  file you create should have three lines, this is an example for memoryalpha:

mylang = 'en' family = 'memoryalpha' usernames['memoryalpha']['en'] = u'ExampleBot'

Save the text file as, saving the text file in the folder with all of the other .py files you downloaded.

unicode mediawiki installation
If you are working on a unicode mediawiki installation and plan on using non-latin characters, you might want to change your console's character encoding to UTF-8 (this is the default setting for most up-to-date Linux distributions) and set the setting console_encoding to utf-8 inside your, so that Unicode characters don't appear as question marks ("????"): console_encoding = 'utf-8'

Permission on wiki
Make sure that your bot is approved by the community at the wiki you are going to use it. Strictness of this differs greatly between various projects; at some you need to announce it in advance and get approval before you start, at others you can do whatever you want.

Using your normal browser, create a login name and password for the bot. It is best to use a name that makes clear that it is a bot, and preferably also who is operating it. A common method is to use your own login name and add the word 'bot' to it, but several other forms also exist.

On the English Wikipedia, bots are only allowed to be used if they are mentioned on en:Wikipedia:Bots. Please note that there is '''no consensus about using an interwiki bot on en:! (English wikipedia)'''

Request a bot flag
If you heavily use a bot, it will clutter recent changes. To avoid that, you can get your bot registered as such. In that case it will not be shown on Recent changes unless a user specifically asks to get bots included.

This can be done by a Steward or a Bureaucrat. You can put a request to get your or someone else's bot registered at Requests for bot status. You will probably be asked for some kind of evidence that your local community agrees with your bot. On the English language Wikipedia, requests should be made at Requests for approvals. It is probably good to get your bot registered whenever it will edit many pages in a single run.

Select and run a bot script
Now we are ready to really start using the bot. You need to get to a textual interface to your Operating System.

On Windows this is done by opening the start menu, and clicking on 'Run'. You are asked to give the name of a program, type "cmd.exe".
 * Change the root to C: by typing cd \
 * Type cd \"name of the folder where python wikipediabot has been downloaded"

On the Mac, find Terminal.app in /Applications/Utilities.

On Linux or any other Unix, use any terminal application such as gnome-terminal, konsole, xterm, or simply the text-mode console.

First run the script login.py by typing "python login.py". It will ask for a password, use the password you used for the bot's login name. The bot can't work anonymously. Unless you change your password, you normally need to run this program only once, the bot usually does not get logged off.

Using the command cd, go to the directory where you saved the files of the robot. You can now run any of the bots here by typing "python botname.py" (If you are using Windows, you might leave out "python").

Now you can use one of the bot scripts. Below is a list of the existing bots with links to their descriptions:

Command-line arguments
Although many bot scripts have their own command line arguments, which should be documented on their respective pages (or in their source code), all bots unless specifically stated to the contrary recognize the following command line arguments:


 * -help
 * Print a list of global bot arguments (this list), followed by bot-specific help if available.


 * -lang:xx
 * Set the language of the wiki you want to work on to language code, overriding the configuration in.


 * -family:xyz
 * Set the family of the wiki you want to work on, e.g., wikipedia, wiktionary, wikitravel, ... This will override the configuration in.


 * -log
 * Enable the logfile. Logs will be stored in the logs subdirectory.


 * -log:xyz
 * Enable the logfile, using  as the filename.


 * -nolog
 * Disable the logfile (if it's enabled by default).


 * -putthrottle:nn
 * Set the minimum time (in seconds) the bot will wait between saving pages. The default value is zero.

For example,  will run the "scriptname" bot on wiktionary articles, overriding the default family setting in your user configuration.

Using bot for a local installed wiki
Look here to find out how to configure the bot to use it on your own mediawiki-powered project.

Update
For further updates chdir into pywikipedia and type $ cvs up -Pd

Development
If you have a function you want to have a bot for that is not yet provided by one of the bots, you can ask one of the programmers to write it for you. Or even better, you can try to work on the bots yourself. Python is a nice language, and not hard to learn. We will welcome you.

Tips
Here are some very basic tips for getting started writing your own bot: site = wikipedia.getSite page = wikipedia.Page(site, pageName) text = page.get page.put(newText) site = wikipedia.getSite cat = catlib.Category(site,'Category:Living people') gen = pagegenerators.CategorizedPageGenerator(cat) for page in gen: #Do something with the page object, for example: text = page.get
 * be sure you've set up your user-config.py file (see above)
 * use  to gain access to the pywikipedia framework
 * to retrieve a page, use the following, where pageName is, e.g., "Wikipedia:Bots" or "India":
 * to update a page, use:
 * look at some of the pywikipedia files for other ideas -- replace.py is relatively easy to read even if you're new to pywikipedia.
 * you can find all available Page methods in the wikipedia.py file.
 * basic.py gives you a setup that can be used for many different bots, all you have to do is define the string editing on the page text.
 * To iterate over a set of pages, see pagegenerators.py for some objects that return a set of pages. An example use of the CategoryPageGenerator that does something for each page in the Category:Living people category:

Contributing changes
If you changed the bot and want to send a patch to the maintainer,
 * 1) Update to the current version (it will merge your changes with the improvements already committed to the CVS Repository),
 * 2) Resolve any conflicts caused by the update (grep for "=====" ;-) and
 * 3) Type:
 * $ cvs diff > cvs.diff

You can then send the file cvs.diff to the developer And ask them to include the changes (maybe you want to review the diff before sending it). The lines at the beginning starting with "?" may be removed.

Multiple accounts
It is a common need to run python wikipedia bot under different accounts (main and/or multiple bot accounts). It can be done in two ways.

Separate pywikipedia distributions
One can install completely separate instances of pywikipedia in different directories (1 for each account) and have diferent  files in each of them. However, when updating the installation via CVS, one needs to run  on each folder separately. Also, every installation takes some disk space, which might be a problem on accounts with limited quota.

One pywikipedia distribution with symbolic links
Let's assume user  has a current CVS snapshot of pywikipedia in. For each of the accounts, he creates a separate directory:

foo@bar:~$ mkdir foobot foo@bar:~$ cd foobot

Pywikipedia needs then some symlinks to the main code tree created in the working directory:

foo@bar:~/foobot$ ln -s ~/pywikipedia/families foo@bar:~/foobot$ ln -s ~/pywikipedia/userinterfaces

Then,  for this account must be created as described in "Configure" section above.

Finally, the bot must be logged in the usual way:

foo@bar:~/foobot$ python ~/pywikipedia/login.py

The working directory is ready. The scripts will however require a slight modification to run (the path to the pywikipedia tree must be added to Python's path).

import sys, os sys.path.append(os.environ['HOME'] + '/pywikipedia') import wikipedia

That's all. Updating to the newest version of pywikipedia on all account at once is now a matter of running  only in the   directory.