Saltar a contenido

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:

  1. Los ETL de los proyectos leen lo que dejan los clientes, sobre todo en SharePoint, y lo convierten en DataFrames, casi siempre con dev_mode mientras se desarrollan.
  2. tai-sql guarda ahí sus backups, que pueden pesar varios GB.
  3. 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.

file.exists()

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 un InvalidPathError.
  • Pisar o borrar se pide explícitamente. upload_file(), copy_to() y move_to() no sobrescriben sin overwrite=True, y folder.delete() no borra una carpeta con contenido sin recursive=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.