Blog do Riverfount

mongo_bakery: o fim da factory que você escrevia pra cada Document do MongoEngine

Sun, 16 Aug 2026 00:00:00 +0000

O teste queria garantir uma coisa só: cancelar um pedido pendente devolve 200. Pra chegar até essa asserção, ele teve que passar por isso primeiro:

asyncio.TaskGroup: quando gather não é suficiente

Wed, 12 Aug 2026 00:00:00 +0000

Um endpoint de checkout dispara três operações concorrentes com asyncio.gather: cobra o cartão, reserva o estoque, envia a notificação de confirmação do pedido. O serviço de pagamento cai no meio da chamada e lança uma exceção. gather propaga esse erro imediatamente para quem está aguardando. O handler captura a exceção, devolve um 500 para o cliente, registra a falha no log. Para quem está de plantão, o sistema reagiu do jeito certo.

Protocol: duck typing com garantias em tempo de análise

Wed, 22 Jul 2026 00:00:00 +0000

Você herdou um sistema de cálculo de descontos. Não tem classe base, não tem ABC, não tem interface formal nenhuma. Cada tipo de desconto (cupom, fidelidade, campanha sazonal) é só uma classe qualquer com um método aplicar(pedido) que devolve o valor final. O código que orquestra isso nem sabe que tipo de objeto está recebendo, só chama desconto.aplicar(pedido) e segue em frente. Duck typing raiz: se anda como pato e grasna como pato, aplica desconto como pato.

O backend não ficou pronto e o frontend não pode esperar

Sat, 11 Jul 2026 00:00:00 +0000

Você está construindo a tela de uma lista de tarefas. Os componentes estão prontos, o layout se comporta em qualquer largura de tela, e falta uma única coisa: buscar as tarefas de algum lugar. Só que a API que deveria devolver essas tarefas ainda não existe. Está na fila de outra equipe, ou é você mesmo que vai escrevê-la depois. Talvez em FastAPI, talvez em Django, quando o frontend já estiver de pé. De qualquer forma, hoje ela não responde, e o fetch que você acabou de escrever aponta para o nada.

O bug que o mypy teria pego antes do deploy

Fri, 26 Jun 2026 00:00:00 +0000

A função recebe um pedido vindo de uma integração externa, soma o valor de cada item e aplica um desconto. Em homologação, com os pedidos de teste, funciona perfeitamente. Em produção, na terceira semana, um cliente específico começa a receber o erro TypeError: unsupported operand type(s) for +: 'float' and 'str' em pleno checkout.

def calcular_total(itens: list) -> float:
    total = 0
    for item in itens:
        total += item["preco"] * item["quantidade"]
    return total - item.get("desconto", 0)

Note que a assinatura já tem uma anotação de tipo: itens: list. Ela não é falsa, mas é rasa o suficiente para não dizer nada de útil. list não revela que cada elemento é um dicionário com chaves específicas, nem que desconto deveria ser numérico. Essa anotação solta passa pelo code review sem levantar suspeita, porque parece tipagem, mas não carrega informação nenhuma sobre o formato real dos dados. É esse tipo de anotação incompleta, não a ausência total de anotação, que vai aparecer recorrentemente neste artigo como o verdadeiro adversário.

Decisões de arquitetura para uma integração com webhook, retry e fallback

Thu, 18 Jun 2026 00:00:00 +0000

Você precisa integrar com dois serviços externos de avaliação de crédito, e eles não se parecem em nada na hora de responder. O principal recebe a proposta, processa por alguns minutos e te chama de volta por um webhook. O fallback — acionado só quando o principal falha — não chama ninguém: você é quem precisa ficar perguntando se ele já terminou. A tentação é tratar tudo isso como uma chamada com um try/except em volta. No caminho feliz, funciona. É no resto que mora este artigo.

suas queries do SQLAlchemy podem ser cacheadas sem Redis manual

Tue, 02 Jun 2026 00:00:00 +0000

O pool está configurado. As queries têm índice. O lru_cache eliminou as buscas repetidas nos endpoints mais simples. Mesmo assim, um endpoint de relatório continua lento, não porque está mal escrito, mas porque ele é genuinamente caro: agrega dados de várias tabelas, cruza informações de três meses, e faz isso a cada requisição, mesmo que os dados subjacentes não mudem por horas.

O lru_cache não resolve. Ele cacheia por argumentos exatos, e os filtros de data variam o suficiente para inviabilizar o hit rate. O Redis resolve, mas exige serializar o resultado manualmente, gerenciar a chave, decidir em que camada a invalidação acontece, código de infraestrutura espalhado pela camada de negócio. O que falta é uma abstração que entenda o ORM.

Por que a aplicação travava mesmo com queries rápidas

Tue, 05 May 2026 00:00:00 +0000

O profiling não encontrou nada. As queries estão com índice, rodam em menos de 5ms, e o cache eliminou as buscas repetidas. Mas sob carga — dez, vinte requisições simultâneas — a aplicação trava. Requisições acumulam na fila, o tempo de resposta explode, e o log mostra um erro que parece absurdo: TimeoutError: QueuePool limit of size 5 overflow 10 reached.

O banco de dados não está sobrecarregado. As queries são rápidas. O problema está entre a aplicação e o banco — no pool de conexões que ninguém configurou.

Sua aplicação está buscando os mesmos dados várias vezes

Fri, 17 Apr 2026 00:00:00 +0000

O profiling apontou um endpoint lento. Você abre o relatório do cProfile, ordena por cumtime, e o topo está dominado por chamadas ao banco de dados. Antes de qualquer coisa: se o problema for N+1 queries, cache não é a solução — é um emplastro. N+1 se resolve na query, com joins, selectinload ou subqueries conforme o ORM. Depois disso, índices. Cache entra só se, após a query estar correta e os índices no lugar, a performance ainda não for suficiente.

Hypothesis encontra os bugs que seus testes ignoram

Tue, 14 Apr 2026 00:00:00 +0000

A suite de testes está verde. Fixtures bem organizadas, parametrize cobrindo os casos óbvios, mocks isolando as dependências externas. Cobertura em 94%. O PR passa no CI e vai para produção.

Três dias depois, um usuário reporta um comportamento estranho. Você reproduz o bug localmente com um input que nunca ocorreu a ninguém testar: uma string vazia em que se esperava pelo menos um caractere, um número negativo em que a função assumia valores positivos, uma lista com um único elemento no qual a lógica de comparação silenciosamente quebra. O teste que teria pego isso seria trivial de escrever — se alguém tivesse pensado em escrever.

dataclass, NamedTuple, attrs ou pydantic: qual usar de verdade?

Fri, 10 Apr 2026 00:00:00 +0000

Existe um ponto no crescimento de qualquer projeto Python em que os dicionários começam a doer. Não de vez — vai acontecendo aos poucos. Você passa um dict para uma função, a função passa para outra, e em algum momento ninguém mais sabe ao certo quais chaves estão garantidas, qual é o tipo de cada valor, ou o que acontece se uma chave estiver faltando.

def calcular_desconto(pedido: dict) -> float:
    # pedido tem "valor"? "valor_bruto"? "subtotal"?
    # "cliente" é um dict também? tem "nivel"?
    return pedido["valor"] * _fator(pedido["cliente"]["nivel"])

Funciona. Ninguém vai questionar em code review. O problema aparece três meses depois, quando alguém passa um pedido sem a chave "nivel" — ou quando você tenta debugar e o repr do dicionário tem quarenta chaves misturadas.

O .env que você não deveria ter commitado

Mon, 06 Apr 2026 00:00:00 +0000

Existe uma busca no GitHub que retorna milhares de resultados úteis para um atacante: filename:.env DB_PASSWORD. Repositórios públicos com arquivos .env commitados por acidente, contendo senhas de banco, chaves de API, segredos JWT — tudo em texto claro, indexado, pesquisável.

Não é incompetência. É o resultado natural de uma prática que parece razoável: colocar credenciais num arquivo, adicionar esse arquivo ao .gitignore, e confiar que o .gitignore vai proteger. Funciona até o dia que não funciona — um git add . no momento errado, um novo membro do time que clona o repo e cria o .env a partir do .env.example sem perceber que o exemplo já tem valores reais, ou um editor que cria arquivos temporários fora do padrão ignorado.

JWT: três erros que todo mundo comete na primeira implementação

Thu, 26 Mar 2026 00:00:00 +0000

Você abre o README do PyJWT, copia o exemplo de dez linhas, gera um token, valida do outro lado — e funciona. O token tem o user_id, expira em uma hora, a assinatura bate. O que pode estar errado?

Bastante coisa. JWT é um dos padrões mais mal implementados em aplicações web, não porque seja complicado, mas porque os exemplos básicos funcionam mesmo com configurações que criam vulnerabilidades sérias. O código roda, os testes passam, e os problemas aparecem meses depois — ou não aparecem, porque ninguém tentou explorar.

A GIL finalmente saiu do caminho: o que muda com o Python 3.14 free-threaded

Mon, 23 Mar 2026 00:00:00 +0000

Você tem quatro núcleos disponíveis. Seu script Python usa um. Isso nunca foi um bug — era uma decisão de design que durava desde 1992. O Python 3.14 não remove essa limitação de vez, mas dá o passo mais concreto até agora para deixá-la para trás.

O que é a GIL e por que ela importa

A Global Interpreter Lock é um mutex que garante que apenas uma thread execute bytecode Python por vez dentro de um processo CPython. Ela existe por uma razão pragmática: simplifica imensamente o gerenciamento de memória e a integração com extensões C, que historicamente assumem que esse lock existe.

Injeção de dependência do jeito certo: IoC com Dishka e FastAPI

Fri, 20 Mar 2026 00:00:00 +0000

Você já escreveu algo assim numa aplicação FastAPI?

@router.get("/orders/{order_id}")
async def get_order(order_id: int):
    db = SessionLocal()
    try:
        repo = OrderRepository(db)
        service = OrderService(repo, settings.TAX_RATE)
        return await service.get_order(order_id)
    finally:
        db.close()

O código funciona. Mas há um problema sério: cada endpoint é responsável por montar sua própria árvore de dependências. Quando OrderService precisar de um CacheClient e de um EventPublisher, quem vai sofrer é quem escreve — e depois testa — cada endpoint.

O FastAPI tem seu próprio sistema de Depends() que resolve parte disso, mas tem limites quando a aplicação cresce e os grafos de dependência ficam complexos. É aqui que entra o conceito de Inversão de Controle e, mais especificamente, uma biblioteca que acerta onde o Depends() tropeça: o Dishka.

Você provavelmente não precisa desse try/finally

Thu, 19 Mar 2026 00:00:00 +0000

Existe um padrão que aparece em quase todo projeto Python com mais de algumas semanas de vida. Ele tem variações, mas o esqueleto é sempre o mesmo:

conn = get_db_connection()
try:
    resultado = conn.execute(query)
    return resultado
finally:
    conn.close()

Funciona. Fecha a conexão mesmo se der exceção. Ninguém vai questionar em code review. O problema é que esse bloco vai se repetir em todo lugar que precisar de uma conexão — e quando a lógica de encerramento mudar (adicionar log, métricas, rollback), você vai caçar essa duplicação pelo projeto inteiro.

Por que seu script Python consome mais memória do que deveria

Tue, 17 Mar 2026 00:00:00 +0000

Se você já usou o memory_profiler para inspecionar um script que processa arquivos grandes, provavelmente se deparou com um gráfico de consumo de RAM que sobe em escada — e não desce. O arquivo tem 500 MB, o script consome 600, 700, às vezes mais de 1 GB, e o culpado raramente é o que parece.

Este artigo começa exatamente aí: num script real com consumo excessivo de memória, explica por que ele se comporta assim, e mostra como generators e itertools resolvem o problema sem mudar a lógica de negócio.

Testes que Realmente Testam: pytest Além do Básico

Mon, 16 Mar 2026 00:00:00 +0000

No artigo sobre injeção de dependência ficou um problema em aberto. A classe OrderService não dava para testar sem subir banco, sem fazer chamada HTTP real, sem criar arquivo em disco. A solução apresentada foi injetar as dependências pelo construtor — o que deixa o código testável. Mas testável não significa testado. Este artigo fecha esse loop.

O objetivo aqui não é ensinar assert 1 == 1. É mostrar as ferramentas que separam uma suite de testes que protege o código de uma suite que só infla a cobertura: fixtures com escopo controlado, parametrize para eliminar duplicação, e mocks com pytest-mock para isolar dependências externas de verdade.

O Primeiro Plugin para niri + DankMaterialShell

Fri, 13 Mar 2026 00:00:00 +0000

O blog tem bastante conteúdo sobre software, Python e hardware embarcado. Mas há um lado que nunca apareceu por aqui: o ambiente de trabalho em si. Este é o primeiro relato sobre o setup com o compositor Wayland niri e o DankMaterialShell — e começa pelo primeiro plugin criado do zero para esse ambiente.

A motivação foi simples: queria ver no painel a versão do kernel em uso e o tempo de uptime do sistema. Sem abrir terminal, sem script externo. Só um widget discreto na barra mostrando 6.19.6-arch1-1 ⏱ 7h 54m.

Controlando Hardware pelo Celular: Uma Experiência com ESP32 e MQTT

Wed, 11 Mar 2026 00:00:00 +0000

O post anterior mostrou o Blink — o Hello World do hardware embarcado. Um LED piscando sozinho, controlado por um timer, sem nenhuma interação externa. Era o suficiente para validar o ambiente, mas deixava uma pergunta óbvia no ar: e se a gente quiser controlar esse LED de verdade? De outro dispositivo, em tempo real, sem cabos?

Essa pergunta levou ao experimento deste post: usar o protocolo MQTT para acionar um LED no ESP32 a partir de um celular, com um broker Mosquitto rodando localmente no PC. O resultado funcionou. O caminho até lá teve algumas surpresas que valem ser documentadas.

asyncio na prática: quando concorrência resolve e quando atrapalha

Tue, 10 Mar 2026 00:00:00 +0000

Se você chegou até aqui provavelmente já passou pelo profiling e encontrou um gargalo. A tentação imediata é jogar async/await em cima do problema e torcer para que o tempo de execução caia. Na maioria das vezes, não cai. Às vezes, piora.

Este artigo começa mostrando exatamente esse cenário — código assíncrono que não resolve nada — e explica por quê. Depois mostra um caso onde asyncio faz diferença real, e só então desce para o mecanismo que explica os dois resultados.

Sets em Python: Desvendando O(1) com Operações de Conjunto

Mon, 09 Mar 2026 00:00:00 +0000

Se você já usou um set em Python apenas para remover duplicatas com um .add() aqui e ali, está deixando na mesa uma das estruturas de dados mais poderosas e mal compreendidas da linguagem. Sets não são apenas listas sem duplicatas — são implementações de conjuntos matemáticos otimizadas para operações de associate arrays com tempo constante O(1), suportando operações que vão de interseção até diferença simétrica com performance que impressiona.

O Hello World do Hardware: Piscando um LED com ESP32

Sun, 08 Mar 2026 00:00:00 +0000

O blog tem bastante conteúdo sobre software — princípios, boas práticas, Python, APIs. Mas há um lado da computação que sempre esteve no horizonte: o hardware embarcado. Este é o primeiro relato de experiência nessa direção, e começa pelo início: o famoso Blink — o Hello World do hardware.

A ideia é simples. Pegar uma ESP32, um resistor, um LED, montar o circuito numa protoboard e gravar um programa que faça o LED piscar. O que parece ser coisa de uma tarde revelou algumas surpresas que valem ser registradas.

Argon2 em Python: o jeito certo de guardar senhas

Thu, 05 Mar 2026 00:00:00 +0000

MD5, SHA-256 e bcrypt ainda aparecem em bases de código novas. O que está errado nessa escolha, como o Argon2 resolve o problema e por que o pepper é a camada extra que separa uma implementação boa de uma implementação sólida.

Profiling em Python: Encontrando Gargalos com cProfile e memory_profiler

Mon, 02 Mar 2026 00:00:00 +0000

Existe um padrão que se repete em quase todo projeto Python que cresce. O código funciona, os testes passam, a feature está pronta — aí alguém percebe que uma rota específica demora três segundos quando deveria demorar duzentos milissegundos. Ou que um processo que roda em batch está consumindo 4 GB de RAM sem nenhuma razão óbvia.

O instinto natural é abrir o código e começar a suspeitar. Aquele loop ali, essa chamada de banco, aquela list comprehension aninhada. O problema é que intuição é um método caro: você otimiza o que acha que é lento, gasta horas em algo que mal contribui para o tempo total, e o gargalo real continua intacto.

Construindo Bots para o Fediverso com Python e apkit

Fri, 27 Feb 2026 08:14:37 -0300

Como implementar um bot ActivityPub funcional — do WebFinger ao HTTP Signature — e os bugs reais que você vai encontrar pelo caminho.

O Fediverso cresce a cada ano, e com ele cresce o interesse de engenheiros em criar aplicações que se integram nativamente ao ecossistema descentralizado. O ActivityPub, padrão W3C desde 2018, é o protocolo que cola tudo isso: Mastodon, Pleroma, Pixelfed e dezenas de outras plataformas falam a mesma língua. A boa notícia para quem escreve Python é que existe uma biblioteca que encapsula a complexidade do protocolo e deixa você focar no que o bot realmente faz.

Injeção de Dependência em Python sem Frameworks

Tue, 24 Feb 2026 08:05:23 -0300

Existe uma sequência bastante comum em projetos Python: você escreve uma classe, ela funciona bem, aí chega a hora de testar — e percebe que não dá para testar sem subir um banco de dados, sem fazer uma chamada HTTP real, sem criar um arquivo em disco. O código funciona, mas ele não é testável. E não testável, na prática, significa frágil.

O problema quase sempre tem a mesma raiz: a classe criou as próprias dependências em vez de recebê-las.

Decorators Internamente: Como Funcionam e Como Criar os Seus

Thu, 19 Feb 2026 11:29:23 -0300

Se você escreve Python há algum tempo, já usou decorators sem perceber. O @app.route do Flask, o @pytest.mark.parametrize, o @dataclass da stdlib, o @property nativo da linguagem — todos são decorators. Eles aparecem em todo framework relevante do ecossistema, mas a maioria dos recursos disponíveis explica como usar sem explicar por que funciona.

Este artigo corrige isso.

A ideia aqui não é ensinar a sintaxe do @. É mostrar o mecanismo embaixo: o que Python faz quando encontra esse símbolo, como construir um decorator do zero com segurança e como evitar as armadilhas que só aparecem em produção.

Sobre mim

Thu, 19 Feb 2026 00:00:00 +0000

Olá! Eu sou Vicente Marçal, também conhecido como Riverfount, desenvolvedor de software especializado em Python, baseado em Londrina-PR. Apaixonado por programação open source, crio soluções práticas e inovadoras para desafios reais.

Minhas Habilidades e Projetos

Trabalho remotamente, com foco em aprendizado contínuo e entrega de software de alta qualidade. Entre meus projetos no GitHub @Riverfount, destaco:

translate-bot: Bot ActivityPub para o Fediverso que detecta o idioma de menções e responde com a tradução via Google Translate API. github
vm-exchange: Uma API leve para cotações de câmbio, construída com FastAPI. github
PesquisaTeses: Ferramenta para busca automatizada de teses acadêmicas. github
vm_cpf_validator: Validador eficiente de CPF em Python. github
gen-cutter-sanborn: Gerador de códigos para catalogação bibliográfica. github

Esses projetos open source são apenas a ponta do iceberg, refletindo minha experiência em automação, APIs e ferramentas práticas para o dia a dia.

Nomear Para Comunicar: Como Escrever Variáveis Claras Concisas e Inteligentes em Python

Tue, 13 Jan 2026 00:00:00 +0000

Saber dar bons nomes é uma das habilidades mais valiosas — e menos ensinadas — na engenharia de software. Em Python, nomes de variáveis e funções bem escolhidos tornam o código legível, reduzem ambiguidade e ajudam a preservar o design ao longo do tempo. Seguindo as diretrizes da PEP 8 e os princípios da Clean Architecture, este artigo mostra como criar nomes expressivos, consistentes e concisos, sem cair na armadilha dos identificadores longos ou genéricos. Você verá exemplos reais, más práticas comuns e um mini refactor que demonstra como nomes claros transformam o código.

Complexidade Ciclomática em Python: Guia Essencial para Engenheiros de Software

Fri, 02 Jan 2026 00:00:00 +0000

A complexidade ciclomática mede o número de caminhos de execução independentes em uma função ou módulo Python, ajudando a identificar código difícil de testar e manter. Desenvolvida por Thomas J. McCabe em 1976, essa métrica é calculada como o número de pontos de decisão (if, for, while, etc.) mais um, revelando riscos em fluxos ramificados excessivos.

Mas o que é Complexidade Ciclomática?

Complexidade ciclomática (CC) quantifica a densidade de caminhos lógicos em um grafo de controle de fluxo. Em Python, cada estrutura condicional ou de loop adiciona ramificações: um if simples eleva a CC para 2, enquanto and/or em condições compostas multiplica caminhos independentes. A fórmula básica é CC = E - N + 2P, onde E são arestas, N nós e P componentes conectados, mas ferramentas como radon ou flake8 computam isso automaticamente.

PLR2004 na prática: por que evitar números mágicos em expressões booleanas em Python

Mon, 29 Dec 2025 00:00:00 +0000

Evitar números mágicos em expressões booleanas é uma recomendação explícita de linters Python modernos (como Pylint e Ruff, via regra PLR2004), pois esses valores dificultam a leitura e a manutenção do código. Entender essa regra e o contexto em que ela surgiu ajuda a justificar a prática ao time e a padronizar o estilo da base de código.

PLR2004: de onde vem essa regra?

A sigla PLR2004 é o identificador da regra magic-value-comparison em ferramentas de lint para Python, como o linter Ruff, que reutiliza a numeração herdada do Pylint. A regra é derivada diretamente da mensagem de refatoração R2004 – magic-value-comparison do Pylint, mantido pelo projeto PyCQA, que incentiva o uso de constantes nomeadas em vez de valores mágicos em comparações.

Pattern Matching em Python: Revolucione seu Código Além do Switch Case Tradicional

Mon, 22 Dec 2025 00:00:00 +0000

Descubra como o pattern matching no Python 3.10+ transforma árvores de if/elif em código declarativo e poderoso, superando limitações do switch case clássico. Neste guia técnico para desenvolvedores Python, explore exemplos práticos de destructuring de listas, dicionários e classes, guards e padrões compostos – otimizado para buscas como “pattern matching Python tutorial”, “match case vs switch Python” e “structural pattern matching exemplos”.

O que Torna o Pattern Matching Único

Introduzido pelos PEPs 634, 635 e 636 no Python 3.10, o match/case vai além da comparação de valores: descreve a estrutura de dados, desconstruindo tuplas, listas, dicionários e objetos em variáveis prontas para uso. Diferente do switch case de C/Java, que compara apenas escalares sem fallthrough automático, aqui o primeiro case que casa encerra o bloco, eliminando bugs comuns. Ideal para APIs REST, eventos JSON e parsers em projetos full-stack Python.

Dominando Dicionários em Python: O Segredo O(1) para DSA Eficiente!

Tue, 09 Dec 2025 00:00:00 +0000

Procurando por dicionários Python DSA, hash tables em Python, complexidade Big O dict Python ou estruturas de dados Python avançadas? Neste guia técnico desvendamos os princípios internos dos dicionários (dict), desde hashing e colisões até operações otimizadas para algoritmos reais. Ideal para engenheiros de software que buscam performance em microservices, grafos e entrevistas técnicas – leia e eleve seu código Python a outro nível!

Dicionários em Python (dict) são uma implementação eficiente de hash tables (tabelas de hash), uma estrutura de dados essencial em DSA para mapear chaves únicas a valores com acesso médio em tempo constante O(1). Essa performance os torna superiores a listas para operações de busca, inserção e deleção em cenários não ordenados, como caches, contagens de frequência ou representações de grafos. Desde Python 3.7, eles mantêm ordem de inserção, combinando benefícios de hash tables com listas ordenadas.[1]

Generators em Python: Técnicas Essenciais para Código Eficiente e Robusto

Thu, 04 Dec 2025 00:00:00 +0000

Generators em Python são funções especiais que usam yield para gerar valores sob demanda, economizando memória em vez de criar listas completas na RAM. Pense neles como “listas preguiçosas” que produzem um item por vez, ideais para processar arquivos grandes ou sequências infinitas sem travar o sistema.

Yield vs Return: A Diferença Fundamental

return encerra a função imediatamente após retornar um único valor, enquanto yield pausa a execução, retorna um valor e preserva o estado interno para continuar de onde parou na próxima chamada. Isso permite que uma única função gere múltiplos valores sequencialmente, como um loop “congelado” e retomado.

Desvende o Segredo do Garbage Collector do Python: Evite Vazamentos e Otimize Sua Memória Agora!

Wed, 03 Dec 2025 00:00:00 +0000

Você já parou para pensar por que seu código Python consome cada vez mais memória em aplicações de longa duração, mesmo sem vazamentos óbvios? Palavras-chave como “garbage collector Python”, “contagem de referências Python”, “ciclos de referência Python” e “otimização de memória CPython” dominam buscas de desenvolvedores que enfrentam pausas inesperadas, inchaço de heap ou serviços que “incham” ao longo do tempo. Neste guia técnico expandido e atualizado, um engenheiro especialista em Python mergulha nos mecanismos internos do GC do CPython – com exemplos práticos de código, benchmarks reais e dicas avançadas de tuning – para você dominar a gestão de memória, detectar vazamentos sutis, configurar gerações otimizadas e escalar aplicações de produção sem surpresas.

Primitive Obsession no Python: Refatorando com Dataclasses para Value Objects Robustos

Tue, 02 Dec 2025 00:00:00 +0000

Baseado na Live de Python #150 do canal Eduardo Mendes no YouTube, este artigo explora de maneira prática e direta a “primitive obsession” — code smell onde tipos primitivos (strings, dicts, lists) substituem abstrações de domínio ricas — e como dataclasses (Python 3.7+, PEP 557) oferecem solução definitiva para criar Value Objects tipados, imutáveis e comportamentalmente ricos. Para sêniores buscando elevar modelagem DDD e reduzir technical debt em escala.

Primitive Obsession: Raiz do Problema

Primitive obsession ocorre quando entidades de domínio são reduzidas a “bags of primitives”, i. e., em que objetos de domínio são representados apenas como coleções simples de tipos primitivos (como strings, números, listas e dicionários) sem encapsulamento ou comportamento. Ou seja, em vez de ter classes ou estruturas que representem conceitos ricos com regras, validações e métodos, o código manipula “sacos” ou “pacotes” de dados primitivos soltos, o que aumenta a complexidade, propensão a erros e dispersa a lógica de negócio. Aplicando princípios de POO fundamentais: encapsulamento, polimorfismo e responsabilidade única. Consequências incluem:

Arquitetura Hexagonal em Python: Isolando o Domínio para Aplicações Robustas e Escaláveis

Mon, 01 Dec 2025 00:00:00 +0000

A arquitetura hexagonal, ou Ports and Adapters, coloca a lógica de negócio no centro de um hexágono simbólico, cercada por portas (interfaces abstratas) que conectam adaptadores externos como bancos de dados, APIs web, filas ou serviços de terceiros. Proposta por Alistair Cockburn em 2005, ela inverte as dependências tradicionais: o domínio não conhece frameworks ou persistência, mas estes dependem dele via injeção de dependências, promovendo código limpo e adaptável em Python. Essa abordagem alinha-se perfeitamente à filosofia “simples é melhor” do Python, mas com rigor para domínios complexos.

Scripts Python Autocontidos: Como Rodar Qualquer `.py` com Dependências Embutidas no UV

Fri, 28 Nov 2025 00:00:00 +0000

Você já precisou compartilhar um script Python com colegas e teve que explicar: “Instala o Python 3.12, cria um venv, instala requests e rich, depois roda”? Com o gerenciador UV, isso acabou.

Agora é possível escrever um único arquivo .py que já traz suas dependências dentro dele, como requests<3 e rich, e rodar tudo com apenas uv run script.py. Neste guia, você vai aprender como usar o bloco # /// script do UV para transformar scripts comuns em artefatos autocontidos, reprodutíveis e portáteis — perfeitos para automações, ferramentas internas e protótipos.

Descubra o UV: Gerenciador de Projetos Python para Iniciantes

Thu, 27 Nov 2025 00:00:00 +0000

O UV é um gerenciador de pacotes e projetos Python extremamente rápido, escrito em Rust, que substitui ferramentas como pip, venv e pipenv por comandos simples e automação de ambientes virtuais. Ele conecta gerenciamento de versões do Python, instalação de dependências e execução de scripts em um único comando, proporcionando agilidade no desenvolvimento.

Instalação Rápida

Para começar, instale o UV facilmente via terminal:

Linux/macOS: curl -LsSf https://astral.sh/uv/install.sh | sh
Windows PowerShell: irm https://astral.sh/uv/install.ps1 | iex

Confirme a instalação com uv --version para garantir que está pronto para uso.

Por que abandonar números mágicos em status codes HTTP

Tue, 25 Nov 2025 00:00:00 +0000

Em desenvolvimento de APIs REST, status codes HTTP são tão importantes quanto o payload da resposta. Eles comunicam, de forma padronizada, o resultado de cada requisição e são consumidos por clientes, gateways, observabilidade e ferramentas de monitoração. Apesar disso, ainda é comum encontrar código repleto de “números mágicos”, como 200, 404 ou 500 espalhados pela base.

Uma abordagem mais robusta é substituir esses valores literais por constantes descritivas, como HTTP_200_OK ou HTTP_404_NOT_FOUND. Essa prática aproxima o código das boas práticas de engenharia de software e melhora diretamente a legibilidade, a manutenção e a confiabilidade da API.

Usando Abstract Base Classes (ABC) em Projetos Reais de Python: Um Exemplo Prático com Microserviços

Mon, 24 Nov 2025 00:00:00 +0000

Este artigo mostra como aplicar Abstract Base Classes (ABC) em um projeto real robusto, focado no desenvolvimento de microserviços. O objetivo é garantir clareza, contratos explícitos e extensibilidade, aliando os conceitos a práticas modernas.

Contexto do Projeto

Imagine um sistema de microserviços para gerenciamento de pedidos, em que diferentes serviços precisam manipular objetos que representam entidades diversas, como Pedido e Cliente. Queremos garantir que todas as entidades sigam um contrato explícito para operações comuns (ex.: obter ID, validação). Além disso, há um repositório genérico para armazenar dados dessas entidades com verificação de tipo.

Protocols, Generics e Typing Avançado em Python: Técnicas para Construir Aplicações Robústas e Manuteníveis

Fri, 21 Nov 2025 00:00:00 +0000

Este artigo aborda como usar funcionalidades avançadas de tipagem em Python, como Protocols, Generics e técnicas avançadas de typing, para criar aplicações escaláveis, flexíveis e de fácil manutenção.

Protocols: Contratos Flexíveis e Estruturais

Protocols permitem definir contratos de métodos e propriedades sem herança explícita, facilitando a interoperabilidade entre microserviços. Qualquer classe que implemente os métodos definidos no protocolo pode ser usada onde esse protocolo é esperado.

Exemplo prático:

from typing import Protocol

class Serializer(Protocol):
    def serialize(self) -> bytes:
        pass

class JsonSerializer:
    def serialize(self) -> bytes:
        return b'{"user": "alice"}'

class XmlSerializer:
    def serialize(self) -> bytes:
        return b'<user>alice</user>'

def send_data(serializer: Serializer) -> None:
    data = serializer.serialize()
    print(f"Enviando dados: {data}")

send_data(JsonSerializer())
send_data(XmlSerializer())

Neste exemplo, send_data aceita qualquer objeto que implemente o método serialize, garantindo baixo acoplamento e flexibilidade.

Desvendando a Armadilha dos Argumentos Mutáveis como Default em Python

Wed, 19 Nov 2025 00:00:00 +0000

Você já enfrentou resultados inesperados ao usar listas ou dicionários como valores padrão em funções Python? Esse é um problema comum que pode causar bugs sutis e difíceis de encontrar. Neste artigo técnico, vamos desmistificar o motivo desse comportamento, mostrando exemplos práticos e como evitá-lo com boas práticas de programação. Se você é um desenvolvedor Python buscando produzir código mais robusto e previsível, este conteúdo é essencial para o seu dia a dia.

`from módulo import *` em Python: por que você nunca deveria usar essa prática

Tue, 18 Nov 2025 00:00:00 +0000

Entenda os riscos do uso de from módulo import * em Python, saiba por que ele compromete a legibilidade e a manutenção do código e descubra as alternativas recomendadas por desenvolvedores experientes.

A armadilha da conveniência em Python

Há algo em Python que seduz até os desenvolvedores mais experientes: a promessa de simplicidade. Poucas linguagens conseguem equilibrar legibilidade e poder expressivo como ele faz. Mas é justamente essa aparente simplicidade que, às vezes, nos leva a atalhos perigosos. Entre eles, um velho conhecido: from módulo import *.

Comparações com True em Python: erros comuns e práticas recomendadas para engenheiros

Mon, 17 Nov 2025 00:00:00 +0000

No desenvolvimento Python, especialmente em projetos de médio a grande porte e pipelines complexos de testes automatizados, é comum encontrar erros sutis relacionados a comparações com o valor booleano True. Uma prática aparentemente inofensiva, como usar == True para verificar condições, pode introduzir comportamentos inesperados que dificultam a manutenção, geram falsos positivos em testes e causam dúvidas em revisões de código.

Essas situações não são incomuns em equipes que lidam com múltiplas camadas de abstração — desde o código de negócio até frameworks de teste — e evidenciam a importância de entender profundamente a diferença entre identidade e igualdade em Python, bem como as melhores práticas para escrever condicionais claras e robustas.

Como aplicar o Princípio da Inversão de Dependência em Python: um guia prático para sistemas flexíveis

Fri, 14 Nov 2025 00:00:00 +0000

Resumo:
O Princípio da Inversão de Dependência (DIP), parte do conjunto SOLID, é fundamental para criar sistemas sustentáveis, extensíveis e fáceis de testar. Este artigo explora como aplicá-lo em Python usando typing.Protocol e injeção de dependência, com foco em arquiteturas limpas e aplicação prática em sistemas corporativos.

Contexto

Projetos orientados a objetos de longo prazo exigem mais do que modularidade: precisam de estabilidade arquitetural. O Princípio da Inversão de Dependência (Dependency Inversion Principle - DIP) aborda exatamente esse ponto.
Ele recomenda que módulos de alto nível (os que contêm as regras de negócio) não conheçam os detalhes de baixo nível (implementações, drivers, frameworks), mas interajam por meio de abstrações.

Segregação de Interfaces em Python: projetando contratos enxutos com ABC e Protocol

Wed, 12 Nov 2025 00:00:00 +0000

O Princípio da Segregação de Interfaces (ISP — Interface Segregation Principle) é um dos pilares do SOLID e trata diretamente da qualidade dos contratos entre componentes. Em essência, ele afirma que uma classe não deve ser obrigada a depender de métodos que não utiliza. Essa regra incentiva o desenho de interfaces menores, mais coesas e representativas de um papel específico no sistema.

Na prática, o ISP força uma reflexão arquitetural: qual é a verdadeira responsabilidade dessa abstração? Se a resposta envolve comportamentos heterogêneos, a interface provavelmente está concentrando demasiadas responsabilidades — um sinal de design frágil e baixo reuso.

Liskov, Duck Typing e Protocolos: Como Python Transforma o Princípio de Substituição

Tue, 11 Nov 2025 00:00:00 +0000

No mundo da programação orientada a objetos, o Princípio de Substituição de Liskov (LSP) é um guia essencial para criar sistemas robustos e flexíveis. Porém, em Python, esse princípio ganha uma nuance especial graças ao duck typing e aos protocolos, que mudam completamente a forma como pensamos em substituição e hierarquia.

Neste post, vamos explorar como esses conceitos se entrelaçam, por que o LSP faz tanto sentido na linguagem pythonica e como seu entendimento ajuda a escrever códigos mais limpos, seguros e reutilizáveis — tudo isso sem depender exclusivamente de herança formal. Prepare-se para olhar para o LSP através das lentes de Python e descobrir ferramentas poderosas para o design de software elegante e eficiente.

Como o Princípio Aberto-Fechado Pode Transformar Seu Código Python

Mon, 10 Nov 2025 00:00:00 +0000

O Princípio Aberto-Fechado (Open-Closed Principle), um dos pilares do SOLID, é essencial para quem busca escrever código Python orientado a objetos mais flexível, escalável e de fácil manutenção. Ele estabelece que entidades de software — como classes, módulos e funções — devem estar abertas para extensão, mas fechadas para modificação.
Em outras palavras, o comportamento do sistema deve poder evoluir sem necessidade de alterar o código existente.

Entendendo o Princípio Aberto-Fechado

Aberto para extensão significa que o sistema pode adquirir novas funcionalidades.
Fechado para modificação significa que essas melhorias não devem exigir alterações nas implementações originais, reduzindo a chance de regressões e preservando a integridade do código já testado.

Em Python, a aplicação desse princípio está fortemente relacionada ao uso de abstrações, polimorfismo e injeção de dependências. Projetar para interfaces (ou classes abstratas) é o caminho para permitir evolução sem quebrar funcionalidades existentes.

O Princípio da Responsabilidade Única em Python: menos é mais

Sun, 09 Nov 2025 00:00:00 +0000

Em Python, é comum — especialmente pela flexibilidade da linguagem e pelo foco em produtividade — cairmos na armadilha de escrever grandes blocos de código em uma única função, método ou rota. Às vezes, é tentador resolver “tudo em um só lugar”: validar os dados, consultar o banco, tratar erros e ainda montar a resposta final.

Mas essa abordagem tem um preço. O código cresce, as responsabilidades se misturam e, de repente, você tem uma função que faz de tudo — e nada bem feito.

DRY: o princípio que separa código amador de código profissional

Fri, 07 Nov 2025 00:00:00 +0000

Na prática de desenvolvimento, é comum ver blocos de código duplicados, copiados e colados em diferentes partes de um sistema. Parece inofensivo; afinal, “funciona”. Mas com o tempo, essa abordagem se torna um problema sério. É aqui que entra o princípio DRY — Don’t Repeat Yourself — um dos fundamentos mais importantes da engenharia de software moderna.

O que é o princípio DRY

O princípio DRY afirma que cada informação, comportamento ou lógica de negócio deve ter uma única representação dentro de um sistema. Repetir código é repetir responsabilidade, e cada duplicação se transforma em um ponto a mais para corrigir quando algo muda.

Como usar Type Hints em Callables no Python para aumentar a qualidade do seu código

Thu, 06 Nov 2025 00:00:00 +0000

Os Type Hints transformaram a forma como escrevemos e mantemos código Python. Desde que foram introduzidos oficialmente no Python 3.5+, eles se tornaram essenciais em projetos que buscam clareza, segurança e manutenção mais fácil.

Mesmo sendo uma linguagem dinamicamente tipada, o Python se beneficia muito dessas anotações estáticas, especialmente em callables — funções, métodos e classes. Neste artigo, vamos entender por que usar Type Hints é uma prática que vale o investimento.

Comparando `type()` vs `isinstance()` em Python — e o que o duck typing tem a ver com isso

Wed, 05 Nov 2025 00:00:00 +0000

Você sabe qual é a forma mais Pythonic de verificar tipos em seu código? Se ainda usa type() para testar variáveis, talvez esteja limitando o potencial do seu projeto sem perceber. Entender a diferença entre type(), isinstance() e o conceito de duck typing pode transformar a maneira como você escreve código mais limpo, flexível e verdadeiro ao estilo do Python.

Entendendo a diferença entre `type()` e `isinstance()`

Em Python, é comum verificar o tipo de uma variável em um if. Dois padrões clássicos são:

O que é uma API REST? Segunda parte ...

Tue, 04 Nov 2025 00:00:00 +0000

Dando continuidade ao artigo “O que é uma API REST? Explicação Detalhada para Desenvolvedores”, esta segunda parte aprofunda-se em um método HTTP essencial que não foi coberto anteriormente: o PATCH, destacando seu papel na atualização parcial de recursos. Enquanto no artigo inicial exploramos os métodos GET, POST, PUT e DELETE para operações completas de criação, leitura, atualização e exclusão, aqui explicamos como o PATCH permite modificações mais precisas e eficientes, sem a necessidade de substituir o recurso inteiro.

O que é uma API REST? Explicação Detalhada para Desenvolvedores

Mon, 03 Nov 2025 00:00:00 +0000

Introdução

APIs REST (Representational State Transfer) são um padrão amplamente adotado para comunicação entre sistemas distribuídos, especialmente na web. Elas definem um conjunto de princípios que permitem que aplicações se comuniquem de forma simples, eficiente e escalável usando o protocolo HTTP. Este artigo detalha os conceitos fundamentais, a arquitetura REST e traz exemplos práticos para facilitar o entendimento.

Conceitos Fundamentais de REST

REST não é um protocolo, mas um conjunto de restrições arquiteturais para criar APIs, proposto por Roy Fielding em 2000. Para que uma API seja considerada RESTful, ela deve seguir princípios essenciais: