Otávio Miranda

DeepSeek V4, agentes embutidos e App Runner: IA vira infraestrutura de verdade

Sun, 26 Apr 2026 10:01:30 GMT

Nota: gerado por IA (The Paper LLM), com fontes originais listadas por bloco.

O lote de hoje tem uma linha bem visível: a parte interessante da IA está descendo para a infraestrutura. O modelo continua importante, claro. Mas o que muda o resultado no mundo real aparece no cache, no runtime, no desenho da interface, no fluxo de verificação, no serviço gerenciado que deixa de evoluir e na cadeia de pacotes que entra no container sem pedir licença.

DeepSeek V4 volta como história de runtime, não só de modelo

O DeepSeek V4 já tinha aparecido pelo ângulo de contexto longo, pesos abertos e custo. A novidade de 25 de abril de 2026 é outra: a equipe de SGLang e Miles publicou suporte de "dia zero" para servir e treinar o modelo, e o texto deixa claro que 1 milhão de tokens não se sustenta sozinho.

O post da LMSYS fala de duas famílias de problema. Na inferência, aparecem ShadowRadix para prefix caching em atenção híbrida, HiSparse para estender KV cache com memória de CPU, speculative decoding com metadados dentro do CUDA graph, Flash Compressor, Lightning TopK, kernels para Blackwell e Hopper, além de paralelismo para prefill e deployment. Na parte de treinamento, Miles entra com suporte a RL, paralelismo DP, TP, SP, EP, PP e CP, FP8 e cuidado extra com estabilidade numérica.

O detalhe que importa para agente é o custo de carregar histórico. O texto mostra que, com ShadowRadix e metadados dentro do grafo, o throughput de decode fica quase plano entre 4 mil e 900 mil tokens. Em B200, a queda citada vai de 199 para 180 tokens por segundo. Em H200, de 266 para 240. Em outra parte, o HiSparse promete até 3 vezes mais capacidade e throughput em serving de contexto longo ao manter a parte inativa do KV cache em CPU.

Isso muda o jeito de olhar para contexto gigante. Não é "joga tudo no prompt e pronto". É uma pilha inteira para impedir que o histórico mate latência, memória e custo. Prefix cache, compressão, seleção top-k, offload de cache, kernel customizado e scheduler viram parte do produto.

Então, sim, DeepSeek V4 apareceu de novo. Mas não é reprise. O foco saiu da tabela de preço e foi para a pergunta que realmente decide se um agente longo fica usável: quem está segurando o peso do contexto quando a conversa passa de demo bonita para workload de verdade?

Fonte: LMSYS - DeepSeek-V4 on Day 0: From Fast Inference to Verified RL with SGLang and Miles.

Feldera puxa agentes para dentro do software

O texto da Feldera acerta porque troca a fantasia do "agente colega de trabalho" por um problema mais técnico: agente fica barulhento quando o software oferece interface ruim. Se a única superfície é chat, ele precisa perguntar, resumir, negociar, inferir estado e explicar demais. Isso consome atenção humana e tokens.

A proposta é construir software que o agente consiga operar com menos conversa. O post cita três padrões bem conhecidos: CLI, especificações declarativas e reconciliation loops no estilo Kubernetes. Em vez de transformar tudo em um diálogo, o sistema oferece comandos, estado desejado e mecanismo de convergência. O agente deixa de perguntar "o que faço agora?" o tempo todo e passa a trabalhar em cima de interfaces mais previsíveis.

O ponto mais forte vem quando o texto entra em banco de dados e change data capture. Em um modelo ruim, o agente consulta tabelas, compara snapshots e tenta descobrir o que mudou. Em um modelo melhor, o sistema emite eventos: esta transação entrou, esta conta foi marcada como risco alto, este registro mudou para revisão. O agente reage a mudanças específicas, não a um mar de estado.

Isso conversa muito com DevOps, segurança e coding agents. Um agente com boa interface não precisa ficar "lendo o mundo" a cada rodada. Ele recebe sinais precisos, aplica uma política, propõe uma mudança ou chama um humano quando a decisão passa do limite.

A frase que fica é simples: software feito para humanos nem sempre é software bom para agentes. Às vezes, a melhor evolução não é um prompt maior. É um produto com CLI decente, estado declarativo, evento de mudança e limite de ação.

Fonte: Feldera - Agents Aren't Coworkers, Embed Them in Your Software.

O caso da matemática mostra o gargalo da verificação

A Scientific American publicou uma história com cara de manchete viral: Liam Price, 23 anos, sem treinamento avançado formal em matemática, usou ChatGPT Pro e chegou a uma solução para um problema de Erdős que estava aberto havia cerca de 60 anos. O assunto envolve conjuntos primitivos de números inteiros e uma conjectura sobre o comportamento do chamado Erdős sum quando os números do conjunto ficam grandes.

O risco óbvio seria transformar isso em "IA substituiu matemáticos". Não é o que a própria reportagem mostra. Price encontrou uma rota incomum com ajuda do modelo e mandou o resultado para Kevin Barreto. Depois, especialistas como Terence Tao e Jared Lichtman avaliaram o caminho. Lichtman foi bem direto: a saída bruta do ChatGPT era ruim, e alguém com conhecimento precisava peneirar, entender e comprimir a ideia. Tao também descreveu a mudança como uma rota diferente da sequência padrão de movimentos que humanos vinham tentando.

Essa é a parte útil para quem trabalha com código, agentes e automação. A IA consegue baratear busca. Ela pode sugerir um caminho estranho, puxar uma técnica de uma área vizinha ou quebrar a inércia de uma abordagem que todo mundo vinha repetindo. Mas a prova ainda precisa existir. No fim, alguém precisa validar se o caminho fecha.

É um bom antídoto contra dois exageros opostos. Não é "milagre, acabou a matemática humana". Também não é "não aconteceu nada, ignore". A notícia mostra um padrão que deve aparecer mais vezes: geração de candidatos fica barata, verificação continua cara.

Para dev, dá para traduzir quase sem esforço. O agente pode sugerir refactor, patch, arquitetura ou exploit hipotético. A pergunta séria vem depois: compila, passa teste, preserva contrato, não vaza segredo, não inventa requisito e não quebra produção?

Fonte: Scientific American - An amateur just solved a 60-year-old math problem by asking AI.

AWS App Runner fecha para novos clientes e vira lição de plataforma

A AWS informa que o App Runner deixará de aceitar novos clientes a partir de 30 de abril de 2026. Quem já usa o serviço pode continuar criando recursos e serviços normalmente, mas a AWS também diz que não planeja adicionar novos recursos. Em outras palavras: o produto continua vivo para clientes existentes, mas a trilha de evolução acabou.

O guia de migração recomenda Amazon ECS Express Mode. A promessa é preservar parte da simplicidade operacional do App Runner, mas em cima de uma pilha ECS mais explícita. A AWS descreve um fluxo em que você fornece uma imagem de container e duas IAM roles, e o ECS cria a aplicação com Fargate, Application Load Balancer, auto scaling e rede na sua conta.

O caminho sugerido é blue/green com DNS weighted routing. O serviço antigo e o novo rodam em paralelo, e o tráfego vai sendo deslocado aos poucos via Route 53 ou outro provedor de DNS. Se a aplicação foi publicada no App Runner a partir de código fonte, antes é preciso criar uma etapa de build que gere uma imagem de container e envie para um registry.

O recado prático é antigo, mas sempre volta com um nome novo. Serviço gerenciado compra velocidade, não imortalidade. Quando o produto para de evoluir, o que salva a migração é ter container, domínio, DNS, certificado, observabilidade, variáveis, health check e papéis de IAM minimamente entendidos.

Para quem mantém aplicação pequena, isso não significa "nunca use serviço gerenciado". Seria exagero. Significa só que abstração boa precisa ter rota de saída. Se ela não tiver, a conveniência vira dívida.

Fonte: AWS App Runner availability change.

npm e PyPI continuam sendo parte da superfície de ataque

O texto "Npm Slop & Wonky Software Supply Chains", publicado em 9 de abril e atualizado em 24 de abril de 2026, não é uma notícia de última hora. Entra aqui porque encaixa direto no tema do dia: infraestrutura de agente não é só sandbox. Também é o que você instala dentro dele.

A crítica central é que npm e PyPI não são ecossistemas realmente baseados em fonte. Eles distribuem bundles, wheels e binários enviados por mantenedores. Em muitos casos, não dá para reconstruir o pacote publicado a partir do repositório original. Lockfile ajuda a fixar o artefato baixado, mas o hash normalmente amarra o pacote pronto, não toda a cadeia de origem.

Os exemplos tornam o problema bem visível. O texto diz que o OpenClaw puxa 385 pacotes npm, com 324 sem attestation. Express, mesmo sendo um servidor web clássico do Node, puxa 65 pacotes, todos sem attestation no levantamento citado. Vite aparece como caso menor, com 15 pacotes, mas ainda inclui JavaScript empacotado e binários Rust pré-compilados.

Attestation melhora a situação, mas não fecha a história. O autor lembra que ela pode fixar commit e workflow, sem necessariamente fixar imagem do runner, ferramentas baixadas durante o build e binários de ações terceiras. A cadeia parece mais limpa, mas ainda pode depender de coisa que muda por baixo.

Para agente de IA, isso é especialmente chato. Muita gente fala de prompt injection, permissão de ferramenta e isolamento de container. Tudo isso importa. Mas, se o ambiente baixa centenas de dependências opacas antes de rodar, a fronteira de confiança já começou antes do primeiro prompt.

Fonte: Simon Ramstedt - Npm Slop & Wonky Software Supply Chains.

Destaques rápidos

O relatório da Cisco Talos sobre UAT-4356 e FIRESTARTER é de 23 de abril, mas ainda merece atenção operacional: o backdoor roda dentro do processo LINA em dispositivos Cisco ASA e FTD, e a mitigação séria pode envolver reimagem do equipamento. Fonte: Cisco Talos - UAT-4356's Targeting of Cisco Firepower Devices.
O texto da DTN Advisory sobre OAuth em ferramentas de IA junta Vercel, Context.ai, Lovable e MCP em uma tese útil: uma integração SaaS com escopo amplo demais vira uma relação de confiança persistente. O ponto não é só "mais um vazamento"; é inventário e governo de OAuth. Fonte: DTN Advisory - Knock Knock, Your AI Tool Just OAuth'd the Attacker In.
O GnuPG 2.5.19 saiu em 24 de abril com a série 2.5 trazendo Kyber, também chamado de ML-KEM ou FIPS 203, para o caminho principal de criptografia pós-quântica. O anúncio também lembra que a série 2.4 chega ao fim de vida em cerca de dois meses. Fonte: GnuPG announce - GnuPG 2.5.19 released.
O tutorial sobre PageIndex é mais vitrine de produto do que paper final, mas a ideia vale radar: em documentos longos e estruturados, árvore de seções e busca guiada por raciocínio podem ser melhores do que jogar tudo em vetor e torcer pela similaridade. Fonte: MarkTechPost - RAG Without Vectors: How PageIndex Retrieves by Reasoning.
Matthew Brunelle descreve um uso bem pé no chão de Claude Code: ressuscitar um projeto pessoal que provavelmente ficaria parado. O valor não está em "aceitar tudo", mas em dar spec, convenções, OpenAPI, plan mode, revisão e teste real de cliente. Fonte: Matthew Brunelle - It's OK to Use Coding Assistance Tools To Revive The Projects You Never Were Going To Finish.
O post sobre reviver BrowserID em 2026 é pequeno, mas toca em um problema que vai crescer com apps pessoais feitos com IA: autenticação para software pequeno, de domínio próprio, sem depender de Auth0, Google ou um painel centralizado para cada brinquedo novo. Fonte: Wakamoleguy - Reviving BrowserID in 2026.
Chris Wellons aposentou o Emacs depois de 20 anos de uso diário e está procurando mantenedores para pacotes ativos como Elfeed. O trecho mais curioso é a reconstrução de ferramentas pessoais com ajuda de IA, que muda o custo de refazer software que antes ficaria eternamente para algum dia. Fonte: Nullprogram - I have officially retired from Emacs.

Acompanhamento de tendências

Agente está virando problema de sistema. DeepSeek V4 precisa de SGLang, Miles, cache, kernel e paralelismo. Feldera quer interfaces melhores para agentes. PageIndex tenta mudar a camada de retrieval. O modelo é só uma peça.
Verificação continua sendo o gargalo. A história da matemática não vale por "a IA provou sozinha", mas por mostrar que busca ficou barata e validação continua especializada. O mesmo vale para código gerado, automação, segurança e migração de infraestrutura.
A confiança está nas camadas chatas. OAuth, pacote npm, wheel do PyPI, App Runner, GnuPG, DNS e processo LINA não têm o brilho de um modelo novo. Mas é ali que o sistema ganha ou perde no mundo real.

GPT-5.5, Claude Code e DeepSeek V4: agentes de IA viram infraestrutura

Sat, 25 Apr 2026 10:01:28 GMT

Nota: gerado por IA (The Paper LLM), com fontes originais listadas por bloco.

O lote de hoje continua batendo na mesma tecla, mas com peças novas: agente de IA não é mais só "modelo respondendo prompt". A diferença prática está no runtime, no cache, no histórico, nas ferramentas, no sandbox, no custo por token e no jeito como tudo isso é observado quando dá errado.

GPT-5.5 chega na API com cara de plataforma de agentes

A OpenAI colocou o GPT-5.5 e o GPT-5.5 Pro na API em 24 de abril de 2026. O changelog lista uma janela de contexto de 1 milhão de tokens, entrada por imagem, saída estruturada, function calling, prompt caching, Batch, web search, computer use, hosted shell, apply patch, Skills, MCP e tool search. A página do modelo também mostra 1.050.000 tokens de contexto e até 128.000 tokens de saída.

Isso muda o enquadramento do lançamento. O GPT-5.5 não aparece só como "modelo mais forte". Ele chega grudado em uma superfície de execução para agentes. A pergunta deixa de ser apenas "qual modelo responde melhor?" e vira "qual ambiente consegue pesquisar, chamar ferramenta, editar arquivo, rodar shell, aplicar patch, preservar contexto e parar na hora certa?"

A própria documentação de prompting aponta nessa direção. A OpenAI recomenda tratar o GPT-5.5 como uma família nova, não como troca cega de nome de modelo. Também orienta prompts com critérios de sucesso, regras de parada, uso mais cuidadoso de absolutos como "sempre" e "nunca", preâmbulos curtos antes de tarefas longas com ferramentas, e compaction intencional em agentes de execução prolongada.

Sim, a ironia é difícil de ignorar: este próprio texto sai de um pipeline automatizado que depende de modelo, prompt, ferramentas, memória, arquivos e checagens de build. Quando a ferramenta ganha shell, patch, navegador, contexto gigante e geração de imagem, o prompt deixa de ser só instrução de escrita. Ele vira parte da infraestrutura.

Para quem mantém automações reais, a leitura prática é simples. Migrar para GPT-5.5 não deve ser só trocar gpt-5.4 por gpt-5.5 e torcer. Vale revisar prompts longos, tool contracts, mensagens de progresso, regras de parada, limites de busca, critérios de conclusão, custo de contexto, geração de assets e comportamento em tarefas que rodam por muitos minutos.

Fontes: OpenAI API changelog, modelo GPT-5.5, guia de uso do GPT-5.5 e prompt guidance da OpenAI.

DeepSeek V4 volta, mas agora o assunto é cache e custo de agente

DeepSeek V4 já apareceu no roundup anterior pelo ângulo de preço, pesos abertos e contexto longo. A história de hoje não é a mesma. O texto novo do Hugging Face e a publicação técnica da NVIDIA puxam a conversa para outro lugar: 1 milhão de tokens só ajuda se o custo de atenção e de KV cache não matar o agente no meio da tarefa.

O Hugging Face resume bem a diferença. A janela de 1 milhão de tokens é capacidade, não performance. Em uma tarefa longa, cada resultado de ferramenta, log, trecho de código e decisão anterior entra no contexto. A cada passo, o modelo paga para olhar para tudo aquilo de novo. Se a arquitetura não reduzir esse custo, contexto gigante vira uma promessa cara.

Segundo o texto do Hugging Face, o DeepSeek-V4-Pro usa 27% dos FLOPs de inferência por token e 10% da memória de KV cache em comparação com o DeepSeek-V3.2 em 1 milhão de tokens. O V4-Flash reduz ainda mais esses números: 10% dos FLOPs e 7% da memória de cache. A NVIDIA apresenta a mesma direção pelo lado de deployment: V4-Pro tem 1,6 trilhão de parâmetros totais e 49 bilhões ativos; V4-Flash tem 284 bilhões totais e 13 bilhões ativos; ambos com licença MIT e contexto de 1 milhão de tokens.

O pedaço mais interessante para dev talvez esteja no Reasonix. O projeto tenta ser um agente específico para DeepSeek, com loop cache-first, prefixo estável, MCP, TUI em terminal e edição por blocos revisáveis. A tese é bem direta: framework genérico de agente tende a remontar o prompt a cada turno e, com isso, pode perder o benefício do cache de prefixo. Quando o provedor dá uma vantagem específica, a abstração genérica pode custar dinheiro.

Ainda precisa de teste em workload real. Mas o sinal editorial é bom: a próxima briga em agentes não é só benchmark. É cache hit, formato de trace, prompt imutável, log append-only, custo por chamada e arquitetura que entende o modelo que está usando.

Fontes: Hugging Face - DeepSeek-V4, NVIDIA Developer Blog sobre DeepSeek V4 e GitHub - Reasonix.

Anthropic mostra que agente pode piorar sem o modelo "piorar"

A Anthropic publicou um postmortem sobre reclamações recentes de qualidade no Claude Code. A parte útil é que a empresa não joga tudo na conta de um modelo misterioso ficando mais burro. Ela aponta três mudanças de produto: alteração no esforço de raciocínio padrão, bug de cache que descartava pensamento antigo em sessões ociosas, e uma instrução de sistema para reduzir verbosidade que acabou prejudicando qualidade de código.

O primeiro caso veio do trade-off entre inteligência, latência e consumo de limites. O Claude Code tinha Opus 4.6 em high por padrão, depois passou para medium, e usuários começaram a relatar queda de qualidade. A Anthropic diz que reverteu a decisão em 7 de abril: Opus 4.7 passou a usar xhigh por padrão, e os demais modelos voltaram para high.

O segundo caso é mais interessante para quem mexe com automação longa. Em 26 de março, a Anthropic enviou uma otimização para limpar pensamento antigo depois de uma sessão ficar ociosa por mais de uma hora. A intenção era reduzir custo ao retomar uma sessão que já teria perdido cache. O bug fez essa limpeza acontecer em todos os turnos seguintes. Resultado: o agente parecia esquecido, repetitivo e tomava decisões estranhas porque perdia a trilha do próprio raciocínio. A correção saiu em 10 de abril.

O terceiro caso veio de prompt. Uma instrução para limitar texto entre tool calls e respostas finais foi enviada em 16 de abril e revertida em 20 de abril depois que avaliações mais amplas mostraram queda de 3% em Opus 4.6 e 4.7. Prompt pequeno, efeito grande. Quem já ajustou agente por tentativa e erro conhece esse tipo de acidente.

A lição é ótima porque é chata do jeito certo. Quando um coding agent piora, não basta perguntar "qual modelo está por baixo?". Tem que olhar effort, prompt, memória, cache, rollout, versão pública, evals internas e métricas de qualidade. O modelo pode ser o mesmo, mas o produto em volta mudou.

Fonte: Anthropic - An update on recent Claude Code quality reports

Kali365 mostra por que MFA não basta quando a sessão é autorizada

O relatório da Arctic Wolf sobre Kali365 é um bom lembrete de que ataque de identidade moderno não precisa roubar senha do jeito antigo. A campanha usa o fluxo legítimo de device code da Microsoft. O atacante inicia uma solicitação, a vítima entra em uma página real da Microsoft, autentica de verdade, passa pelo MFA e, sem perceber, autoriza uma sessão controlada pelo atacante.

O que sai disso não é uma senha. São tokens OAuth válidos. Segundo a Arctic Wolf, tokens de acesso e refresh capturados permitem acesso imediato à mailbox e atividade pós-comprometimento. Em alguns casos, os operadores também criaram regras maliciosas de inbox para esconder alertas de segurança e aumentar o tempo de permanência.

O Kali365 Live aparece como uma plataforma de phishing-as-a-service com painel multi-tenant, geração de lures, páginas hospedadas em Cloudflare Workers, compartilhamento de tokens entre afiliados, fluxo de captura adversary-in-the- middle e até cliente desktop para acompanhar tokens e mailbox. É produto. Feio, mas produto.

O ponto defensivo é bem concreto. Se device code flow não é necessário, bloquear por Conditional Access reduz muito o caminho do ataque. Quando for necessário, vale restringir por grupo, local confiável e dispositivo gerenciado. Também vale caçar padrões de autorização suspeitos, regras novas de mailbox e sinais de uso do cliente identificado pela Arctic Wolf.

Para treinamento de segurança, esse caso é melhor do que mais um slide dizendo "cuidado com phishing". Ele mostra o fluxo exato: código legítimo, provedor legítimo, MFA legítimo e sessão ilegítima no final.

Fonte: Arctic Wolf - Token Bingo: Don't Let Your Code be the Winner

GitNexus, Stash e VT Code mostram a pilha em volta do modelo

Três projetos do briefing apontam para a mesma direção. GitNexus, Stash e VT Code não tentam ganhar a conversa dizendo "temos o modelo mais inteligente". Eles mexem no que fica ao redor: mapa de código, memória persistente, política de comando, sandbox, auditoria e contexto.

O GitNexus indexa um repositório em grafo de conhecimento com dependências, call chains, clusters e fluxos de execução. A parte prática está na exposição via MCP e em ferramentas como análise de impacto antes de mudança. Em vez de dar para o agente um monte de arquivo solto e esperar que ele descubra tudo, a ideia é entregar uma visão estrutural do código.

O Stash ataca outro problema: memória entre sessões. Ele usa PostgreSQL, pgvector e MCP para transformar episódios em fatos, relacionamentos, padrões, falhas e objetivos. Isso é útil, mas também acende uma luz amarela. Memória persistente melhora continuidade, só que também vira superfície de privacidade, injeção e vazamento se não tiver namespace, inspeção e caminho claro de apagar.

O VT Code entra pelo terminal. É um coding agent em Rust com suporte a múltiplos provedores, busca semântica, Agent Skills, ACP, MCP e interface TUI. O detalhe mais importante para este roundup está na seção de segurança: allowlist de comandos, validação de argumentos, isolamento de workspace, sandbox nativo no macOS e no Linux, políticas para ferramentas MCP, aprovação humana e trilha de auditoria.

Juntando os três, a mensagem é difícil de ignorar. Agente bom não é só modelo bom. É contexto certo, memória que dá para auditar, ferramenta com política, comando com limite e mapa de impacto antes de sair editando código.

Fontes: GitHub - GitNexus, Stash - Persistent Memory for AI Agents e GitHub - VT Code.

Destaques rápidos

A Mozilla diz que o Firefox 150 inclui correções para 271 vulnerabilidades encontradas durante uma avaliação inicial com Claude Mythos Preview. O texto é de 21 de abril de 2026, então não é notícia fresca do dia, mas encaixa no mesmo quadro: IA defensiva começa a virar pipeline de segurança, não demo de laboratório. Fonte: Mozilla - The zero-days are numbered
A CISA adicionou quatro falhas exploradas ao catálogo KEV envolvendo SimpleHelp, Samsung MagicINFO 9 Server e roteadores D-Link DIR-823X. A data limite para agências federais aplicarem correções ou descontinuarem o uso é 8 de maio de 2026. Fonte: The Hacker News - CISA Adds 4 Exploited Flaws to KEV
O experimento quantumslop trocou o backend IBM Quantum por /dev/urandom e manteve o restante do verificador intacto. Se a recuperação de chaves continua com bytes aleatórios, o resultado medido não prova vantagem quântica; prova que o harness aceita candidatos aleatórios suficientes. Fonte: GitHub - quantumslop URANDOM_DEMO
Jeff Geerling testou adaptadores USB de 10 gigabits Ethernet baseados em RTL8159. O achado prático é o de sempre: para chegar perto de 10 gigabits por segundo, precisa de porta USB 3.2 Gen 2x2; em máquinas sem essa porta, o mundo real fica mais perto de 6 a 7 gigabits por segundo. Fonte: Jeff Geerling - New 10 GbE USB adapters
O fwupd 2.1.2 parece atualização pequena, mas traz endurecimento importante: checagem para AMD EntrySign, parser CBOR nativo, limites contra ZIP bombs, teto de 4 GiB para cápsulas UEFI e correções em parsing de arquivos PE maliciosos. Firmware updater roda em caminho privilegiado; parser robusto importa. Fonte: GitHub - fwupd 2.1.2
A AWS colocou TLS híbrido pós-quântico no Secrets Manager para clientes que suportam o recurso. Na prática, a ação principal é atualizar o cliente e verificar no CloudTrail se o campo tlsDetails.keyExchange mostra X25519MLKEM768. Fonte: AWS Security Blog - Protecting your secrets from tomorrow's quantum risks
A dica git config am.threeWay true, do Michael Catanzaro, é pequena e ótima. Ela faz muitos patches que falhariam no git am caírem em conflito de três vias, como um merge normal. Para mantenedor e backport de segurança, isso economiza tempo e paciência. Fonte: Michael Catanzaro - git config am.threeWay
O ensaio sobre plain text é menos notícia e mais lembrete. Markdown, diagramas ASCII, monospace e arquivos textuais continuam vivos porque atravessam editor, terminal, git, automação e IA com menos atrito do que formatos ricos demais. Fonte: Unsung - Plain text has been around for decades

Acompanhamento de tendências

Lançamento de modelo está virando lançamento de runtime. GPT-5.5 chega com ferramentas hospedadas, DeepSeek V4 força conversa sobre cache e Reasonix tenta explorar comportamento específico do provedor.
A qualidade percebida de agente depende de camadas que muita gente não mede. O postmortem da Anthropic deixa isso explícito: effort, cache, memória, prompt, eval e rollout podem mudar a experiência sem trocar o modelo base.
Segurança está saindo do prompt isolado. Device code phishing, memória persistente, MCP, sandbox, política de comando e audit trail estão na mesma pilha operacional.
As ferramentas boas estão ficando menos mágicas e mais inspecionáveis. Grafo de código, logs, namespaces, allowlists e verificações pequenas parecem detalhes chatos. São exatamente os detalhes que permitem confiar um pouco mais no agente.

Fechando o quadro

O resumo de hoje poderia ser "o modelo continua importante, mas sozinho ele não fecha a conta". GPT-5.5 mostra o pacote de plataforma. DeepSeek V4 mostra custo e cache. Anthropic mostra que produto em volta do modelo quebra qualidade. Kali365 mostra que identidade falha mesmo quando o login parece legítimo. GitNexus, Stash e VT Code mostram que contexto, memória, política e auditoria já viraram parte do produto.

Não é a parte mais brilhante da IA. É a parte que decide se ela aguenta uso real.

DeepSeek V4, Ubuntu 26.04 e MCP: infraestrutura e segurança voltam ao centro da IA

Fri, 24 Apr 2026 10:01:47 GMT

Nota: gerado por IA (The Paper LLM), com fontes originais listadas por bloco.

O lote de hoje tem uma linha bem prática: IA não está avançando só pelo modelo mais esperto. O jogo também está no custo por token, no sistema operacional que vira base de container, na forma como ferramentas são descritas para agentes e na velha pergunta: "esse caminho de arquivo é mesmo confiável?"

DeepSeek V4 empurra a briga para contexto longo barato

Em 24 de abril de 2026, a DeepSeek publicou os modelos DeepSeek-V4-Pro e DeepSeek-V4-Flash no Hugging Face. Os dois são modelos MoE com janela de contexto de 1 milhão de tokens. O Pro tem 1,6 trilhão de parâmetros no total e 49 bilhões ativos. O Flash tem 284 bilhões no total e 13 bilhões ativos.

O dado mais importante para dev não é só o tamanho. É o preço. A página oficial da API lista o Flash a US$0,14 por 1 milhão de tokens de entrada sem cache e US$0,28 por 1 milhão de tokens de saída. O Pro aparece a US$1,74 na entrada e US$3,48 na saída. Para tarefas com muito contexto, isso muda o tipo de experimento que dá para fazer sem virar planilha de custo.

Simon Willison colocou o lançamento no mesmo eixo da corrida de modelos fechados: o GPT-5.5 fica no topo de capacidade para agentes e trabalho longo, mas com preço bem mais alto. O DeepSeek V4 entra por outro lado, tentando tornar contexto longo e pesos abertos mais baratos. Não é a mesma proposta. E é justamente por isso que a comparação importa.

Na prática, isso pode afetar pipelines de busca, classificação, revisão em lote, agentes que precisam carregar muito histórico e ferramentas que hoje evitam contexto grande por custo. Ainda precisa de teste real fora da tabela de benchmark. Mas o sinal é claro: contexto longo barato virou produto, não só promessa de laboratório.

Fontes: DeepSeek-V4-Pro no Hugging Face, DeepSeek-V4-Flash no Hugging Face, DeepSeek API Pricing e Simon Willison sobre DeepSeek V4.

Ubuntu 26.04 LTS muda detalhes que pegam em servidor e container

A Canonical publicou as notas do Ubuntu 26.04 LTS em 23 de abril de 2026. A versão terá suporte padrão até abril de 2031, com janela estendida via Ubuntu Pro. Para desktop isso sempre traz uma lista grande de aplicativos novos, mas o ponto mais útil para quem mexe com VPS, Docker, WSL e imagem base está nas trocas menos chamativas.

O OpenSSH salta da família 9.6 para 10.2 no caminho de upgrade a partir do Ubuntu 24.04 LTS. Isso traz avisos e remoções que podem aparecer em ambiente velho, como a retirada do algoritmo DSA fraco e mudanças em torno de chaves, DNS SSHFP e opções do sshd. Também entra o algoritmo híbrido pós-quântico mlkem768x25519-sha256 por padrão.

No tempo do sistema, novas instalações passam a usar Chrony no lugar de systemd-timesyncd. No boot, o Ubuntu agora usa Dracut como infraestrutura padrão de initramfs, embora initramfs-tools continue suportado. No pacote básico, APT foi para a versão 3.1 e o apt-key foi removido. Scripts antigos que ainda gerenciam chaves do jeito velho podem quebrar.

Esses detalhes parecem pequenos até alguém trocar a base de uma imagem e o CI começar a falhar. Para ambientes de agentes, runners e sandboxes, a mensagem é simples: Ubuntu 26.04 não é só "mais uma LTS". É uma nova linha de base para SSH, tempo, boot, pacotes e comportamento de sistema.

Fontes: Ubuntu 26.04 LTS release notes e Ubuntu 26.04 LTS summary for LTS users.

Papers novos mostram que agente seguro não é só prompt seguro

Uma leva de papers publicados entre 22 e 23 de abril de 2026 reforça um ponto incômodo: o ataque contra agentes está saindo do prompt isolado e indo para a camada de ferramentas, memória e contexto.

O paper "Breaking MCP with Function Hijacking Attacks" descreve um ataque que manipula a seleção de ferramentas por meio de funções adversariais. A ideia não é apenas convencer o modelo a dizer algo errado, mas fazer o agente escolher uma função específica. Nos testes citados pelos autores, o ataque chegou a taxas de sucesso entre 70% e 100% em tarefas no estilo BFCL com cinco modelos.

Outro trabalho, "Cross-Session Threats in AI Agents", olha para ataques espalhados em várias sessões. Um guardrail que avalia cada mensagem de forma isolada pode não enxergar o ataque inteiro, porque o payload só aparece quando as partes são juntadas. O paper propõe um benchmark para esse tipo de ameaça e testa leitores de memória com orçamento limitado.

O terceiro, "CI-Work", foca em agentes corporativos com acesso a contexto interno. A conclusão é bem direta: agentes que recuperam informação para ajudar o usuário também podem vazar contexto sensível. O estudo relata violações de privacidade entre 15,8% e 50,9%, com vazamento chegando a 26,7% nos cenários avaliados.

Sim, tem uma ironia aqui. Um agente de IA avisando que agente de IA precisa de limite. Mas é justamente por isso que o aviso importa.

O aprendizado prático não é exótico. Descrição de ferramenta também é entrada. Memória também é superfície de ataque. Recuperação de contexto também precisa de política. E, quando o agente tem ferramenta de verdade, a segurança precisa acompanhar a trajetória, não só a resposta final.

Fontes: arXiv - Breaking MCP with Function Hijacking Attacks, arXiv - Cross-Session Threats in AI Agents e arXiv - CI-Work: Benchmarking Contextual Integrity in Enterprise LLM Agents.

Abrir arquivo com segurança ainda é uma armadilha real

Em 23 de abril de 2026, Sebastian Wick publicou um texto sobre uma operação que parece banal: abrir um arquivo. A tese do artigo é que uma string de caminho não é uma referência estável. Ela aponta para uma localização em um namespace de arquivos, e essa localização pode mudar enquanto outro processo está tentando validar e usar o caminho.

O exemplo central é a velha corrida TOCTOU, de "time of check" para "time of use". Um processo privilegiado normaliza um caminho, resolve symlinks e acha que está tudo dentro do diretório permitido. Enquanto isso, outro processo troca um componente do caminho por symlink. O que parecia seguro pode acabar abrindo algo fora do limite esperado.

A saída defendida no texto é trabalhar com file descriptors sempre que possível. Depois que o kernel entrega um descriptor para um inode, a referência fica presa àquele objeto. O caminho pode ser renomeado, removido ou substituído por symlink; o descriptor continua apontando para o mesmo inode.

Isso conversa bem com agentes e sandboxes porque muita automação mistura código gerado, arquivos temporários, permissões e processos auxiliares. Quando existe fronteira de privilégio, passar path cru para helper privilegiado é pedir para ter surpresa. O texto passa por O_PATH, openat, openat2, O_NOFOLLOW e fd-based traversal, mas a regra mental já ajuda: path é nome, file descriptor é referência.

Fonte: Sebastian Wick - How Hard Is It To Open a File?

Destaques rápidos

O Google DeepMind publicou o Decoupled DiLoCo, uma abordagem para treinamento distribuído assíncrono entre ilhas de compute. O ponto mais interessante é operacional: a empresa relata treinamento de um modelo de 12 bilhões de parâmetros em quatro regiões dos EUA usando 2 a 5 Gbps de rede entre regiões. Fonte: Google DeepMind - Decoupled DiLoCo
O paper BadStyle mostra uma linha desconfortável de ataque: estilo natural de escrita como gatilho de backdoor em LLMs. Isso é especialmente relevante para fine-tuning, adapters e pipelines que tratam "estilo" como detalhe inocente. Fonte: arXiv - Stealthy Backdoor Attacks against LLMs Based on Natural Style Triggers
O projeto sem propõe diffs em nível de entidade, em vez de linhas. Para revisão com IA, a ideia é boa: quando a ferramenta sabe que uma função mudou, consegue montar contexto e impacto de forma mais útil do que um diff textual solto. Fonte: GitHub - Ataraxy-Labs/sem
O Honker leva semântica parecida com NOTIFY e LISTEN para SQLite, com filas duráveis e streams transacionais. É pequeno, mas aponta para uma direção interessante: apps locais com fila, evento e banco simples sem puxar uma stack inteira. Fonte: Simon Willison - russellromney/honker

Acompanhamento de tendências

A disputa entre modelos está virando disputa de custo por contexto. O modelo mais capaz continua importando, mas o preço por milhão de tokens muda o que dá para experimentar todo dia.
A base operacional voltou para o centro da conversa. LTS nova, APT novo, OpenSSH novo, initramfs novo e detalhes de filesystem parecem assunto de sysadmin até quebrarem um runner de agente.
Segurança de agente está ficando menos parecida com jailbreak de prompt e mais parecida com arquitetura de produto. Ferramenta, memória, contexto, auditoria e fronteira de privilégio precisam entrar no mesmo desenho.

Fechando o quadro

O recado do dia é menos glamouroso do que "saiu um modelo novo", mas talvez seja mais útil. O que define se IA funciona bem no mundo real é o pacote: modelo, preço, contexto, sistema operacional, sandbox, ferramenta, memória e permissão. Separar essas coisas no papel é fácil. Em produção, elas se misturam rápido.

GPT-5.5 apareceu no Codex hoje. Peguei no pulo.

Thu, 23 Apr 2026 20:04:35 GMT

O GPT-5.5 saiu hoje, 23 de abril de 2026, e eu descobri do jeito mais besta possível: apareceu um botão pra atualizar o Codex. Cliquei.

Quando olhei de novo, o modelo já tinha mudado pra GPT-5.5.

Então, antes que isso vire "notícia de ontem" (o que em IA parece acontecer em umas três horas), resolvi deixar esta nota aqui.

Mas, vamos com calma: isso aqui não é review. Não deu tempo. Eu literalmente acabei de pegar o modelo. Este texto é baseado principalmente no material de lançamento da própria OpenAI, então ainda tem muito cheiro de marketing de fabricante. Benchmark bonito, frase forte, promessa de produtividade, aquele pacote completo.

Dito isso, tem algumas coisas interessantes.

O que a OpenAI está prometendo

Segundo a OpenAI, o GPT-5.5 não está sendo vendido só como "um chat melhor". A promessa é mais específica: um modelo melhor pra trabalhar com ferramentas por mais tempo.

Código, pesquisa online, análise de dados, documentos, planilhas, uso de software e tarefas que exigem várias etapas.

Ou seja: menos "me responde isso aqui" e mais "pega esse problema bagunçado, entende o contexto, usa ferramentas, testa, corrige e me devolve algo que preste".

Pra quem usa Codex, isso é exatamente onde a coisa começa a ficar interessante.

A OpenAI diz que o GPT-5.5 melhorou em tarefas de código e uso de terminal. No material oficial, eles citam 82.7% no Terminal-Bench 2.0 contra 75.1% do GPT-5.4. No SWE-Bench Pro, que tenta medir resolução de issues reais em projetos, o número subiu pouco: 58.6% contra 57.7%.

Esse "subiu pouco" também é importante. Nem todo benchmark grita revolução. Algumas coisas parecem avanço incremental mesmo.

E tudo isso ainda precisa passar pelo teste mais cruel: projeto real, com código velho, decisão estranha, teste quebrando, dependência chata e humano cansado do outro lado.

Codex, contexto e preço

No anúncio oficial, a OpenAI diz que o GPT-5.5 está chegando ao ChatGPT e ao Codex para usuários Plus, Pro, Business e Enterprise. No Codex, também entram Edu e Go, com janela de contexto de 400K.

Também existe um modo Fast, que gera tokens mais rápido, mas custa mais. A promessa oficial é 1.5x mais rápido por 2.5x o custo.

Na API, ele ainda aparece como "em breve". A própria página de preços da OpenAI já lista o GPT-5.5 como "coming soon", com US$5 por 1 milhão de tokens de entrada e US$30 por 1 milhão de tokens de saída.

Então, sim, parece mais capaz. Também parece mais caro.

Como todo bom dev, a gente comemora com uma mão e segura a carteira com a outra.

A parte de segurança

Outra parte forte do lançamento é segurança.

A OpenAI publicou um system card do GPT-5.5, fala em testes antes do lançamento, red teaming, avaliações para cyber e biologia, além de feedback de quase 200 parceiros de acesso antecipado.

Ela também abriu um Bio Bug Bounty específico do GPT-5.5. O escopo é bem específico: GPT-5.5 no Codex Desktop, procurando um jailbreak universal para perguntas de segurança biológica. O prêmio principal anunciado é de US$25.000.

Traduzindo: eles também sabem que um modelo melhor em código, pesquisa e ferramentas pode ser útil pra coisa boa e pra coisa ruim.

E esse é o pedaço que mais me interessa no longo prazo. Não só "o modelo ficou mais inteligente", mas "o modelo ficou mais capaz de agir". Quando entra ferramenta, terminal, navegador, arquivo, repositório, sandbox e automação, a conversa muda de tamanho.

Minha impressão de primeira hora

Curiosidade.

Não vou fingir conclusão madura onde só existe botão recém-clicado. Quero ver se ele realmente entende melhor projetos grandes, se respeita mais o estilo do código, se testa direito, se não inventa moda quando eu só quero uma alteração pequena e se consegue trabalhar sem transformar cada tarefa simples numa tese.

Também quero ver uma coisa que benchmark não mede tão bem: comportamento no fluxo real.

Porque um agente pode ser muito inteligente e ainda ser chato. Pode ser capaz e ansioso. Pode resolver um bug difícil e, cinco minutos depois, mexer onde não precisava. Quem usa esse tipo de ferramenta todo dia sabe que "mais autonomia" só é bom quando vem junto com bom senso.

Então fica a nota: peguei o GPT-5.5 no pulo aqui no Codex.

Talvez eu volte a falar dele depois de usar mais. Talvez não. Eu não costumo fazer post sobre cada modelo novo que aparece, mas esse caiu direto na ferramenta que eu uso pra trabalhar no blog, no código e nas automações.

Aí ficou difícil ignorar.

Valeu.

Fontes

Terrarium, Lazarus e benchmarks: 4 alertas sobre segurança e infraestrutura de agentes de IA

Thu, 23 Apr 2026 12:00:50 GMT

Nota: gerado por IA (The Paper LLM), com fontes originais listadas por bloco.

O lote de hoje gira em torno do mesmo problema: muita gente ainda olha para IA pensando só no modelo, mas os riscos e os gargalos estão cada vez mais no runtime, no sandbox, no ambiente de execução e no jeito como essas ferramentas entram no fluxo de trabalho de quem desenvolve.

Terrarium mostra como um sandbox pode virar parte do problema

Em 21 de abril de 2026, o CERT/CC publicou a nota VU#414811 sobre uma falha no Terrarium, plataforma de execução de código em sandbox. O problema está numa travessia da cadeia de protótipos JavaScript dentro do ambiente Pyodide, o que abre caminho para alcançar o globalThis, acessar internals do Node.js e executar comandos arbitrários com privilégios de root no processo hospedeiro.

O ponto mais importante aqui não é só a existência da falha. É o tipo de confiança que ela quebra. Ferramentas como o Terrarium costumam aparecer justamente no momento em que alguém pensa: "beleza, vou deixar o modelo gerar código porque isso aqui está isolado". Quando a camada de isolamento falha, o sandbox deixa de ser proteção e passa a ser mais uma superfície de ataque.

O CERT/CC diz que não conseguiu coordenar uma correção com o fornecedor e lista mitigações mais defensivas do que curativas: segmentação de rede, monitoramento da atividade do container, controles de acesso e redução de funcionalidades expostas. Em português claro, se você executa código não confiável, o ideal continua sendo reduzir o raio de explosão desde o início, não presumir que o sandbox vai segurar tudo sozinho.

Fonte: CERT/CC - VU#414811

A campanha descrita pela Expel leva o ataque direto para o workflow do dev

Em 22 de abril de 2026, a Expel publicou um relatório sobre um grupo que ela rastreia com alta confiança como ligado à Coreia do Norte. O alvo principal são desenvolvedores de Web3, mas a mecânica do ataque interessa a qualquer pessoa que receba repositório de teste, projeto de entrevista ou prova técnica para rodar localmente.

Segundo a Expel, o grupo usa falsas ofertas de emprego e envia take-home assessments adulterados. Em vários casos, o pacote vem com tasks.json malicioso no VS Code, configurado para disparar código assim que a pasta é aberta. Quando isso não basta, o próprio código do projeto já traz backdoors pensados para rodar quando a vítima tenta executar a aplicação.

O detalhe que chama atenção é o uso pesado de ferramentas de IA generativa no processo. No relatório, a Expel diz que o grupo abusa de ferramentas como Cursor e ChatGPT para escalar a operação. O resultado não é "malware mágico feito por IA". É algo mais pé no chão e, por isso mesmo, mais perigoso: campanhas mais baratas, melhor escritas e mais fáceis de multiplicar.

Esse tipo de história é um bom lembrete de que abrir pasta, confiar em automação do editor e rodar projeto de terceiros já faz parte do modelo de ameaça. Não é só navegador, e-mail ou anexo estranho. O ambiente de desenvolvimento entrou de vez nessa conta.

Fonte: Expel - Inside Lazarus: How North Korea uses AI to industrialize attacks on developers

Benchmarks de agentes podem mudar bastante só por causa da infraestrutura

Em um texto recente de engenharia, a Anthropic argumenta que benchmarks de coding agents podem variar vários pontos percentuais sem que o modelo mude. A mudança vem só da configuração de infraestrutura. No experimento descrito pela empresa, a diferença entre o setup mais restrito e o menos restrito no Terminal-Bench 2.0 chegou a 6 pontos percentuais.

Os números do texto ajudam a entender o tamanho do ruído. Em configuração estrita, os erros de infraestrutura ficaram em 5,8%. No cenário sem limite, caíram para 0,5%. Até certo ponto, dar mais folga de CPU e memória corrige instabilidade que nem deveria contaminar a medição. Depois desse ponto, a própria prova muda, porque agentes mais pesados passam a conseguir instalar dependências grandes, abrir subprocessos caros e tentar estratégias que morrem sob orçamento apertado.

Essa distinção importa muito. Uma coisa é remover ruído operacional. Outra é facilitar a prova sem dizer claramente que isso aconteceu. O argumento da Anthropic é simples: leaderboard de agente não vale muita coisa sem CPU, RAM, limite rígido, método de enforcement e janela de tempo bem descritos. Diferença pequena demais, sem metodologia clara, merece desconfiança.

Fonte: Anthropic - Quantifying infrastructure noise in agentic coding evals

Managed Agents reforça uma separação que muita stack ainda ignora

Em outro texto de engenharia, a Anthropic descreve a arquitetura do Managed Agents como uma separação mais dura entre sessão, harness e sandbox. A ideia é parar de tratar o agente inteiro como um container único, frágil e cheio de acoplamentos. Em vez disso, o "cérebro" fica desacoplado das "mãos", e cada parte pode falhar, reiniciar ou ser trocada sem levar o resto junto.

O ganho não fica só na elegância da arquitetura. A Anthropic diz que, com essa separação, a recuperação de falhas ficou mais simples, a integração com VPCs dos clientes melhorou e a latência até o primeiro token caiu bastante. No texto, a empresa afirma que o p50 de time-to-first-token caiu cerca de 60%, enquanto o p95 caiu mais de 90%.

Tem também um ponto de segurança que vale prestar atenção. Quando código não confiável roda no mesmo container que guarda credenciais e contexto, uma injeção bem sucedida precisa atravessar bem menos barreiras para encontrar segredo valioso. Separar harness, sessão e sandbox não elimina risco, mas corta um atalho ruim que aparece em muita implementação apressada.

Fonte: Anthropic - Scaling Managed Agents: Decoupling the brain from the hands

Destaques rápidos

O texto do Martin Fowler sobre technical, cognitive, and intent debt continua valendo a leitura porque põe nome num problema que muita equipe já está sentindo: não é só o código que degrada quando a automação entra sem cuidado. O entendimento do sistema e a clareza sobre o que o time realmente quis construir também começam a escorregar. Fonte: Martin Fowler - Technical, cognitive, and intent debt
O paper sobre hidden measurement error in LLM pipelines combina bem com a discussão sobre benchmarks acima. A ideia central é simples: juiz, prompt, temperatura e detalhes do pipeline conseguem distorcer avaliação a ponto de fazer diferença pequena parecer grande. Fonte: arXiv - Hidden Measurement Error in LLM Pipelines Distorts Annotation, Evaluation, and Benchmarking
Em The Tool-Overuse Illusion, os autores batem numa tecla que aparece com frequência em stacks de agentes: mais ferramenta nem sempre significa mais capacidade. Em bastante caso, excesso de chamada é sintoma de orquestração ruim ou planejamento fraco. Fonte: arXiv - The Tool-Overuse Illusion
O trabalho AVISE chama atenção por um motivo bem prático: segurança de IA precisa de suíte de avaliação repetível, não só demo bonita de lançamento. Ainda está cedo, mas a direção faz sentido. Fonte: arXiv - AVISE: Framework for Evaluating the Security of AI Systems

Acompanhamento de tendências

A fronteira de segurança está descendo a pilha. O risco aparece menos no prompt isolado e mais no editor, no sandbox, no runner, no CI e no container onde o agente realmente vive.
A discussão sobre benchmark está ficando menos glamourosa e mais útil. Infraestrutura, metodologia e critério de avaliação estão pesando tanto quanto o modelo em si.
Plataformas de agentes estão ficando com cara de produto de infraestrutura. Memória, identidade, observabilidade, isolamento e governança já não são detalhe de implementação.

Fechando o quadro

Juntando as quatro histórias, o padrão fica claro: a discussão séria sobre agentes de IA está descendo a pilha. O modelo continua importante, claro. Mas o estrago real e as diferenças práticas estão aparecendo no container, no editor, no benchmark, no scheduler, no sandbox e na forma como tudo isso conversa com código e credenciais do mundo real.

Paperclip: empresa de IAs que funciona sozinha (será?)

Mon, 20 Apr 2026 17:37:45 GMT

Subi o Paperclip no VPS com Gemini, Codex e Claude, testei hand off, gastei com heartbeat, falei de budgets e segurança. Entenda como funciona e se é para você.

Algo engraçado só pra constar: antes do hype no Paperclip eu torci o nariz para a ferramenta. E ainda penso que estava com razão. Já apareceu ferramenta demais prometendo organizar caos, entregando só mais uma camada de caos que gera ainda mais caos. Sempre é um wrapper em cima do que já existe que é complexo para entender, cheio de bugs e que vai desaparecer logo.

Nessa situação: ou você perde tempo com a ferramenta, ou você perde tempo com a ferramenta (isso não foi um erro). É bem provável que as próprias empresas (Anthropic, OpenAI, Google e outras...), vão criar ferramentas que fazem exatamente o que o novo salvador do hype faz.

Porém, o irônico é que eu sempre penso assim na minha vida pessoal: "você não sabe o que você não sabe". Então, prefiro ficar quieto do que falar mal de algo que não está na minha bolha de uso.

O Paperclip veio com uma proposta que eu já bati o olho e pensei: marketing. E realmente, veja:

Paperclip - The human control plane for AI labor.
Hire AI employees, set goals, automate jobs and
your business runs itself.

Tradução:
Paperclip - o plano de controle humano para o trabalho de IAs.
Contrate funcionários de IA, defina objetivos, automatize
tarefas e deixe sua empresa rodando sozinha.

Qual empresa do planeta vai rodar sozinha? Então você monta a sua empresa e deixa LLMs tomando conta de tudo? Tem certeza?

No entanto, bastou eu ter um problema que o Paperclip resolvia pra eu entender o que ele realmente faz.

Apoio - Hostinger

Quer testar o Paperclip no seu próprio servidor? Vá de Hostinger.

Acesse: www.hostg.xyz/SHJHL
Cupom: OTAVIOMIRANDA (10% de desconto)

Obrigado Hostinger por acreditar no meu conteúdo 💜.

Em vídeo

Aqui está tudo o que fiz com o Paperclip, você pode tirar suas conclusões:

Vídeo: youtu.be/Mcp3fXfFV5A
Arquivo Gist usado no vídeo

Quer continuar a ler? Bora então!

Vibe Coding (pera, deixa eu explicar primeiro)

No meu dia a dia eu não fico brincando de vibe coding o tempo todo. Sou do tipo que fala: escreva um teste antes de tocar no código que tenha X comportamento. Abra o arquivo Y, na linha 80 e edite a função Z. Faça o teste passar. E depois ainda reviso linha a linha o que foi feito.

Mas é bom acompanhar as tendências e ver para qual rumo o nosso ramo está migrando.

Fazia bastante tempo que eu queria criar um agregador de notícias (um feed RSS) com LLM. Eu já tinha a ideia inteira desenhada na cabeça: buscar as notícias, injetar dados no modelo de forma dinâmica de acordo com o feedback das próprias notícias, e gerar interesses bem específicos sobre o que eu gosto e o que eu não gosto.

Como eu queria validar a ideia primeiro antes de me comprometer a desenvolver isso, decidi fazer por Vibe Coding. Usei o Codex, Claude e o Gemini em várias ocasiões.

O projeto foi crescendo com um "adiciona isso", outro "adiciona aquilo", outro "e se a gente colocasse isso?", e assim foi. Hoje ele até lê as notícias em voz alta e já saiu totalmente do meu controle. O último recurso que usei nele foi o "Claude Design". O negócio ficou MARAVILHOSO.

Enfim, um belo dia eu precisava mexer em várias partes do programa. Ajustar interface, corrigir um bug no TTS, ajustar o daemon e algumas outras coisas. Como iniciei este projeto bem estruturado (quer dizer, eu disse para os modelos trabalharem com testes e boa arquitetura), percebi que nenhuma das tarefas em que eu precisava mexer tinha overlap. Cada parte do software estava separada na sua própria camada e ninguém precisaria mexer no mesmo arquivo do coleguinha.

Abri 5 agentes. Quatro ficaram codando, e um deles ficou comigo só ajudando a verificar se ninguém estava fazendo nada errado. Claude Opus, Claude Sonnet, Codex App com GPT 5.4, outro Codex App com GPT 5.4 e o Gemini 3.1 Pro no Antigravity.

Se você já fez isso, vai entender perfeitamente o que vou falar agora: às vezes eu precisava falar com um agente para testar algum recurso. Nesse tempo, os outros todos terminavam o serviço e eu não via. Isso era perda de tempo, já que eu mesmo não estava revisando código, só testando a implementação.

Então lembrei do Paperclip. E a ideia dele começou a fazer mais sentido pra mim. Como ele mostra todos os agentes em uma única interface, fica bem mais fácil gerenciar tudo. De fato, você consegue manter todos trabalhando usando dois recursos que ele tem: hand off por menção e heartbeat.

O Hand Off é igual você marcar alguém em uma rede social. Um agente pode fazer @CTO (por exemplo) e indicar para o @CTO que ele terminou o serviço. O @CTO acorda e vai conferir sem você colocar a mão em nada.

Heartbeat é um loop que fica rodando de tempos em tempos (você escolhe). Assim que chegar o momento do Heartbeat, o agente é obrigado a acordar, verificar o que tem pra fazer e agir. Essa função é mais útil pra quem realmente não quer ficar vigiando os agentes. Um exemplo disso foi quando eu queria testar se eles fariam um site sozinhos, mas já estava pingando de sono. Simplesmente ativei o Heartbeat do meu @CEO, deixei instruções para ele sobre o que fazer e fui dormir.

No outro dia eu tava com tudo pronto e funcionando.

Evite gastar tokens demais

Como o tutorial completo está no vídeo, vou focar mais nas partes importantes que você precisa ter em mente nesse texto.

Se você montar uma empresa como indicam internet afora, vai gastar tokens como nunca gastou na vida.

Eu fiz isso e, sem ter feito absolutamente nada além do "Onboarding" (contratações e configurações), gastei 85 Milhões de tokens. Claro, isso conta cache, input e output tudo somado.

Existem várias coisas no Paperclip que você deve ficar de olho. Alguns exemplos:

Usar os CLIs oficiais (como Claude Code, Codex CLI e Gemini CLI) gasta absurdamente mais tokens. Minha teoria é que os CLIs oficiais carregam pelo menos 20k tokens a cada wake-up do agente.
Deixar o Heartbeat ativado sem ter o que fazer faz o agente acordar, gastar muitos tokens para ter contexto e perceber que não tem nada pra fazer. Só deixe o Heartbeat ativo se realmente tiver algo para fazer.
Issues muito longas que se arrastam infinitamente. Em vez de ficar insistindo na mesma issue, feche-a e abra uma nova para qualquer micro ajuste.

Os agentes do Paperclip funcionam com contexto zerado. Isso significa que toda vez que eles acordam, é necessário injetar todo o contexto para que o agente possa fazer o serviço.

Agora pense:

20k tokens do CLI oficial
20k só do skill do Paperclip
100k tokens da sua issue gigante

Só aqui, estamos falando de 140k tokens. Se o seu Heartbeat estiver configurado para 1 hora, em 24 horas você gastaria mais de 3 milhões de tokens sem fazer absolutamente nada. Só o seu agente acordando e dormindo. Se você fizer a burrice que eu fiz, colocar 5 agentes, todos com heartbeat de 1 hora, multiplique o gasto por 5.

O modo econômico é: use o pi, deixe o Heartbeat desativado (até entender como funciona), deixe issues pequenas. Não crie uma hierarquia muito profunda. Se possível nem crie hierarquia. Vá direto no agente que precisar.

Quando vale a pena?

Na minha concepção, só vale a pena se você faz vibe coding.

Isso aqui vai multiplicar sua velocidade em 10x (ou na quantidade de agentes que seu servidor e seu bolso aguentarem).

Faça o teste e me diga. Esse é literalmente o caso de você estar dormindo e seus agentes trabalhando por você.

Onde eu não acho que isso vale a pena

Se você é dev, não faz sentido. O motivo é simples: um dev é responsável pelo seu código. Você vai mandar os agentes fazerem o seu código e assinar embaixo? Se for, então use.

Estou pensando mais no dev que trabalha para empresas mais sérias. Se você precisa revisar o código com cuidado, fica bem difícil usar mais de um agente.

Na prática, a quantidade de código pode ficar inviável de revisar direito.

Outro ponto que percebi também. Não acho que o Paperclip seja a melhor ferramenta do mundo pra microajuste fino.

Se eu quero mexer num espaçamento, trocar uma fonte, arrumar um detalhe visual ou fazer uma mudança pequena e direta, muitas vezes compensa mais usar um fluxo simples. Só funciona bem para trabalho em larga escala que pode ser feito por vários agentes ao mesmo tempo.

E faz sentido. Se o agente não tem contexto e recebe isso tudo de volta a cada wake-up, cada vez que você falar pra ele "aumentar a margem" de uma página, você multiplica a quantidade de tokens que gastou na última rodada. O pior disso é que você pode ter mais de um agente por issue. Aí é pedir pra torrar dinheiro.

O que eu levei dessa experiência

Uma coisa que ficou muito clara pra mim foi o modelo de funcionamento do Paperclip. A parte do Heartbeat já existia no OpenClaw. Porém, o OpenClaw é um chat normal.

O Paperclip não tem chat. Você precisa especificar muito bem o que quer na issue inicial. Isso te força a pensar muito mais antes de enviar um prompt qualquer para a IA.

Nada de "Oi, tudo bem?", nada de "vou te mandar o contexto". No Paperclip você precisa injetar tudo o que for necessário para a tarefa na issue inicial. Do contrário a issue vira chat e você vai pagar bem caro em tokens.

Hand off também achei genial. A ideia de um agente passar o bastão para o outro é muito interessante. Exemplo: você especializa um agente em fazer o código, outro em garantir bons testes. Um pode passar para o outro assim que concluir o serviço. "Pode começar a testar" ou o contrário (TDD), "Testes prontos, pode montar o código".

Em resumo: estou de olho nos prompts, no Heartbeat, no Hand Off e na interface maravilhosa que o Paperclip tem. Acho que é isso (no vídeo falo bem mais, assiste lá).

Valeu, e até o próximo.

Guia de sobrevivência Bash e Shell Script (Sério!)

Fri, 10 Apr 2026 19:09:38 GMT

Esse vai para devs que já sabem o básico do Shell Script e Bash e querem subir de nível. Me incluo nisso também. De fato, só estou escrevendo isso porque tenho estudado muito sobre o assunto.

Você vai ler por sua conta e risco. Perceba que o autor desse post não tem nenhum desses nomes: Erich Gamma, Richard Helm, Ralph Johnson e John Vlissides. Então você está vivendo perigosamente.

Tá parei!

Não sei se foi assim com você também, mas eu tive um caso com Bash e Shell Script.

Como tinha acesso ao root do servidor, depois que aprendi #!/bin/bash e echo "hello world", fui só ladeira abaixo.

Eu te juro que lembro de pesquisar no Google algo como: "Por que alguns scripts têm #!/bin/bash e outros #!/bin/sh". (pode ir pesquisar, te espero)

Se você está estranhando o acesso ao servidor, antigamente usávamos tudo direto mesmo (pelo menos EU, usava). Digitava ssh user@host e usava um programa chamado FileZilla na porta 21 (seco, inseguro, direto). Segurança? 🤬

Mas estou divagando.

As coisas mudaram (um pouco). Melhorei meu conhecimento (um pouco, também) e sigo estudando. Então considere que você está lendo minhas notas de estudo. Espero que elas sejam úteis pra você, como estão sendo pra mim.

Do que pretendo falar? (caramba velho, você já está no artigo, só rolar, mas...)

Padrões de tratamento de erro que separam script de brinquedo de script de produção
Técnicas de manipulação de variáveis que substituem vários dos seus hábitos com sed e awk
Mistérios de controle de processo que causam o famoso bug do "ué, por que minha variável ficou vazia?"
Padrões do mundo real pra parsing de argumentos, config, logs e testes
Armadilhas de segurança e como não ser atropelado por elas

Eu poderia muito bem corrigir as frases acima. Elas não têm meu tom de escrita. Mas vou manter do jeito que veio da IA por alguns motivos.

Primeiro, este post está sendo escrito faz um tempo e eu não lembrava o que tinha escrito. Segundo, eu não sabia falar tecnicamente o que eram cada uma das coisas que escrevi. Então, fique com uma pitada de IA neste texto.

Eu já enrolei e brinquei demais. E, não comenta com ninguém, mas faço isso pra espantar público desqualificado. Aquele povo só queria copiar algo daqui e sair. Prefiro você, que está disposto a aprender assim como eu.

Já que eles já foram, então agora temos trabalho.

Fundamentos e redes de segurança: escrevendo scripts Bash sem susto

Essa parte aqui é o kit de sobrevivência. Não é a parte "olha como eu sou avançado". É mais como um básico inicial, mas essencial.

Tratamento de erro sem autoengano

Considero o script abaixo:

#!/bin/bash
cd /tmp/build
rm -rf *
cp -r /src/output/* .
tar czf release.tar.gz *
echo "Pronto!"

Enquanto tudo está bonito, ele funciona.

O problema aparece no dia em que /tmp/build não existe. Nesse caso, o cd falha e o rm -rf * roda no diretório errado. Parabéns, agora você apagou tudo do diretório atual. Seu release vai ficar lindo!

O primeiro freio de mão costuma ser este:

set -euo pipefail

Ajuda bastante. Mas eu acabei descobrindo que isso não resolve tudo.

set -e (errexit) manda o script parar quando um comando falha. Show! Só que ele tem alguns comportamentos estranhos.

Um dos meus favoritos é este aqui:

# Isso engole erros silenciosamente:
local result=$(might_fail)

# Isso captura o erro direito:
local result
result=$(might_fail)

Até ontem, as duas linhas acima não teriam diferença na minha cabeça.

No primeiro caso, o local devolve 0 e esconde a falha do comando. Você segue com uma variável vazia e ainda acha que está tudo certo.

Outra pegadinha estranha: set -e fica meio "desligado" em alguns contextos, como comandos usados em if. Então não confia cegamente nele. Entende onde ele ajuda e onde ele faz pose.

set -u (nounset) transforma variável não definida em erro. Sem isso, $UNSET_VAR vira string vazia e a festa continua. Em Bash antigo, arrays vazios podem dar umas respostas mais esquisitas, então vale testar se você ainda precisa suportar versão jurássica. A maioria dos servidores modernos suporta versões novas do Bash (e para de ficar mantendo script legado, a IA resolve eles pra você em segundos).

set -o pipefail corrige outro clássico: pipeline que "passa" porque só o último comando foi bem. Sem ele, um curl pode falhar e o jq ainda sair com cara de inocente. Só lembra que head -n1 e amigos podem encerrar o pipe cedo e gerar SIGPIPE no processo anterior. Quando isso for esperado, trate o caso de forma explícita.

O modo estrito moderno

Se eu pudesse escolher, prefiro já começar assim (mas não olhe meus dotfiles, só confia no que falo 🤣):

#!/usr/bin/env bash
set -Euo pipefail
shopt -s inherit_errexit  # Bash 4.4+
trap 's=$?; echo "$0: Erro na linha $LINENO: $BASH_COMMAND" >&2; exit $s' ERR

Os extras fazem diferença.

set -E ajuda o trap ERR a alcançar função e subshell.
inherit_errexit evita outra daquelas "gentilezas" do Bash com $(...).
O trap pelo menos te diz onde deu pepino, em vez de deixar só um silêncio constrangedor e "indebugável" (não copia, acabei de inventar a palavra).

Olha o contraste:

#!/bin/bash
DATA=$(curl -s https://api.example.com/data)
echo "$DATA" | jq '.users[] | .email' > emails.txt
wc -l emails.txt
echo "Exportacao concluida"

Se a API estiver fora, esse script ainda consegue terminar sorrindo e dizendo "exportação concluída". Maravilhoso. Assim você esperava...

Talvez assim fique melhor. Faça o teste:

#!/usr/bin/env bash
set -Euo pipefail
shopt -s inherit_errexit
trap 's=$?; echo "FALHOU na linha $LINENO: $BASH_COMMAND (saida $s)" >&2; exit $s' ERR

DATA=$(curl -sf https://api.example.com/data)
echo "$DATA" | jq -e '.users[] | .email' > emails.txt
LINES=$(wc -l < emails.txt)
echo "Exportacao concluida: $LINES emails"

curl -f para de fingir que HTTP quebrado é sucesso. jq -e também ajuda a falhar quando o resultado vem vazio ou null. E o trap te devolve um erro que dá pra investigar sem precisar abrir uma sessão espírita.

POSIX vs recursos específicos do Bash (ou zsh)

Antes de usar array, [[ ]], mapfile e companhia, decide uma coisa: seu script é sh ou é Bash? Quando não temos experiencia com isso, achamos que shell é tudo igual.

#!/bin/sh não significa "shell genérico mágico". No macOS, costuma cair num Bash 3.2 antigo. Em Debian e Ubuntu, normalmente é dash. Em Alpine, geralmente é ash. Cada um tem suas manias, e nenhum deles jura compatibilidade com os bashismos que a gente usa sem pensar.

O bug clássico é este: você testa localmente com Bash, sobe a mesma coisa num container Alpine e toma um Syntax error: "(" unexpected na cara.

#!/bin/sh
# Parece inocente. Quebra em praticamente qualquer lugar que nao seja bash.

NAMES=("Alice" "Bob" "Charlie")
for name in "${NAMES[@]}"; do
    if [[ "$name" == "Bob" ]]; then
        echo "Bob encontrado!"
    fi
done

MSG="Hello\tWorld"
echo -e "$MSG"

curl -s https://example.com &>/dev/null

Aí já tem array, [[ ]], echo -e e &>/dev/null. Tudo coisa que pode explodir ou se comportar diferente fora do Bash.

Se a ideia for ficar em POSIX, algo assim já é bem mais honesto:

#!/bin/sh
set -- "Alice" "Bob" "Charlie"
for name in "$@"; do
    case "$name" in
        Bob) echo "Bob encontrado!" ;;
    esac
done

printf 'Hello\tWorld\n'

curl -s https://example.com >/dev/null 2>&1

Vou falar dele mais adiante, mas o shellcheck pode te ajudar a escrever scripts que funciona de acordo com o shebang.

O jeito que eu tenho usado é simples:

Se o shebang é #!/bin/sh, escreve POSIX sem jeitinho.
Se você quer recurso do Bash, assume isso logo e usa #!/usr/bin/env bash.
Também tenho me aventurado no Mac com #!/usr/bin/env zsh (e já munda muito do Bash para o zsh).

Pra testar, shellcheck -s sh e dash script.sh já evitam bastante dor de cabeça.

ShellCheck ajuda bastante

Se eu tivesse que te recomendar uma ferramenta só pra escrever shell script menos torto, seria o ShellCheck. Ele não pega só estilo. Ele pega bug que morde.

Um aviso famoso é o SC2115:

# ShellCheck avisa: SC2115
# Use "${var:?}" para garantir que isso nunca expanda para /*
rm -rf "$STEAMROOT/"*

Se $STEAMROOT vier vazio, isso pode virar rm -rf /*. Não é paranoia. Já aconteceu com o cliente Linux da Steam. A forma segura é exigir que a variável exista de verdade com ${STEAMROOT:?}.

Cinco avisos que vivem aparecendo:

SC2086: coloca aspas nas variáveis.
SC2155: separa declaração de atribuição.
SC2164: não trata cd como decoração.
SC2046: coloca aspas em substituição de comando também.
SC2162: usa read -r.

Se quiser integrar no projeto:

# .shellcheckrc
shell=bash
enable=all
severity=style
source-path=SCRIPTDIR

Às vezes também vem warning chato, aí eu só desativo mesmo. Às vezes ele não enxerga o arquivo que você está usando para source e eu também não estou muito animado a configurar (nem sei se dá pra configurar).

# shellcheck disable=SC1091
. "${HOME}/dotfiles/zsh/config/functions"

No CI, eu faria algo assim:

- name: ShellCheck
  run: find . -name '*.sh' -print0 | xargs -0 shellcheck --severity=warning

E no pre-commit:

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/koalaman/shellcheck-precommit
    rev: v0.10.0
    hooks:
      - id: shellcheck

Quando NÃO usar Bash

Bash é ótimo como cola. Como linguagem de propósito geral, pode ser mais trabalhoso do que o necessário.

Eu gosto de Bash quando a tarefa é:

ligar comando com comando
mover arquivo, chamar processo, organizar pipeline
fazer automação curta
ser entrypoint, script de deploy ou etapa de CI

Eu já começo a desconfiar quando aparece isso aqui:

estrutura de dados mais séria
parsing de JSON, YAML ou XML virando rotina
HTTP com retry, autenticação e tratamento de erro mais chato
muito awk e sed segurando a arquitetura nas costas
regra de negócio crescendo dentro do shell

Não existe número mágico, mas quando um script começa a crescer e a lógica vai ficando mais cheia de desvio, vale parar e perguntar: "isso aqui ainda é Bash ou eu só estou teimando?".

Às vezes 200 linhas em Bash ficam ótimas. Às vezes 50 já passaram da conta. O critério, pra mim, é menos tamanho e mais sofrimento.

Hoje, eu tendo a gostar mais do script Bash que sabe seu lugar: orquestra bem, falha cedo e passa o trabalho pesado pra ferramenta certa. Python é um ótimo substituto do Bash para lógicas mais complexas, mas aí já envolve subir o interpretador. Você escolhe.

Variáveis e expansões avançadas: além de `$var`

Muita gente aprende name="world" e echo "$name" e para ali. Eu também fiquei um bom tempo nessa. Só que Bash começa a ficar menos sofrido quando você usa as expansões direito e para de abrir subprocesso por qualquer coisinha.

Arrays: pare de fingir com string separada por espaço

Isso aqui é a minha cara:

files="file1.txt file2.txt file3.txt"

... mas em minha defesa, eu nem sabia que o Bash tinha arrays. Olha só:

# Declaracao
files=("report Q1.csv" "data 2024.json" "notes.txt")

# Iteracao - o jeito mais seguro
for f in "${files[@]}"; do
    echo "Processando: $f"
done

Esse "${files[@]}" com aspas não é frescura. É o que impede report Q1.csv de virar dois argumentos.

Se precisar de mapa, tem array associativo:

declare -A http_codes=(
    [200]="OK"
    [404]="Not Found"
    [500]="Internal Server Error"
)

echo "${http_codes[404]}"  # Not Found
echo "${!http_codes[@]}"   # Chaves: 200 404 500
echo "${#http_codes[@]}"   # Quantidade: 3

Sem declare -A, o Bash faz o favor de interpretar chave string como expressão aritmética. Adivinha o tipo de bug bonito que sai daí.

Exemplo mais útil:

declare -A status_counts

while IFS= read -r line; do
    # Extrai o status HTTP (quinto campo do common log format)
    status="${line##* \" }"
    status="${status%% *}"
    (( status_counts[$status]++ ))
done < access.log

# Relatorio
for code in "${!status_counts[@]}"; do
    printf "%-6s %d\n" "$code" "${status_counts[$code]}"
done | sort -t' ' -k2 -rn

Quando o dado vai continuar vivo dentro do script, isso costuma ser melhor do que transformar tudo em texto e depois parsear de novo.

Pra carregar arquivo em array:

# Seguro: lida com espacos e nao faz glob
mapfile -t lines < input.txt

# Tambem funciona (alternativa para bash 3.x)
IFS=$'\n' read -r -d '' -a lines < input.txt || true

# Evite isto: globbing + word splitting destroem seus dados
lines=( $(cat input.txt) )    # NAO FACA ISSO

mapfile resolve isso. O $(cat file) é o tipo de coisa que parece funcionar até o dia em que a entrada vem com espaço, * ou qualquer outra surpresinha simpática.

Expansão de parâmetros

Aqui começa a parte divertida do Bash. Não divertida no sentido "uau, que linguagem elegante". Divertida no sentido "pera, eu realmente não preciso abrir um processo pra isso?".

Só pra constar, eu não sei isso de cor. Toda vez que preciso de algo assim: Google. O problema é você não conhecer e nem saber o que pesquisar. Olha que massa:

filepath="/home/deploy/app/config.tar.gz"

echo "${filepath##*/}"    # config.tar.gz  (basename, remove prefixo de forma gulosa)
echo "${filepath%/*}"     # /home/deploy/app  (dirname, remove sufixo de forma curta)
echo "${filepath%%.*}"    # /home/deploy/app/config  (remove TODAS as extensoes)
echo "${filepath%.gz}"    # /home/deploy/app/config.tar  (remove so a ultima extensao)

Sua colinha de bolso:

# corta da esquerda
% corta da direita
uma vez = menor correspondência
dobrado = maior correspondência

Renomear extensão fica simples. E eu estava precisando disso agora mesmo pra fazer isso:

# Agora suas imagens .png com fundo transparente tem um fundo preto.
# De nada 🥸 (a pasta mess aí é pra me lembrar de limpar minha própria bagunça)
for f in "${HOME}"/Desktop/mess/fotos/*.png; do
    ########################## só isso pra trocar a extensão   ↓     ↓
    magick "$f" -background black -alpha remove -alpha off "${f%.png}.jpg"
done

Busca e substituição também:

msg="ERROR: connection failed: timeout: host=db.prod"

echo "${msg//:/ -}"          # Substitui todos os : por -
echo "${msg//:/}"            # Remove todos os :
echo "${msg/#ERROR/WARN}"    # Substitui so se estiver no inicio
echo "${msg/%prod/staging}"  # Substitui so se estiver no fim

E tem as expansões de default, que eu uso bastante. Você seria obrigado a usar isso se fosse fazer um script direito, como vimos anteriormente. Se uma variável não tiver valor, dá erro e ele nem roda. Isso resolve:

# ${var:-default} - usa o default se var estiver vazia OU nao definida
db_host="${DB_HOST:-localhost}"

# ${var:=default} - mesma coisa, mas TAMBEM atribui o valor a var
: "${CACHE_TTL:=3600}"  # Define CACHE_TTL se ainda nao existir

# ${var:+alternate} - usa alternate so se var EXISTIR e nao estiver vazia
auth_header="${API_TOKEN:+Authorization: Bearer $API_TOKEN}"

# ${var:?message} - sai com erro se var estiver vazia ou nao definida
: "${DATABASE_URL:?DATABASE_URL precisa estar definida}"

:= é útil pra inicializar. :? é ótimo pra falhar cedo sem escrever aquele bloco if [ -z ... ] pela milésima vez.

Se você estiver num Bash 4+, ainda ganha conversão de caixa:

name="john DOE"
echo "${name^^}"   # JOHN DOE  (maiusculas)
echo "${name,,}"   # john doe  (minusculas)
echo "${name^}"    # John DOE  (capitaliza o primeiro caractere)

É pouca coisa? Sim. Mas já corta subprocesso besta com tr.

O inferno das aspas

Se eu tivesse que escolher uma coisa pra martelar em shell script, seria aspas. Metade dos bugs estranhos de Bash parece ter sido criada num laboratório só pra te lembrar disso. Sabe aquele tipo de regra cheio de ifs? Sãs as aspas no Bash (principalmente as duplas).

#!/bin/bash
cleanup() {
    local dir=$1
    for file in $(ls "$dir"); do
        rm "$dir/$file"
    done
}

cleanup "/tmp/my app/cache"

Esse script é uma fábrica de problema. $(ls "$dir") faz word splitting. Aí o arquivo com espaço vira dois. E você só percebe quando apagou a coisa errada ou quando nada funciona no servidor "sem motivo".

Pro tip: Se você está começando agora, já saiba disso: rm não tem volta. Começa com echo rm algumacoisa. E veja o comando que vai ser executado primeiro. Eu faço isso toda hora. Aqui o histórico do meu zsh que não me deixa mentir:

: 1776691649:0;for f in ~/Desktop/mess/fotos/*.*; do echo magick "$f" -background black -alpha remove -alpha off "${f%(.png|.jpg)}.jpg" ; done
: 1776691666:0;for f in ~/Desktop/mess/fotos/*.*; do magick "$f" -background black -alpha remove -alpha off "${f%(.png|.jpg)}.jpg" ; done

O que? Achou que era mentira, né? Te peguei!

O mínimo aceitável fica assim:

cleanup() {
    local dir=$1
    for file in "$dir"/*; do
        [[ -f "$file" ]] && rm -- "$file"
    done
}

Três regras que ajudam muito:

Coloca aspas em expansão de variável.
Usa "$@" pra repassar argumentos.
Prefere [[ ]] a [ ] quando estiver em Bash.

Sobre "$@" vs $*, olha isso:

# Suponha que o script foi chamado assim: ./script "hello world" "foo bar"

echo "--- \$* ---"
for arg in $*; do echo "  [$arg]"; done
# [hello] [world] [foo] [bar]  - 4 args. Quebrado.

echo "--- \"\$*\" ---"
for arg in "$*"; do echo "  [$arg]"; done
# [hello world foo bar]  - 1 arg. Tambem quebrado.

echo "--- \"\$@\" ---"
for arg in "$@"; do echo "  [$arg]"; done
# [hello world] [foo bar]  - 2 args. Correto.

"$@" preserva os argumentos do jeito que eles vieram. "$*" tem seus usos, mas quase nunca é o que você quer.

E sobre [[ ]]:

# Fragil - quebra com valores vazios ou com espacos
[ "$var" = "" ] && echo "vazia"

# Robusto - sem ginastica com aspas
[[ -z $var ]] && echo "vazia"

# Bonus: regex (so em [[ ]])
[[ "$email" =~ ^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$ ]] && echo "valido"

Variáveis indiretas e nameref: dinamismo sem `eval`

Quando você precisa usar o nome de uma variável guardado dentro de outra, eval costuma ser a primeira ideia ruim que aparece.

# PERIGOSO - nunca faca isso com entrada nao confiavel
key="PATH"
eval "echo \$$key"    # Funciona, mas eval interpreta codigo arbitrario

Funciona? Funciona. E também abre a porta pra você executar coisa que não devia.

Pra ler o valor de outra variável, usa expansão indireta:

key="HOME"
echo "${!key}"    # /home/deploy - expande a variavel cujo nome esta em $key

Se precisar mesmo de referência, aí entra declare -n:

declare -n ref="HOME"
echo "$ref"           # /home/deploy
ref="/opt/app"        # Isso ALTERA $HOME (cuidado!)

Caso real:

load_config() {
    local config_file="$1"
    while IFS='=' read -r key value; do
        # Ignora comentarios e linhas em branco
        [[ "$key" =~ ^[[:space:]]*# ]] && continue
        [[ -z "$key" ]] && continue
        # Remove espacos
        key="${key## }" ; key="${key%% }"
        value="${value## }" ; value="${value%% }"
        # Exporta como variavel de ambiente em maiusculas
        declare -g "${key^^}=$value"
    done < "$config_file"
}

# config.env:
# db_host = postgres.prod
# db_port = 5432
# cache_ttl = 3600

load_config "config.env"
echo "$DB_HOST"    # postgres.prod
echo "$CACHE_TTL"  # 3600

Sem eval, sem source, sem transformar config em código executável.

Outra situação boa pra nameref é "retorno múltiplo":

# Uma funcao que devolve o valor em variaveis escolhidas pelo chamador
parse_semver() {
    local version="$1"
    declare -n major_ref="$2"
    declare -n minor_ref="$3"
    declare -n patch_ref="$4"

    major_ref="${version%%.*}"
    local rest="${version#*.}"
    minor_ref="${rest%%.*}"
    patch_ref="${rest#*.}"
}

parse_semver "3.14.2" maj min pat
echo "$maj.$min.$pat"  # 3.14.2

É um jeito limpo de fazer a função escrever no que o chamador escolheu, sem arquivo temporário e sem gambiarra global.

Nota de versão: arrays associativos exigem Bash 4.0+, conversão de caixa (^^, ,,) exige 4.0+, mapfile exige 4.0+, e declare -n exige 4.3+. O macOS ainda vem com Bash 3.2 por causa da novela da GPLv3. Então, se você precisa suportar macOS puro, ou instala Bash novo com brew install bash, ou segura a onda com recursos mais antigos.

Controle de processos e sinais: aqui o shell começa a aprontar

Quando Bash fica estranho de verdade, geralmente não é por causa de variável. É por causa de processo. A variável sumiu? Talvez ela tenha nascido num subshell. O Ctrl-C não limpou nada? Talvez você não amarrou os sinais. O nohup não virou daemon? Porque ele nunca prometeu isso.

Substituição de processo: quando pipe não resolve

Pipe é ótimo quando o próximo comando quer stdin. Nem sempre ele quer.

Nesses casos, a substituição de processo quebra um galho enorme:

<(list)   # um pseudo-arquivo legivel com o stdout de list
>(list)   # um pseudo-arquivo gravavel alimentando o stdin de list

O Bash te entrega algo via /dev/fd ou FIFO pra você plugar em comando que espera caminho de arquivo.

Exemplo clássico:

comm -3 <(sort prod-packages.txt) <(sort staging-packages.txt)

Ou com diff:

diff -u <(sort before.txt) <(sort after.txt)

Sem arquivo temporário perdido em /tmp, sem cleanup extra só pra comparar duas coisas.

O >(...) também é útil:

tar -cf - project \
  | tee >(sha256sum > project.tar.sha256) \
  > project.tar

Você gera o tar uma vez só e ainda calcula o hash no caminho.

Agora, o bug clássico:

last=""
printf '%s\n' alpha beta | while IFS= read -r line; do
  last=$line
done
printf 'last=%s\n' "$last"

Se isso te devolveu variável vazia, bem-vindo ao clube. O loop rodou num subshell por causa do pipeline. O shell pai não ficou sabendo de nada.

Quando o estado precisa sobreviver, eu prefiro assim:

last=""
while IFS= read -r line; do
  last=$line
done < <(printf '%s\n' alpha beta)
printf 'last=%s\n' "$last"

Ou, se já for arquivo:

while IFS= read -r line; do
  last=$line
done < input.txt

Tem lastpipe? Tem. Eu basearia convenção de time nisso? Nem a pau.

Se a lógica mexe em estado que você ainda vai usar, eu evitaria pipear pra dentro dela (mais uma palavra inventada neste post).

Traps: cleanup de verdade

Se o script cria temporário, lock, socket ou processo em background, cleanup deixa de ser detalhe bem rápido. Se você deixa pra pensar nisso no fim, normalmente já deu tempo de se arrepender.

Um padrão que costuma me servir:

#!/usr/bin/env bash
set -euo pipefail

tmpdir=$(mktemp -d)
worker_pid=""

cleanup() {
  [[ -n "$worker_pid" ]] && kill "$worker_pid" 2>/dev/null || true
  rm -rf "$tmpdir"
}

trap cleanup EXIT
trap 'exit 130' INT
trap 'exit 143' TERM

(
  while :; do
    date +%s >>"$tmpdir/heartbeat.log"
    sleep 2
  done
) &
worker_pid=$!

printf 'worker=%s temp=%s\n' "$worker_pid" "$tmpdir"
wait "$worker_pid"

Se o script só limpa no caminho feliz, ele não limpa. Só teve sorte.

Coisas que eu tento não esquecer:

EXIT é onde eu quase sempre penduro teardown.
INT e TERM merecem atenção.
ERR ajuda no diagnóstico, mas não substitui fluxo pensado.
SIGKILL não negocia com ninguém.

E não, o Bash não vira supervisor só porque você colocou um & no final. Guardou PID? Sabe quem precisa morrer? Sabe o que acontece se o shell ignorar um sinal? Isso tudo importa.

Job control: bom no terminal, outra história em script

No shell interativo, job control é uma mão na roda:

$ rsync -av --info=progress2 big-tree/ backup:/srv/backup/
^Z
[1]+  Stopped                 rsync -av --info=progress2 big-tree/ backup:/srv/backup/
$ bg %1
[1]+ rsync -av --info=progress2 big-tree/ backup:/srv/backup/ &
$ jobs
[1]+  Running                 rsync -av --info=progress2 big-tree/ backup:/srv/backup/ &
$ fg %1
rsync -av --info=progress2 big-tree/ backup:/srv/backup/

Pra esse tipo de uso, ele quebra um galho bonito. Você pausa, manda pro background, traz de volta. Beleza.

O tropeço vem quando a gente começa a tratar isso como gerenciamento de serviço. Não é.

Se quiser manter o job vivo depois do logout:

bg %1
disown -h %1

Ou já inicia com nohup:

nohup rsync -av --info=progress2 big-tree/ backup:/srv/backup/ \
  >rsync.log 2>&1 &

Lembra do detalhe: nohup não manda pro background sozinho. O & continua necessário.

Se o processo realmente importa, eu tenderia a jogar isso pra systemd, tmux, screen, systemd-run ou outro supervisor de verdade. disown e nohup resolvem um problema bem mais simples.

Subshells vs grupos de comando

Essa diferença parece boba até o dia em que você toma uma rasteira:

(commands)      # roda em um subshell
{ commands; }   # roda no shell atual

Com parênteses, mudança de diretório, variável e opções do shell morrem ali dentro. Com chaves, elas continuam valendo.

(cd /tmp; printf 'dentro de (): %s\n' "$PWD")
printf 'depois de (): %s\n' "$PWD"

{ cd /tmp; printf 'dentro de {}: %s\n' "$PWD"; }
printf 'depois de {}: %s\n' "$PWD"

E é a mesma ideia por trás do contador que fica em 0:

count=0
printf '%s\n' a b c | while IFS= read -r _; do
  ((count++))
done
echo "$count"   # 0

count=0
while IFS= read -r _; do
  ((count++))
done < <(printf '%s\n' a b c)
echo "$count"   # 3

O resumo que eu tento guardar é este:

usa (...) quando quiser isolamento
usa { ...; } quando quiser manter efeito colateral
evita pipeline quando a lógica precisa alterar estado do shell atual

Parece detalhe. Não é. É o tipo de detalhe que decide se o script é previsível ou se vai ter comportamento de poltergeist.

Padrões do mundo real: Bash de produção

Quando eu penso em Bash de produção, eu não penso em "script elegante". Eu penso em script previsível. Aquele troço chato, explícito e um pouco paranoico, mas que não inventa surpresa ruim.

Parsing de argumentos sem gambiarra

getopts já resolve muita coisa. Não é framework de CLI, não vai te dar subcomando bonitinho, mas pra muito script real ele basta.

O problema é que muita gente acha que parsing acaba quando você conseguiu ler -v e -o. Não acaba. Parsing também é validar aridade, formato e tudo aquilo de que o resto do script depende.

Esse é o tipo de padrão que eu gosto de ter por perto:

#!/usr/bin/env bash
set -euo pipefail

usage() {
  cat <<'USAGE'
Usage: report-sync [-v] [-o file] [-c config] job_name source_dir
USAGE
}

die() {
  printf 'ERROR: %s\n' "$*" >&2
  exit 1
}

verbose=0
output_file=
config_file=
job_name=
source_dir=

normalize_args() {
  local normalized=()

  while (($#)); do
    case "$1" in
      --verbose) normalized+=(-v) ;;
      --output)
        (($# >= 2)) || die "--output requires a file path"
        normalized+=(-o "$2")
        shift
        ;;
      --config)
        (($# >= 2)) || die "--config requires a path"
        normalized+=(-c "$2")
        shift
        ;;
      --help) normalized+=(-h) ;;
      --)
        shift
        while (($#)); do
          normalized+=("$1")
          shift
        done
        break
        ;;
      *) normalized+=("$1") ;;
    esac
    shift
  done

  printf '%s\0' "${normalized[@]}"
}

parse_args() {
  local -a argv=()

  while IFS= read -r -d '' token; do
    argv+=("$token")
  done < <(normalize_args "$@")

  set -- "${argv[@]}"
  OPTIND=1

  while getopts ':vo:c:h' opt; do
    case "$opt" in
      v) verbose=1 ;;
      o) output_file=$OPTARG ;;
      c) config_file=$OPTARG ;;
      h)
        usage
        exit 0
        ;;
      :)
        die "Option -$OPTARG requires an argument"
        ;;
      \?)
        usage >&2
        die "Unknown option: -$OPTARG"
        ;;
    esac
  done

  shift $((OPTIND - 1))
  (($# == 2)) || die 'Expected job_name and source_dir'

  job_name=$1
  source_dir=$2

  [[ $job_name =~ ^[a-zA-Z0-9._-]+$ ]] || die "Invalid job name: $job_name"
  [[ -d $source_dir ]] || die "Source directory not found: $source_dir"

  if [[ -n ${output_file:-} ]]; then
    local parent_dir
    parent_dir=$(dirname -- "$output_file")
    [[ -d $parent_dir ]] || die "Output directory does not exist: $parent_dir"
  fi
}

parse_args "$@"

Algumas escolhas aí eu manteria, pelo menos hoje:

normalizar opção longa na mão em vez de depender de getopt externo
validar logo depois do parsing
falhar cedo quando caminho, nome ou formato vierem errados

Se o script começa a pedir subcomando, config aninhada e um monte de modo mutuamente exclusivo, é um bom sinal de que talvez já tenha passado da hora de sair do Bash.

Arquivos de configuração: dados, não código surpresa

Eu evito source pra config sempre que posso. source não lê "dados". Ele executa shell dentro do shell atual. Se isso é o que você quer, beleza. Se não é, você acabou de transformar configuração em código executável sem nem perceber.

Pra config simples, KEY=VALUE ainda é um formato honesto. Fácil de versionar, de sobrepor com variável de ambiente e de entender sem sofrimento.

Este loader aqui segue essa ideia e já recusa sintaxe shell no valor:

#!/usr/bin/env bash
set -euo pipefail

readonly DEFAULT_CONFIG="$HOME/.myapprc"
readonly SYSTEM_CONFIG="/etc/myapp.conf"
config_file_for_current_run=

find_config_file() {
  local candidate

  for candidate in "${MYAPP_CONFIG:-}" "$DEFAULT_CONFIG" "$SYSTEM_CONFIG"; do
    [[ -n ${candidate:-} && -f $candidate ]] || continue
    config_file_for_current_run=$candidate
    return 0
  done

  return 1
}

die() {
  printf 'ERROR: %s\n' "$*" >&2
  exit 1
}

load_config_file() {
  local file=$1 line lineno=0 key value

  [[ -f $file ]] || die "Config is not a regular file: $file"

  while IFS= read -r line || [[ -n $line ]]; do
    ((lineno++))
    [[ $line =~ ^[[:space:]]*($|#) ]] && continue

    [[ $line =~ ^[[:space:]]*([A-Z_][A-Z0-9_]*)=(.*)$ ]] \
      || die "Sintaxe de config nao suportada em $file:$lineno"

    key=${BASH_REMATCH[1]}
    value=${BASH_REMATCH[2]}

    [[ ! $value =~ [\`\$\(\)\;\&\|\<\>] ]] \
      || die "Recusando sintaxe shell em $file:$lineno"

    value=${value##[[:space:]]}
    value=${value%$'\r'}

    if [[ $value =~ ^"(.*)"$ ]]; then
      value=${BASH_REMATCH[1]}
    elif [[ $value =~ ^\'(.*)\'$ ]]; then
      value=${BASH_REMATCH[1]}
    fi

    printf -v "$key" '%s' "$value"
    export "$key"
  done < "$file"
}

if find_config_file; then
  load_config_file "$config_file_for_current_run"
fi

Eu deixei ele rígido de propósito. Se alguém quiser array, objeto aninhado e meia dúzia de regra de escape, melhor trocar de formato logo em vez de inventar uma mini linguagem no shell.

Pra JSON, usa jq:

api_base_url=$(jq -er '.api_base_url' "$config_json")
concurrency=$(jq -er '.concurrency // 4' "$config_json")

Pra mim, costuma funcionar bem assim:

arquivo de config pros defaults estáveis
variável de ambiente pros overrides do deploy e pros segredos

Logging e debug sem virar bagunça

Log bom em shell, pra mim, tem duas regras:

humano lê em stderr
dado da pipeline vai limpo em stdout

Misturou os dois, você transformou um script reutilizável num bicho irritante.

Uma camada simples já ajuda bastante:

LOG_LEVEL=${LOG_LEVEL:-info}
LOG_FILE=${LOG_FILE:-}

level_number() {
  case "$1" in
    debug) printf '10\n' ;;
    info)  printf '20\n' ;;
    warn)  printf '30\n' ;;
    error) printf '40\n' ;;
    *) return 1 ;;
  esac
}

log() {
  local level=${1:?missing log level}
  shift

  local current threshold ts line
  current=$(level_number "${level,,}") || return 1
  threshold=$(level_number "${LOG_LEVEL,,}") || threshold=20

  (( current < threshold )) && return 0

  printf -v ts '%(%Y-%m-%dT%H:%M:%S%z)T' -1
  printf -v line '%s %-5s %s' "$ts" "${level^^}" "$*"

  printf '%s\n' "$line" >&2
  [[ -n ${LOG_FILE:-} ]] && printf '%s\n' "$line" >> "$LOG_FILE"
}

Com isso, você ganha nível, timestamp e arquivo de log sem sujar stdout. Quando eu quero espelhar stream, ainda gosto de tee:

exec 2> >(tee -a "$LOG_FILE" >&2)

set -x ajuda, mas a saída crua costuma ser barulhenta demais. O truque abaixo deixa o trace num descritor separado e com contexto que presta:

exec 9>>"${TRACE_FILE:-/tmp/report-sync.trace}"
export BASH_XTRACEFD=9
export PS4='+ ${BASH_SOURCE##*/}:${LINENO}:${FUNCNAME[0]:-main}: '

set -x
# bloco suspeito aqui
set +x

É o tipo de coisa que vale guardar porque economiza um bom tempo quando o script começa a se comportar como se estivesse possuído.

Testando script Bash sem sofrimento

Dá pra testar shell script, sim. E eu acho que vale bastante quando o script começa a lidar com flag, config, arquivo ou efeito colateral.

Se for um scriptinho de 15 linhas em volta de um comando, talvez nem precise. Agora, se ele apaga coisa, faz parsing e conversa com produção, eu prefiro ter algum teste.

bats me atende bem porque mantém tudo no ecossistema do shell.

Um teste útil, pro loader de config acima, seria algo assim:

#!/usr/bin/env bats

load '../lib/config.sh'

@test "load_config_file rejeita sintaxe shell em valores" {
  config="$BATS_TEST_TMPDIR/bad.conf"
  printf 'OUTPUT_FILE=$(touch /tmp/nope)\n' > "$config"

  run load_config_file "$config"

  [ "$status" -eq 1 ]
  [[ "$output" == *"Recusando sintaxe shell"* ]]
}

Esse teste protege uma fronteira que, pra mim, importa bastante: config tem que continuar sendo dado.

Pra mockar comando externo, eu gosto do jeito simples: diretório temporário no começo do PATH e executável falso lá dentro. Menos frágil do que tentar inventar mágica com alias.

Pra mim, testabilidade em Bash costuma andar junto com design menos bagunçado. Quando parsing, config e efeito colateral ficam separados em funções pequenas, o teste deixa de ser castigo.

Segurança e produção: onde Bash para de ser brincadeira

Quando o script começa a rodar em servidor, CI, container ou qualquer lugar com entrada menos controlada, a história muda rápido. O que no notebook era só "script útil" vira superfície de ataque sem pedir licença.

As armadilhas de segurança

Injeção de comando: o botão vermelho do `eval`

Se você monta comando a partir de entrada de usuário, está perigosamente perto de entregar um shell de presente.

O script vulnerável:

#!/bin/bash
# "Visualizador simples" de logs - NAO USE ISSO
echo "Digite o nome do arquivo:"
read -r filename
eval "cat logs/$filename"

O atacante pode meter um ;, um $(...) ou qualquer outra gracinha. E, às vezes, nem precisa ser algo espalhafatoso pra causar estrago.

Pra mim, aqui não adianta tentar "sanitizar melhor". O que ajuda de verdade é parar de tratar dado como código:

#!/bin/bash
read -r filename

# Valida: somente letras, numeros, traco, ponto e underscore
if [[ ! "$filename" =~ ^[a-zA-Z0-9._-]+$ ]]; then
    echo "Nome de arquivo invalido" >&2
    exit 1
fi

# Usa a variavel como DADO, nao como CODIGO
# Sem eval, sem expansao desprotegida, sem montar comando na mao
cat -- "logs/$filename"

O -- evita interpretar nome como opção. O regex barra ../../etc/passwd e coisa parecida. Aqui a ideia é simples: cada camada corta um pedaço do problema.

Quando bate vontade de usar eval, eu paro e desconfio. Na maior parte das vezes dá pra fazer melhor. Quando eu realmente preciso montar comando, costumo ir de array:

cmd=(find "$directory" -name "*.log" -mtime +"$days")
"${cmd[@]}"

Corrida com arquivo temporário: `mktemp` ou arrependimento

# VULNERAVEL: nome previsivel, condicao de corrida
tmpfile="/tmp/myapp-$$"
echo "$data" > "$tmpfile"

Esse padrão com PID no nome parece "único o bastante" até o dia em que alguém cria um symlink ali antes de você. Aí o seu script grava dado onde não devia e a brincadeira acaba.

Um padrão bem melhor:

#!/bin/bash
set -euo pipefail

tmpdir=$(mktemp -d "${TMPDIR:-/tmp}/myapp.XXXXXXXXXX")
trap 'rm -rf -- "$tmpdir"' EXIT

# Agora use $tmpdir com seguranca - aleatorio, dono voce, modo 0700
echo "$data" > "$tmpdir/output.txt"

mktemp cria de forma atômica e com permissão restritiva. O trap limpa depois. E diretório temporário costuma ser mais prático do que arquivo temporário solto.

Segredos: o que NÃO fazer

# Tudo isso aqui esta errado:
PASSWORD="hunter2"                      # Hardcoded no codigo
curl -u "admin:$PASSWORD" "$url"        # Visivel em /proc/$pid/cmdline
echo "$SECRET" | docker login --stdin   # Melhor, mas cuidado com historico do shell
export DB_PASS="secret"                 # Herdado por TODO processo filho

Em shell, segredo espalha fácil demais. Vai pro histórico, vai pro ps, vai pro ambiente do processo filho, vai parar onde você não queria.

Quando der, eu prefiro ler de arquivo/FD ou deixar a plataforma injetar só no momento do uso:

# Le segredo de file descriptor, sem tocar disco nem aparecer em ps
db_password=$(< /run/secrets/db_password)
PGPASSWORD="$db_password" psql -h "$host" -U "$user" "$dbname" <<< "$query"

Quando o Bash fica lento (e quando isso não importa)

Bash costuma ir melhor abrindo processo do que processando dado em loop apertado. Quando o script fica lento, muitas vezes o problema é um festival de fork.

A versão lenta: 3 forks externos por iteração.

# Processando 10.000 linhas: ~45 segundos
while IFS= read -r line; do
    name=$(echo "$line" | cut -d',' -f1)
    value=$(echo "$line" | cut -d',' -f2)
    echo "$name: $value"
done < data.csv

A versão rápida: zero fork.

# Processando 10.000 linhas: ~0.3 segundos
while IFS=, read -r name value _rest; do
    printf '%s: %s\n' "$name" "$value"
done < data.csv

A diferença está aí: o primeiro exemplo cria processo demais. O segundo deixa o shell fazer o que ele consegue fazer sem sair abrindo ferramenta externa em cada linha.

Pra paralelismo de verdade, muitas vezes é melhor sair do loop manual:

# Processa arquivos em paralelo, 8 por vez
find . -name '*.log' -print0 | xargs -0 -P 8 -I{} gzip {}

# GNU parallel com barra de progresso
find . -name '*.csv' | parallel --bar -j+0 'process_file {}'

A regra prática que eu tento lembrar é: shell lento quase sempre tem loop com fork demais.

CI/CD: códigos de saída são sua API

CI é binário: saiu 0, passou. Qualquer outra coisa, falhou. Então o script que roda ali precisa ser bem honesto com código de saída:

#!/bin/bash
set -euo pipefail

Sem pipefail, o pipeline pode mascarar erro feio e o build passar com cara de vencedor.

ShellCheck no CI

ShellCheck no CI é um daqueles freios baratos que compensam muito:

# .github/workflows/lint.yml
name: Shell Lint
on: [push, pull_request]
jobs:
  shellcheck:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run ShellCheck
        run: |
          find . -name '*.sh' -print0 | xargs -0 shellcheck --severity=warning
      - name: Run BATS tests
        run: |
          sudo apt-get install -y bats
          bats tests/

Com ShellCheck e algum teste em Bats, eu já fico bem mais tranquilo com o script.

Docker: o problema do PID 1

Docker com shell tem uma pegadinha bem comum: PID 1. Se a sua app vira filha do Bash e o Bash não repassa sinal direito, o container morre de forma feia.

Um entrypoint que eu usaria com mais tranquilidade em produção:

#!/bin/bash
set -euo pipefail

# --- Configuracao via ambiente ---
: "${APP_PORT:=8080}"
: "${APP_ENV:=production}"
: "${GRACEFUL_SHUTDOWN_TIMEOUT:=30}"

# --- Espera dependencias ---
wait_for_db() {
    local retries=30
    while ! pg_isready -h "$DB_HOST" -p "${DB_PORT:-5432}" -q; do
        retries=$((retries - 1))
        if [[ $retries -le 0 ]]; then
            echo "ERROR: Banco de dados indisponivel apos 30 tentativas" >&2
            exit 1
        fi
        sleep 1
    done
}

# --- Tratamento de sinais ---
shutdown_handler() {
    echo "Sinal de encerramento recebido, drenando conexoes..."
    # Da tempo pro load balancer remover a instancia
    sleep 2
    kill -TERM "$child_pid" 2>/dev/null || true
    wait "$child_pid"
    exit_code=$?
    echo "Aplicacao saiu com codigo $exit_code"
    exit "$exit_code"
}

trap shutdown_handler SIGTERM SIGINT

# --- Init ---
wait_for_db
echo "Iniciando app em :${APP_PORT} (env=${APP_ENV})"

# --- Launch: exec substitui o shell SE nao houver pos-processamento ---
# Quando voce precisa encaminhar sinais (como no tratador acima), NAO use exec.
# Em vez disso, jogue o processo para background e espere.
/usr/local/bin/myapp --port "$APP_PORT" &
child_pid=$!
wait "$child_pid"

Daqui, eu guardo basicamente isto:

exec substitui o shell pelo processo final quando você não precisa de lógica extra.
background + wait entra quando você realmente precisa interceptar sinal.
Alpine não te dá Bash por padrão.
--init com tini às vezes já resolve sem precisar reinventar nada.

Padrões de deploy

Publicando sem surpresa

Pra script standalone, eu gosto de falhar cedo se a versão do Bash não for a necessária:

#!/bin/bash
# Checagem de versao no topo - falha rapido, nao no meio do caminho
if [[ "${BASH_VERSINFO[0]}" -lt 4 ]]; then
    echo "ERROR: Bash 4+ obrigatorio (encontrado ${BASH_VERSION})" >&2
    exit 1
fi

Idempotência ajuda bastante

Script de produção roda de novo. Retry, cron, recuperação, operador apertando seta pra cima sem querer pensar muito. Então idempotência ajuda bastante:

# Idempotente: cria so se nao existir
mkdir -p /opt/myapp/data
id -u appuser &>/dev/null || useradd -r -s /bin/false appuser

# Idempotente: move so se a origem existir
[[ -f "$src" ]] && mv -- "$src" "$dst"

Quando parar de usar Bash

Bash é bom pra colar programa, mover arquivo, orquestrar etapa. Começa a ficar ruim quando:

você está parseando JSON/YAML o tempo todo
você precisa de estrutura de dados de verdade
o script cresce e ninguém mais quer encostar
recovery de erro e concorrência viram parte do problema

Nessa hora, chamar Python ou Go não é derrota. Muitas vezes é só bom senso.

Conclusão: script chato costuma ser o melhor script

Como eu falei no começo, isso aqui continua sendo nota de estudo. Só que é o tipo de nota de estudo que já me poupou de algumas burradas, então resolvi juntar tudo num lugar só.

Pra mim, Bash fica melhor quando a gente para de procurar truque esperto e começa a desconfiar das coisas certas. Do set -e, do pipeline inocente, do eval, do temporário malfeito, do loop que abre processo demais e jura que está tudo sob controle.

No fim, o tipo de script Bash de que eu mais gosto é aquele que você roda daqui a três meses sem sentir vontade de xingar o seu eu do passado. Se ele falha cedo, fala onde doeu, não mistura dado com código e não sai fazendo gracinha em silêncio, eu já fico feliz.

Se ele funcionar no notebook, no CI e dentro do container sem virar um caso de polícia, melhor ainda. E se em algum momento você perceber que está forçando a barra e tentando transformar Bash em linguagem de aplicação, passa o bastão. Eu mesmo prefiro isso a insistir por teimosia.

Valeu. Até o próximo (esse aqui foi sofrido pra escrever 🙏)

Um dos maiores ataques de supply chain de 2026 (na prática)

Thu, 02 Apr 2026 20:07:56 GMT

Obs.: o tom desse artigo está extremamente diferente de como eu escrevo realmente. O motivo é que se eu falar realmente como eu escrevo, o artigo não vai ser entregue ou vai ser removido por questões de segurança. O assunto é sério e precisa ser falado, mas de forma que o algoritmo entenda e não remova o conteúdo.

Pessoal, preciso falar de um assunto muito sério hoje. Existe um ataque de supply chain bem engenhoso rolando na internet, e se você usa GitHub Actions ou pip install em qualquer pacote Python, você precisa me ouvir. Entre fevereiro e março de 2026 a coisa ficou bem feia na nossa área.

Alguns responsáveis por esse problema conseguiram comprometer o Trivy (sim, um grande scanner de segurança do mercado) e o LiteLLM (que bate quase 95 milhões de downloads mensais no PyPI). Tem indícios de que sobrou até para o Checkmarx.

Eu montei a timeline desses eventos, reproduzi partes do incidente no meu laboratório privado e agora vou te mandar a real dos acontecimentos por baixo dos panos e como você protege o seu próprio código de dor de cabeça igual a essa.

Apoio

Se estiver precisando de servidores (VPS) com bom custo-benefício, dá uma olhada na Hostinger. Usando meu link e cupom, você ganha até 2 anos de desconto.

hostinger.com/otaviomiranda
Cupom: OTAVIOMIRANDA

Em vídeo

Fiz um vídeo completo sobre o assunto, caso queira assistir:

https://youtu.be/oFrcf_17gRg

Então agora é texto, bora...

A fresta de entrada e o bot

Tudo começou lá pelo final de fevereiro, quando surgiu uma conta no GitHub chamada "hackerbot-claw". Esse bot ficava o dia todo escaneando a rede pública atrás de projetos com aquela falha simples na área de CI/CD. Cedo ou tarde ele iria encontrar algo.

O bot focava em projetos usando o famigerado trigger pull_request_target. Só para nivelar a questão: o trigger normal pull_request no Actions roda tudo num ambiente bem isolado blindando os secrets do repositório. O perigo mora lá na sintaxe de "target", que ao contrário da normal inicia tudo mirando com permissões da "main", com a faca e o queijo na mão (no caso todas as chaves e senhas configuradas no sistema).

O ponto de quebra que abriu a porta foi as equipes combinarem o trigger exposto com o checkout direto das linhas dos contribuintes na PR. Isso significa pegar código totalmente não testado rodando nos runners com variáveis da sua carteira de trabalho da nuvem liberados.

on:
  pull_request_target:
    types: [opened, synchronize]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      # O erro: Fazer checkout de um PR feito por desconhecidos
      # dentro de um job na retaguarda com secrets destravados!
      - uses: actions/checkout@v4
        with:
          ref: ${{ github.event.pull_request.head.sha }}

      - run: make build

Eles conseguiram furar e rodar o script no repositório gigante do Trivy explorando exatamente esse passo fraco.

A captura silenciosa do sistema

Na surdina, o script configurado por eles largou um comando de rede simples, entrando nos parâmetros ativos da máquina sem gritaria e sem levantar suspeitas. Eles extraíram os dados do processo lendo a memória RAM de forma direta mapeando os volumes de execução. Lá nesse bloco constava o token principal de acesso ao projeto.

Assim que a senha de edição foi parar no servidor deles, efetuaram um envio camuflado no formato do Conventional Commits e fingiram assinar com a autoria de antigos mantenedores oficiais do Trivy. Tudo continuou parecendo muito normal para a equipe original de manutenção do pacote.

Mas a artimanha inserida trocou com primor um apontamento lá da rotina de lançamento para um endereço alvo falso com o nome (removido por questões de segurança). Esse código alterado ficou um par de semanas dormente, esperando pacientemente o fluxo rodar.

Farsa das tags e a queda do LiteLLM

Então botaram a cereja principal da situação e cometeram o force push no repositório brutalmente, rebaixando e trocando muito mais do que setenta tags do Trivy de volta à fase comprometida. Agora mesmo quem só declarava o clássico valor (REMOVIDO POR QUESTÕES DE SEGURANÇA) nas automações passava a usar esse código contendo as extrações escondidas.

Para o grupo do LiteLLM o estrago nas tags causou muito dano. Todo o fluxo interno de Actions que a equipe geria estava perfeitamente configurado sem erros no caso de checkouts e PRs de estranhos. Só que os devs haviam importado o Trivy na esteira para auditar falhas do mesmo modo padrão utilizado pela grande comunidade global.

A action modificada desceu rodando no servidor LiteLLM engolido pelos scanners deles e extraiu na hora as credenciais sensíveis de enviar releases lá de dentro da automação (chaves das atualizações locais). Pegaram tudo, codificaram os textos e jogaram no próprio servidor remoto que hospedavam. Usando a chave do pacote que eles conseguiram puxar do projeto oficial, o grupo subiu na loja do Python de forma validada o conteúdo do LiteLLM alterado, e para enganar geral a conta primária de código continuava livre desse incidente. O buraco havia sido feito só lá no entregável do servidor e a comunidade de uso instalava pacotes não oficiais rotineiramente sem nem notar.

O truque do .pth e a bomba de processos

Qual foi o passo sorrateiro no pacote pra sobrecarregar a máquina dos desenvolvedores que instalavam isso no seu uso trivial daquele dia? Eles espalharam um pequeno arquivo de sistema usando o formato .pth guardado com discrição nos diretórios de ambiente (pasta padrão originada na execução das instalações locais).

Muitos desconhecem, mas quando a gente sobe uma rotina do código, o motor processa este script .pth para registrar os percursos extras em diretórios que vão constar na variável base. O detalhe não divulgado é que iniciar frases contendo a ordem "import" executa na mesma hora toda alocação contida logo à frente. Sem cerimônia e sem exigências adicionais.

import os; exec("REMOVIDO POR QUESTÕES DE SEGURANÇA")

Só de levantar o prompt REPL, pedir um log simples ou debugar a aplicação, a ferramenta já ativava rotinas secundárias no fundo, mapeando variáveis de ambiente e transferindo resumos pra longe. E sabe por que a conta não fechou e fomos notificados prontamente pela comunidade? Eles erraram bizarramente os loops na inicialização, o que ocasionou chamadas retroativas num congestionamento de tarefas conhecido no mercado por fork bomb. Cerca de onze mil comandos simultâneos rodando até engasgar os computadores alertaram a supervisão em vários setores de que isso era um gargalo gravíssimo rolando de forma anômala.

Ajustes necessários pra você e sua equipe

Esse alerta vem para mostrar onde devemos nos ligar ao construir e publicar sistemas inteiros pelo Github sem copiar do escopo global como meros digitadores. Segue o que funciona tranquilamente no isolamento básico reduzindo bastante os perigos em pipelines.

Use sempre o valor de Hash e não coloque mais a variável nominal do pacote via tag. Todo commit original do projeto traz uma representação com letras que você joga fixada de forma absoluta na frente de tudo que puxar nos runners que nunca será fraudada ou mudada a rodo. Acima disso você tranca no Docker os pacotes referenciando a imagem por meio de digest da versão original ao invés da sintaxe última do release na linha.

# Inseguro
uses: exemplo/seguro@v1

# Correto fixado via hash de origem do projeto
uses: exemplo/seguro@a1b2c3d4e5f6...

Outro conselho de peso pra amarrar bem a porta nos workflows lida com a verificação de código puxado. Só traga checkouts desconhecidos validando por pull_request fechado impedindo rodagem nas permissões chaves da branch mãe de ponta. Reserve pull_request_target no limite seguro pra aprovar flags e regras nos projetos, contanto que jamais em nenhuma circunstância puxe ou aplique ref externa junto com isso nas ações de build. Tranque a sua internet configurando firewalls travando saídas agressivas de envio direto a domínios ocultos da rede no executor Github se não usar isso nas chamadas oficiais ou pacotes internos pra evitar vazamentos descarados do token local na tela dele.

E façam revisões atentas nas dependências do backend renovando credenciais em bloco, nunca deixando chaves antigas ativas. Analisem também aquele formato .pth, sempre validando se algo conta com chamadas automatizadas antes que isso crie brechas indesejáveis em aplicações rodando de forma corporativa ou caseira.

No blog e aqui na aba de comunidade falo das paradas baseadas na raiz, focando para melhorarmos nossas skills avançadas na engenharia ao criarmos ferramentas pra toda galera dev na comunidade com as nossas proteções sólidas montadinhas do que o mercado expõe como norma nas vulnerabilidades em andamento diário no ecosistema por ai afora da net de desenvolvimento livre onde tem o perigo atual operante do supply chain escondidinho onde menos se acredita. Assine a Newsletter ali pra ganhar essas pegadas que chegam rápidas por lá também sem burocracia dos banners irritantes nas navegações usuais na plataforma oficial. É eu trocando a parte técnica limpa a seu dispor direto pro coração dos estudos em tecnologia.

Até a próxima.

Hackers roubaram senhas com litellm (Pacote de IA do Python)

Thu, 26 Mar 2026 11:31:44 GMT

O pacote litellm versões 1.82.7 e 1.82.8 foram comprometidos com um credential stealer sofisticado. Basicamente, foi um script escondido atrás de base64 que rouba qualquer chave secreta no seu computador. Senhas, .env, credenciais em geral, authentication tokens, chaves SSH e qualquer outra coisa que você nem imaginaria que estivesse em arquivo de texto no seu computador (como as próprias credenciais dos modelos de LLM que você usa).

Se você trabalha com IA em Python, ou usa qualquer ferramenta que depende de litellm por baixo dos panos, esse texto é pra você.

Referência da issue inicial: https://github.com/BerriAI/litellm/issues/24512

Apoio Hostinger

Se estiver precisando de servidores (VPS) com bom custo-benefício, dá uma olhada na Hostinger. Usando meu link e cupom, você ganha até 2 anos de desconto.

hostinger.com/otaviomiranda
Cupom: OTAVIOMIRANDA

O que aconteceu?

No dia 24 de março de 2026, hackers publicaram duas versões maliciosas do litellm diretamente no PyPI. Não foi invasão ao repositório do GitHub. Não foi PR malicioso que passou despercebido. Eles simplesmente... publicaram o pacote no lugar do time oficial, usando credenciais roubadas. 🤔

O litellm não é uma biblioteca qualquer. Eu não o usava diretamente, mas estou descobrindo como funciona enquanto escrevo este texto.

Ele é a camada que traduz e roteia chamadas pra mais de 100 provedores de LLM (OpenAI, Anthropic, Google, AWS Bedrock, etc.) numa interface única.

Uma comparação mais familiar para mim seria com o LangChain. Porém, enquanto LangChain é o framework que orquestra os agentes de IA, o litellm é a camada que fica embaixo dele traduzindo essas chamadas pra cada provedor. Inclusive, parece que o LangChain usa o litellm por baixo dos panos em alguns fluxos.

Aquela busca rápida no Google já me entregou o código abaixo sem eu olhar nenhum site. É aquele tipo de amigo que te empurra na piscina, quando você não sabe nadar, pra te ajudar a perder o medo (tô brincando, viu? haha).

# Example Usage
from langchain_litellm import ChatLiteLLM

llm = ChatLiteLLM(model="gpt-4.1-nano", temperature=0.1)
# or using other providers
# llm = ChatLiteLLM(model="bedrock/amazon.titan-embed-text-v1")

Sério agora, é o tipo de biblioteca invisível que você nem sabe que está usando, até que ela é comprometida.

O pacote tem algo em torno de 95 a 97 milhões de downloads por mês. É o motor invisível de boa parte do ecossistema de IA em Python.

Quando um pacote desse tamanho é comprometido, o impacto não é local apenas.

Para você ter uma ideia, as versões maliciosas ficaram no ar por poucas horas, mas isso foi suficiente pra ~47.000 downloads acontecerem. E não, nem todo mundo que foi afetado instalou o litellm diretamente. Mas a gente chega nisso.

Como os hackers conseguiram publicar no PyPI?

A doideira deste ataque é super interessante, mas assustadora ao mesmo tempo.

Não começou no litellm. Começou no Trivy. Ele é um scanner de vulnerabilidades open-source mantido pela Aqua Security. É exatamente a ferramenta que deveria estar te protegendo.

No final de fevereiro, um bot automatizado chamado hackerbot-claw explorou um workflow pull_request_target no GitHub Actions do Trivy e roubou um Personal Access Token (PAT). Já usamos esse tipo de token em vídeos do canal.

A Aqua Security percebeu e tentou revogar... mas a rotação de credenciais foi incompleta. Justo uma empresa de segurança, trancou todas as portas, ligou o alarme, mas deixou a janela aberta. Não me pergunte 😅.

No dia 19 de março, o grupo (conhecido como TeamPCP) voltou com as credenciais que sobraram e comprometeu o Trivy de vez. Publicaram um binário infectado e forçaram commits maliciosos em 75 das 76 tags do trivy-action no GitHub. Ou seja: qualquer pipeline que rodasse com uses: aquasecurity/trivy-action sem travar numa versão específica passou a executar código malicioso.

Lembrando que a maioria das pessoas usa "tags" para travar a versão, mas tags não são imutáveis, apenas os hashes.

Nota para o eu do futuro: Deixe de preguiça e use o SHA do commit ao invés de tag para garantir imutabilidade.

O que esse código malicioso fazia? Vasculhava as variáveis de ambiente do runner em busca dos secrets. E o CI/CD do litellm rodava o Trivy pra fazer scan de segurança sem travar a versão. O malware encontrou o PYPI_PUBLISH token e mandou pro servidor dos atacantes.

Cinco dias depois, com o token em mãos, o TeamPCP publicou as versões 1.82.7 e 1.82.8 direto no PyPI. Sem tocar no GitHub. Sem PR. Sem nenhum rastro no repositório público.

Esse é o tipo de coisa que faz você parar um segundo: será que toda dependência que você adiciona vale a exposição? No caso do litellm, você realmente vai usar os mais de 100 provedores? Ou vai só chamar a OpenAI mesmo?

O truque do `.pth`: por que a versão 1.82.8 é diferente

A versão 1.82.7 já fazia algum estrago. Ela tinha código malicioso embutido em litellm/proxy/proxy_server.py, mas só executava se você importasse o módulo proxy no seu código. Dava pra ter sorte se você não usasse isso.

A versão 1.82.8, publicada 13 minutos depois, não te perdoaria.

Ela incluiu um arquivo chamado litellm_init.pth dentro do wheel. E aqui entra um mecanismo do Python que muita gente não conhece.

Toda vez que o Python inicia (qualquer invocação, qualquer contexto) ele passa pela pasta site-packages e lê todos os arquivos .pth que encontrar.

Normalmente esses arquivos só adicionam caminhos ao sys.path. Mas se uma linha começar com import, o Python executa ela como código nativo. Sem pedir permissão. Sem precisar que você escreva import litellm em lugar nenhum.

O resultado disso é que o payload do TeamPCP rodava em vários cenários:

Quando você abria um Jupyter notebook
Quando o pytest iniciava
Quando o Language Server da sua IDE ligava
Quando você rodava qualquer script Python no ambiente
Durante o próprio pip install, porque o pip invoca Python

E o arquivo litellm_init.pth estava corretamente declarado no manifesto do wheel com hash SHA-256 válido. Ferramentas tradicionais de supply chain scanning não sinalizaram nada.

O que salvou a situação foi um bug dos próprios hackers. O .pth spawna um processo Python pra executar o payload.

Esse processo filho também inicia o Python... que lê o .pth... que spawna outro filho... que lê o .pth... Já viu, né? Loop, fork bomb e a memória RAM da turma começou a ser jantada pelos processos.

A pessoa vai verificar... Puxa um fio daqui, outro dali... E abre uma issue dessas. Cá entre nós, já pensou receber uma dessas?

Se eles não tivessem cometido esse erro, o malware poderia ter ficado rodando em silêncio por dias.

O que o malware coletava

Uma vez rodando, o script vasculhava tudo que encontrava:

Variáveis de ambiente: onde ficam OPENAI_API_KEY, ANTHROPIC_API_KEY, tokens de CI/CD e afins
Chaves SSH (~/.ssh/): par de chaves inteiro, known_hosts
Credenciais de cloud: ~/.aws/credentials, ~/.azure/, arquivos GCP; também consultava o IMDS da AWS pra pegar tokens temporários de alta permissão
Kubernetes: ~/.kube/config e todos os segredos de todos os namespaces do cluster
Docker: ~/.docker/config.json
Carteiras de criptomoedas: Bitcoin, Ethereum, Solana e mais sete
Histórico do terminal: bash e zsh; sim, porque tem gente que digita senha por acidente no prompt e o histórico guarda
Banco de dados: strings de conexão pra PostgreSQL, MySQL, Redis, MongoDB
Arquivos .env recursivamente até 6 diretórios de profundidade

E olha só. Os atacantes se preocuparam com a sua privacidade. Eles criptografavam seus dados roubados com AES-256-CBC e empacotavam com uma chave RSA-4096 embutida no código (pra que ninguém interceptasse a chave AES no meio do caminho).

O pacote tpcp.tar.gz ia via POST pra https://models.litellm.cloud/, domínio falso, registrado horas antes, feito pra parecer tráfego legítimo da biblioteca nos logs.

E se detectasse um cluster Kubernetes acessível, iam além: criavam pods privilegiados em cada nó do cluster, montavam o sistema de arquivos do host e instalavam um backdoor persistente. Mesmo que você deletasse o litellm, a porta dos fundos continuava aberta.

Por que CrewAI, DSPy, MLflow e outros foram afetados

Você pode nunca ter escrito pip install litellm na sua vida e ainda assim ter sido afetado. O que foi o meu caso. Mas, já te mostro os comandos que rodei aqui.

Se você instala o CrewAI, e o CrewAI depende do litellm. Se o arquivo de dependências do CrewAI dizia litellm>=1.80, sem travar numa versão específica, o pip simplesmente pega a versão mais nova disponível no momento. Que, no momento, era a 1.82.8.

Análise dos dados do PyPI mostrou que 88% dos ~2.337 pacotes que dependem do litellm usavam especificações soltas assim.

Ao fazer uma instalação limpa do CrewAI, DSPy, MLflow, GraphRAG ou outros que usam litellm na manhã do dia 24 de março de 2026, baixava o malware automaticamente, sem nenhum aviso.

É o que a galera de segurança chama de dependência transitiva. Você não instalou o problema. Mas o problema veio junto com o que você instalou.

Como verificar se você foi afetado

Aqui vai o passo a passo. Se todos os comandos voltarem vazios ou com erro de import, você está limpo.

IMPORTANTE: rode os comandos em uma pasta acima de onde estão seus pacotes (ou na pasta onde eles estão).

Aqui vai um exemplo de um dos comandos sendo executado, mas buscando por llms.py (só pra encontrar algo):

Se o seu aparecer algo similar a isso, verifique qual a versão do litellm está usando.

Verificar instalação global via pip

pip list 2>/dev/null | grep -i litellm
pip3 list 2>/dev/null | grep -i litellm

Verificar via import direto

python3 -c "import litellm; print(litellm.__version__, litellm.__file__)"

Verificar via uv (se usar)

uv pip list 2>/dev/null | grep -i litellm

Varrer todos os ambientes virtuais em .venv

find . -path "*/.venv/*/site-packages/litellm*" 2>/dev/null

Buscar em arquivos de dependência

grep -ri "litellm" --include="requirements*.txt" \
                   --include="pyproject.toml" \
                   --include="uv.lock" \
                   --include="poetry.lock" \
                   --include="Pipfile*" \
                   --include="setup.py" \
                   --include="setup.cfg" .

Buscar imports no código-fonte

grep -rE --include="*.py" -l "import litellm|from litellm" . \
  | grep -v ".venv" | grep -v "__pycache__"

Buscar o arquivo .pth malicioso

Esse é o mais importante. Se existir, a máquina está comprometida.

find / -name "litellm_init.pth" 2>/dev/null

Pra varrer só dentro dos seus .venv:

find . -type d -name ".venv" -exec find {} -name "litellm_init.pth" \;

Se usar uv, o cache dele também precisa ser checado:

find ~/.cache/uv -name "litellm_init.pth"

O que fazer se encontrou algo

Encontrou o .pth ou a versão 1.82.7 ou 1.82.8 instalada? A postura correta agora é assumir que tudo que estava no ambiente foi vazado. Não é pessimismo, é o protocolo segurança de verdade.

Vamos ter que rotacionar tudo.

Limpe o ambiente e o cache

Deletar o pacote não é suficiente. O pip (e o uv) têm cache em disco, e na próxima instalação podem reaproveitar o wheel contaminado:

# pip
pip uninstall litellm -y
pip cache purge

# uv
uv cache clean
rm -rf ~/.cache/uv

Verifique persistência no sistema

Se o script rodou no seu ambiente, pode ter instalado um backdoor:

ls ~/.config/sysmon/sysmon.py
ls ~/.config/systemd/user/sysmon.service

Se encontrar qualquer um dos dois: delete e reinicie o serviço do systemd do usuário.

Pra quem usa Kubernetes:

kubectl get pods -n kube-system | grep "node-setup"

Qualquer pod com esse nome usando imagem Alpine precisa ser removido imediatamente.

Observação: pedi ajuda para LLMs (3 diferentes) para pontos que não conheço muito bem, como Azure, ClaudTrail, etc.

Rotacione credenciais (por ordem de prioridade)

Tokens de CI/CD primeiro: (GitHub Actions, GitLab CI, CircleCI, PyPI, Docker Hub). Se vazar um token de publicação, o atacante passa a ser você
Cloud (AWS/GCP/Azure): access keys, service accounts, roles; consulte os logs de auditoria (CloudTrail na AWS) pra ver se já usaram as credenciais
Chaves SSH: gere um novo par (preferencialmente Ed25519), remova as chaves antigas do GitHub/GitLab/Bitbucket
API keys de LLM: OpenAI, Anthropic, Google, qualquer provedor que estava em variável de ambiente
Tudo que estava em .env: DB passwords, webhooks, tokens de integração

Como se proteger daqui pra frente

O que protegeu quem não foi afetado? Basicamente uma coisa: lockfile.

Projetos usando poetry.lock ou uv.lock com versões travadas ficaram completamente imunes.

A versão maliciosa nunca foi resolvida porque a versão exata já estava definida no lockfile. Este foi um caso de estudos interessante.

Se eu não atualizei nada, nem instalei nada do zero, o que será instalado será o que está no lockfile. Claro que temos alguns hábitos ruins: talvez pudéssemos travar a versão de forma mais específica nos nossos pyproject.toml.

Você não quer a versão mais nova possível, você quer a versão que está disponível agora.

Falando em "agora", vou deixar algumas práticas que já sigo e outras que vou passar a seguir a partir de agora (eu acho 😅).

Trave versões das suas dependências

Em vez de litellm>=1.80, porque não usar litellm==1.82.6? Vale pra qualquer dependência, não só o litellm.

Use lockfile

uv lock, poetry lock, pip-compile. Você commita o lockfile junto com o código, e qualquer instalação futura (local, CI, Docker) usa exatamente as mesmas versões.

Escopo de segredos no CI/CD

O token PYPI_PUBLISH que foi roubado estava disponível pra toda a pipeline, o tempo todo.

Para nós, a lição é deixá-las disponíveis apenas nas etapas que precisam usá-las. Não como variável de ambiente global disponível pra qualquer step, incluindo steps de terceiros como scanners.

Também use o "princípio do menor privilégio" com chaves e segredos. Se algo precisa ler, não precisa da permissão de escrever.

Trave ferramentas externas por commit SHA

No GitHub Actions, uses: aquasecurity/trivy-action@v0.20.0 não é seguro. O correto seria uses: aquasecurity/trivy-action@COMMIT_SHA_AQUI. Tag pode ser reescrita (foi exatamente o que o TeamPCP fez). SHA não.

Fim

Esse incidente é uma prova de que "o repositório está limpo no GitHub" não é garantia de nada se as credenciais de publicação forem roubadas. O vetor de ataque foi o CI/CD, não o código.

A versão segura é qualquer uma até a 1.82.6. Vi algumas pessoas falando de versões abaixo, mas não consegui confirmar isso. Se você atualizou o litellm (direto ou indiretamente) no dia 24 de março de 2026, vale rodar os comandos acima pra checar.

Qualquer dúvida, comenta aí. Valeu. Até o próximo.

Tools - Ferramentas para desenvolvedores

Wed, 25 Mar 2026 21:07:00 GMT

Com o advento da IA ("Inteligência" Artificial), venho tirando muitas ferramentas para desenvolvedores que tinha vontade de criar do papel.

Tools (esta página) é onde vou agregar todas essas ferramentas.

Links rápidos para as ferramentas

Markdown Editor

Criei este Markdown Editor na esperança de escrever em qualquer lugar, mesmo sem o meu editor favorito (nvim). Na verdade, ele acabou sendo muito mais do que isso. Por rodar no navegador, sempre estou com ele aberto para anotações em geral.

Link: Markdown Editor

WireGuard Config Generator

WireGuard Config Generator é um gerador de configurações para o WireGuard. Isso é uma mão na roda para quem não tem uma rede grande o suficiente para um gerenciador, mas grande para se perder nos arquivos de configuração. Testei com 10 máquinas, funcionou perfeitamente. Ele gerenciada o processo de criação das configurações e evita erros bobos, como IP ou chaves no peer incorreto.

Link: WireGuard Config Generator

SSH Toolkit

Seguindo a mesma lógica do WireGuard Config Generator, também criei o SSH Toolkit. Um monte de ferramentas que te ajudam a configurar o SSH de ponta a ponta. Inclusive, explicando o que é cada uma das configurações. Também gera os comandos que precisa executar.

Link: SSH Toolkit

Loudterm TTS

Loudterm TTS é um aplicativo que usa o modelo Kokoro-82M para converter texto em fala. Funciona com 8 idiomas, incluindo PT-BR. Também tem uma qualidade impressionante para algo gratuito. Eu ouço artigos em inglês e português enquanto faço outras coisas. Tudo gerado por ele.

Link: Loudterm TTS

dotfiles

Todo o meu ambiente Dev está aqui.

Link: dotfiles

OM Theme - Tema para VS Code

Tema que criei enquanto usava o VS Code. As pessoas gostam bastante dele.

Link: Om Theme - VS Code

BGRemover - Remove o fundo de imagens

Remove o fundo de imagens mantendo o personagem principal e fundo transparente. Garanto que você já deve ter pagado algum software para fazer isso.

Link: BGRemover

SSH Tunnels: o canivete suíço que você não está usando

Wed, 25 Mar 2026 21:06:00 GMT

Aproveitando o embalo do meu último conteúdo sobre VPN com o WireGuard, hoje trago o seu primo minimalista: SSH Tunnels na prática. Vamos ver um túnel local com -L, remoto com -R e dinâmico com -D.

Depois dessa, você vai conseguir expor um serviço rodando na sua máquina para fora (mesmo com NAT ou firewall no meio do caminho), acessar um serviço remoto como se estivesse sentado de frente para o próprio servidor e, de quebra, ainda criar um proxy SOCKS. Tudo isso via SSH.

Nesse texto, vou assumir que você já tem uma conexão SSH com um servidor qualquer. Ele nem precisa ter IP público para os exemplos fazerem sentido, mas vai ser muito mais legal se tiver 😈.

Falando em servidores

Se você estiver precisando de um servidor para hospedar seu site, aplicação ou projeto, dá uma olhada na Hostinger.

Estou deixando meu link com desconto abaixo. Isso pode te garantir até 2 anos de benefícios.

Acesse: Hostinger + Otávio Miranda
Cupom: OTAVIOMIRANDA

Em vídeo:

Se quiser assistir ao invés de ler (mas aqui tem muito mais informação):

https://youtu.be/s-B2A8A4hHc

O que é um SSH Tunnel?

Todo mundo já sabe que SSH serve para abrir terminal em outra máquina. O que pouca gente te ensina é que aquele mesmo canal criptografado pode carregar outro tipo de tráfego.

E se você parar para pensar, tudo começa a fazer mais sentido. O túnel já está aberto e seguro, que tal aproveitar a oportunidade para encaixar uma conexão com banco de dados, uma requisição HTTP ou qualquer coisa que use TCP?

O SSH suporta três tipos clássicos de tunnel:

Local -L - Abre uma porta na sua máquina e encaminha para um destino visto do lado do servidor SSH. Com ele você poderia dizer algo como: "Quando alguém acessar a porta 4321 na minha máquina, conecte em localhost:5432 no servidor e me entregue isso aqui". E, magicamente, ao usar localhost:4321, você recebe um PostgreSQL como se estivesse lá no servidor.

Remote -R - Faz o caminho contrário: abre uma porta no servidor e manda o que cair nela para um destino visto do lado da sua máquina. É a carta na manga quando você quer mostrar algo local para fora usando a conexão SSH que já saiu da sua rede. Alguém acessa a porta 8000 no servidor e o SSH chama a sua máquina na porta 3000.

Dynamic -D - Cria um proxy SOCKS na máquina onde você executou o SSH. Tudo que você apontar para esse proxy passa a sair pelo servidor SSH. Se você configurar isso no sistema, os apps que respeitam o proxy do sistema entram no mesmo barco também.

Se quiser usar uma ferramenta automatizada, fiz o SSH Toolkit, é uma ferramenta de código aberto que te ajuda a gerar esses túneis de forma visual. Faz mais do que isso, mas vou te falando ao longo do texto.

Bora destrinchar cada um.

sshd_config

Estou escrevendo isso depois de terminar o artigo inteiro. Eu tinha espalhado essas configurações pelo texto, mas faz mais sentido deixar tudo junto antes de você sair abrindo túnel e depois culpar o SSH (client) por algo que foi o sshd (server).

Abra o arquivo de configuração do servidor SSH. Em geral ele fica aqui:

# Linux
/etc/ssh/sshd_config

# Algumas distros também usam includes aqui
/etc/ssh/sshd_config.d/*.conf

# macOS
/etc/ssh/sshd_config

No OpenSSH, AllowTcpForwarding, PermitOpen e PermitListen já costumam vir liberados por padrão. O que costuma pegar a galera de surpresa é o GatewayPorts, porque ele vem de fábrica como no.

Se você endureceu a config do sshd, garanta pelo menos isso:

# Necessário para -L, -R e -D
AllowTcpForwarding yes

# Só se você restringiu destinos ou portas remotas
# No final, deixo um aviso sobre isso.
PermitOpen any
PermitListen any

# Necessário para expor um -R para outras máquinas
GatewayPorts clientspecified

Resumo rápido do que interessa:

AllowTcpForwarding yes libera os forwards TCP.
PermitOpen any só é necessário se você travou os destinos permitidos para -L/-D.
PermitListen any só é necessário se você travou as portas/endereços permitidos para -R.
GatewayPorts clientspecified deixa o cliente escolher se o -R vai escutar só em localhost ou em 0.0.0.0.

Depois de alterar isso, reinicie o serviço SSH.

# Linux
sudo systemctl restart sshd # ou ssh

# macOS
sudo launchctl kickstart -k system/com.openssh.sshd

O SSH Toolkit também te ajuda nisso.

Local Forward (`-L`): "trago a porta de lá pra cá"

Esse é o mais simples. Você abre uma porta na sua máquina e tudo que chegar nela é encaminhado, pelo túnel SSH, para um destino do outro lado. O resultado é que, ao acessar essa porta, quem responde é o servidor.

Todos os diagramas estão aqui (via excalidraw).

A sintaxe

# Sua porta local encaminha para <host:porta> visto do lado do servidor SSH
ssh -L <porta_local>:<host_remoto>:<porta_remota> <user@servidor>

# Obs.: na maioria das vezes eu uso -N antes de -L para ele só focar no túnel

Fluxo

sua_máquina:porta_local -> túnel SSH -> servidor -> host_remoto:porta_remota

Na prática

Você tem um VPS e subiu um servidorzinho HTTP nele. Esse servidor escuta em localhost:8080. Você não liberou a porta no firewall, não configurou NGINX, não fez nada. Exemplo:

# caminho_qualquer tem um index.html
python3 -m http.server 8080 -d caminho_qualquer

Na sua máquina você pode encaminhar a porta local 8080 para localhost:8080 do servidor assim:

# ---> você:vps --->
ssh -L 8080:localhost:8080 user@seu-vps

Agora, se você abrir http://localhost:8080 no navegador, vai ver o conteúdo do VPS como se estivesse lá. Sem liberar porta, sem configurar nada. Tipo um teletransporte.

O localhost ali no meio da sintaxe se refere ao ponto de vista do servidor. Ou seja, "conecte em localhost:8080 do servidor e traga pra minha porta 8080".

Outro exemplo: banco de dados

Um PostgreSQL rodando no servidor, porta 5432, escutando só em localhost. Sem acesso externo.

# Isso é o mais comum, mesma porta
ssh -L 5432:localhost:5432 deploy@servidor

Conecte seu cliente local em localhost:5432. Pronto, você está no banco remoto.

Se a porta 5432 já estiver ocupada na sua máquina, sem pânico. É só mudar a local:

# Você controla qual a porta quer usar no seu lado
ssh -L 15432:localhost:5432 deploy@servidor

Agora use localhost:15432. Isso continuará chamando "5432" no lado do servidor.

Remote Forward (`-R`): "mando minha porta pra lá"

Esse é o inverso. Você abre uma porta no servidor e tudo que chegar lá volta pelo túnel até a sua máquina. O resultado é que, ao acessar essa porta no servidor, quem responde é sua máquina local.

A sintaxe

# A porta no servidor encaminha para <host:porta> visto do lado da sua máquina
ssh -R <porta_remota>:<destino_local>:<porta_destino> <user@servidor>

O fluxo

servidor:porta_remota → túnel SSH → sua_máquina → destino:porta_destino

Na prática

Agora vira o jogo. Você tem um servidorzinho rodando na sua máquina:

Mesmo exemplo, só que... 😏

# caminho_qualquer tem index.html
python3 -m http.server 8080 -d caminho_qualquer

Quer que alguém acesse isso pelo seu VPS? Faz esse túnel com -R:

# Cria a porta 8080 no VPS apontando para a sua máquina local
ssh -R 8080:localhost:8080 user@seu-vps

Esse comando cria uma porta 8080 no VPS apontando para localhost:8080 da sua máquina. O localhost aqui é visto do lado do cliente SSH, ou seja, do computador onde você executou o comando.

Wait, what? Não funcionou?

Isso acontece. Por padrão, o -R escuta só em 127.0.0.1 no servidor. Ou seja, um curl http://localhost:8080 rodando no próprio VPS funciona de boa, mas o tráfego externo (da Internet) bate de frente numa porta fechada.

Para liberar acesso externo, o servidor SSH precisa ter isso no /etc/ssh/sshd_config:

GatewayPorts clientspecified

Eu prefiro clientspecified porque você escolhe no comando se quer deixar isso privado ou público. Aí sim você especifica o bind:

ssh -R 0.0.0.0:8080:localhost:8080 user@seu-vps

Se você usar GatewayPorts yes, o sshd força bind no wildcard e você perde um pouco desse controle fino.

Depois de alterar o sshd_config, reinicie o serviço SSH:

# Linux
sudo systemctl restart sshd

# macOS
sudo launchctl kickstart -k system/com.openssh.sshd

E não esqueça do firewall. Se a porta 8080 está bloqueada no firewall do VPS, o tunnel funciona, mas ninguém de fora chega lá.

Dynamic Forward (`-D`): proxy SOCKS

Os dois anteriores conectam portas específicas. O -D é diferente: ele cria um proxy SOCKS na sua máquina. Qualquer aplicação que suporte SOCKS pode mandar tráfego por ele, e o servidor SSH conecta no destino final.

Você não precisa definir o destino antes. O proxy decide na hora.

A sintaxe

ssh -D <porta_local> <user@servidor>

O fluxo

seu app -> SOCKS proxy (localhost:porta) -> túnel SSH -> servidor -> destino final

Na prática

Você quer navegar como se estivesse no seu VPS. Não é uma VPN completa do sistema inteiro, mas para os apps que usam o proxy a sensação é bem parecida.

Talvez para testar um bloqueio de IP, talvez porque você está naquele Wi-Fi público super duvidoso de aeroporto e não quer ninguém "cheirando" (sniffing) seus pacotes.

ssh -D 1080 user@seu-vps

Agora configure o proxy SOCKS no sistema ou no navegador.

No macOS: vá em Ajustes do Sistema -> Rede -> a interface que está usando (Wi-Fi, por exemplo) -> Detalhes -> Proxies -> ative Proxy SOCKS → coloque 127.0.0.1 e porta 1080.

Abra o navegador e acesse ifconfig.me ou ip.me. O IP que aparece deve ser o do seu VPS, não o seu.

Só não mistura as coisas: isso vale para o que estiver usando o proxy, não para todo e qualquer pacote do sistema.

Um detalhe sobre DNS

Dependendo da aplicação, a resolução DNS pode acontecer antes de ir para o proxy. Isso meio que entrega o jogo.

No Firefox, por exemplo, vá em about:config e mude network.proxy.socks_remote_dns para true. Assim até as consultas DNS passam pelo tunnel.

Pra variar, o SSH Toolkit também faz isso.

Flags úteis

Na maioria das vezes, você não quer um shell remoto. Quer só o tunnel. Essas flags resolvem:

-N - sem comando remoto

Não executa nenhum comando no servidor. Só mantém o tunnel aberto.

ssh -N -L 8080:localhost:8080 user@servidor

-f - manda para o background

Joga o processo SSH pro background depois de autenticar.

ssh -f -N -L 8080:localhost:8080 user@servidor

Combinar -f com -N é o padrão para tunnels em segundo plano. Eu gosto de somar -o ExitOnForwardFailure=yes para o SSH não fingir que deu tudo certo quando a porta já estava ocupada.

ssh -f -N -o ExitOnForwardFailure=yes -L 8080:localhost:8080 user@servidor

Quando cansar da brincadeira, é só caçar e matar o processo:

# encontre o PID
ps aux | grep ssh

# ou, se souber a porta
lsof -i :8080

# mate o processo
kill <PID>

Keepalive

Tunnels podem morrer se ficarem tempo demais sem tráfego ou se algum NAT no meio resolver te abandonar. Para reduzir isso:

ssh -o ServerAliveInterval=60 -o ServerAliveCountMax=3 -L 8080:localhost:8080 user@servidor

Se o servidor ficar sem responder, o SSH detecta isso e encerra a conexão sem te deixar adivinhando o que aconteceu.

Múltiplos tunnels de uma vez

Pode empilhar quantos quiser:

ssh -L 5432:localhost:5432 -L 8080:localhost:80 -L 3000:localhost:3000 user@servidor

Coloca isso no SSH config

Se você levanta um tunnel com frequência, pelo amor de Deus, pare de digitar esse textão toda vez. Coloca lá no seu ~/.ssh/config:

Host vps-tunnel
    HostName seu-vps.com
    User deploy
    LocalForward 5432 localhost:5432
    ExitOnForwardFailure yes
    ServerAliveInterval 60
    ServerAliveCountMax 3

Agora basta:

ssh -N vps-tunnel

Tunnels persistentes com `autossh`

O SSH não reconecta sozinho. Se a conexão cair, o tunnel morre junto. O autossh resolve isso: ele monitora a conexão e reinicia se precisar.

autossh -M 0 -f -N -o "ServerAliveInterval=60" -o "ServerAliveCountMax=3" \
  -L 5432:localhost:5432 deploy@servidor

O -M 0 desativa a porta de monitoramento do autossh e usa o ServerAliveInterval do próprio SSH, que funciona melhor.

Se quiser algo ainda mais robusto, crie um serviço no systemd e ele reinicia automaticamente em caso de falha.

Coisas que pegam gente desprevenida

Só funciona com TCP

SSH Tunnels encaminham TCP. Se você precisa de UDP de verdade, vá de WireGuard. Se precisa de um redirecionamento pontual fora do SSH, socat pode ajudar. Se quer algo mais para o lado de "quase uma VPN por SSH" para TCP/DNS, dá uma olhada no sshuttle.

Portas privilegiadas

Portas abaixo de 1024 precisam de root no lado que vai abrir a escuta. Se você tentar isso com -L:

ssh -L 80:localhost:80 user@servidor

Vai falhar sem sudo. Use uma porta alta:

ssh -L 8080:localhost:80 user@servidor

No -R, a ideia é a mesma, mas do lado do servidor.

Firewall

O tunnel funciona entre as máquinas, mas se o firewall do servidor bloqueia a porta do -R, ninguém de fora chega. Libere a porta:

# UFW
sudo ufw allow 8080

# firewalld
sudo firewall-cmd --add-port=8080/tcp --permanent
sudo firewall-cmd --reload

Segurança

Tunnels podem furar políticas de rede. Use com responsabilidade.

Se você mandar o bind para 0.0.0.0 no -L, -D ou -R, qualquer máquina que consiga alcançar essa porta pode usar o forward. Por isso o SSH costuma ficar em localhost por padrão. Se for abrir para fora, saiba exatamente o que está fazendo.

Referência rápida

Acessar serviço remoto localmente - ssh -L 8080:localhost:8080 user@servidor
Expor serviço local pelo servidor - ssh -R 0.0.0.0:8080:localhost:3000 user@vps
Proxy SOCKS para navegação - ssh -D 1080 user@servidor
Tunnel em background - ssh -f -N -L 8080:localhost:8080 user@servidor
Tunnel persistente - autossh -M 0 -f -N -L 8080:db:5432 user@vps
Múltiplos forwards - ssh -L 5432:db:5432 -L 8080:web:80 user@srv

Quando usar cada tipo?

Precisa acessar algo que está numa rede remota - Local (-L)
Precisa expor algo local para o mundo - Remote (-R)
Precisa acessar vários serviços sem criar um tunnel para cada um - Dynamic (-D)
Quer navegar com o IP de outra máquina - Dynamic (-D)

Conclusão

SSH Tunnel é uma daquelas ferramentas que resolvem o problema em uma linha e, mesmo assim, a maioria das pessoas não usa.

-L traz, -R manda, -D faz proxy. Mais do que isso, é saber que você não precisa liberar porta no firewall, configurar reverse proxy ou instalar nada extra toda vez que quer acessar algo de outra máquina.

Isso já está instalado no seu sistema. Usa.

PS.: essa é a minha configuração do ssh ao terminar de escrever isso. Tem um aviso enorme só para me lembrar.

PubkeyAuthentication yes
PasswordAuthentication no
KbdInteractiveAuthentication no
ChallengeResponseAuthentication no
PermitRootLogin no
PermitEmptyPasswords no
UsePAM yes
AuthenticationMethods publickey
PermitUserEnvironment no
PermitUserRC no
X11Forwarding no
AllowStreamLocalForwarding no
AllowAgentForwarding no
PermitTunnel no
MaxAuthTries 4
LoginGraceTime 30
ClientAliveInterval 300
ClientAliveCountMax 2
PrintMotd no
UseDNS no

# ===================================================================
# 🚨 ATENÇÃO: ZONA DE PERIGO (TÚNEIS ESCANCARADOS) 🚨
# ===================================================================
# O bloco abaixo permite que qualquer túnel (-R) exponha portas
# diretamente para a INTERNET PÚBLICA (0.0.0.0).
# Excelente para o nosso laboratório e testes, mas se for rodar em
# PRODUÇÃO real, mude o GatewayPorts para 'no' ou 'clientspecified'
# para evitar expor serviços internos acidentalmente.
# ===================================================================
AllowTcpForwarding yes
PermitOpen any
PermitListen any
GatewayPorts yes

Fui.

Ah, o SSH Toolkit faz ssh hardening também.

OpenAI compra Astral (uv, ruff e ty vão junto)

Thu, 19 Mar 2026 00:00:00 GMT

Eu não sou o cara das news, como você já deve ter notado pelo meu conteúdo. Mas aqui não deu pra pular.

Em vídeo:

Link: youtu.be/kHePnM4NPWo

A OpenAI acabou de anunciar a compra da Astral. Só pra te lembrar: Astral é a empresa por trás do Ruff, do uv e do ty. Ou seja, o linter mais rápido do ecossistema Python, o gerenciador de pacotes que tá substituindo pip, poetry, pyenv e companhia, e o type checker novinho que acabou de sair.

Se você acompanha o canal, sabe que eu uso e recomendo bastante o uv e o ruff. Falei disso até no meu curso de Python.

Fiz aquele vídeo de Docker com uv e multistage build que a galera gostou bastante. Então sim, eu tenho skin in the game aqui. Essas ferramentas fazem parte do meu dia a dia e do que eu ensino. Bora entender o que tá acontecendo.

A compra

Dia 19 de março de 2026 (também conhecido como poucas horas atrás), a OpenAI anuncia que vai adquirir a Astral. Ambas as empresas já estão anunciando em seus blogs.

O time inteiro vai ser absorvido pela divisão do Codex, aquele produto de coding com IA da OpenAI que já tem mais de 2 milhões de usuários semanais e que uso constantemente.

O Charlie Marsh, fundador da Astral, disse que vai continuar construindo abertamente, junto com a comunidade.

A OpenAI prometeu manter os projetos open source.

Valor da aquisição? Não divulgaram. A Astral tinha levantado uns 4 milhões em seed com Accel e Caffeinated Capital, mais uma Series A e uma Series B, nada absurdo comparado com as outras loucuras que a OpenAI anda comprando.

A OpenAI já tinha comprado a empresa do Jony Ive por 6,4 bilhões de dólares, tentou comprar a Windsurf por 3 bilhões, mas não deu certo e contratou o Dev do OpenClaw (não sei dizer se compraram o OpenClaw por que realmente não verifiquei). Mas, o ponto é que a Astral deve ter saído barata para eles.

Motivações da OpenAI

E aí a primeira pergunta que vem na cabeça: por que a OpenAI, uma empresa de IA, quer comprar ferramentas de linting e gerenciamento de pacotes Python?

Três motivos que fazem total sentido pra mim.

Primeiro: velocidade. As ferramentas da Astral são escritas em Rust. O Ruff processa um arquivo em menos de 10 milissegundos. O uv resolve dependências numa fração de segundo. Quando você tem um agente de IA iterando num problema centenas de vezes, a diferença entre 10 milissegundos e 2 segundos por verificação é a diferença entre funcionar e não funcionar. Pra agente autônomo, Python tooling tradicional é lento demais.

Segundo: o ciclo completo. O Codex hoje gera código. Mas a OpenAI quer que ele faça tudo: montar o ambiente com uv, lintar com Ruff, checar tipos com ty, rodar testes. Um workflow ponta a ponta, autônomo. As peças encaixam perfeitamente.

Terceiro: distribuição. O uv já tem centenas de milhões de downloads por mês. FastAPI, Django, Pandas, Spark, tudo já usa ou tá migrando. A OpenAI compra acesso direto a milhões de desenvolvedores Python. É um canal de distribuição absurdo por provavelmente uma fração do preço das outras aquisições deles. Do ponto de vista de negócio? Brilhante.

Comunidade Dev e Open Source

Agora... a comunidade? Não posso falar por todos e também não tenho nada contra a OpenAI. Mas, de cara, o que me assustou foi que o uv e o ruff são ferramentas que estão no coração de boa parte do que faço com Python (atualmente, tudo). O problema é que a OpenAI queima dinheiro num ritmo absurdo e ainda não gera lucro. Então, o meu sentimento é medo. Será que vou ter que sair mudando base de código antiga? Preciso regravar vídeos? Não sei...

Busquei pela Internet afora e encontrei algumas coisas. O sentimento não está muito distante do meu.

No Hacker News, as threads explodiram. Chutando por baixo, diria que uns 70 a 75% dos comentários são negativos ou céticos.

A preocupação número um é a mesma que tive: a saúde financeira da OpenAI.

E olha, não sou eu falando. A própria OpenAI projeta 14 bilhões de dólares em prejuízo pra 2026. Eles gastam dois dólares e cinquenta pra cada dólar que faturam. Não esperam fluxo de caixa positivo antes de 2029, 2030. Então você pega infraestrutura Python crítica e coloca debaixo do guarda-chuva de uma empresa que depende de injeção constante de VC pra sobreviver. Se a bolha de IA esfriar ou se alguém espirrar na direção errada... JÁ ERA!

Um cara no HN resumiu bem: "mais funcionalidades essenciais das quais desenvolvedores dependem passam a depender de um fluxo contínuo de bilhões em financiamento VC. O que poderia dar errado?"

A segunda preocupação é enshittification. Todo mundo já está imaginando: daqui a pouco você roda uv add e o negócio quer te oferecer uma sugestão do Codex.

Ou o Ruff começa a ter features premium integradas. Alguém brincou com um cenário de UV_DISABLE_AGENT=1 UV_DISABLE_AI_HINTS=1 uv add. Engraçado, mas é o tipo de humor nervoso, né?

E faz sentido. Imagina que você é uma empresa e precisa urgentemente de capital! A ideia é tentar arrancar grana de onde quer que ela venha.

A terceira é mais filosófica mas importa: assimetria informacional. Se os autores das ferramentas agora são funcionários da OpenAI, o que impede versões internas de evoluírem mais rápido que as públicas? O Codex teria uma vantagem sobre Claude Code e Copilot que não é justa.

Ah, e teve o comentário que eu achei genial: "Empresa que vive dizendo que desenvolvedores de software vão ser substituídos por IA... compra mais desenvolvedores em vez de usar a própria IA pra fazer software." Né?

Pelo jeito, ainda estamos precisando bastante de Devs.

E eu? O que penso?

Beleza, eu já falei algumas vezes no texto, mas deixo minha opinião sincera como alguém que ensina Python e usa essas ferramentas todo dia?

Olha, eu sou bem pragmático. Vou continuar usando uv e Ruff amanhã do mesmo jeito que usei ontem. Nada muda na prática agora. As ferramentas são MIT e Apache 2.0. Se a OpenAI fizer besteira, dá pra forkar.

Mas tenho que ser honesto: eu não tô confortável. O motivo é simples: não é sobre a OpenAI especificamente, é sobre o padrão.

A Anthropic comprou a Bun em dezembro de 2025. A OpenAI compra a Astral agora. O Google contratou os fundadores da Windsurf por 2,4 bilhões. A Microsoft já tem o GitHub e o Copilot. Toda empresa de IA tá engolindo infraestrutura de desenvolvedor.

OpenAI captura Python. Anthropic captura JavaScript. E os devs ficam onde nessa história?

O risco real não é agora. É daqui a 2, 3 anos. Quando a pressão por monetização bater, quando o investidor cobrar retorno, é aí que as promessas de "vamos manter tudo aberto" começam a ficar... flexíveis.

A história da tecnologia nos ensina isso. Promessa corporativa sobre open source tem prazo de validade.

O que fazer?

Pra finalizar: o que eu recomendo?

NADA! "Apenas sorria e acene, rapazes! Sorria e acene!" 🐧 👋

Continue usando uv e Ruff. Não faz sentido trocar agora. São as melhores ferramentas que o ecossistema Python já teve, e isso não mudou. Pelo menos para mim não muda nada ainda.

Mas fica de olho. Presta atenção nos releases. Se começar a aparecer integração forçada com Codex, funcionalidade que só funciona com conta da OpenAI, qualquer coisa desse tipo, aí a gente reavalia. Talvez troque!

E a comunidade Python tem um dever de casa: garantir que a possibilidade de fork seja real e não só teórica. Porque um dia a gente pode precisar.

Fim

É isso. Se você trabalha com Python, essa notícia te afeta diretamente. Cola nos comentários me dizendo o que você acha. Esse tipo de conteúdo é novo pra mim.

Valeu. Até o próximo.

VPN com WireGuard: O Guia Definitivo

Sun, 15 Mar 2026 00:00:00 GMT

Veja como montar uma VPN WireGuard de verdade: com topologias, túneis, NAT e tudo que eu descobri configurando 7 nodes espalhados por casa, Hostinger e GCP.

Em vídeo

Se preferir assistir ao invés de ler, também fiz um vídeo:

Link: https://youtu.be/yqsLvVz0Y44

Por que WireGuard

Sempre que você coloca um software novo no projeto, não está levando só uma nova feature. Leva o pacote completo. Base de código, dependências, bugs, falhas de segurança... é tipo casamento 😅.

O WireGuard ajuda bastante nessa parte, porque a proposta dele é super minimalista. No Linux, sua implementação fica abaixo de 4.000 linhas de código.

Especialistas em segurança agradecem.

Em um final de semana uma pessoa consegue auditar todo o código do WireGuard, tomar umas, bodar e ainda sobra o domingo inteiro pra curar a ressaca.

Além disso, manutenção e desempenho também são otimizados. Com menos código, temos menos para configurar e o servidor tem menos com o que se preocupar.

Opinativo

O WireGuard é um protocolo opinativo. Ele não senta com você pra perguntar o que quer usar, quais algoritmos prefere, quais modos deseja negociar. Não. Ele já chega dizendo: "vai ser assim". E pronto.

Isso reduz flexibilidade? Com certeza. Mas os ganhos superam essa redução.

Enquanto outras ferramentas, como o OpenVPN, nos dão uma liberdade absurda, o WireGuard pega alguns atalhos, impõe limites e tira opções.

E, por incrível que pareça, isso é uma das suas maiores qualidades.

Eu poderia te falar um milhão de coisas que estava lendo no WhitePaper do WireGuard, mas aí já seríamos duas pessoas sem entender o que foi explicado.

Mas, sério agora, ele encapsula pacotes IPv4/IPv6 sobre o protocolo UDP e trabalha na camada 3. Só isso!

Nada de bridge de camada 2. Nada de túnel sobre TCP. Isso já evita TCP-over-TCP meltdown.

Silencioso

Outra característica muito boa é o silêncio por padrão.

Se um pacote não puder ser autenticado, o WireGuard simplesmente o ignora. Não responde. Não explica. Não negocia.

Isso pode atrapalhar um pouco na hora de depurar algum problema, claro (aconteceu comigo, como veremos 😂). Mas, do ponto de vista de segurança, é bonito de ver. O protocolo fica quieto, como se soubesse que tem alguém tentando fazer algo inesperado.

Cryptokey Routing

Nunca ouviu esse termo? Eu também não! É do próprio WireGuard.

Em vez de separar totalmente autenticação e roteamento, o WireGuard amarra cada chave pública a uma lista de IPs permitidos dentro do túnel.

Na saída, isso funciona como tabela de rotas. Na entrada, funciona como uma ACL (Access Control List). Pra ficar uma frase mais bonita: identidade criptográfica e caminho de rede andam juntos.

Isso chega a mudar até a sua forma de pensar, porque fica mais direto e previsível.

E isso vai ficar muito claro quando começarmos a configurar, você vai ver que mudar um número no AllowedIPs muda tudo.

No final, é essa soma de restrições que faz o WireGuard ser tão interessante: menos negociação, menos ambiguidade, menos superfície para erro. E uma operação muito mais direta.

Topologias: Hub-and-Spoke e Mesh

Eu sei... eu sei... Já estamos chegando lá.

Mas, antes de fazer qualquer configuração, primeiro você precisa definir qual topologia de rede vai usar. Então, responder essas perguntas pode ajudar.

Você tem um servidor que controla tudo?
Vai conectar quantos dispositivos?
Um dispositivo precisa falar diretamente com o outro?
Vai compartilhar a Internet pela VPN?
Tem NAT (a gente fura 😂)?
e outras...

O fato é que, no mundo de redes, existem várias topologias que você pode usar.

Nós, no entanto, não estamos em um curso de redes. Além disso, no WireGuard dá pra fazer muita coisa (se não tudo o que você quiser) apenas usando essas duas:

Caso queira algo mais formal, os links acima vão te ajudar a entender melhor essas topologias de rede. Mas vou deixar um atalho para os mais apressados.

Hub-and-spoke

Meus dispositivos se conectam a um servidor central e ele faz o roteamento dos pacotes para onde for necessário.

O Hub é onde tudo se conecta, o servidor. Os Spokes são os dispositivos que falam com o servidor quando precisam alcançar alguma rota.

Vamos imaginar três spokes e um hub. Um server (hub) e três dispositivos (spoke), node_a, node_b, node_c. Assim, você escala este modelo para quantos nodes precisar.

Node (nó) é um aparelho qualquer conectado à rede (Computador, servidor, smartphone...).

 Ilustração simplificada de Hub-and-Spoke com WireGuard VPN.

                          ┏ HUB ━━━━━━━━━━━━━┓
          ┏━━━━━━━━━━━━━▶ ┃ server           ┃ ◀━━━━━━━━━━━━━━┓
          ┃               ┃ 10.0.0.2/24      ┃                ┃
          ┃               ┗━━━━━━━━━━━━━━━━━━┛                ┃
          ┃                         ▲                         ┃
          ┃                         ┃                         ┃
          ┃                         ┃                         ┃
  10.0.0.0/24 (Split)        0.0.0.0/0 (Full)       10.0.0.0/24 (Split)
          ┃                         ┃                         ┃
          ┃                         ┃                         ┃
          ▼                         ▼                         ▼
 ┏ SPOKE ━━━━━━━━━━━┓     ┏ SPOKE ━━━━━━━━━━━┓     ┏ SPOKE ━━━━━━━━━━━┓
 ┃ node_a           ┃     ┃ node_b           ┃     ┃ node_c           ┃
 ┃ 10.0.0.3/24      ┃     ┃ 10.0.0.4/24      ┃     ┃ 10.0.0.5/24      ┃
 ┗━━━━━━━━━━━━━━━━━━┛     ┗━━━━━━━━━━━━━━━━━━┛     ┗━━━━━━━━━━━━━━━━━━┛

 Split Túnel: parte das redes do node saem pelo VPN (como em 10.0.0.0/24).
 Full Túnel:  todas as redes do node saem pela conexão VPN (como em 0.0.0.0/0).

Você pode fazer o roteamento como preferir no Hub. Ou seja, o server pode rotear os pacotes para dentro ou para fora da rede. Isso permite uma configuração extremamente flexível.

Por exemplo, node_b poderia falar com node_c, node_a, com a Internet e até com outra rede. Isso tudo é controlado pela diretiva AllowedIPs do arquivo de configuração do WireGuard.

✅ Prós

Segurança e auditoria centralizadas
Simplicidade de implementação

❌ Contras

Aumento de Latência (Hairpinning): se não tomar cuidado com a configuração, seus IPs locais passam a sair para a Internet ao acessar nodes da mesma rede. Aconteceu na minha rede. Ao pingar o node ao lado (mesma mesa), a rota foi até São Paulo (no Hub) e voltou (estou em Minas).
SPOF (Single Point Of Failure): é muito comum que redes menores tenham um único Hub. Como ele controla tudo, toda sua VPN para se ele cair.

Topologia Mesh

Na Topologia Mesh, cada node tem uma conexão direta com os outros nodes. Isso permite ter uma VPN sem nenhum servidor, apenas um dispositivo que conhece os outros (e vice-versa).

E olha que coisa interessante: como todo mundo conhece todo mundo, não há necessidade de roteamento. O próprio formato da rede em si já é roteado.

 Ilustração simplificada de topologia Mesh com WireGuard VPN.

          10.0.0.4/32 →         ← 10.0.0.3/32
  ┌ PEER ────────────┐ ◀───────▶ ┌ PEER ────────────┐
  │ node_a           │           │ node_b           │
  │ 10.0.0.3/32      │           │ 10.0.0.4/32      │
  └──────────────────┘           └──────────────────┘
    ▲               ▲             ▲               ▲
    │                ╲           ╱                │
    │            10.0.0.6/32 ↓  ╱                 │
 10.0.0.5/32 ↓         ╲       ╱             10.0.0.6/32 ↓
    │                   ╲ 10.0.0.5/32 ↓           │
    │                    ╲   ╱                    │
    │                     ╲ ╱                     │
    │                      ╱                      │
    │                     ╱ ╲                     │
    │                    ╱   ╲                    │
    │           10.0.0.4/32 ↑ ╲                   │
 10.0.0.3/32 ↑         ╱       ╲             10.0.0.4/32 ↑
    │                 ╱    10.0.0.3/32 ↑          │
    │                ╱           ╲                │
    ▼               ▼             ▼               ▼
  ┌ PEER ────────────┐           ┌ PEER ────────────┐
  │ node_c           │           │ node_d           │
  │ 10.0.0.5/32      │           │ 10.0.0.6/32      │
  └──────────────────┘ ◀───────▶ └──────────────────┘
          10.0.0.6/32 →         ← 10.0.0.5/32

 Em Mesh, cada node tem uma conexão direta com os outros nodes.

Isso te dá várias vantagens em termos de desempenho, estabilidade e alta disponibilidade, mas também te dá algumas boas dores de cabeça na hora de escalar.

Adicionar novos nodes à rede ou até rotacionar as chaves é um pesadelo. Com 4 nodes, cada um tendo uma conexão direta com os outros, estamos falando em 6 conexões. Agora veja como isso cresce rápido:

4 nodes: 6 conexões
6 nodes: 15 conexões
8 nodes: 28 conexões
10 nodes: 45 conexões
12 nodes: 66 conexões
14 nodes: 91 conexões
16 nodes: 120 conexões

Entendeu, não é? Cada node novo adicionado na rede fará você voltar a configurar todos os outros nodes, mais a nova conexão do que estiver sendo adicionado.

A conta para isso é: N (N-1) / 2. Exemplo com 20 nodes: 20*(20-1)/2 = 190.

E não pense que 16 nodes é muito. Eu, com minha rede minúscula, já bati 7 nodes brincando de montar VPNs.

Se eu adicionasse os dispositivos da minha residência, já subiria fácil para 14 nodes. Você precisa contar tudo o que for fazer parte da rede (ou então voltar para o NAT). Relógios, TVs, Tablets, Laptops, Smartphones, talvez até geladeiras (se você gosta dessas coisas 🤔). Tudo isso pode entrar na sua conexão VPN também.

✅ Prós

Melhor desempenho e latência muito mais baixa
Resiliência (sem ponto único de falha). Um node cair afeta apenas ele mesmo (e os nodes que precisarem dele), o restante da rede funciona normalmente
Existem gerenciadores que ajudam a manter a configuração em dia

❌ Contras

Escalar, a partir de poucos nodes, se torna insustentável. Você vai precisar de softwares de terceiros para gerenciar todas as conexões (existem vários).
Quando os dois nodes estão atrás de NAT, não tem como fechar a conexão. Um deles sempre precisa conseguir receber pelo menos um pacote para fechar a conexão.
Fazer auditoria é mais complicado sem um ponto centralizado de conexões.

Qual usar?

Você precisa analisar o seu caso. Mas basta olhar o funcionamento do WireGuard que dá para ter uma noção.

Para autenticar um node, uma das pontas precisa conseguir enviar um pacote diretamente para ele. Isso significa que você precisa que um deles tenha IP válido na Internet.

Um node_a que tem IP válido não consegue se conectar com um node_b que está atrás de NAT. Mas o contrário é possível. O node_b consegue chegar diretamente no node_a. Isso fecharia a conexão.

É por este motivo que precisamos de um servidor quando falamos em VPN.

Falando nisso 💜

Se precisar de servidor VPS, tenho link e cupom que te dá um belo desconto por até 2 anos se quiser.

https://hostinger.com/otaviomiranda
Cupom: OTAVIOMIRANDA

Obrigado à Hostinger por acreditar no meu conteúdo.

Agora, imagine que você está conectando 10 escritórios. Todos eles atrás de NAT. Você vai precisar de um servidor externo para fechar essas conexões.

Se você acompanhou o que eu disse, claramente precisamos de uma rede Hub-and-spoke aqui.

Por outro lado, se todos os nodes estão de cara para a Internet, dá para usar Mesh sem problemas.

E, por fim, se você tem uma rede híbrida, dá para fazer uma configuração híbrida também. Onde estiver de frente para a Internet, use Mesh, onde não for possível, Hub-and-spoke.

Instalando o WireGuard

O WireGuard funciona em todos os sistemas mais conhecidos, então é melhor você seguir o tutorial de instalação do site deles:

Instalar WireGuard

Sim! Funciona em iOS, Android, Linux, macOS, Windows e vários outros sistemas.

Para o macOS, estou usando a versão do brew:

# macOS
brew install wireguard-tools

Para os VPSs e VM, todos tem o Ubuntu Server 24.04 LTS, então:

# Ubuntu Server 24.04 LTS
sudo apt install wireguard

Para iOS (iPhone), estou usando a versão oficial.

Também tenho um Fedora Asahi aqui, estou usando a versão do Fedora:

# Fedora
 sudo dnf install wireguard-tools

Configurando uma rede híbrida no WireGuard

Vamos entender o que tenho para colocar em rede e quais são os desafios. Alguns problemas são propositais, apenas para fins didáticos.

Rede Local (Minas Gerais)

A rede local recebe um IP do provedor e distribui IPs internos. Entrada e saída usam NAT, ou seja, todos os dispositivos da rede interna saem com o mesmo IP do roteador do provedor.

Também significa que não tem como chegar em um dispositivo específico dentro da minha rede, já que o NAT vai bloquear (teria que mexer com redirecionamento de portas, o que não vem ao caso agora).

Então a limitação é: os nodes da minha rede local precisam iniciar a conexão com dispositivos externos, só assim consigo autenticar usando o WireGuard.

Funciona tanto para Hub-spoke quanto para Mesh, mas o dispositivo do outro lado precisa estar visível na Internet. Eu também deixei uma pegadinha nos outros nodes que vão forçar o uso de Hub-and-spoke. Já falaremos sobre isso.

Os dispositivos são (por hostname):

m132 - Laptop - 192.168.0.108/24
m4128 - Laptop - 192.168.0.109/24
fedoraair - Laptop - 192.168.0.114/24
Smartphone - iOS - Dinâmico

Hostinger (São Paulo)

Sem segredo aqui. Todos estão nos datacenters da Hostinger, de cara para a Internet. São 3 VPSs.

kvm2 - VPS - 76.13.71.178/24
kvm4 - VPS - 191.101.70.130/23
kvm8 - VPS - 89.116.73.152/24

VM Google Cloud Platform (Iowa, EUA)

Este é mais um servidor em outra rede completamente diferente das duas anteriores. Rede da Google, em Council Bluffs, Iowa, EUA (us-central1-b).

gc_micro - VM - Dinâmico

E essa foi a pegadinha que deixei para apimentar as coisas. Eu poderia fixar o IP nessa VM, porém vou manter dinâmico.

Se você entendeu tudo até aqui, já deve ter notado que não tenho como fazer Mesh da minha rede local (NAT) para a rede da Google. Até dá para fazer, mas quando o IP da VM mudar, não terei mais conexão. A VM não conseguirá chegar nas minhas máquinas locais e minhas máquinas locais terão o IP da VM incorreto, porque mudou.

A solução mais simples para isso é Hub-and-spoke.

Gerador de Configuração WireGuard Config Generator

De tanto ficar fazendo essas configurações do WireGuard na mão, acabei criando o WireGuard Config Generator. Isso nem é público, não tem ads, não salva dados, nem cookies. Tudo roda no seu navegador usando a Web Crypto API. As chaves são geradas localmente e nunca saem da sua máquina. Foi simplesmente um aplicativo que criei para solucionar um problema meu mesmo.

Ele suporta Hub-and-spoke e Mesh separadamente. Para montar uma rede híbrida como a minha, gerei primeiro a base Hub-and-spoke (com o kvm2 como Hub), depois troquei para Mesh e juntei as configs manualmente. Não é o ideal, mas é muito mais rápido do que fazer tudo do zero.

🚨 Vou te explicar todas as configurações, mas te aconselho fortemente a usar o "Generator". Já perdi incontáveis horas tentando encontrar qual chave ou IP eu errei (foi por isso que o criei).

Depois de te passar medo 😂, vamos ver como fazer isso na unha (ainda assim, vou usar a base do Generator).

Como funciona o WireGuard?

Isso varia bastante de sistema para sistema. Porém, pelo menos no Linux e macOS, depois de instalado, você cria um arquivo de configuração com o nome da Interface em /etc/wireguard/wg0.conf.

No caso do macOS, essa pasta nem existia, então criei ela também.

# Cria a pasta do WireGuard
sudo mkdir /etc/wireguard

# Cria o arquivo de configuração do WireGuard
 sudo touch /etc/wireguard/wg0.conf

# Ajusta as permissões do arquivo de configuração do WireGuard
sudo chmod 600 /etc/wireguard/wg0.conf

Os comandos acima são para Linux e macOS. No Windows eu não sei dizer como funciona, mas não deve ser muito diferente disso.

Com este arquivo pronto, agora só precisamos preencher os dados de Interface (nossa interface de rede local) e Peer. Cada Peer é um dispositivo que vamos nos conectar.

Gerando as chaves

Antes de configurar qualquer coisa, cada node precisa de um par de chaves: privada e pública. Se você já usou SSH com chave, é o mesmo conceito.

A chave privada fica só no seu node. Nunca sai de lá. A chave pública você distribui para os peers que precisam se conectar a você.

# Gera a chave privada
wg genkey

Isso vai cuspir uma string em Base64. Essa é a sua chave privada. Guarda ela (nunca, em hipótese alguma, mostre essa chave para ninguém).

Agora, para gerar a pública a partir da privada:

# Gera a chave pública a partir da privada
echo "SUA_CHAVE_PRIVADA" | wg pubkey

Se quiser fazer tudo de uma vez e já salvar nos arquivos:

# Gera o par de chaves e salva nos arquivos
wg genkey | sudo tee /etc/wireguard/private.key | wg pubkey | sudo tee /etc/wireguard/public.key > /dev/null ;
# Ajuste as permissões dos arquivos importantes
sudo chmod 600 /etc/wireguard/{wg0.conf,private.key}

# COPIE A CHAVE PÚBLICA E ANOTE A QUAL DISPOSITIVO ELA PERTENCE
sudo cat /etc/wireguard/public.key

Faça isso em todos os nodes. No final, cada node terá sua chave privada e você terá a chave pública de cada um para distribuir.

Anatomia do arquivo de configuração

O arquivo wg0.conf tem duas seções: [Interface] e [Peer]. Você terá uma Interface e um ou mais Peers.

[Interface]
PrivateKey = <chave privada deste node>
ListenPort = 51820
Address = <IP do node na VPN>/mascara

[Peer]
PublicKey = <chave pública do peer>
AllowedIPs = <IPs que esse peer pode usar no túnel>
Endpoint = <IP público:porta do peer>
PersistentKeepalive = 25

Calma que vou explicar cada campo.

`[Interface]`: Quem sou eu?

PrivateKey a chave privada deste node. Aquela que você gerou e não compartilha com ninguém.
ListenPort a porta UDP que o WireGuard vai escutar. O padrão é 51820. Pode ser qualquer uma, mas lembre de liberar no firewall. Se quer uma dica, mantenha o padrão 51820.
Address o IP deste node dentro da VPN. É um IP que você inventa. Nada a ver com o IP da sua rede ou da Internet. É o endereço que identifica este node dentro do túnel. Eu costumo usar a rede 10.100.0.0/24 alterando apenas o final de 2 para cima (10.100.0.2, 10.100.0.3, ... 10.100.0.254).

`[Peer]`: Quem são os outros?

PublicKey a chave pública do peer. É o que identifica ele.
AllowedIPs essa é a diretiva mais importante do WireGuard. Ela faz duas coisas ao mesmo tempo:
- Na saída: funciona como tabela de rotas. "Para onde enviar pacotes destinados a esse IP?"
- Na entrada: funciona como ACL. "Aceito pacotes vindos desse peer apenas se o IP de origem estiver nessa lista."
- Se colocar 10.100.0.4/32, só o IP 10.100.0.4 passa.
- Se colocar 10.100.0.0/24, toda a sub-rede 10.100.0.x passa.
- Se colocar 0.0.0.0/0, tudo passa. Isso é o Full Túnel.
Endpoint o IP público (ou domínio) e porta do peer. É para onde o WireGuard manda o primeiro pacote. Esse campo é opcional. Se o peer está atrás de NAT ou tem IP dinâmico, ele não precisa de Endpoint, porque é ele quem vai iniciar a conexão.
PersistentKeepalive intervalo em segundos para enviar um pacote vazio ao peer. Serve para manter a conexão ativa, especialmente quando tem NAT no caminho. Se o NAT não receber pacotes por um tempo, ele fecha o mapeamento e o peer fica inalcançável. O valor 25 (segundos) é o recomendado.

Configurando o Hub (servidor central)

Vamos começar pelo coração da rede: o kvm2. Ele é o Hub. É o servidor que todos os outros nodes conhecem e que faz o roteamento quando necessário.

Lembra do AllowedIPs? No Hub, cada peer recebe um /32 (um IP específico).

Isso porque o Hub sabe exatamente quem é quem. Ele não precisa rotear sub-redes inteiras para um peer, só o IP daquele node.

# /etc/wireguard/wg0.conf — kvm2 (HUB)

[Interface]
PrivateKey = <chave privada do kvm2>
ListenPort = 51820
Address = 10.100.0.2/24, fd10:100::2/64

Repare no Address. Estou usando duas redes: uma IPv4 (10.100.0.2/24) e uma IPv6 (fd10:100::2/64). A rede IPv6 usa o prefixo fd, que é para redes privadas (equivalente ao 10.x.x.x no IPv4). Você pode usar só IPv4 se preferir.

Agora os peers. Vou colocar dois para você entender o padrão, depois é só replicar.

# kvm4 - Hostinger VPS
[Peer]
PublicKey = <chave pública do kvm4>
AllowedIPs = 10.100.0.4/32, fd10:100::4/128
Endpoint = 191.101.70.130:51820
PersistentKeepalive = 25

# m132 - Laptop na rede local
[Peer]
PublicKey = <chave pública do m132>
AllowedIPs = 10.100.0.25/32, fd10:100::25/128
Endpoint = 187.108.118.25:51820
PersistentKeepalive = 25

O kvm4 tem IP fixo, então o Endpoint é direto. O m132 está atrás de NAT, mas o Hub tem o IP público do roteador como Endpoint. Funciona? Funciona. Mas tem um detalhe.

Na minha rede local eu tenho 3 máquinas, todas saindo pelo mesmo IP público.

Isso significa que o Hub não pode iniciar a conexão para uma máquina específica, porque o NAT não saberia para qual delas entregar o pacote. Quem precisa iniciar são as máquinas locais. Quando elas fazem o handshake, o Hub aprende a rota correta (com a porta NAT de cada uma) e a comunicação flui.

O PersistentKeepalive = 25 garante que, uma vez conectado, o NAT não feche o mapeamento por inatividade.

Compartilhando a Internet pelo Hub

Se você quer que um node navegue na Internet usando o IP do servidor (Full Túnel), o Hub precisa fazer NAT masquerading. É como dizer: "tudo que chegar pelo túnel e precisar sair para a Internet, sai com o meu IP".

Para isso, adicionamos regras no [Interface] usando PostUp e PostDown:

[Interface]
PrivateKey = <chave privada do kvm2>
ListenPort = 51820
Address = 10.100.0.2/24, fd10:100::2/64

# Habilita o encaminhamento de pacotes
PostUp = sysctl -w net.ipv4.ip_forward=1
PostUp = sysctl -w net.ipv6.conf.all.forwarding=1

# Regras de firewall para NAT masquerading
PostUp = iptables -A FORWARD -i %i -j ACCEPT
PostUp = iptables -A FORWARD -o %i -m state --state RELATED,ESTABLISHED -j ACCEPT
PostUp = iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE
PostUp = ip6tables -A FORWARD -i %i -j ACCEPT
PostUp = ip6tables -A FORWARD -o %i -m state --state RELATED,ESTABLISHED -j ACCEPT
PostUp = ip6tables -t nat -A POSTROUTING -o eth0 -j MASQUERADE

# Limpeza (quando o WireGuard desliga)
PostDown = iptables -D FORWARD -i %i -j ACCEPT
PostDown = iptables -D FORWARD -o %i -m state --state RELATED,ESTABLISHED -j ACCEPT
PostDown = iptables -t nat -D POSTROUTING -o eth0 -j MASQUERADE
PostDown = ip6tables -D FORWARD -i %i -j ACCEPT
PostDown = ip6tables -D FORWARD -o %i -m state --state RELATED,ESTABLISHED -j ACCEPT
PostDown = ip6tables -t nat -D POSTROUTING -o eth0 -j MASQUERADE
PostDown = sysctl -w net.ipv4.ip_forward=0
PostDown = sysctl -w net.ipv6.conf.all.forwarding=0

%i é substituído automaticamente pelo nome da interface (wg0).

eth0 é a interface de rede que tem acesso à Internet no servidor. No seu caso pode ser ens3, enp1s0 ou outro nome. Para descobrir, rode ip route e veja qual interface aparece na rota default.

PostUp roda quando o WireGuard sobe. PostDown roda quando desce. Assim o servidor fica limpo quando a VPN está desligada.

Isso só precisa existir no Hub. Os spokes não precisam dessas regras (a não ser que também compartilhem Internet para outra rede).

Configurando os Spokes

Agora vamos para o lado dos spokes. A ideia é a mesma em todos: dizer quem eu sou (Interface) e quem eu conheço (Peer).

Spoke com IP fixo (VPS)

O kvm4 é um VPS da Hostinger com IP fixo. Ele tem conexão direta com o Hub e também faz mesh com os outros VPSs e com os nodes locais.

# /etc/wireguard/wg0.conf — kvm4 (Spoke + Mesh)

[Interface]
PrivateKey = <chave privada do kvm4>
ListenPort = 51820
Address = 10.100.0.4/24, fd10:100::4/64

# kvm2 (HUB) - Rota para toda a sub-rede passa por aqui
[Peer]
PublicKey = <chave pública do kvm2>
AllowedIPs = 10.100.0.0/24, fd10:100::0/64
Endpoint = 76.13.71.178:51820
PersistentKeepalive = 25

# kvm8 - Mesh direto (VPS com IP fixo)
[Peer]
PublicKey = <chave pública do kvm8>
AllowedIPs = 10.100.0.8/32, fd10:100::8/128
Endpoint = 89.116.73.152:51820
PersistentKeepalive = 25

Olha o que acontece com o AllowedIPs:

Para o kvm2 (Hub): 10.100.0.0/24. Toda a sub-rede. Isso significa que qualquer IP da VPN que o kvm4 não conheça diretamente vai ser encaminhado para o Hub. O Hub é o "caminho padrão".
Para o kvm8 (Mesh): 10.100.0.8/32. Só o IP específico. Quando o kvm4 quiser falar com 10.100.0.8, vai direto, sem passar pelo Hub.

É aqui que mora a mágica da rede híbrida. O WireGuard escolhe a rota mais específica. /32 ganha de /24. Então o mesh é usado quando possível, e o Hub serve de fallback para o resto.

Spoke atrás de NAT (rede local)

Os nodes de casa (m132, m4128, fedoraair) seguem o mesmo padrão. A única diferença é que eles têm peers extras para os vizinhos de rede local, usando IPs internos.

# /etc/wireguard/wg0.conf — m132 (Spoke local)

[Interface]
PrivateKey = <chave privada do m132>
ListenPort = 51820
Address = 10.100.0.25/24, fd10:100::25/64

# kvm2 (HUB)
[Peer]
PublicKey = <chave pública do kvm2>
AllowedIPs = 10.100.0.0/24, fd10:100::0/64
Endpoint = 76.13.71.178:51820
PersistentKeepalive = 25

# kvm4 - Mesh direto
[Peer]
PublicKey = <chave pública do kvm4>
AllowedIPs = 10.100.0.4/32, fd10:100::4/128
Endpoint = 191.101.70.130:51820
PersistentKeepalive = 25

# kvm8 - Mesh direto
[Peer]
PublicKey = <chave pública do kvm8>
AllowedIPs = 10.100.0.8/32, fd10:100::8/128
Endpoint = 89.116.73.152:51820
PersistentKeepalive = 25

# m4128 - Vizinho de LAN (Endpoint local!)
[Peer]
PublicKey = <chave pública do m4128>
AllowedIPs = 10.100.0.26/32, fd10:100::26/128
Endpoint = 192.168.0.109:51820
PersistentKeepalive = 25

# fedoraair - Vizinho de LAN (Endpoint local!)
[Peer]
PublicKey = <chave pública do fedoraair>
AllowedIPs = 10.100.0.27/32, fd10:100::27/128
Endpoint = 192.168.0.114:51820
PersistentKeepalive = 25

Repare nos Endpoints dos vizinhos de LAN: 192.168.0.x. São IPs internos da rede local. Quando o m132 quer falar com o m4128, ele vai direto pela rede local, sem sair para a Internet e sem passar pelo Hub.

Isso é exatamente o problema de hairpinning que comentei lá em cima. Se eu não colocasse esses Endpoints locais, o pacote iria até o Hub em São Paulo e voltaria. Da minha mesa em Minas para São Paulo e de volta. Para falar com o laptop ao lado.

Spoke com IP dinâmico (gc_micro)

O gc_micro é uma VM no Google Cloud com IP dinâmico. Ele não tem Endpoint fixo, então nenhum peer coloca o IP dele na configuração.

# /etc/wireguard/wg0.conf — gc_micro (Spoke dinâmico)

[Interface]
PrivateKey = <chave privada do gc_micro>
ListenPort = 51820
Address = 10.100.0.28/24, fd10:100::28/64

# kvm2 (HUB) - Rota para toda a sub-rede
[Peer]
PublicKey = <chave pública do kvm2>
AllowedIPs = 10.100.0.0/24, fd10:100::0/64
Endpoint = 76.13.71.178:51820
PersistentKeepalive = 25

# kvm4 - Mesh direto
[Peer]
PublicKey = <chave pública do kvm4>
AllowedIPs = 10.100.0.4/32, fd10:100::4/128
Endpoint = 191.101.70.130:51820
PersistentKeepalive = 25

# kvm8 - Mesh direto
[Peer]
PublicKey = <chave pública do kvm8>
AllowedIPs = 10.100.0.8/32, fd10:100::8/128
Endpoint = 89.116.73.152:51820
PersistentKeepalive = 25

O gc_micro conhece o Hub e os VPSs (que têm IP fixo). Para todo o resto, depende do Hub. E o mais importante: ninguém aponta Endpoint para ele. Ele inicia a conexão, o PersistentKeepalive mantém o NAT aberto e o Hub aprende o caminho.

Se a VM reiniciar e ganhar um IP novo? Sem problemas. Ela conecta de novo no Hub, o Hub atualiza o Endpoint automaticamente e a vida segue.

Subindo o túnel

Configurou tudo? Então vamos ligar.

# Sobe a interface wg0
sudo wg-quick up wg0

Para derrubar:

# Desce a interface wg0
sudo wg-quick down wg0

Se quiser que o WireGuard suba automaticamente junto com o sistema (Linux com systemd):

# Habilita o WireGuard no boot
sudo systemctl enable wg-quick@wg0

Para verificar o status da conexão:

# Mostra o status de todos os peers
sudo wg show

O comando wg show é o seu melhor amigo. Ele mostra quais peers estão conectados, quando foi o último handshake e quantos dados passaram.

Testando a conexão

O bom e velho ping:

# Pinga o Hub pelo IP da VPN
ping 10.100.0.2

Se chegar, o túnel está funcionando. Se não chegar, respira fundo e confere:

O WireGuard está rodando nos dois lados? (sudo wg show)
As chaves públicas estão corretas? (chave pública do peer A no config do B e vice-versa)
A porta 51820/UDP está liberada no firewall?
O AllowedIPs inclui o IP que você está tentando alcançar?
Se tem NAT, o node atrás do NAT iniciou a conexão primeiro?

Lembra que eu disse que o WireGuard é silencioso? Se algo estiver errado, ele simplesmente não responde. Não tem mensagem de erro bonitinha. Então a depuração é por eliminação mesmo 😂.

WireGuard Config Generator no seu navegador

Thu, 12 Mar 2026 00:00:00 GMT

O WireGuard Config Generator não é nada complexo ou feito com o intuito de gerenciar sua conexões de VPN do WireGuard. A única coisa que ele faz é gerar suas configurações para você.

Fiz isso apenas para rotacionar as poucas conexões que tenho sem ter que instalar nada externo. Só preciso adicionar nomes e IPs para o gerador de configurações do WireGuard fazer todos os arquivos de configuração para cada uma das minhas máquinas automaticamente.

Para não usar nada externo, usei a Web Crypto API do próprio navegador.

Para garantir a segurança e confiabilidade, só uso front-end (HTML, CSS e JS) sem salvar nada em lugar nenhum:

Sem Analytics
Sem Cookies
Sem Base de dados
Sem Conexão externa

Além disso, o código do WireGuard Config Generator é aberto.

Se você busca por algo que gerencie toda a conexão para você, talvez seja melhor usar o Headscale ou Tailscale.

Agora, se quer apenas gerar ou rotacionar suas chaves de forma segura acesse:

WireGuard Config Generator

Faltam algumas coisas ainda. Por exemplo, gostaria de colocar a opção de compartilhamento de Internet, roteamento, full túnel e várias outras coisas. Mas, enquanto não monto isso, use o seguinte na sua configuração do WireGuard quando precisar:

# Para Compartilhamento de Internet adicione isso no servidor
# NAT masquerading to share internet
PostUp = sysctl -w net.ipv4.ip_forward=1
PostUp = sysctl -w net.ipv6.conf.all.forwarding=1

PostUp = iptables -A FORWARD -i %i -j ACCEPT
PostUp = iptables -A FORWARD -o %i -m state --state RELATED,ESTABLISHED -j ACCEPT
PostUp = iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE
PostUp = ip6tables -A FORWARD -i %i -j ACCEPT
PostUp = ip6tables -A FORWARD -o %i -m state --state RELATED,ESTABLISHED -j ACCEPT
PostUp = ip6tables -t nat -A POSTROUTING -o eth0 -j MASQUERADE

PostDown = iptables -D FORWARD -i %i -j ACCEPT
PostDown = iptables -D FORWARD -o %i -m state --state RELATED,ESTABLISHED -j ACCEPT
PostDown = iptables -t nat -D POSTROUTING -o eth0 -j MASQUERADE
PostDown = ip6tables -D FORWARD -i %i -j ACCEPT
PostDown = ip6tables -D FORWARD -o %i -m state --state RELATED,ESTABLISHED -j ACCEPT
PostDown = ip6tables -t nat -D POSTROUTING -o eth0 -j MASQUERADE
PostDown = sysctl -w net.ipv4.ip_forward=0
PostDown = sysctl -w net.ipv6.conf.all.forwarding=0

Exemplo de configuração completo

Servidor (Hub) — /etc/wireguard/wg0.conf

[Interface]
PrivateKey = <SERVER_PRIVATE_KEY>
Address = 10.0.0.1/24
ListenPort = 51820

# Para Compartilhamento de Internet adicione isso no servidor
# NAT masquerading to share internet
PostUp = sysctl -w net.ipv4.ip_forward=1
PostUp = sysctl -w net.ipv6.conf.all.forwarding=1

PostUp = iptables -A FORWARD -i %i -j ACCEPT
PostUp = iptables -A FORWARD -o %i -m state --state RELATED,ESTABLISHED -j ACCEPT
PostUp = iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE
PostUp = ip6tables -A FORWARD -i %i -j ACCEPT
PostUp = ip6tables -A FORWARD -o %i -m state --state RELATED,ESTABLISHED -j ACCEPT
PostUp = ip6tables -t nat -A POSTROUTING -o eth0 -j MASQUERADE

PostDown = iptables -D FORWARD -i %i -j ACCEPT
PostDown = iptables -D FORWARD -o %i -m state --state RELATED,ESTABLISHED -j ACCEPT
PostDown = iptables -t nat -D POSTROUTING -o eth0 -j MASQUERADE
PostDown = ip6tables -D FORWARD -i %i -j ACCEPT
PostDown = ip6tables -D FORWARD -o %i -m state --state RELATED,ESTABLISHED -j ACCEPT
PostDown = ip6tables -t nat -D POSTROUTING -o eth0 -j MASQUERADE
PostDown = sysctl -w net.ipv4.ip_forward=0
PostDown = sysctl -w net.ipv6.conf.all.forwarding=0

# Cliente 1
[Peer]
PublicKey = <NOTEBOOK_PUBLIC_KEY>
PresharedKey = <PSK_VPS_NOTEBOOK>
AllowedIPs = 10.0.0.2/32

# Cliente 2
[Peer]
PublicKey = <CELULAR_PUBLIC_KEY>
PresharedKey = <PSK_VPS_CELULAR>
AllowedIPs = 10.0.0.3/32

# Cliente 3
[Peer]
PublicKey = <HOME_SERVER_PUBLIC_KEY>
PresharedKey = <PSK_VPS_SERVIDOR>
AllowedIPs = 10.0.0.4/32, 192.168.1.0/24 # túnel + LAN da casa

Cliente (Exemplo) — /etc/wireguard/wg0.conf

[Interface]
PrivateKey = <NOTEBOOK_PRIVATE_KEY>
Address = 10.0.0.2/32
DNS = 1.1.1.1, 8.8.8.8

[Peer]
PublicKey = <SERVER_PUBLIC_KEY>
PresharedKey = <PSK_VPS_NOTEBOOK>
Endpoint = <IP_PUBLICO_VPS>:51820
AllowedIPs = 0.0.0.0/0, ::/0           # full tunnel (todo tráfego pela VPN)
# AllowedIPs = 10.0.0.0/24             # split tunnel (só rede interna)
PersistentKeepalive = 25

Nota sobre eth0: este nome de interface pública pode ser ens3, enp1s0, etc. Descubra com: ip route show default | awk '{print $5}'

A Base Para Observabilidade: Stack LGTM (Loki, Grafana, Tempo, Mimir)

Tue, 10 Mar 2026 00:00:00 GMT

Até poucos dias atrás, eu não sabia quase nada sobre essa sopa de letrinhas: Loki, Grafana, Tempo, Mimir, Alloy, OpenTelemetry e outras que vão aparecendo nos meus estudos.

Na minha cabeça de "dev raiz", observabilidade era algo como:

"Joga uns logs aí, abre o terminal, procura erro e vai."

Funciona? Às vezes. Sempre damos um jeito de resolver. O problema é sempre está correndo atrás do rabo. Sempre "reagindo ao erro" e não "prevenindo o erro".

E tem mais, chega uma hora em que o log sozinho não responde o que você quer saber. Ele só te mostra que algo aconteceu. Mas não responde algumas perguntas que tendem a aparecer. Alguns exemplos:

quanto aquilo piorou ao longo do tempo?
onde a requisição ficou lenta?
foi no meu código ou na infra?
qual a quantidade de usuários afetados?

Depois de algumas tentativas falhas de estudar observabilidade no passado, dessa vez resolvi pegar firme. Óbvio que não sou nenhum especialista, longe disso. Mas, pelo menos já consigo dar meus pitacos.

Um dos primeiros desafios que encontrei, foi essa sopa de letrinhas. Eu ainda estava só nos logs, quando apareceram: Métricas, Traces e Profiles.

Foi exatamente por isso que resolvi montar uma stack LGTM completa e disponibilizar isso, primeiro para quem me acompanha. (O próprio Grafana tem essa stack pronta, mas eu precisava montar a minha).

Stack LGTM em vídeo

Gravei um vídeo falando mais detalhadamente sobre isso, caso queira assistir, segue abaixo:

Observabilidade: Loki, Grafana, Tempo e Mimir (LGTM Stack)

O log é bom, mas...

Todo desenvolvedor faz isso: acontece alguma coisa estranha na aplicação e a reação imediata é sair espalhando print, console.log, logger.info ou qualquer variação dessa ideia. Quando é fora da aplicação, tail, grep, rg...

Eu faço isso muito mais do que gostaria. Você, provavelmente também faz isso. Acho que todo mundo faz um pouco disso.

Ao meu ver, tá tudo certo. O log é bom, mas... log é um evento textual congelado no tempo. Ele vai te contar algo que aconteceu em um ponto muito específico no tempo.

Só que observabilidade de verdade começa quando você quer responder perguntas um pouco menos específicas. Por exemplo:

isso aconteceu uma vez ou está acontecendo várias vezes sem eu perceber?
isso começou agora ou já vem piorando faz algum tempo?
essa requisição passou por onde?
foi CPU?
foi rede?
foi banco?
foi meu último deploy?

Aí entram os três pilares (tem mais, mas eu ainda estou nesses).

Logs, métricas e traces

Logs

Logs são registros de eventos capturados em momentos específicos no tempo. É o relato bruto. O "aconteceu isso".

Neste projetinho que vou disponibilizar mais adiante no texto, os logs saem da aplicação via stdout, o Docker coleta, o Grafana Alloy lê isso e encaminha para o Loki. Depois eu exploro tudo na interface do Grafana usando LogQL.

É o básico que todo mundo entende primeiro. E com razão. Log é o tipo de coisa que você bate o olho e já reconhece.

Métricas

Métricas são medidas numéricas acompanhadas ao longo do tempo. Aqui a conversa muda.

Você não quer mais saber só se "deu erro" em algum ponto. Você quer saber:

qual foi a taxa de erro?
quantas requisições por segundo estão chegando?
quanto de CPU a VPS está usando?
como a latência se comportou nos últimos minutos

Métrica é tendência, comportamento, padrão. Geralmente, preciso de algum volume de dados e tempo para análise. Um exemplo de métrica poderia ser o tempo médio de resposta da API para os usuários em determinado período.

Sozinhos, Logs não conseguiriam responder isso.

No projeto, essas métricas vão para o Mimir e eu consulto tudo com PromQL.

Traces

Isso aqui é um pouco mais complexo até conseguir configurar tudo de uma forma que os dados façam sentido, mas é uma das partes mais interessantes para mim.

Trace é o caminho completo de uma requisição. E por requisição, não estou falando apenas de requisições HTTP. Qualquer caminho que os dados façam em qualquer aplicação.

Ele mostra por onde a chamada passou e onde o tempo foi gasto em cada um dos pontos. Não interessa se foi uma função do seu código ou alguma parte da infra. Se configurado de maneira correta, você conseguiria ver precisamente onde uma requisição pode ter gerado um erro ou ficado mais lenta.

Então, em vez de olhar só para o resultado final, você passa a olhar para a jornada inteira:

entrou aqui
passou por esse middleware
ficou esse tempo nessa etapa
terminou desse jeito

No meu caso, estou usando Tempo para armazenar traces e OpenTelemetry para instrumentar a API.

É a peça que mais ajuda a sair do "acho que o gargalo está aqui" para "não, está aqui mesmo".

Obs.: já podemos tirar os prints e console.logs de "Chegou Aqui" do código.

Grafana Alloy - Ele é quem distruibui os dados

Uma das coisas que eu não entendia no começo era:

"Beleza, eu tenho logs, métricas e traces. Mas quem pega isso tudo e leva para os lugares certos?"

No meu projeto, esse papel ficou com o Grafana Alloy. Ele funciona como um coletor e roteador.

Pega logs do Docker, recebe métricas e traces da aplicação, coleta sinais do host e dos containers e distribui cada coisa para o backend certo

O fluxo fica mais ou menos assim:

API Logs -> Docker -> Alloy -> Loki
API Métricas -> OTel -> Alloy -> Mimir
API traces -> OTel -> Alloy -> Tempo

Otel é OpenTelemetry.

O Grafana entra depois como a interface onde eu exploro tudo.

Falando em OpenTelemetry (OTel)

O OpenTelemetry entra dentro da aplicação. Tipo o que você faz com seu Logger, mas para métricas e traces. O OTel também faz log e profiling, mas ainda não cheguei nessa página do livro 😅.

Mas, ele foi o padrão que usei para instrumentar a API e emitir telemetria sem ter que sair inventando formato próprio para tudo. Na verdade, hoje em dia ele já é o padrão da indústria (todo mundo já usa).

Foi ele que me permitiu gerar métricas e traces da aplicação de um jeito mais organizado e menos artesanal.

Ou seja:

o Alloy coleta e encaminha
o OpenTelemetry ajuda a aplicação a emitir os sinais

A parte divertida: subir isso em um VPS real

Montar tudo localmente é ótimo para aprender. Mas localmente tudo sempre parece mais bonito do que realmente é.

Se precisar de VPS

Tenho link e cupom de 10% de desconto adicional na Hostinger para planos de 12 e 24 meses.

hostinger.com/otaviomiranda
Cupom: OTAVIOMIRANDA

Você está na sua máquina. Sem latência de internet. Sem borda pública. Sem firewall de verdade. Sem aquele sentimento de "agora isso aqui mora em outro lugar e pode dar ruim". E, o mais importante, sem bots de Internet tentando fazer brute force no seu SSH ou qualquer formulário disponível no seu front-end.

Então resolvi subir a stack numa VPS real.

E aqui entra uma coisa importante: eu não queria fazer um tutorial gigante de "digite 300 comandos comigo". A verdade é que 2025 já foi muito cruel com quem dedicou tempo para criar tutoriais. Então fiz diferente.

Documentei o passo a passo em dois guias:

um guia completo, explicando o que cada comando faz
e um guia mais direto, só com os comandos para subir o servidor

Assim, este texto ou meu vídeo não se tornam um walkthrough cansativo. Quem quiser replicar tem tudo mastigado.

O deploy ficou simples de propósito

Tentei abstrair o máximo da parte chata para deixar a stack mais fácil de estudar.

No repositório, a base do deploy gira em torno do Justfile.

Então, em vez de sair lembrando docker compose gigantesco, arquivo de ambiente, receita de tráfego e outras miudezas, eu deixei comandos curtos para as tarefas principais.

Por exemplo:

cp .env.example .env
# Configure o seu .env
just deploy

Depois disso, consigo gerar tráfego, disparar alertas, resetar ambiente, explorar dashboards e repetir cenários sem precisar decorar um carnaval de comandos.

Esse tipo de coisa parece detalhe, mas faz muita diferença quando você quer estudar sem transformar tudo em atrito.

Segurança: o Grafana não precisa ficar pelado na internet

Outra decisão importante foi não expor tudo publicamente. Mas, quero mudar isso já como um próximo passo.

Eu tinha algumas opções na mesa no momento da configuração:

Traefik com HTTPS para API e Grafana
Traefik com HTTPS para API e Grafana liberando apenas meu IP
VPN WireGuard e Grafana apenas no VPN
E outras...

No meu setup, fiz o seguinte: a API fica atrás de Traefik em 80/443, mas o Grafana fica privado, acessível pela rede do WireGuard.

Isso me dá uma divisão que queria, mas não expõe nada do Grafana para a Internet.

a aplicação pública fica pública
a interface administrativa fica privada

Como laboratório, ainda vou abrir o Grafana para a Internet para "OBSERVAR 😂" o que acontece.

O mais legal de tudo

O mais legal desse processo foi perceber como o entendimento vai mudando muito rápido quando você começa a ver as peças funcionando juntas.

Dois dias antes de montar isso, eu mal sabia o que era LGTM. Pouco depois, eu já estava discutindo:

single binary no Loki
traces no Tempo
métricas do host
alertas no Mimir
Grafana privado via WireGuard
latência real da API vs delay injetado

O cérebro humano é uma máquina engraçada. Isso acontece com você também?

Primeiro você se sente um idiota. Depois começa a reconhecer os nomes. Depois entende o fluxo. Depois começa a ter opinião. Depois está aqui escrevendo sobre isso.

Se você quiser estudar isso

Te convido a usar o meu projeto. Ele está público, gratuito e foi pensado para iniciantes que querem aprender observabilidade vendo algo real funcionar.

Foi pensado assim porque eu também me considero inciante nisso.

O projeto, até agora, tem:

aplicação de demo
stack LGTM completa
dashboards provisionados
tráfego simulando cenários previsíveis
guias para subir localmente e numa VPS

Devo continuar mexendo, então não leve isso ao pé da letra. Mas, se você quiser dar uma olhada, o repositório está aqui:

github.com/luizomf/lgtm1

Se for usar VPS para brincar com isso em ambiente real, eu usei uma da Hostinger nesse laboratório e ela deu conta do recado. Mas o mais importante aqui não é o provedor. É você finalmente parar de depender de achismo para entender o que sua aplicação está fazendo.

No fim, era isso que eu queria.

Menos "hmm, estranho". Mais "agora eu sei onde olhar".

De HTML, CSS e JS para Astro: finalmente migrei

Fri, 27 Feb 2026 15:00:00 GMT

Já tem alguns dias que estou falando sobre esta migração na comunidade do meu canal. Hoje, finalmente terminei!

Meu site foi de HTML, CSS e JavaScript PUROS para o Astro (usando SSG - Static Site Generation).

Além disso, este foi um dos primeiros projetos em que mais administrei do que digitei código. Diria que 95% do código atual foi escrito por 3 LLMs diferentes: Claude Code (Opus 4.6), Codex App (GPT 5.3 Codex High) e Antigravity (Gemini 3.1 Pro High). Também usei variações desses modelos para tarefas simples ou mais complexas.

Usando um arquivo de regras simples, git e GitHub, consegui manter o contexto do que estava em andamento até a conclusão do projeto. Isso me permitiu até mesmo trocar de modelo ao longo da migração sem muitos problemas.

Vamos entender mais detalhes sobre isso adiante.

Mas, primeiro vamos garantir que você não vai cometer os mesmos erros que eu.

Meu erro ao usar HTML, CSS e JS puros

Ao criar um website com HTML, CSS e JS puros, é muito provável que você termine com uma estrutura assim (ou variações disso):

.
├── css
│   └── styles.css
├── images
│   └── ...
├── js
│   └── scripts.js
├── 2025
│   ├── meu-post-1
│   │   └── index.html
│   ├── meu-post-2
│   │   └── index.html
├── 2026
│   ├── meu-post-3
│   │   └── index.html
│   ├── meu-post-4
│   │   └── index.html

... vários anos e posts ...

│ 
└── index.html

No começo, isso parece uma boa ideia.

Só que, sem um padrão ou framework, você vai precisar copiar e colar o diretório de uma página para criar outra (ou inventar uma outra maneira qualquer).

Com o passar do tempo, isso vai fazer você terminar com centenas de páginas com variações levemente diferentes do index.html.

Todas com repetições do mesmo cabeçalho, rodapé, menu e qualquer outra coisa que estiver no seu layout.

Como todo bom dev, cheio de projetos para entregar, você vai pensar:

"Se funciona, vou manter como está! Se precisar, depois melhoro a estrutura."

Tudo vai ficar bem até que...

Você precisa alterar algo.

Pense que você criou um site de notícias que fala de assuntos variados. Como são muitos assuntos, você pode publicar mais de uma vez por dia. Então, rapidamente você tem 999 notícias.

Só que algo passou despercebido na vigésima quinta notícia que você publicou. Um erro de digitação no rodapé do seu index.html. O seu hábito de copiar e colar clonou este erro para mais 974 páginas.

Ao publicar sua próxima notícia, você percebe que é um grande momento, mas aquele erro está pegando mal. Então você pensa:

"Um script Python resolve!"

Talvez! Mas, se isso ainda não tinha passado pela sua cabeça, de agora em diante você lembra disso o tempo todo.

"E se aparecer outro erro?"
"E se eu tiver que alterar o layout e o CSS?"
"E se eu quiser adicionar ou remover um link de menu?"

Refatorar todo o site nessa altura do campeonato é complicado. Você está com vários outros projetos em andamento. Deadlines batendo na porta.

Seu script não vai capturar todas as nuances dos posts, porque todo ser humano tem bursts de dopamina que geram micro alterações de código ao longo do tempo.

E nós sabemos que você nunca voltou para alterar todos aqueles quase 1000 posts.

As janelas estão quebradas...

A partir daqui, começa a acontecer algo muito parecido com a teoria das janelas quebradas.

Você passa a "vandalizar" seu próprio site. Adiciona "só mais um script" para alguma coisa específica, "um ajuste de margem aqui", "uma div ali"... Este site nunca vai estar perfeito.

Isso vai rapidamente da empolgação de algo novo para o "medo de quebrar outro trecho do site", para o "Eu não ligo mais".

Um belo dia, você simplesmente para de publicar completamente. Só manter o que já tem, já será sua vitória.

Exatamente o que aconteceu comigo.

A refatoração mal sucedida

Com o advento dos agentes para código com LLMs cada vez mais inteligentes, criei coragem para fazer essa refatoração. Mas, antes de colocar qualquer IA no projeto tive essa ideia brilhante:

"Vou refatorar isso aqui na mão mesmo mantendo HTML, CSS e JS"

Claro! Vamos cometer o mesmo erro duas vezes seguidas. Já que vamos errar, erramos em tudo o que for possível para não restar dúvidas sobre o erro 😅.

Olhei algumas tendências no CodePen e Dribbble. Não sou bom com design, por isso, tudo que adiciono nos meus layouts vem de coisas que vejo na Internet e gosto.

Meu único código do projeto

Decidi que queria uma section Hero no topo do site com um texto bem grande e centralizado.

Me inspirei no design do Antigravity, com as partículas interativas que ficam se mexendo suavemente.

Cheguei a fazer 3 efeitos de background para decidir qual usar. Estão todos abaixo:

Perdi uns 2 ou 3 dias com isso, mas consegui um resultado que me agradou.

E essa foi minha única participação em digitação de código neste projeto. O canvas e o JavaScript que o acompanha.

Desistência

Cheguei a colocar o canvas na página inicial e fazer alguns ajustes de fonte.

Queria (e consegui) criar um site onde o conteúdo vem primeiro. Principalmente na parte dos posts.

Usei uma fonte grande, muito bem espaçada e não tenho anúncios, pop-ups, cookies...

Nada além do conteúdo.

Código antigo embaixo da cama

BoOoO 👻!

Mesmo tentando remover o máximo de coisas do código antigo sem quebrar nada, mexer em uma parte do CSS ou JS antigo estragava outras partes do site.

Trocar o tamanho de algo, significava ter que sair conferindo todas as outras páginas. Confesso que nem forcei, com uma ou duas tentativas, já desisti disso e fui atrás de solução.

Eu: Me indique um bom framework para SSG em 2026.
IA: Astro!

Como eu ainda não havia usado o Astro, vamos checar do que se trata.

Astro is a JavaScript web framework 🤮🫣☺️💜

Ao entrar no astro.build, adivinha a primeira coisa que vejo?

"Astro is a JavaScript web framework" (sentiu um calafrio aí?).

Toda vez que vejo as palavras JavaScript e Framework juntas, a vontade é tapar os ouvidos e ficar gritando: "lá lá lá lá lá, não quero saber...".

Se você já usou a quantidade de frameworks e libs de JS que eu, deve ter a mesma sensação. No final você só quer não usar nada.

Mas, o Astro foi diferente.

Conceitos do Astro

Olha só que coincidência, alguns dos conceitos do Astro falaram diretamente comigo, como se eu estivesse em uma consultoria com o framework:

Servidor primeiro: "O Astro melhora o desempenho do seu website renderizando componentes no servidor, enviando HTML leve para o browser, com zero overhead de JavaScript desnecessário."
Voltado para conteúdo: "O Astro foi criado para trabalhar com o seu conteúdo, não importa onde ele estiver. Carregue dados do seu sistema de arquivos, APIs externas ou seu CMS favorito."
Personalizável: "Estenda o Astro com suas ferramentas favoritas. Traga sua própria UI de componentes, bibliotecas JS, temas, integrações e mais."

Interessante! Tudo isso realmente está lá no site deles. Agora, quer mais?

Astro Islands

Se você já usou qualquer framework ou lib JavaScript, deve ter notado que queremos encapsular o máximo de coisas de um componente.

Isso evita o problema que eu tive na minha refatoração falha. Editar algo e quebrar outro componente. Mas, até o momento, eu fazia isso com um único framework.

O Astro permite criar ilhas (islands) dentro da página. Dessa forma, um componente pode usar React, outro Vue, outro pode ter somente HTML puro.

Então não vamos procurar mais.

Fechado com Astro 💜

A partir daqui o negócio até que fluiu bem.

Só tem aquele fato que mencionei antes "ainda não havia usado o Astro". Então deixa eu chamar os LLMs e começar os trabalhos.

LLMs: problemas e soluções

O meu intuito com a IA neste projeto não é fazer "Vibe Coding". É o oposto. Quero a IA trabalhando como um colega qualquer (que digita 1000x mais rápido do que eu).

Mas, temos um grande problema atualmente: NÃO EXISTE UM PADRÃO.

Como tudo é muito novo, o que posso te passar são apenas experiências que tive TESTANDO algumas coisas.

O problema do contexto

Sempre que você inicia um novo agente no projeto, ele vem em branco. É como um desenvolvedor entrando em uma base de código pela primeira vez. Precisa ler a documentação ou todo o projeto para entender o que será feito.

O problema é que agentes têm limites de tamanho na janela de contexto e, mesmo que não tivessem, também existe o problema do Context Rot.

Se você quer fazer algo grande sem dores de cabeça, a melhor opção é seguir a técnica de dividir para conquistar. Divida o problema em partes pequenas o suficiente para serem gerenciadas e resolva as pequenas partes uma por vez.

Foi exatamente o que fiz, com alguns percalços até encontrar algo que funcionou.

Primeira tentativa: AGENTS.md

No meu arquivo AGENTS.md, só apontei o modelo para outros arquivos separados:

MEMORY.md - estado da sessão, o que foi feito e o que falta fazer (tipo um CHANGELOG mas para o LLM).
SOUL.md - personalidade e tom do agente (seja conciso, fale em inglês, etc).
USER.md - Meu nome, softwares disponíveis e coisas relevantes sobre o usuário (eu).
AGENTS.md - Aponta o agente para os arquivos anteriores.

A ideia era simples: antes de fazer qualquer coisa, a IA lê esses arquivos e segue as regras.

Terminou o código, atualiza o MEMORY.md com o que aconteceu e faz um commit do que mudou. Assim eu só reviso o commit no final.

Se eu precisar trocar de modelo ou simplesmente limpar o contexto, o MEMORY.md lembra tudo para a IA.

Quando funciona (caminho feliz):

De início, achei que esse era o modo perfeito. Trabalhei tranquilamente uma manhã inteira dessa forma. Gemini, Codex e Claude respeitaram as regras e eu estava revisando o código.

Chamei isso de "loop":

Prompt para a tarefa:
  LLM:
    -> AGENTS.md
      -> SOUL.md
      -> USER.md
   -> Faz o código
      -> MEMORY.md (Contexto)
      -> commit (Contexto)
  EU:
    -> reviso

Problema:

Quando a task era mais complexa, todos os modelos falhavam. E o pior, não dava pra saber onde seria a falha.

Corrigi isso adicionando as regras direto no arquivo global de cada LLM (GEMINI.md, CODEX.md e CLAUDE.md). Esses arquivos sempre são lidos, então elas não esquecem. Mesmo assim, ainda passava alguma coisa sem atualização.

Como percebi que eles estavam sempre fazendo o commit, adicionei um hook validando minhas regras. Se o modelo tentasse fazer commit sem atualizar MEMORY.md, eu gerava um erro explicando as regras de novo.

Isso funcionou? Sim! Mas com vários problemas.

Primeiro, o hook atrapalha você também. Quando você for fazer algum commit, seu hook vai fazer você ter que atualizar o MEMORY.md também 😂.

Segundo, a fricção do modelo com este sistema. Se você ficar olhando ele trabalhar, vai ver isso:

Modelo faz o código
Tenta fazer commit sem atualizar a memória
Erro no commit
Modelo volta e lê o AGENTS.md novamente
Atualiza o MEMORY.md
Faz o commit
Te avisa que esqueceu do MEMORY.md, mas corrigiu

Trabalhei alguns dias assim. Mas, essa fricção estressa você e atrapalha o modelo. Então tentei outra coisa.

Issues, Branch, PR e Merge

Regras em um único arquivo global do modelo. Para cada modelo, usei seu próprio arquivo (GEMINI.md, CODEX.md e CLAUDE.md). Sem espalhar dados em outros arquivos.

# NOME_MODELO.md

- Quem sou eu e como me trate
- O que é o projeto
- Decisões de arquitetura
- Regras do workflow (já explico)

Nessas regras do workflow, fiz o modelo trabalhar como qualquer outro desenvolvedor. Vai fazer algo novo no projeto? Ok, siga esses passos:

Abra uma Issue no repositório
Crie um novo Branch para o que for fazer e faça
Terminou? Crie uma Pull Request
Eu reviso a PR e faço o merge

Por incrível que pareça, nenhuma IA erra nunca neste processo. Creio que elas foram bem treinadas em código open source 😅.

Mas e o contexto? Elas sabem usar o git muito bem. Só avisar o processo para o modelo que ele vai ler Issues, histórico de commits, etc.

Por falar nisso, você também nem precisa conversar com o modelo usando mensagens. Abra uma Issue no repositório e avise ao modelo:

"Trabalhe na issue #N"

Simples assim!

Os três modelos

Os modelos que usei foram:

Claude Code (Opus 4.6) via Claude CLI: Muito bom, mas é o mais caro deles. Além disso, ele é o que tem menos limite nos meus planos. Meu plano atual é o Max 5x (e ele bateu limite várias vezes). Ainda tem um plano acima, o 20x (mais caro ainda). Depois tem a API. Aí o preço não faz nem sentido para mim.

Codex (GPT 5.3 Codex High): não usei o CLI porque o Codex App está com uma promoção que te dá o dobro de tokens até abril. Então, vamos economizar, não é? Eu não chequei essa informação, mas mesmo usando o Codex App um dia inteiro, não vi onde é o limite (e meu plano é o plus, o mais barato).

Antigravity (Gemini 3.1 Pro High): eu não sei o motivo, mas eu considero que "ganhei" o acesso aos produtos do Gemini. Eu já assinava o Google One para backup no Google Drive. Um belo dia incluíram o Gemini no plano. Com ele eu também não vi o limite. Mas, pode ser que tenha acontecido. Em alguns momentos, o modelo começava a dar erro e parava de funcionar. Não sei se foi por causa do volume de uso ou limite mesmo. Acontece que o Gemini 3.1 Pro acabou de ser lançado. Nesses momentos, todo mundo quer testar o novo modelo, então erros são mais comuns.

O ponto principal:

Neste projeto, como era algo mais simples, não vi diferença entre os modelos. Foi muita cópia e cola do velho para o novo, e todos os modelos se saíram muito bem.

Tentei usar um por dia. Quando começava os trabalhos pela manhã, já iniciava com um deles e ia até o final do dia.

Em alguns dias eu fui forçado a trocar por erro (Gemini) ou por limite (Claude).

O que eles construíram?

Se você está lendo isso no meu site, tem a mão deles aí. Foram aproximadamente 2 semanas, comigo basicamente dirigindo e revisando.

Sistema de layouts com componentes reutilizáveis
Content Layer API com schemas Zod para validação de frontmatter
Syntax highlight nativo via Shiki (zero JS client-side para blocos de código)
Pipeline de deploy automático via GitHub Actions
Sitemap automatizado
Editor Markdown no browser com Monaco e Vim mode
CLI para criação de posts (npm run post "Título")
Remoção de ~4.000 linhas de código legado
Dark mode (somente nos posts)
E mais coisas que eu talvez tenha esquecido.

A única parte que eu fiz foi o canvas de partículas na home.

A lição

É simples: só tratei modelos de IA como qualquer outro desenvolvedor:

Issue -> branch -> commit -> revisão (VOCÊ) -> merge (VOCÊ)

Pelo menos até o momento em que escrevi isso, este foi o modelo que melhor funcionou.

Conclusão

Este post começou com um site quebrado e o medo de tocar em qualquer coisa.

Termina com o Astro e builds automáticos no GitHub Pages. Além disso, também aderi ao modelo de Issues. Antes eu fazia push direto no main. Isso me permite até ter rascunhos de posts 😂.

A lição não é sobre o Astro, sobre IA ou sobre nenhuma ferramenta específica.

Quando algo está quebrado e doloroso, a solução quase nunca é "só mais um script". É começar de novo com fundações melhores, mesmo que isso signifique engolir o orgulho e usar outro FrameworkJavaScript (as duas palavras coladas uma na outra pra você 🤬).

Docker Context com SSH

Thu, 26 Feb 2026 00:00:00 GMT

Se você entende como o Docker funciona e o utiliza no seu dia a dia, sabe que ele é uma mão na roda para muitas coisas além do desenvolvimento. Você pode até fazer deploy com ele, como já mostrei algumas vezes no passado.

Só que existem algumas configurações que uso bem menos do que deveria. Como é o caso do contexto (Docker Context). Uma parte extremamente simples do Docker, mas que pode salvar o dia e evitar que você fique fazendo conexões remotas sem necessidade.

Em vídeo: se preferir, tenho este mesmo conteúdo em vídeo.

Mais de um computador? Sem problemas!

Vamos montar um cenário fictício e depois te falo como isso se encaixa com o meu momento atual.

Suponha que você tem um computador que fica sempre parado e um laptop que usa para trabalhar com mais conforto pela casa. O computador tem um hardware excelente e te ajuda nas tarefas mais pesadas. Mas, seu laptop só consegue te ajudar em cenários de baixo “load”.

Usar Docker no laptop vai engolir todo o pouco recurso que ele tem.

Este cenário é muito similar ao que tenho atualmente. Só que o meu problema é um pouco diferente.

Por incrível que pareça, utilizo três computadores ao mesmo tempo. Quando falo isso, pessoas costumam duvidar. Mas, não é exagero.

Tenho um MacBook M1 com 32GB de RAM que carrego pra todo lado (vamos chamá-lo de m132). Nada a reclamar deste laptop. No entanto, ele não roda um “gpt-oss:120b“ ou outros modelos open-source mais parrudos.

Para esses casos mais extremos, tenho um MacBook M4 com 128GB de RAM (que vamos chamar de m4128). Só que este é o meu computador que “fica parado”. Como gravo e edito bastante conteúdo, este computador fica com câmeras, microfones e várias outras coisas conectadas o tempo todo. Eu sei que poderia desconectar tudo e usá-lo como um laptop, mas manter tudo conectado evita atrito na hora de gravar algo novo. Só preciso pressionar um simples botão e já “estou no-ar”.

Para complicar um pouco mais a história, o laptop da minha esposa estragou a tela e ficou encostado por meses. Quando consultamos o preço para troca da tela, valia mais comprar outro do que mantê-lo.

Em um belo dia, decidi instalar o Asahi Linux neste último laptop (uma versão do Fedora). Não estava com muitas esperanças que tudo funcionasse. Este é um MacBook Air M1 com 8GB de RAM (vamos chamá-lo carinhosamente de fedoraair).

Acontece, que o Fedora rodou tão liso neste MacBook via SSH, que eu só queria usar o bendito Linux.

Três computadores ao mesmo tempo

Agora que você entendeu o cenário, como isso funciona? E, o mais importante: o que isso tem a ver com Docker Context?

Como o fedoraair está com a tela danificada, ele também fica parado. Por isso, continuo usando o m132 o dia todo. Meu ambiente de desenvolvimento está inteiro no terminal, então não preciso de GUI.

E sim, uso as IAs todas (Claude, Codex e Gemini) via CLI sem interface gráfica.

O que fiz foi configurar SSH em todos os computadores. Então, consigo trabalhar por qualquer um deles simplesmente digitando:

ssh m132 # <-- Me conecto por aqui
ssh m4128
ssh fedoraair # <-- E trabalho aqui

Sem perceber, acabei montando o cenário perfeito para o Docker Context. A única coisa que você precisa para isso funcionar da mesma maneira que uso por aqui é uma conexão SSH com o computador ou servidor remoto.

# Do m132 entro no fedoraair
ssh fedoraair

# Do fedoraair rodo comandos normal
docker run ...

# O Docker Context está apontado para m4128
# Então, comandos do Docker CLI, rodam lá
# e não consomem recursos do fedoraair 🥹.

Isso significa que toda vez que estou usando o Docker no fedoraair, estou usando 3 computadores ao mesmo tempo (LITERALMENTE).

O que é o Docker Context?

Ao invés de entrar via SSH para rodar comandos manualmente no m4128, uso o cliente do Docker (o CLI) para enviar comandos remotamente para o motor (engine) do Docker na máquina potente.

Faça esse teste comigo... Vai lá, coragem... Abre esse terminal aí agora e roda o comando:

docker context ls

Você vai ver a lista de contextos configurados na sua máquina.

Por padrão, ele aponta para um Unix Socket local, o que significa que os comandos rodam na sua própria máquina.

Mas nós podemos criar novos contextos para apontar para outras máquinas.

Como criar e usar um Docker Context remotamente

Suponha que eu queira me conectar ao m4128 agora. Posso criar um contexto novo especificamente para isso.

Se você tem um servidor, mesma coisa. Não importa onde ele estiver (só precisa de SSH). Crie o contexto:

docker context create m4128 --docker "host=ssh://USUARIO@HOST_OU_IP"

Muda o nome do contexto para o que quiser. Vou usar m4128 só porque já me acostumei com os nomes.

Dica: Se você já configurou o seu arquivo .ssh/config como eu (ensinei isso neste vídeo), você pode simplesmente usar o alias que você definiu:

docker context create m4128 --docker "host=ssh://m4128"

Para listar e ver se deu tudo certo:

docker context ls

Agora que o contexto foi criado, tudo o que precisamos fazer é dizer ao Docker para usá-lo:

docker context use m4128

A partir deste momento, qualquer comando Docker que você digitar no seu terminal (como docker run, docker service ls ou docker node ls) será executado não na sua máquina local, mas lá no servidor remoto.

A magia disso é que você pode interagir com um Swarm ou subir imagens pesadas no seu provedor de nuvem (como a Hostinger) direto do seu laptop, sem consumir um único MegaByte da sua memória local!

Intromissão sem vergonha 💜

Se precisar de servidor VPS, tenho link e cupom que te dá um belo desconto por até 2 anos se quiser.

https://hostinger.com/otaviomiranda
Cupom: OTAVIOMIRANDA

Obrigado à Hostinger por acreditar no meu conteúdo.

O Cuidado Necessário: Bind Mounts vs Named Volumes

Nem tudo são flores. Ao utilizar esse setup, você precisa ficar atento aos Volumes.

Quando usamos bind mount (que atrela uma pasta local do seu projeto ao container), o Docker tentará fazer o bind da pasta que existe lá no servidor, e não na sua máquina local de onde você disparou o comando. Afinal, o motor do Docker está rodando remotamente.

Como resolver isso?

Se a sua imagem não depende de arquivos locais, você pode usar o setup remoto sem problemas.

Se você precisa de volumes, recomendo utilizar Named Volumes no seu docker-compose.yml.

Exemplo de uso com Named Volumes:

services:
  app:
    image: nginx:latest
    volumes:
      - dados-app:/var/www/html

volumes:
  dados-app:

Dessa forma, o Docker se encarrega de criar e gerenciar o volume na máquina remota, evitando transtornos de sincronização de pastas ou de erros ao tentar mapear uma pasta que só existe no seu computador local.

Existem outras formas de contornar isso, mas essa é, de longe, a mais fácil.

Alternativa com Variável de Ambiente

Para uma alteração rápida, sem precisar criar e salvar um contexto inteiro, você pode utilizar a variável de ambiente DOCKER_HOST:

export DOCKER_HOST=ssh://m4128
docker ps

Ele fará praticamente o mesmo processo, de forma direta e provisória. Recomendo usar o docker context para um setup mais contínuo e organizado.

Seja para economizar recursos locais utilizando um servidor potente ou para gerenciar seu ambiente em nuvem remotamente, o Docker Context via SSH é uma ferramenta indispensável no seu cinto de utilidades DevOps.

Se você gostou deste conteúdo e não quer perder as próximas dicas de só me seguir! Posto aqui e em várias outras redes direto 😘.

Shiki - Syntax highlighter

Fri, 20 Feb 2026 00:00:00 GMT

For my personal use. I just want the end HTML and CSS from Shiki Syntax highlighter (Not the JavaScript). This would be only for pure static sites.

Language:

Theme:

Your beautiful code will be available below.

f-strings em Python: coisas que você não sabia

Mon, 10 Nov 2025 00:00:00 GMT

Este texto explora o uso avançado das f-strings no Python, incluindo concatenação, formatação numérica, representação em diferentes bases e várias outras técnicas que talvez você não conheça.

Eu me baseei na transcrição do meu vídeo original, que você pode assistir aqui:

f-strings em Python: coisas que você não sabia

Mas atenção: o texto não é idêntico ao vídeo. Incluí novos exemplos de código, explicações alternativas e detalhei melhor alguns tópicos que achei interessantes. Espero que você goste!

Dica importante: coloquei MUITA coisa bacana nos comentários dos exemplos de código, não deixe de conferir.

ℹ️ Baseado no meu vídeo original, este texto foi gerado inicialmente com o apoio de Inteligência Artificial e da transcrição do vídeo feita pelo Whisper. Posteriormente, reescrevi o conteúdo para garantir clareza e precisão.

Introdução: concatenando strings com inteiros

Um desafio comum na programação é concatenar strings com outros tipos de dados, como inteiros. Em Python, se você tentar concatenar diretamente uma string com um inteiro, terá um erro de tipo:

numero = 123456789
texto = "Número: "

# Isso gera um erro: TypeError: can only concatenate str (not "int") to str
print(texto + numero)

Para resolver isso, você pode converter explicitamente o inteiro para string usando a função str():

numero = 123456789
texto = "Número: "

# Convertendo o inteiro para string antes da concatenação
print(texto + str(numero))
# Saída: Número: 123456789

Mas as f-strings oferecem uma solução muito mais elegante, legível e eficiente para essa tarefa. Vamos conferir na prática como utilizar esse recurso poderoso do Python!

Introdução às `f-strings`

As f-strings (formatação de string com prefixo f) oferecem uma sintaxe concisa e poderosa para incorporar expressões Python diretamente dentro de uma string (str). Para utilizá-las, basta prefixar a string com f e envolver a expressão desejada entre chaves {}.

Exemplo básico:

numero = 123456789
texto = f"Número: {numero}"
print(texto) # Saída: Número: 123456789

Esse método funciona com strings de uma ou várias linhas, com aspas simples, duplas ou triplas.

Formatação numérica com f-strings

As f-strings facilitam muito a formatação numérica, permitindo aplicar separadores de milhares e definir facilmente quantas casas decimais você quer exibir.

Separadores de milhares

Você pode utilizar underscores (_) ou vírgulas (,) após os dois pontos (:) dentro das chaves para destacar os milhares. Veja os exemplos:

numero = 123456789

# Usando underscore como separador de milhares
print(f"Número com underscores: {numero:_}")  # Saída: 123_456_789

# Usando vírgula como separador de milhares
print(f"Número com vírgulas: {numero:,}")     # Saída: 123,456,789

Esses formatos deixam os números grandes bem mais fáceis de ler!

Definindo casas decimais com `.nf`

Para formatar números com ponto flutuante usando f-strings, basta utilizar .nf, onde n é a quantidade desejada de casas decimais após o ponto.

Veja os exemplos:

numero_float = 198.7654321

# Limitando a duas casas decimais
print(f"Duas casas decimais: {numero_float:.2f}")  # Saída: 198.77

# Arredondando para inteiro (sem casas decimais)
print(f"Sem casas decimais: {numero_float:.0f}")   # Saída: 199

# Limitando a quatro casas decimais
print(f"Quatro casas decimais: {numero_float:.4f}")  # Saída: 198.7654

Com isso você consegue controlar exatamente como seu número será exibido.

Combinando separador de milhares e casas decimais

Você também pode combinar os separadores de milhares com a definição de casas decimais, tudo numa única f-string. Veja o exemplo:

numero_float = 19876.54321

# Separador de milhares com vírgula e duas casas decimais
print(f"Formatado: {numero_float:,.2f}")  # Saída: 19,876.54

Essa abordagem é especialmente útil em dashboards, relatórios financeiros e interfaces voltadas ao usuário, tornando os valores numéricos bem mais legíveis.

Exibindo sinais (positivo e negativo)

É possível exibir explicitamente os sinais positivos ou negativos em números usando o símbolo +. Veja o exemplo:

numero_positivo = 10
numero_negativo = -10

# Exibindo explicitamente o sinal positivo
print(f"Número positivo: {numero_positivo:+d}")  # Saída: +10

# Número negativo já exibe o sinal por padrão
print(f"Número negativo: {numero_negativo:d}")   # Saída: -10

Observação: O sinal + força a exibição do sinal também em números positivos. Para negativos, o sinal aparece automaticamente.

Porcentagem

Para representar números como porcentagem, utilize o especificador % junto com a quantidade desejada de casas decimais:

porcentagem = 0.98

# Exibindo porcentagem com duas casas decimais
print(f"Porcentagem: {porcentagem:.2%}")  # Saída: 98.00%

Conversões avançadas: `bytes`, `int`, `str` e `hex`

É possível realizar conversões entre diferentes tipos, como string, inteiro, hexadecimal, octal, binário, ASCII, bytes e outros formatos usando funções internas (built-ins) do Python. Quando combinamos essas funções com as f-strings, temos um poder imenso nas mãos.

Além disso, usando !r dentro das f-strings, você exibe diretamente a representação interna do objeto (o mesmo que usar repr()).

Importante: Ao usar f-strings, os objetos são automaticamente convertidos para strings (str). Strings têm métodos especiais como encode para converter em bytes, e bytes têm o método decode para voltar para string. Você pode conferir mais detalhes sobre esse assunto no artigo:

Normalização Unicode em Python

Agora, veja na prática como converter um inteiro em hexadecimal, depois em bytes, em string novamente, e finalmente voltar ao inteiro original. Este exemplo combina várias técnicas que você pode usar em Python:

# Número inteiro original
num = 255  # inteiro normal: 255

# Convertendo inteiro para hexadecimal (str)
int_to_hex = f'{num:x}'  # resultado: 'ff'

# Convertendo o hexadecimal (str) em bytes
hex_to_bytes = int_to_hex.encode('utf-8')  # resultado: b'ff'

# Convertendo bytes de volta para string
bytes_to_str = hex_to_bytes.decode('utf-8')  # resultado: 'ff'

# Finalmente, convertendo a string hexadecimal de volta para inteiro
hex_to_int = int(bytes_to_str, 16)  # resultado: 255

# Exibindo representações internas usando !r (repr)
print(f"{num = !r}")           # num = 255
print(f"{int_to_hex = !r}")    # int_to_hex = 'ff'
print(f"{hex_to_bytes = !r}")  # hex_to_bytes = b'ff'
print(f"{bytes_to_str = !r}")  # bytes_to_str = 'ff'
print(f"{hex_to_int = !r}")    # hex_to_int = 255

# Exemplos adicionais com :o, :b, :x e :X
print(f"Inteiro: {num = }")          # Inteiro: num = 255
print(f"Octal: {num = :o}")          # Octal: num = 377
print(f"Binário: {num = :b}")        # Binário: num = 11111111
print(f"Hexadecimal: {num = :x}")    # Hexadecimal: num = ff
print(f"HEXADECIMAL: {num = :X}")    # HEXADECIMAL: num = FF

Entendendo as formatações usadas:

:o exibe o valor em octal.
:b exibe o valor em binário.
:x exibe o valor em hexadecimal (letras minúsculas).
:X exibe o valor em hexadecimal (letras maiúsculas).
!r exibe a representação do objeto (equivalente ao repr()).
= exibe também a expressão que gerou o valor dentro da f-string (num = valor_de_num).

É bastante coisa nova, né? A seguir eu explico tudo isso com mais detalhes!

O Operador Walrus (`:=`) em f-strings

O operador Walrus (:=) permite atribuir valores diretamente dentro de expressões, inclusive dentro de f-strings.

Com ele, você faz uma atribuição inline e já reutiliza o valor calculado imediatamente, sem precisar declarar a variável previamente.

Veja o exemplo abaixo: temos uma sequência de bytes que representa a palavra "Otávio" codificada em UTF-8. Primeiro, decodificamos essa sequência para uma string. Depois, usando o operador Walrus dentro da f-string, atribuímos esse valor a uma variável mais curta (v), que pode ser reutilizada em seguida.

# Sequência de bytes que representa a palavra "Otávio"
my_name = b'\x4f\x74\xc3\xa1\x76\x69\x6f'

# Decodificando bytes para uma variável com nome longo
variavel_longa_e_chata = my_name.decode('utf-8')  # resultado: "Otávio"

# Usando operador Walrus diretamente dentro da f-string para atribuir a `v`
print(f"Saída: {(v := variavel_longa_e_chata) = }")
# Saída: (v := variavel_longa_e_chata) = 'Otávio'

# Agora `v` já está disponível para reutilização
print(f"Reutilizando `v`: {v} foi muito legal. {v}")
# Saída: Reutilizando `v`: Otávio foi muito legal. Otávio

O trecho {(v := variavel_longa_e_chata) = } dentro da f-string exibe tanto o código executado quanto o valor atribuído. Isso é especialmente útil em debug, logs ou simplesmente para mostrar valores intermediários sem precisar criar variáveis separadas antes do print.

Nota: A sequência de bytes \x4f\x74\xc3\xa1\x76\x69\x6f, decodificada com UTF-8, forma a palavra "Otávio".

Trabalhando com datas e horas usando `f-strings`

A seguir vou mostrar diversos exemplos práticos sobre formatação de datas, horas, minutos, segundos, milissegundos e microsegundos usando f-strings. Esses formatos são úteis em praticamente qualquer aplicação que envolva manipulação de datas e horários.

Transformando segundos em horas, minutos e segundos (`H:M:S`)

Nesse exemplo, você vai aprender como formatar uma quantidade total de segundos no formato tradicional horas:minutos:segundos (H:M:S).

Primeiro, vamos criar uma função simples para fazer essa conversão pra gente:

def calcula_segundos_para_horas(segundos: int) -> tuple[int, int, int]:
    """
    Converte uma quantidade total de segundos em horas, minutos e segundos.

    Exemplo de uso:
        h, min, seg = calcula_segundos_para_horas(31989)
    """
    horas = segundos // 60 // 60
    minutos = segundos // 60 % 60
    segundos = segundos % 60

    return horas, minutos, segundos

Agora, vamos brincar com as f-strings pra exibir o tempo formatado:

# 8 horas, 53 minutos, 9 segundos
# Total desejado: 08:53:09
total_de_segundos = 31989
horas, minutos, segundos = calcula_segundos_para_horas(total_de_segundos)

# Sem formatação (resultado incorreto visualmente)
print(f"Tempo: {horas}:{minutos}:{segundos}")
# Saída: Tempo: 8:53:9

# Com formatação (padding com zeros à esquerda)
print(f"Tempo: {horas:02}:{minutos:02}:{segundos:02}")
# Saída correta: Tempo: 08:53:09

Também é possível exibir essa mesma informação de forma mais descritiva:

# Exibindo de forma mais amigável
print(f"{horas} horas, {minutos} minutos e {segundos} segundos")
# Saída: 8 horas, 53 minutos e 9 segundos

Você até pode inserir uma condicional diretamente dentro da f-string, embora, na minha opinião, fique meio feio e bagunçado dependendo da complexidade. Porém, às vezes pode ser útil:

# Retirando os 9 segundos para zerar o valor
total_de_segundos = 31980
horas, minutos, segundos = calcula_segundos_para_horas(total_de_segundos)

# Criando uma string condicional para exibir segundos somente se forem maiores que zero
texto_segundos = f", {segundos} segundos"
print(f"{horas} horas, {minutos} minutos{texto_segundos if segundos > 0 else ''}")
# Saída: 8 horas, 53 minutos

Para situações mais complexas, o ideal seria criar uma função de formatação separada, principalmente para evitar coisas estranhas como "1 segundos", que fica bem feio, né?

Se suas contas eventualmente retornarem números em ponto flutuante (float), você pode formatar assim, garantindo que não haverá casas decimais:

print(f"Tempo: {horas:02.0f}:{minutos:02.0f}:{segundos:02.0f}")

Explicando rapidamente o significado de :02.0f:

: inicia a formatação;
02 indica que o número deve ter dois caracteres no total, preenchidos com zeros à esquerda se necessário (1 vira 01);
.0f significa que não desejamos nenhuma casa decimal (nem mesmo o ponto).

Manipulação de horas usando `f-string`, `datetime` e `timedelta`

Vamos criar uma data base apenas para facilitar a formatação de horas. Neste momento não precisamos de uma data real, então vou usar algo bem simples: datetime(1, 1, 1, 8, 23, 1). Isso representa o horário 08:23:01.

from datetime import datetime

# Criando a hora base
hora = datetime(1, 1, 1, 8, 23, 1)

# Formatando com strftime()
print(f"Hora: {hora.strftime('%H:%M:%S')}")
# Saída: Hora: 08:23:01

Dica: Os valores %H, %M e %S representam, respectivamente, horas, minutos e segundos com zero à esquerda. Veja todas as opções disponíveis na documentação do Python.

Você também pode usar timedelta para adicionar ou subtrair tempo facilmente. Vamos ver isso em ação:

from datetime import datetime, timedelta

# Hora inicial: 00:00:00
hora_inicial = datetime(1, 1, 1, 0, 0, 0)

# Adicionando 10 horas, 7 minutos e 10 segundos
tempo_adicional = timedelta(hours=10, minutes=7, seconds=10)
nova_hora = hora_inicial + tempo_adicional

# Formatando com strftime()
print(f"Nova hora: {nova_hora.strftime('%H:%M:%S')}")
# Saída: Nova hora: 10:07:10

# Adicionando mais 10 segundos
nova_hora += timedelta(seconds=10)

# Formatando diretamente com f-string (sem strftime explícito)
print(f"Nova hora: {nova_hora:%H:%M:%S}")
# Saída: Nova hora: 10:07:20

Microssegundos e milissegundos usando `f-string`

Como faço muitos vídeos diariamente, preciso lidar bastante com pequenas frações de segundos pra sincronizar legendas e transcrições. O formato típico usado nas legendas SRT (SubRip) é assim: 00:00:00,000, onde 000 são milissegundos.

A lógica é parecida com a que expliquei anteriormente. Veja na prática:

from datetime import datetime

# Criando um tempo base: 00:02:23
tempo_do_video = datetime(1, 1, 1, 0, 2, 23)

# Exibindo o tempo sem microsegundos
print(f"{tempo_do_video:%H:%M:%S}")
# Saída: 00:02:23

Agora vamos adicionar microssegundos e milissegundos usando timedelta:

from datetime import datetime, timedelta

# Tempo base novamente: 00:02:23
tempo_do_video = datetime(1, 1, 1, 0, 2, 23)

# Adicionando 111 microssegundos (devem aparecer nas últimas três casas)
tempo_do_video += timedelta(microseconds=111)
print(f"{tempo_do_video:%H:%M:%S,%f}")
# Saída: 00:02:23,000111

# Resetando ao valor inicial
tempo_do_video = datetime(1, 1, 1, 0, 2, 23)

# Agora adicionando 111 milissegundos (primeiras três casas após a vírgula)
tempo_do_video += timedelta(milliseconds=111)
print(f"{tempo_do_video:%H:%M:%S,%f}")
# Saída: 00:02:23,111000

# Exibindo apenas milissegundos, removendo os três últimos dígitos com fatiamento
print(f"{tempo_do_video:%H:%M:%S,%f}"[:-3])
# Saída: 00:02:23,111

O que acontece nesse trecho [:-3] é o seguinte: estou removendo as últimas 3 posições da string resultante, o que chamamos de fatiamento de strings (slicing). Isso é bastante útil quando precisamos adaptar rapidamente o formato das strings.

Manipulação de datas usando `f-string`, `datetime` e `timedelta`

Só pra reforçar, a formatação de datas completas usando f-strings é exatamente igual ao que vimos com horas. Veja alguns exemplos práticos:

import locale
from datetime import datetime

# Configurando o locale para o padrão brasileiro (datas, números, etc.)
locale.setlocale(locale.LC_ALL, 'pt_BR')

# Exemplo de data: 02/12/1987 às 10:59:23
nascimento_joaozinho = datetime(1987, 12, 2, 10, 59, 23)

# Formatando a data completa com f-string
print(f"{nascimento_joaozinho:%d de %B de %Y às %H:%M:%S}")
# Saída: 02 de Dezembro de 1987 às 10:59:23

# Outro exemplo mais detalhado
print(
    f"Joãozinho nasceu no ano de {nascimento_joaozinho:%y}. "
    f"Estávamos no mês de {nascimento_joaozinho:%B}, "
    f"dia {nascimento_joaozinho:%d}. "
    f"Era um dia chuvoso, e o relógio marcava "
    f"{nascimento_joaozinho:%H horas e %M minutos}."
)
# Saída:
# Joãozinho nasceu no ano de 87.
# Estávamos no mês de Dezembro, dia 02.
# Era um dia chuvoso, e o relógio marcava 10 horas e 59 minutos.

Ok, talvez eu tenha exagerado nesse último exemplo... 😅 Mas acho que você sacou a ideia e provavelmente é isso que você vai usar no dia a dia.

Representação de objetos com f-strings: `!r`, `!s`, `!a`

Dentro das f-strings você pode exibir a representação de um objeto usando os sufixos !s, !r ou !a. Cada um chama respectivamente as funções internas do Python: str(), repr() e ascii() sobre o valor exibido.

Para entender melhor, vamos criar uma classe simples e ver esses métodos em ação:

class Pessoa:
    def __init__(self, nome: str, sobrenome: str, idade: int) -> None:
        self.nome = nome
        self.sobrenome = sobrenome
        self.idade = idade

    def __repr__(self) -> str:
        cls_name = self.__class__.__name__
        attrs = ", ".join(
            f"{chave}={valor!r}" for chave, valor in self.__dict__.items()
        )
        return f"{cls_name}({attrs})"

    def __str__(self) -> str:
        return f"{self.nome} {self.sobrenome}"

Usando `!s` — chama o método `str`

pessoa = Pessoa("Luiz Otávio", "Miranda", 30)

print(f"{pessoa}")    # Saída: Luiz Otávio Miranda
print(f"{pessoa!s}")  # Mesma saída acima; !s chama explicitamente str()

Aqui o Python usa o método __str__, gerando uma versão amigável e legível para humanos.

Usando `!r` — chama o método `repr`

print(f"{pessoa!r}")
# Saída: Pessoa(nome='Luiz Otávio', sobrenome='Miranda', idade=30)

Agora o Python usa o método __repr__, que gera uma string detalhada e idealmente útil para recriar o objeto.

Usando `!a` — chama o método `ascii()`

O método ascii() funciona como repr(), porém escapa caracteres não-ASCII, substituindo-os por sequências especiais (\x, \u ou \U):

print(f"{pessoa!a}")
# Saída: Pessoa(nome='Luiz Ot\xe1vio', sobrenome='Miranda', idade=30)

Note que o caractere “á” (fora do padrão ASCII básico) foi convertido para \xe1.

Explorando escapes: de `á` para `\xe1` e de volta

valor = "á"

print("\xe1")        # '\x' + e1 → á
print("\u00e1")      # '\u' + 00e1 → á
print("\U000000e1")  # '\U' + 000000e1 → á

# De caractere para hexadecimal:
valor_hex = hex(ord(valor))   # '0xe1'

# De hexadecimal para caractere:
print(chr(int(valor_hex, 16)))  # á

Os primeiros 128 códigos Unicode coincidem com os 128 caracteres ASCII originais. Como “á” fica no ponto de código 225, ele está fora desse intervalo — por isso é escapado.

Para mergulhar mais fundo nesse assunto, confira o artigo normalização Unicode em Python.

Padding e Alinhamento de Strings e Números com f-strings

F-strings oferecem controle preciso sobre o preenchimento (padding) e o alinhamento do texto dentro de um espaço definido. Isso é feito utilizando especificadores de formatação dentro das chaves {}, após os dois pontos :.

A sintaxe geral de formatação é :{fill}{align}{width}, onde:

fill (opcional): O caractere a ser usado para preencher o espaço. Se omitido, o padrão é espaço ( ).
align (opcional): O tipo de alinhamento.
- <: Alinha o texto à esquerda (padrão para strings).
- >: Alinha o texto à direita (padrão para números).
- ^: Centraliza o texto.
width: A largura total mínima do campo. O texto será preenchido até atingir essa largura.

Vamos ver alguns exemplos práticos de como aplicar esses especificadores:

nome = "Python" # Alterado para "Python" para um exemplo mais genérico

# --- Alinhamento com Espaços (padding padrão) ---
print(f"'{nome:<15}'") # Aspas para visualizar o padding
# Alinhamento à esquerda (padrão para strings), preenchido com espaços até 15 caracteres.
# Saída: 'Python         '

print(f"'{nome:>15}'")
# Alinhamento à direita, preenchido com espaços até 15 caracteres.
# Saída: '         Python'

print(f"'{nome:^15}'")
# Alinhamento ao centro, preenchido com espaços até 15 caracteres.
# Saída: '    Python     '

# Para números, o preenchimento com '0' à esquerda é comum
numero_item = 7
print(f"{numero_item:03}")
# Preenchimento com '0' à esquerda até 3 caracteres (útil para numeração).
# Saída: 007

# Você pode usar qualquer caractere para preencher. O caractere de
# preenchimento vem ANTES do alinhamento.
produto_id = "ABC"
print(f"ID: {produto_id:x<10}")
# Preenche com 'x' e alinha à esquerda
# Saída: ID: ABCxxxxxxx

preco = 123.45
print(f"Preço: {preco:*>12.2f}")
# Preenche com '*' e alinha à direita, 2 casas decimais
# Saída: Preço: ******123.45

# Numeração de arquivos com zeros à esquerda (ex: 000001.mp4)
for i in range(3):
    print(f"{i:06}.mp4")
# Saída:
# 000000.mp4
# 000001.mp4
# 000002.mp4

# Alinhamento e preenchimento combinado para um formato específico
valor = 1048576
print(f"Resultado: {valor:!<20}")
# Preenchimento com '!' à esquerda, alinhamento à esquerda, largura total de 20.
# Saída: Resultado: 1048576!!!!!!!!!!!!!

Inserindo expressões e sinal de igual (`=`) em f-strings

As f-strings permitem inserir diretamente expressões Python no texto e, melhor ainda, exibir automaticamente a expressão seguida do seu resultado usando o sinal de igual (=).

Por exemplo, ao invés de fazer algo assim para debug:

print(f"variavel = {variavel}")

você pode simplificar para:

print(f"{variavel = }")

O resultado será exatamente o mesmo, exibindo tanto a expressão quanto o valor atribuído. Veja vários exemplos abaixo (não esqueça de ler os comentários!):

x = 3.55
y = 7.12

# Forma tradicional, sem o sinal de igual automático:
print(f"{x} + {y} = {x + y}")  # Saída: 3.55 + 7.12 = 10.67

# Forma simplificada usando "=" dentro das chaves (ideal para debug)
print(f"{x = }, {y = }, {x + y = }")
# Saída: x = 3.55, y = 7.12, x + y = 10.67

# Usando expressões com literais diretamente:
print(f"5 * 2 = {5 * 2}")  # Saída: 5 * 2 = 10

# Exibindo o valor de uma variável diretamente:
firstName = "Luiz Otávio"
print(f"{firstName}")      # Saída: Luiz Otávio

# Exibindo com o sinal de igual:
print(f"{firstName = }")   # Saída: firstName = 'Luiz Otávio'

Conclusão

Nesse artigo, exploramos várias formas poderosas de usar as f-strings em Python. Começamos com concatenação básica, passamos pela formatação numérica avançada (controle de casas decimais, separadores de milhares), manipulamos datas e horas, representamos objetos, e terminamos mostrando a avaliação direta de expressões com o prático sinal de igual (=).

Dominar f-strings é fundamental pra você, que busca escrever código Python mais limpo, direto e eficiente, especialmente na hora de manipular textos e dados.

Se você chegou até aqui, espero de verdade que tenha aprendido coisas novas. Mesmo eu trabalhando há anos com Python e programação, ainda aprendo muita coisa enquanto escrevo esses textos e gravo meus vídeos.

Até o próximo artigo! ✌️

Transcreva áudio com Python: Sussu CLI + OpenAI Whisper

Sat, 25 Oct 2025 00:00:00 GMT

Essa é uma ferramenta de linha de comando focada em educação e IA offline. Utiliza o poder do Whisper da OpenAI para transcrever áudios e vídeos de forma simples e eficiente.

Esses são todos os links que menciono nos dois vídeos:

whisper em tempo real via microfone - Link
logging — Logging facility for Python - Link
sussu(rro): CLI educacional com OpenAI Whisper - Link
openai / whisper - Link

Vídeos:

Vídeo da parte 1 - Guia Whisper OpenAI Completo
Vídeo da Parte 2 - Whisper e Sussu no seu projeto

Sobre o Whisper e a OpenAI

Estava curioso para saber se a OpenAI usa o Whisper em seus próprios produtos, então questionei o ChatGPT...

Eu: A OpenAI usa o Whisper internamente em algum recurso que as pessoas consomem?
ChatGPT: Sim, a OpenAI usa o Whisper como base para recursos de transcrição e compreensão de áudio em produtos como o ChatGPT com entrada de voz. Ele também é utilizado em APIs que envolvem reconhecimento de fala, como a speech-to-text da OpenAI.

Sobre este documento:

Estou tentando manter este documento (README.md) sincronizado com o link abaixo. Caso não encontre o que procura aqui, acesse:

Transcreva áudio com Python: Sussu CLI + OpenAI Whisper

Introdução geral

Ao rodar este projeto, uma das primeiras coisas que você vai querer fazer é usar o comando whisper para fazer a transcrição inicial de algum vídeo ou áudio. Essa transcrição é um ótimo jeito de ver na prática como o Whisper trabalha e o que esperar dos resultados.

Vamos começar pela instalação do projeto, isso já coloca os comandos sussu e whisper funcionando direto no seu terminal.

Instalação do `sussu`

Se você encontrar alguma dificuldade com o ambiente, recomendo meu tutorial completo:

Ambiente Python Moderno 2025: UV, Ruff, Pyright, pyproject.toml e VS Code

Este projeto utiliza o Python 3.11.9 por questões de compatibilidade com o Whisper. Evite alterar essa versão se não souber o que está fazendo, pois eu já testei tudo para você.

Além disso, este projeto usa o uv para o gerenciamento geral (pacotes, versão do Python, etc.).

Para instalar tudo, basta rodar o comando:

# Se ainda não clonou o repositório
git clone https://github.com/luizomf/sussu.git
# Acesse a pasta do projeto
cd sussu
# Sincronizando
uv sync
# é só isso mesmo 😅

uv sync é suficiente para:

Baixar e instalar o python 3.11.9
Criar o ambiente virtual em .venv
Instalar os pacotes necessários
Buildar o whisper e o sussu

`ffmpeg`

Você também precisará ter o ffmpeg instalado. Ele é um software de código aberto com várias ferramentas e bibliotecas para trabalhar com arquivos multimídia, especialmente áudio e vídeo. Embora o whisper foque na transcrição de áudio, o ffmpeg é quem permite que você transcreva seus vídeos diretamente, sem precisar convertê-los para áudio antes.

Para instalar o ffmpeg no seu sistema, você pode usar um dos comandos abaixo. Eles foram retirados diretamente do repositório oficial do whisper:

# No Ubuntu ou Debian
sudo apt update && sudo apt install ffmpeg

# No Arch Linux
sudo pacman -S ffmpeg

# No macOS com Homebrew (https://brew.sh/)
brew install ffmpeg

# No Windows com Chocolatey (https://chocolatey.org/)
choco install ffmpeg

# No Windows usando Scoop (https://scoop.sh/)
scoop install ffmpeg

# Adicional: No Windows usando winget (https://winstall.app/apps/Gyan.FFmpeg)
winget install --id=Gyan.FFmpeg -e

Observação: Dos comandos listados, os únicos que testei e aprovei (✅) foram os para macOS e Ubuntu.

Rodando pela Primeira Vez

Para verificar se tudo foi instalado corretamente, você tem duas opções: ativar o ambiente virtual ou usar o comando uv run. Sugiro que você teste com whisper -h. Esse comando deve exibir a ajuda completa do whisper, indicando que ele está funcionando. Veja os exemplos:

uv run whisper -h
# Ou, se você já ativou o ambiente virtual
whisper -h

Observação: Editores de código como VS Code ou Zed podem ativar o ambiente virtual automaticamente ao abrir um novo terminal, desde que estejam configurados corretamente. Se for o seu caso, basta fechar e abrir o terminal novamente para que as mudanças façam efeito.

`whisper -h`: Entendendo Alguns Argumentos Importantes

Ao digitar whisper -h ou whisper --help, você pode se surpreender com a quantidade de argumentos disponíveis. Mas não se preocupe! Você não precisa saber o que cada um deles faz. Na verdade, a maioria dos argumentos já vem com valores padrão que funcionam perfeitamente. No entanto, se você quiser personalizar um pouco o comportamento da ferramenta, vamos analisar alguns dos mais importantes.

O whisper utiliza a biblioteca argparse do Python para gerar essa documentação de ajuda (help) completa e bem organizada. Se você tiver interesse em aprender mais sobre como criar interfaces de linha de comando profissionais com Python, confira meu vídeo:

Python e argparse: Do Zero a uma CLI Profissional (Projeto Real na Prática)

Argumentos Essenciais do `whisper`

Vamos começar com os argumentos que você usará com mais frequência:

audio: Este é o argumento posicional principal. Ele representa o caminho completo (localização) do arquivo de áudio ou vídeo que você quer transcrever.

Exemplo:

whisper /caminho/do/seu/arquivo.mp4

No exemplo acima, você notou que especificamos apenas o caminho do arquivo de vídeo. Nas próximas seções, vou detalhar as opções que mais utilizo para personalizar a transcrição.

--model MODEL: Este argumento serve para definir qual modelo será usado na transcrição do seu áudio ou vídeo. Ele é opcional, e o valor padrão é turbo. O modelo turbo é excelente: rápido e multilíngue, mas requer cerca de 6GB de VRAM para rodar.

Talvez você queira usar outros modelos que exigem mais ou menos recursos do seu hardware, ou que possuem mais ou menos parâmetros (como base, small, medium, etc.).

Aqui estão os modelos disponíveis e seus requisitos aproximados de VRAM:

tiny: 39M parâmetros, tiny.en e tiny, VRAM ~1 GB
base: 74M parâmetros, base.en e base, VRAM ~1 GB
small: 244M parâmetros, small.en e small, VRAM ~2 GB
medium: 769M parâmetros, medium.en e medium, VRAM ~5 GB
large: 1550M parâmetros, large, large-v2 e large-v3, VRAM ~10 GB
turbo: 809M parâmetros, turbo, VRAM ~6 GB

VRAM é um tipo de memória RAM especializada que as placas de vídeo (GPUs) usam. Mas não se preocupe se você não tiver uma placa de vídeo dedicada! Se seu computador compartilha a RAM com a GPU, o que acontece em Macs com chips Apple Silicon (M1, M2, M3 e posteriores), por exemplo, você conseguirá usar os modelos do Whisper normalmente.

Nesses casos, o que realmente limita é a quantidade total de memória RAM disponível no seu sistema. Por exemplo: se você tem apenas 8GB de RAM, o ideal é testar os modelos tiny, base ou small.

A partir do modelo medium, é bem provável que você perceba uma queda drástica no desempenho geral da sua máquina, já que a memória será completamente consumida.

Exemplo:

whisper /caminho/do/seu/arquivo.mp4 --model large-v2

--device DEVICE: Este argumento é para você que possui uma placa de vídeo NVIDIA com drivers CUDA e uma versão compatível com o PyTorch. Se for o seu caso, vale a pena usar --device cuda para aproveitar o processamento da GPU. Caso contrário, não se preocupe em alterar esta opção, o padrão é cpu (processamento pela CPU) e funcionará perfeitamente.

Exemplo:

whisper /caminho/do/seu/arquivo.mp4 --model large-v2 --device cpu

--output_dir ou -o: Define o caminho da pasta onde as transcrições serão salvas. Por padrão, os arquivos serão salvos na raiz do projeto (.).

--output_format ou -f: Permite que você escolha o formato da transcrição ou legenda gerada. As opções disponíveis são: txt, vtt, srt, tsv, json e all (que gera todos os formatos). O padrão é all.

Exemplo:

O arquivo de saída será srt (SubRip) na pasta indicada em -o. Essa pasta será criada caso não exista.

whisper /caminho/do/seu/arquivo.mp4 --model turbo -o caminho/da/pasta_de_saida -f srt

--task: Com este argumento, você pode escolher entre transcrever o áudio no idioma original ou traduzir para o inglês. As opções são transcribe (o padrão, que transcreve no idioma falado no áudio) ou translate (que traduz o conteúdo para o inglês).

Exemplo:

whisper /caminho/do/seu/arquivo.mp4 --model turbo --task transcribe

--language: Este argumento permite que você especifique o idioma falado no áudio ou vídeo. Existem muitas opções de idiomas disponíveis. Se você não informar esse argumento, o whisper é inteligente o suficiente para detectar automaticamente o idioma do conteúdo.

Forma curta (language code):

["af", "am", "ar", "as", "az", "ba", "be", "bg", "bn", "bo", "br", "bs", "ca",
"cs", "cy", "da", "de", "el", "en", "es", "et", "eu", "fa", "fi", "fo", "fr",
"gl", "gu", "ha", "haw", "he", "hi", "hr", "ht", "hu", "hy", "id", "is", "it",
"ja", "jw", "ka", "kk", "km", "kn", "ko", "la", "lb", "ln", "lo", "lt", "lv",
"mg", "mi", "mk", "ml", "mn", "mr", "ms", "mt", "my", "ne", "nl", "nn", "no",
"oc", "pa", "pl", "ps", "pt", "ro", "ru", "sa", "sd", "si", "sk", "sl", "sn",
"so", "sq", "sr", "su", "sv", "sw", "ta", "te", "tg", "th", "tk", "tl", "tr",
"tt", "uk", "ur", "uz", "vi", "yi", "yo", "yue", "", "zh"]

Exemplo para português do Brasil: --language pt

Forma longa (language name):

["Afrikaans", "Albanian", "Amharic", "Arabic", "Armenian", "Assamese",
"Azerbaijani", "Bashkir", "Basque", "Belarusian", "Bengali", "Bosnian",
"Breton", "Bulgarian", "Burmese", "Cantonese", "Castilian", "Catalan",
"Chinese", "Croatian", "Czech", "Danish", "Dutch", "English", "Estonian",
"Faroese", "Finnish", "Flemish", "French", "Galician", "Georgian", "German",
"Greek", "Gujarati", "Haitian", "Haitian Creole", "Hausa", "Hawaiian", "Hebrew",
"Hindi", "Hungarian", "Icelandic", "Indonesian", "Italian", "Japanese",
"Javanese", "Kannada", "Kazakh", "Khmer", "Korean", "Lao", "Latin", "Latvian",
"Letzeburgesch", "Lingala", "Lithuanian", "Luxembourgish", "Macedonian",
"Malagasy", "Malay", "Malayalam", "Maltese", "Mandarin", "Maori", "Marathi",
"Moldavian", "Moldovan", "Mongolian", "Myanmar", "Nepali", "Norwegian",
"Nynorsk", "Occitan", "Panjabi", "Pashto", "Persian", "Polish", "Portuguese",
"Punjabi", "Pushto", "Romanian", "Russian", "Sanskrit", "Serbian", "Shona",
"Sindhi", "Sinhala", "Sinhalese", "Slovak", "Slovenian", "Somali", "Spanish",
"Sundanese", "Swahili", "Swedish", "Tagalog", "Tajik", "Tamil", "Tatar",
"Telugu", "Thai", "Tibetan", "Turkish","Turkmen", "Ukrainian", "Urdu", "Uzbek",
"Valencian", "Vietnamese", "Welsh", "Yiddish", "Yoruba"]

Exemplo para português do Brasil: --language Portuguese

Se precisar de um dicionário completo com todos os idiomas e seus códigos, ele está disponível em whisper.tokenizer.LANGUAGES dentro do código do whisper.

Exemplo:

# Para o comando ficar menor, vou manter tudo padrão
# model turbo (padrão)
# task transcribe (padrão)
# etc...
# Idioma falado no vídeo "Português"
whisper /caminho/do/seu/arquivo.mp4 --language pt

--temperature: controla a "criatividade" do modelo. Vai de 0.0 a 1.0. Quanto mais alto, mais liberdade o modelo tem pra decidir os próximos tokens. Esse parâmetro interage com --beam_size, --patience e --best_of.

--beam_size: número de hipóteses que o modelo mantém em paralelo. Pensa como se ele testasse vários caminhos ao mesmo tempo e no fim escolhesse o melhor. O padrão é 5 e só funciona se --temperature == 0.0.

--patience: fator de tolerância que faz o modelo continuar explorando novas hipóteses mesmo depois de achar uma aceitável. Requer --temperature == 0.0 e --beam_size > 1.

--best_of: número de amostras diferentes geradas antes de escolher a melhor. Funciona apenas quando --temperature > 0.0.

Cola rápida:

- temperature > 0 → usa sampling
  ✅ --best_of 5 (5 amostras)
  🔴 --beam_size (ignorado)
  🔴 --patience (ignorado)

- temperature == 0 → usa beam search
  ✅ --beam_size 5 (5 hipóteses)
  ✅ --patience 2 (2 x 5 = 10 hipóteses)
  🔴 --best_of (ignorado)

- temperature == 0 → greedy
  ✅ --beam_size 1 (1 hipótese)
  🔴 --patience (não faz diferença)
  🔴 --best_of (ignorado)

Importante: Quanto maiores os valores de --beam_size, --patience e --best_of, mais lento e "indeciso" o modelo tende a ficar. Isso acontece porque ele precisa gerar mais hipóteses ou amostras e, em seguida, tomar uma decisão entre elas. Faça testes rápidos para confirmar esse comportamento.

Observação sincera:

Na prática, o modelo vai responder como foi treinado, independente do seu capricho nas configs. Trocar temperature, beam_size, patience e afins pode virar desperdício de tempo.

Recomendação direta: só mexa nessas opções se:

o modelo começar a repetir palavras (loop)
estiver errando demais em blocos grandes

Se for só por causa de uma ou duas palavras... aceita e segue. Ou então faz igual eu: testa tudo por uma semana e conclui que o padrão já era bom 😅

Exemplo:

O arquivo de saída será srt (SubRip) na pasta indicada em -o. Essa pasta será criada caso não exista.

# Greedy: Mais rápido, mas pode errar mais por considerar apenas uma hipótese por vez.
whisper /caminho/do/seu/arquivo.mp4 --temperature 0.0 --beam_size 1

# Beam Search: Utiliza 3 hipóteses em paralelo.
# O 'patience' padrão é 1.
whisper /caminho/do/seu/arquivo.mp4 --temperature 0.0 --beam_size 3

# Sampling: Gera 5 amostras diferentes para escolher a melhor.
whisper /caminho/do/seu/arquivo.mp4 --temperature 0.7 --best_of 5

--temperature_increment_on_fallback: Este argumento permite que você aumente a temperatura do modelo em casos de falha na transcrição. Se o modelo encontrar dificuldades na temperatura 0.0, ele fará um "fallback" e tentará com a temperatura incrementada. O valor também varia de 0.0 a 1.0. No entanto, cuidado: definir 0.0 para este argumento causará um erro ZeroDivisionError: float division by zero (isso pode ser um pequeno "bugzinho" 🫣, mas, de fato, não faria muito sentido usar zero aqui, já que o objetivo é justamente incrementar a temperatura). O valor padrão é 0.2.

--max_line_width: Define a quantidade máxima de caracteres por linha na sua legenda. O valor padrão é 1000 (um limite bastante alto, codificado diretamente na classe SubtitlesWriter do whisper). Eu, particularmente, costumo usar 45 para uma melhor legibilidade. Importante: Se este argumento for utilizado, ele anula o --max_words_per_line. Requer --word_timestamps True.

--max_line_count: Controla a quantidade máxima de linhas por legenda (ou "bloco" de texto). Eu uso o valor 2, mas, nos meus testes, percebi que isso força todas as legendas a terem sempre duas linhas. Para mim, não é um problema, mas vale a pena você testar para ver como se adapta ao seu caso. Requer --word_timestamps True.

--max_words_per_line: Determina a quantidade máxima de palavras por linha na legenda. O padrão também é um valor alto, 1000 (também "hardcoded" na classe SubtitlesWriter). Embora eu não costume usá-lo, acredito que 5 palavras por linha pode resultar em uma leitura mais confortável. Atenção: Será anulado por --max_line_width caso você use ambos no mesmo comando. Requer --word_timestamps True.

--highlight_words: Este é o argumento responsável por criar o efeito de "karaokê" na sua transcrição. Ele faz com que cada palavra falada seja sublinhada no momento exato em que é pronunciada. Requer --word_timestamps True.

--word_timestamps: Este argumento é a chave para ativar os recursos de sincronização detalhada. Ao defini-lo como True, o modelo passará a gerar timestamps para cada palavra, em vez de apenas por blocos de frase. Isso pode, sim, aumentar consideravelmente o tempo de transcrição, mas é um requisito fundamental para que vários outros argumentos (como os de formatação de linha e destaque de palavras) funcionem. O valor padrão é False.

Exemplo Completo de Transcrição Detalhada

Veja um exemplo de como combinar vários desses argumentos para obter uma transcrição formatada e com destaque de palavras:

# A '\' (barra invertida no final da linha) é usada apenas para indicar que
# o comando continua na linha de baixo. Isso é uma boa prática para evitar
# que o comando fique muito longo na horizontal e melhora a legibilidade.
whisper meu_video.mp4 \
  --model large-v2 \
  --language pt \
  --output_format srt \
  --word_timestamps True \
  --highlight_words True \
  --max_line_width 45 \
  --max_line_count 2

--initial_prompt:

Este é um texto opcional que serve como um "empurrãozinho" para o modelo antes que ele comece a transcrever. Funciona como uma dica de estilo ou contexto. No entanto, é importante notar que ele só influencia a primeira "janela" do áudio (que por padrão tem 30 segundos).

Exemplo Prático:

Se o seu vídeo é sobre programação, especificamente Python, você pode passar um prompt como este:

--initial_prompt "vídeo de uma explicação sobre programação com destaque para bibliotecas do Python"

Isso pode ajudar o modelo a reconhecer e transcrever termos técnicos de programação e Python com mais precisão. Mas, como dito, não espere milagres para o vídeo inteiro; essa influência é apenas um toque inicial. Para as janelas seguintes, o modelo pode usar o texto transcrito anteriormente, se a opção --condition_on_previous_text estiver como True (que é o padrão).

Analogia para Entender Melhor:

Imagine que é como dizer para um cantor, antes de ele subir no palco:
"Tem 300 mil pessoas te esperando, detona lá!"
Ele vai subir já no clima certo, mas o resto da performance dependerá do show em si.
Da mesma forma, o modelo continua a transcrição com base no que "ouviu" e transcreveu depois do prompt inicial.

Cuidados com o --initial_prompt:

O --initial_prompt pode afetar significativamente a forma como o modelo do whisper opera. Em alguns casos, ele pode levar à geração de legendas excessivamente longas ou até mesmo fazer o modelo entrar em loops de repetição.

Recomendação: Antes de aplicar um prompt em um vídeo completo, faça testes rápidos em um trecho menor do seu vídeo para observar o resultado. Isso evita surpresas e economiza tempo de processamento.

Para cortar facilmente um pedaço do seu vídeo para testes, você pode usar o ffmpeg com o seguinte comando:

# Com ffmpeg
ffmpeg -i entrada.mp4 -c:v copy -c:a copy -ss 00:05:00.000 -to 00:10:00.000 saida.mp4

# Também dá pra usar --clip_timestamps start, end, start, end... (em segundos)
# O argumento --clip_timestamps é detalhado mais abaixo nesse texto
# No comando abaixo ele transcreve de 1min até 2min (nada mais)
whisper meu_video.mp4 --clip_timestamps 60,120

Entendendo o Comando ffmpeg:

-i entrada.mp4: Define o arquivo de vídeo de entrada (o seu vídeo original).
-c:v copy: Copia o codec de vídeo do arquivo original, sem recodificar. Isso torna o processo muito mais rápido!
-c:a copy: Copia o codec de áudio do arquivo original, também sem recodificar.
-ss 00:05:00.000: Especifica o ponto de início do corte (neste exemplo, 5 minutos e 0 segundos do vídeo original).
-to 00:10:00.000: Define o ponto final do corte (neste exemplo, 10 minutos e 0 segundos do vídeo original).

Este comando irá gerar um novo arquivo de vídeo (saida.mp4) contendo apenas o segmento entre 00:05:00 e 00:10:00 do vídeo original. Essa técnica é extremamente útil, especialmente para vídeos mais longos (como os meus de 30+ minutos), pois permite testar configurações específicas em um pedaço pequeno sem ter que processar o vídeo inteiro.

--condition_on_previous_text:

Este argumento crucial define se o texto que já foi transcrito será usado como contexto para ajudar a transcrever a próxima "janela" do áudio.

True (padrão): É a configuração ideal para a maioria dos casos. Ela ajuda a manter a fluidez e a consistência do texto, garantindo uma boa coesão entre os blocos da transcrição.
False: Desativa o uso do contexto anterior. Isso pode ser útil para evitar "loops de erro", onde o modelo fica repetindo frases ou palavras indefinidamente.

Exemplo de Uso:
Se a transcrição começar a errar e ficar repetindo, por exemplo, "Olá, pessoal, hoje vamos falar sobre..." em loop, desativar este argumento (--condition_on_previous_text=False) pode quebrar esse ciclo vicioso.

Recomendações Gerais para Contexto

Para otimizar suas transcrições, considere as seguintes dicas:

Para vídeos bem gravados, com áudio limpo e sem erros ou repetições evidentes, mantenha o padrão: --condition_on_previous_text=True.
Se o modelo começar a repetir frases ou palavras de forma indesejada, experimente mudar para --condition_on_previous_text=False.
O --initial_prompt pode ajudar somente no início da transcrição. Não espere que ele resolva problemas de consistência para o vídeo inteiro, mas pode ser útil para guiar o modelo em termos específicos.

Parâmetros que não usei (ou quase não usei 🫣):

Esses parâmetros aí de baixo eu não testei quase nada (apenas alguns). Só li a documentação, pesquei uma ideia geral e traduzi pra você não precisar sofrer. Se quiser fuçar, fuce, mas vai por sua conta e risco. Pode ser que melhore algo, pode ser que não mude nada. Vai depender do áudio, da fase da lua e do humor do modelo 😅.

Se eu começar a usar alguma dessas opções nas minhas transcrições, prometo que volto aqui e atualizo esse trecho. Alguns deles eu cheguei a testar de forma supercifical (explico nos argumentos).

--length_penalty

Controla a penalização para sequências longas. Valor típico: entre 0.6 e 1.0. Se você notar que a transcrição tá muito curta ou longa, pode brincar com isso. Eu não toquei neste argumento.

--suppress_tokens

Permite suprimir tokens pelo ID. O valor -1 (padrão) já suprime símbolos esquisitos e só mantém pontuações comuns. Deixa assim, a menos que você saiba o que está fazendo.

Exemplo:

# Isso aqui vai cortar algumas coisas úteis (só exemplo).
# Seu texto não terá: 'Olá', 'pessoal', ',', 'este', 'é', 'meu', 'texto', '.'
# Obs: texto sem ponto e vírgula fica horrível
whisper /caminho/do/seu/arquivo.mp4 \
    --model turbo \
    --language pt \
    --suppress_tokens=38056,842,24811,11,4065,1136,9230,35503,13

Quer saber o ID de um token específico?

Seguinte, se você que descobrir algum token para suprimir ou para qualquer outra coisa, veja um exemplo:

>>> from whisper.tokenizer import get_tokenizer
# get_tokenizer -> multilingual, num_languages=99, language='pt', task='transcribe'
#                  True,         99                Qual idioma    Qual task
>>> tokenizer = get_tokenizer(True, num_languages=99, language='pt', task='transcribe')
# tokenizer.encode você passa o 'valor' e recebe os tokens List[int]
>>> tokenizer.encode('Olá pessoal, este é meu texto.')
[38056, 842, 24811, 11, 4065, 1136, 9230, 35503, 13]
# tokenizer.decode você passa os tokens List[int] e recebe o 'valor'
>>> tokenizer.decode([38056, 842, 24811, 11, 4065, 1136, 9230, 35503, 13])
'Olá pessoal, este é meu texto.'
>>>

--fp16

Usa precisão float16 para acelerar em GPU.

No Mac M1, por exemplo, eu sempre uso --fp16 False, assim ele não fica mostrando warning de que trocou pra float32. Essa troca acontece automaticamente se o seu hardware não suportar float16, então:

Se suportar: passa direto com float16.
Se não suportar: ele mostra um aviso e troca para float32 sozinho.

Exemplo do warning:

FP16 is not supported on CPU; using FP32 instead

--compression_ratio_threshold

Se a razão de compressão (gzip) do texto for muito alta, ele assume que houve erro (textos muito repetitivos). Valor padrão é 2.4. Útil pra detectar loop de repetição.

Como funciona a ideia:

O Whisper pega o texto, compacta com gzip e compara o tamanho original com o tamanho compactado para calcular a razão de compressão. Textos repetitivos geram compressões mais eficientes, ou seja, razão mais alta.

"Olá, olá, olá, olá, olá..." → compacta muito → alta razão
"O rato roeu a roupa do rei de Roma." → mais diversidade → menor razão

Se a razão ultrapassar o limite definido (padrão: 2.4), o Whisper descarta o trecho por considerá-lo problemático (repetitivo, bugado etc).

Se sua transcrição estiver falhando sem motivo claro, esse filtro pode ser o culpado. Teste com --compression_ratio_threshold 0 e veja se melhora.

--logprob_threshold

Se a média do logaritmo da probabilidade (logprob) dos tokens estiver abaixo disso, ele trata como erro. Padrão: -1.0. Você consegue ver avg_logprob (média do logaritmo da probabilidade) das frases transcritas pelo Whisper no arquivo .json final gerado. Este arquivo contém algo similar a isso:

{
  "id": 102,
  "seek": 27632,
  "start": 293.8,
  "end": 294.66,
  "text": " primeiro os imports",
  "tokens": [51240, 18314, 3003, 41596, 51283],
  "temperature": 0.0,
  "avg_logprob": -0.08265516709308235,
  "compression_ratio": 1.7523364485981308,
  "no_speech_prob": 1.1688144375965326e-11,
  "words": [
    {
      "word": " primeiro",
      "start": 293.8,
      "end": 294.06,
      "probability": 0.7435079216957092
    },
    {
      "word": " os",
      "start": 294.06,
      "end": 294.24,
      "probability": 0.9965941309928894
    },
    {
      "word": " imports",
      "start": 294.24,
      "end": 294.66,
      "probability": 0.990346372127533
    }
  ]
}

Aqui avg_logprob é -0.08265516709308235. Quanto mais próximo de 0, mais confiante está o modelo.

Suponha que o modelo está descartando coisas na transcrição. Você poderia testar --logprob_threshold=-2.0 ou até --logprob_threshold=-1000 (não descarta nada).

Isso pode gerar muito ruído aleatório na transcrição, mas pode fazer ele detectar o que você quer.

O contrário também é verdadeiro. Se usar --logprob_threshold=-0.1 (por exemplo), o modelo vai pegar praticamente só o que tem certeza absoluta que tá certo. Isso não é uma coisa boa ou ruim, depende do contexto e do seu objetivo. Na dúvida, manter o padrão costuma ser uma escolha segura.

Quanto mais rigoroso, mais lento, porque ele vai tentar gerar várias hipóteses até alcançar esse nível de confiança. No fim das contas, ele vai te entregar um texto de qualquer jeito, mas pode demorar bem mais e talvez nem seja tão diferente assim.

--no_speech_threshold

Se o modelo acredita que é silêncio (probabilidade alta de <|nospeech|>) e a decodificação falha (logprob_threshold), ele descarta o trecho como sendo silêncio. Isso ajuda a cortar "respiros vazios" da transcrição.

Essa funcionalidade me encanta, e tenho planos futuros pra ela. Quem sabe a gente não volta a falar disso mais pra frente?

--prepend_punctuations (com --word_timestamps True):

Este argumento controla quais caracteres de pontuação que aparecem antes de uma palavra devem ser "colados" à palavra seguinte, em vez de serem tratados como um token separado.

Padrão: \"\'“¿([{- (inclui aspas, parênteses, etc.) e requer --word_timestamps True.

Em teoria, se o modelo gerasse, por exemplo, os tokens (, arg, ument, os, ) separadamente (tipo: [7, 33544, 2206, 329, 8] que formariam (argumentos)), o ( e o arg seriam unidos para formar (arg.

Observação Importante: eu testei o whisper com os idiomas Portuguese e English (90% em Portuguese, que é meu caso de uso). Em nenhuma das legendas que gerei houve qualquer caso onde a pontuação viesse antes de alguma palavra. Na prática, eu realmente não usei este parâmetro.

--append_punctuations (com --word_timestamps True):

Este argumento controla quais caracteres de pontuação que aparecem depois de uma palavra devem ser "colados" à palavra anterior.

Padrão: \"\'.。,，!！?？:：”)]}、 (inclui aspas, pontos, vírgulas, interrogações, etc.) e requer --word_timestamps True.

Por exemplo, se os tokens gerados forem Ok e ? separadamente, e o ? estiver incluído nesta lista (o que já está por padrão), eles serão unidos para formar Ok?.

Dica Prática: Esses argumentos de pontuação só farão uma diferença perceptível se você precisar que o ponto ou outro símbolo tenha um timestamp exatamente separado da palavra, o que é um caso de uso bastante específico. Na maioria das situações, o padrão do whisper já é bastante robusto. Do contrário, e para simplificar, mantenha os valores padrão.

Outros úteis

--threads

Define o número de threads que o modelo vai usar na CPU. Exemplo: --threads 4. Se não passar nada, ele usa o padrão da Torch (geralmente via MKL ou OMP).

Nos meus testes (Mac M1), usei 1, 4, 10, 100, 1000. O resultado? Ele só criou mais threads e usou mais CPU, mas a velocidade de transcrição não mudou absolutamente nada.

Claro, meus testes foram superficiais. Pode ser que em outro sistema, com outra CPU (ou invocando Cthulhu no terminal), você veja alguma diferença. Eu? Só vi o cooler suando.

--clip_timestamps

Permite transcrever ou traduzir apenas trechos específicos do áudio ou vídeo. Você passa os intervalos como pares start,end (em segundos). Pode usar vários.

Exemplos:

--clip_timestamps 10,30 → transcreve de 10s até 30s
--clip_timestamps 60,120 → de 1min até 2min
--clip_timestamps 10,30,60,120 → dois trechos: 10s–30s e 1min–2min
⚠️ --clip_timestamps 270 → de 4min30s até o final
⚠️ --clip_timestamps 60,120,0 → transcreve de 1min–2min e depois recomeça do zero até o fim

Atenção:

Esse último exemplo (60,120,0) parece um caso não previsto.

O 0 vem depois de 120, mas não forma um par start,end.

Nos testes, isso gerou um comportamento curioso: o modelo transcreveu normalmente de 1min até 2min, e depois do início até o final.

Mesmo assim, o VLC interpretou direitinho. Ele realinhou os blocos e ignorou os duplicados, mostrando só o que fazia sentido cronológico (aparentemente cortando o primeiro minuto).

--hallucination_silence_threshold

Funciona junto com --word_timestamps True.

Ele tenta detectar trechos de silêncio longos que o modelo pode ter "alucinado" (inventado texto).

Se você passar --hallucination_silence_threshold 1.5, ele vai ignorar silêncios maiores que 1.5s que geraram texto suspeito. Não toquei nesse argumento.

Usando o Whisper via código

Para usar o whisper via código, é bem simples. Como informado no repositório deles, basta usar o seguinte para uso normal do whisper.

import whisper

model = whisper.load_model("turbo")
result = model.transcribe("audio.mp3")
print(result["text"])

Para um acesso de mais baixo nível:

import whisper

model = whisper.load_model("turbo")

# load audio and pad/trim it to fit 30 seconds
audio = whisper.load_audio("audio.mp3")
audio = whisper.pad_or_trim(audio)

# make log-Mel spectrogram and move to the same device as the model
mel = whisper.log_mel_spectrogram(audio, n_mels=model.dims.n_mels).to(model.device)

# detect the spoken language
_, probs = model.detect_language(mel)
print(f"Detected language: {max(probs, key=probs.get)}")

# decode the audio
options = whisper.DecodingOptions()
result = whisper.decode(model, mel, options)

# print the recognized text
print(result.text)

E como eu fiz meu código?

Eu fiz o código de uma forma que eu continuasse usando todos os parâmetros do whisper, porém, adicionando minha própria lógica.

Basicamente eu simulo que os argumentos estão sendo enviados para mim com sys.argv do Python. No Diagrama abaixo eu mostro o processo do "terminal" até chegar ao argparse, e do lado direito, como montei meu código também chamando o argparse.

Diagrama exibindo como usei o sys.argv para simular o terminal no meu código

Veja o código a seguir. Só para constar, tem um logger em outro módulo com o seguinte código.

import logging

from rich.logging import RichHandler

logging.basicConfig(
    level="CRITICAL",
    format="%(message)s",
    datefmt="[%H:%M]",
    handlers=[
        RichHandler(
            show_time=True,
            show_level=True,
            rich_tracebacks=True,
            omit_repeated_times=False,
            markup=False,
        )
    ],
)

logger = logging.getLogger("rich")

Agora sim, vamos ver o código. Deixei vários comentário explicando tudo.

import argparse
from pathlib import Path

import rich_argparse

from sussu.basic_logger import logger

# Example commands:
#
# sussu whisper ~/Desktop/videos/part_0004.mp4 --temperature 0 --beam_size 1 \
# --device cpu --fp16 False --output_format srt --model tiny --language pt \
# --output_dir ~/Desktop/videos/
#
# sussu one ~/Desktop/videos/part_0004.mp4 --temperature 0 --beam_size 1 \
# --device cpu --fp16 False --output_format srt --model tiny --language pt \
# --output_dir ~/Desktop/videos/
#
# sussu batch --input_dir ~/Desktop/videos/ --temperature 0 --beam_size 1
# --device cpu --fp16 False --output_format srt --model tiny --language pt
# -s video.mp4 part_0000.mp4 --skip_files part_0001.mp4
# --output_dir 'this wont do anything here'


# Essa função é basicamente um jeito de "enganar" o cli do `whisper`
# para que ele "entenda" que está sendo chamado com determinados argumentos.
def whisper_cli_runner(whisper_args: list[str]) -> None:
    import sys

    # `whisper` não tem stub, por isso o pyright vai gerar erro (ignorado)
    from whisper.transcribe import cli as whisper_cli  # pyright: ignore

    # Aqui está a malícia. Vamos fingir que o python está recebendo os argumento
    # via sys.argv. Com isso o argparse entra em ação da mesma forma que
    # entraria se estivesse sendo executado via linha de comando.
    sys.argv = ["whisper", *whisper_args]
    whisper_cli()


# Essa é a nossa função que vai processar os arquivos usando o whisper original
def batch_whisper(
    input_dir: Path, whisper_raw_args: list[str], skip_files: list[str] | None = None
) -> None:
    # Vamos preencher essa lista com os dados que precisamos
    whisper_args: list[str] = []

    # As extensões abaixo podem não conter todas as extensões suportadas pelo
    # ffmpeg, sinta-se à vontade para adicionar novas extensões
    # fmt: off
    allowed_extensions =  {
        ".mp3", ".wav", ".flac", ".aac", ".m4a", ".ogg", ".opus", ".mp4", ".mkv",
        ".webm", ".mov", ".avi", ".3gp", ".wmv",
    }
    # fmt: on

    # Às vezes tem alguns arquivos na mesma pasta que são válidos, mas não
    # queremos transcrever (eu só queria agilizar meus testes manuais)
    if not skip_files:
        skip_files = []

    # Passamos em todos os arquivos da pasta enviada pelo usuário
    for file in input_dir.iterdir():
        skip_loop = False
        ########## VAMOS PULAR ALGUNS ARQUIVOS PARA EVITAR ERROS ##########

        # Pulamos quando é um subdiretório
        if file.is_dir():
            logger.warning(f"Directory not allowed: {file.name}")
            continue

        # Pulamos se a extensão não for permitida
        if file.suffix not in allowed_extensions:
            logger.error(f"File extension not allowed: {file.name}")
            continue

        # Pulamos também quando o usuário pede para pular aquele arquivo via -s
        for skip_file in skip_files:
            if str(file).endswith(skip_file):
                logger.info(f"File skipped: {file.name}")
                skip_loop = True

        if skip_loop:
            skip_loop = False
            continue

        ############ DAQUI EM DIANTE VAI PARA O WHISPER ##########

        # O argumento posicional vai sozinho no primeiro índice
        # depois os argumentos desconhecidos
        whisper_args.extend([str(file), *whisper_raw_args])
        logger.debug(f"audio set as {file!s}")

        # Por fim, adicionamos o outdir para ser sempre a pasta onde está
        # o arquivo original. Isso gera um arquivo de mesmo nome com a extensão
        # `.srt`.
        logger.debug(f"--output_dir set to {file.parent}")
        whisper_args.extend(["--output_dir", str(file.parent)])

        # Desativa o modo verboso do `whisper` por padrão para que a gente possa
        # ver nossos logs. Se o user passar algo, usa o que ele passar.
        if "--verbose" not in whisper_args:
            whisper_args += ["--verbose", "False"]
            logger.debug("--verbose set to False by default")

        # Agora só chamar o whisper com os argumentos que montamos
        logger.debug(f"whisper commands are: {whisper_args}")
        logger.debug(f"Final command: whisper {' '.join(whisper_args)}")
        whisper_cli_runner(whisper_args)

        # Zeramos os argumentos para o próximo loop
        whisper_args = []


def build_argparse() -> argparse.ArgumentParser:
    # Nosso main parser e o subparser para os comandos
    parser = argparse.ArgumentParser(
        prog="sussu", formatter_class=rich_argparse.RawDescriptionRichHelpFormatter
    )
    subparsers = parser.add_subparsers(dest="command", required=True)

    ########## WHISPER PARSER ##########

    # Esse subparse só será usado como um wrapper do argparse do whisper.
    # No final das contas, ele só vai chamar `whisper.transcribe.cli()`
    whisper_parser = subparsers.add_parser(
        "whisper",
        help="Calls `whisper` directly",
        conflict_handler="resolve",
        aliases=["one"],
        formatter_class=rich_argparse.RawDescriptionRichHelpFormatter,
    )
    whisper_parser.set_defaults(command="whisper")

    # Esse argumento aqui é pra garantir que vamos chamar o help do whisper e
    # não do nosso parser
    whisper_parser.add_argument(
        "-h", "--help", help="Shows `whisper` help.", action="store_true"
    )

    ########## NOSSOS PARSERS ##########
    # Minha ideia aqui é criar um subparser `batch` que vai receber um diretório
    # com arquivos de vídeo. Vamos passar em todos os arquivos do diretório e
    # usar o whisper para transcrever cada um deles.

    batch_parser = subparsers.add_parser(
        "batch",
        help="Process files with `whisper` in batch mode",
        formatter_class=rich_argparse.RawDescriptionRichHelpFormatter,
    )

    # Só coloquei essa função aqui para ficar próxima do argumento e facilitar
    # minha explicação na hora de gravar.
    def parse_input_dir(path_str: str) -> Path:
        path = Path(path_str)

        if not path.is_dir():
            msg = f"{path_str!r} is not a directory"
            raise argparse.ArgumentTypeError(msg)

        return path.resolve()

    # Isso deverá ser uma pasta que contém arquivos de vídeo ou áudio
    batch_parser.add_argument(
        "--input_dir",
        help="Directory with files to work with",
        type=parse_input_dir,
        required=True,
    )

    # Para testar, eu estava pulando um monte de arquivos para ir mais rápido
    batch_parser.add_argument(
        "-s",
        "--skip_files",
        help="Name of file(s) to skip",
        action="extend",
        nargs="+",
        default=[],
    )

    # Essa foi a maneira mais simples e direta de remover output_dir dos
    # unknown_args. Se isso fosse para o whisper, geraria conflito
    batch_parser.add_argument("-o", "--output_dir", help=argparse.SUPPRESS)
    return parser


def run() -> None:
    ########## PARSE KNOWN ARGS ##########

    # Vamos receber argumentos que são conhecidos (os nossos), e desconhecidos.
    # Argumentos desconhecidos serão repassados para o whisper cli.
    parser = build_argparse()
    args, unknown_args = parser.parse_known_args()

    # Se o comando for whisper, passamos tudo direto para o whisper
    if args.command == "whisper":
        # Simula -h e --help
        if args.help:
            whisper_cli_runner(["--help"])
            return

        # Executa o whisper normal, só que por baixo de `sussu`
        # Ex.: `sussu whisper audio.mp3` chama o cli original do `whisper` com
        # o argumento `audio.mp3` (ou qualquer outro argumento)
        whisper_cli_runner(unknown_args)
        return

    # Se o comando for `batch`, fazemos nosso trabalho
    if args.command == "batch":
        batch_whisper(args.input_dir, unknown_args, args.skip_files)


if __name__ == "__main__":
    run()

É só isso! Obrigado por ler.

Notas Técnicas: Criando CLIs com Python e Argparse

Sun, 05 Oct 2025 00:00:00 GMT

Olá! Este post serve como um guia técnico detalhado e notas de apoio para o meu vídeo completo sobre a criação de CLIs com Python e Argparse, que você pode assistir aqui. Se você caiu aqui de paraquedas, comece pelo vídeo!

O código-fonte completo do projeto está disponível neste repositório do GitHub para você baixar, estudar e acompanhar.

Para gerar todo o conteúdo de apoio que você verá abaixo, usei algumas coisas que podem ser interessantes para os devs mais curiosos. O primeiro passo começa com a montagem do projeto e a gravação do vídeo. Essas partes funcionam exatamente como sempre funcionaram: crio o projeto antes, gravo o vídeo e uso o ffmpeg para gerar uma versão mais compactada do arquivo em MP4.

Feito isso, eu passo o vídeo por um projetinho chamado nlingua2 para gerar a transcrição do vídeo em .srt. Depois, uso o Gemini para analisar essa transcrição e gerar um resumo técnico detalhado, que você pode ler na íntegra abaixo. A partir desses textos, gero os detalhes dos vídeos no Youtube, como título, descrição, timestamps e tags.

Análise Detalhada da Transcrição (Gerado por IA)

A seguir, um resumo trecho por trecho do vídeo.

Trecho iniciando em 00:00:00

Objetivo Principal:

O objetivo principal deste trecho é introduzir um tutorial sobre como usar o argparse do Python para criar ferramentas de linha de comando. O apresentador propõe um desafio prático: construir a interface de linha de comando (CLI) para um projeto existente, permitindo a comunicação externa com o programa.

Tecnologias/Linguagens/Ferramentas:

Python: Linguagem de programação principal usada no projeto.
argparse: Módulo Python para criar interfaces de linha de comando.
rich: Biblioteca Python para formatação de texto e saída colorida no terminal.
rich-argparse: Extensão do rich para aprimorar a aparência do argparse.
tinyDB: Biblioteca para criar um banco de dados simples em formato JSON.
uv (UltraViolet): Gerenciador de ambientes virtuais Python.
git: Sistema de controle de versão usado para gerenciar o código-fonte do projeto.
pip: Instalador de pacotes Python.
pyenv: Ferramenta para gerenciar diferentes versões do Python (mencionada, mas não usada diretamente no trecho).

Passos Práticos/Comandos:

O apresentador mostra o projeto no editor de código e explica a estrutura do desafio.
Ele demonstra como clonar o repositório do projeto via git, incluindo a utilização de branches (main e start_arg_parse).
Alternativamente, ele mostra como baixar o projeto como um arquivo zip.
Ele ativa o ambiente virtual usando o comando uv sync.
Explica que o uv sync instala as dependências do projeto (rich, rich-argparse, tinyDB), cria uma build em modo editável e torna o comando task disponível.
Ele executa o comando task.

Dicas/Conceitos Teóricos Importantes:

O argparse é apresentado como uma maneira moderna e segura de criar CLIs em Python, fornecendo uma API para interagir com o programa.
O tutorial é estruturado como um desafio, com especificações para o CLI a ser construído, incluindo subcomandos, aliases, descrições, e argumentos.
O projeto utiliza o rich para melhorar a formatação da saída no terminal, incluindo syntax highlighting para o help da CLI.
O tinyDB é usado para armazenar dados em um arquivo JSON.
O uv é recomendado como uma alternativa mais simples para gerenciar ambientes virtuais em comparação com o venv tradicional ou o pyenv.
O comando task é o ponto de entrada para o projeto.
O projeto envolve "runners" que recebem argumentos do argparse, convertem-nos em dicionários, mapeiam-nos para as necessidades internas do projeto e, finalmente, salvam os dados usando o tinyDB.

É importante ressaltar que o trecho analisado foca principalmente na configuração do projeto e na introdução do desafio, sem entrar nos detalhes da implementação do argparse.

Trecho iniciando em 00:07:02

Objetivo Principal:

Configurar a estrutura básica de um programa de linha de comando em Python usando o módulo argparse, incluindo a definição do comando principal (task), a exibição de ajuda (-h ou --help), e a inclusão de uma descrição formatada.

Tecnologias/Linguagens/Ferramentas:

Python
Módulo argparse
Ambiente virtual (mencionado, mas não demonstrado diretamente neste trecho)
UVsync (ferramenta para gerenciar o ambiente virtual, mencionado, mas não usado diretamente)

Passos/Comandos:

Estrutura do projeto: Explica a estrutura de pastas do projeto, com ênfase na pasta src como raiz, contendo o pacote task, o módulo cli.py, e a função run dentro de cli.py.
Função run: Inicialmente, a função run limpa o terminal e chama a função build_parser.
Função build_parser: Cria o parser de argumentos usando argparse.ArgumentParser(). Retorna o objeto parser criado.
Chamada à função build_parser: A função run chama build_parser e armazena o resultado na variável parser.
Parsing dos argumentos: Dentro de run, utiliza parser.parse_args() para processar os argumentos da linha de comando e armazena o resultado na variável args.
Exibição dos argumentos: Imprime os argumentos processados com print(args).
Configuração do ArgumentParser:
- Define o nome do programa para task usando prog="task".
- Adiciona uma descrição usando o argumento description.
- Discute o uso de strings multilinha para a descrição.
- Apresenta a formatação da descrição e a diferença entre argparse.RawTextHelpFormatter, argparse.RawDescriptionHelpFormatter, e o formatador padrão (argparse.HelpFormatter).

Dicas/Conceitos Teóricos:

Uso do módulo argparse para criar interfaces de linha de comando em Python.
Importância de estruturar o código para facilitar testes (justificativa para criar a função build_parser).
Diferenças entre os formatadores de ajuda do argparse e como controlar a formatação da descrição e do epílogo.
O argumento prog do ArgumentParser permite controlar o nome do programa exibido na ajuda.
O argparse adiciona automaticamente o argumento -h/--help para exibir a ajuda.
O comportamento padrão do argparse é usar o nome do módulo como nome do programa se prog não for especificado.

Trecho iniciando em 00:14:02

Resumo detalhado do trecho (começando em 00:14:02):

Objetivo principal: Explicar como customizar a ajuda (help) e a formatação de texto em ferramentas de linha de comando criadas com a biblioteca argparse do Python, incluindo a utilização de subcomandos.

Tecnologias/Linguagens/Ferramentas:

Python
Biblioteca argparse
Módulo textwrap (função dedent)
Biblioteca rich-argparse

Passos/Comandos:

Customizando o Help:
- Demonstra o uso de raw_description_help_formatter para manter a descrição curta e sem quebras de linha.
- Apresenta o text_help_formatter para quebras de linha e indentação, mas aponta o problema da indentação fixa.
- Utiliza a função dedent do módulo textwrap para remover a indentação indesejada, mantendo as quebras de linha.
- Mostra como adicionar um epílogo longo com quebras de linha e remover a indentação com dedent.
Adicionando Syntax Highlighting:
- Introduz a biblioteca rich-argparse para adicionar cores e destaque de sintaxe à saída do help.
- Substitui as classes do argparse (e.g., HelpFormatter, RawTextHelpFormatter) pelas equivalentes do rich-argparse (e.g., RichHelpFormatter, RichRawTextHelpFormatter).
Criando Subcomandos:
- Explica o conceito de subcomandos (como em git add, git commit) e sua utilidade para organizar comandos e opções.
- Mostra como criar subcomandos usando add_subparsers() e como acessá-los através da chave command no objeto Namespace retornado pelo argparse.
- Menciona a diferença entre argumentos posicionais (sem flags) e argumentos com flags (e.g., -t, --tag), indicando sua preferência pelos últimos devido à flexibilidade da ordem.
- Explica que subcomandos permitem criar namespaces para opções, permitindo o reuso de nomes de opções (e.g., -t para create e search) com diferentes funcionalidades.

Dicas/Conceitos Teóricos:

A importância de manter o help conciso e fácil de entender.
O uso de textwrap.dedent() para formatar texto com quebras de linha sem indentação fixa.
A vantagem de usar rich-argparse para melhorar a legibilidade da saída do help com syntax highlighting.
A distinção entre argumentos posicionais e argumentos com flags.
O conceito de namespaces e como subcomandos os implementam na prática.
O uso da chave command no objeto Namespace para acessar o subcomando chamado.

Trecho iniciando em 00:21:03

Objetivo principal: Configurar um subparser chamado "create" dentro de um argparse em Python para um programa de linha de comando chamado "task". O apresentador detalha a criação do subparser, adiciona aliases, define a descrição (description) e o epílogo (epilogue) para exibir no help, e explica a diferença entre argumentos posicionais e opções.

Tecnologias/Linguagens:

Python
argparse (biblioteca Python para parsing de argumentos de linha de comando)

Passos/Comandos:

Definindo o destino do parser: O apresentador direciona o parser para a chave "command". Define a chave como required para que o programa gere um erro caso nenhum subcomando seja fornecido.
Criando o subparser "create": Utiliza subparsers.add_parser("create") para criar um subparser associado ao comando "create".
Adicionando aliases: Adiciona os aliases "new" e "add" ao subparser "create" utilizando o parâmetro aliases=["new", "add"].
Definindo description e epilogue: Adiciona description e epilogue ao subparser para melhorar a informação exibida no help.
Utilizando formatter_class: Utiliza formatter_class para formatar a saída do help.
Explicando argumentos posicionais: Mostra o help gerado e explica a diferença entre argumentos posicionais (sem traço) e opções (com um ou dois traços), usando o comando mv do Unix como exemplo.

Dicas/Conceitos:

O parâmetro required em um argparse força o usuário a fornecer um valor para o argumento.
Subparsers permitem estruturar comandos complexos em um programa de linha de comando.
Aliases permitem usar diferentes nomes para o mesmo comando.
Argumentos posicionais dependem da ordem em que são fornecidos, enquanto opções são identificadas por flags (traços).
A forma curta de uma opção usa um traço, enquanto a forma longa usa dois. A forma longa geralmente corresponde ao nome do argumento no objeto.

Trecho iniciando em 00:28:03

Resumo detalhado do trecho (00:28:03):

Objetivo principal: Implementar a validação de argumentos de linha de comando para o comando create, especificamente para o argumento task, usando a biblioteca argparse em Python.

Tecnologias/Linguagens/Ferramentas:

Python
Biblioteca argparse
pathlib (mencionada como alternativa para validação de caminhos)

Passos/Comandos:

add_argument(): Adiciona o argumento task ao subparser create usando add_argument.
Flags curtas e longas: Define as flags -t (curta) e --task (longa) para o argumento.
Tipo do argumento (type): Define o tipo do argumento como string (str), explicando o conceito de factory e como o argparse usa classes para converter e validar os tipos. Menciona que o uso de path da biblioteca pathlib seria uma opção para argumentos que representam caminhos de arquivos.
Validação customizada: Cria uma função validate_str que remove espaços em branco do início e fim da string recebida e levanta um ArgumentTypeError com a mensagem "empty value" se a string resultante for vazia. Define esta função como o tipo (type) do argumento task no add_argument(), demonstrando como usar funções customizadas para validação.
required=True: Define o argumento task como obrigatório.
help: Define o texto de ajuda curto para o argumento.
metavar: Demonstra o uso de metavar para customizar a exibição do nome do argumento na ajuda, mas decide manter o padrão ("task").
Testes: Executa testes com diferentes entradas para o argumento -t/--task, incluindo strings vazias e com espaços em branco, mostrando como a validação customizada funciona e como o argparse gera mensagens de erro apropriadas.
Print de depuração: Utiliza print para exibir os valores recebidos, demonstrando o funcionamento do argumento.

Dicas/Conceitos teóricos:

Flags: Explica o conceito de flags curtas e longas para argumentos.
Factory: Explica o padrão de projeto factory e como o argparse o utiliza para a conversão e validação de tipos.
Validação com argparse: Demonstra como usar funções customizadas com o parâmetro type em add_argument() para validar a entrada do usuário e evitar código de validação redundante na lógica principal do programa.
pathlib: Sugere o uso da biblioteca pathlib para lidar com caminhos de arquivos de forma mais robusta.
Separação de responsabilidades: Enfatiza a importância de delegar a validação de argumentos para o argparse (ou camadas equivalentes em outras arquiteturas) em vez de lidar com isso na lógica principal da aplicação.

Trecho iniciando em 00:35:04

Resumo detalhado do trecho (começando em 00:35:04):

Objetivo principal: Explicar o uso de actions no módulo argparse do Python para processamento de argumentos de linha de comando, focando em boolean_optional_action para criar flags booleanas com valores invertidos e em extend para lidar com listas de argumentos.

Tecnologias/Linguagens/Ferramentas:

Python
Módulo argparse

Passos/Comandos:

boolean_optional_action: O apresentador demonstra como usar boolean_optional_action para criar uma flag booleana (ex: --don). Sem valor, a flag é considerada True. Com o prefixo "no" (ex: --no-don), a flag é False. Se a flag não for usada, o valor padrão é None. O apresentador enfatiza a importância do parâmetro default=False para definir o valor como False caso a flag não seja usada, diferenciando-o de None.
action="extend" e nargs: O apresentador introduz o uso de action="extend" para adicionar múltiplos valores a uma lista através de uma mesma flag (ex: --full). Ele explica o uso de nargs para controlar a quantidade de argumentos que a flag aceita. O valor '*' em nargs='*' permite zero ou mais argumentos para a flag, e o action="extend" garante que cada argumento passado para a flag seja adicionado à lista, ao invés de sobrescrever os valores anteriores. Menciona também outras opções para nargs, como '+' (um ou mais) e a possibilidade de usar um número inteiro para fixar a quantidade de argumentos.

Dicas/Conceitos Teóricos:

boolean_optional_action: Permite criar flags booleanas com valores invertidos usando o prefixo "no". O valor padrão sem a flag é None, podendo ser alterado com default.
action="extend": Usado para criar listas de argumentos através de uma única flag, adicionando cada novo argumento à lista.
nargs: Controla a quantidade de argumentos que uma flag aceita (ex: * para zero ou mais, + para um ou mais, ou um número inteiro).
Importância do default: Usar default=False em boolean_optional_action é crucial para diferenciar entre a flag não usada (False) e a flag explicitamente definida como negativa (--no-don, também False), permitindo uma lógica mais precisa.
Consulta à documentação: O apresentador recomenda consultar a documentação do Python para entender melhor as opções de actions e nargs disponíveis no módulo argparse.

Trecho iniciando em 00:42:05

Resumo detalhado do trecho (começando em 00:42:05):

Objetivo Principal: Configurar o parsing de argumentos de linha de comando usando a biblioteca argparse em Python, focando em como lidar com múltiplos valores para um mesmo argumento, valores padrão, choices restritas e aliases de comandos.

Tecnologias/Linguagens/Ferramentas:

Python
Biblioteca argparse

Passos Práticos/Comandos:

Configurando o argumento --tag:
- action="extend": Permite adicionar múltiplos valores à lista tags.
- default=[]: Define uma lista vazia como valor padrão.
- nargs="*": Aceita zero ou mais argumentos.
- dest="tags": Salva os valores na chave tags do dicionário de argumentos.
- Exemplo de uso: --tag valor1 valor2 valor3
- Observação: Valores repetidos são adicionados múltiplas vezes. Sugestão de remover duplicatas convertendo para set e de volta para list.
Configurando o argumento --priority:
- choices=["low", "medium", "high"]: Restringe os valores possíveis.
- default="medium": Define "medium" como valor padrão.
- help="Define a prioridade": Define o texto de ajuda para o argumento.
- Exemplo de uso: -p low ou --priority high
Corrigindo o problema de aliases com set_defaults:
- set_defaults(comando="create"): Define o valor "create" para a chave "comando", independentemente do alias usado (ex: new, add ou create). Isso evita a necessidade de condicionais (ifs) posteriores para determinar o comando a ser executado.

Dicas/Conceitos Teóricos Importantes:

Uso de action="extend" para adicionar múltiplos valores a uma lista em argparse.
Utilização de choices para restringir valores de entrada.
Definir valores padrão com default para evitar verificações posteriores no código.
Uso de dest para controlar o nome da chave no dicionário de argumentos.
Importância e utilização de set_defaults para definir um valor padrão para uma chave, simplificando a lógica de tratamento de aliases de comandos.
Menciona a possibilidade de converter uma lista para um conjunto (set) e de volta para lista (list) para remover valores duplicados, mas alerta para a possível mudança na ordem dos elementos.

Trecho iniciando em 00:49:06

Objetivo Principal:

Implementar a validação de entrada do usuário para tags (impedindo tags vazias) e integrar o comando create com a classe DefaultRunner para processar os argumentos fornecidos via linha de comando.

Tecnologias/Linguagens/Ferramentas:

Python
Argparse (biblioteca Python para parsing de argumentos de linha de comando)
Namedtuple (estrutura de dados Python)
TypedDict (para tipagem de dicionários em Python)

Passos Práticos/Comandos:

Validação de Tags: Adiciona validação para impedir a inclusão de tags vazias, semelhante à validação já existente para a tarefa (task). Demonstra o erro gerado ao tentar inserir uma tag vazia e o sucesso ao inserir uma tag com valor.
Uso de Aspas: Explica a necessidade de usar aspas simples ou duplas para valores com espaços em comandos de linha de comando, para que sejam tratados como um único valor.
Integração com DefaultRunner:
- Comenta os comandos de exemplo anteriores no runner.
- Define o default_runner como uma instância da classe DefaultRunner.
- Importa a classe DefaultRunner do módulo tasks.runners.
- Remove a verificação condicional if args.command por ser redundante (um comando sempre é fornecido).
- Usa getattr para obter o método correspondente ao comando fornecido (args.command) da instância DefaultRunner.
- Executa o método obtido, passando os argumentos (args) convertidos em um dicionário.
- Imprime o dicionário de argumentos (arguments) para demonstração.
Conversão para Dicionário: Utiliza vars() para converter o objeto Namespace do argparse em um dicionário.
mapDictTrueTaskParams:
- Explica a função mapDictTrueTaskParams, que recebe um dicionário e retorna um TypedDict chamado TaskParamData.
- Detalhes do TaskParamData:
  - task: obrigatório.
  - done: booleano, não obrigatório.
  - tags: tupla de strings, não obrigatório.
  - priority: tipo Priority (literal 'low', 'medium' ou 'high'), não obrigatório.
- A função filtra o dicionário de entrada, mantendo apenas as chaves presentes em task.fields (obtidas de uma Namedtuple).
- Usa um dictionary comprehension para criar o novo dicionário filtrado.
- Realiza um cast para garantir a tipagem correta.

Dicas/Conceitos Teóricos:

Uso de aspas em argumentos de linha de comando com espaços.
Utilização de getattr para acessar atributos dinamicamente.
Conversão de Namespace do argparse para dicionário usando vars().
Uso de Namedtuple e TypedDict para estruturar e tipar dados.
Filtragem de dicionários com dictionary comprehension.
Importância da validação de entradas do usuário para evitar problemas no software.

Trecho iniciando em 00:56:07

Resumo detalhado do trecho (começando em 00:56:07):

Objetivo Principal:

Demonstrar e explicar a criação de uma task (tarefa) utilizando um padrão de projeto Repository e persistindo os dados em um banco de dados TinyDB, mostrando a integração entre diferentes módulos do projeto e o fluxo de execução.

Tecnologias, Linguagens de Programação ou Ferramentas Mencionadas:

Python: Linguagem principal utilizada no projeto.
TinyDB: Banco de dados NoSQL orientado a documentos, utilizado para persistir as tasks.
JSON: Formato de dados utilizado para armazenar as tasks no TinyDB.
Rich: Biblioteca Python para formatação de texto e criação de interfaces de linha de comando, utilizada para exibir tabelas e mensagens formatadas.
Padrão de Projeto Repository: Padrão de projeto que abstrai a lógica de acesso a dados, permitindo a troca de diferentes tipos de bancos de dados sem afetar a aplicação.
(Mencionado) Patterns of Enterprise Application Architecture, de Martin Fowler: Livro de referência sobre padrões de projeto.

Passos Práticos/Comandos Executados:

repository.create(): Chama o método create do repositório para criar uma nova task. O método recebe os dados da task.
Verificação de Existência da Task: Internamente, no método create, verifica se já existe uma task com a mesma descrição. Se existir, retorna um erro e None.
Conversão de Tags: Converte as tags da task em uma tupla.
Inserção no TinyDB: Insere a nova task no banco de dados TinyDB e recupera o ID gerado automaticamente.
Retorno dos Dados: Retorna um objeto Task com os dados da task criada, incluindo o ID gerado pelo TinyDB.
log_task_table.find_all(): Chama o método find_all do módulo log_task_table, que utiliza o repositório para buscar todas as tasks no TinyDB e exibi-las em uma tabela formatada com Rich.
Exibição de Mensagem de Sucesso: Exibe uma mensagem de sucesso utilizando a biblioteca Rich.
Demonstração de erro ao tentar criar task duplicada: Mostra o erro gerado ao tentar criar uma task com a mesma descrição de uma já existente.
Criação de uma nova task com dados diferentes: Demonstra a criação de uma segunda task com uma descrição diferente e tags diferentes.

Dicas ou Conceitos Teóricos Importantes:

Padrão Repository: O apresentador explica o conceito do padrão Repository e sua importância para abstrair a lógica de acesso a dados, permitindo flexibilidade na escolha do banco de dados.
TinyDB - Geração Automática de ID: O TinyDB gera automaticamente o ID para as tasks, simplificando o processo de criação.
Uso de Tipagem em Python: Menciona o uso de tipagem (type hinting) no código para melhorar a legibilidade e facilitar a manutenção.
Módulos para Logs e Tabelas: O apresentador demonstra a separação de responsabilidades em diferentes módulos, como log_task_table, para organizar o código e facilitar a reutilização.
Tratamento de Erros: Mostra a verificação de existência da task antes da criação e o tratamento do erro caso a task já exista.

Trecho iniciando em 01:03:08

Objetivo Principal: Adicionar o subcomando all e search (ou find) a um parser de linha de comando para gerenciamento de tarefas (tasks).

Tecnologias/Linguagens/Ferramentas: Python (implicito pelo uso de termos como "parser", "add_parser") e possivelmente uma biblioteca de parsing de argumentos de linha de comando (como argparse). Um chatbot (ChatGPT) foi usado para gerar a descrição do subcomando search.

Passos Práticos/Comandos:

Subcomando all:
- Cria um parser para o subcomando all usando add_parser("all").
- Define a descrição (description) como "show all tasks".
- Define o texto de ajuda (help) com a mesma descrição.
Subcomando search:
- Copia o código do subcomando create como base.
- Renomeia variáveis e ajusta o código para o subcomando search.
- Adiciona o alias find usando aliases=["find"].
- Gera a descrição (epílogo) usando o ChatGPT.
- Define os argumentos para o subcomando search:
  - task: não requerido (required=False), valor padrão known.
  - destination: mantém o comportamento anterior (sem modificações explícitas no trecho).
  - Mantém outros argumentos presentes no subcomando create, ajustando descrições e valores padrão (default).
  - Adiciona argumento limit (não detalhado no trecho, mas mencionado como diferencial em relação ao create).

Dicas/Conceitos Teóricos:

Uso de known como valor padrão para argumentos não fornecidos pelo usuário, permitindo tratar esses casos na lógica de busca.
Diferenciação entre help (texto curto e sem quebras de linha) e description/epílogo (textos mais detalhados, permitindo quebras de linha).
Uso de metavar para descrever o valor do argumento na ajuda exibida ao usuário.
Uso de expressões regulares permitidas na busca de tarefas (mencionado na descrição do argumento task do subcomando search).
Limitação da quantidade de elementos exibidos na tela através do parâmetro limit no subcomando search.

Trecho iniciando em 01:10:09

Resumo detalhado do trecho (começando em 01:10:09):

Objetivo principal: Descrever a implementação de argumentos de linha de comando para as funcionalidades de busca (search), listagem (all) e deleção (delete) de tarefas (tasks) em uma aplicação.

Tecnologias/Linguagens/Ferramentas: Python (argparse).

Passos/Comandos:

Busca (search):
- Argumentos opcionais: down, tags, priority, limit.
- down: Se não fornecido, o valor padrão é None.
- tags: Se não fornecido, o valor padrão é None.
- priority: Se não fornecido, o valor padrão é None.
- limit (com flag -L ou --limit): Limita o número de tarefas retornadas pela busca. O valor padrão é 10. Há validação para garantir que o valor seja um inteiro positivo. Um erro é lançado se o valor for inválido.
- Se nenhum argumento for fornecido para a busca, o comportamento é equivalente à listagem de todas as tarefas (all).
Deleção (delete):
- Argumentos: id (obrigatório, com flag -i ou --task-id), force (opcional).
- id: ID da tarefa a ser deletada. Tipo inteiro.
- force (com flag --force): Força a deleção sem pedir confirmação. Se não fornecido, o valor padrão é false. A ação store_true é usada, o que significa que se a flag --force estiver presente, o valor será true, caso contrário, será false.
- Se o id não for fornecido, um erro é exibido.
- Se force não for fornecido, o usuário é solicitado a confirmar a deleção com "yes" ou "no".

Dicas/Conceitos:

Uso de None como valor padrão para argumentos opcionais quando a ausência de um valor precisa ser diferenciada de um valor vazio.
Validação de entrada do usuário para garantir que os valores fornecidos sejam do tipo correto e estejam dentro dos limites esperados (exemplo: limit deve ser um inteiro positivo).
Uso de argparse para lidar com argumentos de linha de comando em Python.
Uso de store_true para criar uma flag booleana em argparse.
Implementação de um mecanismo de confirmação antes de executar ações destrutivas, como a deleção de dados.

Trecho iniciando em 01:17:09

Resumo detalhado do trecho (começando em 01:17:09):

Objetivo Principal: Demonstrar o funcionamento do comando delete, one (find one) e search de uma ferramenta de linha de comando, provavelmente para gerenciamento de tarefas, e explicar a lógica por trás da busca com múltiplos critérios.

Tecnologias/Linguagens/Ferramentas:

Python: Linguagem usada para implementar a ferramenta.
TinyDB: Banco de dados NoSQL usado para armazenar as tarefas.
Expressões regulares: Usadas para realizar buscas mais complexas.
Terminal/Linha de Comando: Interface utilizada para interagir com a ferramenta.
Git: Mencionado indiretamente através de referências a branches e ao arquivo README.

Passos/Comandos:

Teste do comando delete:
- Executa o comando getttr (provavelmente para obter as tags existentes).
- Executa o comando delete 1 (para deletar a tarefa com ID 1), confirmando a operação.
- Executa o comando delete 2 -f (ou delete 2 --force) para deletar a tarefa com ID 2 sem confirmação.
- Executa o comando delete 1 novamente (para demonstrar a mensagem de erro quando a tarefa não existe).
- Executa task all para mostrar que não há mais tarefas.
Criação de Tarefas de Teste:
- Executa um comando longo (não mostrado completamente) para criar várias tarefas de teste.
- Executa task all para mostrar as tarefas criadas.
Implementação e Teste do comando one:
- Copia código do comando delete para criar o comando one.
- Adapta o código para buscar uma única tarefa pelo ID.
- Executa comandos como task one -i 2, task one -i 3, etc., para testar a busca por ID.
- Testa com um ID inexistente (100) para demonstrar a mensagem de erro.
Explicação e Teste do comando search:
- Explica a lógica de construção de consultas com o TinyDB, utilizando operadores lógicos (AND, OR, NOT) e expressões regulares.
- Menciona o uso de um método NOP (No Operation) para lidar com consultas vazias.
- Mostra como combinar critérios de busca (task, done, tags, priority).
- Executa o comando search sem parâmetros para mostrar as 10 primeiras tarefas.
- Executa o comando search -t com uma expressão regular para demonstrar a busca por texto na descrição da tarefa.

Dicas/Conceitos Teóricos:

Uso de expressões regulares para buscas flexíveis.
Construção de consultas complexas com o TinyDB, combinando múltiplos critérios com operadores lógicos.
Uso da flag -f ou --force para suprimir a confirmação em comandos de deleção.
Demonstração de mensagens de erro apropriadas para diferentes situações (tarefa não encontrada, etc.).
Importância de testes com diferentes cenários (sucesso, erro, etc.).

Trecho iniciando em 01:24:10

Resumo detalhado do trecho (começando em 01:24:10):

Objetivo Principal: Demonstrar a integração da biblioteca argparse em um programa Python já funcional para criar uma interface de linha de comando, permitindo filtrar tarefas com diferentes critérios. Após a demonstração, o apresentador discute brevemente sobre o empacotamento do projeto usando pi project.tomo e v sync ou v pip install -e ..

Tecnologias/Linguagens/Ferramentas:

Python
argparse (biblioteca Python para parsing de argumentos de linha de comando)
pi project.tomo (ferramenta para gerenciamento de projetos Python)
v sync e v pip install -e . (comandos para build e instalação de pacotes Python no modo editável, provavelmente relacionados a um ambiente virtual)

Passos Práticos/Comandos:

O apresentador demonstra diversos comandos de linha de comando usando o programa modificado com argparse. Os exemplos incluem:

Busca por texto na descrição da tarefa (ex: python): Inicialmente, apresenta problemas por não incluir o argumento search. Posteriormente, corrige o comando.
Filtrar tarefas concluídas: --done e --no-done (ou -d).
Filtrar por prioridade: -p high, -p medium, -p low.
Filtrar por tags: --tag trabalho, --tag slides, --tag python.
Combinar filtros: -t python --no-done -p high --tag "python" (usando aspas para evitar problemas com o argumento python).
Limitar o número de resultados: limit 1.

Dicas/Conceitos Teóricos:

Uso de aspas em argumentos que contêm espaços.
Menciona a possibilidade de customização da formatação da saída com classes e formatter.
Menciona o conceito de "parents" no argparse para evitar repetição de argumentos em subparsers.
Recomenda a leitura da documentação oficial do argparse e do tutorial da própria linguagem Python para aprofundamento.
Discute brevemente a criação de um pacote distribuível a partir do projeto, utilizando pi project.tomo, v-sync e v pip install.

Finalizando o Processo

Depois de receber a análise técnica detalhada (que você viu acima), eu passo esse conteúdo para o Gemini novamente, com um prompt pedindo para ele extrair as informações mais importantes para o SEO do meu vídeo no Youtube. O resultado é exatamente este que mostro abaixo, sem edições:

Resultado Final (Conteúdo para o YouTube)

1. Capítulos para o YouTube:

00:00:00 Introdução e Configuração do Projeto
00:07:02 Criando a Estrutura Básica do CLI com Argparse
00:14:02 Customizando o Help e Adicionando Subcomandos (subparsers)
00:21:03 Criando o subparser "create" com Argparse
00:28:03 Validação de Argumentos com Argparse
00:35:04 Usando Actions e nargs no Argparse (BooleanOptionalAction)
00:42:05 Múltiplos Valores (listas) e Choices no Argparse (action extend)
00:49:06 Validação de Tags (lista de strings) e Integração com o app
00:56:07 Criando uma Task e Persistindo com TinyDB
01:03:08 Adicionando os Subcomandos (subparsers) all e search
01:10:09 Implementando Argumentos para Busca, Listagem e Deleção
01:17:09 Testando os Comandos delete, one e search
01:24:10 Demonstração Final e Empacotamento do Projeto

2. Descrição para o YouTube (SEO Otimizado):

Domine a arte de criar interfaces de linha de comando (CLIs) profissionais e robustas em Python usando o poderoso módulo argparse! Neste tutorial completo, vamos construir uma CLI do zero para um projeto real, desde a configuração inicial até a implementação de recursos avançados como subcomandos, validação de entrada, e persistência de dados com TinyDB. Aprenda as melhores práticas e dicas para tornar suas ferramentas de linha de comando mais intuitivas, eficientes e fáceis de usar.

Após assistir a este vídeo, você será capaz de:

Criar CLIs interativas em Python com argparse.
Implementar subcomandos para organizar a estrutura do seu CLI.
Validar entradas do usuário para garantir a robustez do seu programa.
Persistir dados em um banco de dados TinyDB.
Utilizar bibliotecas como rich e rich-argparse para aprimorar a aparência do seu CLI.
Entender e aplicar conceitos como actions, nargs, choices e metavar.
Empacotar seu projeto Python para distribuição.

Principais tópicos abordados:

Introdução ao argparse e configuração do projeto.
Criação da estrutura básica da CLI.
Customização da ajuda (help) e adição de subcomandos.
Validação de argumentos de entrada.
Uso de actions para opções booleanas e listas.
Lidando com múltiplos valores e choices.
Integração com TinyDB para persistência de dados.
Implementação dos comandos create, search, all e delete.
Testes e demonstração final.
Empacotamento do projeto com uv e pyproject.toml.

Quer aprender a criar ferramentas de linha de comando incríveis em Python? Então este vídeo é para você! Assista agora e leve suas habilidades de desenvolvimento Python para o próximo nível.

Keywords: Python, argparse, CLI, interface de linha de comando, tutorial, TinyDB, rich, rich-argparse, validação de dados, subcomandos, Python CLI, criar CLI, desenvolvimento Python, ferramentas de linha de comando, empacotamento Python, pyproject.toml, uv sync, uv pip install, programação, tutorial argparse, argparse python, criar programa linha de comando, linha de comando python.

Notas técnicas sobre o vídeo Whisper OpenAI CLI do Youtube

Fri, 03 Oct 2025 00:00:00 GMT

Fala aí! 👋 Este post mostra como usei a legenda .srt do vídeo abaixo para gerar resumos, descrições otimizadas para SEO, hashtags, capítulos e versões em outros idiomas, tudo com o apoio de ferramentas de IA.

Guia Completo do OpenAI Whisper - Link

Se você caiu aqui de paraquedas, recomendo começar por esse vídeo. Também falo sobre ele em mais detalhes no post principal:

CLI educacional com OpenAI Whisper - Link

⚙️ Ferramentas e fluxo com IA (bastidores)

Para montar os conteúdos derivados do vídeo (resumos, descrições, títulos, etc.), sigo um processo simples e replicável:

Gravação: Câmera Sony A6100 + lente Yongnuo 50mm f/1.8 Microfone Shure MV7 Gravação no OBS Studio
Edição leve: Uso o ffmpeg pra compactar o vídeo final Removo silêncios automaticamente com o auto-editor
Transcrição com IA: Rodo o whisper da OpenAI para transcrever o vídeo
Correções com LLMs: A transcrição original tem erros técnicos (nomes de libs, ferramentas, etc). Divido a legenda em chunks (~1000 caracteres) e envio para a API do Gemini corrigir.

Esse chunking é necessário porque algumas legendas passam dos 300 mil caracteres, e IAs como Gemini ou GPT têm limites de contexto.

🧠 Output do Gemini a partir da legenda SRT

A partir daqui, eu não escrevi absolutamente nada. Tudo gerado por IA com base na legenda .srt corrigida.

Trecho iniciando em 00:00:00

Este trecho introdutório de um tutorial tem como objetivo principal apresentar o Whisper, um modelo de reconhecimento de fala de código aberto da OpenAI, focando em seu uso como ferramenta de linha de comando. O apresentador explica que o vídeo será dividido em duas partes: a primeira (presente neste trecho) aborda o uso do Whisper via linha de comando, enquanto a segunda (futura) mostrará sua integração em código (ex: Django).

As tecnologias e ferramentas mencionadas são:

Whisper (OpenAI): Modelo de reconhecimento de fala e transcrição de áudio, utilizado como ferramenta principal do tutorial. É descrito como gratuito e open source.
FFmpeg: Ferramenta mencionada como sendo utilizada pelo Whisper para processamento de áudio e vídeo.
ChatGPT: Usado pelo apresentador para confirmar se a OpenAI utiliza internamente o Whisper (a resposta foi afirmativa). O ChatGPT é mencionado como um produto que usa o Whisper para transcrição e compreensão de áudio.
Speech-to-Text da OpenAI: API mencionada como utilizadora do Whisper.
Python: Linguagem de programação implícita, uma vez que o apresentador menciona um "script Python" usado para cortar silêncios do áudio e a integração do Whisper em código será mostrada em um vídeo futuro.
Django: Framework Python mencionado como um exemplo de onde o Whisper poderia ser integrado.
Gemini: API de inteligência artificial utilizada pelo apresentador para gerar resumos, traduções e otimização SEO a partir da transcrição do seu próprio vídeo.
argparse (Python): Mencionado como exemplo de aplicação do processamento de transcrições, com um vídeo anterior do apresentador, sobre o tema, servindo como exemplo.

Passos práticos e comandos:

Embora o vídeo ainda não mostre comandos específicos do Whisper, o apresentador menciona o uso de um repositório chamado "sussu" ("sussu" (rro)) para executar comandos do Whisper. Ele também indica a existência de um repositório oficial do Whisper. O apresentador descreve como um script Python foi utilizado para pré-processar um arquivo de vídeo (one-auto.mp4), cortando partes de silêncio.

Conceitos teóricos importantes:

O apresentador destaca o potencial de usar a transcrição gerada pelo Whisper para outras tarefas, como gerar resumos, traduções e otimização de SEO usando outras APIs de IA (como o Gemini). Ele também brevemente discute os pontos fortes e fracos do Whisper, baseados em sua experiência de seis meses de uso. O apresentador menciona que o Whisper aceita arquivos de vídeo diretamente, devido ao uso do FFmpeg.

Trecho iniciando em 00:07:00

Este trecho do vídeo tutorial tem como objetivo principal explicar como usar o modelo de transcrição de áudio Whisper, incluindo sua instalação, configuração e uso básico. São apresentadas diversas funcionalidades do Whisper, além de alternativas para tarefas relacionadas.

Tecnologias, linguagens de programação e ferramentas mencionadas:

Whisper: Modelo de transcrição e tradução de áudio.
FFmpeg: Ferramenta usada pelo Whisper para manipulação de áudio e vídeo. Sua instalação é um passo prévio essencial.
NLLB ("No Languages Left Behind"): Sistema de tradução para múltiplos idiomas, apresentado como alternativa ao Whisper para traduções além do inglês.
Gemini: Mencionado como uma alternativa mais robusta (e paga) para tradução.
Python 3.11: Versão específica do Python necessária para compatibilidade com o Whisper.
uv (provavelmente um gerenciador de pacotes): Utilizado para gerenciar a instalação e configuração do projeto Whisper.
git: Usado para clonar o repositório do projeto (sussu).
sussu (repositório do apresentador): Simplifica a instalação e configuração do Whisper.
Auto-editor: Ferramenta (não baseada em IA) para cortar silêncios em vídeos, comparada com a capacidade de detecção de atividade de voz (VAD) do Whisper.

Passos práticos e comandos:

Instalação do FFmpeg (comandos específicos para Debian, Arch Linux, MacOS e Windows são fornecidos, mas não detalhados na transcrição).
Clonagem do repositório sussu usando git clone.
Uso de uv sync para instalar dependências, incluindo Python 3.11 e o próprio Whisper.
Uso de uv run whisper ou execução direta do comando whisper (após ativação do ambiente virtual) para executar o programa.
Execução do comando whisper [caminho do arquivo] para transcrever um arquivo de áudio ou vídeo (exemplo: whisper one-auto.mp4).

Dicas e conceitos teóricos importantes:

O Whisper não processa áudio diretamente, mas sim um espectrograma log-mel, representando o áudio como uma imagem.
O Whisper processa o áudio em trechos de 30 segundos.
O Whisper realiza transcrição multilíngue, mas tradução somente para inglês, a menos que se utilize ferramentas complementares como NLLB ou Gemini.
O Whisper possui a funcionalidade de detecção de atividade de voz (VAD), útil para tarefas como corte de silêncios em vídeos, superando a precisão de métodos baseados apenas em ondas sonoras.
O Whisper utiliza o FFmpeg internamente.
O uv instala e configura automaticamente o ambiente Python necessário, incluindo a instalação e compilação do Whisper e do repositório sussu.

A transcrição apresenta diversos argumentos e opções do comando whisper, mas não detalha todas as suas funcionalidades. A maior parte dos comandos e detalhes de configuração são deixados para consulta na documentação do Whisper e no repositório sussu.

Trecho iniciando em 00:14:01

Este trecho do vídeo (00:14:01-00:15:31) demonstra o funcionamento do modelo de transcrição de áudio Whisper da OpenAI. O objetivo principal é mostrar o processo de transcrição de um arquivo de áudio utilizando o Whisper, explicando o que acontece "por baixo dos panos" e as opções disponíveis.

Tecnologias/Ferramentas/Linguagens:

Whisper (OpenAI): Modelo de reconhecimento de fala e transcrição.
Python: Linguagem de programação implícita, pois o apresentador menciona a biblioteca site-packages e a função transcribe.
argparse: Biblioteca Python usada na interface de linha de comando (CLI) do Whisper.
Espectrograma log-mel: Técnica de processamento de sinal de áudio usada pelo Whisper.
JSON: Formato de saída utilizado pelo Whisper para apresentar os dados da transcrição.
OBS Studio: Software de captura de tela e streaming mencionado para o processamento de áudio.
Auto-editor: Editor de texto mencionado para formatar o arquivo JSON de saída.

Passos/Comandos:

O apresentador demonstra, principalmente, a execução de um comando de linha de comando que utiliza o modelo turbo do Whisper para transcrever um arquivo de áudio ("oneauto.json"). Ele explica que este comando aciona a função transcribe interna do Whisper, a qual processa o áudio em janelas de 30 segundos, utilizando os 30 segundos anteriores para contexto. O comando gera arquivos de saída em diferentes formatos (SRT, TSV, TXT, VTT, JSON). O apresentador mostra a inspeção do arquivo JSON gerado, destacando a estrutura com segmentos, IDs, timestamps, texto e tokens. Ele também menciona a possibilidade de utilizar a API da OpenAI como alternativa para computadores sem recursos suficientes.

Dicas/Conceitos Teóricos:

O Whisper não "escuta" o áudio diretamente, mas sim processa um espectrograma log-mel.
O modelo utiliza janelas de 30 segundos do áudio, com sobreposição, para a transcrição, fornecendo contexto.
A opção de usar FP16 ou FP32 para processamento é mencionada, dependendo da capacidade da CPU.
A qualidade do áudio impacta no resultado da transcrição.
O modelo turbo do Whisper é rápido, mas requer 6 GB de VRAM.
A API da OpenAI oferece uma alternativa para usuários sem hardware adequado para rodar o Whisper localmente.
A saída JSON contém informações detalhadas sobre os segmentos da transcrição, incluindo timestamps, texto e tokens.

Em resumo, a seção do vídeo demonstra e explica a utilização do modelo Whisper para transcrição de áudio, detalhando o processo, a interface de linha de comando, os formatos de saída e as implicações em termos de recursos computacionais.

Trecho iniciando em 00:21:01

O objetivo principal deste trecho do vídeo é explicar como escolher e utilizar diferentes modelos do Whisper (um modelo de transcrição de áudio para IA) baseado nos recursos do computador, principalmente a VRAM.

São mencionadas as seguintes tecnologias/ferramentas:

Whisper: Modelo de transcrição de áudio da OpenAI.
GPU (Placa de vídeo): Com foco na VRAM (memória da placa de vídeo) necessária para rodar diferentes modelos do Whisper.
Mac M1 Max: Um computador que utiliza memória compartilhada entre CPU e GPU.
Python: Linguagem de programação utilizada para executar o Whisper. Menciona-se também o uso do arquivo pyproject.toml para configuração do Python.
PyTorch: Framework de aprendizado de máquina, mencionado em relação à compatibilidade com placas Nvidia e CUDA.
CUDA: Tecnologia da Nvidia para computação paralela em GPUs.
Gemini: Uma ferramenta (provavelmente uma IA) usada para corrigir e melhorar as legendas geradas pelo Whisper, com foco na correção de termos técnicos.
Modelos do Whisper: tiny, base, small, medium, large, large-v2 e turbo, cada um com diferentes requisitos de VRAM e precisão.

Passos práticos e comandos:

O apresentador demonstra como selecionar diferentes modelos do Whisper usando o argumento model (ex: model tiny). Ele também mostra como configurar o device para usar CPU ou CUDA, e o output_dir para definir a pasta de saída das transcrições, usando os argumentos device e --output_dir respectivamente. Ele executa o código do Whisper e mostra como o uso da memória varia entre diferentes modelos. Ele explica que passa a saída do Whisper para o Gemini para correção de erros, fornecendo um exemplo de prompt usado para essa tarefa.

Conceitos teóricos importantes:

VRAM: Memória dedicada da placa de vídeo, crucial para o desempenho do Whisper. A quantidade de VRAM disponível afeta a escolha do modelo que pode ser utilizado.
Memória compartilhada (no Mac M1 Max): O sistema operacional compartilha a memória RAM entre CPU e GPU, permitindo que modelos maiores sejam usados, embora com possível lentidão.
Modelos diferentes do Whisper: Existem vários modelos, cada um com um equilíbrio diferente entre velocidade, precisão e consumo de recursos. Modelos menores (como tiny) são mais rápidos e usam menos recursos, mas são menos precisos, enquanto modelos maiores (como large-v2 e turbo) são mais precisos, mas demandam mais recursos.
Correção de legendas com Gemini: O apresentador utiliza outra IA (Gemini) para aprimorar a saída do Whisper, focando na correção de termos técnicos.
Importância de dar engajamento: O apresentador enfatiza a importância de comentários e curtidas em seus vídeos para motivar a continuidade da produção de conteúdo.

Trecho iniciando em 00:28:05

Este trecho do tutorial visa explicar como refinar o uso do Whisper para transcrição de áudio, focando principalmente nas opções de configuração para otimizar a precisão e velocidade do processo.

Tecnologias, linguagens e ferramentas: O tutorial utiliza o modelo Whisper para transcrição de áudio, especificamente via linha de comando. A linguagem utilizada é o inglês, com alguns comandos em português (PT-BR). Menciona-se também APIs de tradução como Gemini e GPT, embora não sejam utilizadas diretamente no exemplo. O sistema operacional do apresentador é um Mac.

Passos práticos e comandos: O apresentador demonstra a construção de um comando para o Whisper, explicando cada parâmetro:

-o ou --output_dir: Define o diretório de saída para os arquivos de transcrição (no exemplo, "transcriptions").
--device CPU: Especifica o uso da CPU para processamento.
--FP16: Controla o uso de precisão de ponto flutuante (FP16, mais rápido, mas com suporte dependente da máquina; FP32 usado como alternativa).
--language PT: Define o idioma como Português Brasileiro.
-f (opcional): Permite escolher o formato de saída da transcrição (padrão "all").
--task: Especifica a tarefa, podendo ser "transcribe" (transcrição no idioma original) ou "translate" (tradução para inglês).
--temperature: Controla a criatividade do modelo (0 para rigor, 1 para maior criatividade; o apresentador prefere 0).
--beam_size: Define o número de hipóteses mantidas em paralelo durante o processo.
--patience: Define a paciência do modelo em explorar novas hipóteses após achar uma aceitável. Multiplica o efeito do --beam_size quando --temperature é 0.
Modo greedy: Uma opção para acelerar o processo, utilizando apenas a melhor hipótese encontrada.

O apresentador executa o comando com as opções configuradas, embora não mostre o resultado da execução completa.

Dicas e conceitos teóricos:

FP16 vs. FP32: O tutorial explica a diferença entre esses tipos de precisão de ponto flutuante, mostrando que FP16 é mais rápido, mas nem sempre compatível com todos os sistemas.
--language: Mostra como especificar o idioma corretamente, evitando avisos do sistema. Inclui a opção de usar a forma curta (ex: PT) ou longa (ex: português).
--temperature: Explica o conceito de temperatura como um controle da criatividade do modelo, relacionando-o com a qualidade do áudio e as opções --beam_size e --patience.
--beam_size e --patience: Detalham a interação entre esses parâmetros e a temperatura, mostrando como influenciam a velocidade e a precisão da transcrição. A relação entre --beam_size e --patience é explicada, com --patience basicamente multiplicando --beam_size quando --temperature é 0.
Modo greedy: Apresenta uma forma mais rápida, mas possivelmente menos precisa, de gerar a transcrição.

O tutorial demonstra como encontrar a lista de idiomas suportados pelo Whisper, acessando o código fonte em lib/python/whisper/tokenizer/languages.

Trecho iniciando em 00:35:09

Este trecho do tutorial visa explicar como otimizar a geração de legendas usando o modelo Whisper, focando nos parâmetros que controlam a precisão e o formato da saída. As tecnologias mencionadas são o modelo de transcrição de áudio Whisper e suas opções de linha de comando.

O apresentador detalha o funcionamento dos parâmetros --temperature, --beam_size, --patience, e --best_of. Ele explica que --temperature controla a criatividade (valores acima de 0 usam sampling), enquanto --beam_size controla o número de hipóteses (Beam Search) consideradas. --patience multiplica o número de hipóteses quando --beam_size é maior que 1 e --temperature é 0. --best_of seleciona entre várias amostras, funcionando principalmente quando --temperature > 0. O apresentador enfatiza que, na sua experiência, os valores padrão geralmente são suficientes, exceto em casos de áudios de baixa qualidade ou com muita gíria. A configuração --temperature 0 e --beam_size 1 é chamada de "greedy" e tende a ser mais rápida, mas com maior chance de erros.

Os passos práticos envolvem a demonstração de como modificar os parâmetros na linha de comando para gerar legendas. O apresentador mostra como alterar --temperature e --beam_size para ajustar a velocidade e precisão.

Conceitos teóricos importantes abordados são: o funcionamento do sampling e Beam Search, a relação entre --temperature, --beam_size e --patience, e a influência da qualidade do áudio na escolha dos parâmetros. O apresentador também explica que o modelo pode entrar em loop em certos casos, necessitando ajustes nos parâmetros.

Finalmente, o apresentador explica e demonstra o uso dos parâmetros --max_line_width, --max_line_count, --words_timestamps, e --highlight_words para controlar o formato e o estilo da legenda gerada. Ele mostra como limitar o número de caracteres por linha, o número de linhas e como gerar timestamps por palavra, destacando que --max_line_width e --max_words_per_line são mutuamente exclusivos. A opção --words_timestamps é necessária para o --max_line_width funcionar corretamente e permitir o destaque de palavras (--highlight_words). Ele observa que o parâmetro --max_line_count não impõe um limite máximo, mas sim define o número fixo de linhas por legenda.

Trecho iniciando em 00:42:09

Este trecho do tutorial tem como objetivo principal demonstrar e explicar opções avançadas do software Whisper para transcrição de áudio e vídeo, focando em --highlight_words, --initial_prompt, e clip_timestamps, além de como utilizar o FFmpeg para pré-processamento de vídeos.

Tecnologias, linguagens e ferramentas:

Whisper: O software de transcrição de áudio e vídeo da OpenAI, é o foco central do tutorial. São exploradas várias opções de linha de comando do Whisper: --highlight_words, --initial_prompt, --clip_timestamps, words_timestamps.
FFmpeg: Uma ferramenta de linha de comando usada para manipulação de mídia, especificamente para cortar trechos de vídeo antes da transcrição com o Whisper. O comando exemplificado é ffmpeg -i "entrada" -c:v copy -c:a copy -ss 00:05:00 -to 00:10:00 "saida".

Passos práticos e comandos:

O apresentador demonstra o uso do parâmetro --highlight_words True no Whisper para sublinhar as palavras faladas no vídeo correspondente ao tempo de fala, criando um efeito semelhante a karaokê. Ele demonstra a geração de legendas com o Whisper, incluindo a opção --highlight_words. Explica o parâmetro --initial_prompt, que fornece um contexto inicial (primeiros 30 segundos) para o Whisper, mas alerta sobre seu uso limitado e potencial para causar problemas se usado incorretamente. Ele sugere duas formas de testar o --initial_prompt: cortar o vídeo com o FFmpeg antes de usar o Whisper ou usar o parâmetro --clip_timestamps do Whisper para especificar um intervalo de tempo. Também explica como o Whisper, por padrão, utiliza os 30 segundos anteriores de áudio como contexto para a transcrição, a partir do segundo 30.

Dicas e conceitos teóricos importantes:

--highlight_words: Permite sublinhar as palavras no vídeo conforme são faladas.
--initial_prompt: Permite fornecer um contexto inicial ao Whisper para melhorar a precisão nos primeiros 30 segundos do vídeo. O apresentador adverte que esta opção pode levar a resultados inesperados se usada incorretamente, como legendas muito longas ou loops de repetição. Ele a compara a dar uma dica para um cantor antes de um show.
words_timestamps: É um parâmetro necessário para algumas das opções mais avançadas do Whisper e pode tornar o processo de transcrição mais lento.
Uso do FFmpeg para pré-processamento: Cortar um vídeo com o FFmpeg antes de usar o Whisper pode ser útil para testar o parâmetro --initial_prompt ou para transcrever apenas uma parte do vídeo.
Contexto no Whisper: O Whisper usa, por padrão, 30 segundos de contexto do áudio anterior para melhorar a precisão da transcrição.

Em resumo, a seção do vídeo foca em aprimorar a precisão e adicionar recursos à transcrição com o Whisper, utilizando opções avançadas e demonstrando como lidar com possíveis problemas, incluindo o uso de ferramentas externas como o FFmpeg para auxiliar no processo.

Trecho iniciando em 00:49:09

Este trecho do tutorial visa demonstrar e explicar parâmetros avançados do modelo de transcrição Whisper, focando em como manipular a saída de texto gerado. As tecnologias envolvidas são o modelo de transcrição de áudio Whisper da OpenAI e a linguagem de programação Python.

Objetivo principal: Mostrar como controlar a geração de legendas com parâmetros específicos do Whisper, incluindo a supressão de tokens e o tratamento de penalidades de comprimento. Além disso, o objetivo é demonstrar como entender e manipular os tokens gerados pelo modelo usando a biblioteca Python do Whisper.

Tecnologias, linguagens e ferramentas: O modelo de transcrição Whisper, a linguagem Python e sua biblioteca associada. Especificamente, são utilizadas funções como get_tokenizer, encode e decode dentro da biblioteca do Whisper. Também é demonstrado um uso básico da função print em Python.

Passos práticos e comandos:

Manipulação de parâmetros do Whisper: O apresentador explica e demonstra o efeito de configurar condition_on_previous_text como false para desabilitar o contexto anterior na transcrição. Ele também menciona length_penalty (embora não o teste), suppress_tokens (demonstrando como suprimir vírgulas, pontos e outras palavras específicas), e --max_line_count para controlar o comprimento das linhas de legenda. Ele executa comandos do Whisper na linha de comando, mostrando mudanças na saída de legendas.
Manipulação de tokens via Python: O apresentador demonstra como utilizar a biblioteca do Whisper em Python para:
- Importar o get_tokenizer: from whisper.tokenizer import get_tokenizer
- Obter um tokenizer: tokenizer = get_tokenizer(True)
- Codificar texto em tokens: token.encode("Olá mundo")
- Decodificar tokens em texto: tokenizer.decode([401, 842, 7968]) Ele usa isso para mostrar a correspondência (nem sempre exata) entre tokens numéricos e palavras, examinando a saída tanto do comando Whisper quanto do JSON gerado.

Dicas e conceitos teóricos importantes:

condition_on_previous_text: Controlando se o modelo usa o contexto anterior no áudio.
length_penalty: Penaliza sequências de texto longas (valor típico entre 0.6 e 1).
suppress_tokens: Permite suprimir tokens específicos na saída de texto, oferecendo mais controle sobre o resultado final.
Tokens: São representações numéricas de palavras ou partes de palavras utilizadas internamente pelo modelo. A decodificação de tokens é fundamental para entender a saída do modelo em detalhes.
FP16 (float16) vs. FP32 (float32): FP16 costuma ser mais rápido que FP32, mas o apresentador observa que a utilização de FP16 pode gerar warnings. O modelo automaticamente tenta usar FP16 se disponível, mas cai para FP32 se o dispositivo (CPU) não o suporta.

O apresentador enfatiza a importância de testar os diferentes parâmetros para entender seu impacto no resultado final da transcrição. Ele também nota a imprecisão do modelo "Tiny" e sugere o uso de modelos maiores para melhores resultados.

Trecho iniciando em 00:56:10

Este trecho do vídeo (00:56:10 em diante) foca em explicar e analisar parâmetros de configuração avançados do modelo de transcrição de voz Whisper, da OpenAI. O objetivo principal é demonstrar como ajustar esses parâmetros para resolver problemas como loops (repetições) na transcrição e lidar com diferentes comportamentos linguísticos em relação à pontuação.

As tecnologias/ferramentas mencionadas são o modelo de transcrição Whisper, o algoritmo de compressão Gzip e um arquivo JSON gerado pelo Whisper que contém informações de métricas da transcrição. Não são mencionadas linguagens de programação explicitamente, mas o apresentador analisa o código-fonte do Whisper (em alguma linguagem não especificada) para explicar os parâmetros.

Passos práticos/comandos: O apresentador não executa comandos específicos de forma direta. Ele descreve como interpretar os dados do arquivo JSON gerado pelo Whisper, focando em dois parâmetros principais: Compression Ratio Threshold e AVG log probe. Ele explica como valores anormais nesses parâmetros (ex: Compression Ratio acima de 2.4 ou AVG log probe abaixo de -1) podem indicar problemas na transcrição e como ajustar o Compression Ratio Threshold para 0 como um teste de resolução de problemas. Ele também discute o parâmetro prepend_punctuation, explicando seu funcionamento e impacto na transcrição de idiomas com pontuação no início das palavras. O apresentador menciona que consultou o paper da OpenAI sobre o Whisper para entender esses parâmetros.

Conceitos teóricos importantes: O apresentador explica o conceito de "razão de compressão" (Compression Ratio) no contexto da transcrição de voz pelo Whisper. Uma alta razão de compressão indica repetições no áudio, sugerindo um possível loop no modelo. Ele também define e explica a métrica AVG log probe (média do logaritmo de probabilidade), que representa a confiança do modelo na transcrição. Valores baixos indicam baixa confiança e possíveis erros. Adicionalmente, ele detalha o funcionamento do parâmetro prepend_punctuation, que controla o processamento de pontuação que pode aparecer antes das palavras em alguns idiomas. Por fim, ele menciona o conceito de "no speech threshold" que ajuda a detectar e eliminar silêncios e outros ruídos da transcrição, relacionando-o a um sistema de detecção de voz (VAD).

Trecho iniciando em 01:03:13

O objetivo principal desta parte do vídeo é explicar os argumentos de linha de comando do modelo de transcrição de áudio Whisper, focando principalmente nos argumentos relacionados à manipulação de pontuação e ao recorte de trechos de áudio para transcrição.

As tecnologias e ferramentas mencionadas são o modelo de transcrição Whisper e o FFmpeg (mencionado brevemente). A linguagem de programação não é especificamente mencionada, mas o apresentador se refere ao código-fonte do Whisper, particularmente a função merge_punctuations localizada dentro do módulo timing.

Passos práticos e comandos demonstrados: O apresentador explica como os argumentos de pontuação (prepend e append) funcionam no Whisper, mostrando como eles afetam a junção ou separação da pontuação com as palavras transcritas. Ele também demonstra o uso do argumento --clip_timestamps, mostrando como especificar intervalos de tempo para transcrever apenas trechos específicos de um vídeo. Ele detalha diferentes cenários de uso, incluindo a especificação de múltiplos intervalos e casos de uso inesperados, como o retorno ao início da transcrição após um intervalo definido. O apresentador também menciona o argumento threads para controlar o número de threads usadas durante a transcrição, e hallucination silence threshold, para lidar com silêncios longos que podem resultar em texto alucinado.

Conceitos teóricos importantes: O apresentador explica como a função merge_punctuations do Whisper funciona, analisando sua lógica interna para a manipulação da pontuação. Ele destaca que o comportamento da função em relação ao espaço em branco antes dos sinais de pontuação é peculiar. Ele também discute a utilidade dos argumentos --clip_timestamps para transcrever partes específicas de vídeos, incluindo a possibilidade de processar trechos em idiomas diferentes ou testar partes curtas de um vídeo. Por fim, o apresentador ressalta que os argumentos de pontuação só são relevantes se o carimbo de tempo das palavras for usado para analisar a colagem de pontuação, e que o argumento hallucination silence threshold ajuda a lidar com texto inventado pelo modelo em trechos de silêncio.

Trecho iniciando em 01:10:16

Resumo detalhado do trecho (começando em 01:10:16):

Objetivo principal: O objetivo principal desta parte do vídeo é encerrar o tutorial atual e adiar a demonstração da integração do modelo de transcrição Whisper ao código para um vídeo subsequente. O apresentador justifica a decisão pela duração esperada da tarefa.

Tecnologias, linguagens de programação ou ferramentas mencionadas: A tecnologia mencionada é o modelo de transcrição Whisper. Não há menção de linguagens de programação específicas ou outras ferramentas.

Passos práticos ou comandos executados: Nenhum passo prático ou comando é executado neste trecho. A ação principal é a decisão do apresentador de adiar a demonstração para um vídeo futuro.

Dicas ou conceitos teóricos importantes: Não há dicas ou conceitos teóricos explicados neste curto segmento. A única informação relevante é a intenção de usar o Whisper para transcrição em um tutorial futuro.

Resumo final gerado para o Youtube

1. Capítulos para o YouTube:

00:00:00 Introdução ao Whisper: Transcrição via Linha de Comando
00:07:00 Instalando e Configurando o Whisper
00:14:01 Transcrição de Áudio com o Whisper: Demonstração Prática
00:21:01 Escolhendo o Modelo do Whisper: Recursos de Computador
00:28:05 Refinando a Transcrição: Parâmetros de Configuração
00:35:09 Otimizando a Geração de Legendas: Parâmetros Avançados
00:42:09 Opções Avançadas: --highlight_words, --initial_prompt, FFmpeg
00:49:09 Manipulando a Saída de Texto: Tokens e Parâmetros em Python
00:56:10 Parâmetros Avançados: Resolvendo Loops e Pontuação
01:03:13 Argumentos de Linha de Comando: Pontuação e Recorte de Áudio
01:10:16 Encerramento e Prévia do Próximo Vídeo

2. Descrição para o YouTube (SEO Otimizado):

Domine a transcrição de áudio e vídeo com o Whisper da OpenAI! Neste tutorial completo, aprenda a usar o poderoso modelo de reconhecimento de fala da OpenAI, diretamente na linha de comando, para gerar legendas precisas e otimizadas. Após assistir, você será capaz de instalar, configurar e usar o Whisper para transcrever seus arquivos de áudio e vídeo, otimizando parâmetros para diferentes necessidades e resolvendo problemas comuns. Você também aprenderá a manipular a saída do Whisper usando Python, obtendo total controle sobre o processo.

Introdução ao Whisper e sua utilização via linha de comando.
Instalação e configuração detalhada do Whisper, incluindo o uso do repositório sussu.
Demonstração prática de transcrição de áudio e vídeo com diferentes modelos do Whisper.
Otimização de parâmetros para melhorar a precisão e velocidade da transcrição.
Manipulação de tokens e parâmetros avançados usando a biblioteca Python do Whisper.
Resolução de problemas comuns, como loops e erros de pontuação.
Uso do FFmpeg para pré-processamento de vídeos.
Explicação detalhada dos argumentos de linha de comando do Whisper.
Prévia da integração do Whisper com código (próximo vídeo).

Este tutorial abrange todos os aspectos do uso do Whisper, desde a instalação até a otimização de parâmetros avançados.

Se você busca aprender sobre transcrição de áudio, reconhecimento de fala, processamento de linguagem natural, legendas automáticas, OpenAI Whisper, linha de comando, Python, FFmpeg, ou como melhorar a precisão das suas legendas, este vídeo é para você! Palavras-chave relevantes incluem:

Whisper tutorial, transcrição de áudio, reconhecimento de fala, OpenAI Whisper, linha de comando, legendas automáticas, Python Whisper, FFmpeg, processamento de áudio, modelo de linguagem, transcrição de vídeo, otimização de legendas, parâmetros Whisper, resolução de problemas Whisper, tokens Whisper, beam search, greedy decoding, modelos de transcrição.

Tentei usar o whisper live via microfone

Thu, 02 Oct 2025 00:00:00 GMT

Criei esse arquivo pra ir anotando minhas tentativas de rodar o whisper em tempo real, puxando o áudio direto do microfone. Já vou deixar claro que isso não funcionou do jeito que eu esperava, e ainda tem coisa pra testar.

Na minha cabeça, talvez o certo fosse trabalhar direto com o modelo do whisper, sem usar o código oficial da OpenAI. Aquela janela fixa de 30 segundos pode ter atrapalhado real. Pode até ser que precise refinar o modelo pra rodar liso num esquema live.

Mas enfim... isso é só uma ideia. Não fui muito além do que tá descrito aqui porque quero ver primeiro se esse tipo de conteúdo realmente chama atenção do pessoal pra eu focar mais tempo pra gerar conteúdo (vídeos, posts, aulas, etc).

(🚫 FAILED) Captura do microfone via `ffmpeg`

Minha primeira tentativa foi capturar o áudio do computador usando o ffmpeg.

Pra deixar claro: tô usando o ChatGPT e o Gemini pra me ajudar nas partes que eu manjo menos, principalmente as coisas mais técnicas de áudio. Além disso, tô rodando tudo com esse setup aqui (não sei se faz diferença, mas vai que...):

MacBook Pro 2021
Chip Apple M1 Max
32 GB de RAM
SSD de 1 TB
macOS Sequoia 15.5

Listando os dispositivos de áudio

Obs: tô testando só no macOS por enquanto.

# macOS
ffmpeg -hide_banner -f avfoundation -list_devices true -i ""

# Linux
ffmpeg -hide_banner -f alsa -list_devices true -i ""
# ou (às vezes mais confiável)
arecord -l
# ou
arecord --list-devices

# Windows
ffmpeg -hide_banner -list_devices true -f dshow -i dummy

No meu caso, a saída foi mais ou menos como a que mostro logo abaixo. Só dei uma enxugada, tirando os dispositivos que não interessavam (tipo fone, celular, etc). Também cortei aquele trecho inicial que o ffmpeg cospe sempre.

➜  Desktop
ffmpeg -hide_banner -f avfoundation -list_devices true -i "" 2>&1

2025-06-18 09:15:21.567 ffmpeg[37312:1839628] WARNING:
Add NSCameraUseContinuityCameraDeviceType to your Info.plist to use AVCaptureDeviceTypeContinuityCamera.

2025-06-18 09:15:21.708 ffmpeg[37312:1839628] WARNING:
AVCaptureDeviceTypeExternal is deprecated for Continuity Cameras.

Please use AVCaptureDeviceTypeContinuityCamera and add NSCameraUseContinuityCameraDeviceType to your Info.plist.

[AVFoundation indev @ 0x153706960] AVFoundation video devices:
[AVFoundation indev @ 0x153706960] [0] Câmera FaceTime HD
[AVFoundation indev @ 0x153706960] [5] Capture screen 0
[AVFoundation indev @ 0x153706960] [6] Capture screen 1
[AVFoundation indev @ 0x153706960] AVFoundation audio devices:
[AVFoundation indev @ 0x153706960] [0] MOTIV Mix Virtual
[AVFoundation indev @ 0x153706960] [1] JBL TUNE125BT FOREBA
[AVFoundation indev @ 0x153706960] [2] Microfone (MacBook Pro)

[in#0 @ 0x600001f5c600] Error opening input: Input/output error

Error opening input file .
Error opening input files: Input/output error

A parte importante dessa saída é saber duas coisas: o [ID] e o nome do dispositivo.

Por exemplo, se eu quiser usar o Microfone (MacBook Pro), isso quer dizer que o ID do dispositivo de áudio que eu vou usar é o 2.

(🚫 FAILED) Testando a captura de áudio em um `.wav`

Antes de tudo, bora garantir que tá tudo funcionando bonitinho. A ideia aqui é só gravar um .wav com o áudio capturado direto do microfone. Ainda não é o comando final, é só pra testar mesmo.

# Lembra do meu [2] Microfone (MacBook Pro) -> ID 2
# No comando abaixo, o ":2" representa o dispositivo que eu tô usando
# Resultado: grava um arquivo out.wav com 10 segundos de áudio
ffmpeg -f avfoundation -i ":2" -t 10 -ac 1 -ar 16000 out.wav

Ou seja, pra capturar só o [2] Microfone (MacBook Pro), é só passar :2 no argumento -i.

Se tu quiser capturar vídeo e áudio ao mesmo tempo, o formato vira V:A, onde V é o ID do vídeo e A o do áudio.

Tipo assim:

# Captura da Câmera FaceTime HD (ID 0) + Microfone (MacBook Pro) (ID 2)
# Grava um out.mp4 com 10 segundos de vídeo e áudio dos dispositivos 0 e 2
ffmpeg -f avfoundation -framerate 30 -i "0:2" -t 10 out.mp4

(🚫 FAILED) O que rolou com o `ffmpeg`?

No meu caso, o ffmpeg não funcionou do jeito que eu queria. O áudio ficou todo picotado, com umas falhas bem esquisitas. Daí pra frente, passei praticamente o dia inteiro testando várias coisas: mudei o sample rate, tentei outros codecs, troquei de microfone, testei outras fontes (até tentei capturar o som direto do sistema). Nada deu certo.

Minha conclusão: o avfoundation no meu macOS não tá se comportando direito.

Testei comandos como esse aqui:

ffmpeg \
    -thread_queue_size 512 \
    -loglevel debug \
    -f avfoundation \
    -i ":2" \
    -c:a copy \
    -t 10 \
    out.wav \
    -y

Esse -c:a copy (pra manter o codec de áudio original) foi uma das últimas tentativas, depois de trocar um monte de outras coisas. E com isso o ffmpeg revelou que o áudio tava vindo com essas specs:

Stream #0:0, 1, 1/1000000: Audio: pcm_f32le, 48000 Hz, mono, flt, 1536 kb/s

Eu já tinha testado pcm_f32le com 48000 Hz antes, então... nenhuma surpresa.

Enfim, deixo isso aqui documentado porque, se acontecer contigo também, já te poupo umas horas de frustração. A única coisa que resolveu o problema de áudio tremido/picotado foi usar o sox.

(✅ SUCCESS) `sox` pra capturar o áudio

Na primeira tentativa com sox, já rolou de boa, zero esforço.

sox \
    -b 32 \
    -e float \
    -r 16000 \
    -c 1 \
    -d \
    --buffer $((16000*4*10)) \
    out.wav \
    trim 0 10 \
    fade t 1 -0 1

Esse comando foi gerado pelo Gemini ou ChatGPT (não lembro). Só pedi um exemplo que gravasse 10 segundos de áudio com fade-in e fade-out, só pra teste mesmo.

Depois fui testando outras paradas, mas o comando que pretendo usar com o whisper é esse aqui:

# 🚫 não executa ainda
sox -t \
    coreaudio "Microfone (MacBook Pro)" \
    -b 16 \
    -e signed-integer \
    -r 16000 -c 1 \
    -t raw \
    -

Repara que a saída tá indo pro stdout (por isso tem esse - no fim), não pra um arquivo. Ou seja, isso aqui é só a base pra integrar com outro processo, tipo jogar direto no whisper.

Eu não entendo muito do sox ainda (primeiro uso), mas usei o ffmpeg (lá em cima) pra listar os dispositivos. E aqui é diferente: em vez de usar o ID como no ffmpeg, tu passa o nome do dispositivo, tipo, meu caso: "Microfone (MacBook Pro)".

(🤔 SUCCESS?) `whisper` live, ou quase

Aqui é onde começo a achar que talvez eu precise refinar o modelo ou até usar ele "cru", sem passar pelo código oficial da OpenAI (whisper).

Fiz um código bem porquinho, só pra ver se ia funcionar. A ideia era: se desse certo, aí sim eu refinava tudo com calma.

Considera isso aqui como um MVP na versão 0.0.0alpha mesmo.

# pyright: basic
import asyncio

import numpy as np
import whisper
from scipy.io import wavfile

MODEL = whisper.load_model("turbo")


async def recorder(queue, counter, buffer, chunk_size, sr=16000, duration=5):
    print("🗣️ Recording started")

    proc = await asyncio.create_subprocess_exec(
        "sox",
        "-t",
        "coreaudio",
        "Microfone (MacBook Pro)",
        "-b",
        "16",
        "-e",
        "signed-integer",
        "-r",
        "16000",
        "-c",
        "1",
        "-t",
        "raw",
        "-",  # raw para facilitar o corte
        stdout=asyncio.subprocess.PIPE,
        stderr=asyncio.subprocess.DEVNULL,
    )

    while True:
        data = await proc.stdout.read(chunk_size)
        if not data:
            break
        buffer += data

        chunk_byte_size = sr * 2 * duration

        if len(buffer) >= chunk_byte_size:
            audio_chunk = buffer[:chunk_byte_size]
            buffer = buffer[chunk_byte_size:]

            audio_np = np.frombuffer(audio_chunk, np.int16).astype(np.float32) / 32768.0
            await queue.put(audio_np)

            wavfile.write(
                f"media/debug_{counter}.wav",
                16000,
                audio_np,
            )

            print(f"🗣️ Chunk {counter} ends \n")
            counter += 1


async def transcriber(queue):
    prefix = ""
    while True:
        print("💬 Whisper started")

        audio = await queue.get()
        audio = whisper.pad_or_trim(audio)

        mel = whisper.log_mel_spectrogram(audio, n_mels=MODEL.dims.n_mels).to(
            MODEL.device
        )

        options = whisper.DecodingOptions(
            language="en",
            temperature=0,
            beam_size=1,
            patience=0,
            without_timestamps=True,
            prompt=None,
            prefix=None,
        )
        result = whisper.decode(
            MODEL,
            mel,
            options,
        )

        prefix = result.text
        print("💬", result.text, "\n")
        queue.task_done()


async def main():
    from pathlib import Path
    from shutil import rmtree

    media = Path("media")
    rmtree(media)
    media.mkdir(exist_ok=True)

    queue = asyncio.Queue()
    counter = 0
    buffer = b""
    chunk_size = 4096

    await asyncio.gather(
        recorder(queue, counter, buffer, chunk_size, 16000, 30), transcriber(queue)
    )


if __name__ == "__main__":
    asyncio.run(main())

Nesse código eu uso asyncio justamente pra não travar tudo enquanto o whisper tá transcrevendo. A ideia é deixar o processo rodando em paralelo: enquanto uma parte grava, a outra já vai transcrevendo em tempo real.

Também uso o scipy.io.wavfile pra salvar os áudios em chunks, do mesmo jeitinho que o whisper recebe. Isso ajuda no debug: depois eu junto esses arquivos e escuto como ficou o áudio real que foi processado.

A função recorder é quem inicia o sox com o microfone que escolhi e roda um loop que fica monitorando a quantidade de bytes acumulados. Essa contagem é baseada no tamanho que cada trecho de áudio teria, considerando a duração que defini.

# Sample rate (16000) * Sample Width (2 bytes) * duração (ex: 5s)
chunk_byte_size = sr * 2 * duration

Quando o tamanho do buffer atinge esse chunk_byte_size, a gente corta exatamente até ali. Esses são os bytes crus do trecho de áudio que vai pra transcrição. Em seguida, o buffer é atualizado pra remover esse pedaço processado e guardar qualquer sobra, que vai ser usada no próximo ciclo.

Esse loop aqui embaixo é o coração da gravação. Ele fica rodando enquanto o sox tá mandando dados pela stdout.

while True:
    # captura o que vem do sox
    data = await proc.stdout.read(chunk_size)
    if not data:
        break
    # joga no buffer
    buffer += data

    # calcula quantos bytes correspondem à duration configurada
    chunk_byte_size = sr * 2 * duration

    # se o buffer já tiver o tamanho certo pra um trecho de áudio completo
    if len(buffer) >= chunk_byte_size:
        # pegamos só o pedaço que interessa
        audio_chunk = buffer[:chunk_byte_size]
        # e atualizamos o buffer, removendo o que já usamos
        buffer = buffer[chunk_byte_size:]

Aí, com esse audio_chunk em mãos, é só converter pra um formato que o whisper entenda e jogar isso na queue, que o transcriber vai processar depois:

audio_np = np.frombuffer(audio_chunk, np.int16).astype(np.float32) / 32768.0
await queue.put(audio_np)

Esse .frombuffer(...).astype(...) / 32768.0 basicamente transforma os bytes crus em um array de float32 com valores normalizados entre -1 e 1, que é o formato que o whisper espera.

Como eu queria ver exatamente o que o whisper também "tava enxergando", salvei cada trecho de áudio assim:

wavfile.write(
    f"media/debug_{counter}.wav",
    16000,
    audio_np,
)

Usei esse counter só pra gerar arquivos separados, tipo: debug_0.wav, debug_1.wav, debug_2.wav, e por aí vai.

Depois juntei tudo com o ffmpeg:

ffmpeg -f concat -safe 0 -i input.txt -c copy out.wav

E o arquivo input.txt fica assim:

file 'debug_0.wav'
file 'debug_1.wav'
file 'debug_2.wav'

Até esse ponto, tava tudo fluindo lindamente. Eu já tava achando que ia dar bom. Mas... o resultado final foi bem mais ou menos.

(🤔 SUCCESS?) os problemas!

É aqui que entra o whisper de verdade. Testei um monte de coisas pra tentar deixar tudo o mais rápido possível, e, claro, sem perder precisão na transcrição.

Dá uma olhada nos comentários que deixei no código. Logo mais abaixo eu explico outras coisas que descobri no caminho.

Essa é a função transcriber, que fica rodando enquanto tem coisa na fila (queue). Comentei bastante no código, mas aqui vai uma visão geral com uns complementos:

async def transcriber(queue):
    prefix = ""  # USEI ISSO DE DUAS FORMAS DIFERENTES, SEM SUCESSO
    while True:
        print("💬 Whisper started")

        # Pega o áudio cru da fila
        audio = await queue.get()

        # Isso aqui é um pé no saco: não importa o tamanho real do áudio,
        # o whisper sempre espera cerca de 30s.
        #
        # Se for menor, ele preenche o resto com zeros (silêncio).
        # Se for maior, ele corta o que passa dos 30s.
        #
        # IMPORTANTE: não tem como passar áudios de durações diferentes
        # usando o código da OpenAI, porque o modelo foi treinado assim.
        audio = whisper.pad_or_trim(audio)

        # O whisper não "ouve" o som, ele transforma em imagem.
        # É um gráfico do som chamado espectrograma (Mel logarítmico).
        # Já expliquei isso num vídeo, é bem de boa de entender.
        mel = whisper.log_mel_spectrogram(audio, n_mels=MODEL.dims.n_mels).to(
            MODEL.device
        )

        options = whisper.DecodingOptions(
            # Último teste: inglês (en)
            # Mas 90% dos testes foram em português (pt), com áudios limpos,
            # de vídeos do YouTube com gente falando claro, sem gíria nem ruído.
            language="en",

            # Tentei deixar mais rápido usando o modo "greedy"
            # Também expliquei isso no outro vídeo
            temperature=0,
            beam_size=1,
            patience=0,  # isso aqui nem faz nada, foi mais no desespero

            # Desativei os timestamps pra ver se o modelo ficava mais leve,
            # focando só na transcrição mesmo
            without_timestamps=True,

            # Aquele prefixo lá de cima... tentei usar nessas duas opções aqui
            # (prompt e prefix). O modelo entrou em loop e fiquei bolado.
            # Desisti de usar.
            prompt=None,
            prefix=None,
        )

        # E aqui é onde rola a transcrição de fato
        result = whisper.decode(MODEL, mel, options)

        prefix = result.text
        print("💬", result.text, "\n")
        queue.task_done()

Tentei detalhar bastante nos comentários do código acima, mas ainda tem umas coisas importantes que vale comentar.

Primeiro: não consegui usar nenhum modelo acima do medium. O motivo é simples, o tempo de transcrição ficava maior do que a janela de tempo que eu escolhi.

Tipo assim: com o modelo turbo e uma janela de 2 segundos, o whisper levava uns 10 segundos (ou mais!) pra cuspir a transcrição. Ou seja, não dava tempo. Não tinha como rodar em tempo real desse jeito. Pode ser limitação do meu hardware também? Pode. Mas o fato é que não rolou.

Os modelos que se saíram melhor nesse esquema foram o tiny e o base. Ambos ainda são imprecisos, mas se eu tivesse que escolher um, ficaria com o base. O tiny, cara... entra em loop com uma facilidade absurda, qualquer coisa repete, embanana, e vira um samba do sussurrador doido.

Sobre os tempos, testei com várias janelas diferentes:

⚠️ 1s, 2s, 3s, 4s: sem chance. O modelo não entende nada, e em poucos ciclos já começa a repetir as coisas.
⚠️ 5s a 9s: até vai, mas ainda rola loop e perda de qualidade em alguns momentos.
✅ 10s a 30s: aqui a coisa começou a funcionar de verdade. Foi a faixa que deu o melhor resultado.

Percebeu o paradoxo? Eu queria uma parada em tempo real, mas só começou a ficar usável a partir dos 10 segundos de áudio por vez. Foi aí que me bateu a real: talvez só role se eu refinar o modelo e usar um código customizado, sem depender da implementação padrão do whisper.

Todos esses testes foram feitos usando exatamente o código oficial da OpenAI. Nada modificado no core do modelo.

Conclusão geral

Desse jeito que mostrei até aqui, pra mim não rola usar o whisper com precisão em tempo real. Pelo menos foi essa a conclusão que cheguei depois de tudo isso.

Mas ó: foi uma experiência massa. Aprendi muita coisa que eu nem fazia ideia, principalmente sobre áudio, e me diverti bastante fuçando esse modelo.

Tô deixando tudo documentado aqui porque pode ser que te ajude a ir mais fundo no modelo, ou até mexer no código do whisper pra tentar um resultado melhor que o meu.

Outra opção que eu não testei, mas pode valer muito a pena, seria usar o whisper.cpp (versão C++) ou o faster-whisper, que é uma implementação otimizada em Python com base no CTranslate2.

Valeu demais se tu leu até aqui! Tomara que eu tenha te ajudado ou feito você perder menos tempo se fosse testar tudo isso que testei.

Obs: escrevi esse texto com markdown, se quiser baixar:

Baixar esse texto em markdown

Bye 👋!!!

Liskov Substitution Principle ou Princípio da Substituição de Liskov

Fri, 12 Sep 2025 00:00:00 GMT

Quem já trabalhou com herança na programação orientada a objetos, muito provavelmente também já ouviu falar sobre o Princípio da Substituição de Liskov, ou até já sofreu na prática quando ele foi quebrado no seu programa.

Introduzido por Barbara Liskov em 1987, o LSP é um dos cinco princípios do famoso SOLID e define uma regra simples, mas muito poderosa: um subtipo deve poder substituir seu tipo base sem que o comportamento esperado do sistema mude.

Parece simple e extremamente óbvio, mas não é. O que muita gente esquece é que não basta a tipagem funcionar, o comportamento (a sua lógica) também precisa ser compatível. É aqui que entram conceitos como pré-condições, pós-condições e invariantes: três pilares que ajudam a identificar se um subtipo realmente respeita o contrato definido pela superclasse.

Neste artigo, vamos entender a definição formal do LSP, traduzi-la para um contexto mais prático e analisar exemplos, desde os clássicos, até situações sutis que passam despercebidas por type checkers, mas que podem quebrar seu sistema no pior momento possível.

A Definição Formal de Barbara Liskov

Se você for como eu, precisará ler o que ela disse algumas vezes até entender o que ela quis dizer. Mas vamos para a definição forma em inglês e português.

"What is wanted here is something like the following substitution property: If for each object o1 of type S there is an object o2 of type T such that for all programs P defined in terms of T, the behavior of P is unchanged when o1 is substituted for o2, then S is a subtype of T."

Tradução literal:

"O que se quer aqui é algo como a seguinte propriedade de substituição: se, para cada objeto o1 do tipo S, existe um objeto o2 do tipo T, de forma que, para todos os programas P definidos em termos de T, o comportamento de P permanece inalterado quando o1 é substituído por o2, então S é um subtipo de T."

Entendeu? Ok, vamos decifrar isso juntos...

O que ela quis dizer?

Tomei a liberdade de traduzir o que ela disse de uma forma menos formal. E eu não fiz isso enquanto escrevia este texto, foram anos quebrando a cabeça até chegar em algo assim:

S é subtipo de T somente se qualquer programa escrito para funcionar com objetos do tipo T continuar se comportando exatamente da mesma forma quando receber um objeto do tipo S, sem "perceber" a troca.

Ou seja, não basta a tipagem bater com o Type Checker, o comportamento do subtipo também precisa ser compatível com o comportamento do supertipo.

Você pode ter um código perfeito para o type checker e mesmo assim quebrar o LSP se violar o contrato do tipo base.

Se isso acontecer, com certeza terá bugs no seu programa no futuro.

Como verificar se o LSP está sendo respeitado

O checklist clássico é baseado em três pontos-chave: pré-condições, pós-condições e invariantes. Antes de analisarmos cada um, vale lembrar que a compatibilidade começa na assinatura dos métodos, ou seja, parâmetros, retorno e exceções fazem parte do contrato que o subtipo precisa manter.

Compatibilidade de assinaturas

Parâmetros: No subtipo, devem ser iguais ou mais genéricos (contravariantes).
Retorno: No subtipo, devem ser iguais ou mais específicos (covariantes).
Exceções: O subtipo não deve lançar exceções que não sejam subtipos das lançadas pela superclasse.

Em Python, o Callable já é contravariante nos argumentos e covariante nos retornos. Para saber qual exceção é subtipo de outra, veja a hierarquia de exceptions.

Falamos sobre a variância no vídeo Genéricos ABC, Covariância, Contravariância e Invariância no Python - Aula 5.

Pré-condições (inputs / parâmetros)

Pré-condições estão relacionadas aos parâmetros de entrada (ou inputs).

Regra: O subtipo não pode ser mais restritivo que o tipo base.

Exemplos:

Se a abstração aceita um container iterável com qualquer tipo de elemento, o subtipo não pode exigir uma list[str].
Se a abstração espera uma URL (HTTP ou HTTPS), o subtipo não pode aceitar apenas caminhos de arquivo local.
Se a abstração aceita qualquer int, o subtipo não pode restringir para apenas inteiros positivos.
Se a abstração aceita str vazia ou não vazia, o subtipo não pode proibir string vazia.
Se a abstração aceita None como valor opcional, o subtipo não pode rejeitar None.
Se a abstração aceita qualquer objeto no in (__contains__), o subtipo não pode lançar TypeError para tipos diferentes.
Se a abstração aceita float com ou sem casas decimais, o subtipo não pode aceitar apenas números inteiros representados como float (ex.: 1.0, 2.0).
Se a abstração aceita qualquer formato de data válido, o subtipo não pode aceitar apenas datetime.date e rejeitar datetime.datetime.
Se a abstração aceita parâmetros por posição ou por nome, o subtipo não pode exigir que todos sejam nomeados (ou todos posicionais).
Se a abstração aceita qualquer arquivo aberto (modo leitura ou escrita), o subtipo não pode exigir exclusivamente arquivos abertos em modo leitura.

Exemplo concreto para pré-condições (inputs / parâmetros)

Vejamos um exemplo onde o subtipo viola uma pré-condição do LSP:

class Tags:
    def __init__(self, tags: set[str]) -> None:
        self._tags = tags

    # Contrato amplo: aceita qualquer objeto
    def __contains__(self, item: object) -> bool:
        return item in self._tags  # Para tipo "errado", retorna False


class StrictTags(Tags):
    # 🚫 Pré-condição mais restritiva: agora só aceita str
    def __contains__(self, item: object) -> bool:
        if not isinstance(item, str):
            raise TypeError("item must be str")
        return item in self._tags


# Cliente escrito para o tipo base:
def has_tag(t: Tags, q: object) -> bool:
    return q in t


t1 = Tags({"python", "types"})
t2 = StrictTags({"python", "types"})

print(has_tag(t1, 123))  # False (ok no contrato do base)
print(has_tag(t2, 123))  # 💥 TypeError, subtipo ficou mais restritivo

No código acima, Tags aceita que qualquer object seja utilizado com __contains__ (in e not in). Mas StrictTags impõe que apenas str pode ser utilizado. O type checker não reclama, mas o comportamento mudou, quebrando a pré-condição da classe base.

Pode parecer sutil, pode funcionar agora, mas em algum momento isso vai quebrar.

Pós-condições (retorno / output)

Regra: O subtipo não pode entregar menos do que o tipo base, ou seja, não pode enfraquecer as condições do tipo base.

Exemplos:

Se o pai promete retornar sempre um número positivo, o filho não pode retornar negativos.
Se o pai promete retornar um objeto não nulo (None nunca é retorno válido), o filho não pode retornar None.
Se o pai promete retornar uma coleção ordenada, o filho não pode retornar elementos fora de ordem.
Se o pai promete retornar todos os registros encontrados, o filho não pode retornar apenas parte deles sem avisar.
Se o pai promete retornar um tipo específico (list), o filho não pode retornar outro tipo compatível mas diferente (tuple, set), mesmo que tenha os mesmos dados.
Se o pai promete retornar um valor convertido para minúsculas, o filho não pode retornar o valor com caixa mista.
Se o pai promete retornar um JSON válido, o filho não pode retornar uma string que não seja JSON parseável.
Se o pai promete retornar um arquivo legível até o fim, o filho não pode retornar um arquivo truncado.
Se o pai promete retornar um caminho absoluto, o filho não pode retornar um caminho relativo.
Se o pai promete retornar um hash único, o filho não pode retornar um valor fixo ou repetido.

Observação: Você pode prometer mais que o pai, mas nunca menos.

Exemplo concreto para pós-condições (outputs / retornos)

Um exemplo de algo que só retorna positivos no Python é o __len__. Este método é chamado ao usar len() para saber quantos itens existem no container. Ou o container está vazio (0 itens) ou tem elementos. Ele nunca terá uma quantidade negativa de itens.

# Tipagem perfeita, mas pós-condição violada
class SizedProtocol:
    def __init__(self, data: list[int]) -> None:
        self._data = data

    def __len__(self) -> int:
        return len(self._data)  # Sempre >= 0 (contrato implícito do Python)

class BadSized(SizedProtocol):
    def __len__(self) -> int:
        return len(self._data) - 1  # 🚫 Pode gerar valor negativo (sutil)


bad_sized = BadSized([])  # Vazio, então seria zero, mas será -1
size = len(bad_sized)     # ValueError: __len__() should return >= 0

Esse exemplo já quebrou antes de nascer, bastou passar um objeto vazio e pedir quantos itens ele tem.

Invariantes (verdades que sempre se mantêm)

Regra: O subtipo deve manter todos os invariantes do tipo base.

Exemplos:

Se a classe base garante que um ID é imutável após criação, o subtipo não pode permitir alterar o ID.
Se a classe base garante que o saldo inicial de conta bancária ≥ 0, o subtipo não pode criar contas com saldo negativo.
Se a classe base garante que uma lista está sempre ordenada, o subtipo não pode inserir elementos fora de ordem.
Se a classe base garante que a largura e altura são independentes, o subtipo não pode forçar que sejam sempre iguais (clássico Rectangle vs Square).
Se a classe base garante que um arquivo temporário é apagado após uso, o subtipo não pode manter o arquivo no disco.
Se a classe base garante que a conexão com banco de dados está aberta enquanto o objeto existir, o subtipo não pode fechar a conexão no meio da execução.
Se a classe base garante que valores duplicados não existem numa coleção, o subtipo não pode permitir duplicatas.
Se a classe base garante que datas estão sempre no futuro (ex.: agendamento), o subtipo não pode permitir datas no passado.
Se a classe base garante que um token expira em até 1 hora, o subtipo não pode emitir tokens com expiração indefinida.
Se a classe base garante que a moeda de uma transação é fixa após criação, o subtipo não pode permitir mudar a moeda depois.

Exemplo concreto para invariantes (verdades que devem se manter)

Um dos exemplos mais conhecidos de quebra de invariante é quando se tenta usar o Quadrado como subtipo de Retângulo. A ideia parece natural: um quadrado é um retângulo com a mesma altura e largura.

O problema é que, nessa frase, já quebramos a invariante dos dois:

Retângulo: largura e altura são independentes.
Quadrado: largura e altura são sempre iguais.

Ou seja, Quadrado e Retângulo são objetos distintos que, por acaso, compartilham uma propriedade em comum: a área. Mas, se for por isso, Círculo também tem área e nem por isso é um retângulo.

Para ilustrar um caso diferente do clássico retângulo/quadrado, veja o código abaixo:

class DatabaseConfig:
    def __init__(self, dsn: str) -> None:
        self._dsn = dsn

    @property
    def dsn(self) -> str: # uma invariância
        return self._dsn


class MySqlDatabaseConfig(DatabaseConfig):
    def __init__(self, host: str, user: str, password: str, db: str) -> None:
        # Não tem DSN, mas força herança para "reaproveitar" métodos
        self.host = host
        self.user = user
        self.password = password
        self.db = db

        # Apenas inicializa a base com valor vazio (quebrando a invariante)
        super().__init__("")


def connect(cfg: DatabaseConfig) -> None:
    # Cliente depende da invariante DatabaseConfig.dsn
    print("Connecting to:", cfg.dsn)


cfg_bad = MySqlDatabaseConfig(host="", user="root", password="", db="app")
connect(cfg_bad)  # ❌ imprime DSN vazio; quebra a invariante

No exemplo acima, DatabaseConfig foi projetada para trabalhar com dsn como parte obrigatória. O subtipo herda a classe mas ignora essa regra, inicializando com valor vazio. Isso quebra o contrato implícito de que dsn sempre está configurado.

Uma forma de resolver seria:

Extrair métodos compartilhados para outra classe/módulo, evitando herança forçada.
Padronizar todas as subclasses para realmente usarem dsn no mesmo formato.

Por que isso importa?

O LSP é fácil de quebrar sem perceber. Não é preciso "herança do mal" nem mudar tipagem, um simples detalhe de lógica já quebra o contrato. Muitos desses bugs são sutis e podem viver despercebidos por anos... até que um dia 💥💥💥.

No fim das contas, respeitar o LSP é menos sobre decorar uma definição formal e mais sobre entender o contrato invisível que existe entre a classe base e seus subtipos. Muitas violações não aparecem nos testes de tipagem, nem nos seus testes automatizados, mas cobram seu preço em produção, quando o sistema começa a se comportar de forma inesperada. Então, da próxima vez que criar uma hierarquia de classes, lembre-se: herdar é fácil, mas herdar corretamente é outra história completamente diferente.

logging no Python: Pare de usar print no lugar errado

Tue, 05 Aug 2025 00:00:00 GMT

O logging é o módulo oficial do Python para lidar com logs de forma estruturada, profissional e extensível. Além disso, ele serve como uma alternativa muito mais poderosa ao velho e conhecido print() para debug rápido durante o desenvolvimento.

Enquanto o print() é ótimo pra exibir algo na tela, o logging te dá controle total sobre o evento que vai ser registrado, como vai ser formatado e pra onde essa informação vai (terminal, arquivo, socket, banco, etc). São funções diferentes entre print e logging, mas esse comparativo sempre aparece quando falamos de logging.

Ele também trabalha com níveis de severidade (DEBUG, INFO, WARNING, ERROR, CRITICAL), suporta múltiplos formatos, múltiplos destinos (handlers), hierarquia de loggers e configuração via código ou arquivos externos.

Em outras palavras: ele foi feito pra log em aplicações reais. São registros de eventos categorizados para aplicações de gente grande, que sabe o que está fazendo e sabe que vai precisar debugar e refatorar o código em algum momento.

O melhor é que já vem com o Python. Sem dependência. Sem gambiarra.

Links úteis para este artigo

Se você caiu nesse artigo de paraquedas, ele é apenas parte de um conteúdo BEM MAIOR. Temos todo esse texto em vídeo no YouTube e também um repositório com todo o código, segue:

Então vamos continuar...

Como o `logging` funciona por dentro

O sistema de logging do Python é organizado como uma estrutura hierárquica (em forma de árvore), onde cada logger é um objeto único identificado por um nome textual (por exemplo: meuapp, meuapp.api, etc). Essa hierarquia é definida simplesmente pelo nome, usando pontos (.) para indicar níveis diferentes.

Exemplo de loggers:

app
app.database
app.http
app.http.requests

Visualmente, a estrutura ficaria assim:

root
└── app
    ├── database
    └── http
        └── requests

Essa hierarquia permite algo muito poderoso: a propagação dos logs. Por padrão, quando um logger emite um log, essa mensagem sobe na hierarquia até chegar ao logger pai e, eventualmente, ao logger raiz (root).

Na prática, isso significa que você pode configurar todos os handlers (por exemplo: imprimir no terminal, gravar em arquivos, enviar logs para serviços externos) diretamente no logger raiz. Assim, todos os loggers filhos automaticamente reutilizam esses handlers, sem precisar configurá-los individualmente toda vez.

Só tem um detalhe importante aqui: algumas bibliotecas também usam loggers internamente, seguindo essa mesma hierarquia de nomes. Por isso, os logs emitidos por essas libs podem acabar sendo capturados pelos seus handlers globais também—desde que o nível configurado permita isso, é claro.

Nota: Se seu app não for grande e cheio de partes independentes, não precisa complicar criando múltiplos loggers e uma hierarquia extensa. Na maioria dos casos, um único logger já resolve tudo.

Nos exemplos a seguir, vamos ver tudo isso funcionando claramente na prática.

Conceitos principais: Loggers, Handlers, Formatters e Filters

O logging é formado por 4 blocos principais:

Logger: é quem dispara a mensagem (ex: logger.info("oi")).
Handler: define pra onde a mensagem vai (terminal, arquivo, e-mail etc).
Formatter: define como a mensagem vai aparecer (formato da string).
Filter (opcional): permite filtrar o que será logado.

Esses blocos funcionam como peças de LEGO: você encaixa e combina como quiser.

Pode ter um logger que salva tudo em um arquivo .json, outro que só mostra ERROR no terminal com cor, outro que manda INFO pro Telegram (por que não?).

Tudo isso é configurável via código ou por arquivos .ini, .yaml, .json, como preferir.

Níveis de severidade: `level`

O nível de severidade (level) aparece em dois momentos distintos:

Na configuração do logger e/ou handler.
Na emissão do log.

A primeira define o que será aceito ou descartado. A segunda define qual a severidade de um log específico.

# 1. Configuração: esse logger aceita logs de WARNING pra cima
logger.setLevel(logging.WARNING)

# ...

# 2. Emissão: esse log será emitido com nível DEBUG
logger.debug("sou um debug")

Como o `level` funciona

Tanto loggers quanto handlers possuem um level. Esse valor determina se uma mensagem será processada ou descartada, com base em sua severidade.

Os níveis disponíveis são:

NOTSET ou 0 – sem configuração explícita.
DEBUG ou 10 – detalhes técnicos para depuração (tipo print()).
INFO ou 20 – informações gerais da execução.
WARNING ou 30 – algo inesperado aconteceu, mas foi contornado.
ERROR ou 40 – erro durante a execução.
CRITICAL ou 50 – erro grave. A aplicação pode parar ou já parou.

Você pode usar os nomes (DEBUG, INFO...) ou os números diretamente.

O valor numérico importa porque a regra é: um log só será processado se o level desse log for maior ou igual ao level do logger e do handler.

Exemplo prático usando level

logger.setLevel(logging.ERROR)

logger.debug("DEBUG")     # ignorado
logger.warning("WARNING") # ignorado
logger.error("ERROR")     # processado
logger.critical("CRITICAL") # processado

Emissão de um log em um `level` específico

Para emitir um log, usamos os métodos do logger que correspondem ao nível de severidade desejado:

logger.debug(...)
logger.info(...)
logger.warning(...)
logger.error(...)
logger.critical(...)

Exemplo:

# Isso emite um log com nível WARNING (30)
logger.warning("mensagem do meu log")

Neste caso, estamos emitindo uma mensagem com nível 30 (WARNING). Ela será avaliada pelo logger e por cada handler configurado, e só será processada se passar pelos filtros de level.

basicConfig: iniciando com `logging` no código

basicConfig é uma função do módulo logging, feita para configurar o root logger de forma simples e rápida. Geralmente, ela será usada em scripts menores para facilitar a configuração rápida do logging.

Dependendo de quais argumentos forem usados, ela pode configurar handlers diferentes no root logger.

`StreamHandler`: saída para `stderr` ou `stdout`

Se você não enviar o argumento filename para basicConfig, o handler padrão usado será um StreamHandler.

O termo stream se refere a objetos semelhantes a arquivos, ou seja, objetos que possuem métodos como .write() e .flush(). Tanto sys.stdout quanto sys.stderr são exemplos desses objetos.

Por padrão, o StreamHandler escreve no stderr. Já o print() padrão do Python escreve no stdout. Ou seja: ambos fazem print, mas vão pra fluxos diferentes.

Nota: É possível trocar o stream da classe StreamHandler, passando um argumento como sys.stdout, mas isso foge do nosso foco aqui.

Código: basicConfig + StreamHandler

Primeiro, importamos o módulo logging e definimos o formato de cada linha de log:

import logging

# Formato do log - veja todos os atributos disponíveis em:
# https://docs.python.org/3/library/logging.html#logrecord-attributes
simple_format = "%(levelname)s|%(name)s|%(asctime)s|%(message)s|%(filename)s|%(lineno)d"

# Isso configura o root logger conforme explico a seguir.
logging.basicConfig(format=simple_format)

O trecho acima faz o seguinte:

Cria um StreamHandler que envia os logs para o stderr;
Aplica um Formatter com o formato definido;
Adiciona esse handler ao root logger;
Define o nível do root logger como WARNING (padrão do Python, caso não seja especificado).

Com isso, o root logger já está pronto pra uso. Basta fazer:

# Logando com o root (não vamos usar isso, só exemplo)
logging.warning("Oi!")

Nota: O basicConfig aceita vários outros argumentos, como level, filename, filemode, handlers, stream e mais. Se você quiser, pode definir o nível diretamente, por exemplo: level=logging.DEBUG.

getLogger() cria ou acessa nosso próprio logger

Com o root logger configurado, a gente pode usar a função getLogger() para criar (ou acessar) nossos próprios loggers. Essa função tem três comportamentos distintos, dependendo do argumento:

logging.getLogger(): sem argumento, retorna o root logger.
logging.getLogger("meuapp"): com um nome, cria um novo logger se ainda não existir.
logging.getLogger("meuapp"): nas próximas chamadas com o mesmo nome, retorna o mesmo logger criado anteriormente (singleton por nome).

Depois de criado, você pode definir o nível de severidade que esse logger vai aceitar:

logger = logging.getLogger("meuapp")
logger.setLevel(logging.DEBUG)

Feito isso, já pode começar a mandar logs e ver tudo aparecendo no terminal:

# Exibe logs com StreamHandler
# debug info warning error critical
logger.debug("mensagem de log")
logger.info("mensagem de log")
logger.warning("mensagem de log")
logger.error("mensagem de log")
logger.critical("mensagem de log")

# Exception
try:
    print(1 / 0)
except ZeroDivisionError:
    logger.exception("dividiu por zero aí")

Saída esperada:

DEBUG|meuapp|2025-06-29 17:36:09,226|mensagem de log|main.py|24
INFO|meuapp|2025-06-29 17:36:09,226|mensagem de log|main.py|25
WARNING|meuapp|2025-06-29 17:36:09,226|mensagem de log|main.py|26
ERROR|meuapp|2025-06-29 17:36:09,226|mensagem de log|main.py|27
CRITICAL|meuapp|2025-06-29 17:36:09,226|mensagem de log|main.py|28
ERROR|meuapp|2025-06-29 17:36:09,226|dividiu por zero aí|main.py|34
Traceback (most recent call last):
  File "main.py", line 32, in <module>
    print(1 / 0)
          ~~^~~
ZeroDivisionError: division by zero

Código completo para basicConfig e StreamHandler

O código completo ficou assim:

import logging

# Formato para o Formatter
# Veja os atributos disponíveis em:
# https://docs.python.org/3/library/logging.html#logrecord-attributes
simple_format = "%(levelname)s|%(name)s|%(asctime)s|%(message)s|%(filename)s|%(lineno)d"
logging.basicConfig(format=simple_format)

# cria o meu logger "meuapp"
logger = logging.getLogger("meuapp")
logger.setLevel(logging.DEBUG)

logger.debug("mensagem de log")
logger.info("mensagem de log")
logger.warning("mensagem de log")
logger.error("mensagem de log")
logger.critical("mensagem de log")

try:
    print(1 / 0)
except ZeroDivisionError:
    logger.exception("Alguém tentou dividir por zero aí.")

`FileHandler`: saída para um arquivo

basicConfig também é capaz de escrever logs em arquivos mudando levemente os argumentos. Precisamos passar o caminho do arquivo de log e o modo de abertura desejado para esse arquivo.

Nota: Se você mudar a pasta onde o arquivo deverá ser salvo, essa pasta precisa existir, do contrário terá um erro.

Peguei só o trecho que precisa de modificação no código anterior:

import logging

format1 = "%(levelname)s|%(name)s|%(asctime)s|%(message)s|%(filename)s|%(lineno)d"

# Migrar para arquivo: basta informar o caminho, modo de abertura e encoding.
logging.basicConfig(
    level=logging.DEBUG,
    format=format1,
    filename="log.log",
    filemode="a",
    encoding="utf-8",
)

# Meu logger -> meuapp (root -> meuapp)
logger = logging.getLogger("meuapp")

# Agora você não verá mais saída no console
logger.debug("Isso deve aparecer no arquivo log.log")

# Arquivo log.log
# DEBUG|meuapp|2025-07-05 10:12:30,311|Isso deve aparecer no arquivo log.log|lesson01.py|20

Ao fazer essa configuração, em vez de usar o StreamHandler que vimos anteriormente, agora ele usa o FileHandler. Para esse handler, precisamos do caminho do arquivo (filename), do modo de abertura (filemode) e do encoding.

Um ponto importante aqui é que você não verá mais nada no terminal, porque o nosso handler agora envia apenas para o arquivo, e não para stderr ou stdout. Para ver ambos, precisamos de mais de um handler.

O filemode pode ser qualquer um dos modos de escrita, por exemplo:

a - escreve no final do arquivo (não apaga logs antigos, apenas adiciona)
w - escreve no começo do arquivo (apaga tudo que estava lá)

`basicConfig`, `FileHandler` e `StreamHandler`

Que tal a gente combinar tudo isso e adicionar dois handlers de uma vez? Bora ver como usar FileHandler e StreamHandler junto com a função basicConfig.

Vou mandar o código completo pra ficar mais fácil de entender.

No exemplo abaixo, a gente cria os dois handlers manualmente e adiciona eles no logger root via basicConfig. O resto continua o padrão de sempre.

A propagação (propagate = True) já fica ativa por padrão. Isso quer dizer que, quando chamamos algo no nosso logger (que não tem handler nenhum), o log é propagado para o logger acima dele, no caso, o root.

Como o root agora tem dois handlers, os dois são executados quando o nível de severidade bate. O resultado? Log no terminal e no arquivo ao mesmo tempo.

Você poderia ter quantos handlers e formatters quisesse, todos pendurados no root.

import logging
import sys

format1 = "%(levelname)s|%(name)s|%(asctime)s|%(message)s|%(filename)s|%(lineno)d"

# Podemos criar nossos próprios handlers usando as classes que mencionei antes
file_handler = logging.FileHandler(
    filename="log.log",
    mode="a",
    encoding="utf-8",
)
stream_handler = logging.StreamHandler(sys.stdout)

# Nossos handlers precisam de um formatter
main_formatter = logging.Formatter(fmt=format1)

# A configuração do formatter pode ser reutilizada.
file_handler.setFormatter(main_formatter)
stream_handler.setFormatter(main_formatter)

# configura o root logger
logging.basicConfig(handlers=[file_handler, stream_handler])

# cria o meu logger
logger = logging.getLogger("meuapp")
# define o nível do meu log
logger.setLevel(logging.DEBUG)

# Saída nos dois handlers
logger.debug("mensagem de log")
logger.info("mensagem de log")
logger.warning("mensagem de log")
logger.error("mensagem de log")
logger.critical("mensagem de log")

# Exception
try:
    print(1 / 0)
except ZeroDivisionError:
    logger.exception("Alguém tentou dividir por zero aí.")

A saída do código acima fica como mostro abaixo tanto no console quando no terminal.

DEBUG|meuapp|2025-07-05 10:59:37,842|mensagem de log|lesson05_01.py|41
INFO|meuapp|2025-07-05 10:59:37,842|mensagem de log|lesson05_01.py|42
WARNING|meuapp|2025-07-05 10:59:37,842|mensagem de log|lesson05_01.py|43
ERROR|meuapp|2025-07-05 10:59:37,842|mensagem de log|lesson05_01.py|44
CRITICAL|meuapp|2025-07-05 10:59:37,842|mensagem de log|lesson05_01.py|45
ERROR|meuapp|2025-07-05 10:59:37,843|Alguém tentou dividir por zero aí.|lesson05_01.py|51
Traceback (most recent call last):
  File "/Users/luizotavio/Desktop/tutoriais_e_cursos/logging_course_yt/src/logging_course/lesson05_01.py", line 49, in <module>
    print(1 / 0)
          ~~^~~
ZeroDivisionError: division by zero

Hierarquia de Loggers e Handlers

Para unir a teoria à prática que exploramos, e para evitar as armadilhas mais comuns, vamos entender com precisão o que acontece no sistema de logging do Python:

Pontos Fundamentais para Lembrar:

basicConfig(): É a função de conveniência que configura o root logger (o "pai" de todos). Por padrão, ele adiciona um StreamHandler (para o console), um Formatter básico e define o level do root para WARNING. Em sistemas menores, é tranquilo usar, mas em sistemas maiores usaremos dictConfig que falaremos adiante.
getLogger('nome'): Cria (ou obtém) um Logger nomeado, que é filho do root logger (ou de outro logger se o nome tiver pontos, como app.modulo).
setLevel(): Usado para definir o nível mínimo de mensagens que um Logger ou um Handler irá processar.
Métodos de Log: debug(), info(), warning(), error() e critical() são os métodos que você usa em um Logger para emitir mensagens com um nível de gravidade específico.

A Grande Sacada: A Propagação e a Filtragem

Esta é a parte crucial e onde a maioria dos materiais simplifica demais. Preste muita atenção aqui!

Múltiplos Handlers: Um Logger pode ter um ou vários Handlers anexados a ele.
Handlers e Formatters: Cada Handler é responsável por direcionar o log para um destino (console, arquivo, etc.) e sempre usará um único Formatter para definir como a mensagem será exibida. Ele também pode ter Filters (que veremos depois) para um controle ainda mais fino.
Níveis Duplos: Tanto o Logger (o coletor de logs) quanto o Handler (o publicador de logs) possuem seu próprio level. Esta é a fonte de possíveis problemas e pode te deixar debugando o próprio logging por horas.

A Propagação: O Caminho Real do Log (e o Papel dos Handlers)

Quando um log é emitido por um Logger nomeado, ele percorre uma jornada pela hierarquia. Esse "caminho" pode ser confuso, porque não é apenas o Logger que está filtrando, os Handlers também entram no jogo.

Imagine a hierarquia de loggers assim:

root           [root_handler_1, root_handler_2]
└── A          [A_handler_1]
    └── A.B    [B_handler_1, B_handler_2, B_handler_3]

Vamos supor que o level de A.B foi configurado como INFO (20) e que emitimos:

A.B.warning("Mensagem de Exemplo")

No Logger A.B (o emissor do log)

A primeira filtragem acontece aqui. O log tem level WARNING (30), e o logger A.B aceita logs com INFO (20) ou superior. Então a verificação é simples:

level do log >= level do logger → ok

Se passar aqui, segue adiante. Se não passar, o log morre aqui, não chega em nenhum handler.

Nos Handlers de A.B

Agora o log chega nos Handlers do logger A.B, no exemplo: B_handler_1, B_handler_2 e B_handler_3.

Cada handler faz sua própria checagem de level. Se o log for aceito, é publicado por aquele handler. Se não, é ignorado por ele (mas ainda pode ser aceito pelos outros handlers ou loggers superiores).

No Logger A (pai de A.B)

Se a propriedade propagate estiver True (valor padrão), o log sobe na hierarquia e chega ao logger A.

Mas aqui vem a pegadinha: o level do logger A não importa mais. Ele não é checado. A partir daqui, só os handlers dos loggers pais é que decidem o que fazer.

Nos Handlers de A

Cada handler de A (ex: A_handler_1) faz a mesma checagem de sempre: level do log >= level do handler. Se passar, o log é publicado.

No Logger root (e seus handlers)

Mais do mesmo: o log chega no logger root, ignora o level dele, e é analisado apenas pelos handlers root_handler_1 e root_handler_2.

Essa explicação é importante porque muita gente pensa que os loggers pais têm o poder de interromper ou descartar um log que subiu pela propagação. Mas não têm. O único logger com poder de barrar a mensagem é o que emitiu o log.

Se fosse pra resumir num post-it:

O log é verificado no logger que o emitiu. Se passar, é entregue aos seus handlers e, com propagate = True, sobe para os loggers pais. Mas a partir daí, apenas os handlers desses loggers superiores fazem checagem. Os loggers pais não barram mais nada.

Se o logger emissor não aceitar o log, acabou o jogo ali. Nada é publicado.

Loggers de terceiros podem entrar no seu log

Se você usar o logging de forma incorreta: tipo deixando o level do root em DEBUG ou usando o root como logger principal por algum motivo. Uma coisa muito comum que costuma ocorrer é você começar a ver logs de DEBUG de aplicações de terceiros no seu log.

Geralmente queremos logs de libs de terceiros no nosso log, mas não um milhão de DEBUGs. Talvez apenas de WARNING para cima, ou até de ERROR para cima.

Vamos simular e corrigir isso a seguir.

`rich`: cobaia e nossos logs mais bonitos no console

Vamos usar a biblioteca rich pra deixar os logs do console mais agradáveis de ler, com cor, syntax highlight e outros agrados visuais. Só que vamos usar essa lib bem mais adiante no texto.

Mesmo assim, instale-a com o gerenciador que preferir e vamos usar ela mesmo como exemplo de log de terceiros:

# Usando uv
uv add rich

# Ou com pip
pip install rich

Exemplo prático: logs de terceiros no seu log com rich

Vamos configurar o logging novamente, do zero, só que com root configurado em level DEBUG (Não recomendado):

import logging

simple_format = "%(levelname)s|%(name)s|%(asctime)s|%(message)s|%(filename)s|%(lineno)d"

# Configura o root logger com:
# - StreamHandler (stderr)
# - Formatter customizado
# - Level DEBUG
logging.basicConfig(format=simple_format, level=logging.DEBUG)

# Cria o nosso logger, mas sem handlers próprios
logger = logging.getLogger("meuapp")
logger.setLevel(logging.DEBUG)

# Apenas um teste
logger.warning("Isso é um teste")

# Saída esperada:
# WARNING|meuapp|2025-07-01 19:44:54,566|Isso é um teste|main.py|14

Agora, vamos simular o uso do rich, que é uma lib que também usa o módulo logging internamente. Suponha que você queira imprimir um markdown no terminal:

from rich import print as rprint
from rich.markdown import Markdown

md = Markdown("# Nos Handlers de `A`")
rprint(md)

Se algum código interno do rich emitir logs, mesmo que você não peça, esses logs vão aparecer, porque o root logger está aberto no nível DEBUG e todos os handlers estão lá.

Esse é o tipo de poluição que você pode querer evitar.

Isso era só pra ser um código normal, simulando algo dentro da minha aplicação. Mas olha só o que apareceu no log:

Nota: eu cortei bastante texto do log abaixo, mas dependendo do que você estiver fazendo, pode ficar absurdamente longo. Em alguns casos, aparecem tantos logs que sua aplicação (ou até seu computador) pode travar.

WARNING|meuapp|2025-07-01 20:02:21,221|Isso é um teste|main.py|14
DEBUG|markdown_it.rules_block.code|2025-07-01 20:02:21,271...
DEBUG|markdown_it.rules_block.fence|2025-07-01 20:02:21,271...
DEBUG|markdown_it.rules_block.blockquote|2025-07-01 20:02:21,271...
DEBUG|markdown_it.rules_block.hr|2025-07-01 20:02:21,271...
DEBUG|markdown_it.rules_block.list|2025-07-01 20:02:21,271...
DEBUG|markdown_it.rules_block.reference|2025-07-01 20:02:21,271...
DEBUG|markdown_it.rules_block.html_block|2025-07-01 20:02:21,271...
DEBUG|markdown_it.rules_block.heading|2025-07-01 20:02:21,271...

Qual o problema aqui? Nenhum, se for intencional.

Só aconteceu que a sua aplicação e o rich decidiram seguir a mesma estratégia: usar o root logger pra tudo.

Quando você configura o root com um nível permissivo (tipo DEBUG), qualquer lib que use o sistema de logging do Python pode ter suas mensagens publicadas nos seus handlers, inclusive aquelas que você nunca pediu pra logar.

Como mencionei antes, é normal querermos logs de libs de terceiros no nosso log. Elas fazem parte da nossa aplicação, porém, em um nível interessante, como WARNING ou ERROR, e acima.

Soluções possíveis para log de libs de terceiros

Tem várias coisas que a gente pode fazer:

Subir o level do logger que está causando problema
Configurar o root adequadamente (de WARNING para cima)
Nunca usar o root logger diretamente como logger da sua aplicação
Isolar o seu logger do root (não recomendado, mas pode ser útil se está criando uma lib para outras pessoas)

Como subir o level de logs de terceiros com getLogger?

No próprio log que poluiu meu console e arquivo, a segunda coluna mostra o nome do logger: markdown_it!

Muita gente configura seus loggers como mostro a seguir. Isso é até uma recomendação da documentação se eu não estiver enganado:

logger = logging.getLogger(__name__)

Isso cria (ou acessa) um logger com o nome do módulo onde está sendo executado. Exemplo: se você está em um pacote chamado learn_logging, e o módulo se chama config_logger.py, o nome do logger será:

__main__ se executar direto
learn_logging.config_logger se importar de outro lugar

Mas voltando ao problema: se o log vem de markdown_it, basta fazer:

logging.getLogger("markdown_it").setLevel(logging.INFO)

Geralmente isso silencia o logger que está jogando um monte de mensagens no seu logger. Mas e se forem muitos? E se forem todas as 10 libs externas que você está usando num código só? E se as 10 libs que você instalou também usam outras 100 libs? Fica impraticável.

Meus handlers nos meus loggers

Você pode configurar os handlers no seu próprio logger. Como estamos usando basicConfig, os handlers estavam indo pro root. Agora vamos fazer de outro modo. Só um exemplo:

import logging

# Cria um handler só nosso
stream_handler = logging.StreamHandler()
stream_handler.setLevel(logging.DEBUG)

# Cria um formatter
simple_format = "%(levelname)s|%(name)s|%(asctime)s|%(message)s|%(filename)s|%(lineno)d"
main_formatter = logging.Formatter(fmt=simple_format)
stream_handler.setFormatter(main_formatter)

# CADÊ O ROOT??? sumiu 😎

logger = logging.getLogger("meuapp")
logger.setLevel(logging.DEBUG)
logger.addHandler(stream_handler)

logger.info("mensagem de log")

Pronto. Agora você não verá mais logs do rich ou de qualquer lib de terceiro. Não porque bloqueamos eles, mas porque não estamos mais ouvindo o root. E como essas libs usam o root, seus logs vão pra lugar nenhum.

Nota: isso pode ser um problema, visto que libs de terceiros fazem parte da nossa aplicação.

Omitir logs de libs de terceiros é como omitir logs de uma parte do código que realmente vai para produção.

O que eu faria nesse caso, seria manter um handler menos importante no meu próprio logger com level DEBUG (vejo tudo no meu handler), mas colocaria os handlers importantes, com níveis de WARNING para cima, no root para continuar tendo acesso aos logs de libs de terceiros.

Cada caso é um caso a ser estudado.

`dictConfig` - agora vamos aos negócios

Como mencionei quando comecei o trecho sobre basicConfig, ela é realmente básica. E o que é mais contraditório nisso tudo, é que se a sua configuração for levemente mais complexa, ela se torna extremamente complexa também.

A forma mais completa (e moderna) de configurar o logging no Python é usando dictConfig.

Como o próprio nome indica, ao invés de ficar configurando tudo solto como quando usamos basicConfig, com dictConfig podemos montar toda a configuração usando um único dicionário. Isso te permite, inclusive, criar arquivos de configuração em outros formatos como JSON ou YAML, e carregar esse arquivo ao subir a aplicação.

Vamos migrar essa configuração para dictConfig:

import logging

file_handler = logging.FileHandler(filename="log.log", mode="a", encoding="utf-8")
stream_handler = logging.StreamHandler()

simple_format = "%(levelname)s|%(name)s|%(asctime)s|%(message)s|%(filename)s|%(lineno)d"

main_formatter = logging.Formatter(fmt=simple_format)
file_handler.setFormatter(main_formatter)
stream_handler.setFormatter(main_formatter)

logging.basicConfig(handlers=[file_handler, stream_handler])

logger = logging.getLogger("meuapp")
logger.setLevel(logging.DEBUG)

logger.debug("mensagem de log")
logger.warning("mensagem de log")
logger.error("mensagem de log")

Aqui temos o seguinte:

2 handlers: FileHandler e StreamHandler
1 formatter: Formatter
A configuração do root com os 2 handlers
A configuração no nosso logger meuapp com level DEBUG

Com dictConfig isso ficaria assim:

import logging
from logging.config import dictConfig
from typing import Any

# Dicionário de Configuração de Logging
# A configuração centralizada para o `dictConfig`.
LOGGING_CONFIG: dict[str, Any] = {
    # Versão da configuração. Sempre 1 por enquanto.
    "version": 1,
    # 'False' para não desativar loggers de bibliotecas de terceiros.
    "disable_existing_loggers": False,
    # Aqui vamos configurar o(s) formatter(s)
    "formatters": {
        # A chave é o nome que você usa para se referir a esse formatter
        "main_formatter": {
            # As configs são `chave`: `valor` no dicionário
            # Aqui está nosso formato anterior
            "format": "%(levelname)s|%(name)s|%(asctime)s|%(message)s|%(filename)s|%(lineno)d",
        },
        # Se tiver mais formatters, basta adicionar mais chaves com nomes desejados
    },
    # Aqui vem os handlers
    "handlers": {
        # É sempre a mesma ideia, a chave é o nome do handler
        "file_handler": {
            "class": "logging.FileHandler",
            "filename": "log.log",
            "mode": "a",
            "encoding": "utf-8",
            # Perceba o nome do formatter aqui (é a chave que criei lá em formatters)
            "formatter": "main_formatter",
            "level": "DEBUG",
        },
        "stream_handler": {
            "class": "logging.StreamHandler",
            "formatter": "main_formatter",
            "level": "DEBUG",
        },
    },
    # Root
    # Como o `root` é especial, tem uma chave só pra ele
    # Configuração do logger raiz, que captura todos os logs.
    "root": {
        # Novamente, estou usando as chaves criadas em handlers
        "handlers": ["file_handler", "stream_handler"],
    },
    # Aqui vem nossos loggers, apesar de que não precisamos disso
    # vale te mostrar como funciona
    "loggers": {
        "meuapp": {
            "level": "DEBUG",
        },
    },
}
dictConfig(LOGGING_CONFIG)

logger = logging.getLogger("meuapp")

logger.debug("mensagem de log")
logger.warning("mensagem de log")
logger.error("mensagem de log")

Não assusta não, se você olhar direitinho só temos isso:

LOGGING_CONFIG: dict[str, Any] = {
    "version": 1, # sempre o mesmo valor
    "disable_existing_loggers": False, # para mim, sempre o mesmo valor
    "formatters": {}, # aqui vem seus formatters
    "handlers": {}, # aqui os handlers
    "filters": {}, # aqui viriam os filters
    "root": {}, # aqui as configurações do `root`
    "loggers": {}, # aqui cada chave é um logger específico
}

As duas primeiras chaves você nem precisa mexer, é sempre o mesmo valor. O restante são palavras que falamos algumas centenas de vezes ao longo desse artigo.

A única coisa que pode soar estranho aqui é a estrutura, porque aqui você não está criando variáveis, nem está passando atributos, muito menos instanciando nada. Você só está informando o que você quer e o logging com a dictConfig que se virem. A nata da programação declarativa.

Eu vou te passar muitas configurações diferentes ao longo do texto, mas se estiver com pressa, vai lá na documentação do Python para mais detalhes sobre o Dictionary Schema Details.

Handlers padrão em `logging.handlers`

Caso precise de outros tipos de handlers para SMTP, SOCKET, HTTP e demais, antes de sair escrevendo suas classes aí, saiba todos handlers que temos disponíveis em logging.handlers (também alguns outros espalhados fora desse módulo).

É bem provável que você não precise escrever seu handler do zero. A documentação desses handlers está em Python - logging.handlers - Logging handlers.

Breve resumo de cada handler:

BaseRotatingHandler É a classe base para handlers que fazem rotação automática de arquivos de log. Você geralmente não usa diretamente, só herda dela pra criar novos handlers que rotacionam logs.
RotatingFileHandler Grava logs num arquivo e automaticamente cria arquivos novos quando atingem um tamanho definido (por exemplo: 5 MB por arquivo).
TimedRotatingFileHandler Similar ao anterior, mas aqui a rotação ocorre baseada em intervalos de tempo (ex: diário, semanal, mensal).
WatchedFileHandler (Unix/Linux) Observa o arquivo de log e, se o arquivo for movido, deletado ou recriado por um processo externo (ex: logrotate), o handler percebe e reabre automaticamente.
SocketHandler Envia logs via rede usando sockets TCP para um servidor remoto de logs.
DatagramHandler Semelhante ao SocketHandler, mas usa UDP em vez de TCP. Isso significa que o envio dos logs é mais rápido, porém não confiável.
SysLogHandler (Linux/macOS) Envia logs diretamente para o syslog do sistema operacional, integrando facilmente com o sistema operacional ou outros serviços que escutam o syslog.
SMTPHandler Envia logs por e-mail usando SMTP. Comumente usado pra logs críticos (ex: erros inesperados em produção).
NTEventLogHandler (Windows) Registra logs no Event Viewer (Visualizador de Eventos) do Windows.
HTTPHandler Envia logs via requisições HTTP para um servidor web externo, útil em integração com APIs ou serviços de log em nuvem.
BufferingHandler Acumula logs na memória, e só os libera quando o buffer atinge um limite definido. Normalmente não usado diretamente, serve como base para handlers que implementam buffering.
MemoryHandler Derivado do BufferingHandler, guarda logs na memória até que uma condição (nível crítico ou quantidade máxima) seja atingida. Nesse momento, os logs são repassados para outro handler configurado.
QueueHandler Envia logs para uma fila (queue.Queue). Ideal para processamento assíncrono de logs, melhorando o desempenho do app principal.
QueueListener Complemento do QueueHandler, escuta logs em uma fila e os despacha para outros handlers configurados. Facilita a implementação de logging assíncrono em aplicações concorrentes.

Handlers diretamente em logging (fora de logging.handlers):

Além desses do módulo logging.handlers, tem alguns handlers no módulo principal (logging):

StreamHandler: Escreve no terminal (stderr ou stdout).
FileHandler: Escreve logs diretamente num arquivo sem rotação automática.
NullHandler: Ignora completamente os logs recebidos, útil pra evitar avisos se nenhum handler tiver configurado.

Não tenho nem como falar sobre todos esses handlers nesse artigo, mas creio que com o que você está aprendendo aqui, não terá dificuldade em implementar nenhum deles para seu caso de uso específico.

`RotatingFileHandler` e múltiplos `StreamHandler` via `stdout` e `stderr`

Para adicionar um pouquinho mais de complexidade (e utilidade prática!) na nossa configuração, vamos fazer o seguinte:

Substituir o FileHandler pelo RotatingFileHandler (que rotaciona arquivos automaticamente);
Criar um StreamHandler que envia logs de níveis DEBUG e INFO para o stdout;
Criar outro StreamHandler que envia logs mais críticos (WARNING, ERROR e CRITICAL) para o stderr.
Também vou criar um formatter para cada handlers. Não há necessidade real para isso, mas quero distinção nos três logs, então preciso de três formatters.

Vou quebrar o dicionário em partes porque está ficando extremamente grande. Vamos trabalhar com as chaves de primeiro nível do dict: formatters, handlers, loggers, filters, root, etc. Só o que mudar.

`dictConfig`, chave `formatters`

"formatters": {
    "file": {
        "format": (
            # Os parenteses em strings geralmente é porque é muito longa
            # Vamos usar `file` para os arquivos de log
            "%(levelname)s|%(name)s|%(asctime)s|%(message)s|%(filename)s|%(lineno)d"
        ),
        "datefmt": "%Y-%m-%dT%H:%M:%S%z",  # Muda o formato da data
    },
    "stdout": {
        # Coloquei um `OUT: ` aqui pra gente conseguir distinguir no log
        "format": "OUT: [%(levelname)s] %(message)s",
    },
    "stderr": {
        "format": (
            # Coloquei um `ERR: ` aqui pra gente conseguir distinguir no log
            # Também coloquei uma cor vermelha aqui.
            # Isso não tem a ver com o dict, dictConfig ou o logging
            "\033[31mERR: [%(levelname)s] %(message)s - "
            "%(filename)s|%(lineno)d\033[0m"
        ),
    },
}

Certo, é bem verboso, mas isso são 3 formatters, do mesmo modo que fizemos antes, porém em dict. Os nomes desses formatters são as chaves do dicionário: file, stdout e stderr.

`dictConfig`, chave `handlers`

"handlers": {
    "file": {
        "class": "logging.handlers.RotatingFileHandler",
        "formatter": "file",  # LOGGING_CONFIG["formatters"]["file"]
        "filename": "log.log",  # Arquivo principal do log
        "maxBytes": 1024 * 1024 * 5,  # Tamanho máximo do log. 5MiB
        "backupCount": 5,  # Máximo de backups do arquivo de log
        "encoding": "utf-8",  # Codificação de caracteres do arquivo
    },
    "stdout": {
        "class": "logging.StreamHandler",
        "formatter": "stdout",  # LOGGING_CONFIG["formatters"]["stream"]
        "level": "DEBUG",  # 🚨 Isso vai gerar problema (tente entender)
        "stream": "ext://sys.stdout",  # ext é algo externo ao dict: sys.stdout
    },
    "stderr": {
        "class": "logging.StreamHandler",
        "formatter": "stderr",  # LOGGING_CONFIG["formatters"]["stream"]
        "level": "WARNING",
        "stream": "ext://sys.stderr",  # ext é algo externo ao dict: sys.stderr
    },
},

Os nomes dos handlers são as chaves do dicionário: file, stdout e stderr. Estou usando o mesmo nome para handlers e formatters, o que facilita a organização.

`dictConfig`, chaves `loggers` e `root`

"root": {
    "handlers": ["file", "stdout", "stderr"],
},
"loggers": {
    "meuapp": {
        "level": "DEBUG",
    },
},

Pronto, agora foi só adicionar os handlers no logger e finalizamos.

Código completo com `dictConfig`

Isso fica extremamente verboso, mas depois vamos mover esse dicionário para um arquivo JSON.

import logging
from logging.config import dictConfig
from typing import Any

LOGGING_CONFIG: dict[str, Any] = {
    "version": 1,
    "disable_existing_loggers": False,
    "formatters": {
        "file": {
            "format": (
                "%(levelname)s|%(name)s|%(asctime)s|%(message)s|%(filename)s|%(lineno)d"
            ),
            "datefmt": "%Y-%m-%dT%H:%M:%S%z",  # Muda o formato da data
        },
        "stdout": {
            "format": "OUT: [%(levelname)s] %(message)s",
        },
        "stderr": {
            "format": (
                "\033[31mERR: [%(levelname)s] %(message)s - "
                "%(filename)s|%(lineno)d\033[0m"
            ),
        },
    },
    "handlers": {
        "file": {
            "class": "logging.handlers.RotatingFileHandler",
            "formatter": "file",  # LOGGING_CONFIG["formatters"]["file"]
            "filename": "log.log",  # Arquivo principal do log
            "maxBytes": 1024 * 1024 * 5,  # Tamanho máximo do log. 5MiB
            "backupCount": 5,  # Máximo de backups do arquivo de log
            "encoding": "utf-8",  # Codificação de caracteres do arquivo
        },
        "stdout": {
            "class": "logging.StreamHandler",
            "formatter": "stdout",  # LOGGING_CONFIG["formatters"]["stream"]
            "level": "DEBUG",  # 🚨 Isso vai gerar problema (tente entender)
            "stream": "ext://sys.stdout",  # ext é algo externo ao dict: sys.stdout
        },
        "stderr": {
            "class": "logging.StreamHandler",
            "formatter": "stderr",  # LOGGING_CONFIG["formatters"]["stream"]
            "level": "WARNING",
            "stream": "ext://sys.stderr",  # ext é algo externo ao dict: sys.stderr
        },
    },
    "root": {
        "handlers": ["file", "stdout", "stderr"],
    },
    "loggers": {
        "meuapp": {
            "level": "DEBUG",
        },
    },
}
dictConfig(LOGGING_CONFIG)

logger = logging.getLogger("meuapp")

logger.debug("mensagem de log")
logger.info("mensagem de log")
logger.warning("mensagem de log")
logger.error("mensagem de log")
logger.critical("mensagem de log")

Eu estava esperando uma saída diferente, mas perceba que os logs estão duplicados:

OUT: [DEBUG] mensagem de log
OUT: [INFO] mensagem de log
OUT: [WARNING] mensagem de log                  ### <- `warning` está no stdout
ERR: [WARNING] mensagem de log - main.py|60
OUT: [ERROR] mensagem de log                    ### <- `error` está no stdout
ERR: [ERROR] mensagem de log - main.py|61
OUT: [CRITICAL] mensagem de log                 ### <- `critical` está no stdout
ERR: [CRITICAL] mensagem de log - main.py|62

Lembra que a ideia era: DEBUG e INFO vão para o stdout, e WARNING, ERROR, CRITICAL vão para o stderr?

O problema está nos níveis configurados. Quando colocamos o handler stdout com nível DEBUG, isso significa:

"Aceite logs de DEBUG para cima"

Ou seja, ele aceita todos os níveis (DEBUG, INFO, WARNING, ERROR, CRITICAL). Por isso estamos vendo os logs mais graves saindo tanto no stdout quanto no stderr.

Pra resolver isso, vamos precisar de filters, assim conseguimos controlar com mais precisão quais mensagens vão pra cada handler.

Claro, bora terminar essa parte com estilo e clareza. Aqui vai a continuação ideal pra essa seção:

`filters` - filtrando logs

filters são adicionados nos handlers ou loggers para controlar melhor quais mensagens de log devem ser processadas por cada um. Eles funcionam como um filtro extra, além do nível mínimo (level). De forma simplista, é só você imaginar que o level é um filter que veio pronto, porém é limitado.

O nosso caso anterior é um exemplo clássico: Queríamos que o handler do stdout exibisse apenas DEBUG e INFO. Mas como ele estava com nível DEBUG, ele acabou aceitando todos os níveis acima também, e por isso vimos WARNING, ERROR e CRITICAL aparecendo duas vezes (uma vez no stdout e outra no stderr).

A solução é aplicar um filter que bloqueie tudo acima de INFO no handler do stdout.

Criando um `filter`

Vamos criar um filtro customizado simples. Estou criando outro módulo chamado filters.py no pacote em que estou (logging_course).

Para criar o filter, vou criar uma classe que herda de logging.Filter. O método filter retorna True se aquele log é permitido ou False se é para descartar. Estranhamente, não é necessário herdar de logging.Filter, mas é mais semântico. Qualquer classe que tenha o método filter vai funcionar. Além disso, o filter também pode alterar o log e retornar um LogRecord completamente diferente.

Nota: LogRecord é o objeto de log com todas as informações daquele log em específico. Toda vez que você emite um log, sua mensagem gera um novo LogRecord que vai ter a data, o módulo, o número da linha, o nível do log, etc.

import logging

class MaxLevelFilter(logging.Filter):
    def __init__(self, max_level: str) -> None:
        # max_level é um argumento adicional que coloquei
        # max_level deve receber o nome do level, mas quero o número
        super().__init__()

        # self.max_level terá o número do level
        self.max_level = logging.getLevelNamesMapping().get(max_level.upper(), 50)

    def filter(self, record: logging.LogRecord) -> bool:
        # record é o LogRecord que eu disse antes
        # record.levelno é o número do level do log
        # se o número do level do log for menor ou igual ao max_level que
        # definimos no filter o log passa.
        # INFO 20 só aceitará logs INFO e DEBUG.
        return record.levelno <= self.max_level

Esse filtro aceita apenas mensagens até o nível informado. Se passarmos logging.INFO, ele permite DEBUG e INFO, e bloqueia o resto.

Atualizando o `dictConfig` com `filters`

Agora vamos incluir o filtro na nossa configuração:

LOGGING_CONFIG: dict[str, Any] = {
    "version": 1, # mesma coisa
    "disable_existing_loggers": False, # mesma coisa
    # `filters` é uma chave de primeiro nível,
    # assim como `formatters`
    "filters": {
        # O nome do meu filtro dentro da dictConfig é a chave
        "only_debug_info": {
            # Como é uma classe customizada, com argumento personalizado,
            # temos que colocar essa chave estranha com parênteses
            # O caminho completo do meu filter: logging_course.filters.MaxLevelFilter
            "()": "logging_course.filters.MaxLevelFilter",
            # Meu argumento adicional com valor INFO
            "max_level": "INFO"
        }
    },
    "formatters": {...}, # mesma coisa
    # resto tudo a mesma coisa
}

E aplicar esse filtro no handler do stdout:

LOGGING_CONFIG: dict[str, Any] = {
    "version": 1, # mesma coisa
    "disable_existing_loggers": False, # mesma coisa
    "filters": {...}, # vimos acima
    "formatters": {...}, # mesma coisa
    "handlers": {
        "stdout": {
            "class": "logging.StreamHandler",
            "formatter": "stdout",
            "level": "DEBUG",
            "filters": ["only_debug_info"], # Poderíamos ter vários filters aqui
            "stream": "ext://sys.stdout"
        },
        # ... os outros handlers são a mesma coisa
    },
    # ...mesma coisa
}

Resultado final com `filter`

Com isso, o comportamento será exatamente o que você queria:

OUT: [DEBUG] mensagem de log
OUT: [INFO] mensagem de log
ERR: [WARNING] mensagem de log - main.py|67
ERR: [ERROR] mensagem de log - main.py|68
ERR: [CRITICAL] mensagem de log - main.py|69

Agora sim, stdout correto, stderr correto.

Configuração via JSON (mas aqui a gente vai manter tudo em Python)

Apesar de ser comum externalizar a configuração do logging usando arquivos .json, nesse artigo vou manter tudo em Python para facilitar a vida, mas em um cenário real, é uma maravilha poder configurar tudo via "JSON".

Eu estou usando JSON como exemplo, mas você pode usar qualquer formato que quiser. JSON, YAML, TOML são bem populares. Outra coisa importante é que o próprio logging também tem uma configuração chamada logging.config.fileConfig caso prefira, está tudo na documentação oficial do Python.

Exemplo de configuração JSON com dictConfig

Vamos criar um arquivo chamado logging.json na raiz do projeto. Estou criando outra configuração nesse exemplo para encurtar um pouco o texto (essa não é a melhor configuração, como vimos antes, mas vai servir). Também vou jogar o único handler que criei dentro do root.

{
  "version": 1,
  "disable_existing_loggers": false,
  "formatters": {
    "default": {
      "format": "[%(levelname)s] %(message)s"
    }
  },
  "handlers": {
    "console": {
      "class": "logging.StreamHandler",
      "formatter": "default",
      "level": "DEBUG",
      "stream": "ext://sys.stdout"
    }
  },
  "root": {
    "handlers": ["console"],
    "level": "DEBUG"
  }
}

Esse DEBUG aí no root chega a dar arrepios.

Carregando a configuração JSON com Python:

import json
import logging.config

with open("logging.json", "r") as f:
    config = json.load(f)

logging.config.dictConfig(config)

Observações:

É meio óbvio, mas JSON não é Python (wow, descobriu agora?). Mas sério, algumas coisas não funcionam exatamente como no Python. Um exemplo: eu estava usando uma cor com \033[31m e \033[0m (vermelho e reset). Na hora que o JSON é carregado, isso tudo é string normal, ou seja, vai aparecer como texto no seu stdout ou stderr.

Tem como corrigir? Sim, já que você tocou no assunto, vamos criar nosso próprio formatter.

Formatter: que tal criar seu próprio formatter?

Vamos lá, vou criar um formatter só como exemplo para você entender como funciona. Mas para deixar o nosso console mais bonito, vou usar o rich no final das contas.

Assim como fiz com filters, vou criar outro arquivo chamado formatters.py.

import logging
from typing import ClassVar


class ColorFormatter(logging.Formatter):
    COLORS: ClassVar[dict[str, str]] = {
        "DEBUG": "\033[36m",  # Ciano
        "INFO": "\033[32m",  # Verde
        "WARNING": "\033[33m",  # Amarelo
        "ERROR": "\033[31m",  # Vermelho
        "CRITICAL": "\033[41m",  # Fundo vermelho
    }

    RESET = "\033[0m"

    def format(self, record: logging.LogRecord) -> str:
        color = self.COLORS.get(record.levelname, "")
        message = super().format(record)
        return f"{color}{message}{self.RESET}"

Como usar no JSON com `dictConfig`

Agora vou voltar a usar a configuração que estou usando enquanto escrevo o artigo só pra te mostrar o tamanho que está ficando meu JSON e também para você ver como ficaria num cenário real.

Esse é o meu JSON nesse momento:

{
  "version": 1,
  "disable_existing_loggers": false,
  "formatters": {
    "file": {
      "format": "%(levelname)s|%(name)s|%(asctime)s|%(message)s|%(filename)s|%(lineno)d",
      "datefmt": "%Y-%m-%dT%H:%M:%S%z"
    },
    "stdout": {
      "format": "OUT: [%(levelname)s] %(message)s"
    },
    "stderr": {
      "format": "ERR: [%(levelname)s] %(message)s - %(filename)s|%(lineno)d"
    },
    "color": {
      "()": "logging_course.formatters.ColorFormatter",
      "format": "[%(levelname)s] %(message)s"
    }
  },
  "filters": {
    "only_debug_info": {
      "()": "logging_course.filters.MaxLevelFilter",
      "max_level": "INFO"
    }
  },
  "handlers": {
    "file": {
      "class": "logging.handlers.RotatingFileHandler",
      "formatter": "file",
      "filename": "log.log",
      "maxBytes": 5242880,
      "backupCount": 5,
      "encoding": "utf-8"
    },
    "stdout": {
      "class": "logging.StreamHandler",
      "formatter": "color",
      "level": "DEBUG",
      "filters": ["only_debug_info"],
      "stream": "ext://sys.stdout"
    },
    "stderr": {
      "class": "logging.StreamHandler",
      "formatter": "color",
      "level": "WARNING",
      "stream": "ext://sys.stderr"
    }
  },
  "root": {
    "handlers": ["file", "stdout", "stderr"]
  },
  "loggers": {
    "meuapp": {
      "level": "DEBUG"
    }
  }
}

Se você pegou o jeito da coisa, é a mesma ideia que vimos em filters (na verdade é a mesma ideia para quase tudo). Sempre que eu tenho uma classe com interface diferente das classes padrão do dictConfig, preciso informar o caminho completo dessa classe no dicionário (ou onde quer quer estiver sua configuração, JSON no nosso caso). Além disso, tenho que usar () na chave, assim as chaves que vierem a seguir no JSON serão passadas para sua classe para configuração.

Resultado:

[DEBUG] mensagem de log       <- em ciano
[INFO] mensagem de log        <- em verde
[WARNING] mensagem de log     <- em amarelo
[ERROR] mensagem de log       <- em vermelho
[CRITICAL] mensagem de log    <- fundo vermelho

Se quiser deixar isso ainda mais modular depois, pode mover os códigos ANSI pra uma constante global ou até gerar dinamicamente por tema. Mas isso é suficiente por agora, porque nem vamos usar isso, usaremos o rich. Como falei isso umas 30 vezes no texto, vamos ver como fazer isso.

RichHandler - o Logging Handler do rich

rich tem sido extensivamente usado com o Python para aplicações de terminal mais elegantes, coloridas e bonitas. E não é por menos: tem praticamente tudo o que você precisaria em termos de componentes visuais para terminal, incluindo um handler para logging.

Para usar, basta fazer o seguinte na no seu arquivo de configuração JSON ou no dicionário mesmo.

{
  "version": 1,
  "disable_existing_loggers": false,
  "formatters": {
    "stdout": {
      "datefmt": "[%X]"
    }
  },
  "handlers": {
    "stdout": {
      "()": "rich.logging.RichHandler",
      "level": "DEBUG",
      "omit_repeated_times": false,
      "formatter": "stdout"
    }
  },
  "root": {
    "handlers": ["stdout"]
  },
  "loggers": {
    "meuapp": {
      "level": "DEBUG"
    }
  }
}

Só de fazer isso, meu log ficou como mostro na imagem a seguir. Por padrão o RichHandler emit os logs para stdout.

Se quiser, pode manter o rich para o seu debug. E daqui em diante, toda vez que pensar em ver o valor de uma variável ou algo semelhante, use o log. Deixa o print para coisas que realmente precisam de print, como exibir algo par ao usuário mesmo.

JSON log formatter: vamos salvar logs em JSON Lines?

Só pra constar: você também pode criar seu próprio formatter e mudar o formato de saída para o que achar melhor. Vamos fazer isso em JSON porque é um dos formatos mais usados, mas você decide qual usar. A ideia é sempre a mesma.

Na real, em vez do JSON tradicional, vamos usar uma variação chamada JSON Lines (ou NDJSON, Newline Delimited JSON). Nesse formato, cada linha é um objeto JSON independente.

O motivo é simples: eficiência. Quando a gente cria um JSON comum, você precisa guardar tudo num único objeto (ou array). A cada novo log, teria que carregar esse JSON, adicionar o novo item, e depois salvar tudo de novo.

Com JSONL, não. Podemos simplesmente dar um append (a) no final do arquivo, sem precisar mexer em nada que já estava lá.

E o melhor: fazer parse disso é fácil. Basta ler o arquivo linha por linha e interpretar cada uma como um JSON separado.

Até porque, convenhamos: não é todo dia que você vai fazer parse de logs. Mas gravar logs... isso sim, é todo dia.

Também vamos melhorar o nosso setup de leve até chegarmos a uma configuração final pronta.

Melhorando nosso setup geral do logging

Até o momento, temos trabalhado com uma configuração toda solta. O ideal é movermos as partes da nossa configuração para uma função. Então vamos fazer o seguinte (veja nos comentários de código):

# Criei uma arquivo separado apenas para configurações
# src/logging_course/config_logger.py
import json
import logging
from logging.config import dictConfig
from pathlib import Path
from typing import Any

# Caminhos em geral
ROOT_DIR = Path(".")  # Raiz do projeto
LOGS_DIR = ROOT_DIR / "logs"  # Pasta para logs (./logs)
LOG_CONFIG_PATH = ROOT_DIR / "logging.json"  # Arquivo de configuração


def setup(logger_name: str) -> logging.Logger:
    """Configura o logger principal da aplicação."""

    # Se a pasta LOGS_DIR não existir, teremos um erro na aplicação,
    # então verificamos e, se não existir, criamos.
    if not LOGS_DIR.is_dir():
        LOGS_DIR.mkdir(parents=True, exist_ok=True)

    with LOG_CONFIG_PATH.open(encoding="utf8") as file:
        logging_config = json.load(file)

    dictConfig(logging_config)

    # Já estou retornando um logger, mas nem precisaria disso
    return logging.getLogger(logger_name)

A única diferença do que fizemos anteriormente é que agora você tem uma função encapsulando tudo. Além disso, quero jogar os arquivos de log na pasta logs para evitar ficar poluindo a raiz do meu projeto. Se essa pasta não existir, isso vai parar a aplicação logo quando logging for tentar salvar o arquivo de log. Se quiser tirar esse trecho de código da nossa função, não tem problema, basta criar a pasta logs manualmente.

Formatter personalizado: JSONLoggerFormatter

Existem libs prontas para isso, mas como estamos aqui para aprender, vamos criar nosso próprio logger.

# src/logging_course/formatters.py
import json
import logging
from datetime import UTC, datetime
from typing import Any, ClassVar, override


# Essas são as chaves disponíveis no LogRecord
# Podemos incluir qualquer uma dessas chaves no nosso log.
LOG_RECORD_KEYS = [
    "name",
    "msg",
    "args",
    "levelname",
    "levelno",
    "pathname",
    "filename",
    "module",
    "exc_info",
    "exc_text",
    "stack_info",
    "lineno",
    "funcName",
    "created",
    "msecs",
    "relativeCreated",
    "thread",
    "threadName",
    "processName",
    "process",
    "taskName",
]

# Só fiz isso para separar o que é padrão do que é meu mesmo
# message não existe em no LogRecord
LOG_RECORDS_EXTENDED_KEYS = [*LOG_RECORD_KEYS, "message"]


# Nosso logger herda de `logging.Formatter`. Vou configurar tudo dessa super
# classe por dentro do meu __init__, ou seja, não vou receber configurações
# externas.
# A única coisa que adicionei aqui foi `include_keys`, que vamos poder usar para
# ativar ou desativar chaves do nosso log.
class JSONLogFormatter(logging.Formatter):
    def __init__(self, include_keys: list[str] | None = None) -> None:
        super().__init__(
            fmt=None,
            datefmt="%Y-%m-%dT%H:%M:%S%z",
            style="%",
            validate=False,
        )
        # Se você não enviar `include_keys`, todas as chaves serão adicionadas.
        self.include_keys = (
            include_keys if include_keys is not None else LOG_RECORDS_EXTENDED_KEYS
        )

    @override
    def format(self, record: logging.LogRecord) -> str:
        # Crio um dicionário onde obtenho todas as chaves de "include_keys"
        # de dentro do LogRecord (`record`). Inicialmente, os valores são
        # iguais, mas alguns desses valores não podem ser serializados para JSON.
        dict_record: dict[str, Any] = {
            key: getattr(record, key)
            for key in self.include_keys
            if getattr(record, key, None) is not None
            and key in LOG_RECORDS_EXTENDED_KEYS
        }

        if "created" in dict_record:
            # Sobrescrevi o método `formatTime` para retornar um datetime
            # ao invés de `struct_time` que é o padrão. Assim consigo trabalhar
            # com timezone.
            dict_record["created"] = self.formatTime(record)

        if "message" in self.include_keys:
            dict_record["message"] = record.getMessage()

        if "exc_info" in dict_record and record.exc_info:
            # `exc_info` traz informações sobre exceções. Precisamos formatar
            # esse valor para uma string. Por sorte isso existe em `Formatter`.
            dict_record["exc_info"] = self.formatException(record.exc_info)

        if "stack_info" in dict_record and record.stack_info:
            # Aqui também precisamos formatar o valor do stack da exceção para str.
            dict_record["stack_info"] = self.formatStack(record.stack_info)

        # Caso utilize extras ao emitir o log
        # Ex.: logger.warning("Mensagem", extra={"contexto": "qualquer coisa"})
        # A chave "contexto" será adicionada ao log também
        for key, val in vars(record).items():
            if key in LOG_RECORDS_EXTENDED_KEYS:
                # Essas chaves nós tratamos antes
                continue

            # Adicionamos a chave extra ao log
            dict_record[key] = val

        # E pronto, salvamos o log como JSON.
        # Aqui só estamos retornando, quem salva mesmo é RotatingFileHandler.
        return json.dumps(dict_record, default=str)

    @override
    def formatTime(self, record: logging.LogRecord, datefmt: str | None = None) -> str:
        # Como disse nos comentários acima, só estou trocando o timestamp
        # para datetime para ter timezone. Configure como preferir.
        date = datetime.fromtimestamp(record.created, tz=UTC)

        if datefmt:
            return date.strftime(datefmt)

        return date.isoformat()

Não deixe de ler os comentários que deixei nos códigos. Eu estou deixando de escrever texto puro aqui para comentar nas linhas onde as coisas realmente acontece para você entender melhor.

Agora só falta configurarmos o nosso logging.json ou o seu dicionário do dictConfig.

Configuração atual do nosso `logging.json` do `dictConfig`

Agora vamos usar dois handlers que aprendemos antes, o RichHandler para o nosso console e o RotatingFileHandler para o JSONLogFormatter.

Você sabe fazer isso, vamos lá:

{
  "version": 1,
  "disable_existing_loggers": false,
  "formatters": {
    "console": {
      "format": "%(message)s",
      "datefmt": "%H:%M:%S"
    },
    "json": {
      "()": "logging_course.formatters.JSONLogFormatter",
      "include_keys": [
        "created",
        "message",
        "levelname",
        "name",
        "filename",
        "module",
        "exc_info",
        "lineno",
        "threadName",
        "processName",
        "taskName",
        "args"
      ]
    }
  },
  "handlers": {
    "console": {
      "class": "rich.logging.RichHandler",
      "formatter": "console",
      "level": "DEBUG",
      "rich_tracebacks": false,
      "tracebacks_show_locals": false,
      "show_time": true,
      "show_level": true,
      "omit_repeated_times": false,
      "markup": true,
      "enable_link_path": true,
      "show_path": true
    },
    "file": {
      "class": "logging.handlers.RotatingFileHandler",
      "level": "DEBUG",
      "formatter": "json",
      "filename": "logs/log.jsonl",
      "maxBytes": 5242880,
      "backupCount": 5,
      "encoding": "utf-8"
    }
  },
  "root": {
    "handlers": ["file", "console"]
  },
  "loggers": {
    "meuapp": {
      "level": "DEBUG"
    }
  }
}

Pronto, agora temos dois logs prontos para uso em uma tacada só. Sai no seu terminal e vai para o arquivo .jsonl.

Bônus: um parser simples para JSONL

Aqui está como fazer o parse do arquivo .jsonl como exemplo:

def parse_jsonl(path: Path) -> list[dict[str, Any]]:
    with path.open("r", encoding="utf8") as file:
        lines = file.readlines()

    logs: list[dict[str, Any]] = []

    if not lines:
        return logs

    for line in lines:
        logs.append(json.loads(line))

    return logs


if __name__ == "__main__":
    from rich import print as p

    log_file = LOGS_DIR / "log.jsonl"

    for log in parse_jsonl(log_file):
        # This is just an example
        p(log)

Estamos acabando. Vamos ver só mais uma coisa que eu acho que você vai achar interessante.

QueueHandler e QueueListener: log sem travar sua aplicação

Às vezes, o seu logger pode virar um gargalo na aplicação. Isso mesmo. A função que deveria te ajudar a debugar começa a travar tudo. Por quê?

Imagine isso:

logger.info("Processando pedido: %s", pedido)

Parece inocente, mas se esse log for:

Formatado com um formatter mais pesado (ex: JSON complexo)
Escrito em disco (arquivo grande, I/O lento)
Impresso no terminal com renderização colorida (RichHandler)
Enviado para múltiplos handlers ao mesmo tempo
Enviando por e-mail, HTTP, Socket, etc

... então essa linha pode virar um mini-freio toda vez que roda. E se sua app roda centenas ou milhares de logs por segundo (ex: scraping, filas, web, workers), esse tempo se acumula.

A solução: enfileirar o log e deixar outra thread cuidar deles

É exatamente isso que QueueHandler e QueueListener fazem.

Você passa a responsabilidade de processar e gravar o log para outra thread, usando uma Queue (fila).

Assim, sua aplicação:

Só coloca o log na fila (QueueHandler faz isso)
E continua rodando normal, sem esperar
Enquanto isso, outra thread (QueueListener) fica escutando essa fila e processa os logs em segundo plano.

Por que isso funciona tão bem?

Porque queue.Queue() em Python é thread-safe e super leve. Você consegue colocar o log na fila em microssegundos. A thread que escuta a fila (QueueListener) processa os logs no tempo que precisar, totalmente separada da thread principal da sua aplicação.

Exemplo prático com nosso JSON de `dictConfig`

Para implementar isso, vamos adicionar uma nova seção ou entrada no seu dictConfig. Ao configurar um QueueHandler, você também informará quais são os "handlers reais" que o QueueListener (que funcionará em uma thread separada) deve usar para processar as mensagens de log retiradas da fila.

Basicamente:

Definimos um QueueHandler que será o ponto de entrada dos logs na fila.
Dentro da configuração desse QueueHandler no dictConfig (ou em uma seção queue_listeners), você indica os handlers para onde o QueueListener deve enviar os logs.
Então, qualquer logger que você queira que se beneficie do processamento assíncrono, você o associa a este QueueHandler. Por exemplo, você pode mover os handlers que estavam no root logger (ou em qualquer outro logger específico) para serem manipulados pelo seu QueueHandler. No meu caso, vou usar no root logger.

{
  "version": 1,
  "disable_existing_loggers": false,
  "formatters": {
    "console": {
      "format": "%(message)s",
      "datefmt": "%H:%M:%S"
    },
    "json": {
      "()": "logging_course.formatters.JSONLogFormatter",
      "include_keys": [
        "created",
        "message",
        "levelname",
        "name",
        "filename",
        "module",
        "exc_info",
        "lineno",
        "threadName",
        "processName",
        "taskName",
        "args"
      ]
    }
  },
  "handlers": {
    "console": {
      "class": "rich.logging.RichHandler",
      "formatter": "console",
      "level": "DEBUG",
      "rich_tracebacks": false,
      "tracebacks_show_locals": false,
      "show_time": true,
      "show_level": true,
      "omit_repeated_times": false,
      "markup": true,
      "enable_link_path": true,
      "show_path": true
    },
    "file": {
      "class": "logging.handlers.RotatingFileHandler",
      "level": "DEBUG",
      "formatter": "json",
      "filename": "logs/log.jsonl",
      "maxBytes": 5242880,
      "backupCount": 5,
      "encoding": "utf-8"
    },
    "queue": {
      "class": "logging.handlers.QueueHandler",
      "handlers": ["file", "console"],
      "respect_handler_level": true
    }
  },
  "root": {
    "handlers": ["queue"]
  },
  "loggers": {
    "meuapp": {
      "level": "DEBUG"
    }
  }
}

Certo, a configuração está pronta, mas se você executou o código, provavelmente percebeu que os logs pararam de funcionar. Isso acontece porque, embora tenhamos configurado o QueueHandler para colocar os logs na fila, ninguém está lendo essa fila ainda!

Lembra que o nosso objetivo é ter o QueueHandler para enfileirar os logs (tirando o peso da sua aplicação) e, em paralelo, o QueueListener para processar esses logs em outra thread. A configuração do dictConfig que acabamos de ver define o QueueHandler e informa para onde o QueueListener deve enviar os logs.

Agora, precisamos explicitamente iniciar o QueueListener para que ele comece a consumir as mensagens da fila e as encaminhe para os handlers "file" e "console".

Para que o sistema de log baseado em filas realmente funcione, precisamos dar a partida no QueueListener. Lembre-se, o QueueHandler apenas coloca os logs na fila; o QueueListener é quem lê e processa.

Precisamos fazer isso programaticamente, após aplicar a configuração do dictConfig. Geralmente, este código é adicionado logo após a chamada para logging.config.dictConfig() (ou fileConfig()).

Exemplo para iniciar o QueueListener:

import logging
import logging.config
import atexit

# A função getHandlerByName() está disponível a partir do Python 3.12.
queue_handler = logging.getHandlerByName("queue")

if queue_handler is not None:
    # O QueueHandler, quando configurado via dictConfig com "handlers",
    # automaticamente cria e gerencia uma instância de QueueListener.
    # Nós simplesmente precisamos iniciar essa instância.
    queue_handler.listener.start()

    # É crucial registrar uma função para parar o listener quando o programa
    # for encerrado. Isso garante um desligamento limpo da thread do listener.
    atexit.register(queue_handler.listener.stop)

Meu código final e completo

Fizemos muitas coisas ao longo desse artigo, mas temos que finalizar em algum lugar, concorda? Então vou te passar como ficou a minha configuração final com alguns ajustes que fiz. Sinta-se à vontade para usar e modificar como quiser.

Para amarrar tudo, aqui está a versão final da sua função setup no módulo config_logger (na verdade, estou mandando o módulo inteiro, então tem mais do que só setup aí). Mudei ela levemente para incluir a lógica de inicialização e desligamento do QueueListener.

Note que esta função setup agora é apenas para configurar o logger, sem criar ou retornar instâncias de logger. Você precisará usar logging.getLogger('nome') em outras partes da sua aplicação para obter e usar os loggers configurados.

import atexit
import json
import logging
from logging.config import dictConfig
from pathlib import Path
from typing import Any

# Caminhos em geral
ROOT_DIR = Path(".")  # Raiz do projeto
LOGS_DIR = ROOT_DIR / "logs"  # Pasta para logs (./logs)
LOG_CONFIG_PATH = ROOT_DIR / "logging.json"  # Arquivo de configuração


# não preciso mais de `name` como argumento aqui
def setup() -> None:
    """Configura o logger principal da aplicação."""

    # Se a pasta LOGS_DIR não existir, teremos um erro na aplicação,
    # então verificamos e, se não existir, criamos.
    if not LOGS_DIR.is_dir():
        LOGS_DIR.mkdir(parents=True, exist_ok=True)

    with LOG_CONFIG_PATH.open(encoding="utf8") as file:
        logging_config = json.load(file)

    dictConfig(logging_config)

    # Aqui está o que adicionamos para iniciar e finalizar `QueueListener`
    queue_handler = logging.getHandlerByName("queue")
    if queue_handler is not None:
        # pyright não reconheceu os tipos
        queue_handler.listener.start()  # pyright: ignore
        atexit.register(queue_handler.listener.stop)  # pyright: ignore

    # sem retorno


def parse_jsonl(path: Path) -> list[dict[str, Any]]:
    with path.open("r", encoding="utf8") as file:
        lines = file.readlines()

    logs: list[dict[str, Any]] = []

    if not lines:
        return logs

    for line in lines:
        logs.append(json.loads(line))

    return logs


if __name__ == "__main__":
    from rich import print as p

    log_file = LOGS_DIR / "log.jsonl"

    for log in parse_jsonl(log_file):
        # This is just an example
        p(log)

O nosso JSON que funciona como configuração principal da dictConfig ficou dessa forma (não devo ter mudado nada nele):

{
  "version": 1,
  "disable_existing_loggers": false,
  "formatters": {
    "console": {
      "format": "%(message)s",
      "datefmt": "%H:%M:%S"
    },
    "json": {
      "()": "logging_course.formatters.JSONLogFormatter",
      "include_keys": [
        "created",
        "message",
        "levelname",
        "name",
        "filename",
        "module",
        "exc_info",
        "lineno",
        "threadName",
        "processName",
        "taskName",
        "args"
      ]
    }
  },
  "handlers": {
    "console": {
      "class": "rich.logging.RichHandler",
      "formatter": "console",
      "level": "DEBUG",
      "rich_tracebacks": false,
      "tracebacks_show_locals": false,
      "show_time": true,
      "show_level": true,
      "omit_repeated_times": false,
      "markup": true,
      "enable_link_path": true,
      "show_path": true
    },
    "file": {
      "class": "logging.handlers.RotatingFileHandler",
      "level": "DEBUG",
      "formatter": "json",
      "filename": "logs/log.jsonl",
      "maxBytes": 5242880,
      "backupCount": 5,
      "encoding": "utf-8"
    },
    "queue": {
      "class": "logging.handlers.QueueHandler",
      "handlers": ["file", "console"],
      "respect_handler_level": true
    }
  },
  "root": {
    "handlers": ["queue"]
  },
  "loggers": {
    "meuapp": {
      "level": "DEBUG"
    }
  }
}

Em qualquer parte da aplicação, eu estava testando as nossas configurações com o seguinte código:

import logging

from logging_course import config_logger

if __name__ == "__main__":
    config_logger.setup()

    logger = logging.getLogger("meuapp")

    logger.debug("mensagem")
    logger.debug("Olá %s %s", "Luiz", "Otávio", extra={"contexto": "qualquer coisa"})
    logger.info("mensagem")
    logger.info("Olá %s %s", "Luiz", "Otávio", extra={"contexto": "qualquer coisa"})
    logger.warning("mensagem")
    logger.warning("Olá %s %s", "Luiz", "Otávio", extra={"contexto": "qualquer coisa"})
    logger.error("mensagem")
    logger.error("Olá %s %s", "Luiz", "Otávio", extra={"contexto": "qualquer coisa"})
    logger.critical("mensagem")
    logger.critical("Olá %s %s", "Luiz", "Otávio", extra={"contexto": "qualquer coisa"})

    try:
        print(1 / 0)
    except ZeroDivisionError:
        logger.exception("Deu ruim")
        logger.exception(
            "Olá %s %s", "Luiz", "Otávio", extra={"contexto": "qualquer coisa"}
        )
        logger.exception("Deu ruim", stack_info=True)
        logger.exception(
            "Olá %s %s",
            "Luiz",
            "Otávio",
            extra={"contexto": "qualquer coisa"},
            stack_info=True,
        )

    print("Testando blocking")
    print("Esses prints são independentes do log.")
    print("Podem aparecer aleatóriamente no topo, meio ou final dos logs.")

Boas Práticas no Logging do Python: e agora? - Aula 13

Parabéns! Você chegou ao final do nosso curso (e do texto, se estiver apenas lendo). A gente poderia continuar falando sobre logging por horas, mas agora você já deixou o print() pra trás, entendeu Handlers, Formatters, Filtros, dictConfig, JSON e até logging assíncrono com QueueHandler.

Você tem um poder enorme nas mãos. Mas agora vem as perguntas mais importantes: Onde e como usar esse poder? O que vale a pena registrar? Como escrever uma mensagem de log que ainda faça sentido daqui a 6 meses, às 3 da manhã, quando um bug crítico estourar em produção?

Nesta última aula, o foco muda um pouco. Vamos falar menos sobre como configurar e mais sobre por que logar, o que logar e quando usar cada nível. Vamos explorar as boas práticas que separam um log amador de um log profissional, e que podem realmente salvar sua pele quando tudo estiver pegando fogo.

Ah, e vale lembrar: isso aqui não tem fim. Sempre tem mais pra aprender. Erros em logs acontecem até nas maiores empresas do mundo, então continue estudando, melhorando, revisando seus logs... e evitando que eles virem uma armadilha.

Para Quem Você Está Escrevendo o Log?

Antes de mais nada: log não é só pra você, desenvolvedor. Na verdade, o que deve ser registrado em log geralmente não é decidido apenas pelos devs. Em ambientes profissionais, outros setores também dependem desses dados.

Claro, como dev, você provavelmente vai usar debug, info, warning,error, critical e exception para entender o comportamento do seu código. Mas a empresa como um todo precisa de muito mais:

O usuário criou uma conta
O usuário fez login
Visualizou o produto X
Comprou o produto Y
Pesquisou por "banana orgânica"

Tudo isso pode parecer irrelevante para debugging técnico, mas para outras áreas, esses logs são ouro em forma de texto. Gente de marketing, produto, segurança, auditoria... todos querem (e precisam) ver esses eventos.

Então, antes de sair logando tudo no debug, entenda o propósito do log. Você está logando para debug ou para outro setor? Se é para outro setor, quais dados eles precisam? Esses dados podem ser salvos? São sensíveis?

Veja alguns exemplos genéricos:

Logs para Desenvolvedores (Você do Futuro): Foco em debugging. Informações que ajudam a entender o fluxo da aplicação, o estado de variáveis e a causa de um bug (não é só debug, todos os níveis de log podem ser relevantes aqui).
Logs para SysAdmins / SRE / DevOps (Monitoramento): Foco em saúde do sistema. Logs sobre falhas, lentidão, uso de recursos, quedas de serviço, etc.
Logs para o Negócio / Auditoria (Análise): Foco em rastrear ações importantes do ponto de vista do negócio. Exemplo: "Usuário X comprou produto Y", "Relatório Z foi gerado" (claro, você precisa se comunicar com outros setores para saber o que logar).
Logs para fins legais? Se um usuário da sua aplicação fizer algo ilegal, talvez a justiça queira saber o que aconteceu. Aqui entra outro tipo de responsabilidade: retenção de logs, dados sensíveis, LGPD, etc. Consulte um advogado (ou o jurídico da empresa) para saber o que pode ou não ser armazenado.

Decifrando os Níveis de Severidade na Prática

Agora sim: vamos entender quando usar cada nível de log na prática.

Abaixo você encontra a descrição de cada nível com exemplos concretos, tanto de situações quanto de código.

`DEBUG`: "Esse é nosso (dos devs)"

Quando usar: Para diagnóstico detalhado durante o desenvolvimento ou debugging intenso.
O que logar: Variáveis internas, payloads de API, queries SQL, entrada e saída de funções complexas.
Regra: Geralmente desativado em produção para evitar excesso de ruído (e vazamento de dados sensíveis da aplicação).

# Cuidado com isso, payload pode conter dados sensíveis da aplicação
# e do usuário
logger.debug("Iniciando função de login com payload: %s", payload)
# Cuidado novamente (nem preciso falar de novo né?)
logger.debug("Consulta SQL gerada: %s", query)

`INFO`: Aconteceu algo certo

Quando usar: Para registrar eventos normais e esperados no fluxo da aplicação.
O que logar: Login de usuário, criação de conta, execução bem-sucedida de uma tarefa.

# Sem senhas, pelo amor de Deus
logger.info("Usuário %s logou com sucesso", username)
logger.info("Relatório gerado e enviado por email")

`WARNING`: Atenção, algo inesperado aconteceu

Quando usar: Quando algo não saiu como o esperado, mas a aplicação conseguiu se recuperar.
O que logar: Funcionalidades obsoletas, API lenta, falha com fallback, tentativa de reconexão, muitas tentativas de login, etc...

logger.warning("API externa demorou %d segundos para responder", elapsed)
logger.warning("Configuração 'X' está obsoleta. Use 'Y' no lugar.")

`ERROR`: Uma operação falhou

Quando usar: Quando uma tarefa específica não pôde ser concluída, mas a aplicação continua rodando.
O que logar: Falha de validação, erro ao salvar no banco, exceção tratada que impediu o sucesso da operação, etc.

logger.error("Erro ao salvar usuário no banco: %s", user_id)
logger.error("Falha ao processar pagamento: %s", str(error))

`CRITICAL`: O navio está afundando!

Quando usar: Para falhas graves que impedem o funcionamento da aplicação.
O que logar: Perda de conexão com o banco após várias tentativas, falha na inicialização de componente essencial, falha na rede interna, etc.

logger.critical("Banco de dados inacessível após 5 tentativas. Encerrando aplicação.")
logger.critical("Arquivo de configuração principal está corrompido.")

Menção honrosa: `logger.exception()`

Quando usar: Sempre que você estiver dentro de um bloco try...except é interessante logar a exceção na maioria dos casos.
Vantagem: Além de logar como error, ele inclui automaticamente o traceback. Isso é ouro puro para debugging.

try:
    resultado = processar_pagamento()
except Exception as e:
    logger.exception("Erro inesperado ao processar pagamento")

Com esses exemplos em mente, você já consegue diferenciar claramente o papel de cada nível de severidade e aplicar isso com consciência. O importante é manter consistência, clareza e foco em quem vai ler o log depois, muitas vezes, esse alguém vai ser você mesmo (só que com sono e pressa).

Além disso, como o que aprendemos sobre loggers, handlers e filters, você conseguirá separar bem os logs por pacote, módulo, por setor da empresa, ou como preferir. Também conseguirá filtrar dados desnecessários em logs específicos.

As Regras de Ouro de uma Boa Mensagem de Log

Depois de tudo que aprendemos sobre configuração e níveis de log, chegou a hora da pergunta mais importante:

Como escrever uma mensagem de log que realmente ajuda?

Aqui vão 3 regras de ouro, simples, mas poderosas, que separam logs descartáveis de logs profissionais e confiáveis.

Regra 1: Escreva logs para máquinas também, não só para humanos

Sim, logs precisam ser legíveis. Mas eles também devem ser estruturados e processáveis por ferramentas de observabilidade, buscas e alertas.

Evite logs "misteriosos" e difíceis de analisar com código.

#🚫 Ruim:
logger.error("Erro no usuário 123")

# ✅ Bom:
logger.error("Falha na atualização do perfil", extra={
    "user_id": 123,
    "reason": "email_invalido"
})

Com logs estruturados (em JSON, como fizemos), você pode filtrar todos os erros por reason=email_invalido, ou agrupar por user_id. Isso é impossível com strings soltas e mal formatadas.

Regra 2: Contexto é rei

A mensagem "Falhou" pode ser verdade, mas não ajuda em nada.

Um bom log responde: Quem? O quê? Onde? Quando? Por quê?

Inclua IDs relevantes (de usuário, pedido, transação, etc). Quanto mais contexto você der, mais rápido será o diagnóstico, inclusive por outras pessoas do time (ou você no futuro, com pressa e sem paciência). Evite também colocar coisas desnecessárias no log (falo disso adiante).

# 🚫 Ruim:
logger.error("Pagamento não foi processado")

# ✅ Bom:
logger.error("Erro ao processar pagamento", extra={
    "user_id": 42,
    "order_id": 101,
    "gateway": "Stripe",
    "error_code": "card_declined"
})

Regra 3: NUNCA logue informações sensíveis

Isso é mais do que uma boa prática: é uma questão legal e de segurança.

O que nunca deve aparecer em logs:

Senhas (óbvio, né?)
Tokens de autenticação ou sessão
Chaves de API
Números de cartão de crédito
Documentos como CPF, RG, etc.
Endereços físicos de clientes, colaboradores, fornecedores, etc.
Dados médicos ou sensíveis (LGPD/GDPR)

Dica técnica: Se você precisa logar objetos que podem conter dados sensíveis (ex: um User ou um Request), crie uma função de serialização segura, ou use um Filter para limpar ou mascarar os dados antes de enviar ao log.

Regra 4: Contexto é bom… até virar poluição

Sim, na Regra 2 eu disse que contexto é rei. Mas cuidado pra não transformar o seu log num romance de 800 páginas com final inconclusivo.

Logar dados demais é tão ruim quanto logar de menos.

Vai deixar os arquivos gigantes
Vai dificultar buscas e análise
Pode até esconder o que realmente importa
Vai ficar caro
Tem mais coisa ruim que não lembrei...

Ruído esconde o sinal.

Veja um exemplo de poluição:

# 🚫 Ruim:
logger.debug("Resposta completa da API: %s", response.text)  # 1000 linhas de HTML
logger.info("Usuário fez login", extra={
    "user_id": 1,
    "nome": "Fulano",
    "email": "fulano@email.com", # dado sensível
    "cpf": "123.456.789-00", # dado sensível
    "endereco": "Rua tal, nº tal, bairro tal", # dado sensível
    "navegador": "Chrome 126",
    "sistema": "macOS",
    "resolução": "1920x1080",
    "timestamp": "2025-07-10T15:34:21Z"
})

Melhor seria algo como:

# ✅ melhor - é o mesmo log, mas eu consigo usar o ID do usuário para fazer
# buscas internas no sistema.
logger.info("Login realizado com sucesso", extra={
    "user_id": 1 # Com o ID do usuário você consegue buscar outros dados
})

Regra prática: Logue apenas o que alguém precisa saber para agir. Se o dado não ajuda a entender, resolver ou monitorar o problema, talvez ele não precise estar ali. Geralmente, IDs que identificam algo são suficientes para fazer uma busca interna no sistema sem expor dados sensíveis em logs.

Lembre-se que quando você não precisa de logs, eles são "lixo" e até inconvenientes. Em algum momento alguém pode esquecer algo e vazar logs da sua aplicação. Se isso acontecer, torça muito para não ter nenhum dado sensível no meio dos dados vazados.

Concluindo

Se você chegou até aqui, parabéns. De verdade.

Você saiu do print() e agora tem um arsenal completo de logging profissional nas mãos: Handlers, Formatters, Filters, JSON, dictConfig, logs assíncronos com QueueHandler, e, mais importante, boas práticas de uso.

Você entendeu que logging não é só sobre escrever mensagens no console. É sobre observabilidade, diagnóstico rápido, comunicação entre times, segurança e até compliance legal. Ou seja: logging bem feito salva seu código, sua sanidade e, às vezes, até o faturamento da empresa.

E agora, o que fazer com esse conhecimento?

Use. Refatore seus projetos. Melhore os logs do seu time. Mostre esse curso pra alguém que ainda vive no print().

E quando for criar algo novo… lembra disso: um bom log não é ruído. É música pros ouvidos de quem tá tentando resolver um bug às 3 da manhã.

Valeu demais por acompanhar até aqui! Se você curtiu, compartilha, vai lá no vídeo e comenta, salva, manda pra galera. E se quiser aprender mais Python moderno, CLI, automações, ou IA aplicada ao mundo real, dá uma olhada nas outras playlists do canal ou nos cursos completos.

Nos vemos nos próximos vídeos ou textos.

Abraço!

Se quiser, esse texto está em markdown e pode ser baixado aqui. Você também rolou bastante essa página né? Volte para o topo ou simplesmente vá para nossa página inicial.

Escopo e Namespace em Python

Sat, 26 Jul 2025 00:00:00 GMT

Em Python, escopo é o contexto onde um nome pode ser usado. Ele define a região do código, o tempo de vida e os limites de acesso desses nomes.

Durante a execução do seu programa, um ou mais escopos estarão ativos. Isso determina quais nomes estão visíveis naquele momento e quais resultarão em um NameError se você tentar acessá-los.

Os nomes definidos dentro de um escopo são armazenados em um objeto chamado namespace. Ele atua como um dicionário, onde a chave é o nome (ou rótulo) de um objeto e o valor é o objeto referenciado.

Neste artigo, vamos explorar não apenas o que são escopo e namespace, mas também vários outros temas relacionados. Ao final, você terá aprendido:

O que é escopo
O que é namespace
Os tipos de escopo: Local, Enclosing, Global e Built-in
A regra LEGB: a ordem de busca por nomes
Como usar as palavras-chave global e nonlocal de forma consciente
Como usar funções como globals(), locals(), vars() e dir() para inspecionar e acessar namespaces

Em vídeo

Eu falo sobre escopo e namespace no Python (tudo o que falo neste artigo) em dois vídeos no meu canal do Youtube. Caso prefira, assista abaixo:

Vídeo 1 - Escopo e Namespace em Python
Vídeo 2 - Entenda a regra LEGB e Enclosing no Python

O que é escopo?

Quando você cria um nome em seu código, como uma variável, uma função ou uma classe, ele só pode ser usado dentro de um certo contexto. Esse contexto é o que chamamos de escopo.

Em termos práticos, escopo é a região do seu código onde um nome está diretamente acessível. Ou seja, é onde o Python vai "procurar" por aquele nome quando você tenta utilizá-lo. Se você conseguir acessar o nome solicitado, falamos que ele está no escopo, do contrário ele estará fora do escopo.

Nota:: sempre que eu usar a palavra "nome", estou me referindo a identificadores como variáveis, classes, funções, módulos ou qualquer coisa que pode receber um nome em Python.

Vamos para um exemplo (sempre leia os comentários de código):

x = 10  # Variável 'x' no escopo global

def mostrar():
    print(x)  # Acessa 'x' do escopo global

mostrar()

Nesse código, a variável x foi definida no escopo global, fora de qualquer função. Quando print(x) é chamado dentro da função mostrar(), o Python primeiramente busca x no escopo local da função. Como não o encontra lá, ele "sobe" para o escopo global, onde x está disponível.

Mas onde o Python guarda esse nome x com o valor 10?

É nesse ponto que os namespaces entram em cena: todo escopo possui seu próprio "espaço de nomes", um local onde os nomes e seus respectivos objetos são armazenados. Vamos explorar isso em detalhes a seguir.

O que é namespace?

Um namespace é, essencialmente, uma estrutura que mapeia nomes a objetos. Você pode pensar nele como um dicionário onde cada chave é o nome que você define (como o nome de uma variável, função ou classe) e o valor é o objeto correspondente no seu código.

Sempre que você cria um nome em Python, essa associação é guardada dentro de um namespace. Algumas das formas mais comuns de criar nomes incluem:

Atribuição: variavel = valor
Importação: import modulo ou from modulo import objeto
Definição de funções: def minha_funcao(): ...
Argumentos de funções: def outra_funcao(arg1, arg2): ...
Definição de classes: class MinhaClasse: ...

Nota: existem diferenças entre operações de atribuição (criar ou modificar um valor) e operações de acesso (apenas ler um valor). Vamos falar sobre isso nesse artigo na seção "global e nonlocal - alterando nomes fora do escopo".

Todos esses exemplos resultam na criação de nomes dentro do namespace ativo no momento da sua definição.

Cada namespace está diretamente ligado a um escopo, que determina onde e quando aquele nome estará disponível durante a execução do seu código.

Embora você possa inspecionar namespaces usando funções como globals() e locals() (que retornam representações em dicionário), isso é mais comum para introspecção de código ou fins didáticos do que para o uso diário.

Existem diferentes tipos de namespaces em Python, cada um com sua finalidade:

Global: Cada módulo Python possui um namespace global, que armazena os nomes definidos diretamente na sua raiz, fora de funções ou classes.
Local: Cada vez que uma função é chamada, um namespace local é criado para ela. Ele existe apenas enquanto a função está em execução e contém as variáveis e argumentos definidos dentro dela.
Built-in: Este namespace contém os nomes de todas as funções e exceções nativas do Python, como print(), len(), str(), etc. Ele é carregado automaticamente.
Enclosing (Não-local): Quando uma função é definida dentro de outra, a função interna pode acessar os nomes do namespace da função externa. Este atua como um escopo "intermediário" entre o local e o global.
Classes: O corpo de uma classe também forma seu próprio namespace, onde os atributos e métodos da classe são definidos. É por isso que você acessa membros da classe usando a notação de ponto (objeto.atributo).

É importante notar que os namespaces de funções (Local e Enclosing) são criados dinamicamente no momento da execução. Quando uma função é chamada, o interpretador Python gera um Frame de Execução (ou Stack Frame) que encapsula as variáveis locais, parâmetros e outras informações necessárias para aquela chamada específica. A função locals() pode ser usada dentro de uma função para acessar seu namespace local.

Uma característica fundamental é que todos os namespaces são independentes entre si. Por exemplo, você pode ter uma função chamada processar() em dois módulos diferentes (modulo1.py e modulo2.py). Não haverá conflito, pois cada uma reside em seu próprio namespace. Para acessá-las, basta prefixar com o nome do módulo: modulo1.processar() e modulo2.processar().

`globals()` e `locals()` para inspeção de namespaces

As funções globals() e locals() são ferramentas valiosas para inspecionar namespaces em tempo de execução:

globals(): Retorna um dicionário que representa o namespace global do módulo atual. Isso inclui todos os nomes definidos na raiz do arquivo.
locals(): Retorna um dicionário com os nomes definidos no escopo local onde a função está sendo executada. Importante: ela só inclui nomes que já foram definidos antes da sua chamada, então geralmente é melhor chamá-la no final do bloco.

Vejamos um exemplo prático:

# Escopo global

def show_namespace() -> None:
    # Escopo local
    module_namespace = globals()
    print("Conteúdo de globals():", module_namespace)

    # Note que 'function_namespace' não aparecerá no locals() se chamado antes dela
    function_namespace = locals()
    print("Conteúdo de locals():", function_namespace)


if __name__ == "__main__":
    show_namespace()

A saída de globals() será algo parecido com:

{
    '__name__': '__main__',
    '__doc__': None,
    # ... outras chaves padrão do módulo
    '__builtins__': <module 'builtins' (built-in)>,
    'show_namespace': <function show_namespace at 0x...> # Nossa função
}

Já a saída de locals() mostrará:

{
    'module_namespace': {...} # O dicionário retornado por globals()
}

Alguns pontos a destacar nessa saída:

__name__: Indica o nome do módulo. Se for o script principal, será __main__.
__builtins__: Referência ao namespace com as funções nativas do Python.
show_namespace: O nome da nossa função, definida no escopo global.

`vars()` e `dir()` - Outras formas de inspecionar

Além de globals() e locals(), vars() e dir() também permitem inspecionar nomes, mas com algumas diferenças importantes:

vars(): Retorna o atributo __dict__ de um objeto, que é onde seus atributos são armazenados. Se chamada sem argumentos, vars() se comporta exatamente como locals(), retornando o namespace local.
dir(): Sem argumentos, dir() lista todos os nomes disponíveis no escopo atual. Com um objeto como argumento, tenta listar todos os nomes acessíveis nele (como métodos e atributos). Note que dir() retorna apenas os nomes, não os objetos ou seus valores.

Vamos ver com um exemplo:

def ver_namespace_local():
    var_local = "variável local"

    print("\nDENTRO DA FUNÇÃO (ESCOPO LOCAL)")
    print("Saída de vars():", vars())
    print("Saída de dir():", dir())


print("FORA DA FUNÇÃO (ESCOPO GLOBAL)")
print("Saída de vars():", vars())
print("Saída de dir():", dir())

ver_namespace_local()

Saída de exemplo:

# FORA DA FUNÇÃO (ESCOPO GLOBAL)
# Saída de vars():
{
    # ... omitidos outros resultados globais
    'ver_namespace_local': <function ver_namespace_local at 0x...>
}
# Saída de dir():
[
    '__annotations__', '__builtins__', '__cached__', '__doc__',
    '__file__', '__loader__', '__name__', '__package__', '__spec__',
    'ver_namespace_local' # Nossa função global
]

# DENTRO DA FUNÇÃO (ESCOPO LOCAL)
# Saída de vars():
{
    'var_local': 'variável local'
}
# Saída de dir():
['var_local']

Como pode ver, quando usadas sem argumentos, vars() e dir() se assemelham a locals() e globals() no que diz respeito ao escopo atual. A grande diferença é que vars() e dir() são mais versáteis, pois podem receber um objeto como argumento, permitindo inspecionar namespaces de módulos importados, instâncias de classe e outros objetos.

Regra LEGB - Local, Enclosing, Global e Built-In

Em Python, é bem comum ter um escopo dentro do outro, pense em funções dentro de módulos, ou até mesmo funções aninhadas dentro de outras funções.

Quando isso acontece e você tenta acessar um nome (como uma variável ou função), o interpretador precisa de uma ordem clara para encontrá-lo, dependendo do ponto em que você está no código.

Essa ordem é definida pela regra LEGB. Sempre que você referencia um nome, seja para leitura, escrita ou execução (tipo x ou print()), o Python o busca sequencialmente, do escopo mais interno para o mais externo:

Local (L): Primeiro, o Python procura no escopo da função atual onde o nome está sendo referenciado. Este é o ambiente mais imediato.
Enclosing (E) / Não-Local: Se o nome não for encontrado localmente, a busca avança para o escopo das funções que envolvem a função atual (se houver). Pense nisso como o escopo "da função de fora".
Global (G): Caso o nome ainda não seja encontrado, o Python então procura no escopo do módulo atual. Este é o nível superior do seu arquivo Python.
Built-in (B): Por último, a busca chega ao escopo built-in, que contém todos os nomes nativos do Python, como funções (len(), print()) e exceções (NameError).

Se o nome não for encontrado em nenhum desses escopos, o Python levanta uma exceção NameError, indicando que o nome não foi definido ou não está acessível no contexto atual.

Para visualizar como esses escopos se aninham, imagine a seguinte representação:

 ┌─────────────────────┐
 │ ┌───────────────┐   │
 │ │ ┌─────────┐   │   │
 │ │ │ ┌───┐   │   │   │
 │ │ │ │ L→│ → │ → │ → │ # Local (L): Onde você está agora, o mais interno
 │ │ │ └───┘   │   │   │
 │ │ │       E→│ → │ → │ # Enclosing (E): A função que envolve a sua função
 │ │ └─────────┘   │   │
 │ │             G→│ → │ # Global (G): O módulo inteiro do seu arquivo
 │ └───────────────┘   │
 │                  B→✘│ # Built-in (B): Mais externo, tudo do Python
 └─────────────────────┘

Se preferir, preparei uma imagem também para te ajudar a entender melhor.

A seguir, vamos ver exemplos de código para tornar cada um desses escopos cristalino.

A regra LEGB em ação

Para entender a regra LEGB na prática, vamos usar um código simples e observar como o Python busca os nomes em cada escopo. Usei bastante os comentátios do código para detalhar melhor o que está acontecendo.

# Escopo do módulo: Global (G)
var_global = "Estou no escopo global!"

def funcao_externa() -> None:
    # Escopo da função: Local (L) para esta função
    var_local = "Estou no escopo local!"

    # Busca de 'var_local':
    # O Python encontra 'var_local' no escopo Local (L).
    print(var_local)

    # Busca de 'var_global':
    # Não encontra 'var_global' no Local (L), então busca no Global (G).
    print(var_global)

    # Busca de 'print':
    # Não encontra 'print' em L ou G, então busca no Built-in (B).
    print(print) # Imprime a representação da própria função print


if __name__ == "__main__":
    funcao_externa()

Analisando o fluxo de busca de nomes nesse exemplo, o Python segue a regra LEGB (sempre do mais interno ao mais externo):

var_local: Encontrado diretamente no escopo Local da funcao_externa. Trajeto: L.
var_global: Não encontrado em L, a busca sobe para o escopo Global. Trajeto: L → G.
print: Não encontrado em L nem em G, a busca atinge o escopo Built-in. Trajeto: L → G → B.

É fundamental entender que essa busca é sempre unidirecional: de dentro para fora. Escopos mais internos conseguem "enxergar" os nomes definidos nos escopos mais externos (que os contêm), mas o contrário não é verdadeiro.

Veja um exemplo clássico de NameError que prova isso:

def funcao_interna():
    mensagem = "Olá do escopo local!"

# Erro! 'mensagem' só existe dentro de 'funcao_interna'
print(mensagem)
# Saída esperada: NameError: name 'mensagem' is not defined

A mensagem de erro NameError: name 'mensagem' is not defined ocorre porque, no escopo global, o Python não consegue "descer" para o escopo local de funcao_interna para encontrar mensagem.

Em resumo: a regra LEGB é uma escada de subida. Você só vê os andares acima ou o seu próprio. Nunca consegue ver o que está nos andares abaixo do seu.

Keywords não seguem a LEGB!

É importante diferenciar nomes de keywords (palavras-chave). Termos como def, if, for, while, return, True, False, None e import são partes da gramática do Python, não nomes.

Por serem palavras reservadas, elas não pertencem a nenhum namespace e, consequentemente, não seguem a regra LEGB. Tentar usá-las como variáveis resultará em um erro de sintaxe (SyntaxError) no momento da análise do código, antes mesmo da execução:

# Isso vai causar um SyntaxError!
# Esse código nem chega a rodar
def = 10

Se quiser ver a lista completa de palavras-chave reservadas, execute o comando abaixo no seu terminal Python:

python -c "help('keywords')"

Isso mostrará a lista das keywords do Python, como False, True, None, and, as, assert, break, class, etc. (Existem também as soft keywords, mas isso fica para outra conversa).

Enclosing - entenda o escopo aninhado

Enquanto os escopos Global, Local e Built-in costumam ser mais intuitivos, o escopo Enclosing gera mais dúvidas porque ele só aparece em um cenário específico: quando temos funções aninhadas, ou seja, uma função definida dentro de outra. Vamos focar nele agora.

Considere este código:

def funcao_externa():
    # 'var_enclosing' é local para 'funcao_externa'
    # e Enclosing para 'funcao_interna'
    var_enclosing = "Eu sou do escopo enclosing!"

    def funcao_interna():
        # 'var_local' está no escopo Local de 'funcao_interna'
        var_local = "Eu sou do escopo local!"

        # Acessando 'var_local' (L) e 'var_enclosing' (E)
        print(var_local, var_enclosing)

    # Chamamos a função interna para executá-la
    funcao_interna()

funcao_externa()
# Saída esperada: Eu sou do escopo local! Eu sou do escopo enclosing!

Como você pode ver na saída, a funcao_interna() consegue acessar tanto var_local (que está em seu escopo Local) quanto var_enclosing (que está no escopo Enclosing, da funcao_externa). Isso acontece exatamente por causa da regra LEGB: o Python busca os nomes de dentro para fora, encontrando var_enclosing no nível acima.

Por outro lado, a funcao_externa() não tem acesso direto a var_local, pois var_local reside em um escopo mais interno que o dela. Da mesma forma, o escopo global não consegue acessar nenhuma das variáveis definidas dentro de funcao_externa ou funcao_interna.

Call stack e o tempo de vida dos escopos

A razão para esse comportamento reside em como o Python gerencia a execução de funções utilizando a call stack (pilha de chamadas).

Sempre que uma função é chamada, o Python cria um frame de execução (ou stack frame) para ela. Esse frame é empilhado no topo da call stack, que funciona no esquema LIFO (Last-In, First-Out: o último que entra é o primeiro que sai). Apenas o frame no topo da pilha está ativo. Quando a função termina sua execução, seu frame é descartado da pilha, e o Python retorna o controle para o frame anterior. É por isso que o escopo local de uma função só "existe" enquanto ela está em execução.

A imagem acima ilustra a call stack em ação. O ícone do Python indica a posição atual do interpretador. As setas vermelhas (--->) representam o fluxo de execução e a criação/remoção de frames na pilha. As setas amarelas (↓) mostram a direção de busca de nomes de acordo com a regra LEGB (do escopo mais interno para o mais externo).

Observe o fluxo na imagem:

A execução inicia no mod.py (escopo Global).
Ao chamar funcao_externa(), um novo frame é empilhado. O interpretador se move para dentro dela.
Dentro de funcao_externa(), ao chamar funcao_interna(), outro frame é empilhado, e o interpretador se move para lá.
Quando funcao_interna() termina, seu frame é desempilhado, e o controle retorna para funcao_externa().
Finalmente, funcao_externa() termina, seu frame é desempilhado, e a execução retorna ao mod.py (escopo global), concluindo o processo.

Esse mecanismo é fundamental para a organização e o isolamento do código:

Você consegue acessar nomes definidos em escopos mais externos (Globais, Enclosing) a partir de dentro de uma função.
Mas não consegue acessar nomes definidos dentro de funções estando fora delas, porque o escopo local de uma função deixa de existir (é descartado) assim que ela termina de executar.

Para um aprofundamento sobre a call stack e funções, especialmente em cenários como recursão, recomendo este material:

Funções recursivas com Python

Agora que entendemos o Enclosing e o que acontece por baixo dos panos, podemos continuar.

global e nonlocal - Alterando nomes fora do escopo atual

Nas seções anteriores, focamos em como os nomes são acessados (lidos) de um escopo em outro, um processo que tende a ser mais direto.

No entanto, a tentativa de alterar um nome que não foi definido no escopo atual gera uma ambiguidade para o interpretador. Como ele saberia se você quer criar um novo nome local (com o mesmo rótulo) ou modificar o nome existente em um escopo externo? Essa é a questão.

Essa ambiguidade surge justamente pela flexibilidade que o Python oferece: a capacidade de ter nomes iguais em escopos diferentes sem que um afete o outro, a menos que você explicitamente peça.

Mas... antes de mergulharmos nas soluções, uma pausa para as boas práticas.

Devo alterar nomes fora de seu escopo imediato?

A principal função do escopo e do namespace é proteger nomes de alterações acidentais e garantir o isolamento do código. Fazer alterações intencionais em nomes que residem fora do escopo imediato vai, em certa medida, contra essa ideia central.

Vou listar alguns problemas que essa prática pode gerar (e a lista é bem maior):

Dificulta o Debug: Rastrear a origem de um bug se torna um pesadelo quando variáveis são alteradas de forma "mágica" em diferentes partes do código.
Dificulta Testes: Funções que dependem ou alteram o estado global são mais complexas de testar isoladamente, exigindo um setup e cleanup maiores.
Reduz a Legibilidade e Manutenção: O código fica menos intuitivo, exigindo que o leitor "pule" entre escopos para entender o fluxo de dados.
Aumenta o Acoplamento: Módulos e funções se tornam mais interdependentes, tornando o sistema mais rígido e difícil de refatorar.
Problemas em Concorrência: Em ambientes multi-thread ou assíncronos, a alteração de estado global pode levar a race conditions e bugs extremamente difíceis de diagnosticar.
Contraria Paradigmas Comuns: Vai contra princípios de paradigmas como programação funcional (que preza imutabilidade) e orientação a objetos (que encapsula estado).

Se você se encontrar na situação de precisar alterar o valor de uma variável fora do seu escopo imediato, pare e reavalie a sua solução. Quase sempre há uma forma mais elegante e segura de resolver o problema, como passar os valores via argumentos ou retornar novos valores.

Ok, com essa ressalva importante em mente, agora sim vamos entender como global e nonlocal funcionam para alterar variáveis fora do seu escopo local.

`global` - alterando nomes no escopo global

Vamos analisar o comportamento padrão quando tentamos alterar uma variável global dentro de uma função. Acompanhe o código e o erro que ele gera:

# Escopo global (G)
variavel = "global"

def funcao():
    # Tentativa de usar `variavel` (G)
    print(variavel) # <-- ISSO VAI GERAR O ERRO

    # Criei um novo nome `variavel` no escopo LOCAL (L)
    # Isso fez o nome `variavel` deixar de existir no print acima
    variavel = "local" # <-- ESSE É O MOTIVO DO ERRO

    # Agora, estamos tentando usar a `variavel` LOCAL
    print(variavel)

funcao() # <-- O interpretador não passa daqui
print(variavel)
# A `variavel` global original permanece inalterada

Ao executar funcao(), você receberá um UnboundLocalError:

UnboundLocalError: cannot access local variable 'variavel'
where it is not associated with a value

O interpretador Python é inteligente: ao ver a linha variavel = "local" dentro da função, ele assume que variavel será uma variável local para funcao(). Portanto, quando print(variavel) é chamado antes dessa atribuição local, Python busca por variavel no escopo local, encontra uma referência de atribuição futura, mas percebe que ela ainda não tem um valor associado dentro daquele escopo local. Isso causa o UnboundLocalError.

Para informar ao Python que você deseja modificar a variável variavel que reside no escopo global, utilizamos a palavra-chave global:

variavel = "global"

def funcao():
    # 'global variavel' informa ao interpretador
    # que estamos referenciando e modificando a variável global.
    global variavel

    # Agora, podemos usar a variável global ANTES de alterá-la
    print(variavel) # Saída: global

    # Esta atribuição agora modifica a variável global
    variavel = "local"
    print(variavel) # Saída: local

funcao()
print(variavel) # Saída: local (o valor global foi alterado com sucesso)

Com global variavel, a primeira chamada a print(variavel) acessa o valor "global". Em seguida, a linha variavel = "local" realmente altera a variavel do escopo global.

Importante: A declaração global deve ser feita para cada variável global que você pretende alterar dentro de cada função onde essa alteração ocorrerá.

Finalmente, vale ressaltar que global só funciona para nomes no escopo global. Se você precisar alterar um nome em um escopo Enclosing (não-local), você precisará usar outra palavra-chave do Python: nonlocal.

`nonlocal`: alterando nomes do escopo enclosing

A palavra-chave nonlocal tem uma função similar a global, mas atua no escopo Enclosing (o E da regra LEGB), ou seja, em variáveis de funções externas que envolvem a função atual, mas que não são o escopo global.

Isso é particularmente útil em cenários onde uma função interna precisa modificar uma variável definida na função que a contém.

Veja o exemplo a seguir com apenas dois níveis de aninhamento:

def soma_mais_um():
    # 'numero' está no escopo Enclosing para 'incrementa'
    numero = 0

    def incrementa():
        # 'nonlocal numero' informa que queremos modificar
        # o 'numero' do escopo Enclosing (soma_mais_um)
        nonlocal numero
        numero += 1
        print(f"Número atual (interno): {numero}")

    # Até aqui, nada alterado
    print(f"Número inicial (externo): {numero}")

    incrementa() # A alteração ocorre aqui
    print(f"Número final (externo): {numero}")

soma_mais_um()
# Saída esperada:
# Número inicial (externo): 0
# Número atual (interno): 1
# Número final (externo): 1

Neste exemplo, a função incrementa() consegue modificar a variável numero que pertence à soma_mais_um(), no seu escopo Enclosing. Se nonlocal numero não fosse usado, incrementa() criaria sua própria variável local numero, sem afetar a de fora.

Cuidado com a complexidade: Embora nonlocal seja uma ferramenta poderosa e frequentemente usada em padrões como closures e decorators, o aninhamento excessivo de funções e o uso indiscriminado de nonlocal podem levar a um código difícil de ler e depurar. Como já mencionado na seção de boas práticas, sempre reavalie se há uma forma mais clara de estruturar seu código.

Concluindo - agora você passou de nível 😁

E assim chegamos ao fim do nosso texto sobre os conceitos de escopo e namespace em Python. Embora esse assunto possa parecer muito abstrato, ele acaba sendo um dos pontos principais para compreender como o Python funciona. Na verdade, não só Python! Muitas outras linguagens funcionam de maneira muito similar. Você vai levar esse conhecimento para todas elas.

Revisamos que:

Um escopo define o local do código onde um nome estará visível e acessível.
Um namespace é a estrutura que armazena essas associações entre nomes e objetos.
Escopo e Namespace são dois assuntos conectados em Python
A regra LEGB (Local, Enclosing, Global, Built-in) é a ordem pela qual o Python busca por nomes, sempre de dentro para fora.
Vimos como as funções globals(), locals(), vars() e dir() podem nos ajudar a inspecionar esses "dicionários" de nomes em tempo real.
E, finalmente, aprendemos sobre as palavras-chave global e nonlocal, que nos permitem, quando necessário e com muita cautela, alterar nomes em escopos externos ao imediato.

Dominar esses conceitos não é apenas sobre "saber o que acontece", mas sobre entender por que seu código se comporta como se comporta, evitar erros comuns como o UnboundLocalError, e escrever um código mais robusto e previsível.

Lembre-se sempre da lição sobre as boas práticas: alterar nomes fora do seu escopo imediato deve ser a exceção, não a regra. Priorize a clareza, o baixo acoplamento e a previsibilidade do seu código.

Com essa base sólida sobre escopo e namespace, você está pronto para mergulhar em tópicos mais avançados do Python, como closures e decorators, que dependem diretamente desse entendimento. Continue praticando e experimentando!

Funções recursivas com Python

Thu, 20 Aug 2020 00:00:00 GMT

Funções recursivas com Python (ou qualquer linguagem de programação) são funções que chamam a si mesmas de maneira direta ou indireta. Infelizmente, não há nenhum benefício em termos de desempenho ao usar funções recursivas em Python, já que laços podem resolver o problema com mais eficiência. Porém, funções recursivas podem ser mais intuitivas para o programador quando um problema pode ser dividido em problemas menores de mesmo tipo.

Considere o conceito de fatorial da matemática: o fatorial de um número é calculado pela multiplicação desse número por todos os seus antecessores até chegar ao número 1.

Esse é um problema extremamente simples para ser resolvido com recursão por dois fatores:

É um problema que pode ser dividido em sub-problemas menores e de mesmo tipo (multiplicar um número pelos seus antecessores)
Temos um caso-base para parar a recursão, retornar um valor real e resolver as equações (quando chegarmos em 1)

def fatorial(n: int) -> int:
    if n == 1 or n == 0:
        return 1
    return n * fatorial(n - 1)


if __name__ == "__main__":
    fat5 = fatorial(5)
    print(fat5)

O resultado da execução da função acima será 120.

# 5 * 4 * 3 * 2 * 1 = 120

Observação: você poderia escrever uma condição mais concisa eliminando o or da expressão com “if n < 2” ao invés de “if n == 1 or n == 0“.

Caso-base e caso recursivo

É muito fácil escrever uma função recursiva incorretamente e cair em uma recursão infinita. Veja isso no código a seguir:

def recursao_infinita(numero: int = 100) -> int:
    return recursao_infinita(numero - 1)


if __name__ == "__main__":
    recursao_infinita()

O Python não vai permitir que este código execute infinitamente, então você deverá ver uma exceção:

# RecursionError: maximum recursion depth exceeded

Isso ocorre porque nunca dissemos para a função quando parar a recursão, mais especificamente, não adicionamos um caso-base na função.

Toda função recursiva é composta de, pelo menos, duas partes: caso-base e caso recursivo. O caso-base é quando a função NÃO chama a si mesma, mas retorna um valor real; já o caso recursivo, como o próprio nome indica, é onde a recursividade ocorre (a função chama a si mesma).

Veja uma nova função recursiva, porém com ambos os casos: caso-base e caso recursivo.

def contagem_regressiva_recursiva(comeca_em: int = 10, termina_em: int = 0) -> int:
    """
    Contagem regressiva iniciando em 'comeca_em' e terminando em 'termina_em'
    """
    print(comeca_em)

    # Caso-base
    if comeca_em <= termina_em:
        # Perceba que aqui um valor real é retornado
        # e não há mais recursão
        return comeca_em

    # Caso recursivo
    # Esse código será executado sempre, até
    # 'comeca_em' se tornar menor ou igual a 'termina_em'
    return contagem_regressiva_recursiva(comeca_em - 1)


if __name__ == "__main__":
    contagem_regressiva_recursiva()

Call stack

Sempre que invocamos uma função, dados do seu escopo interno (como variáveis e parâmetros) precisam ser salvos em algum local. Além disso, também precisamos saber quando a função retorna um valor para que o programa continue a seguir o seu fluxo. Tudo isso é gerenciado pela Call Stack (pilha de chamada ou pilha de execução).

Como funciona a Call Stack

De forma simples e direta, funciona assim: quando meu programa está em execução e encontra uma chamada de função, ele pausa temporariamente o que estava fazendo e vai até o código interno da função para realizar sua execução. Após a execução, a função precisa saber como retornar o programa para o local onde ele parou antes da chamada para a execução. Então, após o retorno da função, o programa sabe como resumir o código partindo exatamente de onde a função retornou.

Exemplo de funcionamento da Call Stack

Veja um exemplo no gif abaixo como o fluxo do programa muda quando existe uma chamada para função:

No trecho simples de código acima, existe uma definição de função (linha 1), definição de variável (linha 5), uma chamada para função (linha 8) e em seguida um “print” em uma variável (linha 11). Eu marquei breakpoints nas linhas 2, 5, 8 e 11, mas não é essa a ordem de execução. Ao executar o programa, a ordem dos breakpoints não é a mesma. Ela é alterada para 5, 8, 2 e 11. Isso porque existe uma chamada para função na linha 8. Então enquanto o interpretador não conferir o que a função da linha 8 retorna, ele não tem como continuar a execução.

Além disso, perceba que, na lateral esquerda do gif, a “Call Stack” está aberta. Nela, existe o que está sendo executado no momento (stack frames). Nesse caso em específico, começamos com o módulo que está sendo executado (<module>). Tudo o que estiver definido dentro do módulo, será exibido na Call Stack dele. Porém, ao chamar a função, algo novo é adicionado ali, a chamada para função “funcao“. Isso ocorre após a execução da linha 8 (chamada da função) e termina após o retorno da função.

Locals

Vamos observar o que existe dentro da chamada de função (após a execução da linha 8).

Após a chamada para a função, a execução do módulo é pausada temporariamente até que o interpretador verifique o que a função retorna. Nesse momento, ela é adicionada na “Call Stack”, seus dados internos são salvos até que ela decida retornar um valor. Perceba que o argumento enviado ao parâmetro “nome” está em “Variables” como locals dessa função, essas são suas variáveis locais.

Assim que o retorno for concluído, a execução do módulo continuará a seguir seu fluxo e a chamada para a função será eliminada da “Call stack”.

Após o retorno da função, ela é eliminada da Call Stack e o módulo pode prosseguir com sua execução. Aliás, também preciso mencionar que capturei o valor do seu retorno em uma variável frase para fazer algo ela posteriormente (como dar um simples print no terminal).

Então, podemos resumir que “Call Stack” é exatamente o que sua tradução descreve, uma pilha de chamadas. Assim como existe uma pilha de livros na prateleira, existe uma pilha de chamadas de funções no seu programa. Cada elemento na call stack contém os dados do momento em que a funções foram chamadas.

Funções dentro de funções

Assim como acontece com funções chamadas diretamente dentro de um módulo, também ocorre com funções chamadas dentro de outras funções. Nesse caso, a pilha de chamadas fica ainda maior, porque se existir outra chamada para função dentro de uma função existente, o interpretador também precisará checar o retorno dessa outra função.

Considere o mesmo código anterior, porém com uma chamada dentro da função já criada.

Agora os passos são um pouco diferentes. Mas, se você me acompanhou até aqui, não terá dificuldade nenhuma para entender o que ocorreu.

Lembra que eu te disse que quando há uma chamada de função, o interpretador precisa verificar o que essa chamada retorna? Então, não é diferente aqui!

Quando estamos dentro de uma funcao_um realizando uma chamada para uma funcao_dois, o que ocorre é que a funcao_um precisa pausar sua execução para saber o que a funcao_dois retorna. Só após isso, a funcao_um poderá continuar sua execução normal.

Mas não termina aqui, isso tudo é registrado pela “Call Stack” (chamarei de pilha daqui em diante). Então, quanto mais chamadas de funções dentro de funções, mais coisas existem acontecendo na pilha.

No código da imagem anterior, temos uma chamada para função na linha 19, então sabemos que o interpretador vai conferir o retorno para essa chamada. Porém, ao acessar o código da função, o interpretador encontra uma nova chamada para função na linha 13, então ele também vai conferir o que essa outra função retorna.

Veja na imagem, que a pilha agora tem o seguinte:

nova_funcao
funcao_anterior
<module>

Cada elemento na pilha tem suas próprias variáveis locais salvas em memória.

Portanto, para resolver essa pilha o interpretador precisa voltar resolvendo todos os retornos de cima para baixo. Ou seja, o resultado final será: retorno da nova_funcao + retorno da funcao_anterior + continua executando o módulo. Como a funcao_anterior retorna a nova_funcao, o retorno final será o que a nova_funcao retornar.

Funções recursivas com Python

As funções recursivas com Python ou com qualquer outra linguagem de programação, funcionam exatamente como outras funções, porém, ao chamarem a si mesmas dentro do seu código, a cada nova chamada um novo elemento é adicionado na pilha (Call Stack, lembra?) contendo as variáveis locais daquele ponto na execução.

Considere a função fatorial, que te mostrei mais acima nesse post:

def fatorial(n: int) -> int:
  if n == 1 or n == 0:
      return 1
  return n * fatorial(n - 1)


if __name__ == "__main__":
  fat5 = fatorial(5)
  print(fat5)

A chamada dessa função (iniciando na linha 8) desencadeará mais 4 chamadas para ela mesma (somando 5 no total) até atingir meu caso-base, que é quando n for igual a 1.

Essas chamadas ocorreram na seguinte ordem:

fatorial(5) * fatorial(4) * fatorial(3) * fatorial(2) * fatorial(1)

Isso tudo está na pilha de chamadas e agora o interpretador precisa voltar resolvendo todas as chamadas de cima para baixo (ou de trás pra frente).

Dessa maneira (vou mostrar apenas os retornos):

# 1 = 1
# 2 * 1 = 2
# 3 * 2 = 6
# 4 * 6 = 24
# 5 * 24 = 120

O trecho descrito acima é exatamente como a pilha foi resolvida.

Perceba que após retornar todos os valores e a pilha terminar de ser resolvida, todas as chamadas e suas variáveis locais agora foram eliminadas da memória e temos apenas o valor de retorno de toda a pilha.

É assim que as Funções recursivas com Python (ou qualquer outra linguagem de programação) funcionam. Exatamente como descrito em todo este artigo.

Problemas que podemos encontrar com Funções recursivas

Como você pôde perceber no texto que seguiu, cada chamada para função dentro de uma função recursiva é adicionada à pilha (cada elemento na pilha, cujo retorno ainda não foi finalizado, é chamado de stack frame). Isso pode ser um problema quando temos muitas recursões ocorrendo dentro de um programa.

Imagine que eu peça o fatorial de 998, isso significa que a minha recursão ocorreria 997 vezes até atingir o caso base (somando 998 chamadas). Isso também significa que eu teria 998 elementos na minha pilha de chamadas (sem contar qualquer outra chamada para funções no módulo e a chamada do módulo em si). Talvez, se o custo de execução da função consumir muita memória, eu poderia esgotar os recursos do computador facilmente apenas chamando uma função recursiva.

Existe uma técnica chamada de Tail Call Optimization (ou Tail Recursion Elimination em casos recursivos) que resolveria este problema. Porém, Guido van Rossum, criador do Python, foi um contra a adição disso no Python alegando ser “Não Pythônico”.

I recently posted an entry in my Python History blog on the origins of Python’s functional features. A side remark about not supporting tail recursion elimination (TRE) immediately sparked several comments about what a pity it is that Python doesn’t do this, including links to recent blog entries by others trying to “prove” that TRE can be added to Python easily. So let me defend my position (which is that I don’t want TRE in the language). If you want a short answer, it’s simply unpythonic. Here’s the long answer.

Por Guido van Rossum, em 22/04/2009, em Neopythonic

Tradução Livre:

Recentemente, publiquei um post em meu blog Python History, sobre as origens dos recursos funcionais do Python. Uma observação simples sobre não suportar Tail Recursion Elimination (TRE) imediatamente provocou vários comentários sobre ser uma pena Python suportar isso, incluindo links para posts recentes de blogs de outros que tentaram “provar” que TRE pode ser adicionado ao Python facilmente. Então, deixe-me defender minha posição (que não quero TRE na linguagem). Se você quer uma resposta curta, simplesmente não é Pythônico. Aqui está a resposta longa.

Por Guido van Rossum, em 22/04/2009, em Neopythonic

Se o próprio criador do Python mencionou isso, não iremos discutir isso por aqui =).

RecursionError: maximum recursion depth exceeded in comparison

Esse erro apareceu pra você? Isso quer dizer que a pilha de elementos no seu call stack passou de 1000 (limite padrão em Python).

Você pode fazer três coisas para resolver este problema:

Checar se você realmente queria fazer mais de 1000 chamadas recursivas. Geralmente, quando criamos funções recursivas incorretamente, são realizadas mais recursões do que gostaríamos;
Trocar por um laço for. Como Python não tem Tail Recursion Elimination (pelo menos até o momento da escrita deste post), talvez você poderia reescrever o código usando for ou até while;
Por fim, um hack (aumentar o limite de recursão).

Para aumentar o limite de recursão, use:

import sys
sys.setrecursionlimit(5000)
print(sys.getrecursionlimit())  # 5000

O padrão são 1000 recursões, no trecho acima aumentei para 5000.

Algoritmos usando recursão

Como vimos anteriormente, o algoritmo mais clichê que é implementado com recursão, seria o fatorial, que vimos ao longo de todo o post. No entanto, há uma gama enorme de algoritmos que podem se beneficiar da recursão.

Eu não pretendo detalhar o que todos eles fazem (talvez fique pra um próximo post), mas seguem alguns:

Sequência Fibonacci

from functools import lru_cache


@lru_cache
def fibonacci_sequence(n: int) -> int:
    """Sequência Fibonacci with memoization"""
    if n < 1:
        return 0
    if n <= 2:
        return 1
    return fibonacci_sequence(n - 1) + fibonacci_sequence(n - 2)


if __name__ == "__main__":
    for i in range(1000):
        print(fibonacci_sequence(i))

A Sequência Fibonacci pode se beneficiar da memoization (cache) de funções executadas anteriormente. O Python inclui lru_cache no módulo functools que serve justamente para isso.

Adaptação do Livro Estruturas de dados e algoritmos com JavaScript (por Loiane Groner)

Quicksort

"""
Quicksort algorithm

>>> print(quicksort(list_of_numbers))
[2, 2, 4, 5, 9, 10, 11, 122, 123, 321]
>>> print(quicksort(list_of_words))
['Aline', 'Helena', 'João', 'Luiz', 'Maria', 'Zara']
>>> print(quicksort(['A']))
['A']
>>> print(quicksort(['B', 'A']))
['A', 'B']
>>> print(quicksort([]))
[]
"""

import doctest
from typing import List, TypeVar

TListValue = TypeVar('TListValue', int, float, str, bool)


list_of_numbers: List[int] = [10, 9, 5, 2, 11, 4, 2, 123, 321, 122]
list_of_words: List[str] = ['Luiz', 'Maria', 'João', 'Helena', 'Zara', 'Aline']


def quicksort(a_list: List[TListValue]) -> List[TListValue]:
    if len(a_list) < 2:
        return a_list

    pivot_index = len(a_list) // 2
    pivot = a_list.pop(pivot_index)
    smaller_values: List = [item for item in a_list if item <= pivot]
    higher_values: List = [item for item in a_list if item > pivot]

    return quicksort(smaller_values) + [pivot] + quicksort(higher_values)


if __name__ == "__main__":
    doctest.testmod(verbose=True)

Adaptação do Livro Entendendo Algoritmos (por Aditya Bhargava)

Um código personalizado

from typing import List


  class Caixa:
      def __init__(self, tem_chave=False) -> None:
          self.tem_chave = tem_chave

      def __repr__(self) -> str:
          return f'Caixa({self.tem_chave})'


  def encontra_chave(caixas: List[Caixa], index: int = 0) -> Caixa:
      if len(caixas) <= index:
          return Caixa()

      caixa = caixas[index]
      print(f'Procurando chave na caixa do índice {index} -> {caixa}')

      if caixa.tem_chave:
          return caixa

      index += 1
      return encontra_chave(caixas, index)


  if __name__ == "__main__":
      caixas: List[Caixa] = [
          Caixa(True), Caixa(), Caixa(), Caixa(),
          Caixa(), Caixa(), Caixa(), Caixa(),
          Caixa(), Caixa(), Caixa(), Caixa(),
      ]

      print(encontra_chave(caixas))

Meu código mesmo.

Torre de Hanoi

Adaptação do Livro O melhor do JavaScript (Por Douglas Crockford)

# Torre de Hanói
def hanoi(disco: int, origem: str, auxiliar: str, destino: str) -> None:
    if disco <= 0:
        return
    hanoi(disco - 1, origem, destino, auxiliar)
    print(f'Movendo disco {disco} de {origem} para {destino}')
    hanoi(disco - 1, auxiliar, origem, destino)


if __name__ == "__main__":
    hanoi(3, 'Origem', 'Auxiliar', 'Destino')

Adaptação do Livro O melhor do JavaScript (Por Douglas Crockford)

Em vídeo

Também criei um vídeo sobre este conteúdo em meu canal do Youtube, segue abaixo:

Link do vídeo no YouTube: https://youtu.be/0PwFwqiNfAI

Super resumo do resumo

Funções recursivas com Python (ou qualquer linguagem de programação) são funções que chamam a si mesmas de maneira direta ou indireta.

Normalização Unicode em Python

Thu, 20 Aug 2020 00:00:00 GMT

Além da normalização Unicode e as formas de normalização NFC, NFD, NFKC e NFKD, você vai aprender tudo o que precisa saber sobre o padrão Unicode em si e Python.

Falando sobre a normalização Unicode em si, que provavelmente é o que te trouxe aqui: normalizar é o ato de transformar strings (textos no padrão unicode) para uma forma normal onde os caracteres sempre terão a mesma representação binária em todo o seu programa. Isso facilita a comparação, indexação e ordenação de strings já que, em um sistema “normalizado”, essas operações são é mais confiáveis.

Frequentemente você verá emojis no meio do texto com um código na frete. Eu espero que você entenda isso ao terminar sua leitura, porque eu não costumo escrever assim, ok? 🤐 (U+1F910).

Um contexto para iniciarmos

Vamos iniciar uma jornada longa neste momento. Portanto, vou te deixar um contexto para discutirmos ao longo de todo o artigo. Porém, não se preocupe se não entender nada agora. Prometo que vou explicar tudo o que você vai ver a seguir 🙏 (U+1F64F).

Porque precisamos de normalização?

No padrão Unicode, caracteres são representados por code points (códigos de identidade do caractere). Mas, alguns desses caracteres são representados mais de uma vez para que o padrão Unicode mantenha compatibilidade com outros padrões que vieram antes dele.

Por exemplo, a letra “á” (a com acento agudo), representada por “U+00E1” em code point Unicode, também pode ser representada por "U+0061" (a) + “U+0301” (acento agudo). Na segunda representação, o acento é algo que é chamado de combining character, porque combinado ao “a“, forma “á“. No entanto, “U+00E1” (á) não é igual a “U+0061” + “U+0301” (á) do ponto de vista do seu programa em Python, mesmo que visualmente o caractere final seja exatamente o mesmo (á).

>>> '\u00e1'
'á'
>>> '\u0061\u0301'
'á'
>>> '\u00e1' == '\u0061\u0301'
False

A normalização unicode vai resolver este problema mantendo apenas uma forma normal dos “ás” apresentados acima. Ou “U+00E1” ou “U+0061” + “U+0301“. No entanto, para entender porque precisamos de normalização unicode em nosso sistema, precisamos entender o Padrão Unicode como um todo.

Unicode – o básico do básico

O Unicode é um padrão que permite aos computadores representar e manipular texto de qualquer sistema de escrita existente utilizando códigos para caracteres individuais. Cada caractere é mapeado para um código específico chamado de “code point“.

Code Points são representados por um U+ seguido de 4 a 6 dígitos hexadecimais (de 0 a 0x10FFFF). Por exemplo: o code point U+0041 representa a letra “A“; o U+0042, a letra “B“, o U+1F40D, uma cobra verde “🐍”, e assim por diante.

Para que um sistema possa representar um code point como um caractere “normal”, ele precisa de um sistema de codificação de caracteres. Este sistema de codificação também é provido pelo padrão Unicode e é responsável por representar uma sequência de code points (qualquer string no padrão Unicode) como um conjunto de code units na memória do computador, que então são mapeados para bytes de 8-bits.

Apesar do padrão Unicode disponibilizar um conjunto razoavelmente grande de sistemas de codificação de caracteres, como UTF-7, UTF-8, UTF-EBCDIC, UTF-16 e UTF32, a codificação mais usada atualmente é a UTF-8 (UTF sendo Unicode Transformation Format e 8 sendo o número de bits por código). No momento da escrita deste post, o site W3Techs – Historical trends in the usage statistics of character encodings for websites, mostra o padrão UTF-8 sendo usado em 94.7% dos sites analisados até 15/04/2020 👀 (U+1F440).

É uma boa ideia manter seu editor de códigos ou IDE no padrão UTF-8 para digitar seus códigos em Python 🤷‍♂️ (U+1F937).

Python e Unicode

Dica 💡 (U+1F4A1): Boa parte do trecho a seguir foi baseada na documentação oficial do Python.

As strings (str) em Python contém caracteres Unicode desde a versão 3.0. Isso quer dizer que qualquer valor entre aspas simples, duplas ou triplas são salvas em Unicode. De fato, o Python 🐍 suporta até mesmo identificadores com caracteres Unicode.

>>> atenção = 'Um teste unicode'
>>> atenção
'Um teste unicode'
>>>

Usando caracteres unicode

Também existem várias maneiras para usar caracteres Unicode dentro do código 💻 (U+1F4BB).

Por exemplo, você pode usar o caractere literal (como de costume), mas também pode usar o nome do caractere Unicode, um hexadecimal ou até um número decimal que representaria o caractere usando função chr:

>>> 'A' # Caractere literal A
'A'
>>> chr(0x41) # Usando a função chr com hexadecimal
'A'
>>> chr(65) # Usando a função chr com decimal
'A'
>>> '\N{Latin Capital Letter A}' # Usando o nome do caractere
'A'
>>> '\u0041' # Usando um hexadecimal 16-bit
'A'
>>> '\U00000041' # Usando um hexadecimal 32-bit
'A'

Veja acima, que representei a letra “A” de várias maneiras diferentes.

Obtendo valores Unicode dos caracteres

Além do que descrevi anteriormente, você também pode fazer o inverso, ou seja, pegar os valores decimal e hexadecimal que representam o caractere desejado.

Para isso, você pode usar as funções ord e hex, dependendo do que deseja (talvez seja necessário combiná-las).

Por exemplo:

>>> ord('A') # Obtém o valor decimal que representa A
65
>>> hex(ord('A')) # Obtém o valor hexadecimal que representa A
'0x41'

Encode (str) e Decode (bytes)

É possível converter uma string em bytes ou bytes em string usando os métodos encode da string ou decode de bytes. Esses métodos recebem dois argumentos. O primeiro argumento especifica a codificação de caracteres desejada (utf-8 ou qualquer outra disponível em Standard Encodings – use utf-8 sempre que possível 🕵). O segundo informa como os erros devem ser tratados (falaremos desse argumento mais adiante neste post).

Porém, é importante tomar cuidado ao converter uma codificação de caracteres para outra (exemplo, de ASCII para UTF-8). Pode não ser possível mapear o código de um caractere para outro em determinadas circunstâncias.

Veja exemplos a seguir.

Encode (str)

Suponha que eu queira converter uma string UTF-8 para bytes UTF-8.

Eu posso fazer isso da seguinte maneira:

>>> meu_nome = 'Otávio'
>>> meu_nome_em_bytes = meu_nome.encode('utf-8')
>>> meu_nome_em_bytes
b'Ot\xc3\xa1vio'
>>>

Bytes são representados por b'valores' em Python.

De acordo com o código anterior, tudo ocorreu perfeitamente. Isso porque converti uma string sabendo que ela tinha caracteres UTF-8 para bytes em UTF-8. Mantendo a mesma codificação de caractere, não terei problemas.

Mas, eu também poderia querer converter minha string UTF-8 para ASCII (um outro tipo de codificação de caracteres). Dependendo do que você estiver convertendo, não terá problemas, porque o UTF-8 foi feito para ser compatível com outras codificações de caracteres existentes. Porém, assim que um caractere sair do range suportado pelo ASCII (de 0 a 127 em base 10), terei um erro:

>>> meu_nome_em_bytes = meu_nome.encode('ascii')
Traceback (most recent call last):
...
UnicodeEncodeError: 'ascii' codec can't encode character '\xe1' in position 2: ordinal not in range(128)

Veja que no erro é descrito o problema. Não foi possível codificar o caractere '\xe1' na posição 2.

Lembra que te mostrei como exibir o caractere utilizando a função chr? Então, o caractere \xe1 é o mesmo que chr(0xe1), ou “á” de “Otávio“. Esse caractere não faz parte da tabela ascii, portanto o erro.

Logo mais veremos o segundo argumento e você poderá selecionar o que acontece quando um erro assim ocorrer.

Decode (bytes)

Se o método encode é usado para converter string em bytes, o método decode é usado para fazer o inverso disso, converter bytes em strings.

Por exemplo, suponha que eu tenha apenas os bytes e queira resgatar seu valor para uma string UTF-8.

>>> meu_nome_em_bytes = b'Ot\xc3\xa1vio'
>>> meu_nome_str = meu_nome_em_bytes.decode('utf-8')
>>> meu_nome_str
'Otávio'

Novamente, aqui ocorreu tudo perfeitamente, porque eu sabia que a codificação dos bytes era UTF-8 e eu os decodifiquei adequadamente. Então tudo ocorreu como esperado. Mas, e se eu quisesse decodificar esses bytes em ASCII?

Inicialmente, não tem como (😒 – U+1F612)!

Para isso você precisa saber a codificação de caracteres usada na codificação para decodificar.

Dica: chardet ajuda a tentar descobrir a codificação de caracteres usada em bytes que você não saberia de outra forma. Mas a maneira mais simples continua sendo: “pergunte ao dono dos bytes qual a codificação”. UTF-8 é um bom chute inicial.

Erros de codificação em decode (bytes)

Imagine que eu não saiba a codificação usada em determinados bytes e tente chutar ascii, por exemplo:

>>> meu_nome_str = meu_nome_em_bytes.decode('ascii') # Otávio (em UTF-8)
Traceback (most recent call last):
...
UnicodeDecodeError: 'ascii' codec can't decode byte 0xc3 in position 2: ordinal not in range(128)

Perceba que aqui, além de um erro de UnicodeDecodeError, eu também tenho um code point incorreto. Se você observar, 0xc3 aponta para “Ã” , que nem existia na minha string anterior.

O motivo disso é simples, “á” da minha string anterior usa dois bytes em UTF-8 e o codec ASCII não sabe disso. Então ele tenta decodificar byte por byte e gera esse erro estranho. Se isso passasse sem erros, o resultado seria um monte de caracteres que não fariam sentido algum. Por exemplo, se eu usasse o codec latin1 ao invés de ascii, o resultado seria ‘OtÃ¡vio’.

Para contornar essa situação, eu preciso saber qual a codificação de caracteres foi usada para codificar os bytes anteriormente. Sabendo disso, eu deveria decodificar esses bytes usando a codificação correta antes de fazer qualquer outra coisa.

Depois de decodificar, eu poderia codificar novamente usando o codec que eu preferir, contando que ele suporte os caracteres que eu estiver usando (usa sempre UTF-8, pelo amor de Deus 😬 – U+1F62C).

Por exemplo, se eu quero codificar de UTF-8 para ISO-8859-1 (Latin1), que é algo que vejo muito aqui no Brasil, principalmente em sistemas públicos, poderia fazer assim:

>>> meu_nome_str = meu_nome_em_bytes.decode('utf8') # Otávio
>>> meu_nome_em_bytes_latin = meu_nome_str.encode('latin_1') # Otávio
>>> meu_nome_em_bytes_latin
b'Ot\xe1vio' # Otávio

Basicamente, isso foi uma conversão de UTF-8 para latin_1. Tenha noção de que sempre que essas conversões ocorrem, uma codificação de caracteres deve suportar a outra. O Unicode foi criado para ser compatível com todas as codificações existentes. No entanto, apenas no sentido de “qualquer codificação” convertido para “Unicode”. Você pode ter problemas ao converter no sentido contrário, de Unicode para “qualquer codificação”, porque o padrão Unicode suporta muito mais caracteres do que qualquer outra codificação de caracteres que você quiser utilizar.

No nosso exemplo, tudo funcionou perfeitamente porque todas as letras de “Otávio” estão presentes na tabela ISO-8859-1 (Latin1), caso contrário ocorreriam erros também.

Dicas

Dica número 1: Sempre que possível use a codificação de caracteres UTF-8, na grande maioria das vezes isso é possível 😅 (U+1F605).

Mais dicas: se você precisa detectar a codificação de caracteres de algo que não tem a mínima ideia como foi codificado, use chardet.detect. Ele não vai acertar em 100% dos casos, mas já me salvou de muitas enrascadas; Se você precisa saber quais codecs de codificação o Python suporta, veja Python Specific Encodings.

Erros em encode e decode

Como te contei anteriormente, encode e decode recebem um argumento com a codificação desejada e outro especificando como os erros devem ser tratados. Para o segundo argumento você pode enviar os seguintes valores:

'strict' – É o padrão. O que levanta uma exceção de UnicodeEncodeError ou UnicodeDecodeError;
'replace' – Usa o caractere U+FFFD (REPLACEMENT CHARACTER) no lugar do caractere que não pôde ser convertido;
'ignore' – Simplesmente pula o caractere que não pode ser convertido;
'backslashreplace' – que insere uma sequência \xNN no lugar do caractere que não pode ser convertido;
'xmlcharrefreplace' – que insere uma referência para um caractere XML (isso só funciona com encode).

>>> 'Otávio'.encode('utf-8')
b'Ot\xc3\xa1vio'
>>> b'Ot\xc3\xa1vio'.decode('ascii', 'ignore') # aqui usei ignore
'Otvio' # e perdi o "á"

Normalização Unicode em Python

Nós demos várias voltas até chegar aqui, mas é importante conhecer o que você está fazendo, não é mesmo (😏 – U+1F60F)?

Então, só pra recapitular tudo:

Você conheceu os code points do Unicode;
Também sabe que Unicode foi feito pensando em compatibilidade com padrões já existente (ascii, latin, etc). Vamos voltar nesse assunto já já;
Viu que UTF-8 é uma das codificações de caracteres do Unicode;
Está ciente que UTF-8 é, de longe, uma das codificações mais usadas no mundo;
E deveria estar usando UTF-8 nos seus código (é muito provável que já esteja).

Uma coisa que eu ainda não te falei é sobre a normalização e o porquê isso existe.

Na verdade, todas as voltas foram para fazer você entender o que é Unicode de verdade. Se já sabia, melhor ainda!

Então agora podemos ter uma conversa mais “complexa”.

Unicode e outros padrões

Lembra que lá no comecinho ☝ (U+261D) te falei que eu poderia escrever a letra “á” de maneiras diferentes em Unicode?

Só pra te lembrar:

>>> '\u00e1'
'á'
>>> '\u0061\u0301'
'á'

Este pode não ser um problema no seu programa caso não tenha tido a necessidade de comparar esses dois “ás”. No entanto, em algum momento este problema pode aparecer e você vai demorar um tempo considerável até descobrir que isso está relacionado com a falta de normalização de caracteres. Nós buscamos recursos de várias fontes externas ao nosso programa e não sabemos qual forma normal utilizaram no sistema deles, e essa bomba pode explodir na sua mão.

O Unicode foi criado pensando em compatibilidade, por isso alguns caracteres aparecem mais de uma vez. Por exemplo, se você olhar na tabela ASCII, vai ver que a letra “A” é representada pelo mesmo hexadecimal que o Unicode (41 vs U+0041). Se olhar na tabela ISO/IEC 8859-1, vai ver que a letra “á” é representada exatamente pelo mesmo hexadecimal que o Unicode (00E1 vs U+00E1). Isso quer dizer que o range de 0 a 127 (base 10) no Unicode é compatível com ASCII, o range de 0 a 255 (base 10) no Unicode é compatível com ISO/IEC 8859-1 (ou latin1) e assim por diante. O Unicode tenta ser compatível com todos os padrões existentes.

Isso vai acabar nos levando a um problema, vai vendo 🤨 (U+1F928)!

Caracteres pré-compostos e caracteres combinados

Pelo motivo que te expliquei anteriormente, existem caracteres que são chamados de pré-compostos, como: á, é, À, Á e vários outros. Esses caracteres pré-compostos existem para manter compatibilidade com padrões que já existiam antes do Unicode.

Por outro lado, o Unicode também dispõe de um sistema de combinação para estender o repositório de caractere suportados, e isso é genial (🥰 – U+1F970)!

Pensa comigo 🤓 (U+1F913), se eu posso ter um “a” e um “acento agudo” em dois caracteres diferentes, não seria inteligente permitir que o acento agudo pudesse ser combinado com esse “a” ou com qualquer outro caractere formando um caractere único? Também acho!

É exatamente esse o mecanismo que foi usado no Unicode. Ao invés de ter um code point único para cada caractere do planeta, fizeram um sistema de combinação de caracteres para formar esses símbolos loucos que a gente acaba usando e nem percebe.

Esses caracteres que podem ser combinados com outros caracteres são chamados de combining character e existem muitos deles.

Mas, como nem tudo são flores (🥀 – U+1F940), isso gerou o problema de ter mais de um caractere representando a mesma coisa. Aquela probleminha que te mostrei no início, sobre os “ás”. Te falei que ia dar problema, não falei 😁 (U+1F601)?

É aqui que entra a normalização e uma outra coisa que é chamada de equivalência canônica.

Equivalência canônica

Como os criadores do Unicode são bem inteligentes 🧐 (U+1F9D0), eles criaram algo chamado de “equivalência canônica“. Isso é só uma maneira bonita de falar “esses dois caracteres são iguais”. Então, na equivalência canônica, U+00E1 (á pré-composto) é igual a U+0041 + U+0301 (a com acento agudo combinados). Isso acontece com todos os caracteres acentuados e mais outros milhares de caracteres que podem ser combinados em vários idiomas diferentes.

Sabendo disso, você poder utilizar mais de uma forma normal em todo o seu programa: NFC e NFD (tem mais duas, mas é questão de compatibilidade, segura aí que a gente já fala sobre isso).

NFC – Normalization Form Canonical Composition

Esse tipo de normalização Unicode visa manter os caracteres pré-compostos no seu programa (sem a separação de caractere + caractere combinado). Tais caracteres são unidos por equivalência canônica.

Lembra dos ás? Aqui eles serão iguais, porque somente o U+00E1 (á pré-composto) será mantido, os caracteres separados serão convertidos em pré-compostos. Por exemplo, U+0061 + U+0301 (a com acento agudo combinados) se tornaria sempre U+00E1 (á pré-composto).

Por exemplo:

>>> import unicodedata
>>> nome = 'Ot\u0061\u0301vio'
>>> nome_normalizado = unicodedata.normalize('NFC', nome)
>>> ['U+' + hex(ord(letra))[2:].zfill(4).upper() for letra in nome_normalizado]
['U+004F', 'U+0074', 'U+00E1', 'U+0076', 'U+0069', 'U+006F']
# O         t         á         v	      i         o

Da pra perceber ali que a letra “á” do meu nome, sempre será mantida como U+00E1 com esse tipo de normalização. Mesmo eu dizendo explicitamente que quero a string 'Ot\u0061\u0301vio'.

Resumidamente: isso não fará nada com caracteres pré-compostos, mas combinará caracteres equivalentes que estiverem separados em sua forma pré-composta por equivalência canônica.

NFD – Normalization Form Canonical Decomposition

Esse tipo de normalização unicode visa manter os caracteres separados (com a separação entre caractere e caractere combinado). Os caracteres serão separados por equivalência canônica.

Aqui os “ás” serão iguais, porque somente os caracteres U+0061 + U+0301 (a com acento agudo combinados) serão mantidos. Os “ás” pré-compostos (U+00E1) serão convertidos em U+0061 + U+0301.

Por exemplo:

>>> import unicodedata
>>> nome = 'Ot\u00e1vio'
>>> nome_normalizado = unicodedata.normalize('NFD', nome)
>>> ['U+' + hex(ord(letra))[2:].zfill(4).upper() for letra in nome_normalizado]
['U+004F', 'U+0074', 'U+0061', 'U+0301', 'U+0076', 'U+0069', 'U+006F']
# O         t         a         acento    v         i         o

Perceba que agora eu consegui manter ambos os caracteres, tanto o “a” quanto o “acento agudo combinado“. Mesmo especificando que eu queria a string 'Ot\u00e1vio'.

Resumidamente: isso não fará nada com aqueles dois caracteres combinados, porém vai separar caracteres pré-compostos para sua forma combinada por equivalência canônica. Basicamente é U+00E1 (á pré-composto) se transformando em U+0061 + U+0301 (a com acento agudo combinados).

NFKC e NFKD – Normalization Form Compatibility Composition/Decomposition

Para complicar um pouquinho mais a sua vida na normalização unicode, também existem caracteres que não são definidos por equivalência canônica, mas por compatibilidade.

Por exemplo, em alguns contextos, o símbolo TM pode ter o mesmo significado que ™ (TRADE MARK SIGN, U+2122). Nesse caso, ambos TM e ™ são definidos como caracteres compatíveis, mas que NÃO TEM equivalência canônica.

Isso quer dizer que nem NFC, nem NFD vão normalizar esses dois valores.

E só pra deixar claro isso pra você, caso ainda não tenha ficado:

NF – Normalization Form (formato de normalização);
C – Composition (composição – une);
D – Decomposition (decomposição – separa);
K – Compatibility (separa por compatibilidade).

Agora que vem a pergunta de 1 milhão de dólares: qual a forma normal entre TM e ™? Depende! Em qual contexto?

Vou te dar um exemplo: nós sabemos que seres humanos tem uma preguiça danada de digitar as coisas corretamente, certo? Imagine que a minha marca fosse OM™ e eu quisesse que no meu sistema de busca, essa marca fosse encontrada. Você acha que as pessoas digitariam OMTM ou OM™? Eu acho que OMTM (caso não encontrassem antes apenas digitando OM). Mas podemos garantir as duas com a normalização.

Então nesse caso, eu usaria a compatibilidade para transformar ™ em TM apenas para realizar uma comparação. Por exemplo, meu texto na base de dados seria normalizado temporariamente com NFKD e o texto enviado pelo usuário também seria normalizado para NFKD. Assim eu consigo encontrar OMTM ou OM™ independente de como isso foi digitado pelo usuário.

Para fazer a normalização unicode de ™ para TM, você vai precisar usar NFK(C ou D):

>>> import unicodedata
>>> nome = 'OM™'
>>> nome_normalizado = unicodedata.normalize('NFKC', nome)
>>> ['U+' + hex(ord(letra))[2:].zfill(4).upper() for letra in nome_normalizado]
['U+004F', 'U+004D', 'U+0054', 'U+004D']
# O         M         T         M

Perceba que “C” e “D” aqui vão fazer o mesmo trabalho descrito anteriormente, mas o “K” vai trabalhar na compatibilidade que te falei antes.

Então só pra resumir: O K significa compatibility e vai converter valores que estariam em apenas um code point Unicode em caracteres que seriam compatíveis (de acordo com as regras deles, que eu não sei quais são). Esses caracteres devem se comportar da mesma maneira em pesquisa, comparação, ordenação e indexação, mas podem mudar o significado e também podem parecer visualmente diferentes em vários contextos. Como no nosso exemplo, OMTM ou OM™ deveria retornar os mesmos valores no meu sistema de pesquisa ou comparação, mas eles são bem diferentes visualmente.

Um ponto de atenção para K

Tenha em mente que a partir do momento que eu separei os valores por compatibilidade, não consigo mais uni-los novamente. Por exemplo, se eu normalizar com K (NFKC ou NFKD) o valor ™ (TRADE MARK SIGN, U+2122), vou obter TM (como vimos). Porém TM não voltará a ser ™.

Por este motivo, é super importante que você não salve os valores permanentemente utilizando K. Você deve normalizar temporariamente no momento que precisar realizar alguma comparação e eliminar esse valor após terminar o que estava fazendo. Salve os valores como eles realmente são.

Usando chardet para detectar a codificação de caracteres

Na grande maioria das vezes que nosso sistema gerar algum problema de codificação de caracteres, esse problema virá de algum recurso externo. Portanto, para simular isso, suponha que eu tenha um arquivo em ISO-8859-1 (latin1). Qualquer editor de textos decente vai te permitir criar o mesmo texto com a mesma codificação de caracteres. Por exemplo, o Visual Studio Code.

![Exemplo de codificação no VS Code](./imgs/python-1.png)

Nós sabemos qual a codificação de caracteres foi usada neste arquivo (latin1), mas finja que não. Vamos carregar esse arquivo pelo Python usando “rb” (read bytes) e solicitar ao chardet para detectar a codificação de caracteres.

Nota: você precisa instalar o chardet com “pip install chardet“.

>>> import chardet
>>> with open('text.txt', 'rb') as file:
...     raw_content = file.read()
...     encoding = chardet.detect(raw_content)
...     encoding["encoding"]
...
'ISO-8859-9'

Ele detectou como ‘ISO-8859-9’, isso seria latin5 e não latin1, mas lembra que te falei que ele não iria acertar 100% das vezes, certo? Bom, vamos tentar converter esse arquivo de ISO-8859-9 (mesmo não sendo a codificação exata do arquivo) para UTF-8 e ver o que ocorre.

Vamos abrir o arquivo novamente, decodificar com a codificação que o chardet quiser (no caso ISO-8859-9, latin5), depois vamos abrir um novo arquivo com 'wb' e salvar como UTF-8. Veja:

>>> with open('text.txt', 'rb') as file:
...     # Vamos ler apenas bytes do arquivo
...     raw_content = file.read()
...     # Agora a gente decodifica
...     content_string = raw_content.decode(encoding["encoding"])
>>>
# Perfeito, agora vamos tentar pegar o conteúdo
# da content_string e salvar em outro arquivo
# porém, agora vamos codificar em UTF-8
>>> with open('text2.txt', 'wb') as file:
...     file.write(content_string.encode('utf8'))
...
192
>>>

Perfeito, sem erros! Agora vamos ver como está o nosso arquivo “text2.txt” (o novo arquivo gerado). Será que os caracteres se mantiveram?

![UTF-8](./imgs/python-2.png)

Perfeito! Viu como a aproximação que o chardet encontrou me ajudou muito? Mesmo que ele não tenha detectado com 100% de certeza qual a codificação de caracteres usada no arquivo, ele me passou uma que provavelmente iria funcionar.

Se você fosse tentar decodificar direto com UTF-8, isso ocorreria:

UnicodeDecodeError: 'utf-8' codec can't decode byte 0xe7 in position 4: invalid continuation byte

E se ignorasse os erros, seu texto ficaria assim:

Ateno Exceo Impresso Concesso Presuno
Voc Pur Croch Metr
Plstico Grfico Espcie Clebre
quelas s
Acar ACAR CABEA CAROO'

Eu acho que deu pra você entender, não é?

Funções interessantes com normalização unicode

Você, como programador(a), já pode ter imaginado milhares de coisas interessantes que pode fazer com a normalização unicode, não é mesmo? Se não, vou te dar algumas ideias:

Obtendo code points Unicode

Suponha que eu queira obter uma lista com todos os code points de uma frase. Veja que legal:

from typing import List
from unicodedata import normalize


def get_unicode_code_points(string: str) -> List[str]:
    string_normalized = normalize('NFD', string)
    code_points: List[str] = [
        'U+' + hex(ord(letter))[2:].zfill(4).upper()
        for letter in string_normalized
    ]
    return code_points


if __name__ == "__main__":
    text = 'Python 🐍™'
    code_points = get_unicode_code_points(text)
    print(code_points)

    """
    ['U+0050', 'U+0079', 'U+0074', 'U+0068',
    'U+006F', 'U+006E', 'U+0020', 'U+1F40D',
    'U+2122']
    """

Obtendo caracteres de code points

Mas, e o inverso? Dado um code point, como converto em caractere? Você já viu isso ao longo do texto todo, mas aqui vai.

from typing import List


def get_char_from_code_point(code_points: List[str]) -> str:
    chars = [chr(int(c.replace('U+', '0x'), 16)) for c in code_points]
    return ''.join(chars)


if __name__ == "__main__":
    code_points = [
        'U+0050', 'U+0079', 'U+0074', 'U+0068',
        'U+006F', 'U+006E', 'U+0020', 'U+1F40D',
        'U+2122'
    ]

    print(get_char_from_code_point(code_points))
    # Python 🐍™

Removendo caracteres fora da tabela ASCII

Em alguns casos, pode ser interessante manter apenas caracteres compatíveis com a tabela “ASCII”. Além disso, nós também podemos converter caracteres que seriam compatíveis se não fossem pré-compostos. Por exemplo, ‘á‘, ‘ã‘, à e â se tornariam simplesmente ‘a‘ e assim por diante para todos os caracteres. Porém, caracteres como 🐍 e 😀 não estariam presentes, porque não existem na tabela ASCII e também não existem compatíveis.

Vamos ver como faríamos isso:

import unicodedata


def non_ascii_to_ascii(string: str) -> str:
    ascii_only = unicodedata.normalize('NFKD', string)\
        .encode('ascii', 'ignore')\
        .decode('ascii')
    return ascii_only


if __name__ == "__main__":
    string = 'Atenção 🐍 😀'
    print(non_ascii_to_ascii(string))  # Atencao

Perceba que caracteres como “ç” e “ã” de “Atenção” foram mantidos sem acento (porque existem na tabela ASCII), porém 🐍 e 😀 foram ignorados.

Removendo acentos das palavras

Na função anterior, a gente meio que removeu os acentos, porém também removemos outras coisas que não queríamos. Mas, suponha que eu queira remover apenas o combining character mantendo o restante (o combining character seria o acento propriamente dito).

Isso me retornaria palavras sem acento.

Eu posso fazer isso, como o Luciano Ramalho descreve em seu livro Python Fluente.

import unicodedata

def remove_accents(string: str) -> str:
    normalized = unicodedata.normalize('NFKD', string)
    return ''.join([c for c in normalized if not unicodedata.combining(c)])

Porém, eu também posso fazer isso com expressões regulares. O que funcionar melhor pra você:

import unicodedata
import re


def remove_accents_regex(string: str) -> str:
    regex = re.compile(r'[\u0300-\u036F]', flags=re.DOTALL)
    normalized = unicodedata.normalize('NFKD', string)
    return regex.sub('', normalized)


if __name__ == "__main__":
    string = 'Atenção 🐍 😀'
    print(remove_accents_regex(string))  # Atencao 🐍 😀

Por falar nisso, eu tenho um detalhe sobre expressões regulares pra te informar: eu tenho um curso inteiro e gratuito na Udemy e no Youtube sobre isso.

Portanto, não há motivos para entrarmos em detalhes sobre regex aqui.

Mais sobre Unicode e Normalização Unicode

Eu sei que esse assunto talvez passe despercebido para vários desenvolvedores e desenvolvedoras mundo a fora e não é culpa deles (ou nossa, também passei por isso). Em nosso meio, a maioria dos cursos, faculdades e livros que você lê para aprender a programar, infelizmente não tratam desse assunto, ou, se tratam, é de maneira superficial. Porém, como você pôde ver, eu fiz questão de deixar todos os links de onde removi todas as informações que escrevi aqui. Assim, é extremamente necessário que você leia esses links também.

Além disso, ainda faltaram algumas coisas que não consegui falar neste post. Por exemplo, casefold e tratamento de arquivos, foram coisas que não mencionei aqui, mas que são mencionadas no Unicode HOWTO oficial do Python. Então, dá um jeito de ler esse artigo também.

Então é isso, te deixo aqui com um pouco mais de serviço pela frente.

Te espero no próximo post.

Filas em Python com deque (queue)

Mon, 08 Jun 2020 00:00:00 GMT

Filas em Python podem ser implementadas utilizando a estrutura de dados deque (do módulo collections) para garantirmos complexidade de tempo constante para inserção e remoção de elementos em qualquer uma das pontas, cabeça (head) ou cauda (tail). Deque – abreviação de Double Ended Queue (ou Fila de duas pontas) – pode ser usada para implementar filas FIFO (que veremos a seguir) e pilhas LIFO.

O que são filas?

Quando falamos em filas, estamos tratando de uma estrutura de dados abstrata que se comporta exatamente como uma fila na vida real. Elementos são adicionados à cauda (tail) e removidos da frente (head).

Porém, remover elementos da frente (com índice 0) pode ser problemático do ponto de vista de desempenho do programa. Por exemplo, poderíamos usar listas para criar filas (como fizemos com as pilhas), porém elas não são otimizadas para isso e acabam movendo os índices de todos os elementos posteriores ao elemento removido. Infelizmente, isso nos dá uma complexidade de tempo linear O(n), ou seja, ao remover um item do começo da lista, o interpretador precisa navegar em todos os seus elementos, reajustando os índices dos elementos restantes.

No entanto, isso não ocorre com deque. Segundo a documentação oficial do Python, deque adiciona e remove em ambas as direções com complexidade de tempo de aproximadamente O(1). Isso quer dizer que requer aproximadamente uma operação para a adição e remoção de elementos.

De forma resumida, deque é mais rápido para inserir e remover elementos da frente da fila (no índice 0).

Filas são FIFO

Na programação, o comportamento de uma fila é conhecido como FIFO (First In First Out), ou seja, o primeiro que entrar será o primeiro a sair. Isso é exatamente o que acontece em uma fila da vida real, a primeira pessoa a entrar na fila, será a primeira a ser atendida. É claro, se ninguém furar a fila!

Imagine uma fila de letras: A, B, C.

Agora, suponha que eu quero adicionar um novo elemento, o D. Para as filas, esse elemento deve ser adicionado na cauda, como mostra o diagrama a seguir:

Mas, se eu precisasse remover um elemento da fila anterior, o elemento removido deveria sair na cabeça (head).

Este elemento é representado pelo A na imagem a seguir:

Além disso, perceba que agora, além da minha fila não ter mais o elemento A, os índices foram reorganizados. B passou a ter o índice 0, C, índice 1 e D, índice 2. Lembre-se que deque é otimizada para isso.

Outra informação que você deve ter percebido, é que a cabeça (head) e a cauda (tail) da minha fila também mudaram. B é a cabeça e D a cauda.

Filas em Python com deque

Se fossemos representar a fila apresentada nas imagens anteriores com os elementos A, B e C, em seguida acrescentar o elemento D, o código ficaria da seguinte maneira:

from collections import deque

fila = deque(['A', 'B', 'C'])

# Inserindo o elemento D
fila.append('D')


# deque(['A', 'B', 'C', 'D'])
print(fila)

Perceba que deque tem quase os mesmos métodos de uma lista normal no Python (por isso podemos usá-las como pilhas se quisermos). Então, para inserir um novo elemento na cauda da fila, basta usarmos o método append.

Para a remoção do elemento A (como fizemos na seção anterior desse post), poderíamos utilizar o método popleft (remover da esquerda).

from collections import deque

fila = deque(['A', 'B', 'C'])

# Inserindo o elemento D
fila.append('D')

# Removendo A
fila.popleft()

# deque(['B', 'C', 'D'])
print(fila)

É bem simples, não é mesmo?

popleft retorna o elemento removido

Um comportamento padrão sempre que usamos métodos “pop” (de remoção) é que o elemento removido é retornado por essa função. Isso não é diferente como popleft.

Por exemplo, se eu estou removendo um elemento da minha fila, é natural querer usá-lo em algum momento do meu código. Então, eu poderia usar uma variável para isso.

from collections import deque

fila = deque(['A', 'B', 'C'])

# Inserindo o elemento D
fila.append('D')

# Removendo A e usando seu valor
head = fila.popleft()

# A
print(head)

# deque(['B', 'C', 'D'])
print(fila)

Perceba que no código acima (linha 9), popleft faz duas coisas:

Remove o primeiro elemento da fila (cabeça);
Retorna o valor do elemento removido para a variável head (A).

Assim, é possível utilizar o valor removido conforme preferir no seu código.

Criando uma filas em Python

Assim como fizemos com as pilhas (no artigo anterior), podemos encapsular deque em uma classe para manter o controle sobre os métodos que deverão ser utilizados para manter o comportamento FIFO das filas. Afinal, deque não tem apenas os métodos append e popleft. De fato, se você conferir a documentação oficial, vai ver que existem vários outros métodos possíveis para deque, incluindo os que quebram o princípio FIFO, removendo elementos da cauda ou inserindo na cabeça, por exemplo.

from typing import Deque, Any
from collections import deque


class Queue:
    """Uma classe representando uma fila"""

    def __init__(self, maxlen=None) -> None:
        # Deque permite enviar maxlen
        # para criar um tamanho máximo para
        # a fila
        self.__items: Deque[Any] = deque(maxlen=maxlen)

    def enqueue(self, *items: Any) -> None:
        """Enqueue (enfileirar) é o mesmo que append"""
        for item in items:
            self.__items.append(item)

    def dequeue(self) -> Any:
        """Dequeue (desenfileirar) é o mesmo que popleft"""
        if not self:
            raise IndexError('pop from empty queue')

        return self.__items.popleft()

    def __repr__(self) -> str:
        return str(self.__items)

    def __bool__(self) -> bool:
        return bool(self.__items)

    def __len__(self) -> int:
        return len(self.__items)

Na classe anterior, criei apenas os métodos que precisava para minha fila. Nesse sentido, também mudei o nome de algumas coisas: append passou a ser enqueue (enfileirar); popleft passou a ser dequeue (desenfileirar). Contudo, eles continuam fazendo o mesmo trabalho.

Também permiti adicionar o argumento “maxlen” de deque, para fixar um tamanho máximo para nossa fila.

Além disso, nós precisamos saber de três coisas muito importantes:

Quais valores estão na fila? Por isso o método __repr__;
Existem valores na minha fila? Por isso o método __bool__;
Quantos valores tem na minha fila? Por isso o método __len__.

Você pode enfeitar essa classe com os métodos que preferir. Aqui eu quis manter as coisas o mais simples que foi possível.

Agora podemos usar a classe:

if __name__ == "__main__":
# Instanciando
fila = Queue()

# Enfileirando A, B e C
fila.enqueue('A', 'B', 'C')

# Enfileirando D
fila.enqueue('D')

# Recuperando A
head = fila.dequeue()
print(head)

# Mostrando a fila
print(fila)

"""
Resultado:

A
deque(['B', 'C', 'D'])
"""

Indo além do básico

Em algum momento, você pode querer iterar sobre a sua fila ou então obter um item diretamente. Pra isso podemos repassar o método __iter__ da nossa classe para o método __iter__ do deque da mesma (__items). Veja a implementação do método __iter__ por si só.

Este método deve estar dentro da classe, é claro (não se preocupe, vou mostrar o código completo logo abaixo).

def __iter__(self) -> Iterator:
    return self.__items.__iter__()

Por fim, se você quiser permitir que um item da fila seja obtido pelo seu índice, também pode implementar o método __getitem__, dessa maneira:

def __getitem__(self, index: int) -> Any:
    return self.__items[index]

Veja como ficou nossa classe completa:

from typing import Deque, Any, Iterator
from collections import deque


class Queue:
    """Uma classe representando uma fila"""

    def __init__(self, maxlen=None) -> None:
        # Deque permite enviar maxlen
        # para criar um tamanho máximo para
        # a fila
        self.__items: Deque[Any] = deque(maxlen=maxlen)

    def enqueue(self, *items: Any) -> None:
        """Enqueue (enfileirar) é o mesmo que append"""
        for item in items:
            self.__items.append(item)

    def dequeue(self) -> Any:
        """Dequeue (desenfileirar) é o mesmo que popleft"""
        if not self:
            raise IndexError('pop from empty queue')

        return self.__items.popleft()

    def __repr__(self) -> str:
        return str(self.__items)

    def __bool__(self) -> bool:
        return bool(self.__items)

    def __len__(self) -> int:
        return len(self.__items)

    def __iter__(self) -> Iterator:
        return self.__items.__iter__()

    def __getitem__(self, index: int) -> Any:
        return self.__items[index]

Perceba que agora temos os métodos __iter__ e __getitem__. Isso nos permite iterar sobre nossa fila e também obter itens por índice, veja:

if __name__ == "__main__":
# Instanciando
fila = Queue()

# Enfileirando A, B, C e D
fila.enqueue('A', 'B', 'C', 'D')

# Obtendo o elemento com índice 1 (B)
print('Item com índice 1:', fila[1], end='\n\n')

# Iterando com for em nossa fila
for item in fila:
    print('Iteração:', item)

"""
Resultado:

Item com índice 1: B

Iteração: A
Iteração: B
Iteração: C
Iteração: D
"""

Nossa classe ficou assim, simples mas útil e eficaz. Todavia, você pode adicionar os métodos que preferir. Apenas adicionei métodos que acho que podem ser úteis.

Resumo

Em conclusão, você viu o seguinte ao decorrer desse post:

Filas em Python podem ser implementadas utilizando deque;
Filas têm o comportamento FIFO (First In First Out), assim como na vida real;
append adiciona elementos na cauda (tail);
popleft remove elementos da cabeça (head);
deque é muito genérica, por isso criamos nossa própria classe para permitir apenas os métodos que queremos.

Como resultado, agora você já sabe criar filas em Python. Além disso, também sabe usar deque, que é outra estrutura de dados abstrata conhecida em programação.

Te vejo no próximo post!

Pilhas em Python com listas (stack)

Mon, 03 Sep 2018 00:00:00 GMT

Pilhas em Python são comumente criadas usando listas, porque estamos interessados em manipular apenas a extremidade do topo da estrutura (o final da lista). Isso nos garante complexidade de tempo O(1) (tempo constante) com métodos append e pop.

Uma pilha é uma coleção de itens que segue o princípio LIFO (Last In First Out) , ou seja, o último item a entrar, será o primeiro a sair. A adição e remoção de novos itens ocorre sempre na mesma ponta da pilha, o final da lista. O final da lista (último índice), representa o topo da pilha, o começo da lista (índice 0) representa a base da pilha.

Itens mais novos são sempre adicionados no topo da pilha e se tornam mais antigos a medida que adicionamos outros itens. Quanto maior o índice na lista, mais novo é o item e mais cedo ele será removido da pilha.

Pilhas são estruturas de dados muito simples, mas podem ser usadas para representar várias coisas no mundo real, por exemplo: uma pilha de pratos, uma pilha de livros ou qualquer coisa que você coloque uma sobre a outra formando uma pilha. Além disso, programas também usam pilhas, como a pilha de chamadas para funções que já vimos anteriormente nesse blog.

Listas são pilhas muito genéricas em Python

Como pilhas só precisam de métodos para adicionar e remover itens do seu topo, as listas do Python já fazem esse trabalho com excelência e complexidade de tempo O(1), ou tempo constante. Então, é super rápido.

Porém, ou você só usa esses dois métodos (append e pop), ou você cria sua própria estrutura de dados chamada de Stack (uma classe que você verá ao final desse post) para outros desenvolvedores não usarem sua pilha de maneira genérica (como filas, por exemplo).

Se você quiser trabalhar diretamente com as listas, pode fazer o seguinte:

# Para Type annotation
from typing import List

# Pilha de livros com type annotation
stack_of_books: List[str] = []  # {1}

# Adicionando livros no topo da pilha
stack_of_books.append('Livro 1')  # {2}
stack_of_books.append('Livro 2')  # {2}
stack_of_books.append('Livro 3')  # {2}

# Obtendo o elemento mais novo
book = stack_of_books.pop()  # {3}

print(book)  # Livro 3 {4}

Perceba que no código acima, criei uma pilha de livros (stack_of_books) como uma lista vazia {1}. Quando precisei adicionar livros na pilha, usei o método append, que é padrão de listas em Python para adicionar itens ao final da lista {2}. Além disso, quando precisei obter o livro mais novo (do topo da pilha), usei o método pop, que também é padrão de listas em Python para obter o último item da lista (ou o elemento do topo da pilha) {3}.

Na verdade, o método pop faz duas coisas. Além de remover o item do topo da pilha, ele também retorna este valor. Então, Isso me permitiu fazer duas coisas em {3}: remover o item do topo da pilha e coletar seu valor em uma variável.

Por fim {4}, imprimimos o valor de book, que foi o “Livro 3”.

Cuidados com pop

Note que, a cada execução do método pop, o item mais novo será removido da pilha. Em algum momento, sua pilha poderá estar vazia e esse método levantará a exceção “IndexError: pop from empty list“, ou “Erro de índice: pop de uma lista vazia” (em tradução livre).

# Para Type annotation
from typing import List

# Pilha de livros com type annotation
stack_of_books: List[str] = []  # {1}

# Adicionando livros no topo da pilha
stack_of_books.append('Livro 1')  # {2}
stack_of_books.append('Livro 2')  # {2}
stack_of_books.append('Livro 3')  # {2}

# Obtendo o elemento mais novo
book_1 = stack_of_books.pop()  # Livro 3 {3}
book_2 = stack_of_books.pop()  # Livro 2 {3}
book_3 = stack_of_books.pop()  # Livro 1 {3}

# IndexError: pop from empty list
book = stack_of_books.pop()  # Não há mais livros {4}

Isso ocorre porque não há mais valores para serem removidos e recuperados da sua pilha {4}.

Para prevenir esse tipo de situação, podemos envolver nosso código em um bloco try e except, tratando a exceção “IndexError“. Veja:

# Para Type annotation
from typing import List

# Pilha de livros com type annotation
stack_of_books: List[str] = []  # {1}

# Adicionando livros no topo da pilha
stack_of_books.append('Livro 1')  # {2}
stack_of_books.append('Livro 2')  # {2}
stack_of_books.append('Livro 3')  # {2}

try:
    # Obtendo o elemento mais novo
    book_1 = stack_of_books.pop()  # Livro 3 {3}
    print(book_1)  # Livro 3

    book_2 = stack_of_books.pop()  # Livro 2 {3}
    print(book_2)  # Livro 2

    book_3 = stack_of_books.pop()  # Livro 1 {3}
    print(book_3)  # Livro 1

    # IndexError: pop from empty list
    book = stack_of_books.pop()  # Não há mais livros {4}
    print(book)  # Seu código não chegará aqui
except IndexError:
    print('Trate o erro como preferir aqui.')

Assim, a partir do momento que a exceção ocorrer {4}, seu código pulará imediatamente para o bloco except. Se não houver exceções, seu código não executará o bloco except.

Não use listas como filas

Além das pilhas, outra estrutura de dados muito usada em programação são as filas (falamos sobre elas em outro artigo). Basicamente, filas trabalham no lado oposto das pilhas. Então, se nas pilhas você trabalha na extremidade final (adicionando e removendo itens do topo), nas filas você trabalha nas duas extremidades, enfileirando itens no final (topo) e desenfileirando itens do início (base).

As listas podem ser usadas para filas também, porém, não é recomendável. Isso torna sua complexidade de tempo O(n), ou tempo linear, o que torna as listas mais lentas para isso.

O método pop, pode receber o índice que você pretende remover da pilha, por exemplo (mas não faça isso):

# Para Type annotation
from typing import List

# Pilha de livros com type annotation
stack_of_books: List[str] = []  # {1}

# Adicionando livros no topo da pilha
stack_of_books.append('Livro 1')  # {2}
stack_of_books.append('Livro 2')  # {2}
stack_of_books.append('Livro 3')  # {2}

book_1 = stack_of_books.pop(0)  # {3} Livro 1

print(book_1)  # Livro 1

Perceba que, no código acima, eu consigo passar um índice para pop descrevendo qual livro quero remover da pilha {3}. Assim, isso me permite remover o item da base da minha pilha (índice 0). Mas, o problema ao fazer algo assim, é que como as listas não foram otimizadas para tal, todos os outros itens da lista agora precisam ter seus índices alterados. O que tinha índice 1, passa a ter índice 0, o que tinha índice 2, passa a ter índice 1 e assim por diante.

A complexidade de tempo O(n) significa que, na pior das hipóteses, quando eu removo um item da base da minha pilha (como nas filas), todos os outros items agora precisam ser modificados, e eu assumo que não era essa a sua intenção.

Nós já falamos sobre filas aqui, mas para resumir, use collections.deque para filas e listas para pilhas.

Iterando pilhas

Em Python a iteração dos iteráveis é feita com for. Se você não quer remover nenhum elemento, mas apenas iterar sobre toda a pilha, faça o seguinte:

# Para Type annotation
from typing import List

# Pilha de livros com type annotation
stack_of_books: List[str] = []  # {1}

# Adicionando livros no topo da pilha
stack_of_books.append('Livro 1')  # {2}
stack_of_books.append('Livro 2')  # {2}
stack_of_books.append('Livro 3')  # {2}

# Laço for
for book in stack_of_books[::-1]:
    # Faça o que preferir com o Livro
    print(book)

"""
Saída:
Livro 3
Livro 2
Livro 1
"""

Perceba que no código acima, na linha 13, temos um laço for que vai iterar em todos os elementos da lista. Então eu posso fazer o que preferir com a variável book.

Detalhe importante: para manter a ordem da pilha (do topo para a base), eu preciso fazer uma iteração em ordem reversa na pilha quando uso for. Por isso adicionei [::-1] em stack_of_books. Isso inverte a ordem de listas em Python.

Um outro tipo de iteração sobre pilha, seria removendo os elementos da pilha ao mesmo tempo que itero sobre eles. Podemos fazer isso com o laço while:

# Para Type annotation
from typing import List

# Pilha de livros com type annotation
stack_of_books: List[str] = []  # {1}

# Adicionando livros no topo da pilha
stack_of_books.append('Livro 1')  # {2}
stack_of_books.append('Livro 2')  # {2}
stack_of_books.append('Livro 3')  # {2}

# Laço while
while stack_of_books:
    book = stack_of_books.pop()
    print(book)

"""
Saída:
Livro 3
Livro 2
Livro 1
"""

Perceba que usando o laço while com o método pop, a ordem é mantida. Porém, é importante saber que estou removendo cada um dos elementos da minha pilha.

Copiando pilhas

Trabalhar com dados mutáveis, como as listas, pode ser perigoso em qualquer linguagem de programação porque manipulamos o dado diretamente. Então, é uma boa ideia manter uma cópia do dado original sempre que o manipulamos (se for possível, é claro). Por outro lado, pode ser caro manter cópia de dados que são muito grandes, então você precisa ponderar as duas coisas: segurança e peso.

Manter a cópia de uma lista, pode ter uma complexidade de tempo linear O(n) se você fizer uma cópia rasa (shallow copy) ou mais do que isso se você mantiver uma cópia profunda (deep copy).

Shallow copy:

Esse tipo de cópia é um clone superficial dos itens da pilha. Ela tem complexidade de tempo linear – O(n) – o que significa que é necessário passar por todos os itens para realizar a cópia destes. A parte interessante desse tipo de cópia é que dados imutáveis (como str, int, float e bool) serão realmente copiados para uma nova pilha. Porém, dados mutáveis (como outras listas, dicionários e sets) não serão copiados, a nova pilha terá apenas uma referência para os dados mutáveis da pilha original.

Para realizar uma cópia do tipo shallow copy da sua pilha, faça o seguinte:

# Para Type annotation
from typing import List

# Pilha de livros com type annotation
stack_of_books: List[str] = []  # {1}

# Adicionando livros no topo da pilha
stack_of_books.append('Livro 1')  # {2}
stack_of_books.append('Livro 2')  # {2}
stack_of_books.append('Livro 3')  # {2}

# A cópia (shallow copy)
stack_of_books_copy = stack_of_books.copy()

# Agora não estou mais alterando os dados
# da pilha original.
while stack_of_books_copy:
    print(stack_of_books_copy.pop())

# A original continua intacta
print(stack_of_books)  # ['Livro 1', 'Livro 2', 'Livro 3']

Deep copy

Quando falamos em pilhas que contém dados mutáveis, como por exemplo, outras listas dentro da nossa pilha. É preciso tomar cuidado com a shallow copy, porque ela não vai copiar esses elementos, vai fazer apenas uma referência apontando para os dados da lista original. Isso significa que meus dados ainda continuarão mutáveis internamente, mesmo na cópia.

A complexidade de tempo de uma deep copy vai depender da profundidade dos itens mutáveis da sua pilha, quanto maior a profundidade, maior a complexidade (mais tempo leva).

Imagine essa estrutura de dados:

# Para Type annotation
from typing import List

# Pilha de listas
stack_of_lists: List[List[str]] = []

# Adicionando elementos
stack_of_lists.append(['A', 'B'])
stack_of_lists.append(['C', 'D'])
stack_of_lists.append(['E', 'F'])

Esse é um tipo de estrutura que devo tomar cuidado, porque existem listas dentro da minha pilha.

Veja o problema:

# Para Type annotation
from typing import List

# Pilha de listas
stack_of_lists: List[List[str]] = []

# Adicionando elementos
stack_of_lists.append(['A', 'B'])
stack_of_lists.append(['C', 'D'])
stack_of_lists.append(['E', 'F'])

# Shallow copy
stack_of_lists_clone = stack_of_lists.copy()

# Obtendo o elemento do topo da pilha
# Isso não altera a lista original
item = stack_of_lists_clone.pop()

# Mas isso sim
item[0] = 'ALTERANDO O DADO'

# Veja o resultado na lista original
print(stack_of_lists)

"""
Saída:
[['A', 'B'], ['C', 'D'], ['ALTERANDO O DADO', 'F']]
"""

Os comentários do código acima, explicam o que ocorre em cada trecho. Mas, aqui vai uma breve explicação:

Linha 13 – Faço uma shallow copy da minha pilha. Como te descrevi anteriormente, dados mutáveis NÃO são copiados de dentro da pilha original, eles passados apenas como referência. Isso significa que a lista cópia terá uma referência desses dados (você consegue acessá-los por ela) mas eles ainda são os dados da lista original e não uma cópia real;
Linha 17 – Obtém o item do topo da lista (esse ainda é o dado da lista original);
Linha 20 – Altero o item. Porém, como esse item é uma referência ao item da lista original, quem será alterado efetivamente será o item da lista original;
Linha 23 – Percebo a besteira que fiz.

Para solucionar esse tipo de coisa, usamos a deep copy, que é um tipo de cópia recursiva. Com isso, todos os dados, mutáveis e imutáveis serão copiados para a lista cópia.

Veja:

# Para Type annotation
from typing import List

# Preciso importar deepcopy
from copy import deepcopy

# Pilha de listas
stack_of_lists: List[List[str]] = []

# Adicionando elementos
stack_of_lists.append(['A', 'B'])
stack_of_lists.append(['C', 'D'])
stack_of_lists.append(['E', 'F'])

# Deep copy
stack_of_lists_clone = deepcopy(stack_of_lists)

# Obtendo o elemento do topo da pilha
# Isso não altera a lista original
item = stack_of_lists_clone.pop()

# Mas isso sim
item[0] = 'ALTERANDO O DADO'

# Veja o resultado na lista original
print(stack_of_lists)

"""
Saída:
[['A', 'B'], ['C', 'D'], ['E', 'F']]
"""

Veja que as únicas coisas alteradas foram na linha 5, porque eu preciso importar “deepcopy” do módulo “copy”. E a linha 16, porque ao invés de “shallow copy”, agora estou fazendo uma “deep copy”.

Classe Stack

A maneira mais segura e correta de se trabalhar com listas como pilhas em Python, é proteger o código para que os métodos genéricos das listas não possam ser chamados diretamente. Assim protegeremos o nosso código para que outros desenvolvedores não possam chamar um pop(0) na nossa pilha, dentre vários outros.

Criando uma classe, podemos adicionar exclusivamente os métodos que queremos. Como append, pop e alguns métodos mágicos para iteração e visualização de dados.

from typing import List, Any
from copy import deepcopy


class Stack:
    """Uma classe representando uma pilha"""

    def __init__(self) -> None:
        # Essa stack é genérica, por isso
        # a lista poderá receber qualquer
        # tipo de dados
        self.__data: List[Any] = []

        # Representa o índice para iterações
        # com for
        self.__index = 0

    def append(self, item: Any) -> None:
        """Representa o append da lista"""
        self.__data.append(item)

    def pop(self) -> Any:
        """Representa o pop da lista sem parâmetros"""
        if not self.__data:
            return

        return self.__data.pop()

    def peek(self) -> Any:
        """Mostra o último elemento adicionado à pilha"""
        if not self.__data:
            return

        return self.__data[-1]

    def __repr__(self) -> str:
        """Representação dos dados"""
        return str(self.__data)

    def __iter__(self):
        """Para iteração com for"""
        self.__index = len(self.__data)
        return self

    def __next__(self):
        """Para iteração com for (next item)"""
        if self.__index == 0:
            raise StopIteration

        self.__index -= 1
        return self.__data[self.__index]

    def __bool__(self):
        """Para iteração com while"""
        return bool(self.__data)


if __name__ == "__main__":
    stack = Stack()

    stack.append('A')
    stack.append('B')
    stack.append('C')

    print('FOR:')
    for item in stack:
        print(item)
    print()

    print('POP:')
    last_item = stack.pop()
    print(stack, last_item)
    print()

    print('WHILE:')
    stack_copy = deepcopy(stack)
    while stack_copy:
        print(stack_copy.pop())
    print()

    print('ORIGINAL STACK:')
    print(stack)

Resumo

Em Python, usamos as listas como pilhas (nunca como filas). Elas são estruturas de dados bem simples que precisam de apenas dois métodos para funcionarem corretamente. Um método de inserção e outro de remoção de valores (append e pop). Geralmente, o método de remoção (pop) também retorna o valor removido e você pode usá-lo com o que preferir.

As pilhas trabalham apenas na extremidade final da lista, por isso têm comportamento LIFO (Last In First Out), ou, o último a entrar é o primeiro a sair. O último elemento adicionado é considerado o elemento do topo da pilha; o primeiro elemento adicionado é o elemento da base da pilha.

Podemos iterar sobre pilhas usando laços for (invertendo seus valores) ou laço while combinado com pop.

É possível copiar listas utilizando shallow copy ou deep copy.

É só isso… Te vejo no próximo artigo.

TypeScript - uma longa introdução

Sun, 02 Sep 2018 00:00:00 GMT

Esse post vai te ajudar a entender melhor o que é o TypeScript de maneira geral. Vamos entrar um pouco mais na parte conceitual sem aprofundarmos em detalhes para que você saiba como e quando usá-lo.

Atenção: não tenho o intuito de falar sobre tudo o que é possível sobre o TS. Para isso, veja a documentação oficial.

O que é o TypeScript?

Segundo o site oficial, o TypeScript é um superconjunto do JavaScript com tipagem que é compilado para JavaScript simples (texto original: TypeScript is a typed superset of JavaScript that compiles to plain JavaScript), ou seja, algo que é adicionado sobre o JavaScript.

No entanto, como poderíamos imaginar um “superconjunto” (superset)? Isso é uma linguagem de programação? Uma versão do JS? Uma quarta dimensão? De fato, um superset não explica muita coisa pra quem conhece o termo (e eu não estou brincando, existe uma outra dimensão no TS, você vai descobrir já já).

Comparação com versões do ECMAScript

Assim como cada versão do ECMAScript adiciona novos recursos ao JavaScript, o TypeScript também o fará.

Por exemplo, imagine as versões do ECMAScript (ES3, ES5, ES6, …, ES2020):

Figura 1. Cada nova versão do ECMAScript adiciona novos recursos ao JavaScript.

Como podemos ver na Figura 1, novas versões do ECMAScript adicionam novos recursos ao JavaScript.

Além disso, cada uma das versões é compatível com a versão anterior. Portanto, você pode facilmente rodar um script ES5 em ambientes ES7, mas não o contrário. Não é possível usar os recursos do ES7 em ambientes ES5, porque tais recursos ainda não existem no ES5 (salvo se usarmos algum polyfill).

Mas, mesmo tendo várias versões do ECMAScript, chamamos todas elas de Javascript (a menos que você queira falar ou usar determinada especificidade de uma versão).

Nota: existem várias versões do ECMAScript, separei apenas três para exemplo. Você pode ver todas elas aqui.

Onde o TypeScript se encaixa?

Se adicionarmos o TS como um layer, como fizemos na Figura 1, esse diagrama ficaria assim:

Figura 2. O TypeScript é um superset do JavaScript.

Então, podemos perceber que o TS adiciona funcionalidades sobre o JS simples. Portanto, é isso que o site oficial quer dizer quando detalha o TypeScript como um superset do JavaScript.

O que realmente é o TypeScript

Aqui segue um resumão sobre o que eu acho que o TS realmente é: O TypeScript é um superset do JS criado pela Microsoft. Um JavaScript mais moderno e seguro, que adiciona as últimas versões do ECMAScript, muitos recursos próprios e um sistema extremamente rico para tipagem. Além disso, ele também adiciona recursos muito úteis ao editor de código para facilitar a vida do desenvolvedor (falaremos mais sobre isso mais adiante).

Por falar em tipagem, uma das partes mais importantes do TypeScript são os tipos (types), por isso o nome TypeScript (acho que você já tinha percebido, né?). De fato, esse é um dos fatores que costuma levar o TS para projetos de larga escala em bases de código gigantescas. Vamos falar mais sobre a tipagem mais adiante neste post também.

Linguagem interpretada ou linguagem compilada?

Depende do seu ponto de vista e do seu ambiente de desenvolvimento!

Quando falamos em TypeScript, geralmente estamos imaginando o ambiente mais comum atualmente (06/2020): Node.js.

Assim, se você pensar neste ambiente, é meio incomum falar de algo como o TS, porque ele não seria uma linguagem interpretada (como Python, Ruby, PHP…), nem uma linguagem que compila para bytecode ou código de máquina como outras linguagens de mais baixo nível fazem. O TS com Node.js seria uma linguagem que compila diretamente para outra linguagem de alto nível, o JavaScript.

Lembra da Figura 2? Pois é, ao terminar de escrever o meu código TypeScript, eu faria a compilação diretamente para JavaScript simples. Por isso, o JavaScript gerado seria o meu código de produção, que ambos, Node.js e o Browser, entendem. Portanto, minha aplicação em produção rodaria apenas JavaScript.

Figura 3. Processo de compilação do TypeScript em JavaScript usando Node.js

Outra dimensão?

Lembra da nova dimensão que falei anteriormente? Então, é aqui que ela entra. Tudo o que o TypeScript adiciona de recursos no momento do desenvolvimento, será removido no código final compilado. Afinal, o Javascript não entende muitos dos recursos adicionados pelo TS, no final das contas, o que a gente quer mesmo é o código compilado, ou seja, o JS puro.

A “dimensão do TypeScript” existirá apenas no seu código de desenvolvimento.

Um cenário diferente

Este acima seria o cenário Node.js, onde você precisa compilar o código para ter o JS puro no back-end. Certamente, é o cenário mais usado hoje em dia e acho que isso ainda vai perdurar por alguns anos.

Porém, em 13 de maio de 2020, a versão 1.0 do Deno foi lançada e ele interpreta TypeScript puro, sem a necessidade de compilação. Então, olhando por este ponto de vista, o TS seria uma linguagem de programação com tipagem estática e interpretada. Você ainda precisaria compilar o código para o front-end, mas não para o back-end.

Neste post, vou focar mais no lado “Node.js” da coisa, com o processo de compilação.

Extensão .ts e .tsx

Arquivos TypeScript tem a extensão .ts ou .tsx ao invés de .js ou .jsx e aqui cabe uma dica interessante: converter um arquivo JavaScript válido em TypeScript válido é um processo relativamente simples, basta renomear a extensão de .js(x) para .ts(x). Dependendo da configuração do seu ambiente, o TypeScript poderá compilar o seu código JavaScript sem nenhum problema (talvez com alguns alertas, mas o código JS será gerado normalmente).

Este é um dos muitos fatores que dão tanta popularidade ao TypeScript atualmente. Muitos desenvolvedores estão migrando suas bases de código de JavaScript para TypeScript por conta dessa simplicidade. Apenas configure seu ambiente, renomeie um arquivo .js para .ts e pronto, estará em ambiente TypeScript!

Por exemplo, isso é TypeScript:

function greet(name) {
  console.log(`Olá, ${name}!`);
}

greet('Otávio Miranda'); // Olá, Otávio Miranda!

Alguma diferença com o JS que você conhece? É claro que não usei nenhum recurso do TypeScript neste código, mas eu poderia facilmente (e não acho que isso dificultaria seu entendimento):

function greet(name: string): void {
  console.log(`Olá, ${name}!`);
}

greet('Otávio Miranda'); // Olá, Otávio Miranda!

Isto só é possível, porque se observarmos nossa Figura 2 o TypeScript É JavaScript. Portanto, assim como podemos rodar scripts ES5 em ambientes ES7 (ou superiores), o compilador do TypeScript não terá nenhum problema em entender JavaScript puro. Por outro lado, assim como não conseguimos usar recursos do ES7 no ES5 sem um polyfill, também não conseguimos rodar TypeScript diretamente em ambiente JavaScript. Nem o Browser, nem o Node.js entenderiam TS.

O primeiro código (sem tipagem) rodaria perfeitamente tanto em ambientes JavaScript quanto TypeScript; o segundo (com tipagem) não poderia ser interpretado pelo JavaScript.

Por que o TypeScript é mais seguro?

Considere este código JavaScript abaixo:

const name = 'Otávio Miranda';
const upperCaseName = name.toUppercase();
console.log(upperCaseName);

Agora, me diga: encontrou o erro? Sim! Ele tem um erro que só seria detectado no momento da execução (runtime). Porém, quase posso garantir que, ao passar o olho sobre este código, você não o detectou facilmente, estou certo?

Se um código assim fosse para produção, ao ser executado seus usuários veriam algo como:

Uncaught TypeError: name.toUppercase is not a function

Ou, para um usuário comum, ele simplesmente veria seu programa parar de funcionar sem saber o motivo.

Mas, se você colocar este código em um ambiente TypeScript, antes mesmo da execução do seu código este erro seria detectado.

Figura 4. O TypeScript detecta o erro antes que você possa executar seu código.

Conveniência da Intelligent code completion

Além de analisar o meu código enquanto eu digito sem deixar o meu editor lento, a mensagem do TypeScript ainda me informa qual o erro, qual o tipo da variável e ainda me da uma sugestão sobre o que eu quis dizer. Nesse caso, se você ainda não detectou, toUppercase não existe no tipo string, o correto seria toUpperCase.

Por fim, veja esse outro código (aqui o erro é explícito)?

console.log([1, 2, 3] * 2); // NaN

Viu o erro? No entanto, o JavaScript não tem problema em permitir que meu código rode assim, multiplicando um array por um número.

Porém, veja o que acontece quando migramos para TypeScript:

console.log([1, 2, 3] * 2); // NaN
//          ^ The left-hand side of an
//            arithmetic operation must
//            be of type 'any', 'number',
//            'bigint' or an enum
//            type.ts(2362)

Por isso que o TypeScript deixa nossos códigos mais seguros.

Nota: vou representar esses erros com comentários de código (se necessário) ao invés de imagens pra facilitar minha vida. O ^ representa onde o erro será exibido.

Esses erros são bem simples e fáceis de encontrar e corrigir. Mas, você provavelmente já sabe que um ambiente de produção é muito mais complexo que isso: objetos podem ser aninhados, funções, classes e variáveis podem vir de outros módulos, bases de dados e o ambiente podem prover APIs (como a DOM, do browser por exemplo), e assim por diante. Esses são os casos onde o TypeScript brilha ainda mais.

Mas, espera aí! Como o TypeScript está vendo erros no meu código sendo que eu ainda nem o compilei? Este, minha amiga ou meu amigo, é trabalho do tsserver e do Typechecker do TypeScript. Que vamos falar logo a seguir.

TypeScript – Typechecker e tsserver

Nota: você realmente não precisa saber de nada disso pra programar em TypeScript ou JavaScript.

Programas são feitos por humanos e para humanos (pelo menos alguns rsrs), isso quer dizer que a linguagem de programação que escolhemos funciona exatamente como um “Idioma” qualquer que será traduzido para que o dispositivo entenda e execute de alguma forma. Mas, seu código precisa chegar na engine do JS de alguma forma, certo? Vamos ver.

Como seu código Javascript vai parar na engine do JS

Este processo é feito no JavaScript seguindo os seguintes passos (de forma bem resumida):

Seu código JavaScript é convertido em uma AST;
A AST é convertida em Bytecode;
O Bytecode é avaliado pela engine.

Perceba que entre você criar seu código e ele ser executado pela engine do JS, nada além de uma conversão ocorre do seu código. Se ocorrer um erro (algo digitado incorretamente, por exemplo), seu código vai ser executado com erro e a engine vai parar no ato do erro. Por isso vemos Uncaught TypeError: Bla bla bla por não tratar essa exceção, só depois de executar o código.

Como seu código TypeScript vai parar na engine do JS

Ao adicionar o TypeScript, esse processo fica bem maior, veja:

Seu código TypeScript é convertido em uma AST (TS)
A AST é analisada pelo Typechecker (TS)
A AST é convertida em código JavaScript (TS)
O código JavaScript é convertido em uma AST (JS)
A AST é convertida em Bytecode (JS);
O Bytecode é avaliado pela engine (JS);

Perceba que as partes em negrito foram adicionadas ao processo. Passos de 1 a 3 são executados pelo TypeScript; passos de 4 a 6 são executados pelo JavaScript. A tipagem é checada nos passos 1 e 2 (do TS). Do passo 3 em diante, o TypeScript não vai mais checar seu código. Em outras palavras, a última coisa que o compilador do TypeScript faz é compilar o seu código para Javascript, toda a checagem é feita antes da compilação.

Por este motivo, eu posso compilar meus códigos JavaScript sem tipagem pelo TypeScript (como eu te disse, TypeScript é JavaScript). Também é por este motivo, que eu posso configurar o nível de restrição do TypeScript (eu poderia, por exemplo, não permitir a compilação se meu código tiver algum tipo de alerta ou falta de tipagem).

tsserver

Eu falei, falei e falei, e acabei não respondendo sua pergunta: Como o TypeScript está vendo erros no meu código sendo que eu ainda nem o compilei?

Quando instalamos o TypeScript, ganhamos duas coisas: o compilador (tsc) e um servidor que provê serviços da linguagem (tsserver). De fato, você pode ver eles na pasta “bin” do “node_modules”. Em nosso dia a dia como programador ou programadora, não nos preocupamos com o tsserver porque ele geralmente é usado pelo seu editor ou IDE. Porém, ele é super importante pra gente. É ele que nos permite ter auto completar, inspeções de código, navegação, refatoração, e muito mais, diretamente no editor que usamos para criar nosso código.

Então, respondendo a sua pergunta, o tsserver roda em background em alguns editores de código fazendo essa checagem. Quando ele encontra algo que não bate com a minha configuração do TypeScript, ele grifa o trecho de código com aquela linha vermelha ondulada dizendo o que está incorreto. Dessa forma, eu não preciso executar meu código pra saber que existe um erro nele.

vscode

Eu não sei qual editor de códigos você usa, mas gosto bastante do VSCode porque ele já vem com o tsserver embutido (muito editores também já fazem isso). Com isso, eu posso digitar o meu código tranquilamente, sabendo que enquanto o sublinhado vermelho não aparecer, provavelmente meu código não tem nenhum erro (a não ser de lógica rsrs).

Outra coisa interessante é que se eu passar o mouse sobre determinada variável, eu sei exatamente qual o tipo dela. Isso em bases de código maiores é uma mão na roda.

Figura 5. VSCode + tsserver exibindo o tipo de uma variável

Fatos interessantes:

O VSCode foi criado pela Microsoft e foi escrito em TypeScript e JavaScript com o Electron. Ele usa type definitions do TypeScript para a maioria das funções do seu IntelliSense tanto para JavaScript quanto para TypeScript. Portanto, se você usa o VSCode para editar seus códigos Javascript, você já faz uso extensivo de TypeScript (mesmo sem saber).

Instalando e configurando o TypeScript

Se você chegou até aqui, provavelmente eu já despertei seu interesse em TypeScript (ou talvez você já o tinha). De qualquer forma, que bom! Na minha opinião, se você começar a usar o TS nos seus projetos, vai ser difícil voltar atrás, vai por mim.

Contudo, isso pode ser algo desafiador em meio a tantas opções, não é mesmo? A seguir, vamos ver como iniciar um projeto TypeScript do zero. Embora eu não vá conseguir te explicar tudo o que existe sobre ele em apenas um post, percebo que o mais difícil é iniciar, o resto você pode ir aprendendo com o tempo e a documentação.

Instalação de programas

Eu gosto de usar algumas coisas nos meus projetos, por isso, a configuração que você vai ver a seguir será a mesma que utilizo em muitos dos meus projetos. Entretanto, tenha em mente que isso vai variar muito de desenvolvedor para desenvolvedor e de projeto para projeto. Assim, é provável que você verá outras configurações muito diferentes por aí, ou talvez você tenha que conversar com seu time antes de sair configurando o ambiente de um projeto como um todo.

Se você tem experiencia com isso, provavelmente poderá pular para “Instalando o TypeScript, ts-node e eslint“.

Antes de começar, você vai precisar do seguinte (se quiser o mesmo ambiente que o meu):

Baixar e instalar o Node.js;
Baixar e instalar o VSCode;

Criando a pasta do projeto

No seu sistema operacional, crie uma pasta exclusiva para o seu projeto com o TS. Isso é importante para termos uma pasta node_modules e package.json exclusivos para este projeto.

Nota: você pode migrar uma base de código existente apenas renomeando arquivos .js para .ts e fazendo as configurações abaixo. Nesse caso use strict como false (você vai ver isso abaixo). Além disso, verifique se todos os módulos que você utiliza no projeto JS dão suporte para TS. Tenha em mente que pode ser necessário modificar coisas complicadas para fazer essa migração.

Para um projeto novo (recomendável), apenas abra a nova pasta pasta no VSCode, indo em File > Open Folder e escolhendo a pasta que você acabou de criar.

Instalando o TypeScript, ts-node e eslint

Abra o terminal do VSCode em View > Terminal e digite o seguinte:

npm init -y
npm i typescript ts-node eslint @types/node -D

typescript – é o próprio TypeScript (tsc e tsserver);
ts-node – permite executar scripts do TypeScript diretamente;
eslint – É o meu linter preferido, algumas pessoas preferem o tslint (você pode conferir depois);
@types/node – São as definições de tipo para o Node.js

Extensões do VSCode

Para uso do ESLint e do ts-node, eu gosto de duas extensões no VSCode.

Instale ambas as extensões no seu VSCode

O Code Runner habilita a possibilidade executar um comando apenas pressionando um botão de “Play” no canto superior direito do seu VSCode. Assim, ao invés de digitar:

npx ts-node index.ts

Eu posso simplesmente configurar o Code Runner para executar automaticamente este comando para todos os meus arquivos TypeScript assim que eu pressionar o play. Isso é fantástico para executar rapidamente seus código e focar no aprendizado.

O Eslint (a extensão) faz a integração do ESLint (linter) com o VSCode.

Configurando o ESLint

Vamos instalar alguns plugins para que o ESLint funcione com o TypeScript. Para isso, digite no terminal:

npm i @typescript-eslint/eslint-plugin @typescript-eslint/parser -D

Crie um arquivo com o nome .eslintrc.js na raiz do seu projeto e cole o seguinte nele:

module.exports = {
  env: {
    browser: true,
    es6: true,
    node: true,
  },
  extends: [
    'eslint:recommended',
    'plugin:@typescript-eslint/eslint-recommended',
    'plugin:@typescript-eslint/recommended',
  ],
  globals: {
    Atomics: 'readonly',
    SharedArrayBuffer: 'readonly',
  },
  parser: '@typescript-eslint/parser',
  parserOptions: {
    ecmaVersion: 11,
    sourceType: 'module',
  },
  plugins: ['@typescript-eslint'],
  rules: {},
};

E é só, agora você já tem o ESLint integrado ao seu VSCode e configurado. No entanto, não configurei nenhuma regra do ESLint justamente para que você possa fazer suas próprias escolhas. Seu projeto usa aspas simples ou duplas? Requer ponto e vírgula? Usa tabs ou espaços? Quantos? Enfim, essas são decisões que você precisa tomar.

Eu gosto de usar as regras do Prettier, com ponto e vírgula, aspas simples e 2 espaços (vou mostrar como configurar mais abaixo).

Configurando o Code Runner

No seu projeto, crie uma pasta chamada de .vscode. Nessa pasta, crie um arquivo chamado de settings.json.

Cole o seguinte neste arquivo:

{
  "code-runner.executorMap": {
    "typescript": "npx ts-node --files"
  }
}

Note que este arquivo pode já existir. Caso positivo, adicione a configuração acima junto com a configuração anterior que pode já estar no arquivo settings.json.

Por exemplo:

{
  "window.zoomLevel": 0,
  "code-runner.executorMap": {
    "typescript": "npx ts-node --files"
  }
}

No arquivo acima, estou simulando que já existia a configuração "window.zoomLevel", então adicionei as configurações do Code Runner junto.

Agora você pode clicar no “Play” no canto superior direito sempre que quiser executar o seu arquivo TypeScript.

tsconfig.json

Você pode compilar seus arquivos TypeScript em JavaScript de duas maneiras diferentes:

com parâmetros via linha de comando
com parâmetros via tsconfig.json

No entanto, não recomendo o uso da primeira opção.

Assim, crie um arquivo chamado tsconfig.json na raiz do seu projeto e cole o seguinte:

{
  "compilerOptions": {
    "lib": ["es2015"],
    "module": "commonjs",
    "outDir": "dist",
    "strict": true,
    "target": "es2015",
    "esModuleInterop": true
  },
  "include": ["src"]
}

Vamos entender o que fizemos, afinal, é pra isso que você está aqui:

lib – configura o ambiente que o TSC vai assumir que você está usando. Assim, es2015 assume que o ambiente no qual você vai rodar seu código é compatível com o ECMAScript 2015.
module – configura qual o sistema de módulos o TSC vai usar para compilar seu código. Geralmente, escolho ‘common.js‘ e ativo ‘esModuleInterop‘. Isso me permite usar Import/Export em qualquer ambiente. No entanto, se eu fosse usar algum ambiente front-end, usaria o webpack para fazer meu bundle.
outDir – É a pasta de saída do seu código. Quando você compilar, a pasta de saída terá a mesma estrutura da pasta de entrada. Então, seus arquivos de produção estarão em “dist” após a compilação.
strict – Esse é o modo recomendável para uso do TS, ativa várias flags restritivas no TSC. Qualquer coisa que não estiver em conformidade, o compilador vai reclamar. Porém, isso só é recomendável se você estiver iniciando um projeto do zero com TS, se for migrar um código antigo de JS para TS, configure como false.
target – configura a versão ECMASCript que o TSC vai usar para compilar seu código (ES3, ES5, …, ES2020, ESNext). Entretanto, o ambiente de produção do seu código precisará suportar a versão escolhida.
esModuleInterop – Ver module.
include – quais pastas o tsc vai analisar para compilar.

Testando tudo

Como você pôde perceber na configuração anterior, nossa pasta de entrada será “src” e de saída “dist“. Embora você possa usar a configuração que preferir, essa é uma convenção muito utilizada atualmente. Então, prefira mantê-la.

Nota: a pasta src precisa ser criada manualmente, assim como os arquivos .ts dentro dela.

Vamos criar todos os nossos arquivos com extensões .ts na pasta src. Eventualmente, vamos compilar nosso código simplesmente digitando “tsc” (sem aspas) no terminal.

Você terá duas opções para executar seu código:

Usando o ts-node
Usando o tsc

Código de exemplo

Embora eu ainda não tenha especificado como escrever códigos TS. Crie o arquivo src/index.ts (arquivo index.ts dentro da pasta src) e digite o seguinte para testar:

const name = 'Otávio Miranda';
console.log(name);

Conforme configuramos o tsconfig.json com strict = true, você não conseguiria executar qualquer JS sem tipagem adequada (alguns sim, outros não). No trecho acima estou usando a inferência de tipos do TypeScript. Porém, se quiser executar qualquer JS normal (sem tipagem) dentro do seu script TS, modifique strict para false.

ts-node

Para usar o ts-node, digite seu código dentro de um arquivo (suponha index.ts) ou use meu código de exemplo (acima) e pressione o play no canto superior direito da tela. Similarmente, você pode simplesmente digitar:

npx ts-node src/index.ts

Se o arquivo index.ts importar qualquer outro módulo, ele será compilado temporariamente apenas para exibir o resultado no terminal. Embora isso não compile códigos reais, é super interessante para execução rápida de códigos on the fly. Contudo, você vai precisar compilar seu código em algum momento. Para isso, use tsc.

tsc

Anteriormente, vimos uma maneira simples para compilar códigos temporariamente (sem criar novos arquivos) com ts-node. Contudo, você vai precisar dos arquivos para produção, afinal, o código JS é que será executado no ambiente de produção. Portanto, para compilar realmente seu código (gerando os arquivos na pasta dist), simplesmente digite no terminal:

npx tsc

O compilador irá usar as configurações no tsconfig.json a fim de gerar nossos arquivos JS. Além disso, ele criará e atualizará a pasta “dist” com os arquivos de saída. Embora não necessário, dê uma olhada nos arquivos gerados na pasta dist.

Depois que compilei o código TS, meu arquivo dist/index.js ficou assim:

'use strict';
const name = 'Otávio Miranda';
console.log(name);

Ou seja, quase nenhuma diferença do arquivo original. Todavia, os arquivos reais de produção devem ficar extremamente diferentes dos originais, vai por mim.

Uma outra forma de compilação é o modo “watch“, onde o tsc fica “assistindo” mudanças no seu código a fim de gerar automaticamente os arquivos de saída. Para usar o modo “watch“, digite:

npx tsc -w

Você vai perceber que o tsc vai ficar assistindo modificações no seu código e atualizando a saída assim que você salvar seu arquivo. Para parar, pressione CTRL + C no terminal.

Prettier e formatação automática (opcional)

Como eu te disse anteriormente, gosto bastante de usar as configurações do “Prettier” e a formatação automática em meus códigos. Embora opcional, você pode fazer essa configuração como mostro abaixo.

Instalando os pacotes do Prettier

Digite o seguinte no terminal:

npm i prettier eslint-config-prettier eslint-plugin-prettier -D

Não tenho muito o que te explicar sobre isso, são pacotes necessários para o funcionamento do Prettier com o ESLint.

Crie um arquivo chamado .prettierrc.js na raiz do seu projeto e cole o seguinte:

module.exports = {
  semi: true,
  trailingComma: 'all',
  singleQuote: true,
  printWidth: 80,
  tabWidth: 2,
};

As configurações são as seguintes:

semi – força o uso de ponto e vírgula;
trailingComma – deixa uma vírgula ao final de arrays, objetos, etc;
singleQuote – prefere o uso de aspas simples
printWidth – tenta quebrar linhas com 80 caracteres ou mais;
tabWidth – usa dois espaços para tab;

Configurando a formatação automática

O legal é que agora você pode acessar as configurações do VSCode e solicitar a formatação automática afim de formatar seu arquivo assim que você salvá-lo. Para isso, clique em "File" > "Preferences" > "Settings". No canto superior direito da tela, clique no ícone "Open settings (JSON)". Por fim, cole o seguinte nas configurações:

{
  // Configurações já existentes
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true,
    "source.fixAll": true,
  },
  // Mais configurações existentes
}

Assim, quando você salvar o seu arquivo, ele será automaticamente formatado com o Prettier e o ESLint.

Ajustando o eslint

Agora, precisamos adicionar o prettier na configuração “extends” do seu .eslintrc.js.

Abra o .eslintrc.js, que atualmente deve estar assim:

module.exports = {
  // outras configs
  extends: [
    'eslint:recommended',
    'plugin:@typescript-eslint/eslint-recommended',
    'plugin:@typescript-eslint/recommended',
  ],
  // outras configs
};

Em extends, adicione 'plugin:prettier/recommended', dessa maneira:

module.exports = {
  // outras configs
  extends: [
    'eslint:recommended',
    'plugin:@typescript-eslint/eslint-recommended',
    'plugin:@typescript-eslint/recommended',
    'plugin:prettier/recommended',
  ],
  // outras configs
};

Como na linha 7 do exemplo acima.

Se você adicionou tudo corretamente, agora o prettier e a formatação automática já devem estar funcionando.

Tipos básicos e inferência de tipos do TypeScript

Até aqui você leu coisas superficiais sobre o TypeScript. Você sabe o que é, como configurar, mas ainda não viu uma das coisas que faz ele ser o que é e ter a popularidade que tem atualmente, os Tipos.

Um perigo: A tipagem fraca e dinâmica do JS

O Javascript é uma linguagem de tipagem fraca e dinâmica. Fraca porque você consegue fazer coisas como 10 / '20' e o JavaScript se vira de alguma maneira pra retornar um 0.5. Quem não conhece JS pode assustar com esse resultado (mas está certo).

Isso pode ser algo ruim do ponto de vista lógico, quando 10 / '20' um seria 0.5? Só podemos presumir que isso foi uma coerção de tipos, portanto, entendemos um dos valores foi convertido pra outro tipo automaticamente. A string 20 foi convertida em number. Isso caracteriza uma linguagem de tipagem fraca.

Linguagens de tipagem forte, provavelmente levantariam uma exceção neste ponto do seu código.

E dinâmica porque você não precisa declarar os tipos com antecedência e o tipo pode mudar ao longo do código, uma variável que muda de valor, também pode mudar de tipo. Em momento algum eu preciso falar que 10 é um number, que true é um boolean, que 'Luiz' é uma string. Ele faz isso automaticamente também. Isso caracteriza uma linguagem de tipagem dinâmica.

Essas duas coisas combinadas podem trazer um benefício excelente, a flexibilidade. É algo extremamente simples escrever códigos em Javascript. Mas, aqui também mora um perigo iminente. Programadores precisam tomar um cuidado extremo e escrever testes além do necessário apenas para garantir que os tipos dos valores estão corretos. Do contrário, um erro assim poderia chegar em produção sem que soubéssemos:

10 / [20, 10]; // NaN

A tipagem forte, estática e inferida do TypeScript

Por outro lado, o TS tem tipagem forte, estática e inferida (a inferência é muito importante aqui, atenção).

Se eu escrevo um código assim no TypeScript, imediatamente tenho um erro, veja:

let number1 = 10; // number
let number2 = '20'; // string
let number3 = number1 / number2;
//                      ^
// The right-hand side of an arithmetic
// operation must be of type 'any',
// 'number', 'bigint' or an enum type.ts(2363)

Aqui o TS usa um recurso muito interessante chamado de inferência de tipos. Perceba que eu deixei comentado os tipos das duas primeiras variáveis (a última foi um erro). Esses tipos foram inferidos automaticamente pelo TypeScript, em momento algum eu disse que 10 era um number e que '20' era uma string. Mas está igual ao JS, tipagem dinâmica? Não!

A inferência de tipos é uma forma do TypeScript modelar o comportamento do JavaScript e também de deixar o seu código mais limpo. Você não precisa adicionar tipagem em coisas óbvias (salvo em casos onde ele não consegue inferir um tipo). No entanto, uma vez que o tipo for inferido, ele não poderá mais ser alterado (e aqui estamos falando em tipo, não em valor).

let number1 = 10; // number
number1 = '20';
//        ^
// Type '"20"' is not assignable to type 'number'.ts(2322)

Em conclusão, minha dica pra você que está iniciando com o TS seria: só coloque tipos em coisas que não são óbvias, evite sair adicionando tipo em todas as suas variáveis. Quando o TS não conseguir inferir um tipo, ele vai te avisar. Use o seu editor para saber qual tipo foi inferido. Geralmente basta passar o mouse sobre a variável e o editor (como o VSCode) irá lhe informar o tipo da variável.

Figura 6. A inferência de tipos consegue saber o tipo de retorno da função e repassar isso para a variável.

Tipos mais básicos

O TS suporta todos os tipos que você tem o costume de usar em JS, como: boolean, number, bigint, symbol, string, array, null, undefined e object. Além disso, ele também adiciona seus próprios tipos, como: any, tuple, void, never e Enum.

A maneira que eu tenho para informar qual o tipo da minha variável, parâmetro ou retorno de funções e métodos é com : (dois pontos). Existem algumas outras maneiras, mas vamos deixar isso de lado por enquanto.

Por exemplo, aqui eu vou quebrar minha própria dica (sobre inferência) e vou adicionar os tipos em tudo o que for possível só pra você ver a estrutura:

/* eslint-disable */
// Se você não desativar o ESLint aqui, não conseguirá
// declarar esses tipos que seriam inferidos naturalmente
const name: string = 'Luiz'; // string
const age: number = 30; // number
const birthday: Date = new Date('1990-06-14T00:00:00-03:00'); // Date
const addresses: Array<string> = ['Rua 1', 'Rua 2']; // array de strings
const parentNames: string[] = ['João', 'Maria']; // array de strings
const isEmployed: boolean = true; // boolean

console.log(`Meu nome é ${name} e tenho ${age} anos.`);
console.log(
  `Nasci em ${birthday.toLocaleString()}, moro em ${addresses.join(', ')}.`,
);
console.log(`Meus pais são ${parentNames.join(' e ')}`);
console.log(`Eu ${isEmployed ? 'estou' : 'não estou'} empregado atualmente.`);

/*
Saída:
Meu nome é Luiz e tenho 30 anos.
Nasci em 14/06/1990 00:00:00, moro em Rua 1, Rua 2.
Meus pais são João e Maria
Eu estou empregado atualmente.
*/

Perceba que todos esses tipos seriam inferidos naturalmente por serem óbvios, basta o TS olhar o valor para saber o tipo. Então, eu poderia limpar drasticamente meu código os removendo.

const name = 'Luiz'; // string
const age = 30; // number
const birthday = new Date('1990-06-14T00:00:00-03:00'); // Date
const addresses = ['Rua 1', 'Rua 2']; // array de strings
const parentNames = ['João', 'Maria']; // array de strings
const isEmployed = true; // boolean

Menos em objetos um pouco mais complexos, como array e date, o TypeScript foi capaz de inferir os tipos.

O ideal seria você adicionar tipos em coisas onde o tipo não é tão óbvio assim. Por exemplo, os parâmetros de uma função não são óbvios, eu poderia passar literalmente qualquer coisa sem que o JS reclamasse. Esses parâmetros devem ter tipos em TypeScript.

// Essa função precisa receber um array de números
// posso representar isso com number[] ou Array<number>
const sumNumbers = (arrayOfNumbers: number[]) => {
  return arrayOfNumbers.reduce((s, v) => s + v);
};

const result = sumNumbers([1, 2, 3]); // number
console.log(result); // 6

Além disso, eu também poderia representar isso com o rest operator (…).

// Agora qualquer parâmetro dessa função deve
// ser um número
const sumNumbers = (...nums: number[]) => {
  return nums.reduce((s, v) => s + v);
};

const result = sumNumbers(1, 2, 3); // number
console.log(result); // 6

Conforme você também pôde notar nos códigos anteriores, a maioria dos tipos básicos são adicionados com letra minúscula: boolean, number, bigint, symbol, string, array, null, undefined e object.

Tipos básicos que existem apenas no TypeScript

Alguns dos tipos que indiquei anteriormente, existem apenas no TypeScript, como any, tuple, void, never e Enum. Então vamos ver quando usá-los:

any

Esse é um tipo que você não gostaria de ter no seu código (a não ser que não tenha outra opção). Significa a mesma coisa que “qualquer coisa” (assim como no JS).

O fato aqui é que tudo precisa ter um tipo em tempo de compilação no TypeScript, quando você não fornecer um tipo e o TSC também não conseguir inferir um tipo correto, o padrão será “any” (qualquer coisa). Assim, você não terá funções de intelliSense (auto completar, erros, etc). O any aceitará literalmente qualquer coisa que você pedir pra ele fazer.

Por exemplo:

// Agora a função recebe qualquer coisa
const sumNumbers = (...anything: any[]) => {
  return anything.reduce((s, v) => s + v);
};

const result = sumNumbers(1, 2, 'a'); // O tipo dessa variável é any
console.log(result); // 3a <- Resultado inesperado

Evite usar any a todo o custo. Quase sempre tem uma opção melhor.

tuple

Uma tupla é um array de tamanho fixo. Por exemplo:

// O tipo é [string, number]
const personFirstNameAndAge: [string, number] = ['Luiz', 30];
console.log(personFirstNameAndAge);

Perceba que a tupla em TypeScript é representada como um array, porém ela é muito mais específica. Os tipos precisam bater exatamente com os valores. No exemplo acima, minha tupla precisa ter uma string na posição 0 e um número na posição 1. Eu consigo alterar os valores apenas se forem do mesmo tipo.

Tupas podem ter quantos valores você quiser, não são apenas dois como no exemplo acima.

void

Embora represente um “não valor”, é interessante em alguns casos representar um método ou função que não tenha retorno, por exemplo:

function showLog(): void {
  console.log('Hey, sou o log.');
}

Essa função não tem retorno, por isso representamos seu retorno com “void”.

never

Você já imaginou um método ou função que NUNCA retorna? Sim, eu posso ter funções que nunca retornam mas lançam um erro. Por exemplo:

function error(): never {
  throw new Error('NUNCA VOU RETORNAR');
}

error(); // Error: NUNCA VOU RETORNAR

O retorno dessa função nunca vai ocorrer, porque o erro ocorre antes.

Enum

Enums são uma maneira de enumerar valores. Uma estrutura de dados não ordenada que mapeiam chaves para valores. São muito usados quando pessoas querem dar um determinado número de opções de escolha (choice).

Por exemplo, na função abaixo, só posso receber parâmetros do tipo “ProgrammingLanguages“, nada mais que isso.

enum ProgrammingLanguages {
  Python,
  JavaScript,
  TypeScript,
}

function yourPreferedProgrammingLanguage(choice: ProgrammingLanguages) {
  console.log(`Você gosta de ${ProgrammingLanguages[choice]}`);
}

// Você gosta de TypeScript
yourPreferedProgrammingLanguage(ProgrammingLanguages.TypeScript);
// Você gosta de JavaScript
yourPreferedProgrammingLanguage(ProgrammingLanguages.JavaScript);
// Você gosta de Python
yourPreferedProgrammingLanguage(ProgrammingLanguages.Python);

// Error
// Argument of type '"Java"' is not assignable to
// parameter of type 'ProgrammingLanguages'.ts(2345)
yourPreferedProgrammingLanguage('Java');

Te confesso que não uso muito essa estrutura (tem outras maneira de fazer “choices” em TS).

Salvando tipos em variáveis

É claro que você também pode reusar os tipos que você cria, para isso você pode usar Type ou Interface. Não vou me aprofundar tanto nisso aqui, porque esse post está mais imenso do que eu poderia imaginar. Porém, você pode ver um tutorial sobre isso aqui para Type e aqui para Interfaces.

Por exemplo, imagine que eu queira criar uma calculadora com funções. Todas as operações serão iguais, add (somar), div (dividir), sub (subtrair), mul (multiplicar). Todas essas funções receberiam x (number) e y (number). Eu posso facilmente criar um Type Alias ou uma Interface para mapear o tipo de todas essas funções a fim de reutilizar a tipagem.

// Usando type para declarar o tipo de uma função
type CalculatorFn = (x: number, y: number) => number;

const add: CalculatorFn = (x, y) => x + y;
const div: CalculatorFn = (x, y) => x / y;
const sub: CalculatorFn = (x, y) => x - y;
const mul: CalculatorFn = (x, y) => x * y;

const onePlusTwo = add(1, 2); // number
console.log(onePlusTwo); // 3

Perceba que o tipo CalculatorFn agora pode ser utilizado em qualquer função que implemente essa assinatura. Além disso, eu já fiz a tipagem dos parâmetros também, então não preciso adicionar tipos de x e y em cada uma das funções.

Similarmente, posso fazer o mesmo com Interfaces (em várias ocasiões, Type Alias e Interfaces podem ser usados para fazer a mesma coisa).

// Usando type para declarar o tipo de uma função
interface CalculatorFn {
  (x: number, y: number): number;
}

const add: CalculatorFn = (x, y) => x + y;
const div: CalculatorFn = (x, y) => x / y;
const sub: CalculatorFn = (x, y) => x - y;
const mul: CalculatorFn = (x, y) => x * y;

const onePlusTwo = add(1, 2); // number
console.log(onePlusTwo); // 3

Para casos mais simples assim, eu prefiro usar Type Alias, para casos mais complexos, talvez use Interfaces.

Eu posso fazer isso com qualquer tipo, por exemplo:

type NumberOrString = number | string; // | significa OU (union type)

function sayIt(it: NumberOrString): void {
  console.log(`Você disse: ${it}`);
}

sayIt(10); // Você disse: 10
sayIt('Olá'); // Você disse: Olá

// Error:
// Argument of type '{}' is not
// assignable to parameter
// of type 'NumberOrString'.
sayIt({});

Perceba também que além de usar Type Alias, também usei Union Type. Da uma lida sobre isso aqui.

Concluindo

Como eu te disse no comecinho, essa seria uma longa introdução ao TypeScript. Falamos sobre muita coisa, porém ainda tem muito, mas muito mais para você aprender. O local que sempre indico para quem me pergunta onde e como aprender TypeScript é na documentação, mais especificamente na parte do Handbook.

Tenho a intenção de trazer mais conteúdo como este aqui para o blog, então fique de olho.

Domínio e hospedagem: guia para leigos

Wed, 04 Apr 2018 00:00:00 GMT

Domínio e hospedagem são duas coisas que caminham de mãos dadas, mas não são a mesma coisa. Nesse tópico, vou deixar claro o que são e como configurar ambos em algumas hospedagens diferentes. Ao final, você poderá configurar seu próprio domínio e hospedagem sem precisar pagar um profissional para isso.

Se você precisa de um site, seja para vender, ter um blog ou qualquer outro fim, vai precisar de duas coisas em seu nome ou da sua empresa: domínio e hospedagem. O domínio é o nome (endereço) do site; a hospedagem é o local onde os arquivos e configurações do site estão.

Ambos estão ligados porque o domínio aponta para o IP do servidor de hospedagem, onde os arquivos do site estão. Desse modo, pessoas que digitarem o domínio do seu site no navegador, serão redirecionadas automaticamente para o servidor de hospedagem.

Geralmente, empresas especializadas em hospedagem de sites têm planos que trazem ambos os serviços em um mesmo pacote. Vamos falar sobre essas empresas posteriormente nesse artigo.

Domínio: o endereço do site

O domínio é o endereço do site em si. Aquele que, geralmente, inicia-se com “www” e termina com “.com” ou “.com.br”. Como www.exemplo.com.br, por exemplo.

Contudo, aqui cabem alguns adendos: não é necessário que um domínio inicie com “www”, mas é recomendado. As partes “.com” e “.br” são domínios de topo e ambos podem ser totalmente diferentes para cada domínio.

Vamos ver, na prática, o que acontece quando o seu domínio é usado no navegador de Internet:

O internauta digita o endereço (domínio) do seu site no navegador;
O navegador busca as configurações do seu domínio no servidor de DNS;
O servidor de DNS diz para o navegador qual o IP da sua hospedagem;
Sua hospedagem diz pro navegador em qual pasta do servidor seu site está;
O navegador faz o download do conteúdo da pasta do seu site na hospedagem para o internauta e mostra na tela.

Assim, para que um domínio funcione corretamente ele precisa de servidores de DNS. Geralmente, esses servidores serão configurados pelo próprio provedor no iqual você o contratou e não precisam ser modificados, porém, é bom que você entenda como eles funcionam.

Um servidor de DNS é quem vai receber a requisição do navegador de internet e direcionar o Internauta para o local onde seu site está hospedado (hospedagem) de acordo com as configurações da Zona de DNS.

A não ser em casos muito específicos, como a configuração de uma rede de distribuição de conteúdo (CDN), você não precisa alterar os servidores de DNS do seu domínio. Mas, se precisar, é só ir no painel do provedor onde você contratou o domínio, acessar a parte de domínios (ou meus domínios) e acessar as configurações do domínio desejado. Certamente, a opção vai se chamar algo similar a “Configurar servidores DNS”, “Alterar Nameservers” ou algo parecido com isso. Ainda assim, vou mostrar como fazer isso em duas hospedagens diferentes mais abaixo.

Dica importante: A “Zona de DNS” tem configurações dentro do servidor de DNS. Portanto, você não precisa alterar o servidor de DNS para configurar um registro dentro da zona de DNS.

Como modificar os Servidores de DNS

Conforme mencionei anteriormente nesse artigo, são poucos os casos em que você precisa alterar os servidores de DNS do seu provedor, mas caso precise, veja como fazê-lo na Uolhost e Hostgator.

Na uolhost

Acesse o painel da uolhost;
Entre com seus dados de usuário e senha;
Acesse o menu “Domínios”;
Role a página até encontrar “Seus domínios”;
Em “Gerenciar”, clique no menu suspenso e acesse a opção “Configurar Servidores DNS”;

Nessa página, você verá 3 opções de servidores “Master”, “Slave 1” e “Slave 2”. Os servidores padrão da Uolhost são:

ns1.dominios.uol.com.br
ns2.dominios.uol.com.br
ns3.dominios.uol.com.br

Nota: A princípio, você não precisa preencher todos os campos, o servidor “Master” é o principal, “Slave 1” e “Slave 2” são servidores secundários. Caso o “Master” não funcione por algum motivo, os servidores secundários serão acionados, entretanto, como o “Master” é o mais importante, geralmente todas as requisições vão pra ele.

Finalmente, clique em “Salvar” após a configuração.

Na hostgator

Acesse a área do cliente;
Entre com seu usuário e senha;
No menu superior vá em “Domínios” > “Meus domínios”;
No menu suspenso ao lado do domínio desejado, clique em “Alterar Nameserver – DNS”;

A hostgator te dá opção para adicionar 5 servidores de DNS, mas você não precisa usar todos caso não tenha milhares de servidores de DNS. O primeiro é o “Master” e o restante secundários.

Configure como quiser e clique em “Alterar Nameserver – DNS”.

Zona de DNS

A zona de DNS armazena registros que especificam os endereços dos serviços do seu site, como ip da hospedagem, servidores de e-mail, subdomínios, entre outros dados específicos do seu domínio.

Existem vários tipos de registros que podem ser configurados na Zona de DNS do seu domínio, dentre eles:

Zona de DNS A zona de DNS armazena registros que especificam os endereços dos serviços do seu site, como ip da hospedagem, servidores de e-mail, subdomínios, entre outros dados específicos do seu domínio.

Existem vários tipos de registros que podem ser configurados na Zona de DNS do seu domínio, dentre eles:

Tipo A – Registro que associa um domínio ao endereço IP de um servidor. O valor sempre será um endereço de IP. Geralmente, o IP da sua hospedagem, mas pode ser outro IP em alguns casos;
CNAME – É um tipo de registro que mapeia um nome de alias para um nome de domínio. Certamente, são muito usados para criar subdomínios ao seu domínio. Por exemplo: suponhamos que você venda um curso online e que esse curso seja uma página separada do restante do seu site. Você pode criar o subdomínio “curso.seudominio.com.br” e mapear isso com um registro CNAME. Contudo, vale lembrar que dentro da hospedagem precisa existir uma pasta específica para esse subdomínio. Sozinho, o registro CNAME não fará nada. Provavelmente, no painel da sua hospedagem existe uma opção para configuração de subdomínios e ela irá criar o registro CNAME, portanto, use-a ao invés de alterar os registros CNAME.
TXT – Registros que podem conter um texto. Normalmente são usados para verificação de domínio. Por exemplo: recentemente adicionei o “Search console” da Google em um site e eles me pediram para verificar a autoridade do domínio com um registro de DNS do tipo TXT.
MX – Registros que tem como destino o servidor responsável por receber os e-mails do domínio. O campo “Prioridade” é usado para definir a prioridade dos servidores (quanto menor o número, maior a prioridade).

Antes que você me pergunte, esses não são todos os tipos de registros de DNS. Caso tenha interesse, veja mais alguns tipos aqui.

Se você contratou domínio e hospedagem no mesmo pacote de uma empresa de hospedagem, certamente não vai precisar se preocupar com essas configurações. Sem dúvida, o pessoal das empresas de hospedagens já deixam o domínio contratado apontando para a hospedagem, de modo que é só enviar os arquivos do site pelo servidor FTP (vamos falar sobre isso também mais adiante) e acessá-los pelo domínio contratado. Afinal, isso é interessante pra eles!

Caso tenha interesse em alterar a zona de DNS, faça o seguinte:

Na uolhost

Acesse o painel;
Entre com seus dados de usuário e senha;
Acesse a opção “Domínios”;
No menu suspenso do domínio desejado, clique em “Alterar Zona de DNS”;
Em “Zona de DNS”, clique em “Gerenciar”; Crie os registros dos tipos desejados e salve.

Na hostgator

Dependendo do seu tipo de hospedagem, pode ser que seja necessário usar o cPanel. Portanto, vou mostrar como encontrar as opções para gerenciar a zona de DNS do seu domínio por ele.

Entre no seu painel;
Na sua hospedagem, clique em cPanel;
Role a página até a sessão “Domínios”;
Você pode usar tanto o “Simple Zone Editor” ou o “Advanced Zone Editor”. No “Simple Zone Editor” você tem algo mais simples e direto, basta escolher o tipo de registro, nome e o valor. Porém, para o “Advanced Zone Editor” é necessário que você entenda o que está fazendo, já que tem todas as opções disponíveis pra você configurar um registro de DNS;

Vale lembrar que o cPanel possui uma área específica para a criação de subdomínios, portanto, não é necessário criar um registro CNAME para um subdomínio, ele fará isso automaticamente. Aliás, se você criar uma entrada CNAME e tentar criar um subdomínio, será apresentado um erro na tela.

Mas, ainda assim, é bom que você saiba como realizar tais configurações.

Whois – Informações de contato

O **whois **serve para identificar o proprietário de um site. Assim, ele é alimentado pela própria empresa de hospedagem e reúne todas as informações pertencentes a uma página. incluindo CNPJ ou CPF de quem o registrou. Além disso, essas informações são públicas, ou seja, se você registrou um domínio em seu nome, eventualmente, alguns dos seus dados serão disponibilizados publicamente online para quem olhar o whois do seu domínio.

São três setores de contato disponíveis no whois: o contato administrativo, o contato técnico e o contato de cobrança. Muitos serviços de hospedagem vão usar o contato do proprietário para todos os setores de contato, todavia, você pode mudar isso no painel da sua hospedagem.

Se você quiser ver o whois de um site, acesse who.is e digite o domínio desejado. Então veja a mágica!

Hospedagem: o local onde seu site está

Agora que você já está fera em domínios, vejamos o que é uma hospedagem.

Embora pareça complicado, uma hospedagem nada mais é do que um espaço que você está alugando para os arquivos e configurações do seu site em um ou vários servidores.

Um servidor pode ser um ou vários computadores que as empresas de hospedagem mantém sempre ligados para que seu site esteja sempre online.

Existem vários tipos de hospedagem que você pode contratar, cada um com seus prós e contras. Mas isso vai depender do nível no qual o seu site está. Quando eu digo nível, estou me referindo a quantidade de acessos e quais serviços serão utilizados.

Embora pareça complexo de início, se você está iniciando e sabe que seu site vai começar a receber visitas neste momento, provavelmente a mais barata irá lhe servir bem, mas é sempre bom verificar se a sua hospedagem oferece upgrade do seu plano, ou seja, se seu site crescer, será fácil pagar um pouco mais para que eles liberem mais recursos do servidor para seu site a medida que precise.

Em uma analogia, seria como se a sua hospedagem fosse um cano, desses que passam água, e os visitantes do site a água. Se a quantidade de água que passar for menor que o diâmetro do cano, tudo funciona muito bem, mas, se a quantidade de água for maior, ela será limitada pelo diâmetro do cano. Assim, se seu site receber mais visitar do que a hospedagem pode suportar, alguns clientes poderão ver páginas de erros do servidor, outros não conseguiram acessar e, certamente, tudo vai ficar muito lento.

Tipos de hospedagem

Separei alguns tipos de hospedagem encontrados comumente nos provedores.

Hospedagem compartilhada

Geralmente, trata-se do pacote mais barato dos provedores. Uma solução excelente para quem está começando e sabe que não terá um turbilhão de visitas de início.

Os provedores conseguem um preço tão em conta porque compartilham os recursos de apenas um servidor com outros sites. Ou melhor, CPU, memória, espaço em disco, tudo isso é compartilhado.

Além disso, esse plano vem todo configurado, portanto você não precisará modificar praticamente nada, nem mesmo as configurações de domínio que mencionei anteriormente nesse artigo.

Contudo, nem tudo são flores. Você não terá praticamente nenhum controle sobre as configurações do seu servidor e, provavelmente, também não terá acesso SSH. Além disso, se algum dos sites do servidor tiver algum pico de visitas ou receber ataques, o desempenho do seu, certamente, será afetado.

Ainda assim, continua sendo um dos melhores e mais populares planos para sites que estão começando ou que recebem poucas visitas.

Hospedagem VPS (Virtual Private Server)

Na hospedagem VPS, apesar de você ainda continuar compartilhando um servidor com outros sites, nesse caso recursos são alocados especificamente para seu site, só que picos em outros sites podem não afetar o desempenho do seu.

Seu provedor vai alocar uma partição do servidor e recursos (CPU e memória) exclusivos para o seu site com possibilidade de expansão caso necessário.

Apesar de mais cara do que a hospedagem compartilhada, pode valer a pena para sites que têm grande prospecção para expansão. Além disso, a empresa também vai te passar dados para que você acesse e altere configurações via SSH, ou seja, você tem acesso e autonomia para configurar determinados serviços dentro do seu “servidor virtual”.

Como nem tudo é um mar de rosas, pode ser necessário conhecimento adicional para trabalhar com hospedagens VPS.

Hospedagem Cloud

Atualmente, a maioria dos provedores oferecem hospedagem “Cloud” (na nuvem). Nesse tipo de hospedagem seu site não estará em um servidor, muito menos compartilhado com outros sites, ele estará alocado em um cluster de servidores (vários servidores). Isso quer dizer que, se algum dos servidores parar de funcionar por algum motivo seu site será realocado para outro servidor e continuará funcionando normalmente.

O fornecimento de recursos também pode ser de acordo com a demanda, ou seja, você pode pagar mais para receber mais recursos. Particularmente, já vi casos em que você paga um valor fixo mensal, mas também já vi casos em que você paga pelo que utiliza.

Aqui você também vai precisar de muito conhecimento adicional. Me lembro quando contratei o primeiro plano cloud para um site em que estávamos trabalhando, o provedor me mandou o IP de um servidor com o Ubuntu Server instalado e usuário e senha, ponto. Não tinha absolutamente nada configurado nesse servidor.

Hospedagem WordPress

Como o próprio nome já diz, é um tipo de hospedagem específica para sites feitos com o WordPress. Já vem até com alguns plugins de segurança e cache configurados. Porém, como é uma hospedagem específica, o site vai performar bem melhor nela pela otimização já realizada pelo provedor.

Os benefícios disso é que é uma hospedagem mais em conta e que não demanda conhecimento. Talvez você nem precise ter conhecimento sobre WordPress em si.

Vale lembrar que se seu site não usa o WordPress, não vale a pena investir nessa hospedagem.

Hospedagem dedicada

Na hospedagem dedicada você tem seu próprio servidor e pode fazer o que quiser com ele, até mudar o sistema operacional, alterar configurações de acordo com suas necessidades ou desligar o servidor quando quiser (dependendo do provedor).

Porém, além de um enorme conhecimento, você vai precisar de grana. É um tipo de hospedagem bem caro.

Minha hospedagem preferida

De todos os planos que já utilizei em vários provedores, pra mim o que mais gostei foi a hospedagem cloud (na nuvem). Além da flexibilidade, nunca vi o serviço fora do ar por nem um segundo em anos.

O que você precisa saber sobre a sua hospedagem?

Quando se contrata uma hospedagem você precisará saber algumas coisas sobre ela para realizar configurações, dentre elas estão o gerenciamento do banco de dados e contas FTP, já que a maioria dos sites que você vai configurar vão utilizar pelo menos um banco de dados e uma conta FTP.

Se a sua hospedagem oferecer o cPanel gratuitamente, tudo fica bem mais simples, porque você não precisará de tanto conhecimento para realizar tais configurações.

Vou mostrar como criar um usuário do banco de dados e um banco de dados para este usuário no cPanel de maneira rápida.

Como criar usuário MySQL e banco de dados no cPanel

Passo 1: Abra o cPanel e acesse “MySQL remoto®”;

Passo 2: Em “Host (o coringa % é permitido)” adicione o “%” (sem aspas) e clique em “Adicionar host”;

Dica: vale lembrar que aqui você está adicionando quais IPs podem acessar seu servidor MySQL. O coringa significa “todos”.

Passo 3: no menu da lateral esquerda, clique novamente em “Banco de dados” e agora acesse a configuração “Bancos de dados MySQL®”;

Passo 4: em “Criar novo banco de dados” adicione o nome do seu banco de dados e clique em “Criar banco de dados”;

Dica: onde adicionei o retângulo vermelho, vai existir um prefixo que a própria hospedagem lhe fornece, isso não é editável, porém faz parte do nome do seu banco de dados.

Passo 5: clique em voltar e role a página até “Adicionar novo usuário”; Preencha os campos “Nome de usuário” (depois do prefixo), “Senha” e “Senha (novamente)”. Por fim, clique em “Criar usuário”;

Passo 6: Clique em “Voltar” e navegue até “Adicionar usuário ao banco de dados”; Em “Usuário”, selecione o usuário que acabou de criar; Em “Banco de dados”, selecione o banco de dados que criamos anteriormente; Por fim, clique em “Adicionar”;

Na nova janela que abriu, clique em “Todos os privilégios” e para finalizar “Fazer alterações”;

Pronto, agora se você precisar dos dados para criar qualquer site, os dados serão:

Servidor MySQL (host): seudominio.com.br;
Usuário do Banco de dados: O usuário que você acabou de criar;
Senha: A senha que você deu para o usuário anteriormente;
Banco de dados: O nome do banco de dados que você acabou de criar.

Vamos ver como criar uma conta FTP a seguir.

Como criar uma conta FTP no cPanel

Contas FTP serão necessárias para que qualquer desenvolvedor envie arquivos pra dentro do seu site. Além disso, você também pode querer ter uma pasta virtual dentro do seu servidor, para fazer backup dos seus arquivos ou coisas do tipo.

Nesse caso, vamos criar uma conta FTP para adicionar arquivos diretamente dentro da pasta do nosso site. Veja como:

Passo 1: Na página inicial do cPanel, em “Arquivos”, clique em “Contas FTP”;

Passo 2: Em “Adicionar conta de FTP” digite o “Fazer login” (nome do usuário), “Senha” e “Senha (novamente)”; Em “Diretório”, adicione apenas “public_html” (que é a pasta onde o site deve estar). Clique em “Criar conta de FTP”.

Passo 3: Para ver os dados de acesso do usuário, role a página um pouco para baixo, encontre o nome de usuário que acabou de criar e clique em “Configurar cliente FTP”;

Serão exibidos os seguintes dados:

Nome de usuário do FTP
Servidor FTP (Host)
FTP & porta FTPS explícita (A porta)

A senha, certamente não será exibida, mas é aquela que você configurou anteriormente ao criar a conta FTP.

Domínio e hospedagem: conclusão

Domínio e hospedagem caminham de mãos dadas, mas não são a mesma coisa. Conforme expliquei amplamente anteriormente, domínio trata-se do nome do site e é que encaminha o usuário para o local correto na hospedagem.

A hospedagem em si é um espaço no servidor onde os arquivos e configurações do site estão.

Apesar de não serem a mesma coisa, um depende muito do outro para o bom funcionamento de tudo o que é online atualmente.

Dicas de nomes de domínio

Pra finalizar, algumas dicas para não errar na hora de criar seu domínio:

Tente usar uma ou duas palavras apenas (sempre que possível) pra ficar fácil de lembrar;
Se o domínio em nome de sua empresa já existir, tente colocar termos antes do nome da empresa. Por exemplo: para um e-commerce, pode adicionar “loja” + “nomedaempresa”;
Se não conseguir mesmo assim, pegue o contato do proprietário do domínio pelo registro whois (expliquei anteriormente nesse artigo);
Não utilize nomes que não sejam relacionado com a sua empresa. Os e-mails do seu domínio terão o nome do seu domínio ao final, exemplo: meuemail@meudominio.com.br;
Você não precisa utilizar os famosos “.com” ou “.com.br”, existem milhares de extensões de domínio possíveis. Exemplo: .net, .tv, .website, .biz e assim por diante.

Caso tenha ficado alguma dúvida, não hesite em comentar nesse artigo.

Até a próxima 🙏!

Instalando o certificado SSL-TLS grátis da Let’s Encrypt

Wed, 04 Apr 2018 00:00:00 GMT

Nesse artigo você vai aprender a instalar e configurar o certificado SSL-TLS grátis da Let's Encrypt em quantos domínios preferir. É HTTPS gratuito para todos os seus sites.

Quando falamos em comércio eletrônico, estamos falando em duas coisas extremamente importantes e sensíveis: dados pessoais e dinheiro. Portanto, a segurança é primordial para que todos os dados passem através de conexões seguras.

Certamente, você já deve ter ouvido algum especialista em segurança online explicando que, uma das primeiras coisas a se verificar para saber se um e-commerce qualquer é seguro, é verificar se ele possui “aquele cadeado” falando que a conexão é segura (ou, ao invés de usar HTTP no início do domínio, usar HTTPS).

Na verdade, todos os sites que utilizam HTTPS (Hyper Text Transfer Protocol Secure) têm uma camada adicional de segurança que usa o protocolo SSL-TLS. Essa camada de segurança permite que dados sejam transmitidos por uma conexão criptografada que verifica a autenticidade do servidor e do computador cliente usando certificados SSL-TLS. A porta TCP usada pelo HTTPS é a 443.

Falando em modo superficial, qualquer dado pessoal que o cliente digitar em um site com HTTPS, só poderá ser lido no servidor para o qual ele foi enviado. Se, por algum motivo, algum hacker consiga capturar os dados no meio do caminho, esses dados estarão fortemente criptografados e seria quase impossível lê-los (digo “quase”, porque nunca se sabe, né?).

Além disso, se você se preocupa com SEO (aparecer primeiro nas buscas), HTTPS também deverá ajudar seu site a se posicionar melhor no google, por exemplo.

A Let's Encrypt é uma autoridade de certificação lançada em 12 de abril de 2016, que fornece certificados SSL-TLS grátis através de um processo automatizado, criado para eliminar a complexidade dos processos atuais de criação, validação, instalação e renovação de certificados para sites seguros. Sua intenção é fazer com que toda a Internet use HTTPS por uma web mais segura.

Com poucos comandos você conseguirá instalar e configurar seu certificado SSL-TLS, habilitando assim HTTPS para seu site.

Então vamos às configurações. Bora lá!

Antes de começar

Este tutorial é voltado para a instalação do certificado SSL-TLS grátis da Let’s Encrypt diretamente no servidor, sendo, assim, não vou me atentar para hospedagens que ofereçam este recurso em seus respectivos painéis. Se a sua hospedagem oferece certificado SSL gratuito (certamente, é da Let’s Encrypt), por favor, utilize o próprio painel da hospedagem para habilitar HTTPS no seu site, certamente, eles têm um tutorial explicando como realizar tal procedimento.

No momento da criação deste tutorial, estou usando o Debian 9. Este tutorial deverá funcionar perfeitamente em qualquer versão baseada em Debian (Ubuntu, Linux Mint e assim por diante).

Vou explicar como instalar e configurar o certificado. Posteriormente no artigo, explicar como configurar um server block para Nginx e como configurar um Virtualhost para Apache.

Se você ainda não instalou nem configurou nenhum desses servidores Web, siga um dos tutoriais abaixo:

Feito isso, agora é só prosseguir com o tutorial.

Instalando o certbot

certbot é o cliente que vai buscar os certificados da Let’s Encrypt. Muito fácil de usar e instalar.

Para instalar basta digitar:

sudo apt-get install certbot

No seu terminal.

Instalando o certificado SSL-TLS

Após a instalação do certbot, você precisa parar os serviços que rodam na porta 80 (apache ou nginx). Para isso basta digitar:

# Para o nginx
service nginx stop
# Para o apache2
service apache2 stop

E para instalar o certificado SSL-TLS digite:

sudo certbot certonly --standalone -d meudominio.com.br -d www.meudominio.com.br

A única coisa que você precisa alterar são os domínios. Geralmente, um domínio tem duas versões:

meudominio.com.br
www.meudominio.com.br

Ambas apontando para o mesmo local, se esse for o seu caso, no comando acima altere apenas a parte “meudominio.com.br” para o seu domínio nos dois locais.

Se o seu domínio tem apenas uma versão, use o seguinte comando:

sudo certbot certonly --standalone -d meudominio.com.br

Você deverá receber uma mensagem dizendo que está tudo OK, por exemplo:

IMPORTANT NOTES:
- Congratulations! Your certificate and chain have been saved at
  /etc/letsencrypt/live/meudominio.com.br/fullchain.pem.
  Your cert will expire on 2018-11-23. To obtain a new or tweaked
  version of this certificate in the future, simply run certbot
  again. To non-interactively renew *all* of your certificates, run
  "certbot renew"
- If you like Certbot, please consider supporting our work by:

  Donating to ISRG / Let's Encrypt:   https://letsencrypt.org/donate
  Donating to EFF:                    https://eff.org/donate-le

Isso quer dizer que seu certificado SSL-TLS foi salvo em /etc/letsencrypt/live/meudominio.com.br/.

Para cada domínio você terá uma pasta com o nome do domínio em questão. Portanto, se você tem mais de um domínio, siga os mesmos passos para gerar um certificado SSL-TLS para cada um deles.

Configurando um Server Block no nginx

Depois de criar seu certificado SSL-TLS, agora você precisa falar para o nginx as configurações SSL. Para isso acesse o server block do seu site em /etc/nginx/sites-enabled/meudominio.com.br (ou o nome que você deu para o server block do seu site).

sudo nano /etc/nginx/sites-enabled/meudominio.com.br

E adicione as linhas a seguir em vermelho:

server {
	listen 80;
	listen [::]:80;

	listen 443 ssl http2;
	listen [::]:443 ssl http2;

	ssl_certificate /etc/letsencrypt/live/meudominio.com.br/fullchain.pem;
	ssl_certificate_key /etc/letsencrypt/live/meudominio.com.br/privkey.pem;
	ssl_trusted_certificate /etc/letsencrypt/live/meudominio.com.br/chain.pem;

	ssl_session_cache shared:SSL:10m;
	ssl_session_timeout 5m;

	ssl_prefer_server_ciphers on;
	ssl_ciphers ECDH+AESGCM:ECDH+AES256:ECDH+AES128:DH+3DES:!ADH:!AECDH:!MD5;

	# Desativa SSLv3
	ssl_protocols TLSv1 TLSv1.1 TLSv1.2;

	# Diffie-Hellman
	# $ sudo openssl dhparam -out /etc/ssl/certs/dhparam.pem 2048
	ssl_dhparam /etc/ssl/certs/dhparam.pem;

	# Ativa HSTS
	add_header Strict-Transport-Security "max-age=63072000; includeSubdomains";

	# Ativa OCSP stapling
	ssl_stapling on;
	ssl_stapling_verify on;
	resolver 8.8.8.8 8.8.4.4 valid=300s;
	resolver_timeout 5s;

	root /var/www/meudominio.com.br/public_html/;

	# Add index.php to the list if you are using PHP
	index index.html index.htm index.nginx-debian.html index.php;

	server_name meudominio.com.br www.meudominio.com.br;

	location / {
		try_files $uri $uri/ =404;

		# Para WordPress
		# try_files $uri $uri/ /index.php?q=$uri&$args;
	}

	# Passa scripts PHP para o servidor FastCGI (PHP-FPM)
	#
	location ~ \.php$ {
		include snippets/fastcgi-php.conf;
		fastcgi_intercept_errors on;

		#fastcgi_index index.php;
		if (!-f $realpath_root$fastcgi_script_name) {
			return 404;
		}

		fastcgi_buffers 16 16k;
		fastcgi_buffer_size 32k;

		include /etc/nginx/fastcgi_params;
		fastcgi_pass 127.0.0.1:9010;
	}

	location ~ /\. {
		access_log off;
		log_not_found off;
		deny all;
	}

	access_log off;
	error_log   /var/log/nginx/meudominio.com.br-error.log;
}

As linhas em vermelho no trecho do server block acima configuram SSL no seu nginx.

Mais uma coisinha: você precisa executar mais um comando para prevenir ataque contra chaves Diffie-Hellman no OpenSSL.

Para isso digite:

sudo openssl dhparam -out /etc/ssl/certs/dhparam.pem 4096

Atenção: isso vai demorar mmmmmmmmmmmuuuuuuuuuuuiiiiiiiiitooo.

Por fim, não se esqueça de iniciar o nginx novamente.

sudo service nginx start

Em caso de erros, provavelmente são os caminhos dos arquivos, verifique se estão todos em seus devidos locais.

Configurando um Virtualhost no Apache

Se você usa apache, altere seu virtualhost digitando:

sudo nano /etc/apache2/sites-enabled/meudominio.com.br.conf

Claro, você precisa alterar o comando acima para o nome do seu virtualhost.conf.

Eu criei um virtualhost simples aqui no apache na porta 80 que ficou assim:

<VirtualHost *:80>
    ServerAdmin webmaster@meudominio.com.br
    DocumentRoot /var/www/meudominio.com.br/public_html
    ServerName meudominio.com.br
    ServerAlias www.meudominio.com.br

    CustomLog /var/log/apache2/access-meudominio.com.br.br.log combined
    ErrorLog /var/log/apache2/error-meudominio.com.br.br.log

    <FilesMatch "\.php$">
        <If "-f %{SCRIPT_FILENAME}">
            SetHandler "proxy:fcgi://127.0.0.1:9010"
        </If>
    </FilesMatch>

    <Directory "/var/www/meudominio.com.br/public_html">
        Options FollowSymLinks MultiViews
        AllowOverride All
        Order allow,deny
        allow from all
    </Directory>
</VirtualHost>

Um virtualhost bem básico com PHP-FPM.

Para certificado SSL-TLS, vou clonar esse virtualhost, porém adicionando algumas coisinhas, veja:

<VirtualHost *:443>
    ServerAdmin webmaster@meudominio.com.br
    DocumentRoot /var/www/meudominio.com.br/public_html
    ServerName meudominio.com.br
    ServerAlias www.meudominio.com.br

    <FilesMatch "\.php$">
        <If "-f %{SCRIPT_FILENAME}">
            SetHandler "proxy:fcgi://127.0.0.1:9010"
            #SetHandler "proxy:unix:/var/run/php/php7.2-fpm-om.sock|fcgi://127.0.0.1:9010/"
        </If>
    </FilesMatch>

    <Directory "/var/www/meudominio.com.br/public_html">
        Options FollowSymLinks MultiViews
        AllowOverride All
        Order allow,deny
        allow from all
    </Directory>

    CustomLog /var/log/apache2/access-meudominio.com.br.br.log combined
    ErrorLog /var/log/apache2/error-meudominio.com.br.br.log

    SSLEngine on

    SSLProtocol             all -SSLv2 -SSLv3
    SSLCipherSuite          ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256:ECDHE-ECDSA-AES128-SHA:ECDHE-RSA-AES256-SHA384:ECDHE-RSA-AES128-SHA:ECDHE-ECDSA-AES256-SHA384:ECDHE-ECDSA-AES256-SHA:ECDHE-RSA-AES256-SHA:DHE-RSA-AES128-SHA256:DHE-RSA-AES128-SHA:DHE-RSA-AES256-SHA256:DHE-RSA-AES256-SHA:ECDHE-ECDSA-DES-CBC3-SHA:ECDHE-RSA-DES-CBC3-SHA:EDH-RSA-DES-CBC3-SHA:AES128-GCM-SHA256:AES256-GCM-SHA384:AES128-SHA256:AES256-SHA256:AES128-SHA:AES256-SHA:DES-CBC3-SHA:!DSS
    SSLHonorCipherOrder     on
    SSLCompression          off

    SSLOptions +StrictRequire

    SSLCertificateFile /etc/letsencrypt/live/meudominio.com.br/fullchain.pem
    SSLCertificateKeyFile /etc/letsencrypt/live/meudominio.com.br/privkey.pem
</VirtualHost>

As partes em vermelho do código são as partes que adicionei para o certificado SSL-TLS.

Você também precisa ativar o módulo SSL do apache2, para isso digite:

sudo a2enmod ssl

Lembre-se também que, no apache, você precisa ter os dois virtualhosts, o da porta 80 e o da porta 443.

Para finalizar, inicie o apache:

service apache2 start

Prontinho, só testar.

Até a próxima!

SSH keys: chaves de autenticação SSH

Wed, 04 Apr 2018 00:00:00 GMT

SSH keys são chaves de autenticação SSH para aprimorar a segurança do servidor remoto. Nesse artigo você vai aprender a configurar o par de chaves pública/privada no seu computador local (com Linux ou Windows) e no servidor remoto.

Se você administra um servidor e este funciona constantemente online, provavelmente faz acesso a ele via SSH (Secure Shell). E, se já faz algum tempo que esse seu servidor está online, é certo que já deve ter visto algumas coisas estranhas nos logs, como tentativas de login no seu arquivo /var/log/auth.log vindas de vários IPs diferentes. Isso, provavelmente, pode ser alguém tentando fazer brute force no seu servidor.

Existem várias maneiras de prevenir brute force, e vários outros ataques, apenas manipulando regras de firewall. Um bom exemplo disso é a Google Cloud, que permite liberar portas específicas nas VMs apenas para sua rede, porém, não são todos os provedores que permitem tal configuração.

Outra forma muito eficaz para aumentar a segurança do seu servidor e ainda prevenir brute force é usar as SSH Keys (chaves de autenticação SSH) e eliminar a possibilidade de login por senha.

As SSH Keys funcionam no modo chave pública e chave privada (sempre em pares), onde a conexão SFTP/SSH só é autorizada se a chave privada do usuário do computador cliente bater com a chave pública do usuário do servidor.

Soa um tanto complexo, né? Mas você vai entender direitinho ao terminar esse artigo.

Antes de continuar

Será necessário um servidor com OpenSSH instalado e um usuário com acesso sudo nesse servidor.

Atenção: se você está fazendo isso em um servidor de produção, não feche sua conexão SSH antes de criar uma nova conexão e conseguir se conectar com sucesso. Do contrário, pode ser que você perca acesso SSH e SFTP ao servidor. Além disso, preste bastante atenção no que está fazendo para conseguir voltar as configurações anteriores caso necessário.

Divergência de usuários

É importante que você saiba que não é necessário que os usuários do computador local e do servidor remoto tenham o mesmo nome, ou seja, você pode criar uma chave para um usuário chamado “Joãozinho” no computador local, porém ele vai se conectar no usuário “Zézinho” no servidor remoto.

Porém, a chave privada do usuário Joãozinho precisa bater com a chave pública do usuário Zézinho no servidor.

Criando SSH Keys no Linux

Se o seu computador local tem o Linux com OpenSSH instalados, basta digitar o seguinte:

ssh-keygen -t rsa

Ao pressionar “Enter” você verá algo parecido com:

Generating public/private rsa key pair.
Enter file in which to save the key (/home/joaozinho/.ssh/id_rsa):
Created directory '/home/joaozinho/.ssh'.
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in /home/joaozinho/.ssh/id_rsa.
Your public key has been saved in /home/joaozinho/.ssh/id_rsa.pub.
...

Na primeira linha é requisitado que você especifique onde deseja gerar a chave. Não é necessário alterar este local, ela será gerada na sua pasta local dentro de uma pasta oculta chamada .ssh.

Atenção: em “Enter passphrase”, digite uma senha forte e que você se lembre posteriormente. Essa senha sempre será utilizada para realizar a primeira conexão SSH com o servidor. Assim, se você perder ou alguém roubar sua chave, não conseguirá acesso ao servidor sem saber sua “senha forte”. Será necessário repetir essa senha na linha “Enter same passphrase again”.

Criando uma SSH Key para outro usuário no Linux

Apesar de ser algo privado de um usuário e ele mesmo deveria criar e guardar sua própria chave, você pode gerar uma chave para outro usuário apenas alterando o caminho onde ela é salva no comando explicado anteriormente.

Mas, se você tem acesso sudo no computador, pode digitar o seguinte:

sudo -u joaozinho ssh-keygen -t rsa

Apenas altere “joaozinho” para o nome de usuário que deseja criar a chave. Se você não alterar nada, as chaves pública e privada serão geradas na pasta .ssh dentro da home do usuário “joaozinho”.

Como ver a chave pública

Como é a chave pública que será copiada para o servidor, você só vai precisar copiar ela. Para isso, digite:

cat /home/joaozinho/.ssh/id_rsa.pub

Apenas altere “joaozinho” para o seu usuário ou nome de usuário que deseja copiar a chave.

Lembre-se que as permissões desse arquivo são voltadas para o usuário do arquivo, se você estiver criando para outro usuário, precisará usar sudo para executar esse comando.

sudo cat /home/joaozinho/.ssh/id_rsa.pub

Você vai ver muitos caracteres, começando com “ssh-rsa”. Selecione e copie todos os dados dessa linha. Essa é a chave pública do seu usuário que será copiada para o servidor posteriormente nesse artigo.

Criando SSH Keys no Windows

No Windows você vai precisar do Putty para gerar seu par de chaves pública e privada. Baixe o no link a seguir:

Baixar Putty

Baixe o instalador com extensão .msi e instale no seu computador.

Depois de instalado, pressione simultaneamente as teclas “Windows” + “R” e digite:

%programfiles%\Putty

E pressione “Enter”.

Dentro da pasta do PuTTY, abra o arquivo puttygen.exe. Clique em “Generate” e mova o mouse próximo a barrinha de carregamento até terminar.

Na imagem abaixo detalho o que você precisa fazer dentro do puttygen:

Copie sua chave pública para o servidor, como explico na próxima etapa.

Não se esqueça que, para se conectar ao servidor remoto, você primeiro precisa carregar sua chave privada.

Adicione chave pública no servidor remoto

Depois de criar suas chaves, você vai precisar copiar sua chave pública para o servidor. Para isso, basta criar um arquivo chamado “authorized_keys” dentro da pasta .ssh do usuário desejado dentro do servidor.

Por exemplo: suponhamos que eu queira dar autorização para o usuário “Joãozinho” (usado no linux anteriormente) para acessar o servidor remoto como o usuário “Zézinho”. Então eu digitaria o seguinte no servidor remoto:

sudo mkdir --mode=600 /home/zezinho/.ssh/
sudo nano /home/zezinho/.ssh/authorized_keys

E colocaria a chave pública do “Joãozinho” dentro do arquivo “authorized_keys” do “Zézinho”.

Agora cole os dados da sua chave pública dentro desse arquivo e pressione “CTRL” + “O” para salvar, “CTRL” + “X” para sair.

Se vários usuários poderão se conectar usando o usuário do servidor remoto, adicione uma chave pública por linha no authorized_keys.

Pronto, configuramos os usuários, agora vamos configurar o OpenSSH.

Configurando o OpenSSH

Dentro do servidor remoto, digite o seguinte:

sudo nano /etc/ssh/sshd_config

E altere as linhas:

# ...
PermitRootLogin no
# ...
PubkeyAuthentication yes
# ...
PasswordAuthentication no
# ...

PermitRootLogin remove completamente o acesso do root ao servidor SSH, PubkeyAuthentication permite o acesso via chave pública e PasswordAuthentication remove o acesso via senhas de texto.

Pressione “CTRL”+”O” para salvar e reinicie o servidor SSH:

sudo service ssh restart

Atenção: não feche sua conexão SSH atual. Para testar, abra uma nova conexão SSH, se der errado você não perderá sua conexão atual.

É isso, se tiver dúvidas comenta aí.

Otávio Miranda

DeepSeek V4, agentes embutidos e App Runner: IA vira infraestrutura de verdade

DeepSeek V4 volta como história de runtime, não só de modelo

Feldera puxa agentes para dentro do software

O caso da matemática mostra o gargalo da verificação

AWS App Runner fecha para novos clientes e vira lição de plataforma

npm e PyPI continuam sendo parte da superfície de ataque

Destaques rápidos

Acompanhamento de tendências

GPT-5.5, Claude Code e DeepSeek V4: agentes de IA viram infraestrutura

GPT-5.5 chega na API com cara de plataforma de agentes

DeepSeek V4 volta, mas agora o assunto é cache e custo de agente

Anthropic mostra que agente pode piorar sem o modelo "piorar"

Kali365 mostra por que MFA não basta quando a sessão é autorizada

GitNexus, Stash e VT Code mostram a pilha em volta do modelo

Destaques rápidos

Acompanhamento de tendências

Fechando o quadro

DeepSeek V4, Ubuntu 26.04 e MCP: infraestrutura e segurança voltam ao centro da IA

DeepSeek V4 empurra a briga para contexto longo barato

Ubuntu 26.04 LTS muda detalhes que pegam em servidor e container

Papers novos mostram que agente seguro não é só prompt seguro

Abrir arquivo com segurança ainda é uma armadilha real

Destaques rápidos

Acompanhamento de tendências

Fechando o quadro

GPT-5.5 apareceu no Codex hoje. Peguei no pulo.

O que a OpenAI está prometendo

Codex, contexto e preço

A parte de segurança

Minha impressão de primeira hora

Fontes

Terrarium, Lazarus e benchmarks: 4 alertas sobre segurança e infraestrutura de agentes de IA

Terrarium mostra como um sandbox pode virar parte do problema

A campanha descrita pela Expel leva o ataque direto para o workflow do dev

Benchmarks de agentes podem mudar bastante só por causa da infraestrutura

Managed Agents reforça uma separação que muita stack ainda ignora

Destaques rápidos

Acompanhamento de tendências

Fechando o quadro

Paperclip: empresa de IAs que funciona sozinha (será?)

Em vídeo

Vibe Coding (pera, deixa eu explicar primeiro)

Evite gastar tokens demais

Quando vale a pena?

Onde eu não acho que isso vale a pena

O que eu levei dessa experiência

Guia de sobrevivência Bash e Shell Script (Sério!)

Fundamentos e redes de segurança: escrevendo scripts Bash sem susto

Tratamento de erro sem autoengano

O modo estrito moderno

POSIX vs recursos específicos do Bash (ou zsh)

ShellCheck ajuda bastante

Quando NÃO usar Bash

Variáveis e expansões avançadas: além de $var

Arrays: pare de fingir com string separada por espaço

Expansão de parâmetros

O inferno das aspas

Variáveis indiretas e nameref: dinamismo sem eval

Controle de processos e sinais: aqui o shell começa a aprontar

Substituição de processo: quando pipe não resolve

Traps: cleanup de verdade

Job control: bom no terminal, outra história em script

Subshells vs grupos de comando

Padrões do mundo real: Bash de produção

Parsing de argumentos sem gambiarra

Arquivos de configuração: dados, não código surpresa

Logging e debug sem virar bagunça

Testando script Bash sem sofrimento

Segurança e produção: onde Bash para de ser brincadeira

As armadilhas de segurança

Injeção de comando: o botão vermelho do eval

Corrida com arquivo temporário: mktemp ou arrependimento

Segredos: o que NÃO fazer

Quando o Bash fica lento (e quando isso não importa)

CI/CD: códigos de saída são sua API

ShellCheck no CI

Docker: o problema do PID 1

Padrões de deploy

Publicando sem surpresa

Variáveis e expansões avançadas: além de `$var`

Variáveis indiretas e nameref: dinamismo sem `eval`

Injeção de comando: o botão vermelho do `eval`

Corrida com arquivo temporário: `mktemp` ou arrependimento

O truque do `.pth`: por que a versão 1.82.8 é diferente

Local Forward (`-L`): "trago a porta de lá pra cá"

Remote Forward (`-R`): "mando minha porta pra lá"

Dynamic Forward (`-D`): proxy SOCKS

Tunnels persistentes com `autossh`