pep8

PEP8

Sumário

1. Indentação
2. Tabulação
3. Comprimento máximo de linhas
4. Linhas em branco
5. Imports
6. Expressões
7. Argumentos
8. Múltiplos comandos
9. Armazenamento de funções
10. Nomes
11. Identificadores
12. Recomendações

Indentação

• 4 espaços por nível de identação.

Tabulações ou espaços

• Nunca misture tabulações e espaços.

• A forma mais popular de indentar código em Python é somente com espaços.

Comprimento máximo de linhas:

• Limite de linhas de 79 colunas ou caracteres.

• Caso algo passe de 80, quebre com uma barra invertida ** e continue na linha de baixo no mesmo nível de identação.

    class Function(Blob):

        def __init__(self, width, height, color='black',
                     emphasis=None, highlight=0):
            
            if width == 0 and height == 0 and \
               color == 'red' and emphasis == 'strong' or \
               highlight > 100:

                raise ValueError, "sorry, you lose"

• Tente ao máximo armazenar condicionais complexos ou fluxos complexos em variáveis ou métodos para simplifica-lá.

Linhas em branco

• Separe funções e definições de classe com duas linhas em branco.

• Métodos dentro de uma classe devem ser separados com uma única linha em branco.

• Quando linhas em branco são usadas para separar métodos, deve haver também uma linha em branco entre a linha class e o primeiro método da classe ou seus atributos.

• Use linhas em branco para separar blocos lógicos dentro de métodos e funções.

Import

• Imports devem sempre ser feitos em linhas separadas, por exemplo:

# Wrong
import sys, os

# Correct
import sys
import os
from types import StringType, ListType

• Imports devem ser sempre colocados no topo do arquivo, logo depois de quaisquer comentários ou docstrings, e antes de constantes ou globais. Eles devem ser agrupados seguindo a ordem:

  1. módulos da biblioteca padrão
  2. módulos grandes relacionados entre si (por exemplo, todos os módulos de e-mail usados pela aplicação)
  3. módulos específicos da aplicação

• Quando importar uma classe de um módulo de mesmo nome, não há problemas em usar:

from MyClass import MyClass
from foo.bar.YourClass import YourClass

• No entanto, se isso causar conflitos com nomes, use o exemplo abaixo, mas somente se tiver conflito:

import MyClass
import foo.bar.MyClass

Espaços em expressões e instruções

# Wrong:
food_list( meat[ 1 ], { eggs: 2 } )
if x == 4 :
if(x == 4):
food_list (1)
dictionary ['key'] = my_list [index]
x             = 2
long_variable = 3

# Correct:
food_list(meat[1], {eggs: 2})
if x == 4:
if x == 4:
food_list(1)
dictionary['key'] = my_list[index]
x = 2
long_variable = 3

Expressões

• Sempre circunde os seguintes operadores binários com um único espaço de cada lado: $=, ==, <, >, !=, <>, <=, >=, in, not in, is, and, or, not$

• Para qualquer operação de $+, -, /, *, //, %, ...$ use espaços entre os operadores.

• Não use espaços entre o parentese e a operação ou entre parenteses aninhados: $((x * y) + (x + y))$

• Use sempre variáveis em minúsculo (x) evite misturar maiúsculo com minúsculo, por exemplo, x com X.

• Exemplo de uma boa expressão:

x = ((x + y) * (x * z)) / ((x // 2 - x % 2) + y)

Argumentos

• Não use espaços ao redor do sinal de igual (=) quando usado para indicar um valor padrão de um argumento.

• Use espaço entre uma virgula e o próximo argumento

# Wrong:
def subtration(x,y = 0):
    return x - y

# Correct:
def subtration(x, y=0):
    return x - y

Múltiplos comandos

• Não use múltiplos comandos na mesma linha

# Errado:
if name == 'joao': do_something()
do_one(); do_two(); do_three()

# Certo:
if name == 'joao':
    do_something()

do_one()
do_two()
do_three()

Armazenamento de funções

• Para inserir uma função em outra função, evite usar o lambda a menos que seja uma expressão muito simples e se usar armazene em uma variável antes.

# Certo:
def subtration(x, y):
    return x - y

sum = (lambda x, y: x + y)

def math(subtration(x, y), sum(x, y), ...):
   # Implementação

• Para casos do range(inicio, fim, incremento) use uma variável para armazenar o fluxo e use constantes para armazenar os número mágicos:

INITIAL = 0
END = 20
INCREMENT = 2
numbers = range(INITIAL, END, INCREMENT)
for number in numbers:
    print(number, end=' ')

Nomes

Nomes de Pacotes/Pastas:

Os pacotes devem também seguir a mesma base dos módulos, totalmente_em_minúsculas e snake_case.

Nomes de Módulos/Arquivos:

• Módulos devem ter nomes totalmente_em_minúsculas e snace_case.

• Módulos que contenham uma única classe podem ter o mesmo nome da classe (como no módulo StringIO, por exemplo).

• Como nomes de módulos são mapeados para nomes de arquivos, e alguns sistemas de arquivo não apenas desprezam maiúsculas e minúsculas como também reduzem o comprimento do nome, é importante que eles sejam escolhidos de forma a serem curtos e não entrar em conflito com outros módulos. Isso não é um problema em sistemas Unix ou Linux, mas pode ser um problema se o código for usado em Mac ou Windows.

Nomes de Classes

• Quase sem exceção, nomes de classe devem usar o padrão de PalavrasComeçandoPorMaiúscula, exceto no caso de classes para uso interno, que devem começar com um underscore.

Nomes de Funções:

• Funções globais: Exportadas por um módulo podem usar tanto o padrão PalavrasComeçandoPorMaiúscula, quanto totalmente em minúsculas ou minúsculas_separadas_por_underscore). Não há nenhuma preferência clara, mas o primeiro estilo costuma ser mais usado para funções que provêm mais funcionalidade, enquanto o segundo é usado por funções mais simples.

• Variáveis Globais: Variáveis globais devem ser usadas somente dentro do módulo. As convenções são as mesmas para funções. Módulos que são projetados para ser usados com 'from M import *' devem ter suas globais com um underscore como prefixo, para evitar que sejam exportadas.

Nomes de Métodos

• Vale o mesmo para as funções. Use dois underscores quando for importante que apenas a classe atual acesse um atributo. (mas tenha em mente que isso não torna o método realmente privado.

Nomes de Variáveis e atribútos

• Nomes de variáveis/atributos deve ser totalmente_em_minusculo e snake_case

• Atributos privados devem ter dois underscores no começo e nenhum no fim, apenas a classe atual acesse.

• Atributos não-públicos devem ter um underscore no começo e nenhum no fim, evita de serem exportadas.

• Atributos públicos não devem ter underscores nem no começo, nem no fim, a menos que eles entrem em conflito com palavras reservadas, caso em que um único underscore no fim é preferível a um no começo, ou a uma pronúncia diferente, como class_ ao invés de klass.

• Nunca use os caracteres 'l' (L minúsculo), 'O' (o maiúsculo) ou 'I' (i maiúsculo) sozinhos como nomes de variáveis. Em algumas fontes, esses caracteres são indistinguíveis dos números um e zero. Quando tentado a usar somente 'l', use 'L'.

Identificadores

• Adicionalmente, as seguintes formas de usar underscores antes ou depois do identificador são reconhecidas.

• _underscore_no_inicio: costuma indicar que o atributo é de uso interno. ("from M import *" não importa objetos cujos nomes comecem com _ )

• underscore_no_fim_: usado para evitar conflitos com palavras-chave.por exemplo: "Tkinter.Toplevel(master, class_='ClassName')".

• __dois_underscores_no_início: atributo privado da classe.

• __dois_underscores_no_início_e_no_fim__: atributos ou objetos especiais, como __init__ , __import__ ou __file__ . As vezes estes podem ser definidos pelo usuário para disparar alguma ação especial (sobrecarga de operadores, por exemplo).

Recomendações ao Programar

Comparações com singletons, como None, False e True devem sempre ser feitas com "is" ou "is not". Além disso, cuidado para não escrever "if x" quando o que você deseja é "if x is not None", como ao testar se uma variável ou argumento que tem um valor padrão de None, teve outro valor atribuído.

Classes são sempre preferidas à strings, como em exceptions. Módulos ou pacotes devem definir sua própria classe-exception base, que deve ser uma subclasse da classe Exception. Sempre inclua uma docstring. Exemplo:

class MessageError(Exception):
    """
    Base class for errors in the email package.
    """

Evite fatiar strings quando verificando prefixos ou sufixos. Use os métodos startswith() e endswith(), que são mais eficientes e menos sujeitos a erro. Por exemplo:

# Wrong
if foo[:3] == 'bar':

# Correct
if foo.startswith('bar'):

Comparações de tipo de objetos devem sempre usar isinstance() ao invés de comparar tipos diretamente. Exemplo:

# Wrong
if type(obj) is type(1):

# Correct
if isinstance(obj, int):

Com sequências (strings, listas, tuples), tenha em mente o fato de que, quando vazias, elas são falsas em um contexto booleano, portanto, "if not sequence" ou "if sequence" são preferíveis a "if len(sequence)" ou "if not len(sequence)".

Não compare valores booleanos com True e False usando ==

# Wrong
if greeting == True:

# Correct
if greeting: