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.
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 endetails. 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. Eletag, 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.
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.