Saltar a contenido

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' es informes/a.csv dentro de él.
  • \ también separa, como en Windows.
  • .. no se acepta, ni una unidad de Windows (C:): son un InvalidPathError. 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é.