Errores¶
Toda operación devuelve lo que promete o lanza un TaiStorageError, con lo que ha pasado y
lo que hay que hacer:
from tai_storage import FileNotFoundError, TaiStorageError
try:
origin.get_file("entrada/ventas.xlsx").read()
except FileNotFoundError as error:
print(error) # No existe el fichero 'entrada/ventas.xlsx' de … Solución: Comprueba la ruta y el nombre (con su extensión)
error.message # qué ha pasado
error.solution # qué hacer: siempre está
error.details # datos para diagnosticar (la ruta, lo que dijo el servicio); nunca secretos
error.code # ErrorCode.NOT_FOUND: estable, para decidir sin mirar el texto
Si un error no trae solución, o lo que sale es una traza de Python sin un TaiStorageError,
es un fallo de la librería: repórtalo.
Las familias¶
| Excepción | code |
Cuándo |
|---|---|---|
ConfigurationError |
CONFIGURATION |
Falta una credencial o una variable, o no es válida (un sitio que no existe, una biblioteca que no está) |
AuthenticationError |
AUTHENTICATION |
El servicio rechaza las credenciales |
PermissionDeniedError |
PERMISSION_DENIED |
Autenticado, pero sin permiso para esa operación |
NotFoundError → FileNotFoundError, FolderNotFoundError |
NOT_FOUND |
No existe |
AlreadyExistsError → FileAlreadyExistsError, FolderAlreadyExistsError |
ALREADY_EXISTS |
Ya existe y no se pidió overwrite=True |
FolderNotEmptyError |
FOLDER_NOT_EMPTY |
Borrar una carpeta con contenido sin recursive=True |
InvalidPathError |
INVALID_PATH |
La ruta sale del origen (..) o está mal formada |
InvalidRequestError |
INVALID_REQUEST |
Un argumento que no vale, o el servicio rechaza la petición (un nombre no permitido, un patrón mal escrito) |
ConflictError |
CONFLICT |
El servicio es ambiguo o está ocupado: dos ficheros con el mismo nombre en Drive, un fichero bloqueado, una copia que no coincide |
StorageUnavailableError |
UNAVAILABLE |
Red, DNS, TLS, tiempo de espera, 5xx o 429 después de agotar los reintentos |
OperationNotSupportedError |
NOT_SUPPORTED |
El backend no puede hacerlo (leer un documento nativo de Google) |
DataError → DataFormatError, MissingColumnsError, ColumnTypeError |
INVALID_DATA |
Un fichero no se puede leer como tabla sin perder algo (ver DataFrames) |
También son las de Python¶
Cuatro heredan además de la excepción equivalente de Python, así que un except de Python
también las captura:
| tai-storage | Python |
|---|---|
FileNotFoundError |
FileNotFoundError |
FileAlreadyExistsError |
FileExistsError |
PermissionDeniedError |
PermissionError |
InvalidPathError |
ValueError |
En la 0.1 se llamaban igual que las de Python pero no heredaban de ellas, y un except
FileNotFoundError sin importar el de tai-storage no las capturaba.
En un pipeline¶
from tai_storage import (
AuthenticationError, ConfigurationError, FileNotFoundError, StorageUnavailableError, TaiStorageError,
)
try:
procesar(origin)
except (ConfigurationError, AuthenticationError):
raise # no tiene sentido reintentar: hay que arreglar la configuración
except StorageUnavailableError:
reprogramar_en_10_minutos() # la librería ya ha reintentado lo razonable
except FileNotFoundError as error:
avisar(f"No ha llegado el fichero del cliente: {error.message}")
except TaiStorageError as error:
avisar(str(error)) # mensaje + solución, listo para un aviso
Lo que la librería ya reintenta¶
Antes de lanzar StorageUnavailableError, SharePoint y Drive reintentan hasta 5 veces:
- los 429 y los 5xx, con espera exponencial, o la que diga
Retry-After; - los cortes de red, solo en las operaciones que se pueden repetir sin efectos (leer, listar);
- el 403 por límite de peticiones de Drive.
Un 401 pide un token nuevo una vez. Si el token nuevo también es rechazado, es
AuthenticationError. Cada reintento queda en el log en WARNING. Azure usa los reintentos de su
SDK.
Los más habituales¶
ConfigurationError: Falta … Solución: Pásalo como argumento o define X=… en el entorno …
La variable X no está en el entorno del proceso. tai-storage no carga ficheros .env
por su cuenta: si los usas, cárgalos antes de crear el origen.
FileAlreadyExistsError al subir
upload_file(), copy_to() y move_to() no sobrescriben sin overwrite=True. write() sí
sobrescribe por defecto.
InvalidPathError: La ruta '…' sale del origen con '..'
Las rutas son relativas a la raíz del origen y no pueden subir por encima de ella. Para leer de otra raíz, crea otro origen.
ConflictError en Google Drive
Hay dos elementos con el mismo nombre en esa carpeta y la ruta es ambigua. Renombra uno, o
léelo desde un list_files(), donde cada fichero lleva su id.
PermissionDeniedError: … storageQuotaExceeded
Una cuenta de servicio de Google no tiene cuota en «Mi unidad». La raíz tiene que estar en una unidad compartida: ver Google Drive.
Nombres de la 0.1¶
Siguen existiendo como alias, para no romper a quien los importa:
| 0.1 | Es ahora |
|---|---|
SecretNotFoundError |
ConfigurationError |
OriginConnectionError |
StorageUnavailableError |
OriginNotConnectedError |
ConfigurationError (las operaciones conectan solas) |
PermissionError (de tai-storage) |
PermissionDeniedError |