Manuel:Pywikibot/Cookbook/Introduction

Créer un script

Encodage et environnement

It is vital that all Python 3 source files MUST be UTF-8 without a BOM. Therefore it is a good idea to forget the bare Notepad of Windows forever, because it has the habit to soil files with BOM. L'éditeur minimal suggéré est Notepad++, qui est conçu pour la programmation et qui est multi-plateformes. Il a un menu d'encodage dans lequel vous pouvez visionner ce dont je parle, et vous pouvez définir UTF-8 sans BOM comme encodage par défaut. Tout vrai IDE de programmation fonctionnera, par ex. Visual Studio Code est assez populaire de nos jours. Python possède un éditeur intégré appelé IDLE, qui utilise le bon encodage et montre les numéros de ligne par défaut.

Where to put

scripts/userscripts directory is designed to host your scripts. Ceci est une très bonne idée car ce répertoire ne changera pas quand vous mettrez Pywikibot à jour, et vous pouvez facilement sauvegarder votre propre travail, en ne prenant en compte que ce répertoire.

Vous pouvez aussi créer votre propre structure de répertoire. If you would like to use other than the default, search for user_script_paths in user-config.py, and you will see the solution.

See also pywikibot wrapper script.

Exécuter un script

Il existe essentiellement deux méthodes. The recommended one is to call your script through pwb.py. Your prompt should be in Pywikibot root directory where pwb.py is and use:

python pwb.py <global options> <name_of_script> <options>

• Global options: see global options
• Advantages of this method: see [wmdoc:pywikibot/master/scripts_ref/scripts.html#module-scripts scripts.html]

However, if you don't need these features, especially if you don't use global options and don't want pwb.py to handle command line arguments, you are free to run the script directly from userscripts directory.

Règles de codage

Of course, we have PEP 8, Python Coding conventions and Pywikibot/Development/Guidelines. But sometimes we feel like just hacking a small piece of code for ourselves and not bothering the style.

Several times a small piece of temporary code begins to grow beyond our initial expectations, and we have to clean it.

If you'll take my advice, do what you want, but my experience is that it is always worth to code for myself as if I coded for the world.

On the other side, when you use Pywikibot interactively (see below), it is normal to be lazy and use abbreviations and aliases. For example

>>> import pywikibot as py
>>> import pywikibot.pagegenerators as pg

Note that the py alias cannot be used in the second import. It will be useful later, e.g. for py.Site().

However, in this cookbook we won't use these abbreviations for better readability.

Commencer et terminer

In most cases you see something like this in the very first line of Pywkibot scripts:

#!/usr/bin/python or #!/usr/bin/env python3

This is a shebang. If you use a Unix-like system, you know what it is for. If you run your scripts on Windows, you may just omit this line, it does not do anything. But it can be a good idea to use anyway in order someday others want to use your script.

The very last two lines of the scripts also follow a pattern. They usually look like this:

if __name__ == '__main__':
    main()

This is a good practice in Python. When you run the script directly from command line (that's what we call directory mode), the condition will be true, and the main() function will be called. That's where you handle arguments and start the process. On the other side, if you import the script (that is the library mode), the condition evaluates to false, and nothing happens (just the lines on the main level of your script will be executed). Thus you may directly call the function or method you need.

You may see a practical example in the Follow your bot section.

Scripts et utilisation interactive

For proper work we use scripts. But there is an interesting way of creating a sandbox. Just go to your Pywikibot root directory (where pwb.py is), type:

pwb.py shell

This is a short way to invoke the Python shell and importing pywikibot at once. Now you can continue with Pywikibot like:

>>> site = pywikibot.Site()

Now you are in the world of Pywikibot (if user-config.py is properly set). This is great for trying, experimenting, even for small and rapid tasks. For example to change several occurences of Pywikipedia to Pywikibot on an outdated community page just type:

>>> page = pywikibot.Page(site, 'titlecomeshere')
>>> page.text = page.text.replace('Pywikipedia', 'Pywikibot')
>>> page.save('Pywikibot forever!')

Throughout this document >>> prompt indicates that we are in the interactive shell. You are encouraged to play with this toy. Where this prompt is not present, the code lines have to be saved into a Python source file. Of course, when you use save(), it goes live on your wiki, so be careful. You may also set the testwiki as your site to avoid problems.

A big advantage of shell is that you may omit the print() function. In most cases

page.title()

equals to

print(page.title())

Walking the namespaces section shows a rare exception when these are not equivalent, and we can take advantage of the difference for understanding what happens.

Documentation et aide

We have three levels of documentation. As you go forward into understanding Pywikibot, you will become more and more familiar with these levels.

1. Manual:Pywikibot – written by humans for humans. This is recommended for beginners. It also has a "Get help" box.
2. pywikibot – mostly autogenerated technical documentation with all the fine details you are looking for. Click on stable if you use the latest deployed stable version of Pywikibot (this is recommended unless you want to develop the framework itself), and on master if you use the actual version that is still under development. Differences are usually small.
3. The code itself. It is useful if you don't find something in the documentation or you want to find working solutions and good practices. You may reach it from the above docs (most classes and methods have a source link) or from your computer.