Recurso de formatação de código é adicionado experimentalmente ao uv

• A nova versão do uv oferece experimentalmente o recurso de formatação de código
• O comando uv format usa internamente o formatador do Ruff para estilizar código Python de forma consistente
• Agora é possível organizar o código de forma simples usando apenas o uv, sem depender de uma ferramenta separada
• Os usuários podem ajustar em detalhes o comportamento da formatação por meio de argumentos adicionais
• Como ainda é um recurso experimental, o modo de uso e o tratamento de erros ainda podem mudar

---

Visão geral

A versão mais recente do uv (0.8.13) introduz o recurso uv format, um comando experimental aguardado há muito tempo por desenvolvedores Python. Com isso, é possível organizar o estilo do código usando apenas a ferramenta uv, sem precisar gerenciar uma ferramenta de formatação separada dentro do projeto.

O que é uv format?

• O comando uv format oferece formatação de código Python por meio da interface do uv
• Internamente, ele chama o formatador do Ruff para reorganizar automaticamente o código de forma consistente

Observações para desenvolvedores

Charlie Marsh (desenvolvedor do uv) explicou o seguinte no Hacker News:

Ruff e uv não estão sendo mesclados; continuam sendo ferramentas separadas.
O objetivo é apenas melhorar a experiência para que o usuário possa usar o formatador sem percebê-lo como uma ferramenta separada.
É semelhante à relação entre cargo fmt e rustfmt no ecossistema Rust.

Como usar

• É necessário usar a versão 0.8.13 ou superior do uv
• Ao executar o comando uv format na raiz do projeto, o efeito é o mesmo de executar ruff format
• O modo de execução segue a interface de comandos do uv

Passagem de argumentos adicionais

• No formato uv format -- [argumentos adicionais], é possível definir opções detalhadas a serem repassadas ao Ruff
• Assim, dá para aproveitar ao mesmo tempo a praticidade do uv e a configuração refinada do Ruff

Aviso sobre a fase experimental

• No momento, o recurso está em fase experimental, e no futuro a forma do comando ou a integração com a estrutura do projeto podem mudar
• O tratamento de erros e o formato de saída também devem continuar sendo aprimorados
• O recurso deve evoluir com base no feedback dos usuários

Encerramento

• Se você precisa de estilização de código simples e consistente em projetos Python, vale a pena experimentar o uv format
• Como se trata de uma adoção experimental, usar o recurso e enviar feedback pode contribuir para a evolução futura do uv

[GN⁺]

Comentários do Hacker News

• Acho que seria melhor se ruff se unisse ao ty; uv deveria se concentrar em gerenciamento de pacotes ou projetos e não se envolver em edição de estilo de código. Na minha visão, o único caso em que uv deveria modificar arquivos de código seria em atualizações de dependências (PEP 723)
  • Quero deixar claro que ruff e uv não estão se unindo e continuarão sendo ferramentas separadas; a ideia é oferecer uma experiência mais simples para usuários que não querem se preocupar com o formatter separadamente. É uma configuração parecida com a do Cargo no Rust, em que cargo fmt executa internamente o rustfmt
  • É basicamente imitar a forma como cargo fmt existe no cargo do Rust
  • O objetivo, em essência, é tornar o uv um gerenciador de pacotes Python completo, enquanto cada ferramenta componente também pode ser usada separadamente quando necessário. Ou seja, uv seria como o cargo para Python, e se você só precisa de um type checker rápido, usa o ty; se só precisa de formatter/linter, usa o ruff. Nesse sentido, juntar ruff e ty não parece fazer muito sentido
  • Também me pergunto como seria se algum dia o ty fosse incorporado ao uv; como tudo vem da astral.sh, isso talvez faça parte da visão, mas o ty ainda não parece pronto
  • O próximo passo lógico seria introduzir algo como uv lint para executar internamente o ty; idealmente, seria ótimo poder preparar um projeto Python inteiro (formatar, lintar, testar, publicar) com um comando padrão ou uma sequência de comandos. Talvez essa seja a visão por trás disso
• Eu realmente adoro usar uv, mas fico um pouco preocupado com ele estar ficando inchado sem necessidade. Por exemplo, vários subcomandos suportam flags muito específicas, e algumas acabam produzindo quase o mesmo resultado (uv run --no-project e uv run --active, por exemplo). Em vez de adicionar novos recursos sem parar, eu gostaria que o foco fosse mais em melhorar as ferramentas e a documentação que já existem
  • Tornar projetos Python estáveis, reproduzíveis e portáveis é uma tarefa realmente difícil. Em teoria, o uv sync é muito útil porque só constrói conjuntos de pacotes que podem ser reproduzidos novamente, mas pacotes complexos como torch-tensorrt ou flash-attn inevitavelmente variam conforme o ambiente. A comunidade Python muitas vezes tende a personalizar o problema com a lógica de “na minha máquina funciona”, mas o custo de tornar software distribuível, seguro, repetível e confiável nunca desaparece; no fim, alguém vai pagar esse custo depois em condições mais restritas. É realmente muito difícil tentar atender todos esses diferentes usuários e exigências operacionais
  • Não entendo muito bem por que adicionar subcomandos ao uv seria visto como inchaço; uv já é uma ferramenta complexa e bem documentada. Se os comandos forem intuitivos e autoexplicativos assim, acho perfeitamente natural adicioná-los
  • Quando falam sobre o uv, sinto que é como dizer “o comando make tem alvos demais”
  • Fico curioso se essas opções ficam embutidas no executável principal ou se funcionam como binários separados, como no apt ou no cargo
• Acho que essa atualização foi claramente uma boa escolha. Não entendo por que tanta gente é contra uma direção melhor. Claro, “já dá para fazer isso de um jeito um pouco mais inconveniente”, mas continua sendo “um pouco mais inconveniente”
  • Não acho que uvx ruff format ser uma palavra mais longo seja algo ruim. O que pode ser mais confuso é não ficar claro qual formatter está sendo executado de fato, se o ruff será instalado automaticamente ou se, como antes, a ferramenta será baixada e armazenada em cache
  • Concordo fortemente com isso; seria ainda melhor se permitissem configurar o formatter no pyproject
  • Minha maior reclamação é que, por enquanto, aparentemente não há suporte a outros formatters. Se meu projeto usa black, uv format não funciona
• Pessoalmente, estou bem animado porque essa mudança deve tornar a formatação de código drasticamente mais fácil para a minha pequena equipe, cujos principais membros são atuários. Como o uv já teve um impacto considerável na adoção e no onboarding de Python por aqui, qualquer forma de elevar a qualidade do código com mais facilidade é sempre bem-vinda. Claro, também poderíamos usar só o ruff separadamente ou montar uma configuração com pre-commit, mas o modelo mental simples de uv <recurso> ajuda muito a equipe. Também seria ótimo se houvesse integração com outros formatters, e se chegasse ao ponto de suportar até formatação de modelos SQL/dbt, eu não teria mais nada a pedir. Por enquanto, vou testar para ver o potencial
  • Se você precisa de tanta formatação múltipla assim, talvez seja melhor usar algo como um Makefile ou justfile; aí dá para fazer just format e formatar Python/SQL/Bash/TypeScript de uma vez só
• Parece um pouco excesso de funcionalidade. Tenho usado uv cada vez mais há mais de um ano e reconheço as vantagens, mas ele ainda não é minha primeira escolha, e essa mudança não deve aumentar minha preferência por ele
  • Gostaria de entender especificamente qual é o problema nessa abordagem. Go, Rust e Elixir adotam isso, e isso torna muito mais fácil configurar e usar projetos nesses ecossistemas de linguagem. A comunidade ganha ao se concentrar em um conjunto comum de ferramentas, e isso oferece um ponto de entrada consistente tanto para iniciantes quanto para especialistas
  • Nesse caso, fico curioso para saber qual ferramenta você prefere mais
• Acho que, em algum momento, as funcionalidades do ruff vão acabar sendo integradas ao uv e ao ty. O linting poderia ficar mais inteligente nas mãos do ty, que entende melhor a base de código, enquanto a formatação faria sentido sob responsabilidade do uv, cujo foco principal é o gerenciamento de projeto
  • Como o ty já está no mesmo repositório que o ruff, a integração talvez nem esteja tão distante assim
• Um gerenciador de pacotes é essencial para instalar pacotes em ambientes de execução, mas misturá-lo com ferramentas exclusivas de desenvolvimento parece uma espécie de “armadilha atraente, porém perigosa”. Claro que Go e Rust também fazem isso, mas, pensando mais a fundo, não sei se é uma estrutura tão boa assim
  • Isso pode soar muito negativo, mas, como alguém que já usou bastante cargo, eu gostaria que houvesse mais dessas “más ideias”. Se o uv vier a cumprir esse papel de cargo no Python, a experiência de desenvolvimento em Python vai melhorar absurdamente. Depois de mais de 25 anos usando Python e contornando várias deficiências, é muito satisfatório chegar a um ponto em que praticamente tudo possa ser feito só com uv, sem grandes preocupações
• O novo uv format é, na prática, um atalho para uv run --with ruff ruff
• Estou gostando muito dessa direção; se dependesse de mim, chamariam de uv fmt e talvez colocassem algo como uv vet no roadmap também
• Já existem muitas ferramentas de formatação de código bem consolidadas, então não vejo motivo algum para introduzir isso. Parece apenas mais funcionalidade empilhada, e não pretendo incluir isso em nenhum pipeline por enquanto
  • uv format é praticamente um frontend para ruff format; não está sendo adicionado um novo formatter
  • Seria bom que as pessoas soubessem que isso não passa de um atalho para facilitar o uso do ruff format, que muita gente já usa