GuideDeStyle

PEP 8 - Guide de Style pour Python

Cet article est une traduction libre de la PEP 8 - Guide de style pour le code Python, de la part de
GuidoVanRossum(<guido at [Link]>, également référencé comme GvR) et Barry Warsaw
(<barry at [Link]>), disponible en[Link]

Introduction
Ce document propose des conventions pour le code Python compris par la bibliothèque standard qui
accompagne la distribution. Il existe un autre document similaire1qui traite du style pour le code en C
utilisé dans l'implémentation de l'interpréteur et dans les extensions qui composent la bibliothèque standard.

Le contenu de ce document est une adaptation de l'article original Python Style Guide, de
GuidoVanRossum, avec quelques ajouts tirés du guide de style de Barry Warsaw. Où il y avait
Conflits, les règles de GvR ont été maintenues.

Une ConsistanceGrossière est le Croque-mitaine des Petites

Ment
Le but d'un guide de style est de maintenir la cohérence. La cohérence par rapport à ce guide est
importante. La cohérence par rapport à d'autres détails d'un projet est plus importante.
La cohérence par rapport à un module ou à une fonction est encore plus importante.

Mais important encore : sachez quand être incohérent - parfois, les règles de ce guide
ils ne s'appliquent tout simplement pas. En cas de doute, utilisez votre meilleur jugement. voir d'autres exemples
et décidez ce qui est le mieux. Et n'hésitez pas à demander!

Deux bonnes raisons de briser une règle :

• Quand l'adoption d'une règle rendra le code moins lisible, même pour quelqu'un
habitué à ces règles.
• Quand on souhaite être cohérent avec un autre code qui accompagne celui-ci
développement qui viole également les règles - bien que cela soit une bonne opportunité pour
réparer le désordre de quelqu'un.

Formatage du code
• Indentation
• Utilisez le format utilisé par le "Python-mode" d'Emacs : 4 espaces par niveau de
indentation. Pour un code vraiment ancien que vous ne voulez pas déranger, vous pouvez
continuer à utiliser 8 espaces. Le mode Python détecte automatiquement le niveau de
indentation prédominante dans un fichier et suit ce modèle.
• Tabulations ou espaces
 • Ne mélangez jamais les tabulations et les espaces. La façon la plus populaire d'indentation du code en
Python est uniquement avec des espaces. La deuxième forme la plus populaire est uniquement avec

tabulations. Le code avec un mélange des deux doit être converti pour n'utiliser que
espaces. (Dans Emacs, sélectionnez tout le buffer et tapez ESC-x untabify). Passant à
L'option -t pour l'interpréteur Python fait en sorte qu'il émette des avertissements concernant le code qui
mélange illégalement des tabulations et des espaces. Avec -tt, ces avis deviennent des erreurs. Ces
les options sont fortement recommandées ! Pour les nouveaux projets, il est recommandé d'utiliser
seulement des espaces. De nombreux éditeurs ont des options pour faciliter cela.
• Longueur maximale des lignes
• Il y a encore de nombreux moniteurs limités à 80 colonnes.
limitant les fenêtres à 80 caractères, cela permet d'avoir plusieurs fenêtres ouvertes, côte à côte).
Les sauts de ligne standard sur ces moniteurs sont horribles, donc, limitez tous les
lignes à un maximum de 79 caractères. (Emacs coupe les lignes qui ont exactement
80 caractères). Pour de longs blocs de texte (docstrings ou commentaires), limiter le
Le respect d'une largeur de 72 colonnes est recommandé.

La meilleure façon de continuer des lignes longues est d'utiliser la continuation implicite, entre
parenthèses, crochets et accolades. Si nécessaire, vous pouvez ajouter une paire supplémentaire de
parenthèses autour d'une expression, mais, parfois, une barre oblique inverse reste
mieux. Prenez soin d'indenter la ligne correctement. OPython-modedo
Emacs fait cela automatiquement. Exemple :
Masquer le numéro des lignes
1 classe Rectangle(Blob):
2
3 def __init__(self, largeur, hauteur,
4 noir
5 si la largeur == 0 et la hauteur == 0 et \
6 couleur == 'rouge' et accentuation == 'fort' ou \
7 mettre en évidence > 100 :
8 levez ValueError, "désolé, vous perdez"
9 si la largeur == 0 et la hauteur == 0 et (la couleur == 'rouge' ou
10 l'accentuation est None):
11 Lever une ValueError, "Je ne pense pas"
12 Blob.__init__(self, largeur, hauteur,
13 couleur, emphase, surligner

• Lignes vides
• Séparez les fonctions et les définitions de classe par deux lignes vides. Méthodes à l'intérieur de
une classe doivent être séparés par une seule ligne vide. Lignes supplémentaires
peuvent être utilisées (de manière sporadique) pour séparer des groupes de fonctions liées et
peuvent être omises entre des groupes de lignes liés, comme par exemple, des méthodes
que soient remplacées dans les sous-classes. Lorsque des lignes vides sont utilisées pour
séparer les méthodes, il doit également y avoir une ligne vide entre la ligne 'class' et le
première méthode de la classe. Utilisez des lignes vides pour séparer les blocs logiques à l'intérieur
de méthodes et de fonctions. Python accepte le caractère control-L (^L) comme espace en
branco; l'Emacs (et quelques outils d'impression) traitent ces caractères comme
saut de page, donc vous pouvez les utiliser pour séparer les pages des sections
 liées dans votre fichier.
• Importer
• Les imports doivent toujours être faits sur des lignes séparées, par exemple :

incorrect
Masquer le numéro des lignes
1importer sys, os

correct
Cacher le numéro des lignes
1importer sys
2importer os

Mais il n'y a aucun problème à utiliser :

Cacher le numéro des lignes

1des types importent StringType, ListType

• Les imports doivent toujours être placés en haut du fichier, juste après toute
commentaires ou docstrings, et avant les constantes ou les globales. Ils doivent être regroupés
suivant l'ordre :
• modules de la bibliothèque standard
• grands modules liés entre eux (par exemple, tous les modules dee-mail
utilisés par l'application)

• modules spécifiques de l'application

Vous devez laisser une ligne vide entre chaque groupe de modules.
• Lorsque vous importez une classe d'un module du même nom, il n'y a pas de problèmes à utiliser :

Cacher le numéro des lignes

1de MyClass importer MyClass
2de [Link] importer VotreClasse

• Cependant, si cela provoque des conflits avec des noms, utilisez :

Cacher le numéro des lignes

1importer MyClass
2importer [Link]

• et ensuite "[Link]" et "[Link]".

• Espaces dans les expressions et les instructions

• Guido déteste les espaces aux endroits suivants :
• Immédiatement avant et après une parenthèse, un crochet ou une accolade, comme dans :

Cacher le numéro des lignes

 1spam( jambon[ 1 ], { œufs: 2 } )

Toujours écrire ainsi :

Cacher le numéro des lignes
1spam(ham[1], {oeufs : 2})

• Juste avant une virgule, un point-virgule ou des deux-points :

Cacher le numéro des lignes

1si x == 4 : imprimer x , y ; x , y = y , x

Toujours écrivez comme ça :

Cacher le numéro des lignes

1si x == 4 : imprimer x, y ; x, y = y, x

• Logo avant la parenthèse qui ouvre la liste des arguments d'une fonction, comme dans :

Masquer le numéro des lignes

1spam (1)

Toujours écrire :
Cacher le numéro des lignes
1spam(1)

• Immédiatement avant la clé qui ouvre un index, comme dans :

Cacher le numéro des lignes

1dict ['key'] = list [index]

Écrivez toujours :

Cacher le numéro des lignes

1dictionnaire['clé']

• Mais qu'un espace autour d'un opérateur, pour aligner les opérandes :

Masquer le numéro des lignes

1x = 1
2y = 2
3long_variable = 3

Écrivez :
Cacher le numéro des lignes
1x = 1
2y = 2
3long_variable = 3
 • Autres recommandations
• Entourez toujours les opérateurs binaires suivants d'un espace unique de chaque côté
lado: =, ==, <, >, !=, <>, <=, >=, in, not in, is, and, or, not

• Utilisez votre jugement au moment d'insérer des espaces entre les opérateurs arithmétiques.
Exemples :
Cacher le numéro des lignes
1i = i + 1
2soumis = soumis + 1
3x = x*2 - 1
4x*x + y*y
5c = (a+b) * (a-b)
6c = (a + b) * (a - b)

• Ne pas utiliser d'espaces autour du signe égal (=) lorsqu'il est utilisé pour indiquer une valeur par défaut.
d'un argument. Faites ainsi, par exemple :
Cacher le numéro des lignes
1def complexe(réel, imaginaire=0.0):
2 return magie(r=réel, i=imaginaire)

• Les multiples commandes sur la même ligne sont découragées :

Ne fais pas :

Cacher le numéro des lignes

1si foo == 'blah': faire_blah_chose()
2faire_un(); faire_deux(); faire_trois()

Et oui :
Esconder le numéro des lignes
1si foo == 'blah':
2 faire_blah_chose()
3
4faire_un()
5faire_deux()
6faire_trois()

Commentaires
Les commentaires qui contredisent le code sont pires que pas de commentaire. Ayez toujours comme
la priorité est de maintenir les commentaires à jour avec les changements dans le code ! Les commentaires doivent
Toujours être des phrases complètes et sa première lettre doit être en majuscule, sauf si elle commence par
un identifiant qui commence par une lettre minuscule.
Si un commentaire est court, le point final doit être omis. Les commentaires longs normalement
consiste en un ou plusieurs paragraphes et phrases complètes, celles-ci doivent se terminer par un point.

Vous devez utiliser deux espaces après le point final d'une phrase, permettant à Emacs de s'ajuster.
ligne de manière cohérente.
Programmers from countries where English is not a native language: write your comments in
anglais, à moins que vous soyez sûr à 120 % que le code ne sera jamais lu par des personnes qui
ils ne parlent pas votre langue.

Les commentaires en bloc doivent être indentés au même niveau que le code auquel ils se réfèrent. Chaque
la ligne doit commencer par # et un espace (à moins que le texte à l'intérieur du commentaire ne soit indenté).
Les paragraphes à l'intérieur d'un bloc doivent être séparés par une ligne contenant un seul dièse #. Le
Un bloc entier doit être séparé par une ligne vide en haut et en bas.
Les commentaires sur la même ligne doivent être utilisés sporadiquement. Ils doivent être séparés de la commande
par au moins deux espaces. Comme d'autres commentaires, ils doivent commencer par un dièse et un
espace. Ne faites pas de commentaires sur des choses évidentes. Ils distraient plus qu'ils n'aident.

Docstrings
Rédigez des docstrings pour chaque module, fonction, classe et méthode publique. Elles ne sont pas nécessaires.
pour les méthodes "privées", il est recommandé d'avoir un commentaire qui explique ce qu'elles font. Ce
Le commentaire doit être juste après la déclaration.

PEP 257 décrit les conventions utilisées pour les docstrings. Les plus importantes à retenir sont que
doit toujours utiliser des guillemets triplés (chaîne multilignes) même si la chaîne occupe seulement une ligne
(facilite une éventuelle expansion ultérieure) et que les guillemets triples qui terminent une docstring dans
plusieurs lignes doivent être sur une ligne séparée.
Cacher le numéro des lignes
1Retourner un foobang
2
3Le plotz optionnel dit de frobnicate le bizbaz en premier.
4"""

Contrôle de Version
Si vous utilisez un en-tête pour RCS ou CVS dans vos fichiers de code, faites comme suit
forma
Cacher le numéro des lignes
1$Révision : 1.20 $
2# $Source: /cvsroot/python/python/nondist/peps/[Link],v $

Ces lignes doivent être incluses juste après les docstrings du module, avant tout code.
séparées par une ligne blanche au-dessus et en dessous.

Noms et Identifiants
Les conventions utilisées dans les noms de la bibliothèque standard sont un peu désordonnées et difficilement
Nous allons réussir à les rendre cohérents. Malgré cela, passons à quelques règles.

• Styles de noms
• Il existe une série de styles différents utilisés pour les identifiants. C'est bon à savoir.
 reconnaître quel style est utilisé, peu importe ce qui est fait.
Les styles les plus courants sont :
• minuscules_séparées_avec_underscore
• MAIÚSCULAS_SÉPARÉES_AVEC_UNDERSCORE
• PalavrasComComeçoPorMaiúsculas

• nom !commençantParMinuscule"

• Mots_Commençant_Pour_Majuscules_Et_Souligne

Il existe encore l'habitude d'utiliser un préfixe court pour regrouper des noms liés.
par exemple, la fonction [Link]() retourne un tuple dont les éléments ont des noms comme
st_mode, st_size, st_mtime et ainsi de suite. La bibliothèque X11 utilise un X comme
préfixe pour toutes vos fonctions publiques. Ce style n'est pas très courant en Python,
parce que, en général, les attributs et les noms de méthodes sont déjà préfixés par un objet, et
fonctions, par un module.
De plus, les manières suivantes d'utiliser des tirets bas avant ou après le
identificateurs sont reconnus.
• un underscore au début : indique généralement que l'attribut est à usage interne.
"from M import *" n'importe pas les objets dont les noms commencent par _

• underscore_no_fim_: utilisé pour éviter les conflits avec des mots-clés. par
exemple : "[Link](master, class_='NomClasse')".
• __deux_underscores_au_début: attribut privé de la classe (
classe.__atributo est converti par classe.__classe__atributo).

• attributs ou objets
spéciaux, comme __init__, __import__ ou __file__. Parfois, ceux-ci peuvent
être définis par l'utilisateur pour déclencher une action spéciale (surcharge de
opérateurs, par exemple).
• Conventions pour les Noms :
• Noms à éviter Ne jamais utiliser les caractères 'l' (l minuscule), 'O' (O majuscule) ou 'I' (i
majuscules) seuls comme noms de variables. Dans certaines sources, ces caractères
sont indistinguables des nombres un et zéro. Lorsque tenté d'utiliser seulement 'l', utilisez 'L'.
• Noms de Modules
Les modules doivent avoir des noms soit en MotsCommencantParMajuscules soit
totalement_en_minuscules. Les modules qui contiennent une seule classe peuvent avoir le
même nom de la classe (comme dans le module StringIO, par exemple). Modules qui
les fonctions d'exportation sont généralement nommées en minuscules. Comme les noms
de modules sont mappés à des noms de fichiers, et certains systèmes de fichiers ne
ils méprisent à la fois les majuscules et les minuscules tout en réduisant la longueur
il est important qu'ils soient choisis de manière à être courts et non
entrer en conflit avec d'autres modules. Ce n'est pas un problème dans les systèmes Unix ou
 Linux, mais cela peut poser un problème si le code est utilisé sur Mac ou Windows.

Il y a une convention qui émerge selon laquelle lorsqu'une extension écrite en C ou C++ a
un module en Python qui offre une interface de haut niveau, ce module doit avoir
le nom en MotsCommencantParMajuscules, tandis que le module en C/C++ doit
ter le nom entier en minuscules, commençant par un souligné (_socket, par
exemple).
• Noms de classes
Quasiment sans exception, les noms de classe doivent suivre le modèle de
MotsCommencantParMajuscule, sauf dans le cas des classes à usage interne, qui
doivent commencer par un underscore.

• Noms d'exceptions
Si un module définit une unique exception utilisée pour tous les types d'erreurs, elle est
généralement appelée "erreur" ou "Erreur".

• Noms de Fonctions
Les fonctions globales, exportées par un module, peuvent utiliser à la fois le standard
motscommencantparmajuscules, combien totalement en minuscules ou
minuscules_séparées_par_underscore). Il n'y a pas de préférence claire, mais le
le premier style est généralement plus utilisé pour les fonctions qui proviennent davantage
fonctionnalité, tandis que le second est utilisé par des fonctions plus simples.

• Variables GlobalesLes variables globales doivent être utilisées uniquement à l'intérieur du module. Les
Les conventions sont les mêmes pour les fonctions. Des modules qui sont conçus pour être utilisés
com 'from M import *' devem ter suas globais com um underscore como prefixo,
pour éviter qu'elles ne soient exportées.
• Noms de Méthodes

Il en va de même pour les fonctions. Utilisez deux underscores lorsque c'est important que
seule la classe actuelle accède à un attribut. (mais gardez à l'esprit que cela ne rend pas le
méthode vraiment privée. Un utilisateur insistant peut encore y accéder de plusieurs façons
formes, à travers l'attribut __dict__ par exemple).

• Héritage
• Décidez toujours si les méthodes d'une classe et les variables d'une instance seront
publics ou non. En général, ne rendez jamais les variables publiques, à moins que vous ne soyez
implémentation d'un type d'enregistrement. Décidez également si les attributs seront privés
ou non. La différence entre eux est que les attributs privés sont ceux qui n'auront jamais
utilité pour une sous-classe, tandis que les publics peuvent en avoir. Il est prudent de concevoir
ses classes ayant la possibilité d'héritage en tête.
Les attributs privés doivent avoir deux underscores au début et aucun à la fin. Attributs non publics
ils doivent avoir un soulignement au début et aucun à la fin.

Les attributs publics ne doivent pas avoir de soulignés ni au début, ni à la fin, sauf s'ils
entre en conflit avec des mots réservés, auquel cas un unique soulignement à la fin est préférable
au début, ou une prononciation différente, comme class_ au lieu de klass.

Recommandations lors de la programmation

Les comparaisons avec des singletons, comme None, False et True, doivent toujours être faites avec 'is' ou 'is not'.

pas". De plus, faites attention à ne pas écrire "if x" lorsque ce que vous souhaitez est "if x is not None".
comment tester si une variable ou un argument qui a une valeur par défaut de None a eu une autre valeur
attribué.
Les classes sont toujours préférées aux chaînes, comme dans les exceptions. Les modules ou les paquets doivent définir
votre propre classe d'exception de base, qui doit être une sous-classe de la classe Exception. Incluez toujours
umadocstring. Exemplo :
Cacher le numéro des lignes
1class MessageError(Exception):
2 Classe de base pour les erreurs dans le paquet email.

Utilisez les méthodes de l'objet string au lieu du module string, à moins qu'une compatibilité ne soit exigée.
avec des versions de Python antérieures à 2.0. Les méthodes sont beaucoup plus rapides et ont la même API de
chaînesUnicode.
Évitez de fendre des chaînes lors de la vérification des préfixes ou des suffixes. Utilisez les méthodes startswith() et

se termine par(), qui sont plus efficaces et moins sujettes à erreur. Par exemple :
N'utilisez pas :

Cacher le numéro des lignes

1si foo[:3] == 'bar':

Et oui :
Cacher le numéro des lignes
1si foo.commence_par('bar'):

L'exception est s'il y a un besoin pour votre code de fonctionner avec des versions de Python antérieures à
1.5.2.
Les comparaisons de types d'objets doivent toujours utiliser isinstance() au lieu de comparer les types.
directement. Exemple :
Ne pas utiliser :

Cacher le numéro des lignes

1si type(obj) est de type(1) :

Et oui :
Cacher le numéro des lignes
1si isinstance(obj, int):
Lorsque vous vérifiez si l'objet est une chaîne, rappelez-vous qu'il peut aussi être une chaîne.
unicode ! En Python 2.3, strunicode a une classe de base commune, basestring, alors vous
tu peux simplement écrire :
Masquer le numéro des lignes
1si isinstance(obj, basestring):

En Python 2.2, le module typestem a utilisé le type StringTypes à la même fin :

Cacher le numéro des lignes

1de types import StringTypes
2si isinstance(obj, StringTypes) :

Avec des séquences ( chaînes, listes, tuples ), gardez à l'esprit le fait que, lorsqu'elles sont vides, elles sont
falses dans un contexte booléen, donc "if not seq" ou "if seq" sont préférables à "if len(seq)" ou
si ce n'est pas len(seq)

Ne pas utiliser de chaînes qui dépendent d'une quantité significative d'espaces au début ou à la fin.
la quantité de ces espaces est visuellement indistinguable et certains éditeurs l'ajustent même.
Ne comparez pas les valeurs booléennes avec True et False en utilisant == (le type Bool est nouveau en Python)

2.3)
Ne pas utiliser

Cacher le numéro des lignes

1si salutation == Vrai :

Et oui
Cacher le numéro des lignes
1si salutation :

Références
1. PEP 7, Guide de style pour le code C, van Rossum
[Link]://[Link]/doc/essays/[Link]
3. PEP 257, Conventions de Docstring, Goodger, van Rossum
[Link]://[Link]/wiki/CamelCase
[Link] de style de Barry pour GNU Mailman/mimelib

Droit d'auteur
• Ce document a été mis à la disposition du public.

Traduit parPedroWerneck
1. PEP 7, Guide de style pour le code C, van Rossum1)