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
import os
import re
import sys
import pymongo
from sqlalchemy import create_engine, exceptions
from mymodule import MyCustomException, models, views
Voici quelques cas à éviter :
import sys, os # importer différents modules sur une même ligne
from sqlalchemy import * # n'importez pas *
from .models import util # utilisez des noms complètement qualifiés plutôt que des imports relatifs
Exemples 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étique
import a_stdlib_module
import b_stdlib_module
# import des sous-modules des modules stdlib dans l'ordre alphabétique à la fois verticalement et horizontalement
from another_stdlib_module import a_stdlib_submodule, b_stdlib_submodule
from c_stdlib_module import another_stdlib_submodule, last_stdlib_submodule
# import complet de modules tiers dans l'ordre alphabétique
import a_third_party_module
import b_third_party_module
# import de sous-modules de modules tiers, dans l'ordre alphabétique à la fois verticalement et horizontalement
from another_third_party_module import a_third_submodule, b_third_submodule
from c_third_party_module import another_third_submodule, last_third_submodule
# import complet des modules de l'application courante dans l'ordre alphabétique, avec des imports absolus
import myapp.a_module
import myapp.b_module
# import de sous-modules des modules de l'application courante, dans l'ordre alphabétique à la fois verticalement et horizontalement
from my_app.another_module import a_submodule, b_submodule
from my_app.c_module import another_submodule, last_submodule
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
def fractionize(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.
def parse(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.
from sqlalchemy import exceptions as sa_exceptions
from mymodule import exceptions as my_exceptions