Leia os posts do bolha.blog.
Read all posts from our users.
from in.versos
Hoje sou tudo o que fui — ontem — e jamais serei.
Hoje sou beijo e mordida, lábios e dentes, olhos e pele.
Hoje sou saudade, esperança e aflição.
Hoje sou escarro, lágrimas e gritos.
Hoje sou feio, mediano e bonito.
Hoje sou — porque.
Amanhã não sei: talvez eu seja teu amor e tu o meu; talvez eu não seja mais ninguém.
from Riverfount
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.
Antes de entender decorators, é preciso internalizar um conceito que Python respeita de forma consistente: funções são objetos como qualquer outro.
Isso significa que uma função pode ser atribuída a uma variável, passada como argumento para outra função, e retornada como resultado de uma chamada. Se isso parece óbvio, bem. Mas as consequências disso são o alicerce inteiro do decorator pattern.
Funções podem ser atribuídas a variáveis:
def saudacao() -> str:
return "Olá!"
outra_referencia = saudacao # sem parênteses — não estamos chamando, estamos referenciando
print(outra_referencia()) # "Olá!"
Funções podem ser passadas como argumento:
def executar(func) -> None:
print("Antes")
func()
print("Depois")
executar(saudacao)
# Antes
# Olá!
# Depois
Funções podem ser retornadas por outras funções:
def criar_saudacao(nome: str):
def mensagem() -> str:
return f"Olá, {nome}!" # captura 'nome' do escopo externo
return mensagem # retorna a função, não o resultado
ola_vicente = criar_saudacao("Vicente")
print(ola_vicente()) # "Olá, Vicente!" — mesmo após criar_saudacao() ter retornado
Esse último exemplo tem um nome técnico: closure. A função interna mensagem “fecha sobre” a variável nome do escopo externo e a mantém viva mesmo depois que criar_saudacao terminou de executar. O Python preserva esse contexto enquanto houver uma referência à função interna.
Closures são o mecanismo que permite decorators funcionarem. Quando você entende closures, a mecânica do @ deixa de ser mágica e passa a ser consequência natural.
Com closures claras, o decorator se torna trivial de entender: @decorator é açúcar sintático para uma atribuição.
@meu_decorator
def funcao() -> None:
...
O Python transforma isso exatamente em:
def funcao() -> None:
...
funcao = meu_decorator(funcao)
É tudo. Não existe nenhuma magia adicional. O símbolo @ instrui o interpretador a passar a função definida logo abaixo como argumento para meu_decorator e a reatribuir o resultado de volta ao mesmo nome.
Para deixar isso concreto, veja o primeiro decorator possível — sem usar @, para tornar o mecanismo explícito:
def logar(func):
def wrapper():
print(f"Chamando {func.__name__}...")
func()
print(f"{func.__name__} concluída.")
return wrapper
def processar() -> None:
print("Processando pedido.")
# Sem @: reatribuição explícita
processar = logar(processar)
processar()
# Chamando processar...
# Processando pedido.
# processar concluída.
Agora a mesma coisa com a sintaxe @ — o resultado é idêntico:
@logar
def processar() -> None:
print("Processando pedido.")
processar()
# Chamando processar...
# Processando pedido.
# processar concluída.
O @ é apenas uma forma mais limpa de escrever processar = logar(processar). Reconhecer isso é o que permite raciocinar sobre qualquer decorator, não importa o quão complexo ele pareça.
O exemplo acima funciona, mas tem um problema: só aceita funções sem argumentos. Em produção, os decorators precisam ser transparentes — funcionar com qualquer assinatura de função, independentemente de quantos parâmetros ela receba.
Este é o template canônico:
import functools
def meu_decorator(func):
@functools.wraps(func) # (a) preserva a identidade da função original
def wrapper(*args, **kwargs): # (b) aceita qualquer assinatura
# (c) lógica executada antes da função original
resultado = func(*args, **kwargs) # (d) chama a função original com seus argumentos
# (e) lógica executada depois
return resultado # (f) retorna o valor original sem modificá-lo
return wrapper # (g) retorna o wrapper — não chama, retorna
Cada ponto merece atenção:
(a) @functools.wraps(func) preserva os metadados da função original no wrapper. O motivo completo merece uma seção própria — e vai ter uma logo adiante.
(b) *args, **kwargs garante que o wrapper aceita qualquer combinação de argumentos posicionais e nomeados, repassando-os intactos para a função original. Sem isso, o decorator só funciona com funções de assinatura idêntica à do wrapper.
© e (e) São os pontos onde a lógica do decorator vive: logging, validação, timing, cache — tudo entra aqui.
(d) func(*args, **kwargs) chama a função original com os mesmos argumentos recebidos. Note que a variável func vem do escopo externo — isso é a closure em ação.
(f) return resultado é crítico. Um decorator que não retorna o valor da função original “engole” o retorno silenciosamente. Se processar_pedido retorna uma lista de itens e o decorator não faz return resultado, o chamador recebe None.
(g) return wrapper está fora do corpo do wrapper. O decorator retorna a função wrapper — não a chama. É essa distinção que faz o mecanismo funcionar: ao escrever @meu_decorator, Python substitui o nome da função pelo wrapper retornado aqui.
Exemplo completo com timer:
import time
import functools
def timer(func):
@functools.wraps(func)
def wrapper(*args, **kwargs):
inicio = time.perf_counter()
resultado = func(*args, **kwargs)
fim = time.perf_counter()
print(f"{func.__name__!r} executou em {fim - inicio:.6f}s")
return resultado
return wrapper
@timer
def processar_pedidos(n: int) -> list[int]:
"""Simula o processamento de uma lista de pedidos."""
return list(range(n))
itens = processar_pedidos(100_000)
# 'processar_pedidos' executou em 0.004312s
time.perf_counter() é preferível a time.time() para medições de performance: tem resolução mais alta e não sofre ajustes de relógio do sistema.
functools.wraps É ObrigatórioHá um detalhe sutil que cobra um preço alto quando ignorado. Observe:
def log(func):
def wrapper(*args, **kwargs): # sem @functools.wraps
return func(*args, **kwargs)
return wrapper
@log
def calcular_total(pedido: dict) -> float:
"""Calcula o valor total de um pedido com impostos."""
...
print(calcular_total.__name__) # 'wrapper' ← errado
print(calcular_total.__doc__) # None ← errado
Após a decoração, calcular_total aponta para o objeto wrapper. Sem nenhum cuidado adicional, __name__, __doc__, __annotations__ e outros atributos são os do wrapper — não os da função original. O nome que aparece em stack traces, em ferramentas de documentação automática como Sphinx, em pytest markers e no help() interativo é wrapper.
Em um projeto com dezenas de funções decoradas, todo stack trace em produção vai apontar para wrapper em vez de indicar a função real com problema. O custo de debugging aumenta desnecessariamente.
functools.wraps resolve isso. Ele é um decorator aplicado ao wrapper que copia os atributos relevantes da função original:
def log(func):
@functools.wraps(func) # copia os metadados de func para wrapper
def wrapper(*args, **kwargs):
return func(*args, **kwargs)
return wrapper
@log
def calcular_total(pedido: dict) -> float:
"""Calcula o valor total de um pedido com impostos."""
...
print(calcular_total.__name__) # 'calcular_total' ← correto
print(calcular_total.__doc__) # 'Calcula o valor...' ← correto
Internamente, functools.wraps é um atalho para functools.update_wrapper(wrapper, func). Os atributos transferidos são:
| Atributo | O que representa |
|---|---|
__name__ |
Nome da função — aparece em stack traces e repr |
__qualname__ |
Nome qualificado — inclui classe e módulo, para contexto exato |
__doc__ |
Docstring — essencial para help(), Sphinx e IDEs |
__module__ |
Módulo de origem — identifica onde a função foi definida |
__annotations__ |
Type hints — necessário para mypy e ferramentas de análise estática |
__dict__ |
Atributos customizados — preserva metadados adicionados à função |
__wrapped__ |
Referência direta à função original — adicionado pelo wraps |
O atributo __wrapped__ merece destaque: ele permite “desembrulhar” a cadeia de decorators e acessar a função original diretamente, o que é útil em testes e introspecção.
print(calcular_total.__wrapped__) # <function calcular_total at 0x...>
A regra é simples: todo decorator deve usar @functools.wraps(func) no wrapper interno, sem exceção. O custo é zero, o benefício é real.
Até aqui, os decorators recebem apenas a função como argumento. Mas muitos dos decorators mais úteis precisam de configuração: @retry(max_tentativas=3), @cache(ttl=60), @permissao_requerida("admin").
Ao adicionar parênteses ao decorator, o comportamento muda completamente — e é aqui que a maioria dos tutoriais perde o leitor.
A confusão vem do seguinte: @repetir(vezes=3) não está chamando um decorator. Está chamando uma fábrica de decorator — uma função que, ao ser chamada com os argumentos de configuração, retorna o decorator de verdade.
A estrutura tem três camadas:
import functools
def repetir(vezes: int): # ← camada 1: fábrica — recebe os argumentos
def decorator(func): # ← camada 2: decorator — recebe a função
@functools.wraps(func)
def wrapper(*args, **kwargs): # ← camada 3: wrapper — executa em runtime
for _ in range(vezes):
resultado = func(*args, **kwargs)
return resultado
return wrapper
return decorator # fábrica retorna o decorator
@repetir(vezes=3)
def notificar(mensagem: str) -> None:
print(f"[NOTIF] {mensagem}")
notificar("pedido aprovado")
# [NOTIF] pedido aprovado
# [NOTIF] pedido aprovado
# [NOTIF] pedido aprovado
Para entender o que acontece passo a passo, expanda a sintaxe @:
# @repetir(vezes=3) se desdobra em:
_decorator = repetir(vezes=3) # step 1: chama a fábrica, obtém o decorator
notificar = _decorator(notificar) # step 2: aplica o decorator à função
A variável vezes fica capturada pela closure do wrapper, que a usa em cada chamada de notificar.
A regra para identificar quantas camadas um decorator precisa é direta: decorator sem parênteses = uma função que recebe func; decorator com parênteses = uma função que recebe os argumentos e retorna uma função que recebe func.
Python permite empilhar múltiplos decorators sobre uma mesma função. A ordem em que eles aparecem determina o comportamento — e errar essa ordem pode introduzir bugs silenciosos que só aparecem em produção.
@decorator_a # aplicado por último, envolve o resultado de decorator_b
@decorator_b # aplicado primeiro, envolve a função original
def minha_funcao():
...
# Equivalente exato:
minha_funcao = decorator_a(decorator_b(minha_funcao))
A regra de ouro: a aplicação é de baixo para cima (o decorator mais próximo da função é aplicado primeiro), mas a execução em runtime é de cima para baixo (o decorator mais externo executa primeiro).
Para tornar isso concreto, considere dois decorators em um endpoint de API:
import functools
def logar(func):
@functools.wraps(func)
def wrapper(*args, **kwargs):
print(f"[LOG] Chamando {func.__name__!r}")
resultado = func(*args, **kwargs)
print(f"[LOG] {func.__name__!r} concluída")
return resultado
return wrapper
def autenticar(func):
@functools.wraps(func)
def wrapper(usuario: str, *args, **kwargs):
if usuario != "admin":
raise PermissionError(f"Acesso negado para '{usuario}'")
return func(usuario, *args, **kwargs)
return wrapper
Cenário A — @logar acima de @autenticar:
@logar
@autenticar
def obter_relatorio(usuario: str) -> dict:
return {"relatorio": "dados sensíveis"}
obter_relatorio("convidado")
# [LOG] Chamando 'obter_relatorio' ← loga antes de verificar permissão
# PermissionError: Acesso negado para 'convidado'
O log registra a tentativa de acesso mesmo quando o usuário não tem permissão. Em alguns sistemas, isso é o comportamento correto — registrar toda tentativa, incluindo as negadas.
Cenário B — @autenticar acima de @logar:
@autenticar
@logar
def obter_relatorio(usuario: str) -> dict:
return {"relatorio": "dados sensíveis"}
obter_relatorio("convidado")
# PermissionError: Acesso negado para 'convidado'
# (sem log — a exceção ocorre antes do log ser atingido)
Aqui, a autenticação bloqueia antes do log registrar qualquer coisa. Apenas chamadas autenticadas chegam ao log.
Ambos os comportamentos podem ser desejados, dependendo do requisito. O ponto é que a ordem define o comportamento, e não há nada no código que sinalize a diferença visualmente além da posição do @. É uma decisão arquitetural que precisa ser documentada.
Até agora, todos os decorators foram funções. Mas Python permite usar classes como decorators também — e elas se tornam a escolha certa quando o decorator precisa manter estado entre chamadas.
Um contador de invocações é o exemplo mais direto:
import functools
class Contador:
def __init__(self, func) -> None:
functools.update_wrapper(self, func)
self.func = func
self.chamadas: int = 0
def __call__(self, *args, **kwargs):
self.chamadas += 1
return self.func(*args, **kwargs)
@Contador
def buscar_usuario(user_id: int) -> dict:
"""Busca dados de um usuário pelo ID."""
return {"id": user_id}
buscar_usuario(1)
buscar_usuario(2)
buscar_usuario(3)
print(f"Total de chamadas: {buscar_usuario.chamadas}") # Total de chamadas: 3
O @Contador sobre buscar_usuario é equivalente a buscar_usuario = Contador(buscar_usuario). O construtor __init__ recebe a função, __call__ é executado cada vez que a função decorada é chamada, e o estado (self.chamadas) persiste no objeto.
update_wrapper realmente faz numa instância de classeAqui vale parar e ser preciso, porque há uma nuance importante que a maioria dos tutoriais ignora.
functools.update_wrapper(self, func) copia atributos como __name__, __qualname__, __doc__ e __annotations__ da função original para o objeto instância — não para a classe Contador. Isso significa que a introspecção programática funciona corretamente:
print(buscar_usuario.__name__) # 'buscar_usuario' ← correto
print(buscar_usuario.__doc__) # 'Busca dados de um usuário pelo ID.' ← correto
print(buscar_usuario.__wrapped__) # <function buscar_usuario at 0x...> ← correto
Porém, o __repr__ padrão de um objeto em Python é gerado pela classe, não pela instância. E a classe Contador não sabe nada sobre __name__ — ela simplesmente herda o __repr__ de object, que produz:
repr(buscar_usuario)
# <__main__.Contador object at 0x7f3a4c2b1d90>
Não <function buscar_usuario at 0x...>, como seria com um decorator de função. O update_wrapper não tem como alterar isso: atributos de instância não têm efeito sobre o __repr__ padrão da classe.
Para fins práticos do dia a dia — pytest, mypy, Sphinx, logging, stack traces — isso raramente é problema: todas essas ferramentas usam __name__ e __qualname__ diretamente, e esses atributos estão corretos. O __repr__ entra em cena principalmente no REPL interativo e em sessões de debug — exatamente onde um repr que “mente” pode confundir mais do que ajudar.
__repr__ que comunica a realidadeO caminho certo não é imitar o repr de uma função — é comunicar a natureza real do objeto, incluindo o estado que só um decorator de classe pode ter:
import functools
class Contador:
def __init__(self, func) -> None:
functools.update_wrapper(self, func)
self.func = func
self.chamadas: int = 0
def __call__(self, *args, **kwargs):
self.chamadas += 1
return self.func(*args, **kwargs)
def __repr__(self) -> str:
return (
f"<Contador decorator de {self.func.__qualname__!r} "
f"— {self.chamadas} chamada(s)>"
)
@Contador
def buscar_usuario(user_id: int) -> dict:
"""Busca dados de um usuário pelo ID."""
return {"id": user_id}
buscar_usuario(1)
buscar_usuario(2)
repr(buscar_usuario)
# <Contador decorator de 'buscar_usuario' — 2 chamada(s)>
Isso honra os dois requisitos ao mesmo tempo: __name__ e __qualname__ continuam disponíveis para introspecção programática via update_wrapper, e o repr comunica o que o objeto realmente é — um decorator com estado — em vez de fingir ser uma função simples.
A distinção importa especialmente quando o decorator carrega estado observável. Um repr que oculta chamadas, cache, ou qualquer outro estado interno priva o desenvolvedor de informação útil no momento em que ele mais precisa dela: durante o debug.
Quando usar cada abordagem:
| Situação | Escolha |
|---|---|
| Comportamento puro sem estado (log, timer, validação) | Decorator de função |
| Estado entre chamadas (contador, cache, rate limiter) | Decorator de classe com __repr__ explícito |
| Lógica configurável via argumentos | Fábrica de decorators |
Com a mecânica compreendida, esta seção apresenta três decorators que resolvem problemas reais e podem ser adaptados diretamente em projetos.
Chamadas a serviços externos falham. Redes instáveis, timeouts, rate limiting — são situações normais em produção. Um decorator de retry encapsula a lógica de re-tentativa sem poluir o código de negócio:
import time
import functools
def retry(max_tentativas: int = 3, delay: float = 1.0, excecoes: tuple = (Exception,)):
"""
Tenta executar a função até max_tentativas vezes.
Aguarda delay segundos entre cada tentativa.
Levanta a exceção original após esgotar as tentativas.
"""
def decorator(func):
@functools.wraps(func)
def wrapper(*args, **kwargs):
for tentativa in range(1, max_tentativas + 1):
try:
return func(*args, **kwargs)
except excecoes as e:
if tentativa == max_tentativas:
raise
print(
f"[RETRY] {func.__name__!r} — tentativa {tentativa}/{max_tentativas} "
f"falhou: {e}. Aguardando {delay}s..."
)
time.sleep(delay)
return wrapper
return decorator
@retry(max_tentativas=3, delay=0.5, excecoes=(ConnectionError, TimeoutError))
def chamar_api_pagamentos(payload: dict) -> dict:
"""Envia um pagamento para o processador externo."""
...
O parâmetro excecoes permite especificar quais exceções devem acionar o retry. Erros de programação como ValueError ou TypeError não devem ser re-tentados — por isso o padrão não é Exception para tudo.
Funções que recebem os mesmos argumentos e produzem sempre o mesmo resultado são candidatas à memoização. O decorator abaixo ilustra a lógica antes de introduzir a solução da stdlib:
import functools
def memoizar(func):
"""
Armazena resultados anteriores indexados pelos argumentos.
Evita recomputação para entradas já vistas.
"""
cache: dict = {}
@functools.wraps(func)
def wrapper(*args):
if args not in cache:
cache[args] = func(*args)
return cache[args]
return wrapper
@memoizar
def fibonacci(n: int) -> int:
"""Calcula o n-ésimo número de Fibonacci."""
if n <= 1:
return n
return fibonacci(n - 1) + fibonacci(n - 2)
print(fibonacci(40)) # instantâneo — sem memoização seria exponencial
Em projetos reais, use @functools.lru_cache(maxsize=128) ou @functools.cache (Python 3.9+) — são implementações da stdlib com controle de tamanho, thread safety e suporte a kwargs. O decorator manual acima serve para compreender o mecanismo antes de usar a versão pronta.
Validações de entrada que se repetem em múltiplas funções são candidatas a serem extraídas para um decorator. Isso reduz duplicação e, como consequência direta, reduz a complexidade ciclomática de cada função — o que já discutimos no artigo sobre Radon.
import functools
def validar_positivo(func):
"""
Garante que o primeiro argumento posicional é um número positivo.
Levanta ValueError com mensagem descritiva caso contrário.
"""
@functools.wraps(func)
def wrapper(valor: float, *args, **kwargs):
if valor <= 0:
raise ValueError(
f"{func.__name__!r} exige um valor positivo. "
f"Recebido: {valor!r}"
)
return func(valor, *args, **kwargs)
return wrapper
@validar_positivo
def calcular_desconto(preco: float, percentual: float) -> float:
"""Calcula o valor após aplicar o desconto."""
return preco * (1 - percentual / 100)
@validar_positivo
def calcular_frete(peso_kg: float) -> float:
"""Calcula o custo de frete baseado no peso."""
return peso_kg * 3.5
calcular_desconto(-10.0, 5)
# ValueError: 'calcular_desconto' exige um valor positivo. Recebido: -10.0
Cada função de negócio ficou com uma única responsabilidade — o decorator cuidou da guarda de entrada.
Engolir o retorno da função original
# Errado — não retorna o resultado
def log(func):
@functools.wraps(func)
def wrapper(*args, **kwargs):
func(*args, **kwargs) # ← sem return
return wrapper
@log
def somar(a: int, b: int) -> int:
return a + b
resultado = somar(2, 3)
print(resultado) # None — o valor foi perdido silenciosamente
O Python não avisa sobre isso. A função executa normalmente, mas o valor retornado some. Sempre use return func(*args, **kwargs) ou armazene em variável antes de retornar.
Esquecer functools.wraps
Já detalhado na seção 4. O custo de depurar stack traces cheios de wrapper em produção é muito maior do que adicionar uma linha ao decorator.
Decorar métodos de instância sem considerar self
Decorators que inspecionam o primeiro argumento precisam de atenção ao ser aplicados a métodos:
def validar_id(func):
@functools.wraps(func)
def wrapper(*args, **kwargs):
# args[0] aqui é 'self', não o primeiro argumento real do método
user_id = args[1] if len(args) > 1 else kwargs.get("user_id")
if not isinstance(user_id, int) or user_id <= 0:
raise ValueError(f"user_id inválido: {user_id!r}")
return func(*args, **kwargs)
return wrapper
class UserService:
@validar_id
def buscar(self, user_id: int) -> dict:
...
O self entra como args[0], empurrando os argumentos reais para args[1] em diante. Decorators de função que assumem args[0] como primeiro argumento do usuário quebram silenciosamente ao serem aplicados a métodos.
Stacking na ordem errada
Como demonstrado na seção 6, inverter a posição de @autenticar e @logar produz comportamentos diferentes. Sem um comentário que documente a intenção, a ordem parece arbitrária para quem lê o código depois.
| # | Prática | Por quê |
|---|---|---|
| 1 | Sempre use @functools.wraps(func) no wrapper interno |
Preserva identidade da função em stack traces, docs e ferramentas |
| 2 | Use *args, **kwargs no wrapper |
Garante compatibilidade com qualquer assinatura de função |
| 3 | Sempre retorne resultado = func(...) / return resultado |
Evita engolir retornos silenciosamente |
| 4 | Prefira decorator de função para comportamento puro | Mais simples, sem overhead de classe |
| 5 | Use decorator de classe quando precisar de estado entre chamadas | self é o lugar natural para manter estado |
| 6 | Documente o decorator com docstring | Descreva o que ele adiciona, não o que a função faz |
| 7 | Em stacking, coloque o decorator mais específico mais próximo da função | Torna a cadeia de transformações previsível |
| 8 | Especifique as exceções no retry, não use Exception para tudo |
Evita re-tentativas em erros de programação |
| 9 | Em decorators de classe, use functools.update_wrapper(self, func) |
Equivalente ao @wraps para instâncias |
| 10 | Documente a ordem em stacking quando ela for semanticamente relevante | Quem lê o código não deve ter que raciocinar sobre a ordem |
Decorators não são mágica. São closures com açúcar sintático — e a sintaxe @ é apenas uma forma elegante de escrever funcao = decorator(funcao).
Entender isso abre um caminho direto para duas habilidades práticas: saber ler qualquer decorator existente em frameworks e bibliotecas, e saber construir os seus com a estrutura correta desde o início.
Há uma conexão direta com outros princípios já explorados aqui no blog. O functools.wraps é a materialização do princípio de nomear pelo propósito — sem ele, __name__ mente para toda ferramenta que depende do nome da função. E decorators que extraem lógica transversal — retry, log, validação, cache — reduzem a complexidade ciclomática das funções de negócio, exatamente o que o radon mediria como melhoria no artigo sobre CC.
Um decorator bem escrito é invisível: a função de negócio comunica sua intenção, e o comportamento adicional está encapsulado, testável e reutilizável. É código que se explica por si só — e isso é poder puro na engenharia de software.
Se este artigo te fez repensar como você aplica comportamento transversal no seu código, compartilhe o decorator mais criativo que já escreveu: @riverfount@bolha.us
from vitu
Foi promulgada, em 17 de setembro de 2025, a lei nº 15.211, a qual ficou conhecida como “ECA Digital” ou “Lei Felca”, trazendo incertezas e preocupações para administradores de instâncias do Fediverso brasileiro, especialmente quanto a quais medidas devem ser adotadas e quais os riscos a que estarão sujeitos. O objetivo deste texto, longe de trazer soluções plenas, é colaborar com algumas reflexões, questionamentos e, dentro do possível, sugestões para minimizar potenciais riscos.
Vamos então, gradualmente, passando pelos pontos que considerei de principal relevância para as redes federadas como um todo.
Antes de tudo e ponto de extrema importância nessa lei, temos a problemática quanto ao que significa ser um produto ou serviço “direcionado a crianças e a adolescentes ou de acesso provável por eles“. Infelizmente a própria lei não traz uma definição clara e objetiva a esse respeito, de forma que ficaremos dependendo, como em diversos outros pontos, de uma regulamentação posterior pela “autoridade administrativa autônoma de proteção dos direitos de crianças e de adolescentes”, por atos do Poder Executivo e pela jurisprudência que surgir a partir da aplicação efetiva da lei em 17 de março de 2026 (Art. 41-A).
Também é válido questionar o quanto essa lei será aplicável às redes federadas e em que medida, tendo em vista que o seu art. 2º, III define rede social como uma
aplicação de internet que tem como principal finalidade o compartilhamento e a disseminação, pelos usuários, de opiniões e informações veiculadas por textos ou arquivos de imagens, sonoros ou audiovisuais, em uma única plataforma, por meio de contas conectadas ou acessíveis de forma articulada, permitida a conexão entre usuários; (grifo meu)
A dinâmica própria das redes federadas e suas diversas instâncias abrem questionamentos, portanto, sobre o quanto ela pode ser considerada uma rede social, nos termos da lei 15.211/2025, uma vez que, apesar de possibilitar a conexão entre os usuários, essa não ocorre por meio de “uma única plataforma”.
Voltando a atenção ao que torna essa comunicação possível, devido ao conteúdo do § 2º do referido art. 2º, o protocolo ActivityPub não deve ser considerado, por si só, um “produto ou serviço de tecnologia da informação”, uma vez que prescreve o parágrafo:
§ 2º Para os fins desta Lei, não são consideradas produtos ou serviços de tecnologia da informação as funcionalidades essenciais para o funcionamento da internet, como os protocolos e os padrões técnicos abertos e comuns que permitem a interconexão entre as redes de computadores que compõem a internet. (grifo meu)
Não deve, portanto, o protocolo em si ser considerado mesmo uma rede social ou receber qualquer tipo de sanção determinada pela lei, mas a dúvida quanto às instâncias permanece.
Em vários trechos da lei, é mencionada a “autoridade administrativa autônoma de proteção dos direitos de crianças e de adolescentes no ambiente digital”. Como regulamentado pelo Decreto nº 12.622, essa função fiscalizatória foi delegada à Agência Nacional de Proteção de Dados (ANPD), a qual poderá fazer recomendações e orientações para o cumprimento da lei (art. 6º, § 3º); será a responsável por regular e promover soluções técnicas para verificação de idade (art. 11); e fiscalizará o cumprimento da lei, podendo editar normas complementares (art. 34).
Assim sendo, é possível esperar que haja uma postura propositiva por parte da ANPD, chegando a colaborar com soluções para o devido cumprimento da legislação. Entretanto, é algo que somente será passível de confirmação com a sua entrada em vigor.
Por todo o corpo da legislação, é possível vislumbrar uma preocupação com os princípios jurídicos da proporcionalidade e razoabilidade para a análise dos casos concretos e para a aplicação de sanções. Destaco o art. 34, § 2º, que trata da função fiscalizatória da ANPD:
Art. 34. § 2º Nas atividades previstas no caput deste artigo [fiscalização do cumprimento da lei], a autoridade competente deverá observar as assimetrias regulatórias e adotar abordagem responsiva, assegurando tratamento diferenciado e proporcional a serviços de natureza, risco e modelo de negócio distintos. (grifo meu)
Como fica claro pelo conteúdo da norma, devem ser levadas em consideração as desigualdades existentes entre os diferentes serviços. Como entre uma rede social de uma grande empresa multinacional e uma instância de uma rede social ainda de nicho, com público relativamente restrito e que, em geral, não busca resultado financeiro; e prevê ainda que a própria regulamentação pode causar assimetrias entre diferentes atores. Por esses motivos, deve ser assegurado o “tratamento diferenciado e proporcional”, mantendo assim uma proporção entre as plataformas e as sanções aplicadas a cada uma delas.
Reforçando essa ideia, prescreve o art. 39:
Art. 39. As obrigações previstas nos arts. 6º, 17, 18, 19, 20, 27, 28, 29, 31, 32 e 40 desta Lei aplicar-se-ão conforme as características e as funcionalidades do produto ou serviço de tecnologia da informação, moduladas de acordo com o grau de interferência do fornecedor do produto ou serviço sobre os conteúdos veiculados disponibilizados, o número de usuários e o porte do fornecedor. […] § 2º As obrigações referidas no caput deste artigo serão aplicadas de forma proporcional à capacidade do fornecedor de influenciar, de moderar ou de intervir na disponibilização, na circulação ou no alcance dos conteúdos acessíveis por crianças e adolescentes. § 3º A regulamentação definirá critérios objetivos para a aferição do grau de intervenção e para a aplicação proporcional das obrigações previstas neste artigo. (grifo meu)
Observa-se, novamente, a preocupação com a característica específica de cada tipo de serviço, suas funcionalidades e suas capacidades reais, além de seu porte, sendo as obrigações legais diretamente relacionadas às capacidades reais “do fornecedor” — ou do administrador da instância — de ingerência sobre os conteúdos compartilhados na rede.
Nesse sentido, a previsão do § 3º sobre a definição de critérios objetivos para essa avaliação é positiva para que possamos compreender efetivamente as medidas que deverão ser adotadas e como fazer a adequação das instâncias à regulamentação. Enquanto isso, aguardamos a promulgação da regulamentação específica.
O cerne do ECA Digital está na preocupação acerca do uso indevido das redes por menores, como disposto no art. 6º:
Art. 6º Os fornecedores de produtos ou serviços de tecnologia da informação direcionados a crianças e a adolescentes ou de acesso provável por eles deverão tomar medidas razoáveis desde a concepção e ao longo da operação de suas aplicações, com o objetivo de prevenir e mitigar riscos de acesso, exposição, recomendação ou facilitação de contato com os seguintes conteúdos, produtos ou práticas: I – exploração e abuso sexual; II – violência física, intimidação sistemática virtual e assédio; III – indução, incitação, instigação ou auxílio, por meio de instruções ou orientações, a práticas ou comportamentos que levem a danos à saúde física ou mental de crianças e de adolescentes, tais como violência física ou assédio psicológico a outras crianças e adolescentes, uso de substâncias que causem dependência química ou psicológica, autodiagnóstico e automedicação, automutilação e suicídio; IV – promoção e comercialização de jogos de azar, apostas de quota fixa, loterias, produtos de tabaco, bebidas alcoólicas, narcóticos ou produtos de comercialização proibida a crianças e a adolescentes; V – práticas publicitárias predatórias, injustas ou enganosas ou outras práticas conhecidas por acarretarem danos financeiros a crianças e a adolescentes; e VI – conteúdo pornográfico.
Também sendo previsto que:
Art. 8º Os fornecedores de produtos ou serviços de tecnologia da informação direcionados a crianças e a adolescentes ou de acesso provável por eles deverão: […] V - informar extensivamente a todos os usuários sobre a faixa etária indicada para o produto ou serviço no momento do acesso, conforme estabelecido pela política de classificação indicativa. (grifo meu)
Há ainda, no art. 12, I, a exigência de “medidas proporcionais, auditáveis e seguras” para verificação da idade ou faixa etária, com previsão de uma regulamentação posterior específica para os meios de verificação de idade e supervisão parental (§ 3º).
Enquanto a viabilidade de implementar alguma forma de verificação de idade permanece uma incógnita, especialmente na ausência da regulamentação específica a respeito, com base nesse trecho, especificamente no inciso V do art. 8º, é recomendável que as instâncias, tanto em sua página inicial quanto no processo de cadastro, informem de forma clara e objetiva que o uso da rede não é recomendado para menores de 18 anos — ou a idade que o administrador julgar mais conveniente. Essa atitude relativamente simples já pode desenquadrar a instância de algumas situações.
No caso, se não pudermos afirmar categoricamente que não se trata de serviço “de acesso provável” por crianças e adolescentes, minimamente estará excluído do rol dos serviços “direcionados a crianças e a adolescentes” e cumprirá a determinação legal de informar a faixa etária indicada para uso, demonstrando boa vontade, cooperação e boa-fé.
Havendo uso por menores, há previsões quanto à necessidade de implementação de ferramentas para a supervisão pelos responsáveis legais, sendo que deve novamente ser considerada, segundo o art. 17, I, “a tecnologia disponível e a natureza e o propósito do produto ou serviço” e, II, disponibilizadas informações para os responsáveis sobre as ferramentas existentes. Há, novamente, a pendência de uma regulamentação, também por parte da ANPD, sobre quais serão as diretrizes para os mecanismos de supervisão parental (art. 17, § 1º).
Ainda assim, em seu art. 18 é exigida a implementação de ferramentas que possibilitem aos responsáveis legais:
I – visualizar, configurar e gerenciar as opções de conta e privacidade da criança ou do adolescente; II – restringir compras e transações financeiras; III – identificar os perfis de adultos com os quais a criança ou o adolescente se comunica; IV – acessar métricas consolidadas do tempo total de uso do produto ou serviço; V – ativar ou desativar salvaguardas por meio de controles acessíveis e adequados; VI – dispor de informações e de opções de controle em língua portuguesa.
Bem como o art. 24, caput, estabelece que contas de menores de 16 anos devem estar vinculadas a um usuário ou conta do responsável legal.
Ressalte-se, porém, que todas essas determinações, as quais aparentam ser inviáveis atualmente, principalmente para instâncias pequenas, tornam-se desnecessárias para o caso de conseguirmos descaracterizar a instância como sendo “direcionada a crianças e a adolescentes ou de acesso provável por eles”, de forma a tornar todo o disposto no ECA Digital não aplicável. Mas isso apenas as determinações da ANPD e o desenrolar de casos futuros poderão determinar.
Cabe, no momento, apenas ressaltar, conforme art. 24, § 1º, I, e como destacado no tópico anterior, a inadequação do uso do serviço por menores de idade.
Art. 24. No âmbito de seus serviços, os provedores de produtos ou serviços direcionados a crianças e a adolescentes ou de acesso provável por eles deverão garantir que usuários ou contas de crianças e de adolescentes de até 16 (dezesseis) anos de idade estejam vinculados ao usuário ou à conta de um de seus responsáveis legais. § 1º Caso seus serviços sejam impróprios ou inadequados para crianças e adolescentes, os provedores de redes sociais deverão adotar medidas adequadas e proporcionais para: I – informar de maneira clara, destacada e acessível a todos os usuários que seus serviços não são apropriados; (grifo meu)
Um ponto que acredito que possa ter causado desconforto em alguns administradores é o conteúdo do art. 27, principalmente seu § 2º, segundo os quais:
Art. 27. Os fornecedores de produtos ou serviços de tecnologia da informação disponíveis no território nacional deverão remover e comunicar os conteúdos de aparente exploração, de abuso sexual, de sequestro e de aliciamento detectados em seus produtos ou serviços, direta ou indiretamente, às autoridades nacionais e internacionais competentes, na forma de regulamento. […] § 2º Os fornecedores deverão reter, pelo prazo estabelecido no art. 15 da Lei nº 12.965, de 23 de abril de 2014 (Marco Civil da Internet), os seguintes dados associados a um relatório de conteúdo de exploração e de abuso sexual de criança ou de adolescente: I – conteúdo gerado, carregado ou compartilhado por qualquer usuário mencionado no relatório e metadados relacionados ao referido conteúdo; II – dados do usuário responsável pelo conteúdo e metadados a ele relacionados.
Tal retenção, além de incômoda, traz um potencial de aumento nos custos de manutenção dos servidor,es além da preocupação com possíveis sanções pelo seu descumprimento.
Contudo, ao analisar o referido art. 15 do Marco Civil da Internet, conclui-se ser um cenário não aplicável à maioria das instâncias, uma vez que não se tratam de pessoas jurídicas e de atividade profissional remunerada e com fins econômicos.
Art. 15. O provedor de aplicações de internet constituído na forma de pessoa jurídica e que exerça essa atividade de forma organizada, profissionalmente e com fins econômicos deverá manter os respectivos registros de acesso a aplicações de internet, sob sigilo, em ambiente controlado e de segurança, pelo prazo de 6 (seis) meses, nos termos do regulamento. (grifo meu)
Dessa forma, a retenção dos dados se torna desnecessária por parte da instância que receber a denúncia, devendo apenas tomar as ações de moderação cabíveis e notificar a autoridade competente. Excetuando-se apenas os casos de ordem judicial específica, a qual pode determinar a retenção de “registros relativos a fatos específicos em período determinado” (Art. 15, § 1º, Marco Civil da Internet).
O ECA Digital, como esperado para uma lei dessa magnitude, estabelece, em seu art. 35, caput e incisos, as penalidades a que estarão sujeitos os infratores de suas determinações, sendo elas
I – advertência, com prazo para adoção de medidas corretivas de até 30 (trinta) dias; II – multa simples, de até 10% (dez por cento) do faturamento do grupo econômico no Brasil no seu último exercício ou, ausente o faturamento, multa de R$ 10,00 (dez reais) até R$ 1.000,00 (mil reais) por usuário cadastrado do provedor sancionado, limitada, no total, a R$ 50.000.000,00 (cinquenta milhões de reais) por infração; (grifo meu)
Ressalte-se, novamente, a previsão de proporcionalidade e também da gradação na aplicação da penalidade.
Apesar de ser uma multa que pode atingir um valor considerável, uma vez que uma instância com 300 usuários já estaria sujeita a uma multa mínima de R$3.000 — valor esse que pode ser irrisório para grandes empresas, mas que com certeza faria grande diferença na manutenção da infraestrutura de uma instância —, é importante atentar-se ao restante dos parágrafos e incisos, especialmente o § 1º, incisos III e IV.
§ 1º Para fixação e gradação da sanção, deverão ser observadas, além da proporcionalidade e da razoabilidade, as seguintes circunstâncias: III – a capacidade econômica do infrator, no caso de aplicação da sanção de multa; IV – a finalidade social do fornecedor e o impacto sobre a coletividade no que se refere ao fluxo de informações no território nacional. (grifo meu)
A esse respeito, é apresentada, mais uma vez, a preocupação com a proporcionalidade e razoabilidade na aplicação das penalidades, além da capacidade econômica da instância e do seu administrador e a sua finalidade. Assim sendo, por mais que seja arriscado fazer prognósticos antecipados quanto à aplicação de uma nova lei, tudo leva a acreditar que, no caso em questão, a prioridade será pela aplicação de advertência, principalmente se for demonstrada cooperação e boa vontade por parte dos administradores.
Acredito que o texto, além de longo, tenha sido um tanto maçante e não muito otimista para nossos queridos administradores. Gostaria de poder trazer mais respostas e soluções, mas não é algo possível neste momento. Então, nesta conclusão, tentarei resumir os principais ponto levantados, com as dúvidas, questionamentos e recomendações para o cenário atual, visando, principalmente, reduzir os riscos para as instâncias brasileiras.
Os principais pontos envolvem, basicamente, o que significa ser um serviço “direcionado a crianças e a adolescentes ou de acesso provável por eles”, se o fediverso pode ser considerado uma rede social de acordo com a definição da lei e a aplicação ou não do ECA Digital às instâncias, sendo que uma maior elucidação a esse respeito provavelmente resultaria na solução de muitos dos problemas levantados, como quanto à verificação da idade e a supervisão parental. Como destacado no restante do texto, porém, somente novas resoluções da ANPD e a jurisprudência poderão trazer tais respostas.
Todas as punições e sanções previstas foram acompanhadas de termos que estimulam o uso dos princípios de proporcionalidade e razoabilidade para a análise de cada caso, tornando improvável — porém não impossível — a aplicação de multas de valor muito expressivo. Sendo mais provável a aplicação inicial de advertências e progressão para multas em casos reincidentes.
Ainda assim, recomenda-se que as instâncias tomem alguns cuidados, especialmente com o objetivo de demonstrar ciência sobre a lei, boa-fé e boa vontade, fatores que podem influenciar na aplicação e gradação de sanções. Para isso, de forma simples:
Espero que o texto tenha sido informativo e ajude os administradores pelo menos a compreender melhor a situação atual de sua instância dentro da nova legislação.
Estou à disposição para perguntas ou contribuições em @vitu@bolha.us.
from orixás
Eu faço anotações do que eu vou aprendendo e compartilho aqui, se entendi algo errado manda uma mensagem eletrônica para guto@carvalho.life que eu corrijo aqui ;)
—
Na umbanda você vai perceber que o pai nosso é diferente daquele de outros cultos religiosos tradicionais, alguns chamam de “Pai nosso da Natureza” e outros de “Pai nosso da Umbanda”.
Após pesquisar não achei um autor tal como temos para o Hino, ao que me parece, essa releitura foi algo passado pelos guias e adotado nos terreiros de forma natural e compartilhada.
Pai Nosso que estais nos céus, nas matas, nos mares e em todos os mundos habitados. Santificado seja o teu nome, pelos teus filhos, pela natureza, pelas águas, pela luz, e pelo ar que respiramos.
Que o teu reino, reino do bem, reino do amor e da fraternidade, nos una a todos e a tudo que criastes em torno da sagrada cruz, aos pés do Divino Salvador e Redentor.
Que a tua vontade nos conduza sempre a vontade firme para sermos virtuosos e úteis aos nossos semelhantes. Dai-nos hoje o pão do corpo, o fruto das matas e a água das fontes para o nosso sustento material e espiritual. Perdoa, se merecermos, as nossas faltas e dá o sublime sentimento do perdão para os que nos ofendam.
Não nos deixeis sucumbir ante a luta, dissabores, ingratidões, tentações dos maus espíritos e ilusões pecaminosas da matéria. Envia nos Pai, um raio da tua divina complacência, luz e misericórdia para os teus filhos pecadores que aqui habitam, pelo bem da humanidade, nossa irmã.
Assim seja e assim será, pois essa é a Vossa vontade, Olorum, Nosso Divino Pai Criador.
Ele geralmente é falado no começo dos trabalhos, mas isso pode variar.
:)
from orixás
Eu faço anotações do que eu vou aprendendo e compartilho aqui, se entendi algo errado manda uma mensagem eletrônica para guto@carvalho.life que eu corrijo aqui ;)
—
Apesar de existirem muitos tipos de Umbanda, apesar de cada casa, terreiro, tenda ou templo ter suas orientações e formas particulares de cultuar os Orixás, e de trabalhar com as entidades e guias, um elemento é comum em todas as casas, seu Hino.
O Hino da Umbanda escrito por José Manuel Alves, músico português, é oficial em todas as casas de Umbanda.
Refletiu a luz divina com todo seu esplendor é do reino de Oxalá Onde há paz e amor Luz que refletiu na terra Luz que refletiu no mar Luz que veio de Aruanda Para tudo iluminar Umbanda é paz e amor Um mundo cheio de luz É força que nos dá vida e a grandeza nos conduz. Avante filhos de fé, Como a nossa lei não há, Levando ao mundo inteiro A Bandeira de Oxalá ! — Autor: José Manuel Alves
José Manuel, músico e compositor, veio de Portugal para o Brasil em 1929.
José Manuel foi em um terreiro de Umbanda para tentar curar sua cegueira, cego de nascença, buscava enxergar. Ele ouviu sobre uma nova religião foi atrás do Caboclo Sete Encruzilhadas para ajudá-lo. Durante o atendimento o cabloco disse que não era possível curar uma cegueira de origem cármica, mesmo assim, José se apaixou pela Umbanda e decidiu escrever a música em 1960.
Segundo consta, José Manuel dizia que a Umbanda não era para ser vista com os olhos físicos, era para ser vista olhos da alma.
O Hino foi oficializado pelo Caboclo Sete Encruzilhadas em 1961 no segundo congresso de Umbanda, e novamente em 1976 na primeira Convenção do Conselho Nacional Deliberativo de Umbanda.
José Manuel Alves decidiu que não iria cobrar direitos autorais, só pediu que não alterem a letra e que mantenham seu nome como autor da obra, ele também pediu que coloquem a mão no coração ao cantar o hino. A melodia é de Dalmo da Trindade Reis.
Além do Hino ele escreveu diversos pontos de Umbanda para terreiros e músicas populares para intérpretes da época.
from orixás
Eu faço anotações do que eu vou aprendendo e compartilho aqui, se entendi algo errado manda uma mensagem eletrônica para guto@carvalho.life que eu corrijo aqui ;)
—
Quando você começa a frequentar um terreiro vai ouvir que tal semana tem gira de direita ou esquerda, o que pode ser confuso no início, é muito simples de entender.
Quando falamos em Giras de Direita estamos tratando de entidades que vão irradiar energia (irradiação) pra gente, enquanto na Gira de Esquerda as entidades vão consumir energias (consumação) que não fazem bem pra gente.
Direita e esquerda nada mais são do que polos diferentes, assim como positivo, negativo, ativo, passivo, masculino, feminino, 0 e 1, e são a parte de um todo.
Não tem bem ou mal, certo ou errado, são energias distintas, as quais são trabalhadas em dias específicos em cada terreiro.
Gira com entidades que atuam absorvendo desequilibrios, vícios, energia negativa e a energia mais densa do consulente.
Eles literalmente descarregam o consulente.
Exu e Pombagira atuam mais perto da crosta terreste, mais próximo do consulente, e são especializados em trabalhar estas energias densas, as quais a linha da direita teria mais dificuldade de trabalhar.
Eles nos ajudam a identificar o que está errado dentro de nós, e nos permitem trabalhar a preguiça, a tristeza, a angústia, a depressão, a ansiedade, dentre outras manifestações, mostrando um lado que normalmente não queremos ver, para que assim então possamos aceitar e para que eles possam nos ajudar.
É uma bonita limpeza energética, se o consulente permitir.
Entidades:
Gira com entidades que atuam irradiando energias salutares e sublimes para ajudar o consulente. As entidades vão trabalhar na linha da fé, do amor, da justiça, da superação, dentre outras manifestões divinas e vão recarregar e reequilibrar o consulente.
Entidades:
Existem entidades que podem atuar nas duas linhas ou polos, malandros e ciganos são bons exemplos, dentre outros, é importante saber que existem exceções.
from orixás
Eu faço anotações do que eu vou aprendendo e compartilho aqui, se entendi algo errado manda uma mensagem eletrônica para guto@carvalho.life que eu corrijo aqui ;)
—
Ficar descalço no terreiro, especialmente na Umbanda, simboliza humildade, respeito ao solo sagrado e conexão direta com a energia da terra (ancestralidade e orixás).
Esse ato permite o aterramento (descarrego de energias negativas) e a purificação, removendo as sujeiras do mundo exterior antes de entrar no espaço ritualístico, focando na espiritualidade.
Significados e Fundamentos
Conexão e Ancestralidade: O solo do terreiro é considerado sagrado, a casa dos Orixás e guias. Estar descalço facilita a troca de energias, onde o médium se conecta com a força da natureza e dos ancestrais.
Humildade e Igualdade: Representa a remoção das vaidades e distinções materiais. Diante do sagrado, todos estão em pé de igualdade, reconhecendo a própria simplicidade.
Purificação Energética (Aterramento): Os pés agem como condutores que dissipam energias densas ou negativas acumuladas, servindo como um “para-raios” para o solo, essencial durante os trabalhos espirituais.
Respeito: É uma forma de não trazer as impurezas físicas e energéticas da rua (“sujeira do mundo”) para o ambiente de fé.
Tradição: Remete à cultura dos povos originários e negros escravizados, que cultuavam suas crenças em contato direto com a terra.
Embora comum para médiuns em giras, o ato de ficar descalço pode ser facultativo para a assistência em alguns terreiros, mas é altamente recomendado como forma de vivenciar a experiência espiritual.
from orixás
Eu faço anotações do que eu vou aprendendo e compartilho aqui, se entendi algo errado manda uma mensagem eletrônica para guto@carvalho.life que eu corrijo aqui ;)
—
Essa anotação eu criei quando comecei a ouvir sobre as sete linhas da umbanda ou sete tronos da umbanda dentro do templo, tenda ou terreiro.
Apenas para fixar o que eu aprendi:
É importante ressaltar que o terreiro que frequento segue a linha de Rubens Saraceni e as informações abaixo vem de sua codificação.
Voltando as sete linhas ou sete tronos, eu entendi que isso se conecta com o que chamam de essências e manifestações da Coroa Divina.
É na Coroa Divina que se assentam as essências e manifestações divinas.
As setes linhas também são chamadas de Setenário Sagrado.
Existem sete essências que se desdobram em manifestões diversas.
Quando falam de uma essência da Coroa Divina, imagine uma Coroa com sete pontas, onde cada ponta representa uma essência divina.
Entenda os Orixás como jardineiros, cada um cuidando de uma essência em um vasto Jardim, ou seja, cada ponta tem um Orixá responsável.
As polaridades também podem ser referenciadas como energia “ativa” e “passiva”, energia “masculina” e “feminina” ou energia “positiva” e “negativa”.
Se quiser aprofundar no tema, leia o Livro “Sete linhas da Umbanda” de Rubens Saraceni.
Os Orixás essenciais ou ancestrais, apesar de terem essências específicas, conseguem trabalhar diferentes energias ou manifestações.
Obaluaê pode trabalhar o amor, enquanto Oxóssi pode trabalhar a Justiça, todos podem atuar em todas as essências, manifestações e elementos divinos.
As vezes estamos cultuando um Orixá, recebendo atendimento de uma falange de entidades ligada a este Orixá, com foco nas qualidades e essências do Orixá, mas isso não significa que os outros não estão próximos ajudando e atuando no mesmo jardim divino.
Algumas interpretações, cursos, materiais, livros sobre as polaridades podem conter diferenças como:
Isso pode ocorrer nos materiais – em especial – dos filhos formados por Saraceni, que podem ter modificado alguns entendimentos.
Para este texto eu retirei as informações diretamente do livro do Saraceni, Sete Linhas da Umbanda, sexta edição.
As sete linhas vão variar conforme a casa, a linha da umbanda, o autor de livro, então entenda qual linha sua casa segue e se aprofunde no tema.
from in.versos
Há em ti uma canção
Sem voz ou palavras
Uma canção de melodia terna
Cujas notas fazem vibrar meu coração
E a alma, animada, põe-se a bailar
Mas meus olhos, enamorados, esses se entregam
Entregam-se à doce melancolia de saber que não terão a companhia dos teus para verem o amanhecer
from Riverfount
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.
Um código pode estar correto e, ainda assim, ser difícil de entender. Na maioria das vezes, o problema está nos nomes. Na Clean Architecture, os nomes devem refletir conceitos de negócio, não detalhes técnicos ou estruturais.
| Má prática | Boa prática | Por quê? |
|---|---|---|
db_user |
user_account |
Remove o detalhe técnico e foca no domínio. |
json_response |
order_summary |
“JSON” é formato, não conceito. |
user_data |
customer_profile |
“Data” é genérico; “profile” tem significado. |
A lógica é simples: nomeie pelo propósito, não pela forma.
A PEP 8 vai muito além da estética — ela é um guia de comunicação entre pessoas.
Algumas regras práticas:
snake_case para variáveis e funções.cfg, cnt, ttl). Prefira nomes completos (config, count, total).users, orders) e singular para elementos únicos (user, order).UserService, prefira get_user() a get_user_data().# ruim
def list_all_active_user_objects():
...
# bom
def list_active_users():
...
No segundo exemplo, o nome é simples e direto — o leitor entende a intenção de imediato.
Bons nomes reduzem a necessidade de comentários. O código deve ser quase uma frase legível.
# ruim
data = get_data()
# bom
user_orders = order_service.fetch_recent_orders(user_id)
Outro exemplo comum:
# ruim
flag = True
if flag:
process()
# bom
should_notify = True
if should_notify:
send_notification()
Quando as variáveis comunicam intenção, o raciocínio flui naturalmente — o código se torna autoexplicativo.
Nomes longos demais são tão ruins quanto nomes curtos e vagos.
O segredo é deixar o contexto carregar parte do significado.
| Má prática | Boa prática | Justificativa |
|---|---|---|
customer_account_balance_after_transaction_update |
new_balance |
O contexto já comunica o momento. |
temporary_order_price_value |
temp_price |
Clareza mantida, sem prolixidade. |
is_user_valid_and_authenticated |
is_authenticated |
Detalhes extras só atrapalham. |
A clareza vem do contexto, não do tamanho do nome.
Nomes são uma peça invisível da arquitetura do sistema. Quando todas as partes falam a mesma língua — a do negócio —, o código mantém coesão e resiliência. Trocar o banco ou o framework é fácil; perder clareza semântica, porém, é caro.
Bons nomes preservam a intenção arquitetural — mesmo após refatorações.
Eles são a ponte entre design técnico e linguagem de domínio.
data, info, object).db_, api_, json_) em camadas de domínio.Um exemplo simples mostra o poder de nomes bem escolhidos.
Antes (difícil de entender):
def p(u, d):
r = []
for i in d:
if i[1] == u:
r.append(i[0])
return r
Esse código até funciona, mas o leitor não sabe o que p, u, d ou r significam.
Depois (mesma lógica, nomes expressivos):
def get_orders_by_user(user_id: int, orders: list[tuple[int, int]]) -> list[int]:
user_orders = []
for order_id, owner_id in orders:
if owner_id == user_id:
user_orders.append(order_id)
return user_orders
Sem mudar nada na lógica, o código agora se explica. Os nomes contam a história completa — o que está sendo filtrado, por quê e o que é retornado.
Dar bons nomes é mais do que estilo: é comunicação entre mentes técnicas. Variáveis bem nomeadas expressam intenção, reforçam arquitetura e tornam o código sustentável ao longo do tempo. O nome certo transforma a leitura em compreensão imediata — e isso é poder puro na engenharia de software.
Se este artigo te fez repensar como você nomeia variáveis, compartilhe com sua equipe ou continue a conversa no Mastodon: @riverfount@bolha.us
Espalhe boas práticas e ajude mais pessoas a escrever código que realmente se explica por si só.
from in.versos
Sei que amas as flores com as quais teus tantos amantes te presenteiam. E talvez te entristeças por eu não te enviá-las.
Mas flores, querida, morrem cedo. Já o meu amor por ti jaz eternizado nos versos que te dediquei.
from Riverfount
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.
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.
Código Python com CC alta (>10) aumenta o risco de bugs ocultos e eleva o custo de testes unitários para cobertura total. Funções longas com if-elif-else encadeados violam o Zen of Python (“Flat is better than nested”), complicando debugging em IDEs como PyCharm. Em microservices ou APIs Flask/FastAPI, CC elevada impacta deploy em Docker, pois refatorações viram gargalos em CI/CD.
Considere este exemplo problemático:
def processar_usuario(usuario, eh_admin=False, eh_pago=False):
if not usuario:
return None
if eh_admin and eh_pago:
return "acesso_total"
elif eh_admin:
return "acesso_admin"
elif eh_pago:
return "acesso_basico"
else:
if usuario.ativo:
return "acesso_limitado"
return "bloqueado"
Aqui, CC ≈ 6 devido a ramificações múltiplas. Use radon cc arquivo.py para medir:
processar_usuario: CC=6 (alto risco)
| Faixa de CC | Nível de Risco | Ação Sugerida |
|---|---|---|
| 1-5 | Baixo | Manter como está |
| 6-10 | Moderado | Refatorar se possível |
| 11-20 | Alto | Dividir função imediatamente |
| >20 | Crítico | Refatoração urgente |
Valores acima de 10 sinalizam antipadrões em Python, como god functions em Django views.
validar_usuario() e determinar_nivel_acesso().@dataclass ou Enum.if not condicao: return para early returns.handlers = {eh_admin: handler_admin}.pylint ou mypy no pre-commit hook Git para alertas automáticos.Exemplo refatorado (CC reduzida para 2):
def processar_usuario(usuario, eh_admin=False, eh_pago=False):
if not usuario:
return None
return determinar_nivel_acesso(usuario.ativo, eh_admin, eh_pago)
def determinar_nivel_acesso(ativo, eh_admin, eh_pago):
if eh_admin and eh_pago:
return "acesso_total"
handlers = {
(eh_admin, eh_pago): "acesso_basico",
eh_admin: "acesso_admin"
}
return handlers.get((eh_admin, eh_pago), "acesso_limitado" if ativo else "bloqueado")
Em projetos com pytest, mire 100% branch coverage em funções CC<10. No VS Code, extensões como "Python Docstring Generator" ajudam na documentação pós-refatoração. Para equipes, thresholds no GitHub Actions bloqueiam merges com CC>15, alinhando com práticas DevOps em Kubernetes.
Monitore CC regularmente para código limpo e escalável em Python. Experimente radon no seu repo hoje e compartilhe comigo em @riverfount@bolha.us sua maior redução de CC!
from in.versos
Ah, os doces sabores da vida.
Suaves, cítricos, florais, intensos, agridoces.
Sorrisos, olhares, abraços e lábios.
Lábios que beijam, sussurram e provocam.
Lábios vermelhos, lábios de Mell, Pablyne, sublimes.
Sabores que não precisam ser provados para se saber que são doçura, delícia e prazer.
from Riverfount
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.
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.
Na documentação do Ruff, a PLR2004 é descrita como uma verificação que detecta o uso de constantes numéricas “mágicas” em comparações, sugerindo substituí-las por variáveis constantes, justamente para melhorar legibilidade e manutenibilidade. A própria descrição enfatiza que o uso de valores mágicos é desencorajado pelas diretrizes de estilo PEP 8.
A regra PLR2004 inspeciona comparações como ==, !=, <, >, <= e >= em busca de literais numéricos sem nome, tratando-os como magic values quando representam algo além de números triviais. A documentação do Ruff destaca que esses valores tornam o código mais difícil de ler, pois o significado precisa ser inferido apenas pelo contexto, e recomenda o uso de constantes nomeadas.
Por conveniência, a regra costuma ignorar alguns valores muito comuns, como 0, 1 e "", que aparecem em operações idiomáticas, mas ainda assim permite configurar uma allowlist de valores aceitáveis para cenários específicos. Essa flexibilidade existe porque, em certos domínios, números como 90, 180 ou 360 deixam de ser “mágicos” e passam a ser parte da linguagem natural do problema (por exemplo, ângulos em graus).
Em expressões booleanas, o problema dos números mágicos fica mais evidente, porque a condição deveria comunicar a regra de negócio de forma clara. Ao escrever algo como if status == 2:, o leitor não sabe, de imediato, o que 2 representa: ativo, suspenso, cancelado?
A documentação do Pylint para magic-value-comparison / R2004 afirma que usar constantes nomeadas em vez de valores mágicos melhora a legibilidade e a manutenibilidade do código. Quando o valor de negócio muda (por exemplo, o status “ativo” deixa de ser 2 e passa a ser 3), o uso de literais espalhados exige uma busca manual sujeita a erro, enquanto uma constante única permite a mudança em um único ponto.
def can_access_admin_area(user_role: int) -> bool:
# 1 = admin, 2 = editor, 3 = viewer
return user_role == 1
Nesse caso, a PLR2004 sinalizaria o 1 como um magic value na comparação, sugerindo a extração para uma constante com nome significativo.
ADMIN_ROLE_ID = 1
def can_access_admin_area(user_role: int) -> bool:
return user_role == ADMIN_ROLE_ID
Aqui, a expressão booleana se explica sozinha e a ferramenta de lint não acusa a regra PLR2004, pois o valor numérico está encapsulado em uma constante nomeada.[2][1]
def is_valid_retry(status_code: int, retries: int) -> bool:
# 200: OK; 500: erro interno; 3: máximo de tentativas
return status_code != 200 and status_code != 500 and retries < 3
Esse padrão é exatamente o tipo de uso que a regra magic-value-comparison (PLR2004) se propõe a detectar.
HTTP_OK = 200
HTTP_INTERNAL_ERROR = 500
MAX_RETRIES = 3
def is_valid_retry(status_code: int, retries: int) -> bool:
return status_code not in (HTTP_OK, HTTP_INTERNAL_ERROR) and retries < MAX_RETRIES
Agora cada número tem um nome de domínio, a intenção da condição é clara e a manutenção futura fica concentrada nas constantes.
from enum import Enum, auto
class UserStatus(Enum):
INACTIVE = auto()
ACTIVE = auto()
SUSPENDED = auto()
def is_active(status: UserStatus) -> bool:
return status is UserStatus.ACTIVE
Ao usar Enum, o código evita completamente comparações numéricas, eliminando o gatilho da PLR2004 e expressando a lógica booleana em termos de estados de negócio.
A regra PLR2004 (magic-value-comparison), definida originalmente no Pylint e incorporada pelo linter Ruff, existe justamente para forçar a substituição de números mágicos por constantes e construções semânticas em comparações. Em vez de encarar o aviso como ruído, é possível usá-lo como guia de refatoração para deixar suas expressões booleanas mais claras, consistentes e fáceis de evoluir.
from in.versos
Vi, refletida na superfície do espelho, a face oculta da Morte.
Anjo, em vestes negras, cuja efígie me enfeitiça e cujo toque gélido anseio — em encanto e deleite —
no entrecruzar das mãos, cedidas a uma dança.
Uma única valsa, antes do fim.
from Riverfount
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”.
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.
Exemplo clássico de dias da semana, similar a um switch mas com OR nativo (|) e wildcard (_):
def weekday_name(day: int) -> str:
match day:
case 1:
return "Segunda-feira"
case 2 | 3 | 4 | 5:
return "Dia útil"
case 6 | 7:
return "Fim de semana"
case _:
raise ValueError(f"Dia inválido: {day}")
Sem break necessário – o case para automaticamente. Switch tradicional exigiria enum ou strings com fallthrough manual.
O diferencial: padrões que capturam partes de estruturas compostas.
def process_point(point):
match point:
case (0, 0):
return "Origem"
case (0, y):
return f"Eixo Y: {y}"
case (x, 0):
return f"Eixo X: {x}"
case (x, y):
return f"Ponto: ({x}, {y})"
case [x, y, *rest]:
return f"Lista longa: inicia {x},{y} + {len(rest)}"
case _:
raise TypeError("Formato inválido")
Captura variáveis diretamente, sem indexação manual – impossível em switch puro.
def handle_event(event: dict):
match event:
case {"type": "click", "x": x, "y": y}:
return f"Clique em ({x}, {y})"
case {"type": "user", "id": uid}:
return f"Usuário {uid}"
case _:
return "Ignorado"
Perfeito para payloads HTTP/JSON em Flask ou FastAPI.
from dataclasses import dataclass
@dataclass
class CreateUser:
email: str
@dataclass
class DeleteUser:
id: int
def dispatch(cmd):
match cmd:
case CreateUser(email=email):
return f"Criar: {email}"
case DeleteUser(id=uid):
return f"Excluir: {uid}"
Desconstrói atributos por nome – switch não acessa objetos assim.
Combine matching com condições (if) e OR:
def classify(num: int):
match num:
case 0:
return "Zero"
case x if x > 0:
return "Positivo"
case x if x % 2 == 0:
return "Par negativo"
case _:
return "Ímpar negativo."
Guards executam pós-captura, mantendo lógica coesa – superior a ifs externos em switches.
| Aspecto | Switch Case (C/Java) | Pattern Matching Python |
|---|---|---|
| Comparação | Valores escalares | Estrutura + valores [4] |
| Destructuring | Não | Sim (listas/objetos) [1] |
| Guards/Condições | Externo | Integrado no case [2] |
| Fallthrough | Manual (break) | Automático [8] |
| Casos Múltiplos | Labels separados | ` |
Reduz if/elif verbosos em 50-70% para roteamento de dados.
Adote pattern matching em seus projetos Python para código mais legível e robusto. Teste os exemplos acima no seu ambiente e compartilhe comigo em @riverfount@bolha.us qual use case você vai aplicar primeiro. Para mais tutoriais avançados em Python, Spring Boot ou microservices, inscreva-se ou pergunte aqui!