Artigo original: https://www.freecodecamp.org/news/auto-format-your-python-code-with-black/

Escrever código em Python é uma coisa. Escrever o código em um formato bom é outra. Programadores júniores frequentemente focam em ter a certeza de que seus códigos estão funcionando e se esquecem de formatar o código corretamente ao longo do caminho.

Se você escreve um programa pequeno (com mil linhas de código) você, provavelmente, deixará a formatação do seu código para lá.

Porém, à medida que os programas ficam mais e mais complexos, eles ficam cada vez mais difíceis de entender. Em certo ponto (em torno de 15 mil linhas de código), fica difícil de entender o código que você mesmo escreveu.

A diferença entre trabalhar em um código bem formatado e em um código mal formatado é como a diferença entre morar em um palácio e morar em uma casa suja.

Por que formatar seu código em Python é importante?

Legibilidade

Formatar seu código ajudará você a ler seu código de modo eficiente. Ele parece mais organizado e, quando alguém olhar para ele, terá uma boa impressão.

Ajudará em suas entrevistas de programação

Quando você estiver em uma entrevista de programação, às vezes, os entrevistadores estarão atentos ao fato de você estar ou não formatando o código corretamente. Se você se esquecer dessa formatação, poderá perder sua perspectiva de emprego apenas por causa de seu código mal formatado.

Apoio da equipe

Formatar seu código se torna mais importante quando você está trabalhando em uma equipe. Várias pessoas, provavelmente, estarão trabalhando no mesmo projeto de software. O código que você escreve deve ser entendido por seus colegas de equipe. Caso contrário, torna-se mais difícil trabalhar em conjunto.

Facilita a detecção de bugs

Um código mal formatado pode tornar extremamente difícil a detecção de bugs ou, até mesmo, trabalhar em um programa. Ele também é realmente horrível de se ver. É uma ofensa aos seus olhos.

Pylint e Flake8

A maioria dos desenvolvedores em Python gosta de usar o Pylint ou o Flake8 para verificar seus códigos quanto a erros e regras de estilo.

O Pylint é uma ferramenta que verifica erros em Python. Ele tenta impor um padrão de codificação e procura por coisas que "cheiram mal" no código. Ele também pode procurar por certos erros de tipo, recomendar sugestões sobre como determinados blocos podem ser refatorados e oferecer a você detalhes sobre a complexidade do código.

O Flake8 é uma biblioteca do Python que engloba PyFlakes, pycodestyle e o script de McCabe, de Ned Batchelder. É um ótimo conjunto de ferramentas para verificar sua base de código em relação ao estilo de codificação (PEP8), erros de programação como "biblioteca importada, mas não utilizada", "nome indefinido" e código que não está sendo indentado adequadamente.

O problema é que essas ferramentas apenas relatam os problemas que identificam no código-fonte e deixam o fardo de corrigi-los para os desenvolvedores do Python!

Se tivéssemos uma ferramenta que pudesse identificar e resolver o problema ao mesmo tempo, não seria ótimo? O Black é uma ferramenta que permite que você identifique erros e formate seu código em Python ao mesmo tempo. Assim, você se torna mais produtivo.

Introdução ao Black

Do README do projeto:

Ao usar o Black, você concorda em ceder o controle sobre as minúcias da formatação manual. Em troca, o Black oferece a você velocidade, determinismo e liberdade do pycodestyle reclamando da formatação. Você economizará tempo e energia mental para assuntos mais importantes.

O Black pode reformatar seu arquivo inteiro adequadamente, de acordo com o estilo de código do Black. Isso ajuda seu cérebro a se concentrar no problema que você quer resolver e em programar soluções, em vez de se distrair com a estrutura do código e com pequenas diferenças estilísticas.

Então, vamos ver como usá-lo.

Instalar o Black

O Black pode ser instalado executando pip install black. Ele requer a versão 3.6.0 do Python ou superior para ser executado. Assim que o Black estiver instalado, você terá uma nova ferramenta de linha de comando chamada Black disponível em seu terminal e estará pronto para começar!

Para começar imediatamente com padrões sensatos, escolha o arquivo em Python que deseja formatar e, em seguida, escreva black filename.py no terminal. O Black, então, formatará seu arquivo em Python.

Agora, veremos o que o Black pode nos ajudar a fazer.

Formatar um único arquivo

Vejamos este exemplo simples: aqui estão minhas duas funções no meu arquivo em Python, chamado sample_code.py.

Você pode usar black sample_code.py no terminal para mudar o formato. Após executar o Black, você verá a seguinte saída:

Em seguida, abra o arquivo sample_code.py para ver o código em Python formatado:

O código em Python, agora, está formatado e mais legível.

Formatar múltiplos arquivos

Para formatar mais de um arquivo em Python, escreva black nome_da_pasta/ no terminal.

Três arquivos em Python dentro da pasta chamada python_with_black foram reformatados.

Verificando arquivos para formatação

Se você não quer que o Black altere seu arquivo, mas quer saber se ele acha que um arquivo deveria ser alterado, você pode usar um dos seguintes comandos:

black --check .: esse comando verificará quais arquivos em Python podem ser formatados na pasta atual (mas não os modifica).

black --check --diff file_name.py : esse comando mostra o que precisa ser feito no arquivo, mas não o modifica.

Alterar o número de caracteres por linha

Observe que o padrão do Black é de 88 caracteres para o comprimento da linha, mas você pode alterar isso usando a opção -l ou - -line-length.

Por exemplo, para alterar para 60 caracteres: black -l 60 python_file.py.

Black no Jupyter Notebook

Para usuários do Jupyter Notebook, você ainda pode formatar automaticamente seu código em Python com esta simples extensão chamada Jupyter Black. Esta extensão reformata/embeleza o código em uma célula de código do Notebook usando o Black.

A extensão Jupyter Black fornece

• Um botão para a barra de ferramentas.
• Um atalho de teclado para reformatar a célula de código atual (padrão: Ctrl-B).
• Um atalho de teclado para reformatar todas as células de código (padrão: Ctrl-Shift-B).

Instalar o Jupyter Black

Primeiro, assegure-se de ter instalado jupyter-contrib-nbextensions e black. Então, execute os seguintes comandos.

jupyter nbextension install https://github.com/drillan/jupyter-black/archive/master.zip — user

Em seguida, habilite a extensão executando:

jupyter nbextension enable jupyter-black-master/jupyter-black

Agora, você pode começar a formatar seu código em Python em cada célula do Notebook.

Primeiro, selecione a célula do notebook na qual você deseja formatar seu código em Python. Em seguida, clique no botão de extensão chamado Black.

Então, selecione o botão Jupyter Black:

Integração com o editor

Você pode integrar o Black com os seus editores favoritos. Atualmente, o Black suporta PyCharm/IntelliJ IDEA, Wing IDE, Vim, Visual Studio Code, Sublime Text 3, Atom/Nuclide, Kakoune e Thonny. Siga as instruções aqui para integrar o Black com seu editor favorito (texto em inglês).

Se você quiser aprender mais sobre o Black, recomendo assistir a palestra de Łukasz Langa na PyCon 2019 (em inglês).

Se você aprendeu algo novo ou gostou de ler este artigo, compartilhe-o para que outras pessoas possam vê-lo. Até lá, nos vemos na próxima publicação! Você também pode encontrar o autor pelo Twitter.