Aqui está a conclusão: eu prefiro o preto como ferramenta de formatação automática, mas existem algumas dicas práticas (no final) que você deve ter em mente e funciona melhor em paralelo com algumas outras ferramentas como o isort.

Introdução

Autopep8 e Black são ótimas ferramentas para formatar automaticamente seu código Python de acordo com o guia de estilo PEP 8 . Black tem 30,4 mil estrelas no GitHub e é provavelmente a ferramenta mais popular do gênero, enquanto autopep8 tem 4,2 mil estrelas.

Uma das principais diferenças é que o preto é um formatador de opinião, o que significa que sempre converte toda a base de código em seu próprio estilo, enquanto o autopep8 preserva o estilo de entrada até certo ponto e corrige apenas as partes necessárias.

Eu usei as duas ferramentas em meu trabalho e gostaria de compartilhar com você por que prefiro o preto ao invés do autopep8.

Problemas com autopep8

1. Classifica as importações agressivamente

Alguns podem ver isso como uma coisa boa, no entanto, em minha opinião, uma boa ferramenta deve se concentrar em uma coisa e apenas uma coisa. Como ferramenta de formatação, não deve tentar alterar a ordem do código e, de fato, às vezes pode causar problemas.

Vamos considerar o exemplo abaixo. Embora sys.path.appendgeralmente não seja uma boa prática, digamos que realmente queremos fazer algo antes de importar o restante dos módulos.

O Autopep8 reescreveria o script da seguinte forma:

E isso é problemático. Outro exemplo em que posso pensar é que, se quisermos habilitar o back-end do matplotlib para um terminal linux, precisaríamos definir o back-end matplotlib.use("agg") antes do pyplot import from matplotlib import pyplot as plt.

Por outro lado, o preto não alterará o código de exemplo acima. O preto apenas formata e a semântica do código permanece exatamente a mesma. Em outras palavras, o preto não classifica suas importações e não altera a ordem do seu código. (e podemos deixar a tarefa de classificar importações para outra grande ferramenta isort , continue lendo!)

Você ainda pode resolver o problema adicionando # nopep8alguns trechos do seu código, dizendo explicitamente ao autopep8 para não tocá-lo:

Funciona neste caso, mas descobri que a # nopep8regra de exclusão não é aplicada aos comentários, por exemplo, autopep8 ainda converteria o seguinte ### some comment # nopep8em # some comment # nopep8.

Por outro lado, o preto não edita comentários e docstrings, e você pode excluir alguns de seus códigos da formatação adicionando duas linhas de comentário # fmt: offe # fmt: onantes e depois do seu bloco de código.

De qualquer forma, não é muito Pythonic, certo?

2. Não impõe o recuo corretamente

O recuo padrão do Autopep8 é definido como o tamanho da guia do seu editor e você pode especificar o valor passando a opção autopep8 --indent-size 4 myfile.py. Tudo está bem, no entanto, autopep8 apenas este valor de entrada para definir o recuo para o início de cada instrução, mas o tamanho do recuo entre colchetes é sempre definido para o tamanho padrão da tabulação.

Vejamos este exemplo, onde o recuo do código é 1 e o tamanho da guia padrão do meu editor é 4.

Depois de definir o recuo para 3 com autopep8 autopep8 --indent-size 3 format_02_raw.py -i (-i significa no lugar) , obtemos o seguinte:

Podemos ver que o recuo na primeira função está definido corretamente como 3, mas qualquer coisa entre colchetes (neste caso, instrução de impressão e a matriz) é definida como o tamanho de tabulação padrão 4.

Descobri isso porque o tamanho da guia padrão em meu ambiente de trabalho é 2 e prefiro o recuo de 4. Pode parecer trivial, mas por que arriscar a inconsistência desnecessária? O preto não permite que você configure o tamanho do recuo, pois sempre define o recuo para 4 em todos os lugares, o que não me importa.

Usando o preto da maneira certa

O preto implementa seu próprio estilo, do qual algumas pessoas gostam e outras não. Eu gosto bastante porque geralmente é muito limpo e legível, mas há duas coisas a serem lembradas.

1. Use uma vírgula à direita

O exemplo abaixo mostra provavelmente uma das razões mais comuns pelas quais algumas pessoas não gostam de preto. Vamos ver o antes e depois:

É irritante, mas antes que você fique bravo, vamos fazer algumas pequenas alterações no código e ver como o preto muda seu comportamento:

Sim, o preto usa vírgulas à direita para decidir se os itens serão agrupados ou permanecerão em novas linhas. Se um item semelhante a uma matriz terminar sem uma vírgula à direita, seja uma lista, matriz ou dicionário, o preto sempre tentará distorcê-lo em uma linha; se exceder o comprimento da linha, o preto colocará seu conteúdo em novas linhas e adicionará uma vírgula à direita para você . Se houver uma vírgula no final do item, o preto separa seu conteúdo em novas linhas para você .

Resumindo, sempre haverá uma vírgula à direita sempre que o conteúdo de um item semelhante a uma matriz estiver em novas linhas. Acho que isso faz sentido e, em geral, as vírgulas à direita são uma boa prática, pois facilitam a manutenção do código, além de gerar limpeza git diffquando você faz alterações. Portanto, se você não quiser que o preto envolva seu código em uma linha, adicione uma vírgula no final!

Dicas de bônus: quando escrevo consultas SQL, escrevo

SELECT column_a
      ,column_b
      ,column_c
FROM some_table

SELECT column_a,
       column_b,
       column_c
FROM some_table

2. Especifique o comprimento da linha, se necessário

A única coisa que não gosto no estilo de código preto até agora é em relação às instruções if longas, como mostra o exemplo abaixo:

Ele reforçou a consistência, mas sacrificou a legibilidade. O comprimento de linha padrão do preto é 88, mas às vezes tenho instruções um pouco mais longas e não quero que sejam formatadas dessa forma.

Minha solução é permitir comprimento de linha um pouco mais longo. Podemos especificar o comprimento da linha usando --line-lengthou -lsinalizador e, se definirmos o comprimento da linha como 100 black -l 100 format_05_raw.py, o exemplo acima não será reformatado. Pela minha experiência, um comprimento de linha de 100 serviria para a maioria das declarações longas, mantendo a boa legibilidade do código (embora você deva realmente considerar reescrever sua declaração se tiver mais de 100 caracteres), mas é claro, isso cabe a cada equipe decidir .

Autopep8 também tem esse sinalizador --max-line-length, no entanto, como autotpep8 tende a preservar o estilo de código original, o resultado da formatação é muito menos sensível ao comprimento de linha especificado do que preto.

3. Use preto com isort

Como mencionei anteriormente, o preto não classifica suas importações e podemos usar isort (5,4 mil estrelas no GitHub) para fazer isso. Vejamos um exemplo rápido sobre o que o isort pode fazer:

É legal e não atrapalha nosso sys.path.appendexemplo.

Observe que existem algumas pequenas diferenças entre como isort e black organizam as importações, e podemos dizer a isort para classificar as importações de acordo com o estilo de código preto isort --profile black format_06_raw.py.

Agora temos um fluxo de trabalho muito bom: use isort para classificar as importações primeiro e, em seguida, use black para formatar nosso código. Podemos combinar as duas etapas no Makefile:

format:
 isort --profile black src/
 black -l 100 src/

Conclusão

Neste artigo, comparamos duas ferramentas populares de formatação automática em Python — autopep8 e black. Expliquei por que prefiro preto e como gosto de usá-lo, e espero que isso seja útil.

Esta também é a primeira vez que escrevo um artigo no Medium, sinta-se à vontade para me bater palmas se gostar e não se esqueça de deixar seus comentários abaixo, e até a próxima!