Manual:Pywikibot/Mac

This is a complete step-by-step guide on how to run your own pywikipedia bot on Wikimedia projects on Mac.

Downloading MacPython
Apple provides an installation of Python with every Mac OS X installation, by default. You don’t need to install Python.


 * OSX 10.8.4 (Mountain Lion) provides (i.e. provided by Apple) both Python and Pythonw 2.6; and Python and Pythonw 2.7. The default is Python 2.6 -- "$man python" for details on switching between the two if necessary.

Downloading SVN

 * OSX 10.8.4 (Mountain Lion) provides (i.e. provided by Apple) SVN: Subversion command-line client, version 1.6.18

Many Wikimedia projects require that you always should run the latest version of the Pywikipedia framework. The easiest option is to use SVN. This is no harder than running the bot itself.

Downloading the scripts
Open Terminal, you can find it by searching for it in Spotlight. (In Lion (10.7) and Mountain Lion (10.8) Terminal is found under "/Applications/Utilities" in the Finder.) Now, copy-paste the following into Terminal, and press enter/return: svn checkout http://svn.wikimedia.org/svnroot/pywikipedia/trunk/pywikipedia/ pywikipedia

Using Apple's SVN under Mountain Lion 10.8.4, the following Error will be generated by Apple's security interface (Gatekeeper): Error validating server certificate for 'https://svn.toolserver.org:443': - The certificate is not issued by a trusted authority. Use the fingerprint to validate the certificate manually! Certificate information: - Hostname: *.toolserver.org - Valid: from Sun, 26 May 2013 09:34:24 GMT until Wed, 28 May 2014 17:08:01 GMT - Issuer: GeoTrust, Inc., US - Fingerprint: bf:35:7f:3e:62:4b:89:6c:bc:39:c9:c3:38:81:9e:53:26:43:be:f4 (R)eject, accept (t)emporarily or accept (p)ermanently? Responding "p/t" may then result in: svn: warning: Error handling externals definition for 'pywikipedia/externals/pycolorname': svn: warning: OPTIONS of 'https://svn.toolserver.org/svnroot/drtrigon/externals/pycolorname': Could not read status line: connection was closed by server (https://svn.toolserver.org)
 * ( Note: This is assumed to be a transient SVN error and will likely go away with the next SVN update.)

A folder will be created in your “home” folder (look in the left column in the Finder for the house icon and your username), with the name “pywikipedia”, in which all the scripts will be when the downloading is finished. You can see when it’s finished by looking for the following in the last line in Terminal: NAME_OF_COMPUTER:~ USER_NAME$ This text is equal to the one appearing when you open Terminal (it is called the command line or terminal prompt).

Configuring
You need to configure your bot before you can use it. For this purpose we’ll use pico, a simple and straight TUI text editor. Go in Terminal and cd to your pywikipedia directory, e.g.: cd pywikipedia Then type pico user-config.py. Follow the instructions below; when you’re done press CTRL-O to write the file on disk and CTRL-X to quit the editor.
 * Note: This file does not exist as part of the download. You are creating it in this step.

Language
mylang = 'xx' “xx” is the main language you want your bot to work on, equivalent to the language code of the Wikimedia project in which the bot’s going to run.

Family
If the bot’s main wiki is Wikipedia, go right to the Username(s) section. If the bot’s main wiki is for instance Wikibooks, add this line to user-config.py: family = 'wikibooks'

NOTE: Running bots on Wiktionary is more complicated than on the other projects, and is not recommended for beginners. This will not be described further in this guide. If you’re running your bot on Commons, both mylang and family are to be set to “commons”.

Username(s)
Now, you’ll define the desired username(s) of the bot. Don’t register the bot on the wikis yet. You can do this by using the following: usernames['FAMILY']['MYLANG'] = u'ExampleBot' “MYLANG” is the same as you defined in the mylang option, and the same with “FAMILY”. If you’re running the bot on Wikipedia, the family option is not defined, but should be “wikipedia” in the above line (see examples below). The line can be defined as many times as you like (only one per wiki), for each of your bots on different WM wikis. The default will be what’s defined in mylang, except when running interwiki; the bot will edit on all the wikis defined in user-config.py.

Encoding
It’s recommended that you change the encoding to UTF-8. Especially if you are editing a wiki with non-ASCII characters, this is important, if you don’t change the encoding, you’ll end up with “?”s all over the place. For example, the Spanish name María will render like Mar?a. Add this line to user-config.py: console_encoding = 'utf-8'

API login
Because of some problems with SUL bots, the bot must log in via API. Add this line to user-config.py: use_api_login = True

Now, by using Save as, save the file in the “pywikipedia” folder. Then, close TextEdit.

EksempelBot on no.wikipedia
mylang = 'no' usernames['wikipedia']['no'] = u'EksempelBot'

console_encoding = 'utf-8' use_api_login = True

ExampleBot on Commons
mylang = 'commons' family = 'commons' usernames['commons']['commons'] = u'ExampleBot'

console_encoding = 'utf-8' use_api_login = True

BeispielBot on de.wikipedia and de.wikibooks, with de.wikipedia as main wiki
mylang = 'de' usernames['wikipedia']['de'] = u'BeispielBot' usernames['wikibooks']['de'] = u'BeispielBot'

console_encoding = 'utf-8' use_api_login = True

Registering the username on the wanted wikis
It is recommended that you are registered on the wikis where you want to run your bot. Then, when you’re logged into your own user account, write “Special:Userlogin” in the search box, then, choose to register an account. Now fill out the required fields on the page and continue. If the account creation is successful, you should now be able to run the bot.

With SUL it’s easy to run bots on several wikis. If you’ve created the bot account recently, the account is already merged.

If you created it some time ago and it’s not merged, or if it was created some time ago on other wikis, you’ll have to merge it in Special:MergeAccount. Now, when logging in, the other accounts will automatically be registered as you enter the same password for all wikis.

Bot flag and test edits
Don’t forget to apply for bot flag/permission to run the bot! On en.wikipedia and he.wikipedia (there may be more), you have to apply before you make test edits. On other wikis you can apply and make test edits right away. When you make test edits, use the argument -pt:15, which tells the bot to wait 15 seconds between each edit (4 edits/min), so the recent changes list doesn’t get flooded with the bot’s edits.

Navigating to the right folder
To run the scripts, you first need to navigate to the folder in which the scripts are. Write the following in Terminal: cd /Users/USER_NAME/pywikipedia “USER_NAME” is the home text to the right of the house icon in Finder.

Tip
The above can be unnecessarily boring to write each time you want to use the bot. Terminal saves every command you use, and you can use old commands by pressing arrow up. With one press on the arrow up button, you see the last command used. Most likely, the command you see is not the right one; simply keep pressing arrow up until you see the right one. Then, press enter/return. Now, you can start running the bot. When you’re running a script followed by another when the first one is done, you don’t have to use the navigation command once again; only if you close Terminal.

Logging in
Now, you need to log into the bot accounts on the wiki(s), by typing the following into Terminal: python login.py Terminal will ask for the password. Type the password you used when you registered the bot’s username.

If you have accounts on multiple wikis, use login.py -all Type in the passwords, as above.

Logging in is only necessary once, the bot stays logged in.

Running the scripts
After navigating to the right folder, you can now select scripts, by writing: python SCRIPT_NAME.py

To see an overview of some scripts with description pages, look here.

Arguments
Arguments are written by using a dash: - and then the name of the argument, -pt:15 for instance. Many scripts require arguments, for example interwiki.py: python interwiki.py -start:! -autonomous As default, the bot will run interwiki from the main language and project, and correct them on all registered wikis. The -start and -autonomous arguments says that it’ll check all pages on the wiki and add/modify interwikis. It will not remove anything, and it will give up when discovering conflicts, see interwiki.py.

Global arguments
All scripts recognize the following arguments:
 * -help
 * Shows the script’s help text


 * -lang:xx
 * Selects the language you want to work on. Overrides the mylang option in user-config.


 * -family:xyz
 * Selects the family you want to work on. Overrides the family option in user-config.


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


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


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


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

Updating
To update your scripts, simply write the following into Terminal: svn update pywikipedia When it’s done, it will say “At revision XXXX” (“XXXX” depending on the latest revision). If you have modified some of the scripts, don’t worry, your modifications will be merged with the changes made by updating.

If you have experience using Automator, you can do the Shell process in a workflow and save it to your desktop or on your dock, so you can reach it more easily. It’s a good idea to secondary click on it, then, while pressing Alt/Option, hold the cursor over Always open in, then choose Automator runner.

Modifying
You might want to go through the script text before you run it, because for some languages the script may be bot specific. Secondary-click on it, hold the cursor on Open in, then choose Other, scroll down and double-click on TextEdit. However, this is not mandatory, and not recommended for beginners, but if you have to; be careful when editing the scripts!

Reverting
If you want to revert your changes to a script, simply run the following: svn revert NAME_OF_SCRIPT.py

If a script suddenly doesn’t work, and produces the output  SyntaxError: invalid syntax </tt>, you have encountered an SVN conflict.

Revert the script as described above. Then try to run it. If it works, run the following in Terminal: svn resolved NAME_OF_SCRIPT.py

You can now try to make the same edits again, if desired.