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.

Conflicts de nommage
Un problème général est la collision avec les noms déjà utilisés dans le code intégré. There are some builtin names (like  and  ) that you may want to use in your code. The PEP8 way to deal with these conflicts is by appending an underscore to the name, such as  or   (although if you're naming a variable   that may be a code smell).

If you find yourself in conflict with the name of some part of another module,  is your friend.

Voir aussi

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