Manual:Coding conventions/Python/fr

Cette page contient les règles de codage  pour les projets Python faisant partie du projet MediaWiki lui-même et de ceux qu'il supporte.

Préambule
Vous devez vous rappeler d'abord que les règles de codage ne sont que des indications pouvant être outrepassées s'il existe une bonne raison.


 * Visez la lisibilité et l'évidence plutôt que la stricte adhérence dans le souci de respecter absolument.
 * Le code est lu beaucoup plus souvent qu'il n'est écrit.
 * Soyez cohérent avec le code existant et utilisez votre meilleure appréciation. Si ce n'est pas trop difficile de modifier le code existant, soyez gentil, corrigez-le.

Pour tout ce qui ne se trouve pas dans ce document, voir la Proposition 0008 d'Extension de Python (PEP8) qui décrit l'utilisation générale. Les sections suivantes sont pour la plupart un résumé des sections qui référencent le plus la PEP8.

Version Python
La version minimale supportée est la 2.7, mais pour certains cas particuliers des versions plus anciennes encore sont acceptées.

Si vous ne l'avez pas déjà fait, passez à Python 3 pour vos développements locaux.

Caractère espace
L'indentation des lignes doit se faire avec 4 espaces.

Les lignes en fin de fichier doivent se terminer par un passage à la ligne suivante, tout comme les autres lignes du fichier.

Essayez d'avoir des lignes de moins de 80 caractères, mais visez la lisibilité et l'évidence plutôt que la stricte adhérence dans le souci de respecter absolument. Les lignes plus courtes ne sont qu'un effet de bord de la bonne concision de Python - des noms courts et bien significatifs, pas de code en escalier, etc. Lorsque vous coupez des lignes, choisissez évidemment la méthode la moins ambigüe selon la situation.

Structure des modules
La manière classique de distribuer les modules Python est de créer un fichier  et de mettre à niveau une bibliothèque « distribute ». Certains modules génèrent la structure de base du projet pour vous; c'est le cas de  mais ils sont obsolètes et plus maintenus. Une solution utilisable est pythong.

La structure générale des modules est la suivante : newproject ├── bin ├── distribute_setup.py ├── docs ├── newproject │    └── __init__.py ├── setup.py └── tests ├── __init__.py      └── newproject_tests.py

Les import
Dans un fichier il est souvent intéressant d'organiser ses imports d'une manière logique. Typiquement on préfère les déclarer dans l'ordre alphabétique, mais il peut être cassé si vous importez un grand nombre de bibliothèques. Pour vous aider à ne pas tomber dans ce cas, il est bon de regrouper les import dans l'ordre suivant, en séparant les blocs les uns des autres par une ligne vide :


 * imports des bibliothèques standards
 * imports tiers
 * import des bibliothèques du projet

Voici quelques cas à éviter :

Exemples d'import développés
Voici une version détaillée plus abstraite (les commentaires ne servent qu'à l'explication) :

Docstrings et annotation des fonctions
Les docstrings apparaissent généralement quand la fonction devient un tant soit peu complexe et nécessite des explications (pas utile pour les fonctions simples). Elles sont standardisées dans la PEP 257

Ceci permet de générer la documentation de manière automatique et d'utiliser la fonction intégrée  de Python.

Dans Python 3.3 et suivants, PEP 3107 décrit la syntaxe pour annoter les fonctions.

L'annotation des fonctions ne décrit pas tous les cas d'utilisation mais regroupe les cas fréquents pour améliorer la documentation de l'aide ainsi que l'annotation des types.

Conflits de nommage
Un problème général est la collision avec les noms déjà utilisés dans le code intégré. Vous voudrez probablement utiliser certains de ces noms dans votre code (comme   ou  ). PEP8 indique que pour résoudre ces problèmes vous devez ajouter le caractère souligné '_' à la fin du nom, tel que  ou   (bien que si vous appelez une variable   on peut se douter qu'elle appartienne à votre code).

Si vous rencontrez un conflit de nommage avec le contenu d'un autre module, vous pouvez utiliser.

Voir aussi

 * Règles du développement Pywikibot
 * Python : site web officiel