Los conceptos¶
Toda la librería son tres piezas encadenadas, con las mismas reglas en los cuatro servicios.
Origin ──get_folder()──▶ Folder ──get_file()──▶ File
la raíz una carpeta un fichero
(disco, biblioteca, list_files() read() / open_read()
container, carpeta list_folders() write() / write_from()
de Drive) create() / delete() copy_to() / move_to() / delete()
upload_file() get_data() → DataFrame
El origen¶
Un Origin es un espacio de nombres con una raíz:
| Backend | La raíz es |
|---|---|
LocalOrigin |
Un directorio |
SharePointOrigin |
Una biblioteca de documentos de un sitio (la principal, o la que digas) |
AzureBlobOrigin |
Un container (con container=) o la cuenta entera |
GoogleDriveOrigin |
Una carpeta, de «Mi unidad» o de una unidad compartida |
Se crea con StorageFactory.create_*, que lee las credenciales del entorno y comprueba que
funcionan (auto_connect=True):
origin = StorageFactory.create_sharepoint() # conecta ya: si algo falla, falla aquí
origin = StorageFactory.create_sharepoint(auto_connect=False) # conecta en la primera operación
Construir un origen a mano (SharePointOrigin(...)) no habla con el servicio: conecta solo la
primera vez que se usa. connect() sirve para comprobar la configuración antes. Un origen
también es un gestor de contexto (with StorageFactory.create_local("datos") as origin: ...),
que cierra sus conexiones al salir.
Referencias, no consultas¶
get_folder() y get_file() no hablan con el servicio: devuelven una referencia a una ruta.
Lo que no existe falla al usarlo, con un FileNotFoundError o un FolderNotFoundError:
file = origin.get_file("informes/2024/enero.csv") # 0 peticiones
file.exists() # 1 petición: True o False
file.read() # FileNotFoundError si no existe
Así, preparar una ruta para escribir en ella no cuesta nada, y comprobar si algo existe es explícito.
Las rutas¶
Las mismas reglas en los cuatro backends:
- Son relativas a la raíz del origen.
'','.'y'/'son la raíz. - Una barra inicial no sale del origen:
'/informes/a.csv'esinformes/a.csvdentro de él. \también separa, como en Windows...no se acepta, ni una unidad de Windows (C:): son unInvalidPathError. En el disco local tampoco se sale a través de un enlace simbólico.
origin.get_folder("..")
# InvalidPathError: La ruta '..' sale del origen con '..'. Solución: Usa rutas relativas a la raíz del origen, sin '..'
file.full_path es la ruta relativa como texto (informes/2024/enero.csv); file.filename, el
nombre con extensión; file.name, sin ella; file.extension, la extensión con el punto.
Los metadatos¶
file.info es un FileInfo:
| Campo | Qué es |
|---|---|
size |
Tamaño en bytes |
created, modified |
Fechas, siempre con zona horaria (UTC) |
etag |
Cambia cuando cambia el contenido. Es lo que usa dev_mode para saber si su copia vale |
content_type |
El tipo MIME, si el servicio lo da |
extra |
Lo propio del servicio: item_id y web_url en SharePoint, file_id y web_url en Drive, blob_name y metadata en Azure |
Hay atajos: file.size, file.modified_time, file.created_time. Un fichero que viene de un
listado trae ya sus metadatos: leerlos no hace ninguna petición más. Un fichero pedido por
ruta los pide una vez, y file.refresh() los vuelve a pedir.
info.to_dict() devuelve las claves que daba get_metadata() en la 0.1.
Las fechas¶
Todas las fechas que entrega la librería llevan zona (UTC). En los filtros se aceptan también
fechas sin zona, que se interpretan como hora local, que es lo que quiere decir
datetime.now() - timedelta(days=7):
from datetime import datetime, timedelta
recientes = folder.list_files(modified_after=datetime.now() - timedelta(days=7))
Lo que no se puede ocultar¶
Un servicio puede no saber hacer algo. Esas diferencias se declaran en origin.capabilities, y
no se dejan al azar de cada backend:
| Capacidad | Qué dice | Dónde es False |
|---|---|---|
empty_folders |
Si una carpeta puede existir vacía | Azure: una carpeta es un prefijo y existe mientras tenga algún fichero |
if not origin.capabilities.empty_folders:
... # en Azure, create() de una carpeta no deja nada hasta que se escribe en ella
Atajos del origen¶
El origen repite lo más común, para no pedir la carpeta antes:
origin.get_file("a/b.csv") # = origin.get_folder("a").get_file("b.csv")
origin.list_folders("informes")
origin.create_folder("informes/2025")
origin.delete_folder("tmp", recursive=True)
origin.folder_exists("informes")
Siguiente: La filosofía, con lo que la librería garantiza y por qué.