notify-utils 0.1.0

Biblioteca Python para parsing de preços de scraping, cálculo de descontos e análise estatística de histórico de preços.

notify-utils

Biblioteca Python completa para análise de preços de e-commerce: parsing, validação, cálculo de descontos reais e detecção de promoções falsas através de análise estatística de histórico.

🎯 Funcionalidades

• Parser de Preços: Normaliza strings de preços de diferentes formatos (BR, US)
• Cálculo de Descontos Inteligente: Detecta descontos reais vs anunciados usando histórico
• Análise Estatística Avançada: Média, mediana, tendências, volatilidade e confiança
• Sistema de Validação de Preços: Estratégias inteligentes para validar preços antes de adicionar ao histórico
• Ajuste Automático de Período: Garante inclusão de histórico mais recente
• Filtro de Ruído: Ignora dados voláteis recentes (scraping com erros)
• Notificações Discord: Envio de alertas de preço via webhook (opcional)

Instalação

pip install notify-utils

Uso Básico

Parsing de Preços

from notify_utils import parse_price

preco = parse_price("R$ 1.299,90")  # → 1299.90
preco = parse_price("$1,299.90")    # → 1299.90

Cálculo de Desconto com Histórico

from notify_utils import Price, get_discount_info
from datetime import datetime, timedelta

# Histórico de preços
precos = [
    Price(value=1299.90, date=datetime.now() - timedelta(days=60)),
    Price(value=1199.90, date=datetime.now() - timedelta(days=30)),
]

# Calcular desconto real baseado no histórico
info = get_discount_info(
    current_price=899.90,
    price_history=precos,
    period_days=30
)

print(f"Desconto real: {info.discount_percentage:.2f}%")
print(f"É desconto real? {info.is_real_discount}")

Análise de Tendência

from notify_utils import calculate_price_trend

trend = calculate_price_trend(precos, days=30)

print(f"Direção: {trend.direction}")  # 'increasing', 'decreasing', 'stable'
print(f"Mudança: {trend.change_percentage:.2f}%")
print(f"Confiança: {trend.confidence}")

Validação de Preços com Estratégias

from notify_utils import PriceHistory, Price, PriceAdditionStrategy, PriceAction

history = PriceHistory(product_id="PROD123", prices=precos)

# Estratégia SMART: aceita quedas imediatas, aumentos após 24h
novo_preco = Price(value=899.90, date=datetime.now())
result = history.add_price(
    novo_preco,
    strategy=PriceAdditionStrategy.SMART,
    min_hours_for_increase=24
)

# Integração com banco de dados
if result.action == PriceAction.ADDED:
    db.insert_price(product_id, result.affected_price)
    print(f"✅ Preço adicionado: R$ {result.affected_price.value:.2f}")
elif result.action == PriceAction.REJECTED:
    print(f"⏭️  Ignorado: {result.reason}")

Ajuste Automático de Período e Filtro de Ruído

from notify_utils import get_discount_info

# Ajusta período automaticamente + ignora 3 dias mais recentes
info = get_discount_info(
    current_price=899.90,
    price_history=precos,
    period_days=30,
    auto_adjust_period=True,  # Inclui histórico mais recente
    skip_recent_days=3        # Ignora ruído de 0-2 dias
)

print(f"Período solicitado: {info.period_days} dias")
print(f"Período ajustado: {info.adjusted_period_days} dias")
print(f"Dias ignorados: {info.skip_recent_days}")
print(f"Amostras usadas: {info.samples_count}")

Notificações Discord

from notify_utils import Product, DiscordEmbedBuilder

produto = Product(
    product_id="PROD123",
    name="Notebook Gamer",
    url="https://loja.com/produto"
)

builder = DiscordEmbedBuilder()
embed = builder.build_embed(produto, info, precos)
# Enviar via webhook Discord

📊 Estratégias de Validação

A biblioteca oferece 4 estratégias para adicionar preços ao histórico:

Estratégia	Comportamento	Uso Recomendado
ALWAYS	Sempre adiciona	Testes, coleta sem filtro
ONLY_DECREASE	Apenas quedas	Alertas de promoção
SMART ⭐	Quedas imediatas + aumentos após tempo mínimo	Produção (padrão)
UPDATE_ON_EQUAL	Atualiza timestamp se preço igual	Rastreamento de estabilidade

🔧 Casos de Uso

1. Sistema de Scraping com Validação

def processar_scraping(product_id: str, novo_valor: float):
    prices_from_db = db.get_prices(product_id)
    history = PriceHistory(product_id=product_id, prices=prices_from_db)

    novo_preco = Price(value=novo_valor, date=datetime.now())
    result = history.add_price(novo_preco, strategy=PriceAdditionStrategy.SMART)

    if result.action == PriceAction.ADDED:
        db.insert_price(product_id, result.affected_price)

        # Notificar se queda >= 10%
        if result.status.value == "decreased" and abs(result.percentage_difference) >= 10:
            notifier.send_price_alert(product, discount_info, history.prices)

2. Detecção de Promoções Falsas

# Loja anuncia "De R$ 1.999 por R$ 899" (50% off!)
# Mas histórico mostra que preço real era R$ 1.299

info = get_discount_info(
    current_price=899.90,
    price_history=precos_historicos,
    advertised_old_price=1999.90  # IGNORADO quando há histórico!
)

print(f"Desconto anunciado: 55%")
print(f"Desconto REAL: {info.discount_percentage:.2f}%")  # ~31% (vs R$ 1.299)
print(f"Estratégia: {info.strategy}")  # 'history' (priorizou histórico)

3. Análise de Melhor Momento para Comprar

trend = calculate_price_trend(precos, days=30)

if trend.is_decreasing() and trend.has_high_confidence():
    print("✅ Tendência de queda com alta confiança - BOM momento!")
elif trend.is_increasing() and trend.is_accelerating:
    print("⚠️ Preço subindo rápido - compre agora ou espere próxima promoção")

📚 Documentação Completa

Para mais detalhes e exemplos avançados, consulte:

• CLAUDE.md - Documentação completa com arquitetura e exemplos
• notify_utils/ - Código fonte com docstrings detalhadas

🛠️ Requisitos

• Python >= 3.12
• discord-webhook >= 1.4.1 (opcional, apenas para notificações)

📝 Changelog

v0.1.0 (2026-02-03)

• ✨ Sistema de validação de preços com estratégias
• 📊 Ajuste automático de período histórico
• 🔇 Filtro de ruído de dados recentes
• 📈 Análise de tendências com volatilidade
• 🎯 Novos modelos tipados e enums

Veja o changelog completo no CLAUDE.md

📄 Licença

MIT - veja LICENSE para detalhes.

👥 Contribuindo

Contribuições são bem-vindas! Abra issues ou pull requests no repositório.

⭐ Agradecimentos

Desenvolvido para ajudar consumidores a identificar promoções reais vs falsas no e-commerce brasileiro.