Saltar a contenido

tai-storage

Los mismos ficheros, estén donde estén. Con una sola API se trabaja con el disco local, SharePoint Online, Azure Blob Storage y Google Drive, y con la misma semántica en los cuatro: las mismas rutas, los mismos valores por defecto y los mismos errores. Encima de eso, la lectura de CSV, Excel, JSON y Parquet como DataFrames, sin perder ni una fila ni una columna sin avisar, y un informe HTML con lo que tienen de raro.

from tai_storage import StorageFactory

origin = StorageFactory.create_sharepoint()                 # credenciales del entorno

for file in origin.get_folder("Ventas/2024").list_files(pattern=r"\.csv$"):
    print(file.filename, file.size, file.modified_time)     # sin una petición más por fichero

df = origin.get_file("Ventas/2024/enero.csv").get_data().to_dataframe()
origin.get_file("Informes/enero.csv").write(df.to_csv(index=False).encode())

Cambia create_sharepoint() por create_local("/datos"), create_azure(container="ventas") o create_googledrive() y el resto del código no cambia.


Empieza por aquí

  • Instalación


    El núcleo y un extra por cada servicio: instalas solo lo que usas.

    Instalación

  • Primeros pasos


    De una carpeta local a SharePoint, con un DataFrame por el camino.

    Primeros pasos

  • Los orígenes


    Local, SharePoint, Azure y Drive: cómo se configura cada uno y qué cuesta cada operación.

    Orígenes

  • DataFrames


    Del fichero a pandas sin perder decimales, ceros a la izquierda ni fechas.

    DataFrames


Los principios que explican el resto

  1. Nada falla en silencio. Toda operación devuelve lo que promete o lanza un error que dice qué ha pasado y qué hacer. exists() no devuelve False porque haya caducado el token, y leer un CSV no convierte en vacío lo que no entiende.
  2. Un contrato, cuatro backends. El mismo código hace lo mismo en Local, SharePoint, Azure y Drive, con caché o sin ella. Lo comprueba una misma batería de tests contra cada uno.
  3. Seguro por defecto. Una ruta nunca sale del origen, nada se sobrescribe ni se borra sin pedirlo, y los logs no llevan secretos.
  4. Importar no tiene efectos. import tai_storage no carga pandas ni los SDK de los servicios, no abre conexiones y no lee el entorno. Cada cosa se carga cuando se usa.
  5. El coste se sabe. Cada operación de un servicio remoto documenta cuántas peticiones hace, y los ficheros grandes van por trozos: subir un backup de varios GB no lo carga en memoria.

Están explicados, con ejemplos, en La filosofía.


Qué trae

Cuatro orígenes Local, SharePoint (Microsoft Graph), Azure Blob y Google Drive, con la misma API
Ficheros grandes Subida y descarga por trozos. Con 1 GB, la memoria crece unos 20 MB
Errores con solución Cada error dice qué hacer, y los de fichero son también los de Python (except FileNotFoundError los captura)
Reintentos y tokens Los servicios remotos reintentan los 429 y 5xx respetando Retry-After, y renuevan el token cuando caduca
dev_mode Una caché local para no descargar lo mismo en cada ejecución mientras desarrollas, con la misma semántica que el origen
DataFrames CSV, Excel, JSON y Parquet, con números y fechas en formato español por defecto e inferencia de tipos que nunca introduce un nulo
Informe de datos Un HTML que se abre sin internet, con los avisos (nulos, duplicados, códigos, atípicos…) y una ficha por columna
Logs Con tai-alphi: lo que cambia algo en INFO, lo anómalo en WARNING
El CLI tai-storage ping, ls, read, analyze: probar credenciales, ver una carpeta, saber cómo se leerá un fichero o sacar su informe sin escribir código
Reglas para asistentes de IA tai-storage rules install deja en tu proyecto lo que un asistente necesita saber de la librería

Quién la usa

  • Los ETL de los proyectos: leer lo que dejan los clientes, casi siempre en SharePoint, y convertirlo en DataFrames. Mientras se desarrollan, con dev_mode.
  • tai-sql, como almacén de sus backups (backup_storage): ficheros que pueden pesar varios GB.
  • Cualquier script que necesite leer o escribir en esos servicios sin aprender cuatro SDK.