tablas-python 0.1.2__py3-none-any.whl → 0.1.4__py3-none-any.whl

helpers/table_manager.py

@@ -58,14 +58,58 @@ class TableManager:
         auto_load : bool (por defecto True)
             Carga las tablas automáticamente al instanciar.
         """
+        self.archivo_abierto = archivo_abierto
+        self.preferir_xlwings = preferir_xlwings
+        self.tables: List[Union[RawTableInfo, RawExcelTableInfo, RawSQLiteTableInfo]] = []
+        self.is_open_in_memory = False
+
+        # 1. Si es Excel y archivo_abierto=True o None, buscar primero en libros abiertos en pantalla (xlwings)
+        if self.preferir_xlwings and archivo_abierto is not False:
+            try:
+                import xlwings as xw
+                if not file_path or file_path.lower() in ["", "activo", "active", "libro_activo"]:
+                    matched_book = xw.books.active if len(xw.books) > 0 else None
+                else:
+                    clean_target = os.path.basename(file_path).strip().lower()
+                    name_no_ext = os.path.splitext(clean_target)[0]
+                    matched_book = None
+                    for b in xw.books:
+                        b_name = b.name.lower()
+                        b_name_no_ext = os.path.splitext(b_name)[0]
+                        b_fullname = getattr(b, 'fullname', '').lower()
+                        if (clean_target == b_name or
+                            name_no_ext == b_name_no_ext or
+                            (b_fullname and clean_target == os.path.basename(b_fullname).lower())):
+                            matched_book = b
+                            break
+
+                if matched_book:
+                    self.file_path = getattr(matched_book, 'fullname', matched_book.name)
+                    self.ext = os.path.splitext(matched_book.name)[1].lower() or ".xlsx"
+                    self.is_open_in_memory = True
+                    if auto_load:
+                        self.cargar_tablas()
+                    return
+            except Exception:
+                pass
+
+        if archivo_abierto is True:
+            try:
+                import xlwings as xw
+                abiertos = [b.name for b in xw.books] if len(xw.books) > 0 else []
+            except Exception:
+                abiertos = []
+            raise FileNotFoundError(
+                f"No se encontró ningún libro abierto en Excel con el nombre '{file_path}'. "
+                f"Libros actualmente abiertos en Excel: {abiertos if abiertos else 'Ninguno (Excel no tiene libros abiertos)'}"
+            )
+
+        # 2. Si no es un libro abierto en memoria, resolver la ruta física en disco
         self.file_path = resolve_file_path(file_path)
         if not os.path.exists(self.file_path):
             raise FileNotFoundError(f"No se encontró el archivo: {self.file_path}")
         
         self.ext = os.path.splitext(self.file_path)[1].lower()
-        self.archivo_abierto = archivo_abierto
-        self.preferir_xlwings = preferir_xlwings
-        self.tables: List[Union[RawTableInfo, RawExcelTableInfo, RawSQLiteTableInfo]] = []
         
         valid_extensions = ['.pdf', '.xlsx', '.xls', '.xlsm', '.csv', '.db', '.sqlite', '.sqlite3', '.db3']
         if self.ext not in valid_extensions:

tablas_python/__init__.py

@@ -32,7 +32,7 @@ from utils.data_helpers import (
     conciliar_tablas,
 )
 
-__version__ = "0.1.2"
+__version__ = "0.1.4"
 
 __all__ = [
     "TableManager",

{tablas_python-0.1.2.dist-info → tablas_python-0.1.4.dist-info}/METADATA

@@ -1,375 +1,375 @@
-Metadata-Version: 2.4
-Name: tablas-python
-Version: 0.1.2
-Summary: Suite modular para extraer, transformar, conciliar y exportar tablas desde PDF, Excel y SQLite a pandas.
-Author: Reciba
-License: MIT
-Project-URL: Homepage, https://github.com/Reciba/tablas_python
-Project-URL: Repository, https://github.com/Reciba/tablas_python.git
-Project-URL: Issues, https://github.com/Reciba/tablas_python/issues
-Keywords: tables,pdf,excel,xlwings,pdfplumber,sqlite,pandas,data-extraction,vlookup,conciliation
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.8
-Classifier: Programming Language :: Python :: 3.9
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Operating System :: OS Independent
-Classifier: Topic :: Office/Business :: Financial :: Spreadsheet
-Classifier: Topic :: Scientific/Engineering :: Information Analysis
-Requires-Python: >=3.8
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: pandas>=1.5.0
-Requires-Dist: pdfplumber>=0.9.0
-Requires-Dist: openpyxl>=3.1.0
-Requires-Dist: xlwings>=0.30.0
-Requires-Dist: rich>=13.0.0
-Requires-Dist: numpy>=1.20.0
-Provides-Extra: dev
-Requires-Dist: build; extra == "dev"
-Requires-Dist: twine; extra == "dev"
-Requires-Dist: pytest; extra == "dev"
-Requires-Dist: reportlab>=3.6.0; extra == "dev"
-Dynamic: license-file
-
-# 📊 Tablas Python - Suite Integral de Procesamiento de Tablas
-
-Sistema modular en Python diseñado para **reconocer, extraer, transformar, conciliar, validar y exportar tablas** provenientes de múltiples fuentes:
-- 📄 **Documentos PDF** (usando `pdfplumber` con descarte de filas de basura iniciales)
-- 📊 **Archivos Excel / CSV** (usando `xlwings`, compatible con libros **abiertos** o **cerrados**, tablas oficiales `ListObjects`, celdas de inicio y rangos)
-- 🗄️ **Bases de Datos SQLite** (archivos `.db`, `.sqlite`, `.sqlite3`)
-
-Además, incluye un conjunto completo de herramientas para **cálculos rápidos (IVA, márgenes, % participación), formateo de monedas/porcentajes, cruces tipo `BUSCARV`, conciliación automática de tablas, escritura en vivo en Excel, unión masiva de carpetas y reportes de calidad de datos**.
-
----
-
-## 📁 Arquitectura del Proyecto
-
-El código está estructurado de forma modular y desacoplada por capas:
-
-```text
-tablas_python/
-│
-├── main.py                     # Script principal con todas las utilidades importadas y listas para usar
-├── requirements.txt            # Dependencias del proyecto
-├── README.md                   # Documentación técnica completa
-├── .gitignore                  # Exclusiones de Git
-│
-├── utils/                      # Capa de bajo nivel (lógica desacoplada y reutilizable)
-│   ├── __init__.py             # Exportaciones unificadas del paquete utils
-│   ├── file_utils.py           # Resolución de rutas (relativas/absolutas) y nombres seguros
-│   ├── pdf_extractor.py        # Extracción multipágina en PDF con pdfplumber
-│   ├── excel_extractor.py      # Extracción en Excel con xlwings (tablas oficiales, celdas y rangos)
-│   ├── excel_writer.py         # Escritura en Excel en vivo o en segundo plano con xlwings
-│   ├── sqlite_extractor.py     # Extracción y consultas SQL en SQLite
-│   ├── table_cleaner.py        # Limpieza, descarte de basura superior, tipos y normalización
-│   ├── batch_processor.py      # Unión masiva de carpetas con múltiples archivos a 1 DataFrame
-│   ├── validator.py            # Validación de esquemas, diagnóstico de calidad y duplicados
-│   ├── exporter.py             # Exportación individual y por lotes a CSV/Excel (utf-8-sig / sep=';')
-│   └── data_helpers.py         # Cálculos: BUSCARV, conciliación, IVA, %, totales, celdas y formato
-│
-├── helpers/                    # Capa de fachada y presentación
-│   ├── __init__.py             # Exportaciones unificadas del paquete helpers
-│   ├── table_manager.py        # TableManager unificado, obtener_tabla y exportar_archivo_a_csv
-│   └── display_helper.py       # Visualizador enriquecido en consola con Rich
-│
-├── samples/                    # Archivos y generador de prueba
-│   ├── generate_samples.py     # Script generador de datos de prueba
-│   ├── ejemplo_facturas.pdf    # PDF de muestra con tablas y encabezados desplazados
-│   ├── ejemplo_inventario.xlsx # Excel con tablas oficiales, celdas específicas y múltiples hojas
-│   └── ejemplo_empresa.db      # Base SQLite de muestra con tablas 'clientes', 'ventas' y vistas
-│
-└── exports/                    # Carpeta por defecto para salidas CSV y Excel
-```
-
----
-
-## 🚀 Instalación
-
-Clona el repositorio e instala las dependencias:
-
-```bash
-git clone https://github.com/Reciba/tablas_python.git
-cd tablas_python
-pip install -r requirements.txt
-```
-
----
-
-## 💡 Guía de Uso Completa
-
-### 1. Extracción desde PDF (`pdfplumber`)
-
-Resuelve el problema donde las filas 1, 2 o 3 contienen títulos, membretes o metadatos irrelevantes y los encabezados reales comienzan más abajo (por ejemplo en la **fila 4**):
-
-```python
-from helpers.table_manager import obtener_tabla, TableManager
-
-# Modo 1: En una sola línea indicando tabla 3 y fila 4 como encabezado:
-df = obtener_tabla("samples/ejemplo_facturas.pdf", tabla=3, fila_encabezado=4)
-print(df.head())
-
-# Modo 2: Con inspección previa usando TableManager:
-manager = TableManager("samples/ejemplo_facturas.pdf")
-manager.resumen()             # Muestra cuántas tablas hay y en qué páginas
-manager.ver_crudo(tabla=1)    # Muestra las primeras filas numeradas (Fila 1, Fila 2, Fila 3...)
-df_limpio = manager.get_df(tabla=1, fila_encabezado=4, skip_footer=1)
-```
-
----
-
-### 2. Extracción desde Excel con `xlwings`
-
-Soporta conectarse a archivos **abiertos en pantalla** (sin conflictos de bloqueo) o **cerrados en disco** (en segundo plano):
-
-```python
-from helpers.table_manager import obtener_tabla
-
-# A) Por Nombre Oficial de Tabla de Excel (ListObject / Tabla con Formato):
-df_stock = obtener_tabla("samples/ejemplo_inventario.xlsx", tabla="TablaStock")
-
-# B) Por Celda de Inicio donde parte la tabla (ej. celda C4 en la hoja 'Despacho'):
-df_despacho = obtener_tabla(
-    "samples/ejemplo_inventario.xlsx",
-    celda_inicio="C4",
-    hoja="Despacho"
-)
-
-# C) Por Rango Exacto:
-df_rango = obtener_tabla(
-    "samples/ejemplo_inventario.xlsx",
-    rango="C4:F8",
-    hoja="Despacho"
-)
-
-# D) Control de archivo abierto/cerrado:
-# archivo_abierto=None (autodetecta), True (fuerza conexión al Excel abierto), False (abre oculto)
-df = obtener_tabla("reporte.xlsx", tabla=1, fila_encabezado=4, archivo_abierto=True)
-```
-
----
-
-### 3. Extracción y Consultas en SQLite (`.db`, `.sqlite`)
-
-```python
-from helpers.table_manager import TableManager, obtener_tabla
-
-# A) Obtener tabla completa por nombre:
-df_clientes = obtener_tabla("samples/ejemplo_empresa.db", tabla="clientes")
-
-# B) Ejecutar consultas SQL personalizadas directamente a DataFrame:
-db = TableManager("samples/ejemplo_empresa.db")
-db.resumen() # Lista tablas y vistas
-
-df_ventas = db.query("""
-    SELECT c.nombre AS cliente, c.ciudad, v.monto_neto, v.fecha
-    FROM clientes c
-    JOIN ventas v ON c.id_cliente = v.id_cliente
-    WHERE v.estado = 'Pagado'
-""")
-```
-
----
-
-### 4. Búsqueda de Celdas por Nombre de Fila y Nombre de Columna
-
-Puedes acceder a cualquier celda específica mediante nombres sin depender de posiciones numéricas:
-
-```python
-from utils.data_helpers import obtener_celda, modificar_celda
-
-# A) Usando la función helper obtener_celda:
-precio = obtener_celda(df, fila="PROD-101", columna="Precio Unitario")
-print("Precio PROD-101:", precio)
-
-# B) Usando set_index nativo de pandas con .at o .loc:
-df_idx = df.set_index("Codigo")
-precio = df_idx.at["PROD-101", "Precio Unitario"]
-cantidad = df_idx.at["PROD-101", "Cantidad"]
-total = float(precio) * float(cantidad)
-
-# C) Modificar una celda por su nombre:
-df_actualizado = modificar_celda(df, fila="PROD-101", columna="Precio Unitario", nuevo_valor=49.90)
-```
-
----
-
-### 5. Cruces de Datos con `buscar_v` (BUSCARV / VLOOKUP en 1 línea)
-
-Cruza dos DataFrames asociando datos a partir de una clave en común:
-
-```python
-from utils.data_helpers import buscar_v
-
-# Trae el nombre del cliente desde df_clientes a df_ventas usando 'id_cliente':
-df_ventas["Nombre_Cliente"] = buscar_v(
-    df_origen=df_ventas,
-    df_destino=df_clientes,
-    clave="id_cliente",
-    columna_a_traer="nombre"
-)
-```
-
----
-
-### 6. Conciliación y Auditoría entre 2 Tablas (`conciliar_tablas`)
-
-Compara dos tablas (por ejemplo: extracto bancario vs. registro contable, o inventario físico vs. teórico):
-
-```python
-from utils.data_helpers import conciliar_tablas
-
-resultado = conciliar_tablas(df_sistema, df_banco, clave="id_transaccion")
-
-print("Coincidentes:", resultado["coincidentes"]) # Idénticas en ambas tablas
-print("Diferencias:",  resultado["diferencias"])   # Existen en ambas pero con valores distintos
-print("Solo en A:",    resultado["solo_en_A"])     # Registros que faltan en B
-print("Solo en B:",    resultado["solo_en_B"])     # Registros que faltan en A
-```
-
----
-
-### 7. Escritura en Vivo en Excel con `escribir_en_excel`
-
-Pega un DataFrame en una celda exacta de una plantilla Excel que tengas **abierta en pantalla** o **cerrada en disco**, conservando fórmulas y formatos:
-
-```python
-from utils.excel_writer import escribir_en_excel
-
-escribir_en_excel(
-    df=df_reporte,
-    archivo_excel="plantilla_ventas.xlsx",
-    hoja="Resumen",
-    celda_inicio="B5",
-    archivo_abierto=None # Detecta automáticamente si la ventana de Excel está abierta
-)
-```
-
----
-
-### 8. Consolidación Masiva de Carpetas (`unir_archivos_carpeta`)
-
-Lee y une decenas de archivos periódicos (facturas PDF, Excels mensuales, etc.) en un solo DataFrame maestro:
-
-```python
-from utils.batch_processor import unir_archivos_carpeta
-
-df_consolidado = unir_archivos_carpeta(
-    carpeta="facturas_2026/",
-    extension="pdf",
-    tabla=1,
-    fila_encabezado=4
-)
-# Agrega automáticamente la columna 'Archivo_Origen' con el nombre de cada archivo
-```
-
----
-
-### 9. Calidad y Validación de Datos (`validar_dataframe` y `reporte_calidad`)
-
-```python
-from utils.validator import validar_dataframe, reporte_calidad, detectar_duplicados
-
-# 1. Diagnóstico completo de nulos, completitud y tipos por columna:
-print(reporte_calidad(df))
-
-# 2. Validación de reglas de negocio antes de procesar:
-check = validar_dataframe(
-    df,
-    columnas_requeridas=["id_venta", "monto_neto", "fecha"],
-    no_nulos=["id_venta", "monto_neto"],
-    tipos_esperados={"monto_neto": "numeric"}
-)
-
-if not check["es_valido"]:
-    print("❌ Errores encontrados:", check["errores"])
-
-# 3. Detección de registros duplicados:
-duplicados = detectar_duplicados(df, columnas_clave=["id_venta"])
-```
-
----
-
-### 10. Cálculos Rápidos y Formato para Reportes
-
-```python
-from utils.data_helpers import (
-    aplicar_impuesto,
-    calcular_participacion,
-    calcular_variacion,
-    agregar_fila_totales,
-    formatear_dataframe,
-    formato_moneda,
-    formato_porcentaje,
-    limpiar_numero
-)
-
-# A) Calcular IVA (19%) y Total Bruto:
-df = aplicar_impuesto(df, col_neto="monto_neto", tasa=0.19)
-
-# B) Calcular % de participación sobre el total:
-df = calcular_participacion(df, columna_valor="Total Bruto")
-
-# C) Agregar fila final con totales:
-df = agregar_fila_totales(df, columnas_sumar=["monto_neto", "IVA (19%)", "Total Bruto"])
-
-# D) Formatear números a moneda ($) y porcentaje (%):
-df_formateado = formatear_dataframe(df, {
-    "monto_neto": "moneda",
-    "IVA (19%)": "moneda",
-    "Total Bruto": "moneda",
-    "% Participación": "porcentaje"
-})
-```
-
----
-
-### 11. Exportación Fácil a CSV y Excel
-
-```python
-from utils.exporter import guardar_csv, guardar_excel
-from helpers.table_manager import exportar_archivo_a_csv
-
-# A) Guardar DataFrame individual a CSV (optimizado con ';' y utf-8-sig para Excel):
-guardar_csv(df, "exports/mi_tabla.csv")
-
-# B) Guardar a Excel:
-guardar_excel(df, "exports/mi_tabla.xlsx")
-
-# C) Exportar TODAS las tablas encontradas en un archivo a CSVs independientes:
-archivos = exportar_archivo_a_csv("samples/ejemplo_facturas.pdf", carpeta_salida="exports/pdf_tablas", fila_encabezado=4)
-```
-
----
-
-## 🖥️ Ejecución por Consola
-
-```bash
-# 1. Ejecutar script principal de demostración:
-python main.py
-
-# 2. Modo interactivo en terminal (asistente guiado):
-python main.py -i
-
-# 3. Exportar todas las tablas de cualquier archivo por línea de comandos:
-python main.py -f "samples/ejemplo_facturas.pdf" -r 4 --export-all "exports/salida_csv"
-```
-
----
-
-## 📦 Tecnologías Utilizadas
-
-- **[pandas](https://pandas.pydata.org/)**: Manipulación y estructuras tabulares en DataFrames.
-- **[xlwings](https://docs.xlwings.org/)**: Integración avanzada con Microsoft Excel (archivos abiertos/cerrados, rangos y tablas).
-- **[pdfplumber](https://github.com/jsvine/pdfplumber)**: Extracción precisa de texto y tablas multipágina en PDFs.
-- **[openpyxl](https://openpyxl.readthedocs.io/)**: Soporte nativo y fallback para archivos `.xlsx`.
-- **[reportlab](https://www.reportlab.com/)**: Generación de PDFs de prueba.
-- **[rich](https://github.com/Textualize/rich)**: Visualización y formato de tablas en consola.
-
----
-
-## 📄 Licencia
-
-Distribuido bajo licencia MIT. Consulta `LICENSE` para más información.
+Metadata-Version: 2.4
+Name: tablas-python
+Version: 0.1.4
+Summary: Suite modular para extraer, transformar, conciliar y exportar tablas desde PDF, Excel y SQLite a pandas.
+Author: Reciba
+License: MIT
+Project-URL: Homepage, https://github.com/Reciba/tablas_python
+Project-URL: Repository, https://github.com/Reciba/tablas_python.git
+Project-URL: Issues, https://github.com/Reciba/tablas_python/issues
+Keywords: tables,pdf,excel,xlwings,pdfplumber,sqlite,pandas,data-extraction,vlookup,conciliation
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Office/Business :: Financial :: Spreadsheet
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pandas>=1.5.0
+Requires-Dist: pdfplumber>=0.9.0
+Requires-Dist: openpyxl>=3.1.0
+Requires-Dist: xlwings>=0.30.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: numpy>=1.20.0
+Provides-Extra: dev
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: reportlab>=3.6.0; extra == "dev"
+Dynamic: license-file
+
+# 📊 Tablas Python - Suite Integral de Procesamiento de Tablas
+
+Sistema modular en Python diseñado para **reconocer, extraer, transformar, conciliar, validar y exportar tablas** provenientes de múltiples fuentes:
+- 📄 **Documentos PDF** (usando `pdfplumber` con descarte de filas de basura iniciales)
+- 📊 **Archivos Excel / CSV** (usando `xlwings`, compatible con libros **abiertos** o **cerrados**, tablas oficiales `ListObjects`, celdas de inicio y rangos)
+- 🗄️ **Bases de Datos SQLite** (archivos `.db`, `.sqlite`, `.sqlite3`)
+
+Además, incluye un conjunto completo de herramientas para **cálculos rápidos (IVA, márgenes, % participación), formateo de monedas/porcentajes, cruces tipo `BUSCARV`, conciliación automática de tablas, escritura en vivo en Excel, unión masiva de carpetas y reportes de calidad de datos**.
+
+---
+
+## 📁 Arquitectura del Proyecto
+
+El código está estructurado de forma modular y desacoplada por capas:
+
+```text
+tablas_python/
+│
+├── main.py                     # Script principal con todas las utilidades importadas y listas para usar
+├── requirements.txt            # Dependencias del proyecto
+├── README.md                   # Documentación técnica completa
+├── .gitignore                  # Exclusiones de Git
+│
+├── utils/                      # Capa de bajo nivel (lógica desacoplada y reutilizable)
+│   ├── __init__.py             # Exportaciones unificadas del paquete utils
+│   ├── file_utils.py           # Resolución de rutas (relativas/absolutas) y nombres seguros
+│   ├── pdf_extractor.py        # Extracción multipágina en PDF con pdfplumber
+│   ├── excel_extractor.py      # Extracción en Excel con xlwings (tablas oficiales, celdas y rangos)
+│   ├── excel_writer.py         # Escritura en Excel en vivo o en segundo plano con xlwings
+│   ├── sqlite_extractor.py     # Extracción y consultas SQL en SQLite
+│   ├── table_cleaner.py        # Limpieza, descarte de basura superior, tipos y normalización
+│   ├── batch_processor.py      # Unión masiva de carpetas con múltiples archivos a 1 DataFrame
+│   ├── validator.py            # Validación de esquemas, diagnóstico de calidad y duplicados
+│   ├── exporter.py             # Exportación individual y por lotes a CSV/Excel (utf-8-sig / sep=';')
+│   └── data_helpers.py         # Cálculos: BUSCARV, conciliación, IVA, %, totales, celdas y formato
+│
+├── helpers/                    # Capa de fachada y presentación
+│   ├── __init__.py             # Exportaciones unificadas del paquete helpers
+│   ├── table_manager.py        # TableManager unificado, obtener_tabla y exportar_archivo_a_csv
+│   └── display_helper.py       # Visualizador enriquecido en consola con Rich
+│
+├── samples/                    # Archivos y generador de prueba
+│   ├── generate_samples.py     # Script generador de datos de prueba
+│   ├── ejemplo_facturas.pdf    # PDF de muestra con tablas y encabezados desplazados
+│   ├── ejemplo_inventario.xlsx # Excel con tablas oficiales, celdas específicas y múltiples hojas
+│   └── ejemplo_empresa.db      # Base SQLite de muestra con tablas 'clientes', 'ventas' y vistas
+│
+└── exports/                    # Carpeta por defecto para salidas CSV y Excel
+```
+
+---
+
+## 🚀 Instalación
+
+Clona el repositorio e instala las dependencias:
+
+```bash
+git clone https://github.com/Reciba/tablas_python.git
+cd tablas_python
+pip install -r requirements.txt
+```
+
+---
+
+## 💡 Guía de Uso Completa
+
+### 1. Extracción desde PDF (`pdfplumber`)
+
+Resuelve el problema donde las filas 1, 2 o 3 contienen títulos, membretes o metadatos irrelevantes y los encabezados reales comienzan más abajo (por ejemplo en la **fila 4**):
+
+```python
+from helpers.table_manager import obtener_tabla, TableManager
+
+# Modo 1: En una sola línea indicando tabla 3 y fila 4 como encabezado:
+df = obtener_tabla("samples/ejemplo_facturas.pdf", tabla=3, fila_encabezado=4)
+print(df.head())
+
+# Modo 2: Con inspección previa usando TableManager:
+manager = TableManager("samples/ejemplo_facturas.pdf")
+manager.resumen()             # Muestra cuántas tablas hay y en qué páginas
+manager.ver_crudo(tabla=1)    # Muestra las primeras filas numeradas (Fila 1, Fila 2, Fila 3...)
+df_limpio = manager.get_df(tabla=1, fila_encabezado=4, skip_footer=1)
+```
+
+---
+
+### 2. Extracción desde Excel con `xlwings`
+
+Soporta conectarse a archivos **abiertos en pantalla** (sin conflictos de bloqueo) o **cerrados en disco** (en segundo plano):
+
+```python
+from helpers.table_manager import obtener_tabla
+
+# A) Por Nombre Oficial de Tabla de Excel (ListObject / Tabla con Formato):
+df_stock = obtener_tabla("samples/ejemplo_inventario.xlsx", tabla="TablaStock")
+
+# B) Por Celda de Inicio donde parte la tabla (ej. celda C4 en la hoja 'Despacho'):
+df_despacho = obtener_tabla(
+    "samples/ejemplo_inventario.xlsx",
+    celda_inicio="C4",
+    hoja="Despacho"
+)
+
+# C) Por Rango Exacto:
+df_rango = obtener_tabla(
+    "samples/ejemplo_inventario.xlsx",
+    rango="C4:F8",
+    hoja="Despacho"
+)
+
+# D) Control de archivo abierto/cerrado:
+# archivo_abierto=None (autodetecta), True (fuerza conexión al Excel abierto), False (abre oculto)
+df = obtener_tabla("reporte.xlsx", tabla=1, fila_encabezado=4, archivo_abierto=True)
+```
+
+---
+
+### 3. Extracción y Consultas en SQLite (`.db`, `.sqlite`)
+
+```python
+from helpers.table_manager import TableManager, obtener_tabla
+
+# A) Obtener tabla completa por nombre:
+df_clientes = obtener_tabla("samples/ejemplo_empresa.db", tabla="clientes")
+
+# B) Ejecutar consultas SQL personalizadas directamente a DataFrame:
+db = TableManager("samples/ejemplo_empresa.db")
+db.resumen() # Lista tablas y vistas
+
+df_ventas = db.query("""
+    SELECT c.nombre AS cliente, c.ciudad, v.monto_neto, v.fecha
+    FROM clientes c
+    JOIN ventas v ON c.id_cliente = v.id_cliente
+    WHERE v.estado = 'Pagado'
+""")
+```
+
+---
+
+### 4. Búsqueda de Celdas por Nombre de Fila y Nombre de Columna
+
+Puedes acceder a cualquier celda específica mediante nombres sin depender de posiciones numéricas:
+
+```python
+from utils.data_helpers import obtener_celda, modificar_celda
+
+# A) Usando la función helper obtener_celda:
+precio = obtener_celda(df, fila="PROD-101", columna="Precio Unitario")
+print("Precio PROD-101:", precio)
+
+# B) Usando set_index nativo de pandas con .at o .loc:
+df_idx = df.set_index("Codigo")
+precio = df_idx.at["PROD-101", "Precio Unitario"]
+cantidad = df_idx.at["PROD-101", "Cantidad"]
+total = float(precio) * float(cantidad)
+
+# C) Modificar una celda por su nombre:
+df_actualizado = modificar_celda(df, fila="PROD-101", columna="Precio Unitario", nuevo_valor=49.90)
+```
+
+---
+
+### 5. Cruces de Datos con `buscar_v` (BUSCARV / VLOOKUP en 1 línea)
+
+Cruza dos DataFrames asociando datos a partir de una clave en común:
+
+```python
+from utils.data_helpers import buscar_v
+
+# Trae el nombre del cliente desde df_clientes a df_ventas usando 'id_cliente':
+df_ventas["Nombre_Cliente"] = buscar_v(
+    df_origen=df_ventas,
+    df_destino=df_clientes,
+    clave="id_cliente",
+    columna_a_traer="nombre"
+)
+```
+
+---
+
+### 6. Conciliación y Auditoría entre 2 Tablas (`conciliar_tablas`)
+
+Compara dos tablas (por ejemplo: extracto bancario vs. registro contable, o inventario físico vs. teórico):
+
+```python
+from utils.data_helpers import conciliar_tablas
+
+resultado = conciliar_tablas(df_sistema, df_banco, clave="id_transaccion")
+
+print("Coincidentes:", resultado["coincidentes"]) # Idénticas en ambas tablas
+print("Diferencias:",  resultado["diferencias"])   # Existen en ambas pero con valores distintos
+print("Solo en A:",    resultado["solo_en_A"])     # Registros que faltan en B
+print("Solo en B:",    resultado["solo_en_B"])     # Registros que faltan en A
+```
+
+---
+
+### 7. Escritura en Vivo en Excel con `escribir_en_excel`
+
+Pega un DataFrame en una celda exacta de una plantilla Excel que tengas **abierta en pantalla** o **cerrada en disco**, conservando fórmulas y formatos:
+
+```python
+from utils.excel_writer import escribir_en_excel
+
+escribir_en_excel(
+    df=df_reporte,
+    archivo_excel="plantilla_ventas.xlsx",
+    hoja="Resumen",
+    celda_inicio="B5",
+    archivo_abierto=None # Detecta automáticamente si la ventana de Excel está abierta
+)
+```
+
+---
+
+### 8. Consolidación Masiva de Carpetas (`unir_archivos_carpeta`)
+
+Lee y une decenas de archivos periódicos (facturas PDF, Excels mensuales, etc.) en un solo DataFrame maestro:
+
+```python
+from utils.batch_processor import unir_archivos_carpeta
+
+df_consolidado = unir_archivos_carpeta(
+    carpeta="facturas_2026/",
+    extension="pdf",
+    tabla=1,
+    fila_encabezado=4
+)
+# Agrega automáticamente la columna 'Archivo_Origen' con el nombre de cada archivo
+```
+
+---
+
+### 9. Calidad y Validación de Datos (`validar_dataframe` y `reporte_calidad`)
+
+```python
+from utils.validator import validar_dataframe, reporte_calidad, detectar_duplicados
+
+# 1. Diagnóstico completo de nulos, completitud y tipos por columna:
+print(reporte_calidad(df))
+
+# 2. Validación de reglas de negocio antes de procesar:
+check = validar_dataframe(
+    df,
+    columnas_requeridas=["id_venta", "monto_neto", "fecha"],
+    no_nulos=["id_venta", "monto_neto"],
+    tipos_esperados={"monto_neto": "numeric"}
+)
+
+if not check["es_valido"]:
+    print("❌ Errores encontrados:", check["errores"])
+
+# 3. Detección de registros duplicados:
+duplicados = detectar_duplicados(df, columnas_clave=["id_venta"])
+```
+
+---
+
+### 10. Cálculos Rápidos y Formato para Reportes
+
+```python
+from utils.data_helpers import (
+    aplicar_impuesto,
+    calcular_participacion,
+    calcular_variacion,
+    agregar_fila_totales,
+    formatear_dataframe,
+    formato_moneda,
+    formato_porcentaje,
+    limpiar_numero
+)
+
+# A) Calcular IVA (19%) y Total Bruto:
+df = aplicar_impuesto(df, col_neto="monto_neto", tasa=0.19)
+
+# B) Calcular % de participación sobre el total:
+df = calcular_participacion(df, columna_valor="Total Bruto")
+
+# C) Agregar fila final con totales:
+df = agregar_fila_totales(df, columnas_sumar=["monto_neto", "IVA (19%)", "Total Bruto"])
+
+# D) Formatear números a moneda ($) y porcentaje (%):
+df_formateado = formatear_dataframe(df, {
+    "monto_neto": "moneda",
+    "IVA (19%)": "moneda",
+    "Total Bruto": "moneda",
+    "% Participación": "porcentaje"
+})
+```
+
+---
+
+### 11. Exportación Fácil a CSV y Excel
+
+```python
+from utils.exporter import guardar_csv, guardar_excel
+from helpers.table_manager import exportar_archivo_a_csv
+
+# A) Guardar DataFrame individual a CSV (optimizado con ';' y utf-8-sig para Excel):
+guardar_csv(df, "exports/mi_tabla.csv")
+
+# B) Guardar a Excel:
+guardar_excel(df, "exports/mi_tabla.xlsx")
+
+# C) Exportar TODAS las tablas encontradas en un archivo a CSVs independientes:
+archivos = exportar_archivo_a_csv("samples/ejemplo_facturas.pdf", carpeta_salida="exports/pdf_tablas", fila_encabezado=4)
+```
+
+---
+
+## 🖥️ Ejecución por Consola
+
+```bash
+# 1. Ejecutar script principal de demostración:
+python main.py
+
+# 2. Modo interactivo en terminal (asistente guiado):
+python main.py -i
+
+# 3. Exportar todas las tablas de cualquier archivo por línea de comandos:
+python main.py -f "samples/ejemplo_facturas.pdf" -r 4 --export-all "exports/salida_csv"
+```
+
+---
+
+## 📦 Tecnologías Utilizadas
+
+- **[pandas](https://pandas.pydata.org/)**: Manipulación y estructuras tabulares en DataFrames.
+- **[xlwings](https://docs.xlwings.org/)**: Integración avanzada con Microsoft Excel (archivos abiertos/cerrados, rangos y tablas).
+- **[pdfplumber](https://github.com/jsvine/pdfplumber)**: Extracción precisa de texto y tablas multipágina en PDFs.
+- **[openpyxl](https://openpyxl.readthedocs.io/)**: Soporte nativo y fallback para archivos `.xlsx`.
+- **[reportlab](https://www.reportlab.com/)**: Generación de PDFs de prueba.
+- **[rich](https://github.com/Textualize/rich)**: Visualización y formato de tablas en consola.
+
+---
+
+## 📄 Licencia
+
+Distribuido bajo licencia MIT. Consulta `LICENSE` para más información.

{tablas_python-0.1.2.dist-info → tablas_python-0.1.4.dist-info}/RECORD

@@ -1,22 +1,22 @@
 helpers/__init__.py,sha256=hopndlywciR50FKi6W6Lo_cAOP_YyPsQV3xj8hfkH_Y,899
 helpers/display_helper.py,sha256=i0--Txkjc9__IIKwdkmpx98vzwM_Sekr0RzxvVGEPYA,7749
-helpers/table_manager.py,sha256=86MgHe-RtmZZYjkW_7lOQSy1cSGOBvleClEx_FhMg8g,16865
-tablas_python/__init__.py,sha256=QeyjiNr49IR0cgw_2OlW2mGzmsQqfqzzIoYfKyOonjM,1771
+helpers/table_manager.py,sha256=85OZqMdDqgBBJaln2ehb3-t7RWS1Gowo6aud_zqVHAo,19063
+tablas_python/__init__.py,sha256=xVyYUKPzia_CaMiVFM_WxtIBx-8Y06ltIAWFD0U-cVY,1771
 tablas_python/cli.py,sha256=3BModRFfT8WFkbCSxM9cF_oBK87FetPMGm5F0GTZGNo,1957
-tablas_python-0.1.2.dist-info/licenses/LICENSE,sha256=DQi0EoD04d2_-pnEKrC4WmcmgR6O0WQcJdvma9ILoFQ,1063
+tablas_python-0.1.4.dist-info/licenses/LICENSE,sha256=DQi0EoD04d2_-pnEKrC4WmcmgR6O0WQcJdvma9ILoFQ,1063
 utils/__init__.py,sha256=duEZSrdPZggUMdpJqJsNMQ5aLRaFcONBvhsdJuhCToo,2004
 utils/batch_processor.py,sha256=rE59qkb2sp5J0E5NU77U-CF82Aa-ukrjN2druwgS2Uk,4162
-utils/data_helpers.py,sha256=oJx5NPTpCNTHVvSCpqVeTnWGJsflYKl5v6lLUov08Hs,21758
-utils/excel_extractor.py,sha256=FqDqrBk-ls66-fk4R1bIblp0K532cIsC2PXgdcRX6a0,16191
-utils/excel_writer.py,sha256=MKbpAtuzxuD6wzHO6HRq7qxRKI5CpAJ-d8hN_GzSKns,6671
+utils/data_helpers.py,sha256=U6RTiJd0NpqYtk8kQa37jaJBMCay0CUnduREjaoPLM0,23526
+utils/excel_extractor.py,sha256=0WUhkV5eu9uUusU8zSHQB1ujFG7eQVqI-go4zqxmPFU,18364
+utils/excel_writer.py,sha256=zH_Mtu3Cr_ND_wSHKFyvzH3j16gjVoANpM3dVFXKpr0,6991
 utils/exporter.py,sha256=Oo9Y6dXTg_7t6n824xoxv8d9yuhdHZNWfwLLXvSvtMw,4661
 utils/file_utils.py,sha256=Et3fEaRn70xxpIj5oz84N90ocACK2KkCUr1fO3h6Lgo,2302
 utils/pdf_extractor.py,sha256=3JRMqnEfhBVaUOeYfiNH1rReC4EoSbzDwk919x6647w,4768
 utils/sqlite_extractor.py,sha256=mvKlKY-nsd5cV73nn3xFoqg5dgagPJceRDJfPLG0cbs,5033
 utils/table_cleaner.py,sha256=ncyiunqpVdKParFcRKwQbCqyKZgpyKRN0aUM0Oug9wU,10465
 utils/validator.py,sha256=0UywK_D510ZQCcSkhFRKhEuw48788NM_RFVC-bIFZkE,5837
-tablas_python-0.1.2.dist-info/METADATA,sha256=1wrPGbeRuRclphZTIYvP_cl8zTwYs7Y5jPSUpc9rpH4,13986
-tablas_python-0.1.2.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
-tablas_python-0.1.2.dist-info/entry_points.txt,sha256=l29nooItcUpsFzN5LmxM1b-j0qih61vJB9tX8KUwlMg,89
-tablas_python-0.1.2.dist-info/top_level.txt,sha256=Foud-Tbf5pviUJmp7wc3v24IjIyypkvbcZt7HkrWvss,28
-tablas_python-0.1.2.dist-info/RECORD,,
+tablas_python-0.1.4.dist-info/METADATA,sha256=jpBHw3DHlXyFY2qoyOofl65SS0PTXuvRATwthrL0qZI,13611
+tablas_python-0.1.4.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+tablas_python-0.1.4.dist-info/entry_points.txt,sha256=l29nooItcUpsFzN5LmxM1b-j0qih61vJB9tX8KUwlMg,89
+tablas_python-0.1.4.dist-info/top_level.txt,sha256=Foud-Tbf5pviUJmp7wc3v24IjIyypkvbcZt7HkrWvss,28
+tablas_python-0.1.4.dist-info/RECORD,,

utils/data_helpers.py

@@ -141,22 +141,56 @@ def formato_moneda(val: Any, simbolo: str = "$", decimales: int = 0, separador_m
     return f"{simbolo} {texto}" if simbolo else texto
 
 
-def formato_porcentaje(val: Any, decimales: int = 1) -> str:
+def formato_porcentaje(
+    val: Any,
+    decimales: Optional[int] = None,
+    multiplicar_por_100: bool = False,
+    separador_decimal: str = ","
+) -> str:
     """
-    Formatea un valor a porcentaje.
-    Ejemplo:
-        formato_porcentaje(15.42) -> "15.4%"
-        formato_porcentaje(0.1542, es_ratio=True)
+    Formatea un valor a porcentaje de manera exacta.
+    
+    A diferencia de versiones anteriores, NO multiplica arbitrariamente por 100
+    a menos que se indique explícitamente con `multiplicar_por_100=True`.
+    Por lo tanto, 0.056 se muestra como 0,056% y 5.56 se muestra como 5,56%.
+    
+    Ejemplos:
+        formato_porcentaje(5.56)                     -> "5,56%"
+        formato_porcentaje(0.056)                    -> "0,056%"
+        formato_porcentaje("0.056%")                 -> "0,056%"
+        formato_porcentaje(0.056, multiplicar_por_100=True)  -> "5,6%"
+        formato_porcentaje(15.42, decimales=1)       -> "15,4%"
     """
+    if pd.isna(val) or val is None or str(val).strip() == "":
+        return ""
+
+    s_orig = str(val).strip()
+    tenia_simbolo_pct = "%" in s_orig
+
     num = limpiar_numero(val)
     if pd.isna(num) or not isinstance(num, (int, float)):
-        return "" if pd.isna(val) else str(val)
-    
-    # Si el valor está entre 0 y 1 (ratio), convertir a base 100
-    if -1.0 <= num <= 1.0 and num != 0:
+        return s_orig
+
+    # Solo multiplicar por 100 si el usuario lo pide explícitamente y el valor NO traía ya el '%'
+    if multiplicar_por_100 and not tenia_simbolo_pct:
         num = num * 100
 
-    return f"{num:.{decimales}f}%"
+    if decimales is not None:
+        fmt_str = f"{{:.{decimales}f}}"
+        txt_num = fmt_str.format(num)
+    else:
+        # Conservar los decimales significativos del número sin truncar
+        if isinstance(num, int) or (isinstance(num, float) and num.is_integer()):
+            txt_num = str(int(num))
+        else:
+            txt_num = f"{num:.6f}".rstrip('0').rstrip('.')
+
+    if separador_decimal == ",":
+        txt_num = txt_num.replace(".", ",")
+    else:
+        txt_num = txt_num.replace(",", ".")
+
+    return f"{txt_num}%"
 
 
 def formato_miles(val: Any, decimales: int = 0) -> str:
@@ -176,6 +210,8 @@ def formatear_dataframe(
             'Ventas': 'moneda',
             'Precio': 'moneda_2dec',
             'Margen': 'porcentaje',
+            'Participacion': 'porcentaje_1dec',
+            'Ratio': 'ratio_pct',
             'Cantidad': 'miles'
         })
     """
@@ -188,7 +224,13 @@ def formatear_dataframe(
         elif tipo == 'moneda_2dec':
             df_out[col] = df_out[col].apply(lambda x: formato_moneda(x, decimales=2))
         elif tipo == 'porcentaje':
-            df_out[col] = df_out[col].apply(formato_porcentaje)
+            df_out[col] = df_out[col].apply(lambda x: formato_porcentaje(x))
+        elif tipo == 'porcentaje_1dec':
+            df_out[col] = df_out[col].apply(lambda x: formato_porcentaje(x, decimales=1))
+        elif tipo == 'porcentaje_2dec':
+            df_out[col] = df_out[col].apply(lambda x: formato_porcentaje(x, decimales=2))
+        elif tipo == 'ratio_pct':
+            df_out[col] = df_out[col].apply(lambda x: formato_porcentaje(x, multiplicar_por_100=True, decimales=1))
         elif tipo == 'miles':
             df_out[col] = df_out[col].apply(formato_miles)
     return df_out

utils/excel_extractor.py

@@ -63,25 +63,66 @@ class ExcelTableExtractor:
         archivo_abierto: Optional[bool] = None,
         preferir_xlwings: bool = True
     ):
+        self.archivo_abierto = archivo_abierto
+        self.preferir_xlwings = preferir_xlwings and HAS_XLWINGS
+        self.book_name = os.path.basename(file_path) if file_path else ""
+        self.is_open_in_memory = False
+
+        # 1. Si el usuario indicó archivo_abierto=True o None, buscar primero en libros abiertos de xlwings
+        if self.preferir_xlwings and archivo_abierto is not False:
+            matched_book = self._find_open_workbook_in_excel(file_path)
+            if matched_book:
+                self.book_name = matched_book.name
+                self.file_path = getattr(matched_book, 'fullname', matched_book.name)
+                self.ext = os.path.splitext(matched_book.name)[1].lower() or ".xlsx"
+                self.is_open_in_memory = True
+                return
+
+        # Si forzó archivo_abierto=True pero no se encontró libro abierto en Excel
+        if archivo_abierto is True and self.preferir_xlwings:
+            abiertos = [b.name for b in xw.books] if HAS_XLWINGS and len(xw.books) > 0 else []
+            raise FileNotFoundError(
+                f"No se encontró ningún libro abierto en Excel con el nombre '{file_path}'. "
+                f"Libros actualmente abiertos en Excel: {abiertos if abiertos else 'Ninguno (Excel no tiene libros abiertos)'}"
+            )
+
+        # 2. Si es un archivo cerrado o en disco, resolver la ruta física
         self.file_path = resolve_file_path(file_path)
         if not os.path.exists(self.file_path):
             raise FileNotFoundError(f"No se encontró el archivo Excel en: {self.file_path}")
         
         self.ext = os.path.splitext(self.file_path)[1].lower()
-        self.archivo_abierto = archivo_abierto
-        self.preferir_xlwings = preferir_xlwings and HAS_XLWINGS
 
-    def _is_workbook_open_in_excel(self, file_name: str) -> bool:
-        """Comprueba si el libro ya está abierto en alguna sesión activa de Excel."""
+    def _find_open_workbook_in_excel(self, target: str) -> Optional[Any]:
+        """Busca y retorna el objeto Book de xlwings si está abierto en memoria."""
         if not HAS_XLWINGS:
-            return False
+            return None
         try:
+            if not target or target.lower() in ["", "activo", "active", "libro_activo", "hoja_activa"]:
+                if len(xw.books) > 0:
+                    return xw.books.active
+                return None
+
+            clean_target = os.path.basename(target).strip().lower()
+            name_no_ext = os.path.splitext(clean_target)[0]
+
             for book in xw.books:
-                if book.name.lower() == file_name.lower() or book.fullname.lower() == self.file_path.lower():
-                    return True
+                b_name = book.name.lower()
+                b_name_no_ext = os.path.splitext(b_name)[0]
+                b_fullname = getattr(book, 'fullname', '').lower()
+
+                # Comparar con nombre completo, sin extensión o fullname
+                if (clean_target == b_name or
+                    name_no_ext == b_name_no_ext or
+                    (b_fullname and clean_target == os.path.basename(b_fullname).lower())):
+                    return book
         except Exception:
-            return False
-        return False
+            return None
+        return None
+
+    def _is_workbook_open_in_excel(self, file_name: str) -> bool:
+        """Comprueba si el libro ya está abierto en alguna sesión activa de Excel."""
+        return self._find_open_workbook_in_excel(file_name) is not None
 
     def extract_by_cell_or_range(
         self,

utils/excel_writer.py

@@ -24,17 +24,36 @@ except ImportError:
 from .file_utils import resolve_file_path
 
 
-def _is_workbook_open_in_excel(file_path: str, file_name: str) -> bool:
-    """Comprueba si el libro ya está abierto en Excel activo."""
+def _find_open_workbook_in_excel(target: str) -> Optional[Any]:
+    """Busca y retorna el objeto Book de xlwings si está abierto en memoria."""
     if not HAS_XLWINGS:
-        return False
+        return None
     try:
+        if not target or target.lower() in ["", "activo", "active", "libro_activo"]:
+            if len(xw.books) > 0:
+                return xw.books.active
+            return None
+
+        clean_target = os.path.basename(target).strip().lower()
+        name_no_ext = os.path.splitext(clean_target)[0]
+
         for book in xw.books:
-            if book.name.lower() == file_name.lower() or book.fullname.lower() == file_path.lower():
-                return True
+            b_name = book.name.lower()
+            b_name_no_ext = os.path.splitext(b_name)[0]
+            b_fullname = getattr(book, 'fullname', '').lower()
+
+            if (clean_target == b_name or
+                name_no_ext == b_name_no_ext or
+                (b_fullname and clean_target == os.path.basename(b_fullname).lower())):
+                return book
     except Exception:
-        return False
-    return False
+        return None
+    return None
+
+
+def _is_workbook_open_in_excel(file_path: str, file_name: str) -> bool:
+    """Comprueba si el libro ya está abierto en Excel activo."""
+    return _find_open_workbook_in_excel(file_name) is not None or _find_open_workbook_in_excel(file_path) is not None
 
 
 def escribir_en_excel(
@@ -50,35 +69,45 @@ def escribir_en_excel(
 ) -> str:
     """
     Escribe un DataFrame directamente en una celda específica de un libro de Excel.
-
-    Parámetros:
-    -----------
-    df : pd.DataFrame
-        El DataFrame con los datos a escribir.
-    archivo_excel : str
-        Ruta o nombre del archivo Excel.
-    hoja : str o int (por defecto 1)
-        Nombre o número de la hoja donde se escribirán los datos.
-    celda_inicio : str (por defecto 'A1')
-        Coordenada de la celda superior izquierda donde comenzará a escribirse (ej: 'B5', 'C4').
-    incluir_encabezados : bool (por defecto True)
-        Si escribe los nombres de las columnas en la primera fila.
-    incluir_indice : bool (por defecto False)
-        Si incluye la columna de índice de pandas.
-    guardar : bool (por defecto True)
-        Si guarda el archivo tras escribir.
-    archivo_abierto : bool o None
-        - True: Se conecta a la ventana activa de Excel.
-        - False: Trabaja en segundo plano cerrado.
-        - None: Detecta automáticamente si está abierto o cerrado.
-    crear_si_no_existe : bool (por defecto True)
-        Crea un nuevo archivo Excel si no existe en la ruta dada.
-
-    Retorna:
-    --------
-    str
-        Ruta absoluta del archivo modificado.
     """
+    # 1. Si está abierto en memoria o archivo_abierto=True, usar directamente xlwings
+    if HAS_XLWINGS and archivo_abierto is not False:
+        matched_book = _find_open_workbook_in_excel(archivo_excel)
+        if matched_book:
+            book = matched_book
+            # Seleccionar o crear hoja
+            sheet_names = [s.name for s in book.sheets]
+            if isinstance(hoja, int):
+                if 1 <= hoja <= len(book.sheets):
+                    sht = book.sheets[hoja - 1]
+                else:
+                    sht = book.sheets.add(f"Hoja{hoja}")
+            else:
+                if str(hoja) in sheet_names:
+                    sht = book.sheets[str(hoja)]
+                else:
+                    sht = book.sheets.add(str(hoja))
+
+            clean_cell = celda_inicio.replace("$", "").upper()
+            sht.range(clean_cell).options(
+                index=incluir_indice,
+                header=incluir_encabezados
+            ).value = df
+
+            if guardar:
+                try: book.save()
+                except Exception: pass
+
+            return getattr(book, 'fullname', book.name)
+
+    if archivo_abierto is True and HAS_XLWINGS:
+        abiertos = [b.name for b in xw.books] if len(xw.books) > 0 else []
+        raise FileNotFoundError(
+            f"No se encontró ningún libro abierto en Excel con el nombre '{archivo_excel}'. "
+            f"Libros actualmente abiertos en Excel: {abiertos if abiertos else 'Ninguno (Excel no tiene libros abiertos)'}"
+        )
+
+    # 2. Si es archivo cerrado en disco
     try:
         resolved_path = resolve_file_path(archivo_excel)
     except Exception:
@@ -87,7 +116,6 @@ def escribir_en_excel(
     if not os.path.exists(resolved_path):
         if crear_si_no_existe:
             os.makedirs(os.path.dirname(resolved_path), exist_ok=True)
-            # Crear libro vacío con openpyxl o pandas
             df_init = pd.DataFrame()
             with pd.ExcelWriter(resolved_path, engine='openpyxl') as writer:
                 sheet_title = hoja if isinstance(hoja, str) else "Hoja1"
@@ -99,64 +127,45 @@ def escribir_en_excel(
 
     # Intentar con xlwings si está disponible
     if HAS_XLWINGS:
+        app = None
+        book = None
         try:
-            is_open = _is_workbook_open_in_excel(resolved_path, file_name)
-            should_connect = archivo_abierto is True or (archivo_abierto is None and is_open)
-
-            app = None
-            book = None
-            needs_close = False
-
-            try:
-                if should_connect:
-                    try:
-                        book = xw.books[file_name]
-                    except Exception:
-                        book = xw.Book(resolved_path)
+            app = xw.App(visible=False, add_book=False)
+            app.display_alerts = False
+            app.screen_updating = False
+            book = app.books.open(resolved_path)
+
+            sheet_names = [s.name for s in book.sheets]
+            if isinstance(hoja, int):
+                if 1 <= hoja <= len(book.sheets):
+                    sht = book.sheets[hoja - 1]
                 else:
-                    app = xw.App(visible=False, add_book=False)
-                    app.display_alerts = False
-                    app.screen_updating = False
-                    book = app.books.open(resolved_path)
-                    needs_close = True
-
-                # Seleccionar o crear hoja
-                sheet_names = [s.name for s in book.sheets]
-                if isinstance(hoja, int):
-                    if 1 <= hoja <= len(book.sheets):
-                        sht = book.sheets[hoja - 1]
-                    else:
-                        sht = book.sheets.add(f"Hoja{hoja}")
+                    sht = book.sheets.add(f"Hoja{hoja}")
+            else:
+                if str(hoja) in sheet_names:
+                    sht = book.sheets[str(hoja)]
                 else:
-                    if str(hoja) in sheet_names:
-                        sht = book.sheets[str(hoja)]
-                    else:
-                        sht = book.sheets.add(str(hoja))
-
-                # Escribir DataFrame en la celda indicada
-                clean_cell = celda_inicio.replace("$", "").upper()
-                sht.range(clean_cell).options(
-                    index=incluir_indice,
-                    header=incluir_encabezados
-                ).value = df
-
-                if guardar:
-                    book.save()
-
-                return resolved_path
-
-            finally:
-                if needs_close:
-                    if book:
-                        try: book.close()
-                        except Exception: pass
-                    if app:
-                        try: app.quit()
-                        except Exception: pass
-
-        except Exception as e:
-            # Fallback a openpyxl si ocurre algún error COM
-            pass
+                    sht = book.sheets.add(str(hoja))
+
+            clean_cell = celda_inicio.replace("$", "").upper()
+            sht.range(clean_cell).options(
+                index=incluir_indice,
+                header=incluir_encabezados
+            ).value = df
+
+            if guardar:
+                book.save()
+
+            return resolved_path
+        finally:
+            if book:
+                try: book.close()
+                except Exception: pass
+            if app:
+                try: app.quit()
+                except Exception: pass
+
+        return resolved_path
 
     # Fallback con openpyxl si xlwings no pudo ejecutarse
     if HAS_OPENPYXL: