La filosofía¶
Estos son los principios de tai-storage. Cada uno lo vigila un test, y explican casi todas las
decisiones de la API: por qué upload_file no sobrescribe, por qué exists() puede lanzar una
excepción, o por qué leer un CSV con un texto entre los números no da un vacío.
Para qué existe¶
tai-storage es la pieza de la plataforma tai que lee y escribe ficheros donde estén. Sus usos, por orden de importancia:
- Los ETL de los proyectos leen lo que dejan los clientes, sobre todo en SharePoint, y lo
convierten en DataFrames, casi siempre con
dev_modemientras se desarrollan. - tai-sql guarda ahí sus backups, que pueden pesar varios GB.
- Cualquier script puede usarla como librería independiente.
La librería no sabe que tai-sql o un ETL concreto existen: no hay ni un nombre ni una convención suya dentro.
1. Nada falla en silencio¶
Toda operación devuelve lo que promete o lanza un TaiStorageError con mensaje y solución.
Si el token de SharePoint ha caducado y no se puede renovar, exists() no devuelve False:
lanza AuthenticationError. False significa siempre «no existe», y nunca «no he podido
preguntar». Lo mismo con un filtro de fechas: si una comparación falla, el error se ve en vez de
devolver una lista vacía.
En los DataFrames esto significa que cada fila y cada columna del fichero acaba en el DataFrame, o hay un error, y que una conversión de tipos nunca introduce un nulo que no estaba:
# importe: 1.234,50 · 12,00 · pendiente
df = file.get_data().to_dataframe()
df["importe"] # texto: 'pendiente' no es un número, y el informe de lectura dice dónde está
Un problema que puedes arreglar tú (una credencial, una ruta, un formato) dice cómo hacerlo. Si el error es un fallo de la librería, se ve la traza entera.
2. Importar no tiene efectos¶
import tai_storage no carga pandas ni los SDK de los servicios, no abre conexiones, no lee
variables de entorno, no crea carpetas y no configura el logging de tu aplicación. La
configuración se lee al usarse, y si falta algo, el error dice qué definir:
StorageFactory.create_sharepoint()
# ConfigurationError: Falta el tenant de Azure AD. Solución: Pásalo como argumento o define SHAREPOINT_TENANT_ID=… en el entorno (tai-storage no carga el .env: si lo usas, cárgalo antes)
El logger tai-storage trae un valor por defecto que tu aplicación puede sobrescribir antes o
después de importar.
3. Un contrato, cuatro backends¶
El mismo código hace lo mismo en Local, SharePoint, Azure y Drive, con dev_mode o sin él:
las mismas rutas, los mismos valores por defecto de overwrite, el mismo significado de
recursive, pattern y los filtros de fecha, y las mismas excepciones.
Esto lo prueba la suite de contrato: una misma batería de tests contra cada backend (el disco, el disco con caché, Azurite, un SharePoint real y los servicios simulados). Lo que no está en esa suite no forma parte del contrato.
Una diferencia de un servicio que no se puede ocultar se declara en origin.capabilities y se
documenta. Por ejemplo, en Azure no existen las carpetas vacías.
4. Seguro por defecto¶
- Una ruta nunca sale del origen.
.., las rutas absolutas de Windows y los enlaces que escapan de la raíz son unInvalidPathError. - Pisar o borrar se pide explícitamente.
upload_file(),copy_to()ymove_to()no sobrescriben sinoverwrite=True, yfolder.delete()no borra una carpeta con contenido sinrecursive=True. Esto vale en todos los backends: en la 0.1, borrar una carpeta de SharePoint la vaciaba aunque no se pidiera. - Los logs no llevan secretos, ni tokens, ni URL firmadas.
- No hay credenciales por defecto, ni en el código ni en los tests.
folder.delete()
# FolderNotEmptyError: La carpeta 'tmp' de SharePoint contoso.sharepoint.com/sites/Ventas tiene contenido. Solución: Pasa recursive=True para borrarla con todo lo que contiene
5. El coste de cada operación se sabe¶
Cada operación de un servicio remoto documenta cuántas peticiones hace, y un listado no se convierte en una petición más por fichero al leer el tamaño o la fecha. Las tablas están en la página de cada origen.
Los ficheros grandes van por trozos: subir o bajar un backup de varios GB no lo carga entero en memoria. Con 1 GB, la memoria crece unos 20 MB en Local y en Azure. En SharePoint se midió lo mismo con 200 MB.
folder.upload_file(Path("/backups/produccion.dump"), "produccion.dump") # por trozos, desde la ruta
file.download_to_local("/tmp/produccion.dump") # por trozos y atómico
6. dev_mode es una caché, no otro backend¶
Con dev_mode=True, el origen guarda copias locales de lo que lee. Solo cambia de dónde salen
los bytes: los valores por defecto, los errores y lo que existe son los del servicio. Cada
lectura comprueba con el servicio si la copia sigue valiendo, y escribir o borrar va siempre al
servicio. Ver dev_mode.
Cómo se ve en los logs¶
La librería registra en el logger tai-storage de tai-alphi:
- en
INFO, lo que cambia algo y las lecturas de DataFrames; - en
DEBUG, cada lectura y cada petición; - en
WARNING, lo anómalo que se ha podido recuperar.
Un error no se registra: se lanza. Ver Logs.