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_*:
- Lee del entorno lo que no se pasa como argumento. Si falta algo, lanza un
ConfigurationErrorque dice qué variable definir. tai-storage no carga ficheros.env: si los usas, cárgalos tú antes (por ejemplo conpython-dotenv). - 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. - Con
dev_mode=True, envuelve el origen en unCachedOrigin.
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 queupload_file(),copy_to()ymove_to()no lo hacen sinoverwrite=True. Escribir crea las carpetas que falten.folder.delete()no borra una carpeta con contenido sinrecursive=True.patternes 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=Truemientras 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: