Utiliser la documentation des modules de Python

Vous pouvez utiliser la fonction doc() chaque fois que vous en avez besoin pour obtenir de l’aide. Cependant, il existe un meilleur moyen d’étudier les modules et les bibliothèques fournis avec Python : c’est la documentation de celui-ci. Celle-ci apparaît parfois sous le nom Module Docs dans le dossier de Python. On y fait aussi référence sous le nom de pydoc. Mais quelle que soit l’appellation, cette documentation est une aide précieuse pour les développeurs. Voyons donc cela de plus près.

Ouvrir l’application pydoc

Pydoc est tout simplement une autre application Python. Elle se trouve dans le dossier \Python310\Lib de votre système sous le nom de pydoc.py. Comme tout autre fichier .py, vous pouvez l’ouvrir dans IDLE et étudier son fonctionnement. Une autre manière d’y accéder consiste à choisir le raccourci Python 3.10.7 Module Docs de votre installation Python, ou encore à taper une commande en mode Invite de commandes ou Terminal.

L’application crée un serveur localisé qui fonctionne avec votre navigateur Web par défaut afin d’afficher des informations sur les modules et les bibliothèques de Python. Lorsque vous la lancez, vous voyez une Invite de commandes (ou un Terminal) semblable à l’illustration de la Figure.

Lancer pydoc signifie ouvrir une fenêtre de commandes (un Terminal) pour démarrer le serveur.

Comme pour tout serveur, votre système peut vous demander une autorisation d’accès. Par exemple, votre pare-feu peut vous signaler qu’un programme inconnu tente d’accéder au système local. Vous devez alors valider la permission demandée pour accéder aux informations fournies par pydoc. Il en va de même le cas échéant pour votre antivirus. Sous Windows, et d’autres plates-formes, vous aurez donc peut-être besoin d’élever votre niveau de privilèges.

Normalement, le serveur ouvre automatiquement une fenêtre dans votre navigateur, comme sur la Figure.

Cette fenêtre liste les divers modules contenus sur votre système, y compris les modules personnalisés que vous auriez créés et qui seraient contenus dans le chemin d’accès de Python. Pour voir le contenu correspondant, il vous suffit de cliquer sur un lien.

Bien entendu, toutes ces documentations sont en anglais, ce dont vous vous doutiez déjà.

L’Invite de commandes/Terminal offre deux commandes pour contrôler le serveur. Il vous suffit pour cela de taper la lettre correspondante :

Lorsque vous avez terminé votre navigation, n’oubliez pas de taper q et d’appuyer sur Entrée pour refermer le serveur. Celui-ci va libérer les ressources qu’il consommait, et refermer tous les trous ^漏洞 qu’il aurait pu provoquer dans votre pare-feu.

Utiliser les liens d’accès rapide

Si vous observez le haut de la Figure, vous allez remarquer trois liens sur la droite.

Ces liens fournissent un accès rapide aux fonctions du site. La première page affichée est toujours celle qui correspond au lien Module Index. Si vous avez besoin de revenir à cette page, il vous suffit donc à tout instant de cliquer sur ce lien.

Le lien Topics ouvre la page illustrée sur la Figure. Elle propose des liens vers des sujets essentiels de Python. Si vous voulez en savoir plus sur les valeurs booléennes, par exemple, cliquez sur le lien BOOLEAN. La page qui va s’afficher alors décrit la manière dont les valeurs booléennes fonctionnent dans Python. En bas de cette page, vous trouvez d’autres liens permettant d’accéder à des informations complémentaires utiles.

Le lien Keyword donne accès à la page illustrée sur la Figure. Vous y voyez une liste de mots-clés supportés par Python. Si vous voulez par exemple en savoir plus sur la création de boucles for, cliquez sur ce lien.

La page Keywords contient une liste de mots-clés supportés par Python.

---

Taper un terme^术语 à rechercher ^{键入搜索关键词}

Les pages contiennent également deux champs de texte^{两个文本字段}, en haut et vers la droite. Le premier est suivi d’un bouton Get, et le second d’un bouton Search. Lorsque vous entrez un terme à rechercher dans le premier champ et que vous cliquez sur le bouton Get, vous obtenez la documentation qui concerne ce module ou cet attribut particulier. La Figure illustre ce comportement. Pour voir ce qui se passe, tapez print et cliquez sur Get.

Si vous tapez un critère^标准 dans le second champ et que vous cliquez sur le bouton Search, vous obtenez cette fois une liste de tous les sujets qui peuvent avoir un rapport avec ce terme. Essayez par exemple de taper print et de cliquer sur Search.

Get permet d’obtenir des informations spécifiques sur le terme recherché.

La Figure illustre le résultat obtenu. Vous pouvez ensuite cliquer sur un autre lien, par exemple calendar, si vous voulez consulter des informations techniques sur la gestion de l’affichage des dates.

Le bouton Search permet d’obtenir une liste de sujets liés au terme recherché.

Voir les résultats

Les réponses que vous obtenez peuvent varier considérablement. Certains sujets sont brefs, comme dans le cas de la Figure, et donc peuvent facilement être lus, et même imprimés. Mais d’autres sont bien plus développés. Si vous cliquez par exemple sur le lien calendar, visible sur la Figure, vous allez voir s’afficher une page plutôt copieuse ^{丰富的, 丰盛的} (voir la Figure).

Certaines pages contiennent des informations extrêmement copieuses.

Dans ce cas particulier, vous voyez des informations qui concernent le module, les erreurs gérées, ses classes, ses fonctions, ses données, et ainsi de suite. Bien entendu, la masse de renseignements à laquelle vous pouvez accéder dépend en partie de la complexité du sujet, et en partie du niveau de description fourni par le créateur du module. Si vous faites l’essai depuis la page Module Index avec le module MyLibrary utilisé dans ce chapitre, vous ne verrez qu’une liste de ses fonctions sans aucune description.

Bien documenter vos modules est important non seulement pour vous, mais aussi pour tous ceux qui pourraient avoir besoin de les utiliser plus tard.