notify-utils 0.0.1__py3-none-any.whl

notify_utils/notifiers/formatters.py

@@ -0,0 +1,108 @@
+"""
+Formatadores para exibição de preços e históricos.
+"""
+
+from typing import List
+from ..models import Price
+
+
+def format_price(value: float) -> str:
+    """
+    Formata preço para exibição.
+
+    Regras:
+    - Se >= R$ 1: sem centavos (ex: "R$ 1.299")
+    - Se < R$ 1: com centavos (ex: "R$ 0,99")
+    - Usa separador de milhar (ponto) e decimal (vírgula) padrão BR
+
+    Args:
+        value: Valor do preço
+
+    Returns:
+        String formatada
+
+    Examples:
+        >>> format_price(1299.90)
+        'R$ 1.299'
+        >>> format_price(899.50)
+        'R$ 899'
+        >>> format_price(0.99)
+        'R$ 0,99'
+        >>> format_price(0.50)
+        'R$ 0,50'
+    """
+    if value < 1.0:
+        # Produtos baratos: mostra centavos
+        return f"R$ {value:.2f}".replace('.', ',')
+    else:
+        # Produtos >= R$ 1: sem centavos, com separador de milhar
+        valor_inteiro = int(round(value))
+
+        # Formata com separador de milhar
+        valor_str = f"{valor_inteiro:,}".replace(',', '.')
+
+        return f"R$ {valor_str}"
+
+
+def get_unique_prices(prices: List[Price], limit: int = 5) -> List[float]:
+    """
+    Extrai preços únicos de uma lista, ordenados do menor para o maior.
+
+    Args:
+        prices: Lista de objetos Price
+        limit: Quantidade máxima de preços a retornar
+
+    Returns:
+        Lista de valores únicos ordenados (menor para maior)
+    """
+    if not prices:
+        return []
+
+    # Extrai valores e remove duplicatas usando set
+    unique_values = list(set(p.value for p in prices))
+
+    # Ordena do menor para o maior
+    unique_values.sort()
+
+    # Limita quantidade
+    return unique_values[:limit]
+
+
+def format_price_history(prices: List[Price], limit: int = 5) -> str:
+    """
+    Formata histórico de preços para exibição.
+
+    Extrai os últimos N preços ÚNICOS, ordena do menor para maior,
+    e formata como string separada por vírgulas.
+
+    Args:
+        prices: Lista de objetos Price
+        limit: Quantidade máxima de preços a mostrar (padrão: 5)
+
+    Returns:
+        String formatada (ex: "R$ 899, R$ 999, R$ 1.299")
+
+    Examples:
+        >>> prices = [
+        ...     Price(value=1399.90, date=datetime.now()),
+        ...     Price(value=1299.90, date=datetime.now()),
+        ...     Price(value=1299.90, date=datetime.now()),  # duplicata
+        ...     Price(value=999.90, date=datetime.now()),
+        ...     Price(value=899.90, date=datetime.now()),
+        ... ]
+        >>> format_price_history(prices, limit=5)
+        'R$ 899, R$ 999, R$ 1.299, R$ 1.399'
+    """
+    if not prices:
+        return "Sem historico"
+
+    # Obtém preços únicos ordenados
+    unique_values = get_unique_prices(prices, limit)
+
+    if not unique_values:
+        return "Sem historico"
+
+    # Formata cada preço e junta com vírgula
+    formatted_prices = [format_price(value) for value in unique_values]
+
+    return ", ".join(formatted_prices)

notify_utils/parser.py

@@ -0,0 +1,109 @@
+"""
+Parser para normalizar valores de preços de diferentes formatos.
+"""
+
+import re
+from typing import Union
+
+
+def parse_price(price_string: Union[str, float, int]) -> float:
+    """
+    Converte uma string de preço em formato decimal (float).
+
+    Suporta múltiplos formatos:
+    - "R$ 1.299,90" → 1299.90
+    - "1.299,90" → 1299.90
+    - "1,299.90" → 1299.90
+    - "$1,299.90" → 1299.90
+    - "1299.90" → 1299.90
+    - 1299.90 → 1299.90
+
+    Args:
+        price_string: String contendo o preço ou número
+
+    Returns:
+        Valor do preço em formato decimal
+
+    Raises:
+        ValueError: Se o formato não for reconhecido ou valor for inválido
+    """
+    # Se já é número, retorna
+    if isinstance(price_string, (int, float)):
+        if price_string < 0:
+            raise ValueError("Preço não pode ser negativo")
+        return float(price_string)
+
+    if not isinstance(price_string, str):
+        raise TypeError(f"Esperado str, int ou float, recebido {type(price_string)}")
+
+    # Remove espaços em branco
+    price_string = price_string.strip()
+
+    if not price_string:
+        raise ValueError("String de preço vazia")
+
+    # Remove símbolos de moeda e espaços
+    # Remove: R$, $, €, £, etc
+    cleaned = re.sub(r'[R\$€£¥\s]', '', price_string)
+
+    if not cleaned:
+        raise ValueError("String de preço inválida após limpeza")
+
+    # Detecta o formato baseado na última ocorrência de separador
+    # Se tiver vírgula depois do último ponto, é formato BR (1.299,90)
+    # Se tiver ponto depois da última vírgula, é formato US (1,299.90)
+
+    last_comma = cleaned.rfind(',')
+    last_dot = cleaned.rfind('.')
+
+    try:
+        if last_comma > last_dot:
+            # Formato brasileiro: 1.299,90
+            # Remove pontos (separador de milhar) e troca vírgula por ponto
+            cleaned = cleaned.replace('.', '').replace(',', '.')
+        else:
+            # Formato americano: 1,299.90
+            # Remove vírgulas (separador de milhar)
+            cleaned = cleaned.replace(',', '')
+
+        value = float(cleaned)
+
+        if value < 0:
+            raise ValueError("Preço não pode ser negativo")
+
+        return value
+
+    except ValueError as e:
+        raise ValueError(f"Não foi possível converter '{price_string}' para preço: {e}")
+
+
+def parse_price_range(price_string: str) -> tuple[float, float]:
+    """
+    Parseia strings de faixa de preço.
+
+    Exemplos:
+    - "R$ 100 - R$ 200" → (100.0, 200.0)
+    - "100-200" → (100.0, 200.0)
+
+    Args:
+        price_string: String contendo a faixa de preço
+
+    Returns:
+        Tupla (preço_mínimo, preço_máximo)
+
+    Raises:
+        ValueError: Se o formato não for reconhecido
+    """
+    # Separa por hífen, "a", "até", etc
+    parts = re.split(r'\s*[-–—]\s*|\s+a\s+|\s+até\s+', price_string, maxsplit=1)
+
+    if len(parts) != 2:
+        raise ValueError(f"Formato de faixa inválido: '{price_string}'")
+
+    min_price = parse_price(parts[0])
+    max_price = parse_price(parts[1])
+
+    if min_price > max_price:
+        raise ValueError(f"Preço mínimo ({min_price}) maior que máximo ({max_price})")
+
+    return min_price, max_price

notify_utils/statistics.py

@@ -0,0 +1,362 @@
+"""
+Análise estatística de histórico de preços.
+"""
+
+from datetime import datetime, timedelta
+from typing import List, Optional
+from statistics import mean, median as median_builtin, stdev
+from .models import Price, PriceTrend
+
+
+def days_since_most_recent_price(prices: List[Price]) -> Optional[int]:
+    """
+    Calcula quantos dias se passaram desde o preço mais recente até hoje.
+
+    Útil para verificar se o histórico está desatualizado e ajustar
+    o período de análise dinamicamente.
+
+    Args:
+        prices: Lista de preços
+
+    Returns:
+        Número de dias desde o preço mais recente (arredondado para cima)
+        ou None se a lista estiver vazia
+
+    Example:
+        >>> prices = [Price(100.0, datetime.now() - timedelta(days=33))]
+        >>> days_since_most_recent_price(prices)
+        33
+    """
+    if not prices:
+        return None
+
+    # Encontra o preço mais recente
+    most_recent = max(prices, key=lambda p: p.date)
+
+    # Calcula diferença em dias (arredonda para cima)
+    time_diff = datetime.now() - most_recent.date
+    days_diff = int(time_diff.total_seconds() / 86400)  # 86400 segundos em um dia
+
+    # Arredonda para cima se houver fração de dia
+    if time_diff.total_seconds() % 86400 > 0:
+        days_diff += 1
+
+    return days_diff
+
+
+def get_recommended_period(prices: List[Price], desired_period: int) -> int:
+    """
+    Retorna o período recomendado que garante incluir o histórico mais recente.
+
+    Se o preço mais recente for mais antigo que o período desejado,
+    retorna o número de dias necessário para incluí-lo.
+
+    Args:
+        prices: Lista de preços
+        desired_period: Período desejado em dias
+
+    Returns:
+        Período ajustado que inclui o histórico mais recente
+
+    Example:
+        >>> # Histórico mais recente tem 33 dias
+        >>> prices = [Price(100.0, datetime.now() - timedelta(days=33))]
+        >>> get_recommended_period(prices, 30)
+        33  # Ajustado para incluir o histórico
+
+        >>> # Histórico recente tem 20 dias
+        >>> prices = [Price(100.0, datetime.now() - timedelta(days=20))]
+        >>> get_recommended_period(prices, 30)
+        30  # Mantém período desejado
+    """
+    if not prices:
+        return desired_period
+
+    days_since = days_since_most_recent_price(prices)
+
+    if days_since is None:
+        return desired_period
+
+    # Retorna o maior entre o período desejado e dias desde o mais recente
+    return max(desired_period, days_since)
+
+
+def filter_by_period_range(
+    prices: List[Price],
+    start_days: int,
+    end_days: int
+) -> List[Price]:
+    """
+    Filtra preços por um intervalo de dias (ignorando dias muito recentes).
+
+    Útil para ignorar ruído de dados muito recentes (mesmo dia, próximos dias).
+
+    Args:
+        prices: Lista de preços
+        start_days: Começa N dias atrás (ex: 3 = ignora 0, 1, 2 dias)
+        end_days: Termina M dias atrás (ex: 30 = até 30 dias atrás)
+
+    Returns:
+        Lista de preços entre [hoje-end_days ... hoje-start_days]
+
+    Raises:
+        ValueError: Se start_days < 0, end_days <= 0, ou start_days >= end_days
+
+    Example:
+        >>> # Ignora preços de 0-2 dias, usa apenas 3-30 dias
+        >>> filtered = filter_by_period_range(prices, start_days=3, end_days=30)
+        >>> # Retorna preços entre hoje-30d e hoje-3d
+    """
+    if start_days < 0:
+        raise ValueError("start_days deve ser >= 0")
+    if end_days <= 0:
+        raise ValueError("end_days deve ser > 0")
+    if start_days >= end_days:
+        raise ValueError("start_days deve ser menor que end_days")
+
+    now = datetime.now()
+    start_date = now - timedelta(days=start_days)  # Data mais recente permitida
+    end_date = now - timedelta(days=end_days)      # Data mais antiga permitida
+
+    # Filtra preços entre end_date (mais antigo) e start_date (mais recente)
+    return [p for p in prices if end_date <= p.date <= start_date]
+
+
+def filter_by_period(prices: List[Price], days: int) -> List[Price]:
+    """
+    Filtra preços por período de dias a partir de hoje.
+
+    Args:
+        prices: Lista de preços
+        days: Número de dias para filtrar (ex: 7, 30, 90)
+
+    Returns:
+        Lista de preços dentro do período especificado
+    """
+    if days <= 0:
+        raise ValueError("Número de dias deve ser positivo")
+
+    cutoff_date = datetime.now() - timedelta(days=days)
+    return [p for p in prices if p.date >= cutoff_date]
+
+
+def calculate_mean(prices: List[Price], days: Optional[int] = None) -> Optional[float]:
+    """
+    Calcula a média de preços.
+
+    Args:
+        prices: Lista de preços
+        days: Número de dias para filtrar (opcional, se None considera todos os preços)
+
+    Returns:
+        Média dos preços ou None se lista vazia
+
+    Raises:
+        ValueError: Se days for <= 0
+    """
+    if not prices:
+        return None
+
+    filtered_prices = filter_by_period(prices, days) if days else prices
+
+    if not filtered_prices:
+        return None
+
+    values = [p.value for p in filtered_prices]
+    return round(mean(values), 2)
+
+
+def calculate_median(prices: List[Price], days: Optional[int] = None) -> Optional[float]:
+    """
+    Calcula a mediana de preços.
+
+    Args:
+        prices: Lista de preços
+        days: Número de dias para filtrar (opcional, se None considera todos os preços)
+
+    Returns:
+        Mediana dos preços ou None se lista vazia
+
+    Raises:
+        ValueError: Se days for <= 0
+    """
+    if not prices:
+        return None
+
+    filtered_prices = filter_by_period(prices, days) if days else prices
+
+    if not filtered_prices:
+        return None
+
+    values = [p.value for p in filtered_prices]
+    return round(median_builtin(values), 2)
+
+
+def get_min_max(
+    prices: List[Price],
+    days: Optional[int] = None
+) -> Optional[tuple[float, float]]:
+    """
+    Retorna o preço mínimo e máximo do período.
+
+    Args:
+        prices: Lista de preços
+        days: Número de dias para filtrar (opcional)
+
+    Returns:
+        Tupla (preço_mínimo, preço_máximo) ou None se lista vazia
+
+    Raises:
+        ValueError: Se days for <= 0
+    """
+    if not prices:
+        return None
+
+    filtered_prices = filter_by_period(prices, days) if days else prices
+
+    if not filtered_prices:
+        return None
+
+    values = [p.value for p in filtered_prices]
+    return round(min(values), 2), round(max(values), 2)
+
+
+def calculate_price_statistics(
+    prices: List[Price],
+    days: Optional[int] = None
+) -> Optional[dict]:
+    """
+    Calcula estatísticas completas de preços.
+
+    Args:
+        prices: Lista de preços
+        days: Número de dias para filtrar (opcional)
+
+    Returns:
+        Dicionário com estatísticas ou None se lista vazia:
+        {
+            'mean': float,
+            'median': float,
+            'min': float,
+            'max': float,
+            'count': int,
+            'period_days': int or None
+        }
+
+    Raises:
+        ValueError: Se days for <= 0
+    """
+    if not prices:
+        return None
+
+    filtered_prices = filter_by_period(prices, days) if days else prices
+
+    if not filtered_prices:
+        return None
+
+    values = [p.value for p in filtered_prices]
+
+    return {
+        'mean': round(mean(values), 2),
+        'median': round(median_builtin(values), 2),
+        'min': round(min(values), 2),
+        'max': round(max(values), 2),
+        'count': len(values),
+        'period_days': days
+    }
+
+
+def calculate_volatility(prices: List[Price]) -> Optional[float]:
+    """
+    Calcula a volatilidade (desvio padrão) dos preços.
+
+    Args:
+        prices: Lista de preços
+
+    Returns:
+        Desvio padrão dos preços ou None se lista vazia ou com apenas 1 item
+    """
+    if not prices or len(prices) < 2:
+        return None
+
+    values = [p.value for p in prices]
+    try:
+        return round(stdev(values), 2)
+    except:
+        return None
+
+
+def calculate_price_trend(
+    prices: List[Price],
+    days: int = 30,
+    stability_threshold: float = 5.0
+) -> Optional[PriceTrend]:
+    """
+    Analisa a tendência de preço com informações detalhadas.
+
+    Compara a média dos últimos N dias com a média do período anterior
+    e retorna análise completa incluindo volatilidade e confiança.
+
+    Args:
+        prices: Lista de preços
+        days: Período em dias para análise (padrão: 30)
+        stability_threshold: % de mudança para considerar estável (padrão: 5.0)
+
+    Returns:
+        PriceTrend com análise detalhada ou None se não houver dados suficientes
+    """
+    if len(prices) < 2:
+        return None
+
+    # Divide em dois períodos
+    recent_prices = filter_by_period(prices, days)
+    cutoff_date = datetime.now() - timedelta(days=days)
+    older_cutoff = cutoff_date - timedelta(days=days)
+    older_prices = [p for p in prices if older_cutoff <= p.date < cutoff_date]
+
+    if not recent_prices or not older_prices:
+        return None
+
+    # Calcula médias
+    recent_mean = mean([p.value for p in recent_prices])
+    older_mean = mean([p.value for p in older_prices])
+
+    # Calcula mudança percentual (positivo = aumento, negativo = queda)
+    change_pct = ((recent_mean - older_mean) / older_mean) * 100
+
+    # Determina direção
+    if abs(change_pct) < stability_threshold:
+        direction = "stable"
+    elif change_pct > 0:
+        direction = "increasing"
+    else:
+        direction = "decreasing"
+
+    # Calcula volatilidade (de todos os preços dos dois períodos)
+    all_period_prices = recent_prices + older_prices
+    volatility = calculate_volatility(all_period_prices) or 0.0
+
+    # Determina se está acelerando (mudança > 10%)
+    is_accelerating = abs(change_pct) >= 10.0
+
+    # Calcula confiança baseado na quantidade de amostras
+    total_samples = len(recent_prices) + len(older_prices)
+    if total_samples >= 20:
+        confidence = "high"
+    elif total_samples >= 10:
+        confidence = "medium"
+    else:
+        confidence = "low"
+
+    return PriceTrend(
+        direction=direction,
+        change_percentage=round(change_pct, 2),
+        recent_avg=round(recent_mean, 2),
+        previous_avg=round(older_mean, 2),
+        volatility=volatility,
+        confidence=confidence,
+        samples_recent=len(recent_prices),
+        samples_previous=len(older_prices),
+        is_accelerating=is_accelerating,
+        analysis_period_days=days
+    )

notify_utils/validators.py

@@ -0,0 +1,98 @@
+"""
+Validadores para preços e dados relacionados.
+"""
+
+from datetime import datetime
+from typing import Union
+
+
+def validate_price(value: Union[float, int]) -> bool:
+    """
+    Valida se um valor de preço é válido.
+
+    Args:
+        value: Valor a ser validado
+
+    Returns:
+        True se válido, False caso contrário
+    """
+    if not isinstance(value, (int, float)):
+        return False
+
+    return value >= 0
+
+
+def validate_currency(currency: str) -> bool:
+    """
+    Valida se um código de moeda é válido (formato básico).
+
+    Args:
+        currency: Código da moeda (ex: "BRL", "USD")
+
+    Returns:
+        True se válido, False caso contrário
+    """
+    if not isinstance(currency, str):
+        return False
+
+    # Códigos de moeda geralmente têm 3 letras maiúsculas
+    return len(currency) == 3 and currency.isupper() and currency.isalpha()
+
+
+def validate_date(date: datetime) -> bool:
+    """
+    Valida se uma data é válida e não está no futuro.
+
+    Args:
+        date: Data a ser validada
+
+    Returns:
+        True se válida, False caso contrário
+    """
+    if not isinstance(date, datetime):
+        return False
+
+    # Não aceita datas futuras
+    return date <= datetime.now()
+
+
+def validate_discount_percentage(percentage: float) -> bool:
+    """
+    Valida se um percentual de desconto é razoável.
+
+    Args:
+        percentage: Percentual de desconto
+
+    Returns:
+        True se válido (entre -100 e 100), False caso contrário
+    """
+    if not isinstance(percentage, (int, float)):
+        return False
+
+    # Permite de -100% (aumento de 100%) até 100% (desconto de 100%)
+    return -100 <= percentage <= 100
+
+
+def is_suspicious_discount(
+    current_price: float,
+    advertised_old_price: float,
+    min_percentage: float = 70.0
+) -> bool:
+    """
+    Verifica se um desconto é suspeito (muito alto).
+
+    Descontos acima de 70% geralmente são suspeitos de fraude.
+
+    Args:
+        current_price: Preço atual
+        advertised_old_price: Preço "de" anunciado
+        min_percentage: Percentual mínimo para considerar suspeito (padrão: 70%)
+
+    Returns:
+        True se suspeito, False caso contrário
+    """
+    if current_price >= advertised_old_price:
+        return False
+
+    discount_pct = ((advertised_old_price - current_price) / advertised_old_price) * 100
+    return discount_pct >= min_percentage