altametris.sara.core.exceptions¶

Custom exceptions for Altametris libraries.

Provides a hierarchy of exceptions for different error scenarios: - AltametrisException: Base exception - ModelError: Model-related errors (loading, architecture, weights) - TrainingError: Training-related errors (dataset, convergence, OOM) - InferenceError: Inference-related errors (input format, device) - ExportError: Export-related errors (format, validation) - ConfigurationError: Configuration-related errors (invalid parameters)

Exceptions¶

`AltametrisException`	Base exception for all Altametris libraries.
`ModelError`	Exception raised for model-related errors.
`TrainingError`	Exception raised for training-related errors.
`InferenceError`	Exception raised for inference-related errors.
`ExportError`	Exception raised for export-related errors.
`ConfigurationError`	Exception raised for configuration-related errors.
`AzureError`	Exception de base pour toutes les erreurs liées à Azure.
`WeightsNotFoundError`	Exception levée lorsqu'un fichier de poids demandé n'existe pas.
`AzureAuthenticationError`	Exception levée lors d'un échec d'authentification Azure.
`AzureDownloadError`	Exception levée lors d'un échec de téléchargement depuis Azure.

Functions¶

validate_param(→ None)

Validate a parameter and raise ConfigurationError if invalid.

Module Contents¶

exception altametris.sara.core.exceptions.AltametrisException(message: str, details: dict[str, Any] | None = None)¶

Bases: Exception

Base exception for all Altametris libraries.

All custom exceptions inherit from this base class to allow catching all Altametris-specific errors with a single except clause.

Parameters:

message – Error message describing what went wrong
details – Optional dictionary with additional error context

Example

>>> try:
...     raise AltametrisException("Something went wrong", {"code": 500})
... except AltametrisException as e:
...     print(e)
...     print(e.details)

message¶

details¶

exception altametris.sara.core.exceptions.ModelError(message: str, details: dict[str, Any] | None = None)¶

Bases: AltametrisException

Exception raised for model-related errors.

Scenarios: - Failed to load model weights - Invalid model architecture - Corrupted checkpoint file - Incompatible model version - Missing required model files

Example

>>> raise ModelError(
...     "Failed to load weights",
...     {"path": "model.pt", "reason": "File not found"}
... )

exception altametris.sara.core.exceptions.TrainingError(message: str, details: dict[str, Any] | None = None)¶

Bases: AltametrisException

Exception raised for training-related errors.

Scenarios: - Dataset not found or invalid format - Training divergence (NaN loss) - Out of memory during training - Invalid hyperparameters - Checkpoint save failure

Example

>>> raise TrainingError(
...     "Training diverged",
...     {"epoch": 10, "loss": float('nan'), "lr": 0.001}
... )

exception altametris.sara.core.exceptions.InferenceError(message: str, details: dict[str, Any] | None = None)¶

Bases: AltametrisException

Exception raised for inference-related errors.

Scenarios: - Invalid input format (wrong shape, type) - Device mismatch (model on CUDA, input on CPU) - Prediction failure - Post-processing error - Batch size too large for memory

Example

>>> raise InferenceError(
...     "Invalid input shape",
...     {"expected": (3, 640, 640), "got": (640, 640)}
... )

exception altametris.sara.core.exceptions.ExportError(message: str, details: dict[str, Any] | None = None)¶

Bases: AltametrisException

Exception raised for export-related errors.

Scenarios: - Unsupported export format - Export validation failed - Missing export dependencies (onnx, tensorrt) - Dynamic shapes not supported - Export optimization failed

Example

>>> raise ExportError(
...     "ONNX export failed",
...     {"format": "onnx", "reason": "Dynamic axes not supported"}
... )

exception altametris.sara.core.exceptions.ConfigurationError(message: str, details: dict[str, Any] | None = None)¶

Bases: AltametrisException

Exception raised for configuration-related errors.

Scenarios: - Invalid configuration parameter - Missing required configuration key - Configuration validation failed - Incompatible configuration values - Invalid YAML/JSON format

Example

>>> raise ConfigurationError(
...     "Invalid batch_size",
...     {"parameter": "batch_size", "value": -1, "expected": "> 0"}
... )

exception altametris.sara.core.exceptions.AzureError(message: str, details: dict[str, Any] | None = None)¶

Bases: AltametrisException

Exception de base pour toutes les erreurs liées à Azure.

Cette exception sert de classe de base pour toutes les erreurs spécifiques à Azure (authentification, téléchargement, blob storage). Permet de capturer toutes les erreurs Azure avec une seule clause except.

Scénarios: - Erreurs génériques Azure non catégorisées - Problèmes de configuration Azure - Timeouts ou erreurs réseau Azure - Erreurs de service Azure non spécifiques

Parameters:

message – Message d’erreur décrivant le problème
details – Dictionnaire optionnel avec le contexte additionnel (storage_account, container, weight_path, etc.)

Example

>>> raise AzureError(
...     "Erreur de connexion à Azure",
...     {"storage_account": "myaccount", "error_code": "NetworkError"}
... )

exception altametris.sara.core.exceptions.WeightsNotFoundError(message: str, details: dict[str, Any] | None = None)¶

Bases: AzureError

Exception levée lorsqu’un fichier de poids demandé n’existe pas.

Cette exception est levée lorsqu’un fichier de poids (weights) demandé n’est pas trouvé dans le stockage (Azure Blob Storage, local, etc.).

Scénarios: - Le fichier de poids demandé n’existe pas dans le conteneur/répertoire - Le chemin du fichier est incorrect ou mal formaté - Le conteneur/répertoire spécifié n’existe pas - Permissions insuffisantes pour accéder au fichier

Parameters:

message – Message d’erreur décrivant le fichier manquant
details – Dictionnaire avec contexte (container, weight_path, storage_account)

Example

>>> raise WeightsNotFoundError(
...     "Weights file 'models/yolo11x.pt' not found",
...     {
...         "container": "models",
...         "weight_path": "yolo11x.pt",
...         "storage_account": "myaccount",
...         "suggestion": "Use list_weights() to see available files"
...     }
... )

exception altametris.sara.core.exceptions.AzureAuthenticationError(message: str, details: dict[str, Any] | None = None)¶

Bases: AzureError

Exception levée lors d’un échec d’authentification Azure.

Cette exception est levée lorsque l’authentification avec Azure échoue, que ce soit avec Managed Identity, Connection String ou SAS Token.

Scénarios: - Managed Identity non configurée ou inactive - Connection String invalide ou expirée - SAS Token expiré ou révoqué - Permissions insuffisantes sur le storage account - Variables d’environnement manquantes ou incorrectes

Parameters:

message – Message d’erreur décrivant le problème d’authentification
details – Dictionnaire avec contexte (auth_method, storage_account, error_details)

Example

>>> raise AzureAuthenticationError(
...     "Échec d'authentification avec Managed Identity",
...     {
...         "auth_method": "managed_identity",
...         "storage_account": "myaccount",
...         "suggestion": "Vérifiez que Managed Identity est activée sur la ressource Azure"
...     }
... )

exception altametris.sara.core.exceptions.AzureDownloadError(message: str, details: dict[str, Any] | None = None)¶

Bases: AzureError

Exception levée lors d’un échec de téléchargement depuis Azure.

Cette exception est levée lorsque le téléchargement d’un fichier de poids depuis Azure Blob Storage échoue pour des raisons autres que l’authentification ou le le fichier de poids inexistant.

Scénarios: - Timeout réseau pendant le téléchargement - Espace disque insuffisant pour le cache local - Corruption de données pendant le transfert - Interruption de connexion réseau - Échec d’écriture dans le répertoire cache

Parameters:

message – Message d’erreur décrivant l’échec du téléchargement
details – Dictionnaire avec contexte (weight_path, bytes_downloaded, error_type)

Example

>>> raise AzureDownloadError(
...     "Timeout lors du téléchargement du fichier de poids",
...     {
...         "weight_path": "models/yolo11x.pt",
...         "bytes_downloaded": 1048576,
...         "total_size": 104857600,
...         "error_type": "NetworkTimeout",
...         "suggestion": "Vérifiez votre connexion réseau et réessayez"
...     }
... )

altametris.sara.core.exceptions.validate_param(condition: bool, param_name: str, value: Any, expected: str) → None¶

Validate a parameter and raise ConfigurationError if invalid.

Parameters:

condition – Condition that must be True (if False, raises exception)
param_name – Name of the parameter being validated
value – Current value of the parameter
expected – Description of expected value

Raises:

ConfigurationError – If condition is False

Example

>>> validate_param(batch_size > 0, "batch_size", batch_size, "> 0")
>>> validate_param(device in ["cpu", "cuda"], "device", device, "cpu or cuda")