Guide de style Python (Google)

Ce projet n'est pas un projet officiel de Google, mais a été créé et maintenu par des programmeurs locaux par passion.

Si vous recherchez la version officielle en anglais de Google, veuillez consulterGoogle Style Guide

Dans le code suivant,Ouisignifie recommandé,Nonsignifie non recommandé.


Points-virgules

N'ajoutez pas de points-virgules à la fin des lignes et n'utilisez pas de points-virgules pour placer deux commandes sur la même ligne.


Longueur des lignes

Chaque ligne ne doit pas dépasser 80 caractères.

Sauf dans les cas suivants :

  1. Longues instructions d'importation de module
  2. URLs dans les commentaires

N'utilisez pas de barres obliques inverses pour joindre des lignes.

Python vajoindre implicitement les lignes entre parenthèses, crochets et accoladesVous pouvez tirer parti de cette fonctionnalité. Si nécessaire, vous pouvez ajouter une paire supplémentaire de parenthèses autour de l'expression.

推荐: foo_bar(self, width, height, color='black', design=None, x='foo',
             emphasis=None, highlight=0)

     if (width == 0 and height == 0 and
         color == 'red' and emphasis == 'strong'):

Si une chaîne de caractères ne tient pas sur une seule ligne, vous pouvez utiliser des parenthèses pour effectuer une jonction implicite de lignes :

x = ('这是一个非常长非常长非常长非常长 '
     '非常长非常长非常长非常长非常长非常长的字符串')

Dans les commentaires, si nécessaire, placez les URL longues sur une seule ligne.

Yes:  # See details at
      # http://www.example.com/us/developer/documentation/api/content/v2.0/csv_file_name_extension_full_specification.html
No:  # See details at
     # http://www.example.com/us/developer/documentation/api/content/\
     # v2.0/csv_file_name_extension_full_specification.html

Notez l'indentation des éléments dans l'exemple ci-dessus ; vous trouverez une explication dans la section :ref:`indentation <indentation>` de ce document.


Parenthèses

Utilisez les parenthèses avec parcimonie.

N'utilisez pas de parenthèses dans les instructions return ou les instructions conditionnelles, sauf si elles sont utilisées pour joindre des lignes. Toutefois, l'utilisation de parenthèses autour de tuples est acceptable.

Yes: if foo:
         bar()
     while x:
         x = bar()
     if x and y:
         bar()
     if not x:
         bar()
     return foo
     for (x, y) in dict.items(): ...
No:  if (x):
         bar()
     if not(x):
         bar()
     return (foo)

Indentation

Utilisez 4 espaces pour indenter le code.

N'utilisez jamais de tabulations et ne mélangez pas les tabulations et les espaces. Pour joindre des lignes, vous devez soit aligner verticalement les éléments répartis sur plusieurs lignes (voir l'exemple dans la section :ref:`line length <line_length>`), soit utiliser une indentation suspendue de 4 espaces (auquel cas la première ligne ne doit pas avoir d'arguments) :

Yes:   # 与起始变量对齐
       foo = long_function_name(var_one, var_two,
                                var_three, var_four)

       # 字典中与起始值对齐
       foo = {
           long_dictionary_key: value1 +
                                value2,
           ...
       }

       # 4 个空格缩进,第一行不需要
       foo = long_function_name(
           var_one, var_two, var_three,
           var_four)

       # 字典中 4 个空格缩进
       foo = {
           long_dictionary_key:
               long_dictionary_value,
           ...
       }
No:    # 第一行有空格是禁止的
      foo = long_function_name(var_one, var_two,
          var_three, var_four)

      # 2 个空格是禁止的
      foo = long_function_name(
        var_one, var_two, var_three,
        var_four)

      # 字典中没有处理缩进
      foo = {
          long_dictionary_key:
              long_dictionary_value,
              ...
      }

Lignes vides

Deux lignes vides entre les définitions de niveau supérieur, une ligne vide entre les définitions de méthode.

Deux lignes vides entre les définitions de niveau supérieur, telles que les définitions de fonction ou de classe. Les définitions de méthode, ainsi que l'intervalle entre une définition de classe et sa première méthode, doivent comporter une ligne vide. À l'intérieur d'une fonction ou d'une méthode, ajoutez une ligne vide là où vous le jugez approprié.


Espaces blancs

Respectez les conventions typographiques standard pour les espaces autour de la ponctuation.

Aucun espace à l'intérieur des parenthèses.

Respectez les conventions typographiques standard pour les espaces autour de la ponctuation.

Yes: spam(ham[1], {eggs: 2}, [])
No:  spam( ham[ 1 ], { eggs: 2 }, [ ] )

Ne mettez pas d'espace avant les virgules, les points-virgules ou les deux-points, mais mettez un espace après ceux-ci (sauf en fin de ligne).

Yes: if x == 4:
         print x, y
     x, y = y, x
No:  if x == 4 :
         print x , y
     x , y = y , x

Ne mettez pas d'espace avant la parenthèse ouvrante d'une liste de paramètres, d'un indice ou d'une tranche.

Yes: spam(1)
no: spam (1)
Yes: dict['key'] = list[index]
No:  dict ['key'] = list [index]

Ajoutez un espace des deux côtés des opérateurs binaires, tels que l'affectation (=), la comparaison (==, <, >, !=, <>, <=, >=, in, not in, is, is not) et les opérateurs booléens (and, or, not). En ce qui concerne l'utilisation des espaces autour des opérateurs arithmétiques, vous devez juger par vous-même. Toutefois, vous devez être cohérent des deux côtés.

Yes: x == 1
No:  x<1

Lorsque '=' est utilisé pour indiquer un argument nommé ou une valeur de paramètre par défaut, n'utilisez pas d'espace de part et d'autre de celui-ci.

Yes: def complex(real, imag=0.0): return magic(r=real, i=imag)
No:  def complex(real, imag = 0.0): return magic(r = real, i = imag)

N'utilisez pas d'espaces pour aligner verticalement des jetons sur plusieurs lignes, car cela devient une charge de maintenance (s'applique à :, #, =, etc.) :

Yes:
     foo = 1000  # 注释
     long_name = 2  # 注释不需要对齐

     dictionary = {
         "foo": 1,
         "long_name": 2,
         }
No:
     foo       = 1000  # 注释
     long_name = 2     # 注释不需要对齐

     dictionary = {
         "foo"      : 1,
         "long_name": 2,
         }

Shebang

La plupart des fichiers .py n'ont pas besoin de commencer par #! au début du fichier. SelonPEP-394, le fichier principal du programme doit commencer par #!/usr/bin/python2 ou #!/usr/bin/python3.

(Note du traducteur : en informatique,Shebang(aussi appelé Hashbang) est une ligne de chaîne composée d'un dièse et d'un point d'exclamation (#!), qui apparaît comme les deux premiers caractères de la première ligne d'un fichier texte. Lorsqu'un Shebang existe dans un fichier, le chargeur de programme des systèmes d'exploitation de type Unix analyse le contenu après le Shebang, traite ce contenu comme une directive d'interpréteur, invoque la directive et utilise le chemin du fichier contenant le Shebang comme argument de l'interpréteur. Par exemple, un fichier commençant par la directive #!/bin/sh invoquera en réalité le programme /bin/sh lors de son exécution.)

#! est d'abord utilisé pour aider le noyau à trouver l'interpréteur Python, mais il sera ignoré lors de l'importation de modules. Par conséquent, seuls les fichiers exécutés directement doivent inclure #!.


Commentaires

Assurez-vous que le style correct est utilisé pour les modules, les fonctions, les méthodes et les commentaires en ligne.

Docstrings

Python a une manière unique de commenter : utiliser des docstrings. Une docstring est la première instruction dans un package, module, classe ou fonction. Ces chaînes peuvent être automatiquement extraites via le membre __doc__ de l'objet et sont utilisées par pydoc. (Vous pouvez exécuter pydoc sur votre module pour l'essayer et voir à quoi cela ressemble). Notre convention pour les docstrings est d'utiliser des triples guillemets doubles """ (PEP-257). Une docstring doit être organisée comme suit : d'abord, une ligne de résumé se terminant par un point, un point d'interrogation ou un point d'exclamation (ou la docstring n'a simplement qu'une seule ligne). Ensuite, une ligne vide. Puis le reste de la docstring, qui doit être aligné avec le premier guillemet de la première ligne de la docstring. D'autres spécifications de formatage pour les docstrings sont données ci-dessous.

Modules

Chaque fichier doit contenir un texte de licence standard. Choisissez le texte de licence approprié en fonction de la licence utilisée par le projet (par exemple, Apache 2.0, BSD, LGPL, GPL).

Fonctions et méthodes

Les fonctions mentionnées ci-dessous incluent les fonctions, les méthodes et les générateurs.

Une fonction doit avoir une docstring, sauf si elle remplit les conditions suivantes :

  1. Non visible de l'extérieur
  2. Très courte
  3. Simple et claire

La docstring doit contenir ce que fait la fonction, ainsi qu'une description détaillée des entrées et des sorties. Habituellement, elle ne doit pas décrire « comment faire », sauf si cela implique des algorithmes complexes. La docstring doit fournir suffisamment d'informations pour que, lorsqu'une autre personne écrit du code pour appeler la fonction, elle n'ait pas besoin de regarder une seule ligne de code — juste la docstring. Pour du code complexe, ajouter des commentaires à côté du code est plus significatif que d'utiliser une docstring.

Plusieurs aspects d'une fonction doivent être documentés dans des sections spécifiques, comme décrit ci-dessous. Chaque section doit commencer par une ligne d'en-tête. La ligne d'en-tête se termine par un deux-points. À l'exception de la ligne d'en-tête, le reste de la section doit être indenté de 2 espaces.

Arguments :
Listez le nom de chaque paramètre, puis après le nom, utilisez un deux-points et un espace pour séparer la description du paramètre. Si la description est trop longue et dépasse 80 caractères sur une seule ligne, utilisez un retrait suspendu de 2 ou 4 espaces (cohérent avec le reste du fichier). La description doit inclure le type requis et sa signification. Si une fonction accepte *foo (liste d'arguments de longueur variable) ou **bar (arguments nommés arbitraires), *foo et **bar doivent être listés en détail.
Renvoie : (ou Génère : pour les générateurs)
Décrivez le type et la sémantique de la valeur de retour. Si la fonction renvoie None, cette section peut être omise.
Lève :
Listez toutes les exceptions liées à l'interface.
def fetch_bigtable_rows(big_table, keys, other_silly_variable=None):
    """Fetches rows from a Bigtable.

    Retrieves rows pertaining to the given keys from the Table instance
    represented by big_table.  Silly things may happen if
    other_silly_variable is not None.

    Args:
        big_table: An open Bigtable Table instance.
        keys: A sequence of strings representing the key of each table row
            to fetch.
        other_silly_variable: Another optional variable, that has a much
            longer name than the other args, and which does nothing.

    Returns:
        A dict mapping keys to the corresponding table row data
        fetched. Each row is represented as a tuple of strings. For
        example:

        {'Serak': ('Rigel VII', 'Preparer'),
         'Zim': ('Irk', 'Invader'),
         'Lrrr': ('Omicron Persei 8', 'Emperor')}

        If a key from the keys argument is missing from the dictionary,
        then that row was not found in the table.

    Raises:
        IOError: An error occurred accessing the bigtable.Table object.
    """
    pass

Classe

Une classe doit avoir une docstring sous sa définition qui décrit la classe. Si votre classe a des attributs publics, la documentation doit comporter une section Attributs. Elle doit suivre le même format que les paramètres de fonction.

class SampleClass(object):
    """Summary of class here.

    Longer class information....
    Longer class information....

    Attributes:
        likes_spam: A boolean indicating if we like SPAM or not.
        eggs: An integer count of the eggs we have laid.
    """

    def __init__(self, likes_spam=False):
        """Inits SampleClass with blah."""
        self.likes_spam = likes_spam
        self.eggs = 0

    def public_method(self):
        """Performs operation blah."""

Commentaires de bloc et commentaires en ligne

Le code qui a le plus besoin de commentaires, ce sont les parties délicates. Si vous, enrevue de code, devez l'expliquer, alors vous devriez écrire un commentaire pour cela maintenant. Pour les opérations complexes, écrivez plusieurs lignes de commentaires avant que l'opération ne commence. Pour le code qui n'est pas évident au premier coup d'œil, ajoutez un commentaire à la fin de la ligne.

# We use a weighted dictionary search to find out where i is in
# the array.  We extrapolate position based on the largest num
# in the array and the array size and then do binary search to
# get the exact number.

if i & (i-1) == 0:        # true iff i is a power of 2

Pour améliorer la lisibilité, les commentaires doivent être à au moins 2 espaces du code.

En revanche, ne décrivez jamais le code. Supposez que la personne qui lit le code connaît Python mieux que vous ; elle ne sait simplement pas ce que votre code est censé faire.

# BAD COMMENT: Now go through the b array and make sure whenever i occurs
# the next element is i+1

Classe

Si une classe n'hérite pas d'autres classes, héritez explicitement de object. Il en va de même pour les classes imbriquées.

Yes: class SampleClass(object):
         pass


     class OuterClass(object):

         class InnerClass(object):
             pass


     class ChildClass(ParentClass):
         """Explicitly inherits from another class already."""
No: class SampleClass:
        pass


    class OuterClass:

        class InnerClass:
            pass

Hériter deobjectsert à faire fonctionner correctement les propriétés, et cela protège votre code d'une incompatibilité potentielle particulière dans Python 3000. Cela définit également certaines méthodes spéciales qui implémentent la sémantique par défaut des objets, notamment__new__, __init__, __delattr__, __getattribute__, __setattr__, __hash__, __repr__, and __str__ .


Chaînes de caractères

Yes: x = a + b
     x = '%s, %s!' % (imperative, expletive)
     x = '{}, {}!'.format(imperative, expletive)
     x = 'name: %s; score: %d' % (name, n)
     x = 'name: {}; score: {}'.format(name, n)
No: x = '%s%s' % (a, b)  # use + in this case
    x = '{}{}'.format(a, b)  # use + in this case
    x = imperative + ', ' + expletive + '!'
    x = 'name: ' + name + '; score: ' + str(n)

Évitez d'utiliser les opérateurs + et += pour accumuler des chaînes dans une boucle. Comme les chaînes sont immuables, cela crée des objets temporaires inutiles et produit un temps d'exécution quadratique plutôt que linéaire. Comme alternative, vous pouvez ajouter chaque sous-chaîne à une liste, puis, après la fin de la boucle, utilisez.joinpour joindre la liste. (Vous pouvez aussi écrire chaque sous-chaîne dans uncStringIO.StringIOtampon.)

Yes: items = ['<table>']
     for last_name, first_name in employee_list:
         items.append('<tr><td>%s, %s</td></tr>' % (last_name, first_name))
     items.append('</table>')
     employee_table = ''.join(items)
No: employee_table = '<table>'
    for last_name, first_name in employee_list:
        employee_table += '<tr><td>%s, %s</td></tr>' % (last_name, first_name)
    employee_table += '</table>'

Dans un même fichier, restez cohérent dans l'utilisation des guillemets pour les chaînes. Utilisez soit des guillemets simples ' soit des guillemets doubles " pour les chaînes, et tenez-vous-y dans le même fichier. Vous pouvez utiliser l'autre type de guillemet à l'intérieur d'une chaîne pour éviter d'avoir à l'échapper. PyLint a déjà ajouté cette vérification.

Yes:
     Python('Why are you hiding your eyes?')
     Gollum("I'm scared of lint errors.")
     Narrator('"Good!" thought a happy Python reviewer.')
No:
     Python("Why are you hiding your eyes?")
     Gollum('The lint. It burns. It burns us.')
     Gollum("Always the great lint. Watching. Watching.")

Utilisez des triples guillemets doubles """ pour les chaînes multilignes au lieu de triples guillemets simples '''. Ce n'est que si le projet utilise des guillemets simples ' pour délimiter les chaînes que des triples ''' peuvent être utilisés pour des chaînes multilignes qui ne sont pas des docstrings. Les docstrings doivent utiliser des triples guillemets doubles """. Notez toutefois que la concaténation implicite de lignes est généralement plus claire, car les chaînes multilignes ne s'alignent pas sur l'indentation du reste du programme.

Yes:
    print ("This is much nicer.\n"
           "Do it this way.\n")
No:
      print """This is pretty ugly.
  Don't do this.
  """

Fichiers et sockets

Fermez explicitement les fichiers et les sockets lorsque vous avez fini de les utiliser.

Laisser inutilement ouverts des fichiers, des sockets ou d'autres objets de type fichier a de nombreux effets secondaires, par exemple :

  1. Ils peuvent consommer des ressources système limitées, telles que les descripteurs de fichiers. Si ces ressources ne sont pas restituées rapidement au système après utilisation, le code qui gère ces objets finira par les épuiser.
  2. Garder des fichiers ouverts peut empêcher d'autres opérations sur ces fichiers, comme les déplacer ou les supprimer.
  3. Le simple fait de fermer logiquement des fichiers et des sockets les laisse encore ouverts à des lectures ou écritures involontaires de la part de programmes qui les partagent. Ce n'est que lorsqu'ils sont réellement fermés que les tentatives de lecture ou d'écriture lèveront des exceptions, faisant apparaître les problèmes rapidement.

De plus, l'idée selon laquelle les fichiers et les sockets se fermeront automatiquement lorsque les objets fichier sont détruits, en essayant de lier la durée de vie des objets fichier à l'état des fichiers, est irréaliste. Pour les raisons suivantes :

  1. Il n'existe aucun moyen de garantir que l'environnement d'exécution exécutera réellement le destructeur du fichier. Différentes implémentations de Python utilisent différentes techniques de gestion de la mémoire, telles que la collecte des déchets différée. La collecte des déchets différée peut entraîner une prolongation arbitraire et indéfinie de la durée de vie des objets.
  2. Des références inattendues à des fichiers peuvent entraîner la conservation des fichiers plus longtemps que prévu (par exemple, dans les tracebacks d'exception qui incluent des variables globales, etc.).

Il est recommandé d'utiliserl'instruction "with"pour gérer les fichiers :

with open("hello.txt") as hello_file:
    for line in hello_file:
        print line

Pour les objets de type fichier qui ne prennent pas en charge l'instruction "with", utilisez contextlib.closing() :

import contextlib

with contextlib.closing(urllib.urlopen("http://www.python.org/")) as front_page:
    for line in front_page:
        print line

Le code hérité AppEngine Python 2.5 utilisant l'instruction "with" nécessite d'ajouter "from __future__ import with_statement".


Commentaires TODO

Utilisez des commentaires TODO pour le code temporaire, une solution à court terme. Pas parfait, mais suffisamment bon.

Les commentaires TODO doivent contenir la chaîne "TODO" tout au début, suivie de votre nom, adresse e-mail ou autre identifiant entre parenthèses. Ensuite, un deux-points facultatif. Après cela, il doit y avoir une ligne de commentaire expliquant quoi faire. L'objectif principal est d'avoir un format TODO uniforme afin que la personne ayant ajouté le commentaire puisse être recherchée (et puisse fournir plus de détails si nécessaire). Écrire un commentaire TODO ne garantit pas que son auteur corrigera personnellement le problème. Lorsque vous écrivez un TODO, veuillez inclure votre nom.

# TODO(kl@gmail.com): Use a "*" here for string repetition.
# TODO(Zeke) Change this to use relations.

Si votre TODO se présente sous la forme "faire quelque chose à l'avenir", assurez-vous d'inclure une date précise ("corriger en novembre 2009") ou un événement précis ("supprimer ce code une fois que tous les clients pourront gérer les requêtes XML").


Format d'import

Chaque import doit être sur sa propre ligne

Yes: import os
     import sys
No:  import os, sys

Les imports doivent toujours être placés en haut du fichier, après les commentaires de module et les docstrings, et avant les variables globales et constantes de module. Les imports doivent être regroupés du plus général au moins général :

  1. Imports de la bibliothèque standard
  2. Imports de bibliothèques tierces
  3. Imports spécifiques à l'application

Au sein de chaque groupe, les imports doivent être triés lexicographiquement par le chemin complet du paquet de chaque module, en ignorant la casse.

import foo
from foo import bar
from foo.bar import baz
from foo.bar import Quux
from Foob import ar

Déclarations

Généralement, chaque instruction doit être sur sa propre ligne

Cependant, si le test et le résultat tiennent sur une seule ligne, vous pouvez également les mettre sur la même ligne. Dans le cas d'une instruction if, vous ne pouvez le faire que s'il n'y a pas de else. En particulier, ne faites jamais cela pourtry/exceptfaire ceci, car try et except ne peuvent pas être placés sur la même ligne.

Yes:

  if foo: bar(foo)
No:

  if foo: bar(foo)
  else:   baz(foo)

  try:               bar(foo)
  except ValueError: baz(foo)

  try:
      bar(foo)
  except ValueError: baz(foo)

Contrôle d'accès

En Python, pour les fonctions d'accès triviales et sans importance, vous devriez utiliser directement des variables publiques à la place, afin d'éviter le surcoût d'appel de fonction. Lorsque vous ajoutez plus de fonctionnalités, vous pouvez utiliser des propriétés pour maintenir la cohérence syntaxique.

(Note du traducteur : les programmeurs orientés objet qui tiennent à l'encapsulation peuvent être offensés par cela, car on leur a toujours enseigné que toutes les variables membres doivent être privées ! En fait, c'est vraiment pénible. Essayez d'accepter la philosophie Pythonique.)

D'un autre côté, si l'accès est plus complexe, ou si le surcoût d'accès à la variable est significatif, vous devriez utiliser quelque chose commeget_foo()etset_foo()des appels de fonction. Si le comportement précédent du code permettait l'accès via des propriétés, alors ne liez pas de nouvelles fonctions d'accès à la propriété. De cette façon, tout code qui tente d'accéder à la variable via l'ancienne méthode échouera, et les utilisateurs réaliseront que la complexité a changé.


Nommer

module_name, package_name, ClassName, method_name, ExceptionName, function_name, GLOBAL_VAR_NAME, instance_var_name, function_parameter_name, local_var_name.

Noms à éviter

  1. Noms d'un seul caractère, sauf pour les compteurs et les itérateurs.
  2. Traits d'union (-) dans les noms de paquets/modules
  3. Noms qui commencent et se terminent par des doubles tirets bas (réservés par Python, par ex., __init__)

Conventions de nommage

  1. Le soi-disant "Interne" désigne ce qui n'est disponible qu'au sein du module ou, au sein d'une classe, protégé ou privé.
  2. Un tiret bas simple en tête (_) indique qu'une variable ou fonction de module est protégée (non incluse lors de l'utilisation de import * from).
  3. Les variables d'instance ou les méthodes commençant par des doubles tirets bas (__) sont privées au sein de la classe.
  4. Placez les classes et fonctions de premier niveau associées dans le même module. Contrairement à Java, il n'est pas nécessaire de se limiter à une classe par module.
  5. Utilisez des mots avec initiale majuscule pour les noms de classes (par ex., CapWords, c'est-à-dire le style Pascal), mais les noms de modules doivent utiliser des minuscules avec des tirets bas (par ex., lower_with_under.py). Bien que de nombreux modules existants utilisent des noms comme CapWords.py, ceci est désormais déconseillé car cela peut prêter à confusion si le nom du module correspond par hasard à un nom de classe.

Spécifications recommandées par le père de Python, Guido

Type Public Interne
Modules lower_with_under _lower_with_under
Paquets lower_with_under  
Classes CapWords _CapWords
Exceptions CapWords  
Fonctions lower_with_under() _lower_with_under()
Constantes globales/de classe CAPS_WITH_UNDER _CAPS_WITH_UNDER
Variables globales/de classe lower_with_under _lower_with_under
Variables d'instance lower_with_under _lower_with_under (protégé) ou __lower_with_under (privé)
Noms de méthodes lower_with_under() _lower_with_under() (protégé) ou __lower_with_under() (privé)
Paramètres de fonctions/méthodes lower_with_under  
Variables locales lower_with_under  

Main

Même un fichier destiné à être utilisé comme script doit être importable. Et un simple import ne doit pas entraîner l'exécution de la fonctionnalité principale du script, car c'est un effet de bord. La fonctionnalité principale doit être placée dans une fonction main().

En Python, pydoc et les tests unitaires exigent que les modules soient importables. Votre code doit toujours vérifier avant d'exécuter le programme principalif __name__ == '__main__', afin que le programme principal ne soit pas exécuté lorsque le module est importé.

def main():
      ...

if __name__ == '__main__':
    main()

Tout le code au niveau supérieur est exécuté lorsque le module est importé. Faites attention à ne pas appeler de fonctions, créer des objets ou effectuer des opérations qui ne doivent pas être exécutées lors de l'utilisation de pydoc.