#!/usr/bin/env python3
"""
utils.py - Utilitários gerais do projeto

Este módulo contém funções utilitárias comuns usadas em todo o projeto.
"""

import re
import hashlib
from typing import Optional, List, Dict, Any
from datetime import datetime

def validate_email(email: str) -> bool:
    """
    Valida se um email tem formato válido.
    
    Args:
        email (str): Email a ser validado
        
    Returns:
        bool: True se válido, False caso contrário
    """
    pattern = r'^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$'
    return re.match(pattern, email) is not None

def hash_password(password: str) -> str:
    """
    Gera hash seguro de uma senha.
    
    Args:
        password (str): Senha em texto plano
        
    Returns:
        str: Hash da senha
    """
    return hashlib.sha256(password.encode()).hexdigest()

def format_timestamp(timestamp: datetime) -> str:
    """
    Formata timestamp para exibição.
    
    Args:
        timestamp (datetime): Timestamp a ser formatado
        
    Returns:
        str: Timestamp formatado
    """
    return timestamp.strftime("%Y-%m-%d %H:%M:%S")

def sanitize_filename(filename: str) -> str:
    """
    Remove caracteres inválidos de nome de arquivo.
    
    Args:
        filename (str): Nome do arquivo original
        
    Returns:
        str: Nome do arquivo sanitizado
    """
    # Remove caracteres especiais
    sanitized = re.sub(r'[<>:"/\\|?*]', '_', filename)
    return sanitized.strip()

def paginate_results(items: List[Any], page: int, per_page: int) -> Dict[str, Any]:
    """
    Pagina uma lista de resultados.
    
    Args:
        items (List[Any]): Lista de itens
        page (int): Número da página (1-indexed)
        per_page (int): Itens por página
        
    Returns:
        Dict[str, Any]: Resultados paginados
    """
    total = len(items)
    start = (page - 1) * per_page
    end = start + per_page
    
    return {
        'items': items[start:end],
        'total': total,
        'page': page,
        'per_page': per_page,
        'total_pages': (total + per_page - 1) // per_page
    }