Manual:Pywikibot/Installation/fr

Installation initiale
Vous devez d'abord choisir la branche de PWB que vous voulez utiliser :
 * Core (précédemment appelée "rewrite") : la meilleure version pour une utilisation dans des projets de la Wikimedia Foundation (comme Wikipédia), mais notez que les scripts n'ont pas tous encore été intégrés à cette branche, donc vous ne pourrez peut-être pas exécuter certains scripts (voir la liste de compatibilité).
 * Compat (précédemment appelée "trunk") : vieille, lente et sale mais que vous pouvez utiliser tellement plus facilement dans des projets hors Wikimedia Foundation (par exemple pour des wikis sans support API) et la plupart des scripts se trouvent dans cette branche.

En fonction de la branche que vous voulez installer et de de votre système d'exploitation, vous devez faire les choses suivantes :
 * 1) Télécharger Python (pour les utilisateurs de Windows) ou le mettre à jour si nécessaire (utilisateurs de Mac).
 * 2) Installer httplib2 (seulement pour "core", si vous utilisez "compat" ce n'est pas nécessaire).
 * 3) Télécharger Pywikibot.

Après cela, vous devez créer un fichier nommé "user-config.py" et vous N'avez PAS besoin "d'installer" Pywikibot pour l'utiliser. En fait, vous avez juste à l'exécuter depuis le dossier où vous l'avez téléchargé (que vous utilisiez Git ou des versions compilées installables).

Télécharger Python
Requirements: Python v2.5 or higher is required for compat. Python v2.7 is required for core. Python branch v3.x isn't currently supported!


 * Mac et Unix : Python est déjà présent sur Mac OS X et sur certaines versions d'Unix (bien qu'il puisse être nécessaire ou recommandé de le mettre à jour si vous avez une très vieille version).
 * Windows : [$Python2_dl Téléchargez la dernière version 2.x de Python ici]. Vous devriez utiliser les versions 2.5, 2.6 ou 2.7 pour "compat". Les autres versions ne sont pas supportées et si vous utilisez ces versions votre robot ne fonctionnera pas correctement. Après téléchargement, installez Python.

Télécharger Pywikibot
The easiest way to download Pywikibot is to use the latest nightly release. Just download the pywikibot zip file to your computer and decompress the file - there is no further installation required.

Télécharger Pywikibot avec Git
Pour une installation avec Git vous devriez exécuter :
 * Pour "core" (anciennement "rewrite")
 * Pour "compat" (anciennement "trunk")

L'option  installe automatiquement les sous-modules nécessaires (comme les messages ou l'orthographe i18n) mais si vous n'utilisez pas cette option, vous devrez les installer à part après le clonage. Il y a deux commandes (i18n est vraiment nécessaire même pour les robots en anglais) :

Télécharger Pywikibot avec SVN
Si vous ne voulez pas utiliser Git vous pouvez aussi utiliser SVN. Pour une installation avec SVN vous devrez exécuter : Pour mettre à jour le code :
 * Pour "core" (anciennement "rewrite")
 * Pour "compat" (anciennement "trunk")

Télécharger Pywikibot avec TortoiseSVN pour les utilisateurs de Windows
Si vous voulez utiliser TortoiseSVN vous devriez l'utiliser comme suivant :

Maintenant nous devons installer les libraires externes utilisées par le framework. Il y a plusieurs manières de faire cela, par exemple avec la commande checkout. Une autre manière est d'utiliser des propriétés :
 * Pour la version "core" (anciennement "rewrite")
 * 1) Faites un clic droit sur votre dossier préféré et exécutez
 * 2) Choisissez  et collez l'URL
 * 3) Choisissez  et changez le dossier par défaut, par exemple , pour   si vous voulez.
 * 4) Confirmer avec.
 * 1) Faites un clic droit sur votre dossier de travail
 * 2) Sélectionnez le dernier item dans la liste déroulante qui devrait être les
 * 3) Sélectionnez le tableau  et cliquez sur le bouton
 * 4) Cliquez sur  et sélectionnez.
 * 5) Cliquez encore une fois sur   pour ajouter un nouveau item externe.
 * 6) Tapez   dans   et   dans
 * 7) Confirmez avec   pour cet item
 * 8) Cliquez encore sur   pour ajouter un second item externe
 * 9) Tapez   dans   et   dans
 * 10) Confirmez avec   pour cet item
 * 11) Confirmez avec   pour les paramètres externes.
 * 12) Confirmez avec   pour la configuration des propriétés.
 * 13) Confirmez avec   pour les propriétés du dossier
 * 14) Maintenant faites un clic droit sur votre copie de travail et sélectionnez   pour télécharger les librairies externes.

Maintenant nous devons installer les librairies externes utilisées par le framework. Il y a différentes façons de faire cela, par exemple avec la commande "checkout". Une autre façon est d'utiliser les propriétés de la même façon que dans la version "core"
 * Pour la version "compat" (anciennement "trunk")
 * 1) Faites un clic droit sur votre dossier préféré et exécutez
 * 2) Choisissez   et collez l'URL
 * 3) Choisissez   et changez le dossier par défaut, par exemple , pour   si vous voulez.
 * 4) Confirmez avec

Right-click on your working copy and choose
 * Updating the working copy

Shortcut in command line
To allow your source code to be developed outside of the pywikibot source directory, add something like: to a file that gets run on login, usually ~/.bashrc - this avoids typing the export PYTHONPATH part in each time you log in. Naturally, change paths to match your installation.

Similarly, you can set the PYWIKIBOT_DIR environment variable to specify the directory in which user-specific information is stored (in particular, user-config.py which contains login data for the bot).

Windows users: create a shortcut
How to make a quick shortcut to run commands (Windows users):

If you're installing Pywikibot in a folder such as "My Documents" it may be troublesome to repeatedly use the "chdir" command to go into the folder to run the bots.

On Windows you can create a shortcut which will open the command box which you can use to run bots easily. Just follow these steps to create one:
 * 1) Right click the folder pywikibot is installed in.
 * 2) Click "Create shortcut". A new shortcut icon with the arrow key will be created.
 * 3) Right click on the new shortcut, and click properties.
 * 4) In the properties window, in the target box type in cmd.exe.
 * 5) In the "start in" box enter the full address of pywikibot.
 * 6) Click "OK".
 * 7) Click the shortcut and the cmd.exe opens up with the full path listed.
 * If you press F5 to refresh the window (or re-open the shortcut's properties), you will notice that the shortcut icon has changed.

Updating

 * If you used Git for downloading Pywikibot, you must go to the your directory and run the following command:


 * If you are using a nightly version, the process is a bit more complicated. You have to re-download a full copy from here. Before installing it, backup your configuration files and scripts (user-config.py, any family file, or custom script that you might have created, and any current dump xml file you're using for a wiki). Replace your pywikibot directory by the new version you just downloaded. Restore your configuration files. If you're not sure of what you're doing, do not erase but keep a backup of your complete old pywikibot directory, to avoid losing any important files.

Automatic Updating on Wikimedia Labs or Toolserver
For automatic updating you can make update bash file and put it in root and fill it with these commands, For WMF labs (in your service group): and then run crontab -e and enter the following to make your bot to run every day at 00:00AM (midnight): Notice: in these cods yourservicegroup is name of your service group (without "-local").

For auto-updating in toolserver you just need to as the same as above but instead of "/data/project/yourservicegroup/" you need to enter "/data/project/yourusername/" which is "yourusername" is your user name!

Dependencies
The pywikibot framework is quite a big and complex code and as such needs external python modules (libraries) from other sources also in order to work properly. The dependencies can be installed manually or automatically (not supported by core yet).

If any issues arise during installation (of dependencies) please file a bug report or write to the pywikipedia-l maillist.

Automatic (recommended)
If available this is the recommended way, because this will result in an identical setup on all machines. All you have to do is just execute your favorite script after installation and pywikibot will ask you whether you want to install missing packages.

Packages will be installed from OS package management if possible (all Linux, not under win). If they cannot be found they will be downloaded as archive from original source, extracted and installed. In the course of this process a few packages have to be slightly modified in order to work seamlessly with pywikibot. This modification needs an additional binary tool called patch (patch.exe under win). Unfortunately this is not available from MS; however, we can use a port of the original linux code (gnuwin32 patch.exe)

It is worth mentioning here that - despite the OS package management "install mode" - all files are installed locally into the externals/ directory of pywikibot. This is a very useful feature for users that do not have permission to install software to their system, e.g. non-admins.

Manual (for experts)
In order to install the needed packages manually, you first need to know which ones. A full list of all needed modules can be found in externals/__init__.py and contains: Which ones you really need, depends strongly on the script you intend to run - if you are unsure use the automatic mode above. In order to check correct installation just run a bot script. If the dependencies are satisfied everything will be ok, else the framework will complain and ask whether it should install missing packages automatically.
 * framework core code:
 * i18n [git submodule]
 * spelling [git submodule]
 * httplib2 [git submodule]
 * BeautifulSoup.py
 * patch.exe
 * depending of which script will be used:
 * opencv, opencv/haarcascades [git submodule]
 * pycolorname [git submodule]
 * irclib
 * mwparserfromhell
 * parse-crontab
 * odfpy
 * openpyxl
 * python-colormath
 * jseg, jseg/jpeg-6b
 * mlpy
 * music21
 * ocropus
 * pydmtx
 * py_w3c
 * zbar
 * (slic)
 * (bob, xbob_flandmark)

Setup on Wikimedia Labs/Tool Labs server
In order to install your bot onto the Wikimedia servers and run it from there, make sure first to become familiar with Wikimedia Labs/Tool Labs environment.

In the next step you have to request several accounts (for labs, for the tools project, your tool), provide an ssh key and so on. How to do this and then proceed, is described in full detail in Setup pywikibot on Labs.

Pywikibot source repo moved (from svn) to git, please confer Manual:Pywikipediabot/Gerrit first.

The bots projects here has become obsolete use tools now, in order to do so follow Tools/Help to get an account. Then create your tool (service group).

If you used the toolserver in the past and know how everything used to work there, confer migrating from toolserver for more info.

Now you are ready to start. Login to Labs tools project: $ ssh USERNAME@tools-login.wmflabs.org switch to the tool account with maintainer@tools-login:~$ become toolname local-toolname@tools-login:~$

Now install/clone the pywikibot code to your tool account as described below.

core
Similar to the instructions given in this mail do: $ git clone --recursive https://gerrit.wikimedia.org/r/pywikibot/core.git pywikibot-core $ cd pywikibot-core

Now you have to setup pywikibot. Choose any one of the following processes to configure your system:
 * Execute
 * Run your favorite bot script (e.g. ) since you are doing this in a fresh clone, it will trigger a bunch of questions on how you want to configure your local copy, answer them carefully in order to proceed.
 * If you already have a config file(s) from a previous version, you can copy those existing files into the right places (e.g. pywikibot-compat/).

Further things you might have to to do (depending on what bot scripts you want to run) is to setup all externals properly - which still has to be done manually in core $ cd externals $ cat READM and follow the instructions there.

You will also have to enter the password for your bot eventually.

Now you have finished the configuration of core and can continue setting up the jobs to execute.

compat
Do: $ git clone --recursive https://gerrit.wikimedia.org/r/pywikibot/compat.git pywikibot-compat

Now, as similarly described in the core section above, you have to setup pywikibot. Choose any one of the following processes to configure your system:
 * Execute
 * Run your favorite bot script (e.g. ) since you are doing this in a fresh clone, it will trigger a bunch of questions on how you want to configure your local copy, answer them carefully in order to proceed.
 * If you already have a config file(s) from a previous version, you can copy those existing files into the right places (e.g. pywikibot-compat/).

See this article for more details on configuring your bot including creating the files manually. You may setup all externals manually if you want - but this is not needed in compat, confer Manual:Pywikipediabot/Installation for further info.

You will also have to enter the password for your bot eventually.

Now you have finished the configuration of compat and can continue setting up the webspace and jobs to execute.

setup web-space
Per default, the directory listing on http://tools.wmflabs.org/TOOLNAME is disabled. If you want to allow it for all users, login to your tool account (as already described) and $ cd ~/public_html $ echo Options +Indexes > .htacces

If you run a bot with the  option, you will find the log files within the logs/ directory. If you want to allow users to access it from the web, do $ cd ~/public_html $ mkdir logs $ cd logs $ ln -s ~/pywikibot-core/logs cor

If you want a specific file type to be handled different by your browser, e.g. .log files like text files, use (confer this) $ echo AddType text/plain .log > .htaccess and (don't forget to) clear your browsers cache afterwards.

Next you might want to consider you cgi-bin directory $ cd ~/cgi-bin follow the hints given at wikitech:Nova Resource:Tools/Help exactly, e.g. even the two commands

$ /usr/bin/python     # valid $ /usr/bin/env python # in-vali work and do the same in shell, only the first one is valid and works here, the second is invalid! Another point to mention is that PHP scripts go into public_html, not cgi-bin. Python scripts on the other hand can be placed in public_html or cgi-bin as you wish. I would recommend to use public_html for documents and keep it listable, whereas cgi-bin should be used for CGI scripts and be protected (not listable).

Setup Job Submission
In order to setup the submission of the jobs you want to execute and use the grid engine you should first consider wikitech:Nova Resource:Tools/Help and if you are familiar with the Toolserver and its architecture consult Migrating from toolserver also.

In general labs uses SGE and its commands like qsub et al, this is explained in this document which you should use in order to get an idea which command and what parameters you want to use.

An infinitely running job (e.g. irc-bot) like this (cronie</tt> entry from TS submit host): 06 0 * * * qcronsub -l h_rt=INFINITY -l virtual_free=200M -l arch=lx -N script_wui $HOME/rewrite/pwb.py script_wui.py -log becomes $ jsub -once -continuous -l h_vmem=256M -N script_wui python $HOME/pywikibot-core/pwb.py script_wui.py -log or shorter $ jstart -l h_vmem=256M -N script_wui python $HOME/pywikibot-core/pwb.py script_wui.py -log the first expression is good for debugging. Memory values smaller than 256MB seam not to work here, since that is the minimum. If you experience problems with your jobs, like e.g. Fatal Python error: Couldn't create autoTLSkey mapping you can try increasing the memory value - which is also needed here, because this script uses a second thread for timing and this thread needs memory too. Therefore use finally $ jstart -l h_vmem=512M -N script_wui python $HOME/pywikibot-core/pwb.py script_wui.py -log Now in order to create a crontab follow Scheduling jobs at regular intervals with cron and setup for crontab file like: $ crontab -e and enter PATH=/usr/local/bin:/usr/bin:/bin 06 0 * * * jstart -l h_vmem=512M -N script_wui python $HOME/pywikibot-core/pwb.py script_wui.py -lo

additional configuration
Furthermore additional tools to support you and your bot at work are available:
 * wikitech:Nova Resource:Tools/Help, basically out-of-the-box but just for a short time period
 * wikitech:Nova Resource:Tools/Help
 * Gerrit/New repositories
 * Git/New repositories/Requests