black
24.10.0
“Qualquer cor que você quiser.”
Black é o formatador de código Python intransigente. Ao usá-lo, você concorda em ceder o controle sobre as minúcias da formatação manual. Em troca, Black oferece velocidade, determinismo e liberdade de reclamações pycodestyle sobre formatação. Você economizará tempo e energia mental para assuntos mais importantes.
O código enegrecido parece o mesmo, independentemente do projeto que você está lendo. A formatação se torna transparente depois de um tempo e você pode se concentrar no conteúdo.
Black torna a revisão do código mais rápida, produzindo as menores diferenças possíveis.
Experimente agora usando o Black Playground. Assista à palestra da PyCon 2019 para saber mais.
Leia a documentação em ReadTheDocs!
O preto pode ser instalado executando pip install black . Requer Python 3.9+ para ser executado. Se você deseja formatar Jupyter Notebooks, instale com pip install "black[jupyter]" .
Se você não pode esperar pelas últimas novidades e deseja instalar a partir do GitHub, use:
pip install git+https://github.com/psf/black
Para começar imediatamente com padrões sensatos:
black {source_file_or_directory}Você pode executar o Black como um pacote se executá-lo como um script não funcionar:
python -m black {source_file_or_directory}Mais informações podem ser encontradas em nossos documentos:
O preto já é usado com sucesso em muitos projetos, pequenos e grandes. Black tem um conjunto de testes abrangente, com testes paralelos eficientes e nosso próprio executor de formatação automática e integração contínua paralela. Agora que nos tornamos estáveis, você não deve esperar grandes mudanças de formatação no futuro. As mudanças estilísticas serão principalmente respostas a relatórios de bugs e suporte para a nova sintaxe Python. Para obter mais informações, consulte O estilo Black Code.
Além disso, como medida de segurança que retarda o processamento, Black verificará se o código reformatado ainda produz um AST válido que seja efetivamente equivalente ao original (consulte a seção Pragmatismo para obter detalhes). Se você estiver se sentindo confiante, use --fast .
Black é um formatador opinativo compatível com PEP 8. Black reformata arquivos inteiros no lugar. As opções de configuração de estilo são deliberadamente limitadas e raramente adicionadas. Não leva em consideração a formatação anterior (veja Pragmatismo para exceções).
Nossa documentação cobre o estilo de código Black atual, mas as alterações planejadas nele também estão documentadas. Vale a pena dar uma olhada em ambos:
As alterações no estilo do código Black estão sujeitas à Política de Estabilidade:
Consulte este documento antes de enviar um problema. O que parece ser um bug pode ser um comportamento intencional.
As primeiras versões de Black costumavam ser absolutistas em alguns aspectos. Eles seguiram seu autor inicial. Na época, isso era bom, pois tornava a implementação mais simples e, de qualquer maneira, não havia muitos usuários. Não foram relatados muitos casos extremos. Como uma ferramenta madura, as pretas fazem algumas exceções às regras que de outra forma seriam mantidas.
Consulte este documento antes de enviar um problema, assim como no documento acima. O que parece ser um bug pode ser um comportamento intencional.
Black é capaz de ler valores padrão específicos do projeto para suas opções de linha de comando a partir de um arquivo pyproject.toml . Isso é especialmente útil para especificar padrões personalizados --include e --exclude / --force-exclude / --extend-exclude para o seu projeto.
Você pode encontrar mais detalhes em nossa documentação:
E se você estiver procurando uma documentação de configuração mais geral:
Dica profissional : se você estiver se perguntando "Preciso configurar alguma coisa?" a resposta é "Não". O preto tem tudo a ver com padrões sensatos. A aplicação desses padrões fará com que seu código esteja em conformidade com muitos outros projetos formatados em Black .
Os seguintes projetos notáveis de código aberto confiam em Black para impor um estilo de código consistente: pytest, tox, Pyramid, Django, Django Channels, Hypothesis, attrs, SQLAlchemy, Poetry, aplicativos PyPA (Warehouse, Bandersnatch, Pipenv, virtualenv), pandas, Pillow , Twisted, LocalStack, cada integração de agente Datadog, Home Assistant, Zulip, Kedro, OpenOA, FLORIS, ORBIT, WOMBAT e muitos mais.
As seguintes organizações usam Black : Facebook, Dropbox, KeepTruckin, Lyft, Mozilla, Quora, Duolingo, QuantumBlack, Tesla, Archer Aviation.
Estamos sentindo falta de alguém? Deixe-nos saber.
Mike Bayer , autor de SQLAlchemy :
Não consigo pensar em nenhuma ferramenta em toda a minha carreira de programação que tenha me proporcionado um aumento maior de produtividade com sua introdução. Agora posso fazer refatorações em cerca de 1% das teclas digitadas que seriam necessárias anteriormente, quando não tínhamos como o código se formatar.
Dusty Phillips , escritor:
Black é teimoso, então você não precisa ser.
Hynek Schlawack , criador do attrs , desenvolvedor principal do Twisted e CPython:
Um formatador automático que não seja uma droga é tudo que eu quero para o Natal!
Carl Meyer , desenvolvedor principal do Django:
Pelo menos o nome é bom.
Kenneth Reitz , criador de requests e pipenv :
Isso melhora muito a formatação do nosso código. Muito obrigado!
Use o emblema no README.md do seu projeto:
[ ![ Code style: black ] ( https://img.shields.io/badge/code%20style-black-000000.svg )] ( https://github.com/psf/black )Usando o emblema em README.rst:
.. image:: https://img.shields.io/badge/code%20style-black-000000.svg
:target: https://github.com/psf/black
Parece com isto:
MIT
Bem-vindo! Fico feliz em ver você disposto a melhorar o projeto. Você pode começar lendo isto:
Você também pode dar uma olhada no restante dos documentos contribuintes ou conversar com os desenvolvedores:
O log ficou bastante longo. Ele foi movido para seu próprio arquivo.
Veja ALTERAÇÕES.
A lista de autores é bastante longa hoje em dia, por isso fica em seu próprio arquivo.
Veja AUTORES.md
Espera-se que todos os participantes do projeto Black , e em particular do rastreador de problemas, solicitações pull e atividades de mídia social, tratem as outras pessoas com respeito e, de maneira mais geral, sigam as diretrizes articuladas no Código de Conduta da Comunidade Python.
Ao mesmo tempo, o humor é incentivado. Na verdade, espera-se uma familiaridade básica com o Flying Circus de Monty Python. Não somos selvagens.
E se você realmente precisa dar um tapa em alguém, faça isso com um peixe enquanto dança.
