Saltar a contenido

Primeros pasos

Un recorrido de diez minutos. Primero, una carpeta local: escribir, listar, leer un DataFrame y mover lo procesado. Después, el mismo código contra SharePoint.

pip install "tai-storage[data]"

1. Un origen

Un origen es la raíz de un almacenamiento: una carpeta del disco, una biblioteca de SharePoint, un container de Azure o una carpeta de Drive. Se crea con StorageFactory:

from tai_storage import StorageFactory

origin = StorageFactory.create_local("datos")    # crea ./datos si no existe

Todas las rutas son relativas a esa raíz, y ninguna puede salir de ella: get_folder("..") es un InvalidPathError.

2. Escribir y listar

entrada = origin.get_folder("entrada")      # no toca el disco: es una referencia

entrada.get_file("ventas.csv").write_text(
    "codigo;cliente;importe;fecha\n"
    "001;Ana;1.234,50;31/01/2024\n"
    "002;Luis;12,00;01/02/2024\n"
)

for file in entrada.list_files(pattern=r"\.csv$"):
    print(file.full_path, file.size, file.modified_time)
entrada/ventas.csv 83 2026-10-01 10:14:16.555198+00:00
  • write_text() y write() crean las carpetas que falten y sobrescriben, como open(…, "w").
  • pattern es una expresión regular que se busca en el nombre, sin distinguir mayúsculas.
  • Las fechas llevan siempre zona horaria (UTC). Y el tamaño y las fechas vienen ya en el listado: leerlos no cuesta otra petición.

3. Leer un DataFrame

df = entrada.get_file("ventas.csv").get_data().to_dataframe()
print(df)
print(df.dtypes)
  codigo cliente  importe      fecha
0    001     Ana   1234.5 2024-01-31
1    002    Luis     12.0 2024-02-01

codigo             string
cliente            string
importe           Float64
fecha      datetime64[us]

Fíjate en lo que no ha pasado:

  • el separador ; se ha detectado solo;
  • 001 sigue siendo 001: con ceros a la izquierda es un código, no un número;
  • 1.234,50 es 1234,5, porque el formato por defecto es el español;
  • 31/01/2024 es el 31 de enero, con el día primero.

Si una columna no se puede convertir entera, se queda como texto y el informe de lectura dice por qué. Nunca se convierte en vacío lo que no se entiende. Ver DataFrames.

4. Lo que no se puede hacer por descuido

from tai_storage import FileAlreadyExistsError, FileNotFoundError

try:
    entrada.upload_file(b"otra cosa", "ventas.csv")      # upload_file no sobrescribe
except FileAlreadyExistsError as error:
    print(error)

try:
    origin.get_file("entrada/ventas.xlsx").read()
except FileNotFoundError as error:                       # también es el FileNotFoundError de Python
    print(error.message)
    print(error.solution)
El fichero 'entrada/ventas.csv' de Local /home/ana/proyecto/datos ya existe. Solución: Pasa overwrite=True para reemplazarlo
No existe el fichero 'entrada/ventas.xlsx' de Local /home/ana/proyecto/datos
Comprueba la ruta y el nombre (con su extensión)

Cada error dice qué ha pasado y qué hacer. Ver Errores.

5. Mover lo procesado

entrada.get_file("ventas.csv").move_to(origin.get_file("procesados/2024/ventas.csv"))

move_to() también funciona entre orígenes distintos: copia, comprueba que el tamaño coincide y solo entonces borra el original.

6. Ver qué ha hecho

La librería registra con tai-alphi. Por defecto solo enseña lo anómalo; para seguir un pipeline, sube el logger a INFO:

from tai_storage import configure_logger

configure_logger("INFO")
[12:14:16][INFO] [tai-storage] Escrito 'entrada/ventas.csv' de Local /home/ana/proyecto/datos (83 B, 11 ms)
[12:14:17][INFO] [tai-storage] Leído 'entrada/ventas.csv': 2 filas × 4 columnas (csv, 69 ms)
[12:14:17][INFO] [tai-storage] Movido 'entrada/ventas.csv' a 'procesados/2024/ventas.csv' en Local /home/ana/proyecto/datos (1 ms)

Ver Logs.

7. El mismo código, contra SharePoint

pip install "tai-storage[sharepoint,data]"
export SHAREPOINT_TENANT_ID=...  SHAREPOINT_CLIENT_ID=...  SHAREPOINT_CLIENT_SECRET=...
export SHAREPOINT_HOSTNAME=contoso.sharepoint.com  SHAREPOINT_SITE_NAME=Ventas
origin = StorageFactory.create_sharepoint()     # en lugar de create_local("datos")

Todo lo demás —get_folder, list_files, get_data, move_to, los errores— funciona igual. Cómo se da de alta la aplicación en Azure AD: SharePoint.

8. Mientras desarrollas: dev_mode

origin = StorageFactory.create_sharepoint(dev_mode=True)

Guarda en .cached_storage/ una copia de lo que lees. La siguiente ejecución la usa si el fichero no ha cambiado en SharePoint, con una sola petición para comprobarlo. Escribir y borrar siguen yendo a SharePoint. Ver dev_mode.


Siguiente: Los conceptos, o directamente los orígenes.