Manuel:Conventions de codage/Python
 | Cette page documente un guide de développement de MediaWiki, construit au fil du temps par consensus des développeurs (ou parfois simplement par un des développeurs principaux) |
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 setup.py 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 paster create 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
importosimportreimportsysimportpymongofromsqlalchemyimportcreate_engine,exceptionsfrommymoduleimportMyCustomException,models,viewsVoici quelques cas à éviter :
importsys,os# importer différents modules sur une même lignefromsqlalchemyimport*# n'importez pas *from.modelsimportutil# utilisez des noms complètement qualifiés plutôt que des imports relatifsExemples d'import développés
Voici une version détaillée plus abstraite (les commentaires ne servent qu'à l'explication) :
# import complet des modules stdlib dans l'ordre alphabétiqueimporta_stdlib_moduleimportb_stdlib_module# import des sous-modules des modules stdlib dans l'ordre alphabétique à la fois verticalement et horizontalementfromanother_stdlib_moduleimporta_stdlib_submodule,b_stdlib_submodulefromc_stdlib_moduleimportanother_stdlib_submodule,last_stdlib_submodule# import complet de modules tiers dans l'ordre alphabétiqueimporta_third_party_moduleimportb_third_party_module# import de sous-modules de modules tiers, dans l'ordre alphabétique à la fois verticalement et horizontalementfromanother_third_party_moduleimporta_third_submodule,b_third_submodulefromc_third_party_moduleimportanother_third_submodule,last_third_submodule# import complet des modules de l'application courante dans l'ordre alphabétique, avec des imports absolusimportmyapp.a_moduleimportmyapp.b_module# import de sous-modules des modules de l'application courante, dans l'ordre alphabétique à la fois verticalement et horizontalementfrommy_app.another_moduleimporta_submodule,b_submodulefrommy_app.c_moduleimportanother_submodule,last_submoduleDocstrings 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
deffractionize(first,second=1):""" Crée une chaîne représentant une fraction composée de deux nombres. Arguments des mots-clés : first -- le numérateur second -- le dénominateur (tout sauf 0) """return"{0} / {1}"%(first,second)Ceci permet de générer la documentation de manière automatique et d'utiliser la fonction intégrée help 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.
defparse(source:"the original document",lang:"quelle est la syntaxe du marquage utilisée ? [md|rst|textile]",force:"Ignorer les erreurs de syntaxe ?"):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 hash ou id). PEP8 indique que pour résoudre ces problèmes vous devez ajouter le caractère souligné '_' à la fin du nom, tel que hash_ ou class_ (bien que si vous appelez une variable class_ 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 import as.
fromsqlalchemyimportexceptionsassa_exceptionsfrommymoduleimportexceptionsasmy_exceptions