Guía de estilo de Python (Google)

Este proyecto no es un proyecto oficial de Google, sino que fue creado y mantenido por programadores chinos con entusiasmo.

Si buscas la versión oficial en inglés de Google, por favor ve aGoogle Style Guide

En el siguiente código,Yesindica recomendado,Noindica no recomendado.


Punto y coma

No agregues punto y coma al final de las líneas, ni uses punto y coma para poner dos comandos en la misma línea.


Longitud de línea

Cada línea no debe exceder los 80 caracteres.

Excepto en los siguientes casos:

  1. Sentencias largas de importación de módulos
  2. URLs en comentarios

No uses barras invertidas para unir líneas.

Python uneimplícitamente las líneas dentro de paréntesis, corchetes y llaves., puedes aprovechar esta característica. Si es necesario, puedes añadir un par adicional de paréntesis alrededor de la expresión.

推荐: 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 una cadena de texto no cabe en una línea, puedes usar paréntesis para lograr la unión implícita de líneas:

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

En los comentarios, si es necesario, coloca las URLs largas en una sola línea.

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

Observa la sangría de los elementos en el ejemplo anterior; puedes encontrar una explicación en la sección :ref:`sangría <indentation>` de este artículo.


Paréntesis

Evita el uso innecesario de paréntesis.

A menos que se usen para la unión de líneas, no uses paréntesis en sentencias de retorno o condicionales. Sin embargo, es aceptable usar paréntesis alrededor de tuplas.

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)

Sangría

Usa 4 espacios para sangrar el código.

Nunca uses tabulaciones, ni mezcles tabulaciones y espacios. Para la unión de líneas, debes alinear verticalmente los elementos en la línea siguiente (ver el ejemplo en la sección :ref:`longitud de línea <line_length>`) o usar una sangría colgante de 4 espacios (en este caso la primera línea no debería tener argumentos):

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,
              ...
      }

Líneas en blanco

Deja dos líneas en blanco entre definiciones de nivel superior, y una línea en blanco entre definiciones de métodos.

Deja dos líneas en blanco entre definiciones de nivel superior, como definiciones de funciones o clases. Entre definiciones de métodos, y entre una definición de clase y su primer método, debe haber una línea en blanco. Dentro de una función o método, deja una línea en blanco donde consideres adecuado.


Espacios

Usa espacios alrededor de los signos de puntuación según las normas estándar de tipografía.

No pongas espacios dentro de los paréntesis.

Usa espacios alrededor de los signos de puntuación según las normas estándar de tipografía.

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

No pongas espacios antes de comas, puntos y comas o dos puntos, pero sí después de ellos (excepto al final de la línea).

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

No debe haber espacio antes del paréntesis izquierdo de una lista de argumentos, indexación o segmento (slice).

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

Agrega un espacio a cada lado de los operadores binarios, como asignación (=), comparación (==, <, >, !=, <>, <=, >=, in, not in, is, is not) y booleanos (and, or, not). En cuanto al uso de espacios alrededor de los operadores aritméticos, debes decidirlo tú mismo. Sin embargo, asegúrate de mantener la consistencia en ambos lados.

Yes: x == 1
No:  x<1

Cuando '=' se usa para indicar un argumento de palabra clave o un valor de parámetro predeterminado, no uses espacios a su alrededor.

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)

No uses espacios para alinear verticalmente marcadores entre varias líneas, porque esto se convierte en una carga de mantenimiento (aplica a :, #, =, 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 mayoría de los archivos .py no necesitan comenzar con #! como inicio del archivo. SegúnPEP-394, el archivo principal del programa debería comenzar con #!/usr/bin/python2 o #!/usr/bin/python3.

(Nota del traductor: en ciencias de la computación,Shebang(también llamado Hashbang) es una línea de cadena compuesta por un signo de numeral y un signo de exclamación (#!), que aparece en los dos primeros caracteres de la primera línea de un archivo de texto. Cuando un archivo contiene un Shebang, el cargador de programas de los sistemas operativos tipo Unix analiza el contenido después del Shebang, lo toma como una directiva de intérprete y lo invoca, pasando la ruta del archivo con Shebang como argumento del intérprete. Por ejemplo, un archivo que comienza con la directiva #!/bin/sh invocará realmente al programa /bin/sh al ejecutarse.)

#! se utiliza primero para ayudar al núcleo a encontrar el intérprete de Python, pero se ignora al importar módulos. Por lo tanto, solo es necesario agregar #! en los archivos que se ejecutan directamente.


Comentarios

Asegúrate de usar el estilo correcto para módulos, funciones, métodos y comentarios en línea.

Cadenas de documentación (docstrings)

Python tiene una forma única de comentar: usar cadenas de documentación. La cadena de documentación es la primera declaración en un paquete, módulo, clase o función. Estas cadenas pueden extraerse automáticamente mediante el miembro __doc__ del objeto y son utilizadas por pydoc. (Puedes ejecutar pydoc en tu módulo para ver cómo se ve). Nuestra convención para las cadenas de documentación es usar comillas dobles triples """(PEP-257). Una cadena de documentación debe organizarse de la siguiente manera: primero una línea de resumen que termine con punto, signo de interrogación o signo de exclamación (o simplemente una sola línea). Luego una línea en blanco. Después el resto de la cadena de documentación, que debe alinearse con la primera comilla de la primera línea. A continuación hay más especificaciones de formato para cadenas de documentación.

Módulos

Cada archivo debe incluir una plantilla de licencia. Elige la plantilla adecuada según la licencia utilizada por el proyecto (por ejemplo, Apache 2.0, BSD, LGPL, GPL).

Funciones y métodos

Las funciones a las que se refiere el texto incluyen funciones, métodos y generadores.

Una función debe tener una cadena de documentación, a menos que cumpla las siguientes condiciones:

  1. No es visible externamente
  2. Es muy corta
  3. Es simple y clara

La cadena de documentación debe describir qué hace la función, y una descripción detallada de las entradas y salidas. Generalmente, no debe describir "cómo se hace", a menos que sea un algoritmo complejo. La cadena de documentación debe proporcionar suficiente información para que alguien que escriba código para llamar a esa función no necesite ver ni una línea de código, solo leer la cadena de documentación. Para código complejo, añadir comentarios junto al código es más significativo que usar una cadena de documentación.

Varios aspectos de la función deben documentarse en secciones específicas, como se describe a continuación. Cada sección debe comenzar con una línea de título. La línea de título termina con dos puntos. Excepto la línea de título, el resto del contenido de la sección debe sangrarse con 2 espacios.

Args:
Enumera el nombre de cada argumento y, después del nombre, usa dos puntos y un espacio para separar la descripción del argumento. Si la descripción es demasiado larga y supera los 80 caracteres en una línea, usa una sangría colgante de 2 o 4 espacios (manteniendo la coherencia con el resto del archivo). La descripción debe incluir el tipo requerido y su significado. Si una función acepta *foo (lista de argumentos de longitud variable) o **bar (argumentos de palabra clave arbitrarios), debes detallar *foo y **bar.
Returns: (o Yields: para generadores)
Describe el tipo y la semántica del valor de retorno. Si la función devuelve None, esta sección puede omitirse.
Raises:
Enumera todas las excepciones relacionadas con la interfaz.
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

Clase

Una clase debe tener una cadena de documentación debajo de su definición que la describa. Si tu clase tiene atributos públicos (Attributes), entonces la documentación debe tener una sección de atributos (Attributes). Y debe seguir el mismo formato que los parámetros de función.

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."""

Comentarios de bloque y comentarios en línea

Lo que más necesita comentarios son las partes ingeniosas del código. Si en la próximarevisión de códigotienes que explicarlo, entonces deberías escribir comentarios ahora. Para operaciones complejas, se deben escribir varias líneas de comentarios antes de que comience la operación. Para código que no es evidente, agrega un comentario al final de la línea.

# 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

Para mejorar la legibilidad, los comentarios deben estar al menos a 2 espacios del código.

Por otro lado, nunca describas el código. Supón que quien lee el código sabe más de Python que tú; solo no sabe lo que tu código pretende hacer.

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

Clase

Si una clase no hereda de otras clases, hereda explícitamente de object. Lo mismo para clases anidadas.

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

Heredar deobjectes para que las propiedades (properties) funcionen correctamente, y esto protege tu código de una posible incompatibilidad especial en Python 3000. También define algunos métodos especiales que implementan la semántica predeterminada de los objetos, incluyendo__new__, __init__, __delattr__, __getattribute__, __setattr__, __hash__, __repr__, and __str__ .


Cadenas

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)

Evita usar los operadores + y += para acumular cadenas en un bucle. Como las cadenas son inmutables, esto crea objetos temporales innecesarios y provoca un tiempo de ejecución cuadrático en lugar de lineal. Como alternativa, puedes agregar cada subcadena a una lista y, al final del bucle, usar.joinpara unir la lista. (También puedes escribir cada subcadena en uncStringIO.StringIObúfer.)

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>'

En el mismo archivo, mantén la coherencia en el uso de comillas para cadenas. Usa comillas simples ' o comillas dobles " para citar cadenas y mantén la misma en el mismo archivo. Dentro de una cadena, se puede usar el otro tipo de comillas para evitar escapar caracteres. PyLint ya ha incorporado esta verificación.

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.")

Usa comillas dobles triples """ para cadenas multilínea en lugar de comillas simples triples '''. Solo si el proyecto usa comillas simples ' para citar cadenas, se pueden usar comillas simples triples ''' para cadenas multilínea que no sean docstrings. Los docstrings deben usar comillas dobles triples """. No obstante, ten en cuenta que normalmente es más claro usar la continuación implícita de líneas, porque las cadenas multilínea no se alinean con la sangría del resto del programa.

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

Archivos y sockets

Cuando termines con archivos y sockets, ciérralos explícitamente.

Además de los archivos, abrir sockets u otros objetos similares a archivos sin necesidad tiene muchos efectos secundarios, por ejemplo:

  1. Pueden consumir recursos limitados del sistema, como descriptores de archivo. Si estos recursos no se devuelven al sistema a tiempo después de su uso, el código que maneja estos objetos puede agotar los recursos.
  2. Mantener archivos abiertos impedirá otras operaciones sobre ellos, como moverlos o eliminarlos.
  3. Cerrar archivos y sockets solo desde el punto de vista lógico no evita que otros programas que los comparten los lean o escriban inadvertidamente. Solo cuando se cierran de verdad, cualquier intento de lectura o escritura sobre ellos lanzará una excepción, haciendo que el problema se manifieste rápidamente.

Además, es poco realista imaginar que los archivos y sockets se cerrarán automáticamente cuando se destruya el objeto de archivo, o intentar vincular el ciclo de vida del objeto de archivo con el estado del archivo. Las razones son las siguientes:

  1. No hay forma de garantizar que el entorno de ejecución lleve a cabo realmente la destrucción del objeto de archivo. Diferentes implementaciones de Python utilizan diferentes técnicas de gestión de memoria, como mecanismos de recolección de basura diferida. La recolección de basura diferida puede hacer que el ciclo de vida del objeto se prolongue de manera arbitraria e ilimitada.
  2. Las referencias inesperadas a un archivo pueden hacer que el archivo se mantenga abierto durante más tiempo del esperado (por ejemplo, seguimientos de excepciones que contienen variables globales, etc.).

Se recomienda usarla declaración "with"para gestionar archivos:

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

Para objetos similares a archivos que no admiten la declaración "with", usa contextlib.closing():

import contextlib

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

En Python 2.5 en el AppEngine heredado, si el código usa la declaración "with", debe añadir "from __future__ import with_statement".


Comentarios TODO

Usa comentarios TODO para código temporal. Son una solución a corto plazo; no son perfectos, pero son lo suficientemente buenos.

Los comentarios TODO deben contener la cadena "TODO" al principio, seguida de tu nombre, dirección de correo electrónico u otro identificador entre paréntesis. Después puede haber dos puntos opcionales. A continuación debe haber una línea de comentario que explique qué hay que hacer. El propósito principal es tener un formato TODO uniforme, para que quien añada comentarios pueda buscarlos (y proporcionar más detalles si es necesario). Escribir un comentario TODO no garantiza que su autor vaya a resolver el problema personalmente. Cuando escribas un TODO, incluye tu nombre.

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

Si tu TODO tiene la forma "hacer algo en el futuro", asegúrate de incluir una fecha específica ("resolverlo en noviembre de 2009") o un evento específico ("eliminar este código cuando todos los clientes puedan procesar solicitudes XML").


Formato de importaciones

Cada importación debe estar en una línea separada.

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

Las importaciones siempre deben colocarse en la parte superior del archivo, después de los comentarios del módulo y los docstrings, y antes de las variables globales y constantes del módulo. Las importaciones deben agruparse en orden de las más generales a las menos generales:

  1. Importaciones de la biblioteca estándar
  2. Importaciones de bibliotecas de terceros
  3. Importaciones específicas de la aplicación

En cada grupo, se deben ordenar lexicográficamente según la ruta completa del paquete de cada módulo, ignorando mayúsculas y minúsculas.

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

Sentencias

Normalmente, cada sentencia debe ocupar su propia línea.

Sin embargo, si la condición de prueba y el resultado caben en la misma línea, también puedes ponerlos en la misma línea. En el caso de una sentencia if, solo puedes hacerlo cuando no haya else. En particular, nunca hagas estotry/exceptcon try/except, porque try y except no pueden estar en la misma línea.

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)

Control de acceso

En Python, para funciones de acceso triviales y sin importancia, debes usar variables públicas en lugar de ellas, para evitar la sobrecarga de llamadas a funciones adicionales. Cuando añadas más funcionalidad, puedes usar propiedades (property) para mantener la consistencia sintáctica.

(Nota del traductor: los programadores orientados a objetos que valoran el encapsulamiento pueden encontrar esto molesto, porque se les ha enseñado que todas las variables miembro deben ser privadas. En realidad, eso es bastante problemático. Intenta aceptar la filosofía Pythonic).

Por otro lado, si el acceso es más complejo, o el costo de acceder a la variable es significativo, entonces deberías usar funciones comoget_foo()yset_foo()tales llamadas a funciones. Si el comportamiento del código anterior permitía el acceso mediante propiedades (property), entonces no vincules las nuevas funciones de acceso con la propiedad. De esta manera, cualquier código que intente acceder a la variable mediante el método antiguo no funcionará, y los usuarios se darán cuenta de que la complejidad ha cambiado.


Nombres

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

Nombres que se deben evitar

  1. Nombres de un solo carácter, excepto contadores e iteradores.
  2. Guiones (-) en nombres de paquetes/módulos
  3. Nombres que comienzan y terminan con doble guion bajo (reservados por Python, por ejemplo __init__)

Convenciones de nomenclatura

  1. Lo que se denomina "interno (Internal)" significa que solo está disponible dentro del módulo, o bien, que está protegido o es privado dentro de la clase.
  2. Comenzar con un guion bajo (_) indica que la variable o función de módulo es protegida (no se incluye al usar 'from ... import *').
  3. Las variables de instancia o métodos que comienzan con doble guion bajo (__) indican que son privados dentro de la clase.
  4. Coloca las clases relacionadas y las funciones de nivel superior en el mismo módulo. A diferencia de Java, no es necesario limitarse a una clase por módulo.
  5. Usa palabras con mayúscula inicial para los nombres de clases (como CapWords, es decir, estilo Pascal), pero los nombres de módulos deben usar minúsculas con guiones bajos (como lower_with_under.py). Aunque ya existen muchos módulos con nombres como CapWords.py, esto ya no se recomienda, porque si el nombre del módulo coincide con el de una clase, puede resultar confuso.

Convenciones recomendadas por Guido, el padre de Python

Type Public Internal
Modules lower_with_under _lower_with_under
Packages lower_with_under  
Classes CapWords _CapWords
Exceptions CapWords  
Functions lower_with_under() _lower_with_under()
Global/Class Constants CAPS_WITH_UNDER _CAPS_WITH_UNDER
Global/Class Variables lower_with_under _lower_with_under
Instance Variables lower_with_under _lower_with_under (protected) or __lower_with_under (private)
Method Names lower_with_under() _lower_with_under() (protected) or __lower_with_under() (private)
Function/Method Parameters lower_with_under  
Local Variables lower_with_under  

Main

Incluso un archivo destinado a usarse como script debe ser importable. Una simple importación no debería provocar que la funcionalidad principal (main functionality) del script se ejecute, ya que eso sería un efecto secundario. La funcionalidad principal debe colocarse en una función main().

En Python, pydoc y las pruebas unitarias requieren que los módulos sean importables. Tu código siempre debe verificar la condición antes de ejecutar el programa principalif __name__ == '__main__', para que el programa principal no se ejecute cuando se importe el módulo.

def main():
      ...

if __name__ == '__main__':
    main()

Todo el código de nivel superior se ejecuta cuando se importa el módulo. Ten cuidado de no llamar funciones, crear objetos o realizar operaciones que no deberían ejecutarse cuando se usa pydoc.