Por que nós precisamos do PEP8 no Python?
O PEP8 é um guia de estilo para código Python. Com sua ajuda escrevemos códigos mais legíveis.
Escrever códigos mais legíveis é importante para a construção profissional. É muito importante escrever um código legível para que as pessoas entendam seu código perfeitamente.
Como nomear funções no Python?
Escolher o nome de variável, função, método entre outros, pode ser complicado.
A maneira mais simples e fácil, é utilizar um nome que deixa claro o que a variável irá armazenar e o que o método irá fazer.
Um exemplo de como nomear váriaveis:
>>nome = “Louis Wolkers”
>>idade = 17
>>print(nome, idade)
Neste exemplo, criamos variáveis com um nome que descreve seu valor.
Layout de código
O import é a primeira forma de falarmos sobre o layout. Você já se perguntou “Como eu separo os imports?”, pois bem, a resposta é mais simples do que imaginamos.
Os imports geralmente são separados por uma linha. Os primeiros imports são das bibliotecas padrões, em seguida importamos bibliotecas de terceiros e por último realizamos as importações de bibliotecas locais.
Exemplo de import:
>># biblioteca padrão
>>from datetime import datetime
>>import re>># biblioteca de terceiros
>>from bs4 import BeautifulSoup>># biblioteca local
>>import matematica
Para separarmos funções e métodos sempre utilizaremos 2 linhas em branco.
>>class PrimeiraClasse:
>> pass>>class SegundaClasse:
>> pass>>def primeira_funcao():
>> return None
Máximo de linha e quebra de código
A quantidade máxima de caracteres permitida pela PEP8, é 79 caracteres. Os limites são escolhidos para evitar a quebra de linha nos editores com a largura da janela definida como 80.
Quando tivermos funções com nome longo e precisarmos quebrar a linha entre os argumentos, a linha seguinte tem que acompanhar logo depois da abertura do parênteses.
>> comidas = almoco(arroz, feijão, banana, batata,
macarrão, salada)
Identação de código
Em Python, a identação é algo que sempre usaremos. A identação é feita com 4 “espaços” entre o método e o que ele irá fazer.
>>def teste():
>> pass
Onde colocar a chave de fechamento?
As continuações de linha permitem que você quebre as linhas entre parênteses, colchetes ou chaves. Alinhe a chave de fechamento com o primeiro caractere diferente de espaço em branco da linha anterior:
>> lista_numerica = [
>> 1, 2, 3
>> 4, 5, 6
>> ]
Também podemos alinhar junto ao primeiro caracter do bloco, por exemplo, alinhado com o nome da varíavel conforme a seguir:
>> lista_numerica = [
>> 1, 2, 3
>> 4, 5, 6
>> ]
Comentários
É importante comentar o código para ficar mais explicativo para alguém ler.
Comentamos apenas uma linha do código utilizando o “#”
>>#Neste código, imprimimos
>>#o meu nome e a idade
>>>nome = “Louis Wolkers”
>>>idade = 17
>>print(nome, idade)
Podemos utilizar as (”’), três aspas simples, que comentará o código todo até fecharmos com mais três aspas.
>>”’Neste código, imprimimos
>>O meu nome e a idade”’
>>>nome = “Louis Wolkers”
>>>idade = 17
>>print(nome, idade)
Espaços em branco em expressões e declarações
O espaço em branco em expressões e declarações, podem ser muito importantes para deixar o código mais legível. Sem os espaços em branco, o código fica colado e complicado para ler, mas com os espaços, fica tudo separado, assim tornando mais fácil para entender.
Evite espaços em branco estranhos nas seguintes situações:
Imediatamente entre parênteses, colchetes ou chaves:
#Correto:
>>suco_natural(abacaxi[1], {laranja: 2})
#Errado:
>>suco_natural( abacaxi[ 1 ], { laranja: 2 } )
Entre uma vírgula final e um parêntese de fechamento a seguir:
#Correto:
>>foo = (0,)
#Errado:
>>foo = (0, )
Imediatamente antes de uma vírgula, ponto e vírgula ou dois pontos:
#Correto:
>>if x == 4: print(x, y); x, y = y, x
#Errado:
>>if x == 4 : print(x , y) ; x , y = y , x
imediatamente antes do parêntese de abertura que inicia a lista de argumentos de uma chamada de função:
>>#Correto:
>>spam(1)>>#Errado:
>>spam (1)
Imediatamente antes do parêntese de abertura que inicia uma indexação ou fracionamento:
>>#Correto:
>>dct[‘key’] = lst[index]>>#Errado
>>dct [‘key’] = lst [index]
Mais de um espaço ao redor de um operador de atribuição (ou outro) para alinhá-lo com outro:
>>#Correto:
>>x = 1
>>y = 2
>>variavel_longa = 3>>#Errado:
>>x = 1
>>y = 2
>>variavel_longa = 3
Citação de strings
Em Python, strings entre aspas simples e strings entre aspas duplas são iguais. Este PEP não faz uma recomendação para isso. Escolha uma regra e cumpra-a. Quando uma string contém caracteres de aspas simples ou duplas, no entanto, use o outro para evitar barras invertidas na string. Melhora a legibilidade.
Para strings com aspas triplas, sempre use caracteres de aspas duplas para ser consistente com a convenção de docstring no PEP 257.
Quando usar vírgulas finais
As vírgulas finais são geralmente opcionais, exceto que são obrigatórias ao fazer uma tupla de um elemento. É recomendável colocar a última vírgula entre parênteses
#Correto:
>>ARQUIVOS = (‘setup.cfg’,)
#Errado:
>>ARQUIVOS = ‘setup.cfg’,
Quando as vírgulas finais são redundantes, geralmente são úteis quando um sistema de controle de versão é usado, quando se espera que uma lista de valores, argumentos ou itens importados seja estendida ao longo do tempo. O padrão é colocar cada valor (etc.) em uma linha por si só, sempre adicionando uma vírgula final e adicionar o parêntese/colchete/chave na próxima linha.
#Correto:
>>FILES = [
>> ‘setup.cfg’,
>> ‘tox.ini’,
>> ]
>>initialize(FILES,
>> error=True,
>> )
#Errado:
>>FILES = [‘setup.cfg’, ‘tox.ini’,]
>>initialize(FILES, error=True,)
Convenções de Nomenclatura
Aqui estão os padrões de nomenclatura atualmente recomendados. Novos módulos e pacotes (incluindo estruturas de terceiros) devem ser escritos de acordo com esses padrões, mas onde uma biblioteca existente tem um estilo diferente, a consistência interna é preferida.
Princípio de Substituição
Os nomes que são visíveis ao usuário como partes públicas da API devem seguir as convenções que refletem o uso em vez da implementação.
Descritivo: estilos de nomenclatura
Existem muitos estilos de nomenclatura diferentes. Ajuda ser capaz de reconhecer qual estilo de nomenclatura está sendo usado, independentemente de para que são usados.
Os seguintes estilos de nomenclatura são comumente distinguidos:
b (letra minúscula única)
B (uma única letra maiúscula)
letras_minúsculas_com_sublinhado
MAIUSCULAS
LETRAS_MAIUSCULAS_COM_SUBLINHADO
CapitalizedWords (ou CapWords, ou CamelCase – assim chamado por causa da aparência irregular de suas letras). Isso também é conhecido como StudlyCaps.
Nota: Ao usar siglas em CapWords, coloque todas as letras da sigla em maiúscula. Portanto, HTTPServerError é melhor do que HttpServerError.
mixedCase (difere de CapitalizedWords pelo caractere inicial minúsculo)
Palavras_Maiusculas_Com_Sublinhado
Prescritivo: Convenções de Nomenclatura
Nomes a evitar
Nunca use os caracteres ‘l’, ‘O’ ou ‘I’ como nomes de variáveis de caractere único.
Em algumas fontes, esses caracteres são indistinguíveis dos numerais um e zero. Quando for tentado a usar ‘l’, use ‘L’.
Nomes de pacotes e módulos
Os módulos devem ter nomes curtos, todos em minúsculas. Sublinhados podem ser usados no nome do módulo se melhorar a legibilidade. Os pacotes Python também devem ter nomes curtos, todos em minúsculas, embora o uso de sublinhados seja desencorajado.
Nomes de classes
Nomes de classes normalmente devem usar a convenção CapWords.
A convenção de nomenclatura para funções pode ser usada nos casos em que a interface é documentada.
Observe que há uma convenção separada para nomes embutidos: a maioria dos nomes embutidos são palavras únicas (ou duas palavras executadas juntas), com a convenção CapWords usada apenas para nomes de exceção e constantes embutidas.
Nomes de variáveis de tipo
Nomes de variáveis de tipo introduzidos no PEP 484 devem normalmente usar CapWords preferindo nomes curtos: T, AnyStr, Num. Recomenda-se adicionar sufixos _co ou _contra para às variáveis usadas para declarar o comportamento covariante ou contravariante de forma correspondente:
>>from typing import TypeVar
>>VT_co = TypeVar(‘VT_co’, covariant=True)
>>KT_contra = TypeVar(‘KT_contra’, contravariant=True)
Nomes de exceção
Como as exceções devem ser classes, a convenção de nomenclatura de classe se aplica aqui. No entanto, você deve usar o sufixo “Error” em seus nomes de exceção (se a exceção realmente for um erro).
Nomes de Variáveis Globais
Módulos que são projetados para uso por meio de M import * devem usar o mecanismo all para evitar a exportação de globais ou usar a convenção mais antiga de prefixar esses globais com um sublinhado (o que você pode querer fazer para indicar que esses globais são “módulo não público “).
Nomes de funções e variáveis
Os nomes das funções devem estar em letras minúsculas, com palavras separadas por sublinhados conforme necessário para melhorar a legibilidade.
Os nomes das variáveis seguem a mesma convenção dos nomes das funções.
Argumentos de função e método
Sempre use self como o primeiro argumento para métodos de instância.
Sempre use cls para o primeiro argumento para métodos de classe.
Se o nome de um argumento de função conflitar com uma palavra-chave reservada, geralmente é melhor anexar um único sublinhado final em vez de usar uma abreviatura ou erro ortográfico. Portanto, class_ é melhor do que clss.
Nomes de métodos e variáveis de instância
Use as regras de nomenclatura de função: minúsculas com palavras separadas por sublinhados conforme necessário para melhorar a legibilidade.
Use um sublinhado inicial apenas para métodos não públicos e variáveis de instância.
Para evitar conflitos de nome com subclasses, use dois sublinhados iniciais para invocar as regras de mutilação de nome do Python.
Python confunde esses nomes com o nome da classe: se a classe Foo tem um atributo denominado __a, ela não pode ser acessada por Foo .__a. (Um usuário insistente ainda pode obter acesso chamando Foo._Foo__a.) Geralmente, sublinhados à esquerda duplos devem ser usados apenas para evitar conflitos de nome com atributos em classes projetadas para serem subclasses.
Constantes
As constantes são geralmente definidas em um nível de módulo e escritas em letras maiúsculas com sublinhados separando as palavras. Os exemplos incluem MAX_OVERFLOW e TOTAL.
Projetando para herança
Sempre decida se os métodos de uma classe e variáveis de instância devem ser públicos ou não públicos. Em caso de dúvida, escolha não público; é mais fácil torná-lo público depois do que tornar um atributo público não público.
Atributos públicos são aqueles que você espera que clientes não relacionados de sua classe usem, com seu compromisso de evitar alterações incompatíveis com versões anteriores. Atributos não públicos são aqueles que não devem ser usados por terceiros; você não garante que atributos não públicos não serão alterados ou mesmo removidos.
Outra categoria de atributos são aqueles que fazem parte da “API de subclasse”. Algumas classes são projetadas para serem herdadas, seja para estender ou modificar aspectos do comportamento da classe. Ao projetar essa classe, tome cuidado para tomar decisões explícitas sobre quais atributos são públicos, quais são parte da API da subclasse e quais devem ser usados apenas por sua classe base.
Sabendo disso, aqui estão as diretrizes Pythonicas:Os atributos públicos não devem ter sublinhados à esquerda.Se o nome do seu atributo público coincide com uma palavra-chave reservada, anexe um único sublinhado final ao nome do seu atributo.Para atributos de dados públicos simples, é melhor expor apenas o nome do atributo, sem métodos acessadores / modificadores complicados.Se sua classe se destina a ser uma subclasse, e você tem atributos que não deseja que as subclasses usem, considere nomeá-los com sublinhados iniciais duplos e sem sublinhados finais.
Recomendações de programação
Comparações com singletons como None devem sempre ser feitas com is ou not, nunca com os operadores de igualdade.O código deve ser escrito de uma forma que não prejudique outras implementações de Python (PyPy, Jython, IronPython, Cython, Psyco e outros).Usar o operador is not em vez de not is. Embora ambas as expressões sejam funcionalmente idênticas, a primeira é mais legível e preferida:
#Correto:
>>if foo is not None:
#Errado:
>>if not foo is None:
PEP 207 indica que as regras de reflexividade são assumidas pelo Python. Assim, o intérprete pode trocar y > x com x < y, y>= x com x <= y, e pode trocar os argumentos de x == y e x != y. As operações sort() e min() têm garantia de usar o operador “>”. No entanto, é melhor implementar todas as seis operações para que não surja confusão em outros contextos.
Sempre use uma instrução def em vez de uma instrução de atribuição que vincula uma expressão lambda diretamente a um identificador:
#Correto:
>>def f(x): return 2*x
#Errado:
>>f = lambda x: 2*x
Derive exceções de Exception em vez de BaseException. A herança direta de BaseException é reservada para exceções em que capturá-las é quase sempre a coisa errada a se fazer.
Projete hierarquias de exceção com base nas distinções que o código que captura as exceções provavelmente precisará, em vez dos locais onde as exceções são levantadas. Tente responder à pergunta “O que deu errado?” programaticamente, em vez de apenas declarar que “Ocorreu um problema”.
As convenções de nomenclatura de classe se aplicam aqui, embora você deva adicionar o sufixo “Erro” às suas classes de exceção se a exceção for um erro. As exceções sem erro que são usadas para controle de fluxo não local ou outras formas de sinalização não precisam de sufixo especial.
Ao capturar exceções, mencione exceções específicas sempre que possível, em vez de usar uma cláusula exceto:
>>try:
>> import platform_specific_module
>>except ImportError:
>> platform_specific_module = None
Uma simples exceção: cláusula capturará exceções SystemExit e KeyboardInterrupt, tornando mais difícil interromper um programa com Control-C e pode disfarçar outros problemas. Se você quiser capturar todas as exceções que sinalizam erros de programa, use exceção Exception: (bare except é equivalente a exceção BaseException :).
Uma boa regra prática é limitar o uso de cláusulas “except” a dois casos:Se o handler de exceção for imprimir ou registrar o traceback; pelo menos o usuário saberá que ocorreu um erro.Se o código precisa fazer algum trabalho de limpeza, mas então permite que a exceção se propague para cima com aumento. raise. try..finally pode ser a melhor maneira de lidar com este caso.
Ao vincular exceções capturadas a um nome, prefira a sintaxe de vinculação de nome explícita adicionada no Python 2.6:
>>try:
>> process_data()
>>except Exception as exc:
>> raise DataProcessingFailedError(str(exc))
Esta é a única sintaxe com suporte no Python 3 e evita os problemas de ambiguidade associados à sintaxe mais antiga baseada em vírgula.
Ao detectar erros do sistema operacional, prefira a hierarquia de exceção explícita introduzida no Python 3.3 em vez da introspecção de valores de errno.
Além disso, para todas as cláusulas try / except, limite a cláusula try à quantidade mínima absoluta de código necessária. Novamente, isso evita bugs de mascaramento:
#Correto:
>>try:
>> value = collection[key]
>>except KeyError:
>> return key_not_found(key)
>>else:
>> return handle_value(value)
#Errado:
>>try:
>> # Muito amplo!
>> return handle_value(collection[key])
>>except KeyError:
>> # Também irá capturar KeyError gerado por handle_value()
>> return key_not_found(key)
Quando um recurso é local para uma seção específica do código, use uma instrução with para garantir que ele seja limpo de forma rápida e confiável após o uso. Uma declaração try / finally também é aceitável.
Os gerenciadores de contexto devem ser chamados por meio de funções ou métodos separados sempre que fizerem algo diferente de adquirir e liberar recursos:
#Correto:
>>with conn.begin_transaction():
>> do_stuff_in_transaction(conn)>>#Errado:
>>with conn:
>> do_stuff_in_transaction(conn)
O último exemplo não fornece nenhuma informação para indicar que os métodos enter e exit estão fazendo algo diferente de fechar a conexão após uma transação. Ser explícito é importante neste caso.
Seja consistente nas declarações de retorno. Todas as instruções de retorno em uma função devem retornar uma expressão ou nenhuma delas. Se qualquer instrução de retorno retornar uma expressão, qualquer instrução de retorno em que nenhum valor seja retornado deve declarar isso explicitamente como return None e uma instrução de retorno explícita deve estar presente no final da função (se alcançável):
#Correto:
>>def foo(x):
>> if x >= 0:
>> return math.sqrt(x)
>> else:
>> return None>>def bar(x):
>> if x < 0:
>> return None
>> return math.sqrt(x)
#Errado:
>>def foo(x):
>> if x >= 0:
>> return math.sqrt(x)>>def bar(x):
>> if x < 0:
>> return
>> return math.sqrt(x)
Use métodos de string em vez do módulo de string.
Os métodos de string são sempre muito mais rápidos e compartilham a mesma API com strings Unicode. Substitua esta regra se a compatibilidade com versões anteriores com Pythons anteriores a 2.0 for necessária.
Use ‘ .startswith() e .endswith() em vez de divisão de string para verificar se há prefixos ou sufixos.
startswith() e endswith() são mais limpos e menos sujeitos a erros:
#Correto:
>>if foo.startswith(‘bar’):
#Errado:
>>if foo[:3] == ‘bar’:
As comparações de tipo de objeto devem sempre usar isinstance() em vez de comparar os tipos diretamente:
#Correto:
>>if isinstance(obj, int):
#Errado:
>>if type(obj) is type(1):
Ao verificar se um objeto é uma string, lembre-se de que também pode ser uma string Unicode! No Python 2, str e unicode têm uma classe base comum, basestring, então você pode fazer:
>>if isinstance(obj, basestring):
Para sequências (strings, listas, tuplas), use o fato de que sequências vazias são falsas:
#Correto:
>>if not seq:
>>if seq:
#Errado:
>>if len(seq):
>>if not len(seq):
Não escreva literais de string que dependem de espaços em branco à direita significativos. Esse espaço em branco final é visualmente indistinguível e alguns editores (ou, mais recentemente, reindent.py) irão cortá-los.
Não compare valores booleanos com verdadeiro ou falso usando == :
#Correto:
>if greeting:
#Errado:
>>if greeting == True:
Pior:
#Errado:
>>if greeting is True:
O uso das instruções de controle de fluxo return / break / continue dentro do conjunto finally de um try … finally, onde a instrução de controle de fluxo saltaria para fora do conjunto finally, é desencorajado. Isso ocorre porque tais instruções cancelarão implicitamente qualquer exceção ativa que esteja se propagando através do pacote finally:
#Errado:
>>def foo():
>> try:
>> 1 / 0
>> finally:
>> return 42
Anotações de função
Para serem compatíveis com versões futuras, as anotações de função no código Python 3 devem usar preferencialmente a sintaxe PEP 484.A experimentação com estilos de anotação que foram recomendados anteriormente neste PEP não é mais incentivada.
No entanto, fora do stdlib, experimentos dentro das regras do PEP 484 agora são incentivados. Por exemplo, marcar uma grande biblioteca ou aplicativo de terceiros com anotações de tipo de estilo PEP 484, ver como foi fácil adicionar essas anotações e observar se sua presença aumenta a compreensão do código.
A biblioteca padrão do Python deve ser conservadora ao adotar tais anotações, mas seu uso é permitido para novos códigos e para grandes refatorações.
Para o código que deseja fazer um uso diferente das anotações de função, é recomendado colocar um comentário no formulário:
type: ignore
Como os linters, os verificadores de tipo são ferramentas opcionais e separadas. Os intérpretes Python por padrão não devem emitir nenhuma mensagem devido à verificação de tipo e não devem alterar seu comportamento com base em anotações.
Os usuários que não desejam usar verificadores de tipo podem ignorá-los. No entanto, espera-se que os usuários de pacotes de bibliotecas de terceiros possam executar verificadores de tipo nesses pacotes. Para este propósito, o PEP 484 recomenda a utilização de arquivos stub: arquivos .pyi que são lidos pelo verificador de tipo em vez dos arquivos .py correspondentes. Os arquivos stub podem ser distribuídos com uma biblioteca ou separadamente (com a permissão do autor da biblioteca) por meio do repositório formatado.
Para o código que precisa ser compatível com versões anteriores, as anotações de tipo podem ser adicionadas na forma de comentários. Consulte a seção relevante do PEP 484.
Anotações de Variável
PEP 526 introduziu anotações de variáveis. As recomendações de estilo para eles são semelhantes às das anotações de função descritas acima:
As anotações para variáveis de nível de módulo, variáveis de classe e instância e variáveis locais devem ter um único espaço após os dois pontos.Não deve haver espaço antes dos dois pontos.Se uma atribuição tiver um lado direito, o sinal de igualdade deverá ter exatamente um espaço em ambos os lados:
#Correto:
code: int
class Point:
coords: Tuple[int, int]
label: str = ‘<unknown>’
#Errado:
code:int # Sem espaço após dois pontos
code : int # Espaço antes de dois pontos
class Test:
result: int=0 # Sem espaços ao redor do sinal de igualdade
Embora o PEP 526 seja aceito para Python 3.6, a sintaxe de anotação de variável é a sintaxe preferida para arquivos stub em todas as versões de Python (consulte PEP 484 para obter detalhes).
Fonte:
https://www.python.org/dev/peps/pep-0008
Este artigo foi importado automaticamente por fazer parte do Planetário Dev. Quer fazer parte deste HUB de conteúdos? Faça parte do Planetário e veja as vantagens.
Não tem site ou blog? Seja um autor do site e ainda pode ser remunerado.
Mais sobre Newsletters?
32 melhores newsletters sobre negócios, startups e tecnologia para assinar em 2022
Leia também: