ExportarExcelTurbo.py

# ExportarExcelTurbo.py
import pandas as pd
import os
import logging
import re
import time
from decimal import Decimal
from datetime import datetime
import xlsxwriter
import numpy as np # Necesario para CalculadoraColumnas

logger = logging.getLogger(__name__)

class CalculadoraColumnas:
    """
    Procesador de columnas calculadas para DataFrames.

    Ejecuta expresiones Python sobre las columnas del DataFrame y retorna
    los valores calculados como una nueva Serie de pandas.

    Características:
    - Sintaxis Python estándar (no Excel)
    - Acceso directo a columnas del DataFrame
    - Evaluación segura de expresiones
    - Soporte para funciones auxiliares personalizadas
    """

    def __init__(self, df):
        """
        Inicializa el calculador con el DataFrame base.

        Args:
            df (DataFrame): DataFrame con los datos originales
        """
        self.df = df
        self.columnas_disponibles = list(df.columns)

    def calcular_columna(self, nombre_columna, expresion_python):
        """
        Calcula una nueva columna basada en una expresión Python.

        Args:
            nombre_columna (str): Nombre de la nueva columna
            expresion_python (str): Expresión Python a evaluar

        Returns:
            pandas.Series: Serie con los valores calculados

        Ejemplo:
            # Para una expresión como: "df['Precio'] * df['Cantidad']"
            # O más simple: "Precio * Cantidad"
            serie = calculadora.calcular_columna('Total', 'Precio * Cantidad')
        """
        try:
            logger.info(f"Calculando columna '{nombre_columna}' con expresión: {expresion_python}")

            # Preparar el contexto de ejecución
            contexto = self._crear_contexto_calculo()

            # Evaluar la expresión de forma segura
            resultado = self._evaluar_expresion(expresion_python, contexto)

            # Convertir resultado a Serie si no lo es ya
            if not isinstance(resultado, pd.Series):
                # Si es un valor escalar, replicarlo para todas las filas
                if pd.api.types.is_scalar(resultado):
                    resultado = pd.Series([resultado] * len(self.df),
                                        name=nombre_columna,
                                        index=self.df.index)
                else:
                    # Si es una lista o array, convertir a Serie
                    # Asegurarse de que tenga la longitud correcta
                    if hasattr(resultado, '__len__'):
                        len_resultado = len(resultado)
                        if len_resultado == len(self.df):
                            resultado = pd.Series(resultado,
                                                name=nombre_columna,
                                                index=self.df.index)
                        elif len_resultado < len(self.df):
                             # Rellenar con NaN si es más corto
                             resultado_padded = [None] * len(self.df)
                             resultado_padded[:len_resultado] = list(resultado)
                             resultado = pd.Series(resultado_padded,
                                                 name=nombre_columna,
                                                 index=self.df.index)
                        else: # len_resultado > len(self.df)
                            # Truncar si es más largo
                            resultado = pd.Series(list(resultado)[:len(self.df)],
                                                name=nombre_columna,
                                                index=self.df.index)
                    else:
                         # Si no es iterable ni escalar, tratar como escalar
                         resultado = pd.Series([resultado] * len(self.df),
                                             name=nombre_columna,
                                             index=self.df.index)

            # Asegurar que la Serie tiene el nombre correcto
            resultado.name = nombre_columna

            logger.info(f"Columna '{nombre_columna}' calculada exitosamente ({len(resultado)} valores)")
            return resultado

        except Exception as e:
            logger.error(f"Error calculando columna '{nombre_columna}': {str(e)}")
            # Retornar serie con valores None en caso de error
            return pd.Series([None] * len(self.df), name=nombre_columna, index=self.df.index)

    def _crear_contexto_calculo(self):
        """
        Crea el contexto de variables y funciones disponibles para el cálculo.

        Returns:
            dict: Diccionario con variables y funciones disponibles
        """
        # Contexto base con el DataFrame completo
        contexto = {
            'df': self.df,
            'pd': pd,
            'np': np, # Agregar numpy al contexto
        }

        # Agregar cada columna como variable individual para sintaxis más simple
        # Esto permite usar "Precio * Cantidad" en lugar de "df['Precio'] * df['Cantidad']"
        for columna in self.columnas_disponibles:
            # Crear nombre de variable válido (reemplazar espacios y caracteres especiales)
            nombre_var = self._crear_nombre_variable_valido(columna)
            if nombre_var != columna:
                logger.debug(f"Columna '{columna}' disponible como variable '{nombre_var}'")
            contexto[nombre_var] = self.df[columna]

        # Agregar funciones auxiliares útiles
        contexto.update({
            'len': len,
            # Redefinir str para manejar Series de pandas correctamente
            'str': lambda x: x.astype(str) if isinstance(x, pd.Series) else str(x),
            'int': int,
            'float': float,
            'bool': bool,
            'abs': abs,
            'min': min,
            'max': max,
            'round': round,
            'sum': sum,
            'any': any,
            'all': all,
            'datetime': datetime,

            # Funciones auxiliares personalizadas
            'si': self._funcion_si,
            'concatenar': self._funcion_concatenar,
            'es_nulo': pd.isna,
            'no_es_nulo': pd.notna,
            'llenar_nulos': lambda serie, valor: serie.fillna(valor),
        })

        return contexto

    def _crear_nombre_variable_valido(self, nombre_columna):
        """
        Convierte un nombre de columna en un nombre de variable Python válido.

        Args:
            nombre_columna (str): Nombre original de la columna

        Returns:
            str: Nombre de variable válido
        """
        import re

        # Reemplazar espacios y caracteres especiales con guiones bajos
        nombre_limpio = re.sub(r'[^\w]', '_', str(nombre_columna))

        # Asegurar que no comience con número
        if nombre_limpio and nombre_limpio[0].isdigit():
            nombre_limpio = 'col_' + nombre_limpio

        # Evitar nombres vacíos
        if not nombre_limpio:
            nombre_limpio = 'col_sin_nombre'

        return nombre_limpio

    def _evaluar_expresion(self, expresion, contexto):
        """
        Evalúa una expresión Python de forma segura.

        Args:
            expresion (str): Expresión a evaluar
            contexto (dict): Contexto con variables disponibles

        Returns:
            any: Resultado de la evaluación
        """
        # Lista limitada de built-ins permitidos por seguridad
        builtins_seguros = {
            '__builtins__': {
                'len', 'str', 'int', 'float', 'bool', 'abs', 'min', 'max',
                'round', 'sum', 'any', 'all', 'zip', 'enumerate', 'range',
                'list', 'tuple', 'dict', 'set', 'True', 'False', 'None'
            }
        }

        try:
            # Evaluar con contexto restringido por seguridad
            resultado = eval(expresion, builtins_seguros, contexto)
            return resultado

        except Exception as e:
            raise RuntimeError(f"Error evaluando expresión '{expresion}': {str(e)}")

    # Funciones auxiliares personalizadas

    def _funcion_si(self, condicion, valor_verdadero, valor_falso):
        """
        Función condicional tipo IF de Excel pero para pandas.

        Args:
            condicion: Serie o array de condiciones booleanas
            valor_verdadero: Valor(es) cuando la condición es verdadera
            valor_falso: Valor(es) cuando la condición es falsa

        Returns:
            pandas.Series o valor: Serie con valores condicionales o un valor escalar
        """
        if isinstance(condicion, pd.Series):
            # Usar np.where para vectorizar la operación
            return pd.Series(np.where(condicion, valor_verdadero, valor_falso), index=condicion.index)
        else:
            return valor_verdadero if condicion else valor_falso

    def _funcion_concatenar(self, *args):
        """
        Concatena múltiples valores o series.

        Returns:
            pandas.Series o str: Resultado de la concatenación
        """
        if len(args) == 0:
            return ""

        # Si algún argumento es una Serie, convertir todo a Series
        series_args = []
        for arg in args:
            if isinstance(arg, pd.Series):
                series_args.append(arg.astype(str))
            else:
                # Crear una Serie con el valor repetido
                series_args.append(pd.Series([str(arg)] * len(self.df), index=self.df.index))

        if series_args:
            # Concatenar series elemento a elemento
            resultado = series_args[0]
            for serie in series_args[1:]:
                resultado = resultado + serie
            return resultado
        else:
            # Concatenar valores escalares
            return ''.join(str(arg) for arg in args)

class HojaBase:
    """
    Clase base para propiedades compartidas entre HojaExcelTurbo y HojaExcelPlaceholder.
    Reduce redundancia en setters y getters.
    """
    def __init__(self):
        self.datos = None
        self.columnas_a_mostrar = []
        self._renombra_encabezados = []
        self.formato_columnas = []
        self.cambia_resultado_a = []
        self.alineaciones_horizontales = []
        self.columnas_calculadas = []
        self.sangrias_columnas = []
        self.mostrar_encabezados = True  # Por defecto, mostrar encabezados
        self.fila_inicial = 1  # Fila inicial por defecto

    @property
    def Columnas_a_mostrar(self):
        return self.columnas_a_mostrar

    @Columnas_a_mostrar.setter
    def Columnas_a_mostrar(self, columnas):
        self.columnas_a_mostrar = columnas if columnas else []

    @property
    def Renombra_Encabezados(self):
        return self._renombra_encabezados

    @Renombra_Encabezados.setter
    def Renombra_Encabezados(self, encabezados):
        self._renombra_encabezados = encabezados if encabezados else []

    @property
    def Formato_Columnas(self):
        return self.formato_columnas

    @Formato_Columnas.setter
    def Formato_Columnas(self, formatos):
        self.formato_columnas = formatos if formatos else []

    @property
    def Cambia_Resultado_A(self):
        return self.cambia_resultado_a

    @Cambia_Resultado_A.setter
    def Cambia_Resultado_A(self, reemplazos):
        self.cambia_resultado_a = reemplazos if reemplazos else []

    @property
    def Alineaciones_Horizontales(self):
        return self.alineaciones_horizontales

    @Alineaciones_Horizontales.setter
    def Alineaciones_Horizontales(self, alineaciones):
        self.alineaciones_horizontales = alineaciones if alineaciones else []

    @property
    def ColumnasCalculadas(self):
        return self.columnas_calculadas

    @ColumnasCalculadas.setter
    def ColumnasCalculadas(self, definiciones):
        if not isinstance(definiciones, list):
            definiciones = [definiciones] if definiciones else []
        definiciones_validas = []
        for def_col in definiciones:
            if isinstance(def_col, dict) and 'nombre_columna' in def_col and 'expresion' in def_col:
                definiciones_validas.append(def_col)
            else:
                logger.warning(f"Definición de columna calculada inválida ignorada: {def_col}")
        self.columnas_calculadas = definiciones_validas

    @property
    def Sangrias_Columnas(self):
        return self.sangrias_columnas

    @Sangrias_Columnas.setter
    def Sangrias_Columnas(self, sangrias):
        self.sangrias_columnas = sangrias if sangrias else []

    @property
    def Mostrar_Encabezados(self):
        """Obtiene si se mostrarán los encabezados de columna en la exportación Excel."""
        return self.mostrar_encabezados

    @Mostrar_Encabezados.setter
    def Mostrar_Encabezados(self, value):
        """Establece si se mostrarán los encabezados. True para mostrar, False para omitir."""
        self.mostrar_encabezados = bool(value)

    @property
    def Fila_Inicial(self):
        """Obtiene la fila inicial donde se empezará a escribir el reporte."""
        return self.fila_inicial

    @Fila_Inicial.setter
    def Fila_Inicial(self, value):
        """Establece la fila inicial. Debe ser un entero positivo."""
        if isinstance(value, int) and value >= 1:
            self.fila_inicial = value
        else:
            logger.warning(f"Fila inicial inválida: {value}. Debe ser un entero >= 1. Usando valor por defecto: 1")
            self.fila_inicial = 1

class HojaExcelTurbo(HojaBase):
    """
    Clase para manejar una hoja individual dentro de un libro Excel usando XlsxWriter.
    Proporciona funcionalidades para:
    - Carga de datos desde diversos formatos
    - Selección de columnas específicas
    - Personalización de encabezados
    - Configuración opcional para mostrar encabezados
    - Aplicación de formatos automáticos y personalizados
    - Optimización de rendimiento para grandes volúmenes de datos
    - Reemplazo de valores específicos en columnas
    - Cálculo de columnas personalizadas (integrado)
    - Configuración de sangrías para columnas
    """
    def __init__(self, workbook, worksheet, nombre_hoja="Hoja1"):
        """
        Inicializa una nueva hoja Excel con estilos predefinidos.
        Args:
            workbook: Instancia del workbook de XlsxWriter
            worksheet: Instancia del worksheet de XlsxWriter
            nombre_hoja (str): Nombre de la hoja
        """
        super().__init__()  # Initialize base class
        self.workbook = workbook
        self.worksheet = worksheet
        self.nombre_hoja = nombre_hoja
        self.fila_actual = 0
        # Inicializar estilos de formato para mejor rendimiento
        self._inicializar_estilos()

    def _inicializar_estilos(self):
        """
        Crea y almacena todos los estilos de formato necesarios.
        XlsxWriter es más eficiente cuando los formatos se crean una sola vez
        y se reutilizan en lugar de crear nuevos formatos para cada celda.
        """
        # Formato para encabezados con fondo azul y texto blanco en negrita
        self.formato_encabezado = self.workbook.add_format({
            'bold': True,
            'font_color': 'white',
            'bg_color': '#366092',
            'align': 'center',
            'valign': 'vcenter',
        })
        # Formato para fechas en formato DD/MMM/YYYY
        self.formato_fecha = self.workbook.add_format({
            'num_format': 'dd/mmm/yyyy',
            'align': 'center',
        })
        # Formato contable para números con separadores de miles y decimales
        self.formato_contabilidad = self.workbook.add_format({
            'num_format': '#,##0.00',
            'align': 'center',
        })
        # Formato para porcentajes con dos decimales
        self.formato_porcentaje = self.workbook.add_format({
            'num_format': '0.00%',
            'align': 'center',
        })
        # Formato para números enteros con separadores de miles
        self.formato_entero = self.workbook.add_format({
            'num_format': '0',
            'align': 'center',
        })
        # Formato para texto con alineación izquierda
        self.formato_texto = self.workbook.add_format({
            'num_format': '@',
            'align': 'left',
            'valign': 'center',
        })
        # Formato general para celdas normales
        self.formato_general = self.workbook.add_format({
            'valign': 'center'
        })
        # Formatos adicionales para alineaciones específicas
        self.formato_izquierda = self.workbook.add_format({
            'align': 'left',
            'valign': 'center'
        })
        self.formato_centro = self.workbook.add_format({
            'align': 'center',
            'valign': 'center'
        })
        self.formato_derecha = self.workbook.add_format({
            'align': 'right',
            'valign': 'center'
        })

    def Carga_Datos(self, datos):
        """
        Carga los datos que serán exportados a la hoja Excel.
        Args:
            datos: Lista de diccionarios, DataFrame de pandas, o cualquier estructura
                  iterable que pueda convertirse en DataFrame
        Returns:
            self: Permite el encadenamiento de métodos (method chaining)
        """
        if datos is None:
            logger.info(f"No se proporcionaron datos para la hoja '{self.nombre_hoja}'; se exportará hoja vacía.")
            self.datos = []
        else:
            self.datos = datos
            logger.info(f"Cargados {len(datos) if hasattr(datos, '__len__') else 'N/A'} registros en la hoja '{self.nombre_hoja}'")
        return self

    # --- INICIO Propiedad para columnas calculadas ---
    @property
    def ColumnasCalculadas(self):
        """Getter para las definiciones de columnas calculadas."""
        return self.columnas_calculadas

    @ColumnasCalculadas.setter
    def ColumnasCalculadas(self, definiciones):
        """
        Define columnas calculadas que se agregarán al DataFrame.

        Args:
            definiciones (list o dict): Lista de definiciones o definición única.

        Formato de definición:
        {
            'nombre_columna': 'NombreDeLaColumna',
            'expresion': 'Precio * Cantidad',  # Expresión Python
            'entre_columna': 'ColumnaAnterior',  # Opcional: insertar después de esta
            'y_columna': 'ColumnaPosterior',     # Opcional: insertar antes de esta
            'formato': 'CONTABILIDAD'            # Opcional: formato específico
        }

        Ejemplos de expresiones:
        - 'Precio * Cantidad'
        - 'si(Estado == "Activo", "SI", "NO")'
        - 'df["Precio"].apply(lambda x: x * 1.16)' # Más complejo
        - 'concatenar(Nombre, " - ", Apellido)'
        - 'Precio * (1 + IVA/100)'
        """
        if not isinstance(definiciones, list):
            definiciones = [definiciones] if definiciones else []

        # Validar definiciones (opcional)
        definiciones_validas = []
        for def_col in definiciones:
            if isinstance(def_col, dict) and 'nombre_columna' in def_col and 'expresion' in def_col:
                definiciones_validas.append(def_col)
            else:
                logger.warning(f"Definición de columna calculada inválida ignorada: {def_col}")

        self.columnas_calculadas = definiciones_validas
        logger.info(f"Definidas {len(self.columnas_calculadas)} columnas calculadas")
    # --- FIN Propiedad para columnas calculadas ---

    def _parsear_asignacion(self, asignacion_str):
        """
        Analiza y separa las asignaciones de encabezados.
        Args:
            asignacion_str (str): String en formato 'CampoOriginal = NombreMostrado'
                                 o simplemente 'NombreCampo'
        Returns:
            tuple: (nombre_original, nombre_a_mostrar)
        """
        asignacion_str = asignacion_str.strip()
        if '=' in asignacion_str:
            partes = asignacion_str.split('=', 1)  # Dividir solo en el primer =
            original = partes[0].strip()
            mostrado = partes[1].strip()
            return original, mostrado
        else:
            # Si no hay =, usar el mismo nombre para ambos
            return asignacion_str, asignacion_str

    def _parsear_formato(self, formato_str):
        """
        Analiza y separa las definiciones de formato de columna.
        Args:
            formato_str (str): String en formato 'NombreColumna = TIPO_FORMATO'
                              o simplemente 'TIPO_FORMATO'
        Returns:
            tuple: (nombre_columna, tipo_formato)
        """
        formato_str = formato_str.strip()
        if '=' in formato_str:
            partes = formato_str.split('=', 1)
            columna = partes[0].strip()
            formato = partes[1].strip()
            return columna, formato
        else:
            # Si no hay =, asumir que es solo el tipo de formato
            return formato_str, 'AUTO'

    def _parsear_alineacion(self, alineacion_str):
        """
        Analiza y separa las definiciones de alineación horizontal.
        Args:
            alineacion_str (tuple): Tupla en formato (nombre_columna, tipo_alineacion)
        Returns:
            tuple: (nombre_columna, tipo_alineacion)
        """
        if isinstance(alineacion_str, tuple) and len(alineacion_str) == 2:
            return alineacion_str[0], alineacion_str[1].upper()
        return None, None

    def _parsear_sangria(self, sangria_str):
        """
        Analiza y separa las definiciones de sangría.
        Args:
            sangria_str (tuple): Tupla en formato (nombre_columna, nivel_sangria)
        Returns:
            tuple: (nombre_columna, nivel_sangria)
        """
        if isinstance(sangria_str, tuple) and len(sangria_str) == 2:
            return sangria_str[0], int(sangria_str[1])
        return None, None

    def _convertir_a_numero(self, valor):
        """
        Convierte diversos tipos de datos a número flotante para cálculos.
        Args:
            valor: Valor a convertir (string, int, float, Decimal, etc.)
        Returns:
            float or None: Número convertido o None si no es posible la conversión
        """
        if pd.isna(valor):
            return None
        if isinstance(valor, (int, float, Decimal)):
            return float(valor)
        if isinstance(valor, str):
            try:
                # Limpiar el string de caracteres comunes en números monetarios
                valor_limpio = valor.replace(',', '').replace('$', '').replace('€', '').strip()
                return float(valor_limpio)
            except (ValueError, TypeError):
                return None
        return None

    def _detectar_formato_automatico(self, serie_valores):
        """
        Analiza una muestra de valores para determinar automáticamente el mejor formato.
        Args:
            serie_valores: Serie o lista de valores a analizar
        Returns:
            str: Tipo de formato detectado (FECHA_ESTANDAR, CONTABILIDAD, etc.)
        """
        # Filtrar valores válidos (no nulos)
        valores_validos = [v for v in serie_valores if pd.notna(v) and v is not None]
        if not valores_validos:
            return 'TEXTO'
        # Tomar una muestra representativa para análisis
        muestra_size = min(20, len(valores_validos))
        muestra = valores_validos[:muestra_size]
        # Contadores para diferentes tipos de datos detectados
        fechas_detectadas = 0
        numeros_detectados = 0
        porcentajes_detectados = 0
        enteros_detectados = 0
        # Patrones de expresiones regulares para fechas
        patrones_fecha = [
            r'\d{1,2}/\d{1,2}/\d{4}',      # DD/MM/YYYY o MM/DD/YYYY
            r'\d{4}-\d{1,2}-\d{1,2}',      # YYYY-MM-DD
            r'\d{1,2}-\d{1,2}-\d{4}',      # DD-MM-YYYY
            r'\d{1,2}/\w{3}/\d{4}',        # DD/MMM/YYYY
        ]
        for valor in muestra:
            # Verificar si es datetime primero
            if isinstance(valor, (datetime, pd.Timestamp)):
                fechas_detectadas += 1
            elif isinstance(valor, str):
                # Verificar patrones de fecha solo si es string
                es_fecha = False
                try:
                    valor_strip = valor.strip()
                    for patron in patrones_fecha:
                        # Asegurarse de que el patrón y el valor sean strings
                        if isinstance(patron, str) and isinstance(valor_strip, str):
                            if re.match(patron, valor_strip):
                                fechas_detectadas += 1
                                es_fecha = True
                                break
                except (TypeError, re.error):
                    # Si hay error en regex, continuar con otras verificaciones
                    pass
                if not es_fecha:
                    # Intentar convertir a número
                    numero = self._convertir_a_numero(valor)
                    if numero is not None:
                        numeros_detectados += 1
                        # Verificar si es un porcentaje (entre 0 y 1, excluyendo exactamente 0 y 1)
                        if 0 < numero < 1:
                            porcentajes_detectados += 1
                        # Verificar si es un entero
                        elif numero == int(numero):
                            enteros_detectados += 1
            elif isinstance(valor, (int, float, Decimal)):
                numeros_detectados += 1
                # Para números, verificar patrones de porcentaje y enteros
                if isinstance(valor, float) and 0 < valor < 1:
                    porcentajes_detectados += 1
                elif isinstance(valor, (int, Decimal)) or (isinstance(valor, float) and valor.is_integer()):
                    enteros_detectados += 1
            # Ignorar tipos booleanos y otros tipos no reconocidos
        # Determinar el formato basado en la mayoría de la muestra
        total_muestra = len(muestra)
        umbral_mayoria = total_muestra * 0.6  # 60% de la muestra
        if fechas_detectadas >= umbral_mayoria:
            return 'FECHA_ESTANDAR'
        elif porcentajes_detectados >= total_muestra * 0.5:  # 50% para porcentajes
            return 'PORCENTAJE'
        elif numeros_detectados >= umbral_mayoria:
            # Decidir entre entero y decimal
            if enteros_detectados >= numeros_detectados * 0.8:  # 80% son enteros
                return 'ENTERO'
            else:
                return 'CONTABILIDAD'
        else:
            return 'TEXTO'

    def _obtener_formato_por_tipo(self, tipo_formato):
        """
        Retorna el formato XlsxWriter correspondiente al tipo solicitado.
        Args:
            tipo_formato (str): Tipo de formato solicitado
        Returns:
            XlsxWriter Format object: Formato correspondiente
        """
        formatos_mapa = {
            'FECHA_ESTANDAR': self.formato_fecha,
            'CONTABILIDAD': self.formato_contabilidad,
            'PORCENTAJE': self.formato_porcentaje,
            'ENTERO': self.formato_entero,
            'TEXTO': self.formato_texto
        }
        return formatos_mapa.get(tipo_formato, self.formato_general)

    def _obtener_formato_alineacion(self, tipo_alineacion):
        """
        Retorna el formato XlsxWriter correspondiente a la alineación solicitada.
        Args:
            tipo_alineacion (str): Tipo de alineación solicitada (LEFT, CENTER, RIGHT)
        Returns:
            XlsxWriter Format object: Formato correspondiente
        """
        alineaciones_mapa = {
            'LEFT': self.formato_izquierda,
            'CENTER': self.formato_centro,
            'RIGHT': self.formato_derecha
        }
        return alineaciones_mapa.get(tipo_alineacion.upper(), self.formato_general)

    def _crear_formato_combinado(self, formato_base, alineacion):
        """
        Crea un formato combinado que incluye tanto el formato base como la alineación.
        Args:
            formato_base: Formato XlsxWriter base
            alineacion (str): Tipo de alineación (LEFT, CENTER, RIGHT)
        Returns:
            XlsxWriter Format object: Formato combinado
        """
        # Obtener las propiedades del formato base
        props_base = formato_base.__dict__.get('_format_properties', {})
        # Obtener las propiedades de alineación
        formato_alineacion = self._obtener_formato_alineacion(alineacion)
        props_alineacion = formato_alineacion.__dict__.get('_format_properties', {})
        # Combinar propiedades
        props_combinadas = props_base.copy()
        props_combinadas.update(props_alineacion)
        # Crear nuevo formato con propiedades combinadas
        return self.workbook.add_format(props_combinadas)

    def _mostrar_encabezados(self, df):
        """
        Muestra los encabezados de las columnas con formato especial (si está habilitado).
        Args:
            df (DataFrame): DataFrame con los datos y columnas finales
        """
        if not self.mostrar_encabezados:
            logger.info(f"Saltando escritura de encabezados para hoja '{self.nombre_hoja}' según configuración.")
            # self.fila_actual ya está configurado en _escribir_y_formatear
            return
        
        encabezados = list(df.columns)
        for col_idx, encabezado in enumerate(encabezados):
            self.worksheet.write(self.fila_actual, col_idx, encabezado, self.formato_encabezado)
        self.fila_actual += 1  # La siguiente fila disponible después de los encabezados

    def _obtener_formatos_para_columnas(self, df):
        """
        Obtiene los formatos correspondientes para cada columna.
        Args:
            df (DataFrame): DataFrame con los datos
        Returns:
            dict: Diccionario con índice de columna y su formato correspondiente
        """
        # Si no se han definido formatos de columna, no aplicar ningún formato
        if not self.formato_columnas and not self.alineaciones_horizontales and not self.sangrias_columnas:
            # Retornar formato general para todas las columnas
            formatos_resultado = {}
            for col_idx in range(len(df.columns)):
                formatos_resultado[col_idx] = self.formato_general
            return formatos_resultado
        encabezados = list(df.columns)
        formatos_resultado = {}
        # Crear mapeo de formatos definidos por el usuario
        formatos_usuario = {}
        for formato_str in self.formato_columnas:
            nombre_columna, tipo_formato = self._parsear_formato(formato_str)
            formatos_usuario[nombre_columna] = tipo_formato
        # Crear mapeo de alineaciones definidas por el usuario
        alineaciones_usuario = {}
        for alineacion_tupla in self.alineaciones_horizontales:
            nombre_columna, tipo_alineacion = self._parsear_alineacion(alineacion_tupla)
            if nombre_columna and tipo_alineacion:
                alineaciones_usuario[nombre_columna] = tipo_alineacion
        # Crear mapeo de sangrías definidas por el usuario
        sangrias_usuario = {}
        for sangria_tupla in self.sangrias_columnas:
            nombre_columna, nivel_sangria = self._parsear_sangria(sangria_tupla)
            if nombre_columna is not None and nivel_sangria is not None:
                sangrias_usuario[nombre_columna] = nivel_sangria
        # Crear mapeo de columnas originales a nombres mostrados
        mapeo_columnas = {}
        if self._renombra_encabezados:
            for asignacion in self._renombra_encabezados:
                original, mostrado = self._parsear_asignacion(asignacion)
                mapeo_columnas[original] = mostrado
        # Aplicar formatos columna por columna
        for col_idx, nombre_columna in enumerate(encabezados):
            # Buscar el nombre original de la columna
            nombre_original = None
            # Primero buscar si el nombre mostrado corresponde a algún nombre original
            for original, mostrado in mapeo_columnas.items():
                if mostrado == nombre_columna:
                    nombre_original = original
                    break
            # Si no se encontró correspondencia, usar el nombre mostrado como original
            if nombre_original is None:
                nombre_original = nombre_columna
            # Determinar el tipo de formato para esta columna
            if nombre_original in formatos_usuario:
                tipo_formato = formatos_usuario[nombre_original]
            elif nombre_columna in formatos_usuario:
                tipo_formato = formatos_usuario[nombre_columna]
            else:
                # Si no se especifica formato, usar AUTO
                tipo_formato = 'AUTO'
            # Para AUTO, detectar el formato basado en los datos
            if tipo_formato == 'AUTO':
                columna_datos = df[nombre_columna]
                tipo_formato = self._detectar_formato_automatico(columna_datos)
            # Obtener el formato XlsxWriter correspondiente
            formato_base = self._obtener_formato_por_tipo(tipo_formato)
            # Verificar si hay alineación personalizada para esta columna
            alineacion_personalizada = None
            if nombre_original in alineaciones_usuario:
                alineacion_personalizada = alineaciones_usuario[nombre_original]
            elif nombre_columna in alineaciones_usuario:
                alineacion_personalizada = alineaciones_usuario[nombre_columna]
            # Si hay alineación personalizada, crear formato combinado
            if alineacion_personalizada:
                formato_final = self._crear_formato_combinado(formato_base, alineacion_personalizada)
            else:
                formato_final = formato_base
            # Verificar si hay sangría personalizada para esta columna
            sangria_personalizada = None
            if nombre_original in sangrias_usuario:
                sangria_personalizada = sangrias_usuario[nombre_original]
            elif nombre_columna in sangrias_usuario:
                sangria_personalizada = sangrias_usuario[nombre_columna]
            # Si hay sangría personalizada, crear formato con sangría
            if sangria_personalizada is not None:
                props = formato_final.__dict__.get('_format_properties', {}).copy()
                props['indent'] = sangria_personalizada
                formato_final = self.workbook.add_format(props)
            # Guardar el formato para esta columna
            formatos_resultado[col_idx] = formato_final
        return formatos_resultado

    def _escribir_datos_optimizado(self, df):
        """
        Escribe los datos del DataFrame aplicando formatos durante la escritura.
        Args:
            df (DataFrame): DataFrame con los datos a escribir
        """
        # Primero, obtener los formatos para cada columna
        formatos_columnas = self._obtener_formatos_para_columnas(df)
        # Convertir DataFrame a lista de listas para escritura más rápida
        datos_como_listas = df.values.tolist()
        encabezados = list(df.columns)
        # Escribir fila por fila
        for fila_idx, fila_datos in enumerate(datos_como_listas):
            fila_excel = self.fila_actual + fila_idx
            # Escribir celda por celda aplicando el formato correspondiente
            for col_idx, valor in enumerate(fila_datos):
                # Convertir datetime a formato apropiado para Excel
                if isinstance(valor, pd.Timestamp):
                    valor = valor.to_pydatetime()
                elif isinstance(valor, datetime):
                    # Ya es datetime, dejarlo como está
                    pass
                elif pd.isna(valor):
                    valor = ""
                # Obtener el formato para esta columna
                formato = formatos_columnas.get(col_idx, self.formato_general)
                # Escribir con formato
                self.worksheet.write(fila_excel, col_idx, valor, formato)

    def _ajustar_ancho_columnas(self, df, incluir_encabezados=True):
        """
        Ajusta automáticamente el ancho de las columnas basado en el contenido y tipo de dato.
        Aplica lógica específica para diferentes tipos de datos para evitar anchos exagerados.
        
        Args:
            df (DataFrame): DataFrame con los datos para calcular anchos
            incluir_encabezados (bool): Si True, incluye el ancho de los encabezados en el cálculo
        """
        limites = {
            'fecha': {'min': 10, 'max': 15},
            'numero_entero': {'min': 6, 'max': 18},
            'numero_decimal': {'min': 8, 'max': 20},
            'porcentaje': {'min': 6, 'max': 10},
            'numero_como_texto': {'min': 8, 'max': 20},
            'texto': {'min': 5, 'max': 40}
        }
        
        for col_idx, columna in enumerate(df.columns):
            # Calcular el ancho base del encabezado
            if incluir_encabezados:
                ancho_encabezado = len(str(columna))
            else:
                ancho_encabezado = 0
            
            # Obtener muestra de datos para análisis
            muestra_datos = df[columna].dropna().head(200)  # Muestra más grande, sin valores nulos
            
            if muestra_datos.empty:
                # Si no hay datos, usar solo el ancho del encabezado
                ancho_ajustado = max(ancho_encabezado + 2, 8)
                self.worksheet.set_column(col_idx, col_idx, ancho_ajustado)
                continue
            
            # Detectar el tipo de datos de la columna
            tipo_columna = self._detectar_tipo_columna_para_ancho(muestra_datos)
            
            # Calcular ancho según el tipo de datos
            ancho_contenido = self._calcular_ancho_por_tipo(muestra_datos, tipo_columna)
            
            # Aplicar límite al ancho del contenido
            limite = limites.get(tipo_columna, {'min': 5, 'max': 50})
            ancho_contenido_limited = min(ancho_contenido, limite['max'])
            
            # Combinar ancho de encabezado y contenido limitado
            ancho_total = max(ancho_encabezado, ancho_contenido_limited)
            
            # Aplicar límites finales (solo mínimo, ya que el máximo ya se aplicó al contenido)
            ancho_ajustado = max(limite['min'], ancho_total)
            
            # Agregar padding mínimo
            ancho_final = ancho_ajustado + 1
            
            self.worksheet.set_column(col_idx, col_idx, ancho_final)
            
            logger.debug(f"Columna '{columna}' ({tipo_columna}): ancho={ancho_final}")

    def _detectar_tipo_columna_para_ancho(self, muestra_datos):
        """
        Detecta el tipo de datos de una columna para optimizar el cálculo de ancho.
        
        Args:
            muestra_datos: Serie de pandas con muestra de datos
            
        Returns:
            str: Tipo detectado ('fecha', 'numero_entero', 'numero_decimal', 'porcentaje', 'texto')
        """
        if muestra_datos.empty:
            return 'texto'
        
        # Verificar si son fechas/datetime
        if muestra_datos.dtype.name.startswith('datetime') or isinstance(muestra_datos.iloc[0], (datetime, pd.Timestamp)):
            return 'fecha'
        
        # Verificar si son números
        if pd.api.types.is_numeric_dtype(muestra_datos):
            # Analizar si son enteros o decimales
            valores_numericos = muestra_datos[pd.to_numeric(muestra_datos, errors='coerce').notna()]
            
            if valores_numericos.empty:
                return 'texto'
            
            # Verificar si todos son enteros
            son_enteros = all(isinstance(val, (int, np.integer)) or 
                             (isinstance(val, (float, np.floating)) and val.is_integer()) 
                             for val in valores_numericos)
            
            if son_enteros:
                return 'numero_entero'
            
            # Verificar si parecen porcentajes (valores entre 0 y 1)
            valores_float = valores_numericos.astype(float)
            if (valores_float >= 0).all() and (valores_float <= 1).all() and len(valores_numericos) > 5:
                return 'porcentaje'
            
            return 'numero_decimal'
        
        # Para strings, verificar patrones específicos
        if muestra_datos.dtype == 'object':
            # Intentar convertir a números para detectar números como strings
            valores_como_numeros = pd.to_numeric(muestra_datos, errors='coerce')
            if not valores_como_numeros.isna().all():
                # Si más del 80% se pueden convertir a números, tratarlos como números
                porcentaje_numericos = valores_como_numeros.notna().sum() / len(muestra_datos)
                if porcentaje_numericos > 0.8:
                    return 'numero_como_texto'
        
        return 'texto'

    def _calcular_ancho_por_tipo(self, muestra_datos, tipo_columna):
        """
        Calcula el ancho necesario basado en el tipo de datos específico.
        
        Args:
            muestra_datos: Serie con muestra de datos
            tipo_columna: Tipo de datos detectado
            
        Returns:
            int: Ancho calculado para el contenido
        """
        if tipo_columna == 'fecha':
            # Las fechas suelen tener formato fijo: "DD/MMM/YYYY" = 11 caracteres
            return 12
        
        elif tipo_columna == 'numero_entero':
            # Para enteros, calcular basado en el valor máximo en la muestra
            valores_numericos = pd.to_numeric(muestra_datos, errors='coerce').dropna()
            if valores_numericos.empty:
                return 8
            
            max_valor = abs(valores_numericos).max()
            if max_valor < 1000:
                return 6  # Números pequeños
            elif max_valor < 1000000:
                return 10  # Miles con separadores
            else:
                return 15  # Millones con separadores
        
        elif tipo_columna == 'numero_decimal':
            # Para decimales, considerar formato contable con 2 decimales
            valores_numericos = pd.to_numeric(muestra_datos, errors='coerce').dropna()
            if valores_numericos.empty:
                return 10
            
            max_valor = abs(valores_numericos).max()
            if max_valor < 1000:
                return 8  # "999.99"
            elif max_valor < 1000000:
                return 12  # "999,999.99"
            else:
                return 16  # "999,999,999.99"
        
        elif tipo_columna == 'porcentaje':
            # Porcentajes: "99.99%" = 6 caracteres máximo
            return 7
        
        elif tipo_columna == 'numero_como_texto':
            # Números almacenados como texto, usar lógica similar a números
            try:
                valores_convertidos = pd.to_numeric(muestra_datos, errors='coerce').dropna()
                if not valores_convertidos.empty:
                    return self._calcular_ancho_por_tipo(valores_convertidos, 'numero_decimal')
            except:
                pass
            return self._calcular_ancho_texto(muestra_datos)
        
        else:  # tipo_columna == 'texto'
            return self._calcular_ancho_texto(muestra_datos)

    def _calcular_ancho_texto(self, muestra_datos):
        """
        Calcula el ancho para columnas de texto de manera más inteligente.
        
        Args:
            muestra_datos: Serie con muestra de datos de texto
            
        Returns:
            int: Ancho calculado
        """
        longitudes = muestra_datos.astype(str).str.len()
        
        # Usar percentil 95 en lugar del máximo para evitar valores extremos
        percentil_95 = longitudes.quantile(0.95)
        promedio = longitudes.mean()
        
        # Usar el menor entre percentil 95 y promedio * 2
        ancho_calculado = min(percentil_95, promedio * 2)
        
        return max(int(ancho_calculado), 5)  # Mínimo 5 caracteres

    def _aplicar_limites_por_tipo(self, ancho_calculado, tipo_columna):
        """
        Aplica límites específicos por tipo de datos para evitar anchos extremos.
        Ahora permite anchos mayores si el encabezado lo requiere, ya que el contenido ya está limitado.
        
        Args:
            ancho_calculado: Ancho calculado base (ya incluye límite para contenido)
            tipo_columna: Tipo de datos
            
        Returns:
            int: Ancho con límites aplicados
        """
        limites = {
            'fecha': {'min': 10, 'max': 15},
            'numero_entero': {'min': 6, 'max': 18},
            'numero_decimal': {'min': 8, 'max': 20},
            'porcentaje': {'min': 6, 'max': 10},
            'numero_como_texto': {'min': 8, 'max': 20},
            'texto': {'min': 5, 'max': 40}
        }
        
        limite = limites.get(tipo_columna, {'min': 5, 'max': 50})
        # Solo aplicar el mínimo; el máximo ya se aplicó al contenido para permitir encabezados largos
        return max(limite['min'], ancho_calculado)

    def _aplicar_reemplazos(self, df):
        """
        Aplica los reemplazos definidos en `cambia_resultado_a`.
        Args:
            df (DataFrame): DataFrame original
        Returns:
            DataFrame: DataFrame con valores reemplazados
        """
        if not self.cambia_resultado_a:
            return df
        df_mod = df.copy()
        for item in self.cambia_resultado_a:
            # Soportar ambos formatos: con y sin tipo_valor
            if len(item) == 4:
                columna, tipo_valor, valor_original, valor_reemplazo = item
            elif len(item) == 3:
                columna, valor_original, valor_reemplazo = item
            else:
                logger.warning(f"Formato de reemplazo inválido: {item}")
                continue
            if columna not in df_mod.columns:
                logger.warning(f"Columna '{columna}' no encontrada para reemplazo.")
                continue
            # Aplicar el reemplazo manejando correctamente valores None
            try:
                # Para valores None, usar el parámetro específico
                if pd.isna(valor_original):
                    # Reemplazar valores NaN/None
                    df_mod[columna] = df_mod[columna].fillna(valor_reemplazo)
                else:
                    # Reemplazo normal para otros valores
                    df_mod[columna] = df_mod[columna].replace(valor_original, valor_reemplazo)
            except Exception as e:
                logger.warning(f"Error aplicando reemplazo en columna '{columna}': {str(e)}")
        return df_mod

    # --- INICIO Lógica para aplicar columnas calculadas ---
    def _aplicar_columnas_calculadas(self, df):
        """
        Aplica todas las columnas calculadas definidas al DataFrame.

        Args:
            df (DataFrame): DataFrame original

        Returns:
            DataFrame: DataFrame con columnas calculadas agregadas
        """
        if not self.columnas_calculadas:
            return df

        df_resultado = df.copy()
        logger.debug(f"Aplicando {len(self.columnas_calculadas)} columnas calculadas...")

        # Ordenar columnas para mantener el orden original en la inserción
        # Se procesarán en orden para que las referencias a columnas calculadas anteriores funcionen
        # Este ordenamiento simple asume que el usuario define el orden deseado.
        # Para una lógica más compleja de dependencias, se necesitaría un análisis topológico.

        for definicion in self.columnas_calculadas:
            try:
                nombre_columna = definicion['nombre_columna']
                expresion = definicion['expresion']

                logger.debug(f"Procesando columna calculada: '{nombre_columna}' con '{expresion}'")

                # Crear calculadora con el DataFrame actual (puede incluir columnas ya calculadas)
                calculadora = CalculadoraColumnas(df_resultado)

                # Calcular la nueva columna
                nueva_columna = calculadora.calcular_columna(nombre_columna, expresion)

                # Determinar posición de inserción
                posicion = self._determinar_posicion_insercion(df_resultado, definicion)

                # Insertar columna en la posición determinada
                df_resultado = self._insertar_columna_en_posicion(
                    df_resultado, nueva_columna, posicion
                )

                logger.info(f"Columna '{nombre_columna}' agregada exitosamente")

            except Exception as e:
                logger.error(f"Error procesando columna calculada '{definicion.get('nombre_columna', 'unknown')}': {str(e)}")
                # Opcional: continuar con las demás o detenerse?
                # continue # Descomentar para continuar con otras columnas

        return df_resultado

    def _determinar_posicion_insercion(self, df, definicion):
        """
        Determina dónde insertar una nueva columna calculada.

        Args:
            df (DataFrame): DataFrame actual
            definicion (dict): Definición de la columna

        Returns:
            int: Posición de inserción (None = al final)
        """
        entre_columna = definicion.get('entre_columna')
        y_columna = definicion.get('y_columna')

        try:
            if entre_columna and y_columna:
                # Insertar entre dos columnas (después de 'entre_columna')
                if entre_columna in df.columns and y_columna in df.columns:
                    pos_entre = df.columns.get_loc(entre_columna)
                    # pos_y = df.columns.get_loc(y_columna) # No se usa directamente
                    # Se inserta después de 'entre_columna'
                    return pos_entre + 1
                else:
                    logger.warning(f"No se encontraron columnas '{entre_columna}' o '{y_columna}' para insertar entre ellas.")
                    return len(df.columns) # Insertar al final si no se encuentran

            elif entre_columna:
                # Insertar después de una columna
                if entre_columna in df.columns:
                    return df.columns.get_loc(entre_columna) + 1
                else:
                   logger.warning(f"Columna '{entre_columna}' no encontrada para insertar después.")
                   return len(df.columns) # Insertar al final

            elif y_columna:
                # Insertar antes de una columna
                if y_columna in df.columns:
                    return df.columns.get_loc(y_columna)
                else:
                   logger.warning(f"Columna '{y_columna}' no encontrada para insertar antes.")
                   return len(df.columns) # Insertar al final

            # Si no se especifica o no se encuentra, insertar al final
            return len(df.columns) # None también funciona, pero len(df.columns) es más explícito

        except Exception as e:
            logger.warning(f"Error determinando posición de inserción: {str(e)}")
            return len(df.columns) # Por defecto, al final

    def _insertar_columna_en_posicion(self, df, nueva_columna, posicion):
        """
        Inserta una columna en una posición específica del DataFrame.

        Args:
            df (DataFrame): DataFrame base
            nueva_columna (Series): Columna a insertar
            posicion (int o None): Posición de inserción

        Returns:
            DataFrame: DataFrame con la nueva columna insertada
        """
        if posicion is None or posicion >= len(df.columns):
            # Agregar al final
            df[nueva_columna.name] = nueva_columna
            return df

        # Insertar en posición específica
        columnas = list(df.columns)
        # Asegurarse de que la posición no sea negativa
        posicion = max(0, posicion)
        columnas.insert(posicion, nueva_columna.name)

        # Crear DataFrame con nuevo orden
        df_con_nueva = df.copy()
        df_con_nueva[nueva_columna.name] = nueva_columna

        return df_con_nueva[columnas]
    # --- FIN Lógica para aplicar columnas calculadas ---

    def _exportar_datos(self):
        """
        Método principal que orquesta todo el proceso de exportación de datos.
        Este método:
        1. Valida que hay datos para exportar
        2. Convierte los datos a DataFrame
        3. APLICA COLUMNAS CALCULADAS
        4. Aplica reemplazos personalizados (ahora incluye columnas calculadas)
        5. Filtra columnas si se especifican
        6. Renombra encabezados según configuración
        7. Mostrar encabezados (si está habilitado) y datos
        8. Aplica formatos
        9. Ajusta anchos de columnas
        """
        inicio_exportacion = time.time()
        df = self._preparar_dataframe()
        if df.empty:
            logger.info(f"DataFrame vacío en hoja '{self.nombre_hoja}'; exportando hoja vacía con formatos (encabezados según configuración).")
            self._escribir_y_formatear(df)  # Muestra formatos y encabezados (si está habilitado) por consistencia
        else:
            df = self._aplicar_columnas_calculadas(df)
            df = self._aplicar_reemplazos(df)
            df = self._filtrar_y_renombrar(df)
            self._escribir_y_formatear(df)
            fin_exportacion = time.time()
            logger.info(f"Hoja '{self.nombre_hoja}' exportada en {fin_exportacion - inicio_exportacion:.2f} segundos")

    def _preparar_dataframe(self):
        df = pd.DataFrame(self.datos)
        logger.info(f"Procesando {len(df)} registros en la hoja '{self.nombre_hoja}'")

        # Si el DataFrame está vacío pero tenemos columnas_a_mostrar definidas,
        # preparar un DataFrame vacío con encabezados correctos
        if df.empty and self.columnas_a_mostrar:
            df = self._preparar_dataframe_vacio()

        return df

    def _preparar_dataframe_vacio(self):
        """
        Prepara un DataFrame vacío con las columnas y encabezados correctos.
        Útil cuando no hay datos pero queremos mantener la estructura del Excel.
        """
        # Crear DataFrame vacío con las columnas especificadas
        df = pd.DataFrame(columns=self.columnas_a_mostrar)

        # Aplicar renombrado de encabezados para DataFrames vacíos
        if self._renombra_encabezados:
            mapeo_encabezados = {}
            for asignacion in self._renombra_encabezados:
                original, mostrado = self._parsear_asignacion(asignacion)
                if original in df.columns:
                    mapeo_encabezados[original] = mostrado
                else:
                    logger.warning(f"Columna '{original}' no encontrada para renombrar a '{mostrado}'")

            if mapeo_encabezados:
                df = df.rename(columns=mapeo_encabezados)

        return df

    def _filtrar_y_renombrar(self, df):
        # Filtrar columnas si se especifican
        if self.columnas_a_mostrar:
            columnas_existentes = [col for col in self.columnas_a_mostrar if col in df.columns]
            columnas_faltantes = [col for col in self.columnas_a_mostrar if col not in df.columns]
            if columnas_faltantes:
                logger.warning(f"Columnas no encontradas en los datos: {columnas_faltantes}")
            if columnas_existentes:
                df = df[columnas_existentes]
            else:
                logger.error("Ninguna de las columnas especificadas existe en los datos")
                return df  # Return df to avoid None

        # Crear mapeo de encabezados personalizados
        mapeo_encabezados = {}
        if self._renombra_encabezados:
            for asignacion in self._renombra_encabezados:
                original, mostrado = self._parsear_asignacion(asignacion)
                if original in df.columns:
                    mapeo_encabezados[original] = mostrado
                else:
                    logger.warning(f"Columna '{original}' no encontrada para renombrar a '{mostrado}'")

        # Aplicar renombrado de encabezados
        if mapeo_encabezados:
            df = df.rename(columns=mapeo_encabezados)
        return df

    def _escribir_y_formatear(self, df):
        # Inicializar fila_actual basado en fila_inicial (0-based para XlsxWriter)
        self.fila_actual = self.fila_inicial - 1
        
        if df.empty:
            # Para DataFrames vacíos: mostrar encabezados (si está habilitado) y ajustar anchos de columna
            # respetando la configuración del usuario
            if self.mostrar_encabezados:
                self._mostrar_encabezados(df)
                self._ajustar_ancho_columnas(df, incluir_encabezados=True)  # Incluir encabezados en el cálculo
            else:
                self._ajustar_ancho_columnas(df, incluir_encabezados=False)  # No incluir encabezados en el cálculo
        else:
            # Para DataFrames no vacíos
            if self.mostrar_encabezados:
                self._mostrar_encabezados(df)
                self._escribir_datos_optimizado(df)
                self._ajustar_ancho_columnas(df, incluir_encabezados=True)  # Incluir encabezados en el cálculo
            else:
                self._escribir_datos_optimizado(df)
                self._ajustar_ancho_columnas(df, incluir_encabezados=False)  # No incluir encabezados en el cálculo

    def __enter__(self):
        """Soporte para context manager (with statement)."""
        return self

    def __exit__(self, exc_type, exc_val, exc_tb):
        """
        Ejecuta la exportación automáticamente al salir del context manager.
        Args:
            exc_type: Tipo de excepción si ocurrió
            exc_val: Valor de la excepción si ocurrió
            exc_tb: Traceback de la excepción si ocurrió
        """
        try:
            self._exportar_datos()
        except Exception as e:
            logger.error(f"Error durante la exportación de la hoja '{self.nombre_hoja}': {str(e)}")
            raise

class LibroExcelTurbo:
    """
    Clase para manejar un libro completo de Excel con múltiples hojas usando XlsxWriter.
    XlsxWriter está optimizado para velocidad de escritura y bajo uso de memoria,
    especialmente efectivo para grandes volúmenes de datos.
    Características principales:
    - Alto rendimiento en escritura
    - Soporte para múltiples hojas
    - Gestión automática de archivos
    - Validación de nombres de archivo
    """
    def __init__(self, nombre_archivo):
        """
        Inicializa un nuevo libro Excel.
        Args:
            nombre_archivo (str): Nombre del archivo a generar
        """
        # El workbook se creará cuando se escriba el archivo
        self.nombre_archivo = nombre_archivo
        self.workbook = None
        self.hojas_creadas = []  # Almacenar información de hojas creadas
        self.archivo_creado = False

    def Nueva_Hoja(self, nombre_hoja="Hoja1"):
        """
        Crea una nueva hoja dentro del libro Excel.
        Args:
            nombre_hoja (str): Nombre de la nueva hoja
        Returns:
            HojaExcelTurbo: Instancia de la nueva hoja creada
        """
        # Validar nombre de hoja (Excel tiene restricciones)
        nombre_hoja = self._validar_nombre_hoja(nombre_hoja)
        # Almacenar información de la hoja para crear después
        info_hoja = {
            'nombre': nombre_hoja,
            'datos_callback': None
        }
        self.hojas_creadas.append(info_hoja)
        logger.info(f"Hoja '{nombre_hoja}' programada para creación")
        # Retornar un placeholder que será reemplazado durante la escritura
        return HojaExcelPlaceholder(info_hoja)

    def _validar_nombre_hoja(self, nombre_hoja):
        """
        Valida y corrige el nombre de la hoja según las restricciones de Excel.
        Args:
            nombre_hoja (str): Nombre propuesto para la hoja
        Returns:
            str: Nombre validado y corregido
        """
        # Excel no permite ciertos caracteres en nombres de hoja
        caracteres_prohibidos = ['/', '\\', '?', '*', '[', ']', ':', '|']
        nombre_limpio = nombre_hoja
        for caracter in caracteres_prohibidos:
            nombre_limpio = nombre_limpio.replace(caracter, '_')
        
        # Evitar nombres vacíos
        if not nombre_limpio.strip():
            nombre_limpio = 'Hoja'
        
        # Limitar longitud (Excel permite máximo 31 caracteres)
        if len(nombre_limpio) > 31:
            nombre_limpio = nombre_limpio[:31]
            logger.warning(f"Nombre de hoja truncado a: '{nombre_limpio}'")
        
        # Evitar nombres duplicados
        nombres_existentes = set(hoja.get('nombre', '') for hoja in self.hojas_creadas)
        contador = 1
        nombre_original = nombre_limpio
        max_iter = 100  # Previene bucle infinito
        while nombre_limpio in nombres_existentes and contador < max_iter:
            sufijo = f"_{contador}"
            if len(nombre_original) + len(sufijo) > 31:
                nombre_limpio = nombre_original[:31 - len(sufijo)] + sufijo
            else:
                nombre_limpio = nombre_original + sufijo
            contador += 1
        
        if contador >= max_iter:
            logger.error("No se pudo generar un nombre único de hoja después de 100 intentos.")
            nombre_limpio = f"{nombre_original[:28]}_max"
        
        return nombre_limpio

    def Escribe_Libro(self, ruta_salida=None):
        """
        Escribe el libro completo al disco con todas las hojas configuradas.
        Args:
            ruta_salida (str): Directorio donde guardar el archivo.
                              Si es None, usa 'reportes'
        Returns:
            str: Ruta completa del archivo generado
        """
        inicio_escritura = time.time()
        # Determinar directorio de salida
        output_dir = ruta_salida or "reportes"
        if not os.path.exists(output_dir):
            os.makedirs(output_dir)
            logger.info(f"Directorio creado: {output_dir}")
        filepath = os.path.join(output_dir, self.nombre_archivo)
        try:
            # Crear el workbook con XlsxWriter
            self.workbook = xlsxwriter.Workbook(filepath, {
                'constant_memory': True,  # Optimización de memoria para archivos grandes
                'default_date_format': 'dd/mmm/yyyy'
            })
            # Procesar cada hoja programada
            for info_hoja in self.hojas_creadas:
                nombre_hoja = info_hoja['nombre']
                logger.info(f"Creando hoja: '{nombre_hoja}'")
                # Crear worksheet en XlsxWriter
                worksheet = self.workbook.add_worksheet(nombre_hoja)
                # Crear instancia real de HojaExcelTurbo
                hoja_real = HojaExcelTurbo(self.workbook, worksheet, nombre_hoja)
                # Si hay un placeholder, transferir la configuración
                if 'placeholder' in info_hoja and info_hoja['placeholder']:
                    placeholder = info_hoja['placeholder']
                    hoja_real.datos = placeholder.datos
                    hoja_real.columnas_a_mostrar = placeholder.columnas_a_mostrar
                    hoja_real._renombra_encabezados = placeholder._renombra_encabezados
                    hoja_real.formato_columnas = placeholder.formato_columnas
                    hoja_real.cambia_resultado_a = placeholder.cambia_resultado_a
                    hoja_real.alineaciones_horizontales = placeholder.alineaciones_horizontales
                    hoja_real.columnas_calculadas = getattr(placeholder, 'columnas_calculadas', [])
                    hoja_real.sangrias_columnas = getattr(placeholder, 'sangrias_columnas', [])
                    hoja_real.mostrar_encabezados = getattr(placeholder, 'mostrar_encabezados', True)
                    hoja_real.fila_inicial = getattr(placeholder, 'fila_inicial', 1)
                # Exportar datos de la hoja
                hoja_real._exportar_datos()
            # Cerrar y guardar el workbook
            self.workbook.close()
            self.archivo_creado = True
            fin_escritura = time.time()
            tiempo_total = fin_escritura - inicio_escritura
            logger.info(f"Archivo Excel generado exitosamente: {filepath}")
            logger.info(f"Tiempo total de escritura: {tiempo_total:.2f} segundos")
            logger.info(f"Hojas creadas: {len(self.hojas_creadas)}")
            return filepath
        except Exception as e:
            logger.error(f"Error al escribir el archivo Excel: {str(e)}")
            # Limpiar recursos en caso de error
            if self.workbook:
                try:
                    self.workbook.close()
                except:
                    pass
            raise

    def __enter__(self):
        """Soporte para context manager (with statement)."""
        return self

    def __exit__(self, exc_type, exc_val, exc_tb):
        """
        Cierre automático del libro al salir del context manager.
        Args:
            exc_type: Tipo de excepción si ocurrió
            exc_val: Valor de la excepción si ocurrió
            exc_tb: Traceback de la excepción si ocurrió
        """
        # El workbook se cierra automáticamente en Escribe_Libro()
        # No necesitamos hacer nada aquí a menos que haya errores
        if exc_type:
            logger.error(f"Error en el context manager del libro: {exc_val}")

class HojaExcelPlaceholder(HojaBase):
    """
    Clase placeholder que almacena la configuración de una hoja hasta que se cree el workbook real.
    Necesaria porque XlsxWriter requiere que el archivo esté abierto para crear worksheets,
    pero queremos mantener la misma interfaz de uso que la versión original.
    """
    def __init__(self, info_hoja):
        """
        Inicializa el placeholder con referencia a la información de la hoja.
        Args:
            info_hoja (dict): Diccionario con información de la hoja
        """
        super().__init__()
        self.info_hoja = info_hoja
        self.info_hoja['placeholder'] = self

    def Carga_Datos(self, datos):
        """
        Almacena los datos que serán exportados cuando se cree la hoja real.
        Args:
            datos: Datos a exportar
        Returns:
            self: Permite method chaining
        """
        self.datos = datos
        return self

    def __enter__(self):
        """Soporte para context manager."""
        return self

    def __exit__(self, exc_type, exc_val, exc_tb):
        """
        Al salir del context manager, no hace nada porque la exportación
        real ocurre cuando se escribe el libro completo.
        """
        pass

class ExportaExcelTurbo:
    """
    Clase principal para crear libros Excel usando XlsxWriter para máximo rendimiento.
    Esta implementación turbo ofrece:
    - Velocidad de escritura significativamente mejorada vs openpyxl
    - Menor uso de memoria para archivos grandes
    - Mejor manejo de formatos y estilos
    - Compatibilidad total con la interfaz original
    - Optimizaciones específicas para reportes masivos
    - Soporte para reemplazo personalizado de valores
    - Soporte para alineaciones horizontales personalizadas
    - Soporte para sangrías de columnas
    - Configuración opcional para mostrar encabezados
    Ideal para:
    - Reportes con miles o millones de registros
    - Exportaciones frecuentes y automatizadas
    - Sistemas que requieren alta performance
    """
    @staticmethod
    def Nuevo_Libro(nombre_archivo="Excel_Exportado.xlsx", garantiza_extension_correcta=True):
        """
        Crea una nueva instancia de libro Excel turbo.
        Args:
            nombre_archivo (str): Nombre del archivo a generar
            garantiza_extension_correcta (bool): Si es True, asegura que el nombre del archivo
                                    termine con la extensión correcta
        Returns:
            LibroExcelTurbo: Nueva instancia del libro Excel
        """
        # Extension por defecto
        extension = ".xlsx"
        # Garantizar la extensión correcta si la opción está habilitada
        if (garantiza_extension_correcta) and (not nombre_archivo.lower().endswith(extension.lower())):
            # Si no encuentra la extensión correcta se agrega
            nombre_archivo = nombre_archivo + extension
        return LibroExcelTurbo(nombre_archivo)