tablas-python 0.1.0__py3-none-any.whl

utils/exporter.py

@@ -0,0 +1,158 @@
+"""
+Módulo dedicado a la exportación de DataFrames y lotes de tablas a archivos CSV y Excel.
+Optimizado con codificación utf-8-sig y separadores configurables para máxima compatibilidad con Microsoft Excel.
+"""
+
+from typing import Dict, List, Optional, Union, Any
+import os
+import pandas as pd
+from .file_utils import ensure_dir, sanitize_filename
+
+
+class TableExporter:
+    """
+    Clase de exportación para guardar DataFrames individuales o colecciones completas de tablas.
+    """
+
+    @staticmethod
+    def to_csv(
+        df: pd.DataFrame,
+        output_path: str,
+        sep: str = ";",
+        encoding: str = "utf-8-sig",
+        index: bool = False,
+        decimal: str = ",",
+        **kwargs
+    ) -> str:
+        """
+        Exporta un DataFrame a archivo CSV.
+
+        Parámetros:
+        -----------
+        df : pd.DataFrame
+            El DataFrame a exportar.
+        output_path : str
+            Ruta del archivo CSV destino.
+        sep : str (por defecto ';')
+            Separador de campos (';' abre perfectamente en Excel en español sin desfasar columnas).
+        encoding : str (por defecto 'utf-8-sig')
+            Codificación con BOM para que tildes, caracteres especiales y la 'ñ' se vean bien en Excel.
+        index : bool (por defecto False)
+            Si incluye la columna de índice numérico de pandas.
+        decimal : str (por defecto ',')
+            Separador decimal para valores numéricos en el CSV.
+
+        Retorna:
+        --------
+        str
+            Ruta absoluta del archivo CSV generado.
+        """
+        if not output_path.lower().endswith(".csv"):
+            output_path += ".csv"
+
+        ensure_dir(os.path.dirname(os.path.abspath(output_path)))
+        
+        df.to_csv(
+            output_path,
+            sep=sep,
+            encoding=encoding,
+            index=index,
+            decimal=decimal,
+            **kwargs
+        )
+        return os.path.abspath(output_path)
+
+    @staticmethod
+    def to_excel(
+        df: pd.DataFrame,
+        output_path: str,
+        sheet_name: str = "Datos",
+        index: bool = False,
+        **kwargs
+    ) -> str:
+        """
+        Exporta un DataFrame a un archivo Excel (.xlsx).
+        """
+        if not output_path.lower().endswith((".xlsx", ".xls")):
+            output_path += ".xlsx"
+
+        ensure_dir(os.path.dirname(os.path.abspath(output_path)))
+        
+        df.to_excel(
+            output_path,
+            sheet_name=sheet_name,
+            index=index,
+            engine="openpyxl",
+            **kwargs
+        )
+        return os.path.abspath(output_path)
+
+    @classmethod
+    def export_batch_to_csv(
+        cls,
+        tables_dict: Dict[str, pd.DataFrame],
+        output_dir: str,
+        sep: str = ";",
+        encoding: str = "utf-8-sig",
+        index: bool = False
+    ) -> List[str]:
+        """
+        Exporta múltiples DataFrames en archivos CSV individuales dentro de un directorio.
+
+        Parámetros:
+        -----------
+        tables_dict : dict
+            Diccionario {nombre_tabla: df} con los DataFrames a exportar.
+        output_dir : str
+            Directorio donde se guardarán los archivos CSV.
+
+        Retorna:
+        --------
+        List[str]
+            Lista con las rutas absolutas de todos los archivos CSV creados.
+        """
+        ensure_dir(output_dir)
+        generated_files: List[str] = []
+
+        for name, df in tables_dict.items():
+            if df is None or df.empty:
+                continue
+            
+            clean_name = sanitize_filename(str(name))
+            file_name = f"{clean_name}.csv"
+            out_file = os.path.join(output_dir, file_name)
+            
+            saved_path = cls.to_csv(
+                df=df,
+                output_path=out_file,
+                sep=sep,
+                encoding=encoding,
+                index=index
+            )
+            generated_files.append(saved_path)
+
+        return generated_files
+
+
+# Funciones directas de conveniencia
+def guardar_csv(
+    df: pd.DataFrame,
+    ruta: str,
+    sep: str = ";",
+    encoding: str = "utf-8-sig",
+    index: bool = False,
+    **kwargs
+) -> str:
+    """Función de una línea para guardar un DataFrame a CSV optimizado para Excel."""
+    return TableExporter.to_csv(df, output_path=ruta, sep=sep, encoding=encoding, index=index, **kwargs)
+
+
+def guardar_excel(
+    df: pd.DataFrame,
+    ruta: str,
+    sheet_name: str = "Datos",
+    index: bool = False,
+    **kwargs
+) -> str:
+    """Función de una línea para guardar un DataFrame a Excel."""
+    return TableExporter.to_excel(df, output_path=ruta, sheet_name=sheet_name, index=index, **kwargs)

utils/file_utils.py

@@ -0,0 +1,65 @@
+"""
+Módulo de utilidades para manejo seguro de rutas de archivos y nombres de exportación.
+"""
+
+import os
+import sys
+import re
+from typing import Optional
+
+# Configurar automáticamente la salida UTF-8 en Windows al importar
+if sys.platform == "win32":
+    try:
+        sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+    except Exception:
+        pass
+
+
+def resolve_file_path(file_path: str) -> str:
+    """
+    Resuelve una ruta de archivo ya sea que se pase:
+    - Ruta absoluta (ej: C:/Users/.../archivo.xlsx)
+    - Ruta relativa al directorio de trabajo actual (ej: samples/archivo.xlsx o ./archivo.xlsx)
+    - Nombre simple de archivo en la misma carpeta del script o en la carpeta samples.
+    """
+    if not file_path:
+        raise ValueError("La ruta del archivo no puede estar vacía.")
+
+    # 1. Si es absoluta y existe
+    if os.path.isabs(file_path) and os.path.exists(file_path):
+        return os.path.abspath(file_path)
+    
+    # 2. Relativa directa al directorio de trabajo actual (CWD)
+    if os.path.exists(file_path):
+        return os.path.abspath(file_path)
+
+    # 3. Relativo al directorio raíz del proyecto
+    base_dir = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+    alt_path = os.path.join(base_dir, file_path)
+    if os.path.exists(alt_path):
+        return os.path.abspath(alt_path)
+
+    # 4. Dentro de la carpeta samples
+    samples_path = os.path.join(base_dir, "samples", file_path)
+    if os.path.exists(samples_path):
+        return os.path.abspath(samples_path)
+
+    # Si no se encuentra, retornar la ruta absoluta esperada para que el error sea claro
+    return os.path.abspath(file_path)
+
+
+def sanitize_filename(name: str, replacement: str = "_") -> str:
+    """
+    Limpia una cadena para que sea un nombre de archivo válido en Windows/Linux/Mac.
+    """
+    # Eliminar caracteres no permitidos en nombres de archivo
+    sanitized = re.sub(r'[\\/*?:"<>|]', replacement, name)
+    # Reducir espacios y guiones repetidos
+    sanitized = re.sub(r'\s+', '_', sanitized).strip('._ ')
+    return sanitized if sanitized else "tabla"
+
+
+def ensure_dir(dir_path: str) -> str:
+    """Asegura que el directorio exista creándolo recursivamente si es necesario."""
+    os.makedirs(dir_path, exist_ok=True)
+    return os.path.abspath(dir_path)

utils/pdf_extractor.py

@@ -0,0 +1,129 @@
+"""
+Módulo para extracción de tablas desde archivos PDF usando pdfplumber.
+Soporta detección de múltiples tablas por página, configuraciones de extracción
+y escaneo página por página o completo.
+"""
+
+from typing import List, Dict, Any, Optional
+from dataclasses import dataclass
+import os
+import pdfplumber
+from .file_utils import resolve_file_path
+
+
+@dataclass
+class RawTableInfo:
+    """Información y contenido crudo de una tabla detectada."""
+    table_id: int
+    source_file: str
+    page_number: int
+    table_in_page: int
+    raw_data: List[List[Any]]
+    num_rows: int
+    num_cols: int
+    bbox: Optional[tuple] = None
+
+    def get_preview(self, max_rows: int = 5) -> List[List[Any]]:
+        """Retorna las primeras filas crudas para inspección visual."""
+        return self.raw_data[:max_rows]
+
+
+class PDFTableExtractor:
+    """
+    Extractor de tablas especializado en documentos PDF.
+    """
+
+    def __init__(self, file_path: str):
+        self.file_path = resolve_file_path(file_path)
+        if not os.path.exists(self.file_path):
+            raise FileNotFoundError(f"El archivo PDF no existe: {self.file_path}")
+
+    def extract_all_tables(
+        self,
+        pages: Optional[List[int]] = None,
+        table_settings: Optional[Dict[str, Any]] = None,
+        fallback_text_strategy: bool = True
+    ) -> List[RawTableInfo]:
+        """
+        Extrae todas las tablas del PDF.
+
+        Parámetros:
+        -----------
+        pages : list of int, opcional
+            Lista de números de página a procesar (1-indexed). Si es None, procesa todo el PDF.
+        table_settings : dict, opcional
+            Configuración personalizada para pdfplumber (ej. vertical_strategy, horizontal_strategy).
+        fallback_text_strategy : bool (por defecto True)
+            Si con la estrategia estándar no se detectan tablas, intenta con estrategia de texto.
+
+        Retorna:
+        --------
+        List[RawTableInfo]
+            Lista con la información y datos crudos de cada tabla encontrada.
+        """
+        tables_found: List[RawTableInfo] = []
+        global_table_id = 1
+
+        with pdfplumber.open(self.file_path) as pdf:
+            total_pages = len(pdf.pages)
+            page_indices = range(total_pages)
+            
+            if pages is not None:
+                # Convertir a 0-indexed y filtrar válidas
+                page_indices = [p - 1 for p in pages if 1 <= p <= total_pages]
+
+            for p_idx in page_indices:
+                page = pdf.pages[p_idx]
+                page_num = p_idx + 1
+                
+                # 1. Intento con settings provistos o estándar
+                extracted = page.extract_tables(table_settings) if table_settings else page.extract_tables()
+                
+                # 2. Si no encontró y fallback está activo, probar estrategia text
+                if not extracted and fallback_text_strategy:
+                    alt_settings = {
+                        "vertical_strategy": "text",
+                        "horizontal_strategy": "text",
+                        "snap_tolerance": 3,
+                    }
+                    extracted = page.extract_tables(alt_settings)
+
+                # Procesar cada tabla detectada en la página
+                for table_idx, raw_table in enumerate(extracted, start=1):
+                    # Validar que la tabla tenga contenido útil
+                    if not raw_table or len(raw_table) == 0:
+                        continue
+                    
+                    # Calcular filas y columnas
+                    n_rows = len(raw_table)
+                    n_cols = max((len(r) for r in raw_table if isinstance(r, list)), default=0)
+                    
+                    info = RawTableInfo(
+                        table_id=global_table_id,
+                        source_file=self.file_path,
+                        page_number=page_num,
+                        table_in_page=table_idx,
+                        raw_data=raw_table,
+                        num_rows=n_rows,
+                        num_cols=n_cols
+                    )
+                    tables_found.append(info)
+                    global_table_id += 1
+
+        return tables_found
+
+    def extract_table_by_id(
+        self,
+        table_id: int,
+        table_settings: Optional[Dict[str, Any]] = None
+    ) -> RawTableInfo:
+        """
+        Extrae y devuelve directamente la tabla con el ID global indicado (1-indexed).
+        """
+        all_tables = self.extract_all_tables(table_settings=table_settings)
+        for t in all_tables:
+            if t.table_id == table_id:
+                return t
+        raise IndexError(
+            f"No se encontró la tabla {table_id}. Tablas disponibles: {len(all_tables)}"
+        )

utils/sqlite_extractor.py

@@ -0,0 +1,133 @@
+"""
+Módulo para extracción de tablas y consultas desde bases de datos SQLite (.db, .sqlite, .sqlite3).
+Permite listar tablas, inspeccionar esquemas y extraer DataFrames de tablas completas o consultas SQL.
+"""
+
+from typing import List, Dict, Any, Optional, Union
+from dataclasses import dataclass
+import os
+import sqlite3
+import pandas as pd
+from .file_utils import resolve_file_path
+
+
+@dataclass
+class RawSQLiteTableInfo:
+    """Información de una tabla o vista detectada en una base de datos SQLite."""
+    table_id: int
+    source_file: str
+    table_name: str
+    table_type: str  # 'table' o 'view'
+    columns: List[str]
+    num_rows: int
+    raw_data: List[List[Any]]
+    num_cols: int
+
+    def get_preview(self, max_rows: int = 5) -> List[List[Any]]:
+        """Retorna los encabezados y las primeras filas de datos."""
+        if not self.raw_data:
+            return [self.columns]
+        return [self.columns] + self.raw_data[:max_rows]
+
+
+class SQLiteTableExtractor:
+    """
+    Extractor de datos para bases de datos SQLite.
+    """
+
+    def __init__(self, file_path: str):
+        self.file_path = resolve_file_path(file_path)
+        if not os.path.exists(self.file_path):
+            raise FileNotFoundError(f"No se encontró la base de datos SQLite en: {self.file_path}")
+
+    def list_tables(self) -> List[Dict[str, str]]:
+        """Lista todas las tablas y vistas disponibles en la base de datos."""
+        with sqlite3.connect(self.file_path) as conn:
+            cursor = conn.cursor()
+            cursor.execute(
+                "SELECT name, type FROM sqlite_master "
+                "WHERE type IN ('table', 'view') AND name NOT LIKE 'sqlite_%' "
+                "ORDER BY name"
+            )
+            rows = cursor.fetchall()
+            return [{"name": r[0], "type": r[1]} for r in rows]
+
+    def extract_all_tables(self) -> List[RawSQLiteTableInfo]:
+        """
+        Extrae la información y una muestra de datos de todas las tablas en la base de datos.
+        """
+        tables = self.list_tables()
+        tables_found: List[RawSQLiteTableInfo] = []
+
+        with sqlite3.connect(self.file_path) as conn:
+            for idx, item in enumerate(tables, start=1):
+                t_name = item["name"]
+                t_type = item["type"]
+                
+                # Obtener columnas
+                cursor = conn.cursor()
+                cursor.execute(f"PRAGMA table_info('{t_name}')")
+                col_info = cursor.fetchall()
+                cols = [c[1] for c in col_info] if col_info else []
+
+                # Obtener conteo de filas
+                try:
+                    cursor.execute(f"SELECT COUNT(*) FROM '{t_name}'")
+                    row_count = cursor.fetchone()[0]
+                except Exception:
+                    row_count = 0
+
+                # Obtener primeras filas
+                cursor.execute(f"SELECT * FROM '{t_name}' LIMIT 20")
+                sample_data = [list(r) for r in cursor.fetchall()]
+
+                info = RawSQLiteTableInfo(
+                    table_id=idx,
+                    source_file=self.file_path,
+                    table_name=t_name,
+                    table_type=t_type,
+                    columns=cols,
+                    num_rows=row_count,
+                    raw_data=sample_data,
+                    num_cols=len(cols)
+                )
+                tables_found.append(info)
+
+        return tables_found
+
+    def get_table_df(self, table_name_or_id: Union[str, int]) -> pd.DataFrame:
+        """
+        Obtiene un DataFrame con la tabla completa por su nombre o su ID (1-indexed).
+        """
+        tables = self.list_tables()
+        selected_name = None
+
+        if isinstance(table_name_or_id, int):
+            if 1 <= table_name_or_id <= len(tables):
+                selected_name = tables[table_name_or_id - 1]["name"]
+            else:
+                raise IndexError(f"ID de tabla {table_name_or_id} fuera de rango. Hay {len(tables)} tablas.")
+        else:
+            table_str = str(table_name_or_id).strip()
+            # Buscar coincidencia exacta o insensible a mayúsculas
+            for t in tables:
+                if t["name"].lower() == table_str.lower():
+                    selected_name = t["name"]
+                    break
+            if not selected_name:
+                raise ValueError(f"No se encontró la tabla '{table_name_or_id}' en {self.file_path}")
+
+        with sqlite3.connect(self.file_path) as conn:
+            df = pd.read_sql_query(f"SELECT * FROM '{selected_name}'", conn)
+        return df
+
+    def query_df(self, sql_query: str, params: Optional[Union[tuple, dict]] = None) -> pd.DataFrame:
+        """
+        Ejecuta una consulta SQL personalizada y devuelve el resultado en un DataFrame.
+        """
+        with sqlite3.connect(self.file_path) as conn:
+            if params is not None:
+                df = pd.read_sql_query(sql_query, conn, params=params)
+            else:
+                df = pd.read_sql_query(sql_query, conn)
+        return df