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.
-
Primeros pasos
De una carpeta local a SharePoint, con un DataFrame por el camino.
-
Los orígenes
Local, SharePoint, Azure y Drive: cómo se configura cada uno y qué cuesta cada operación.
-
DataFrames
Del fichero a pandas sin perder decimales, ceros a la izquierda ni fechas.
Los principios que explican el resto¶
- 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 devuelveFalseporque haya caducado el token, y leer un CSV no convierte en vacío lo que no entiende. - 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.
- Seguro por defecto. Una ruta nunca sale del origen, nada se sobrescribe ni se borra sin pedirlo, y los logs no llevan secretos.
- Importar no tiene efectos.
import tai_storageno carga pandas ni los SDK de los servicios, no abre conexiones y no lee el entorno. Cada cosa se carga cuando se usa. - 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.