Utilidades

El módulo util.py proporciona funciones auxiliares para normalización, escape, JWT, dimensiones de imagen, etc.

Funciones de Normalización

normalize_phone(phone: str) -> str

Normaliza un número cubano al formato 53XXXXXXXX.

normalize_phone("+5351234567")   # "5351234567"
normalize_phone("51234567")      # "5351234567"

build_jid(phone: str) -> str

Construye un JID ToDus.

build_jid("5312345678")  # "5312345678@im.todus.cu"

parse_jid(jid: str) -> tuple[str, str]

Extrae número de teléfono y resource de un JID.

parse_jid("5312345678@im.todus.cu/resource")
# ("5312345678", "resource")

Generación de Tokens

generate_token(length: int = 8) -> str

Genera un token alfanumérico criptográficamente seguro (usando secrets).

token = generate_token(16)  # "aB3dEfGhIjKlMnOp"

Escape XML

escape_xml(text: str) -> str

Escapa caracteres especiales XML (&, <, >, ').

escape_xml("Hola & adiós")  # "Hola & adiós"

unescape_xml(text: str) -> str

Revierte el escape XML.

unescape_xml("Hola & adiós")  # "Hola & adiós"

JWT

jwt_decode_payload(token: str) -> dict

Decodifica el payload de un JWT sin verificar la firma.

payload = jwt_decode_payload(token)
# {"username": "5312345678", "exp": 1234567890, ...}

Tiempo

timestamp_ms() -> int

Retorna el timestamp actual en milisegundos.

ts = timestamp_ms()  # 1700000000000

Formato de Tamaños

format_size(size_bytes: int) -> str

Formatea bytes a unidades humanas (B, KB, MB, GB).

format_size(1500000)  # "1.4 MB"

Dimensiones de Imagen

get_image_dimensions(data: bytes) -> tuple[int, int]

Extrae ancho y alto de imágenes JPEG o PNG sin decodificar completamente.

with open("foto.jpg", "rb") as f:
    data = f.read()
width, height = get_image_dimensions(data)
print(f"{width}x{height}")

BlurHash

generate_blurhash(width: int, height: int) -> str

Genera un BlurHash genérico basado en dimensiones (placeholder).

hash = generate_blurhash(800, 600)
# "LFE_@w00ay00ay00ay00ay00ay00ay"

Sanitización de Nombres de Archivo

sanitize_filename(filename: str, file_type: int = 0) -> str

Limpia caracteres problemáticos y añade la extensión correcta según el tipo de archivo.

sanitize_filename("foto/extraña?.jpg", FileType.PICTURE)  # "foto_extra_a_.jpg"
sanitize_filename("sin_extension", FileType.VIDEO)        # "sin_extension.mp4"