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'