Documentation du projet pythoneon

Avant tout, il faut choisir les outils de base qui permettent d’effectuer le cycle :

écriture -> compilation -> écoute -> écriture -> compilation -> etc.

ce qui est expliqué dans la page consacrée à la caisse à outils

Peut-être meme qu’il faut expliciter cette documentation:

Principe de base

Une page HTML est consacrée

  • soit à un module;
  • soit à une partie de module;
  • soit à un thème englobant des généralités ou englobant plusieurs traitements ou constructions.

Les objets

Il y a des modules, des classes, des fonctions, des variables et le reste. Cette définition est rabiatte: je ne suis pas grammairien.

Il est recommandé de bien expliquer ce que fait chaque module, classe, fonction etc. car les modules qui sont nommés dans le pythoneon.pth sont facilement importés lors d’un session interactive de Python. En appelant help(un_module) on dispose d’un résumé de ce que le module peut faire et on peut lire les __doc__ de chaque classe ou fonction (à condition de les avoir rédigés).

On peut aussi installer le logiciel Sphinx qui traite les fichiers en rst au fur et à mesure qu’on dispose d’une bibliothèque de modules (les Américains appellent cela une librairie - car à cause d’Amazon ils ne savent pas ce que c’est).

Présentation

Si la page est consacrée à un module, le nom du module est lisible dans le titre de la page.

Les sections traitent:

  • des fonctions, par exemple:

    def une_fonction(param0, param1, ...):
    print param0
    print param1

  • des classes, par exemple:

    class LaClasse(OrigineStr):
    def __init__(self):
        print "Vous êtes ici !"

  • des variables:

    SR = 384000

Les paramètres des fonctions et méthodes seront expliquées par des listes.

Style de la rédaction des pythons

Python, c’est le langage; tandis qu’un python c’est un module ou un script ou un programme écrit en Python (n’en faites pas état dans une discussion; c’est une dénomination personnelle).

Les modules

Il est très important de respecter les us et coutumes que préconisent ceux qui ont beaucoup erré dans l’interprétation des messages d’erreurs et dans la recherche des erreurs de logique. Ces us sont en général spécifiés par des PEPs qu’on retrouve quelque part sur le site

http://www.python.org

en particulier, la PEP 8 traitant le style

http://legacy.python.org/dev/peps/pep-0008/

Le labo informatique Logilab a conçu pylint pour aider le rédacteur de pythons; je conseille vivement d’installer pylint et d’en faire un usage quotidien pour améliorer le style, car la conséquence d’un bon style est:

  • une lecture plus facile,
  • d’où une maintenance et une réutilisation plus faciles.

Par exemple, je déconseille d’écrire:

from conversions import *

C’est pourtant ça qu’on trouve dans beaucoup de manuels (sur les graphiques par ex.) et on explique que c’est par commodité. Quelle commodité ? Ces bouquins étant écrits en anglo-américain, il faut, après, s’ingénier à distinguer entre les termes builtin (normalement en anglais) et les noms des objets importés (en catimini) - ce qui est très peu commode quand on débute et une généreuse source d’erreurs.

Il est de fait interdit de donner aux modules un nom qui existe déjà, sous peine de s’exposer à des confusions obscures. Si on a l’intention de rédiger un module xxx.py, je conseille de lancer Python en interactif et de demander

import xxx

si ce module est effectivement importé, c’est qu’il existe déjà; si on en rédige un deuxième, les ennuis commencent.

Les tests

En général, il est nécessaire de tester ce qu’on vient de fabriquer. Les géniaux qui sont absolument sûrs de leurs moutures sont dispensés de cette corvée.

Le minimum consiste à écrire un python de test pour chaque module. Mais pour plus de clarté on peut aussi écrire un python-test de classe ou de fonction. J’ai pris l’habitude de donner à ces modules des noms qui commencent par t_; ce qui donne

t_nom_du_module.py
t_nom_de_la_classe.py
t_nom_de_la_fonction.py

Comme tous ces modules ont des structures semblables, j’ai une collection de modèles; voir: Modèles

Éloge de Python

Python permet une écriture lisible qui donne l’impression de ne pas être le servant de l’ordinateur. L’agencement structuré du source nous débarasse de précautions inutiles (p.ex. écrire obligatoirement des séparateurs d’instructions). Il est possible de penser le flux de ce qu’il faut faire selon une logique qui tient à l’enseignement du calcul et de l’algèbre, donc des mécanismes logiques parfaitement intériorisées.

Pour avoir pratiqué ou du moins avoir tâté d’autres langages:

  • le Basic de base (horrible);
  • Algol et Fortran de façon purement théorique;
  • Sorbas - Structure Oriented Basic - avec un réel plaisir, car ce Sorbas montrait ce qu’on pouvait faire en Basic;
  • TurboPascal efficace, bon marché, fiable - un langage qui m’a sauvé la vie;
  • Common Lisp, Scheme, efficaces mais finalement très contraignants par leur syntaxe à rebrousse-poil; l’efficacité me semblant acquise au prix de la lisibilité:

j’affirme que Python permet de voyager plus loin et en classe de luxe avec un billet vraiment bon marché.

Avantages d’un langage informatique généraliste

Python est un langage pour tous usages: fabrication de pages web, logiciels de compta, analyse de données astrophysiques, gestion de serveurs, interfaces pour usagers, etc.

Le langage est à la pointe du savoir informatique actuel et il intègre les concepts informatiques les plus modernes. Mais la base du langage est pratiquement invariable; ce qui veut dire qu’on n’est pas du tout obligé de se servir de ces outils nouveaux.

Le problème des langages dédiés (p.ex. Csound) est qu’ils semblent bien adaptés au domaine concerné (ici, la musique et la composition musicale). En fait, ils traînent des syntaxes totalement obsolètes où l’usager est le servant de l’ordinateur - et non l’inverse.