Saltar a contenido

Un backend nuevo

Un backend (un FTP, S3, un servidor de ficheros) implementa las primitivas de tres clases abstractas. Las reglas del contrato no se implementan en cada backend: los valores por defecto, los filtros de list_files, las comprobaciones antes de borrar, las rutas y los logs viven en la base y valen para todos.

tai_storage.base.Origin   →   tai_storage.base.Folder   →   tai_storage.base.File

Lo que implementa cada clase

Método Qué hace
connect() Comprueba credenciales y raíz; lanza si no valen. Al conseguirlo, llama a self._mark_connected(), que lo registra en INFO una sola vez
_make_folder(path) La carpeta de path (un PurePosixPath ya normalizado), sin hablar con el servicio
describe() Qué almacenamiento es, para los mensajes, sin secretos ("FTP ftp.cliente.com")
cache_key Un nombre estable que lo distinga en la caché de dev_mode
capabilities Lo que no puede hacer (Capabilities(empty_folders=False))
Método Qué hace
exists() True/False; lanza ante cualquier otro fallo
_list() (ficheros, carpetas) directos, con sus metadatos
_create(parents) Crearla (la base ya ha comprobado que no existe y que está el padre)
_delete(recursive) Borrarla (la base ya ha comprobado que existe y, sin recursive, que está vacía)
_make_file(name, info=None) El File de name
_info() Su FolderInfo
_walk_files(), _is_empty() Opcionales: si el servicio puede hacerlo más rápido que la base
Método Qué hace
_fetch_info() Su FileInfo; FileNotFoundError si no existe
_open_read() Un stream de lectura, sin descargarlo entero
_write(stream, size, overwrite) Escribir por trozos. Crea las carpetas que falten, y con overwrite=False falla si existe, de forma atómica si el servicio puede
_delete() Borrarlo; FileNotFoundError si no existe
_copy_native(), _move_native() Opcionales: devuelven True si el servicio copia o mueve sin pasar los bytes por el proceso

open_read(), read(), write(), write_from(), delete(), copy_to(), move_to(), list_files(), create() y delete() de carpeta no se redefinen: son de la base.

Las reglas

  • Un solo sitio habla con el servicio, y una sola función traduce sus errores a los de tai-storage. Esa traducción no puede fallar: un error que no reconoce sale igualmente como un TaiStorageError, con el estado y lo que dijo el servicio en details.
  • exists() y _fetch_info() solo dicen «no existe» ante un «no existe» definitivo. Un 401 o un corte de red lanzan.
  • Las fechas de FileInfo, en UTC con zona. El etag, algo que cambie cuando cambia el contenido.
  • Nada de pandas ni del SDK del servicio al importar el módulo del backend: se importa al construirlo, y si falta, el error dice qué extra instalar.
  • Cada operación documenta en su docstring cuántas peticiones hace.
  • Si el backend usa HTTP, se apoya en tai_storage._http.HttpTransport, que ya trae token, reintentos, tiempos de espera y logs.

La suite de contrato

Un backend está terminado cuando pasa la suite de contrato del repositorio (tests/contract/): la misma batería que pasan Local, SharePoint, Azure y Drive. Se añade una entrada a BACKENDS en tests/contract/conftest.py. Lo que el servicio no puede hacer se declara en Capabilities, y el test correspondiente se salta de forma explícita.

pip install -e ".[all,dev]"
pytest tests/contract -k mi_backend

Cómo está montada la librería por dentro, y qué no se debe introducir, está en las reglas del repositorio (.claude/rules/), que son para quien trabaja en tai-storage.