Saltar a contenido

Los orígenes

Cuatro servicios, una API y una semántica. Lo que cambia entre ellos es cómo se crean y qué cuesta cada operación.

Origen Se crea con Extra La raíz es
Local StorageFactory.create_local(root_path) — Un directorio
SharePoint StorageFactory.create_sharepoint() sharepoint Una biblioteca de documentos de un sitio
Azure Blob Storage StorageFactory.create_azure(container=…) azure Un container, o la cuenta entera
Google Drive StorageFactory.create_googledrive() googledrive Una carpeta de una unidad compartida

Con cualquiera de ellos, dev_mode=True añade una caché local de lo que se lee.

StorageFactory

Cada create_*:

  1. Lee del entorno lo que no se pasa como argumento. Si falta algo, lanza un ConfigurationError que dice qué variable definir. tai-storage no carga ficheros .env: si los usas, cárgalos tú antes (por ejemplo con python-dotenv).
  2. Conecta (auto_connect=True): comprueba las credenciales y la raíz, y si algo no vale falla en ese momento, no a mitad del proceso.
  3. Con dev_mode=True, envuelve el origen en un CachedOrigin.
from tai_storage import StorageFactory

origin = StorageFactory.create_sharepoint()                                  # todo del entorno
origin = StorageFactory.create_sharepoint(site_name="Ventas", drive="Informes")   # una parte a mano
origin = StorageFactory.create_azure(container="backups", dev_mode=True)

Las variables de cada servicio están en Variables de entorno.

Lo que es igual en todos

  • Las rutas, sus reglas y sus errores (Los conceptos).
  • write() sobrescribe, mientras que upload_file(), copy_to() y move_to() no lo hacen sin overwrite=True. Escribir crea las carpetas que falten.
  • folder.delete() no borra una carpeta con contenido sin recursive=True.
  • pattern es una expresión regular que se busca en el nombre (re.search) sin distinguir mayúsculas. Los filtros de fecha son estrictos, y una fecha sin zona se toma como hora local.
  • Los listados vienen ordenados por ruta y con los metadatos de cada fichero.
  • Los ficheros grandes se suben y se bajan por trozos.

Lo que cambia

Local SharePoint Azure Drive
Carpetas vacías sí sí no (una carpeta es un prefijo) sí
Borrar definitivo a la papelera del sitio definitivo definitivo
overwrite=False atómico atómico atómico se comprueba antes de subir (no atómico)
Escritura atómica (temporal + rename) sesión de subida por trozos bloques subida reanudable por trozos
Reintentos — 429 y 5xx, con Retry-After los del SDK 429, 5xx y el 403 de límite de peticiones
Contrastado con el disco un SharePoint real Azurite (el emulador oficial) un Drive simulado

Elegir

  • Un ETL que lee lo que deja un cliente: el origen donde lo deja (casi siempre SharePoint), con dev_mode=True mientras se desarrolla.
  • Backups de tai-sql: Azure con container= (una raíz propia y escritura atómica), o Local.
  • Tests de tu proyecto: create_local(tmp_path). Como la semántica es la misma, lo que pase en local pasará igual en el servicio.

Sin StorageFactory

Los orígenes se pueden construir directamente. Así no se lee el entorno ni se conecta hasta la primera operación:

from tai_storage import LocalOrigin, SharePointOrigin, AzureBlobOrigin, GoogleDriveOrigin, CachedOrigin

origin = SharePointOrigin(tenant_id, client_id, client_secret, site_name="Ventas", hostname="contoso.sharepoint.com")
cached = CachedOrigin(origin, cache_path=".cached_storage")