GuiaDeEstilo

PEP 8 - Guia de Estilo Para Python

Este artigo uma traduo livre da PEP 8 - Style Guide for Python Code, de autoria de
GuidoVanRossum !guido at "ython#org$, referen%iado tam&m %omo GvR' e (arry )arsa*
!&arry at "ython#org$', dis"on+vel em htt",--***#"ython#org-"e"s-"e"-...8#html#
Introduo
Este do%umento ofere%e %onven/es "ara o %0digo Python %om"reendido "ela &i&liote%a "adro 1ue
a%om"anha a distri&uio# 23 outro do%umento semelhante
4
1ue trata do estilo "ara o %0digo em C
usado na im"lementao do inter"retador e nas e5tens/es 1ue %om"/e a &i&liote%a "adro#
6 %onte7do deste do%umento uma ada"tao do artigo original Python Style Guide, de
GuidoVanRossum, %om alguns a%rs%imos retirados do guia de estilo de (arry )arsa*# 6nde houve
%onflitos, as regras de GvR foram mantidas#
Uma Consistncia Tosca o Bicho-Pao das Pe!uenas
"entes
6 "ro"0sito de um guia de estilo manter a %onsist8n%ia# Consist8n%ia em relao a esse guia
im"ortante# Consist8n%ia em relao a outros detalhes de um "ro9eto mais im"ortante#
Consist8n%ia em relao a um m0dulo ou funo ainda mais im"ortante#
:ais im"ortante ainda, sai&a 1uando ser in%onsistente - algumas ve;es, as regras deste guia
sim"lesmente no se a"li%am# Em %aso de d7vida, use seu melhor 9ulgamento# ve9a outros e5em"los
e de%ida o 1ue fi%a melhor# E no hesite em "erguntar<
=uas &oas ra;/es "ara 1ue&rar uma regra,
>uando a adoo de uma regra ir3 tornar o %0digo menos leg+vel, mesmo "ara algum
a%ostumado %om essas regras#
>uando dese9a-se ser %onsistente %om outro %0digo 1ue a%om"anhe a1uele em
desenvolvimento 1ue tam&m viola as regras - a"esar dessa ser uma &oa o"ortunidade "ara
%onsertar a &aguna de algum#
#ormatao do C$di%o
?ndentao
@se o "adro usado "elo APython-modeA do Ema%s, B es"aos "or n+vel de
indentao# Para %0digo realmente antigo 1ue vo%8 no 1uer &agunar, vo%8 "ode
%ontinuar a usar 8 es"aos# 6 Python-mode automati%amente dete%ta o n+vel de
indentao "redominante em um ar1uivo e segue este "adro#
Ca&ula/es ou es"aos
Dun%a misture ta&ula/es e es"aos# E forma mais "o"ular de indentar %0digo em
Python somente %om es"aos# E segunda forma mais "o"ular somente %om
ta&ula/es# C0digo %om uma mistura dos dois deve ser %onvertido "ara usar somente
es"aos# Do Ema%s, sele%ione o &uffer inteiro e digite ESC-5 unta&ify'# Passando a
o"o -t "ara o inter"retador Python, fa; %om 1ue ele emita avisos so&re %0digo 1ue
misture ilegalmente ta&ula/es e es"aos# Com -tt esses avisos se tornam erros# Essas
o"/es so altamente re%omendadas< Para "ro9etos novos, re%omenda-se usar
somente es"aos# :uitos editores t8m o"/es "ara tornar isso mais f3%il#
Com"rimento m35imo de linhas
Einda h3 "or a+ muitos monitores limitados a linhas de 8. %olunas alm disso,
limitando as 9anelas a 8. %ara%teres, "ermite ter v3rias 9anelas a&ertas, lado a lado'#
Es 1ue&ras de linha "adro nesses monitores horr+vel, "ortante, limite todas as
linhas a um m35imo de FG %ara%teres# o Ema%s 1ue&ra as linhas 1ue t8m e5atamente
8. %ara%teres'# Para longos &lo%os de te5to docstrings ou %oment3rios', limitar o
%om"rimento a FH %olunas re%omendado#
E melhor maneira de %ontinuar linhas longas usando a %ontinuao im"l+%ita, entre
"ar8nteses, %ol%hetes e %haves# Se ne%ess3rio, vo%8 "ode adi%ionar um "ar e5tra de
"ar8nteses em volta de uma e5"resso, mas, Is ve;es, uma &arra invertida fi%a
melhor# Come o %uidado de indentar a linha ade1uadamente# 6 Python-mode do
Ema%s fa; isso automati%amente# E5em"lo,
Es%onder n7mero das linhas
1 class Rectangle(Blob):
2
3 def __init__(self, width, height,
4 color='black', e!hasis="one, highlight=#):
$ if width == # and height == # and %
& color == 'red' and e!hasis == 'strong' or %
' highlight ( 1##:
) raise *al+e,rror, -sorr., .o+ lose-
/ if width == # and height == # and (color == 'red' or
1# e!hasis is "one):
11 raise *al+e,rror, -0 don't think so-
12 Blob1__init__(self, width, height,
13 color, e!hasis, highlight)
Jinhas em &ran%o
Se"are fun/es e defini/es de %lasse %om duas linhas em &ran%o# :todos dentro de
uma %lasse devem ser se"arados %om uma 7ni%a linha em &ran%o# Jinhas e5tras
"odem ser usadas es"oradi%amente' "ara se"arar gru"os de fun/es rela%ionadas e
"odem ser omitidas entre gru"os rela%ionados de linhas, %omo "or e5em"lo, mtodos
1ue se9am so&res%ritas em su&%lasses# >uando linhas em &ran%o so usadas "ara
se"arar mtodos, deve haver tam&m uma linha em &ran%o entre a linha K%lassK e o
"rimeiro mtodo da %lasse# @se linhas em &ran%o "ara se"arar &lo%os l0gi%os dentro
de mtodos e fun/es# Python a%eita o %ara%tere %ontrol-J LJ' %omo es"ao em
&ran%oM o Ema%s e algumas ferramentas de im"resso' tratam esses %ara%teres %omo
1ue&ra de "3gina, ento vo%8 "ode us3-los "ara se"arar "3ginas de se/es
rela%ionadas no seu ar1uivo#
?m"ort
?m"orts devem sem"re ser feitos em linhas se"aradas, "or e5em"lo,
in%orreto,
Es%onder n7mero das linhas
1 i!ort s.s, os
%orreto,
Es%onder n7mero das linhas
1 i!ort s.s
2 i!ort os
:as no h3 "ro&lema algum em usar,
Es%onder n7mero das linhas
1 fro t.!es i!ort 2tring3.!e, 4ist3.!e
?m"orts devem ser sem"re %olo%ados no to"o do ar1uivo, logo de"ois de 1uais1uer
%oment3rios ou docstrings, e antes de %onstantes ou glo&ais# Eles devem ser agru"ados
seguindo a ordem,
m0dulos da &i&liote%a "adro
m0dulos grandes rela%ionados entre si "or e5em"lo, todos os m0dulos de e-mail
usados "ela a"li%ao'
m0dulos es"e%+fi%os da a"li%ao
Vo%8 deve %olo%ar uma linha em &ran%o se"arando %ada gru"o de m0dulos#
>uando im"ortar uma %lasse de um m0dulo de mesmo nome, no h3 "ro&lemas em usar,
Es%onder n7mero das linhas
1 fro 5.6lass i!ort 5.6lass
2 fro foo1bar17o+r6lass i!ort 7o+r6lass
Do entanto, se isso %ausar %onflitos %om nomes, use,
Es%onder n7mero das linhas
1 i!ort 5.6lass
2 i!ort foo1bar17o+r6lass
e de"ois A5.6lass15.6lassA e Afoo1bar17o+r6lass17o+r6lassA#
Es"aos em e5"ress/es e instru/es
Guido odeia es"aos nos seguintes lugares,
?mediatamente antes e a"0s "ar8ntese, %ol%hete ou %have, %omo em,
Es%onder n7mero das linhas
1 s!a( ha8 1 9, : eggs: 2 ; )
Sem"re es%reva assim,
Es%onder n7mero das linhas
1 s!a(ha819, :eggs: 2;)
Jogo antes de uma v+rgula, "onto-e-v+rgula ou dois-"ontos,
Es%onder n7mero das linhas
1 if < == 4 : !rint < , . = < , . = . , <
Sem"re es%reva assim,
Es%onder n7mero das linhas
1 if < == 4: !rint <, .= <, . = ., <
Jogo antes do "ar8ntese 1ue a&re a lista de argumentos de uma funo, %omo em,
Es%onder n7mero das linhas
1 s!a (1)
Sem"re es%reva,
Es%onder n7mero das linhas
1 s!a(1)
?mediatamente antes da %have 1ue a&re um +ndi%e, %omo em,
Es%onder n7mero das linhas
1 dict 8'ke.'9 = list 8inde<9
Sem"re es%reva,
Es%onder n7mero das linhas
1 dict8'ke.'9 = list8inde<9
:ais do 1ue um es"ao em volta de algum o"erador, "ara alinhar os o"erandos,
Es%onder n7mero das linhas
1 < = 1
2 . = 2
3 long_>ariable = 3
Es%reva,
Es%onder n7mero das linhas
1 < = 1
2 . = 2
3 long_>ariable = 3
6utras re%omenda/es
Sem"re %ir%unde os seguintes o"eradores &in3rios %om um 7ni%o es"ao de %ada
lado, N, NN, !, $, <N, !$, !N, $N, in, not in, is, and, or, not
@se o seu 9ulgamento na hora de inserir es"aos entre o"eradores aritmti%os#
E5em"los,
Es%onder n7mero das linhas
1 i = i?1
2 s+bitted = s+bitted ? 1
3 < = <@2 A 1
4 h.!ot2 = <@< ? .@.
$ c = (a?b) @ (aAb)
& c = (a ? b) @ (a A b)
Do use es"aos ao redor do sinal de igual N' 1uando usado "ara indi%ar um valor "adro
de um argumento# Oaa assim, "or e5em"lo,
Es%onder n7mero das linhas
1 def co!le<(real, iag=#1#):
2 ret+rn agic(r=real, i=iag)
:7lti"los %omandos na mesma linha so desen%ora9ados,
Do faa,
Es%onder n7mero das linhas
1 if foo == 'blah': do_blah_thing()
2 do_one()= do_two()= do_three()
E sim,
Es%onder n7mero das linhas
1 if foo == 'blah':
2 do_blah_thing()
3
4 do_one()
$ do_two()
& do_three()
Coment&rios
Coment3rios 1ue %ontradi;em o %0digo so "iores do 1ue nenhum %oment3rio# Sem"re tenha %omo
"rioridade manter os %oment3rios atuali;ados %om as mudanas no %0digo< Coment3rios devem
sem"re ser frases %om"letas e sua "rimeira letra deve ser mai7s%ula, a menos 1ue ele %ome%e %om
um identifi%ador 1ue %omea %om uma letra min7%ula#
Se um %oment3rio for %urto, o "onto final deve ser omitido# Coment3rios grandes normalmente
%onsistem de um ou mais "ar3grafos e sentenas %om"letas, estas sim devem terminar %om "onto#
Vo%8 deve usar dois es"aos de"ois do "onto final de uma frase, "ermitindo 1ue o Ema%s a9uste a
linha de maneira %onsistente#
Programadores de "a+ses 1ue no t8m o ingl8s %omo l+ngua nativa, es%revam seus %oment3rios em
ingl8s, a menos 1ue vo%8 tenha 4H.P de %erte;a de 1ue o %0digo 9amais ser3 lido "or "essoas 1ue
no falam sua l+ngua#
Coment3rios em &lo%o devem ser indentados no mesmo n+vel do %0digo a 1ue se referem# Cada
linha deve %omear %om Q e um es"ao a menos 1ue o te5to dentro do %oment3rio se9a indentado'#
Par3grafos dentro de um &lo%o devem ser se"arados "or uma linha %ontendo uma 7ni%a tralha Q# 6
&lo%o inteiro deve ser se"arado "or uma linha em &ran%o no to"o e em&ai5o#
Coment3rios na mesma linha devem ser usados es"oradi%amente# =evem ser se"arados do %omando
"or "elo menos dois es"aos# Como outros %oment3rios, devem %omear %om uma tralha e um
es"ao# Do faa %oment3rios em %oisas 0&vias# Eles distraem mais do 1ue a9udam#
Docstrin%s
Es%reva docstrings "ara todo m0dulo, funo, %lasse e mtodo "7&li%o# Elas no so ne%ess3rias
"ara mtodos A"rivadosA, mas re%omend3vel ter um %oment3rio 1ue e5"li1ue o 1ue ele fa;# Este
%oment3rio deve estar logo a"0s a de%larao#
E PEP HRF des%reve as %onven/es usadas "ara docstrings# Es mais im"ortantes a lem&rar so 1ue
deve sem"re usar as"as tri"las string multiline' mesmo 1ue a dosctring o%u"e a"enas uma linha
fa%ilita uma "oss+vel e5"anso "osterior' e 1ue as as"as tri"las 1ue finali;am uma dos%tring em
m7lti"las linhas deve estar em uma linha se"arada#
Es%onder n7mero das linhas
1 ---Ret+rn a foobang
2
3 B!tional !lotC sa.s to frobnicate the biCbaC first1
4 ---
Controle de 'erso
Se vo%8 utili;a um %a&ealho "ara RCS ou CVS nos seus ar1uivos de %0digo, faa %omo da seguinte
forma,
Es%onder n7mero das linhas
1 __>ersion__ = -DRe>ision: 112# D-
2 E D2o+rce: Fc>srootF!.thonF!.thonFnondistF!e!sF!e!A###)1t<t,> D
Estas linhas devem ser in%lu+das logo a"0s as docstrings do m0dulo, antes de 1ual1uer %0digo,
se"aradas "or uma linha em &ran%o a%ima e a&ai5o#
(omes e Identi)icadores
Es %onven/es usadas em nomes na &i&liote%a "adro so um "ou%o &agunadas e d+fi%ilmente
vamos %onseguir torn3-las %onsistentes# :esmo assim, vamos a algumas regras#
Estilos de nomes
23 uma srie de diferentes estilos usados "ara identifi%adores# S &om sa&er
re%onhe%er 1ual estilo est3 sendo usado, inde"endentemente do 1ue est3 sendo feito#
6s estilos mais %omuns so,
Amin7s%ulasTse"aradasT%omTunders%oreA
A:E?USC@JESTSEPERE=ESTC6:T@D=ERSC6REA
APalavrasComeandoPor:a+us%ulasA
Anome<ComeandoPor:in7s%ulaA
APalavrasTComeandoTPorT:ai7s%ulasTET@nders%oreA horr+vel<'
23 ainda o %ostume de usar um "refi5o %urto "ara agru"ar nomes rela%ionados# Por
e5em"lo, a funo os1stat() retorna uma tu"la %u9os +tens t8m nomes %omo
stTmode, stTsi;e, stTmtime e assim "ort diante# E &i&liote%a V44 usa um V %omo
"refi5o "ara todas suas fun/es "7&li%as# Este estilo no muito %omum em Python,
"or1ue, geralmente, atri&utos e nomes de mtodos 93 so "refi5ados "or um o&9eto, e
fun/es, "or um m0dulo#
Edi%ionalmente, as seguintes formas de usar underscores antes ou de"ois do
identifi%ador so re%onhe%idas#
_+nderscore_no_inicio, %ostuma indi%ar 1ue o atri&uto de uso interno#
Afrom : im"ort WA no im"orta o&9etos %u9os nomes %ome%em %om T '
+nderscore_no_fi_, usado "ara evitar %onflitos %om "alavras-%have#"or
e5em"lo, ACXinter#Co"levelmaster, %lassTNKClassDameK'A#
__dois_+nderscores_no_inGcio, atri&uto "rivado da %lasse
classe1__atrib+to %onvertido "ara classe1__classe__atrib+to '#
__dois_+nderscores_no_inGcio_e_no_fi__, atri&utos ou o&9etos
es"e%iais, %omo __init__ , __i!ort__ ou __file__ # Es ve;es estes "odem
ser definidos "elo usu3rio "ara dis"arar alguma ao es"e%ial so&re%arga de
o"eradores, "or e5em"lo'#
Conven/es "ara Domes,
Domes a evitar Dun%a use os %ara%teres KlK J min7s%ulo', K6K o mai7s%ulo' ou K?K i
mai7s%ulo' so;inhos %omo nomes de vari3veis# Em algumas fontes, esses %ara%teres
so indistingu+veis dos n7meros um e ;ero# >uando tentado a usar somente KlK, use KJK#
Domes de :0dulos
:0dulos devem ter nomes ou em PalavrasComeandoPor:a+us%ulas ou
totalmenteTemTmin7s%ulas# :0dulos 1ue %ontenham uma 7ni%a %lasse "odem ter o
mesmo nome da %lasse %omo no m0dulo String?6, "or e5em"lo'# :0dulos 1ue
e5"ortam a"enas fun/es so normalmente nomeados em min7s%ulas# Como nomes
de m0dulos so ma"eados "ara nomes de ar1uivos, e alguns sistemas de ar1uivo no
a"enas des"re;am mai7s%ulas e min7s%ulas %omo tam&m redu;em o %om"rimento
do nome, im"ortante 1ue eles se9am es%olhidos de forma a serem %urtos e no
entrar em %onflito %om outros m0dulos# ?sso no um "ro&lema em sistemas @ni5 ou
Jinu5, mas "ode ser um "ro&lema se o %0digo for usado em :a% ou )indo*s#
23 uma %onveno surgindo de 1ue 1uando uma e5tenso es%rita em C ou CYY tem
um m0dulo em Python 1ue oferea uma interfa%e de alto n+vel, este m0dulo deve ter
o nome em PalavrasComeandoPor:ai7s%ulas, en1uanto o m0dulo em C-CYY deve
ter o nome todo em min7s%ulas, %omeando "or um unders%ore Tso%Xet, "or
e5em"lo'#
Domes de Classes
>uase sem e5%eo, nomes de %lasse devem usar o "adro de
PalavrasComeandoPor:ai7s%ula, e5%eto no %aso de %lasses "ara uso interno, 1ue
devem %omear %om um underscore#
Domes de E5%e"tions
Se um m0dulo define uma 7ni%a exception usada "ara todos os ti"os de erro, ela
geralmente %hamada AerrorA ou AErrorA#
Domes de Oun/es
Oun/es glo&ais, e5"ortadas "or um m0dulo "odem usar tanto o "adro
PalavrasComeandoPor:ai7s%ula, 1uanto totalmente em min7s%ulas ou
min7s%ulasTse"aradasT"orTunders%ore'# Do h3 nenhuma "refer8n%ia %lara, mas o
"rimeiro estilo %ostuma ser mais usado "ara fun/es 1ue "rov8m mais
fun%ionalidade, en1uanto o segundo usado "or fun/es mais sim"les#
Vari3veis Glo&ais Vari3veis glo&ais devem ser usadas somente dentro do m0dulo# Es
%onven/es so as mesmas "ara fun/es# :0dulos 1ue so "ro9etados "ara ser usados
%om Kfrom : im"ort WK devem ter suas glo&ais %om um unders%ore %omo "refi5o,
"ara evitar 1ue se9am e5"ortadas#
Domes de :todos
Vale o mesmo "ara as fun/es# @se dois underscores 1uando for im"ortante 1ue
a"enas a %lasse atual a%esse um atri&uto# mas tenha em mente 1ue isso no torna o
mtodo realmente "rivado# @m usu3rio insistente ainda "ode a%ess3-lo de diversas
formas, atravs do atri&uto __dict__ "or e5em"lo'#
2erana
=e%ida sem"re se os mtodos de uma %lasse e as vari3veis de uma instZn%ia sero
"7&li%os ou no# Em geral, nun%a torne vari3veis "7&li%as, a menos 1ue vo%8 este9a
im"lementando algum ti"o de registro# =e%ida ainda se os atri&utos sero "rivados
ou no# E diferena entre eles 1ue atri&utos "rivados so a1ueles 1ue 9amais tero
utilidade "ara uma su&%lasse, en1uanto os "7&li%os "odem ter# S "rudente "ro9etar
suas %lasses tendo a "ossi&ilidade de herana em mente#
Etri&utos "rivados devem ter dois underscores no %omeo e nenhum no fim# Etri&utos no-"7&li%os
devem ter um underscore no %omeo e nenhum no fim#
Etri&utos "7&li%os no devem ter underscores nem no %omeo, nem no fim, a menos 1ue eles
entrem em %onflito %om "alavras reservadas, %aso em 1ue um 7ni%o underscore no fim "refer+vel
a um no %omeo, ou a uma "ron7n%ia diferente, %omo %lassT ao invs de Xlass#
*ecomenda+es ao Pro%ramar
Com"ara/es %om singletons, %omo "one, Halse e 3r+e devem sem"re ser feitas %om AisA ou Ais
notA# Elm disso, %uidado "ara no es%rever Aif 5A 1uando o 1ue vo%8 dese9a Aif 5 is not DoneA,
%omo ao testar se uma vari3vel ou argumento 1ue tem um valor "adro de "one, teve outro valor
atri&u+do#
Classes so sem"re "referidas I strings, %omo em exceptions# :0dulos ou "a%otes devem definir
sua "r0"ria %lasse-e5%e"tion &ase, 1ue deve ser uma su&%lasse da %lasse E5%e"tion# Sem"re in%lua
uma docstring# E5em"lo,
Es%onder n7mero das linhas
1 class 5essage,rror(,<ce!tion):
2 ---Base class for errors in the eail !ackage1---
@se mtodos do o&9eto string ao invs do m0dulo string, a menos 1ue se9a e5igida %om"ati&ilidade
%om vers/es de Python anteriores I H#.# 6s mtodos so muito mais r3"idos e t8m a mesma EP? de
strings Unicode#
Evite fatiar strings 1uando verifi%ando "refi5os ou sufi5os# @se os mtodos startswith() e
endswith(), 1ue so mais efi%ientes e menos su9eitos a erro# Por e5em"lo,
Do use,
Es%onder n7mero das linhas
1 if foo8:39 == 'bar':
E sim,
Es%onder n7mero das linhas
1 if foo1startswith('bar'):
E e5%eo se e5istir a ne%essidade do seu %0digo de fun%ionar %om vers/es de Python anteriores I
4#R#H#
Com"ara/es de ti"o de o&9etos devem sem"re usar isinstance() ao invs de %om"arar ti"os
diretamente# E5em"lo,
Do use,
Es%onder n7mero das linhas
1 if t.!e(obI) is t.!e(1):
E sim,
Es%onder n7mero das linhas
1 if isinstance(obI, int):
>uando estiver verifi%ando se o o&9eto uma string, lem&re-se 1ue ele tam&m "ode ser uma string
unicode< Em Python H#[, str e unicode t8m uma %lasse &ase em %omum, basestring, ento vo%8
"ode sim"lesmente es%rever,
Es%onder n7mero das linhas
1 if isinstance(obI, basestring):
Em Python H#H o m0dulo types tem o ti"o StringCy"es "ara o mesmo "ro"0sito,
Es%onder n7mero das linhas
1 fro t.!es i!ort 2tring3.!es
2 if isinstance(obI, 2tring3.!es):
Com se1\8n%ias strings, listas, tu"les', tenha em mente o fato de 1ue, 1uando va;ias, elas so
falsas em um %onte5to &ooleano, "ortanto, Aif not se1A ou Aif se1A so "refer+veis a Aif lense1'A ou
Aif not lense1'A#
Do use strings 1ue de"endam de uma 1uantia signifi%ativa de es"aos no %omeo ou no fim# E
1uantidade desses es"aos visualmente indistingu+vel e alguns editores at mesmo a a9ustam#
Do %om"are valores &ooleanos %om 3r+e e Halse usando NN o ti"o (ool novo em Python
H#['
Do use
Es%onder n7mero das linhas
1 if greeting == 3r+e:
E sim
Es%onder n7mero das linhas
1 if greeting:
*e)erncias
4# PEP F, Style Guide for C Code, van Rossum
H# htt",--***#"ython#org-do%-essays-styleguide#html
[# PEP HRF, =o%string Conventions, Goodger, van Rossum
B# htt",--***#*iXi"edia#%om-*iXi-CamelCase
R# (arryKs GD@ :ailman-mimeli& style guide
Coyri%ht
Este do%umento foi dis"oni&ili;ado em dom+nio "7&li%o#
Cradu;ido "or Pedro)erne%X
4# PEP F, Style Guide for C Code, van Rossum 4'