Error Handler

Le module ErrorHandler fournit un système centralisé pour la gestion et la traçabilité des erreurs dans l’application.

Usage

ErrorHandler est utilisé dans toute l’application pour garantir une gestion cohérente des exceptions.

Fonctionnalités

Fournit un décorateur @handle_errors pour une intégration simplifiée dans le code.
Catégorise les erreurs par type (Configuration, Réseau, LLM, etc.) et par niveau de gravité.
Enregistre les erreurs avec un contexte détaillé pour faciliter le débogage.
Suggère des solutions pour les erreurs courantes.

Modules

class src.smart_watch.core.ErrorHandler.ErrorSeverity(*values)[source]

Bases : Enum

Enumération représentant le niveau de gravité d’une erreur.

LOW

erreur mineure, le traitement peut continuer.

Type:: str

MEDIUM

erreur modérée, le traitement peut continuer avec une dégradation des fonctionnalités.

Type:: str

HIGH

erreur grave, il est recommandé d’arrêter le traitement.

Type:: str

CRITICAL

erreur critique, le traitement ne peut pas continuer.

Type:: str

LOW = 'low'

MEDIUM = 'medium'

HIGH = 'high'

CRITICAL = 'critical'

class src.smart_watch.core.ErrorHandler.ErrorCategory(*values)[source]

Bases : Enum

Enumération d’erreurs utilisées pour classifier les exceptions dans l’application.

CONFIGURATION

erreur liée à la configuration de l’application.

Type:: str

DATABASE

erreur en lien avec la base de données.

Type:: str

NETWORK

erreur de connexion ou de communication réseau.

Type:: str

LLM

erreur liée au modèle de langage (LLM).

Type:: str

FILE_IO

erreur lors des opérations d’entrée/sortie sur les fichiers.

Type:: str

VALIDATION

erreur de validation des données ou des paramètres.

Type:: str

CONVERSION

erreur lors de la conversion de données ou de formats.

Type:: str

PARSING

erreur lors de l’analyse ou du parsing de données.

Type:: str

EMAIL

erreur lors de l’envoi ou de la réception d’emails.

Type:: str

EMBEDDINGS

erreur lors de l’utilisation des embeddings.

Type:: str

UNKNOWN

erreur non catégorisée.

Type:: str

CONFIGURATION = 'configuration'

DATABASE = 'database'

NETWORK = 'network'

LLM = 'llm'

FILE_IO = 'file_io'

VALIDATION = 'validation'

CONVERSION = 'conversion'

PARSING = 'parsing'

EMAIL = 'email'

EMBEDDINGS = 'embeddings'

UNKNOWN = 'unknown'

class src.smart_watch.core.ErrorHandler.ErrorContext(module: str, function: str, operation: str, data: Dict[str, Any] | None = None, user_message: str | None = None)[source]

Bases : object

Classe représentant le contexte d’une erreur survenue dans l’application.

module

nom du module où l’erreur s’est produite.

Type:: str

function

nom de la fonction où l’erreur s’est produite.

Type:: str

operation

description de l’opération en cours lors de l’erreur.

Type:: str

data

données supplémentaires liées à l’erreur.

Type:: Optional[Dict[str, Any]]

user_message

message destiné à l’utilisateur concernant l’erreur.

Type:: Optional[str]

module: str

function: str

operation: str

data: Dict[str, Any] | None = None

user_message: str | None = None

__init__(module: str, function: str, operation: str, data: Dict[str, Any] | None = None, user_message: str | None = None) → None

class src.smart_watch.core.ErrorHandler.HandledError(category: ErrorCategory, severity: ErrorSeverity, exception: Exception, context: ErrorContext, timestamp: str, traceback: str, resolved: bool = False, solution_attempted: str | None = None)[source]

Bases : object

Classe représentant une erreur gérée.

category

catégorie de l’erreur.

Type:: ErrorCategory

severity

niveau de sévérité.

Type:: ErrorSeverity

exception

exception associée à l’erreur.

Type:: Exception

context

contexte dans lequel l’erreur s’est produite.

Type:: ErrorContext

timestamp

date et heure de l’occurrence de l’erreur.

Type:: str

traceback

trace complète de l’erreur.

Type:: str

resolved

indique si l’erreur a été résolue.

Type:: bool

solution_attempted

description de la solution tentée, si applicable.

Type:: Optional[str]

category: ErrorCategory

severity: ErrorSeverity

exception: Exception

context: ErrorContext

timestamp: str

traceback: str

resolved: bool = False

solution_attempted: str | None = None

__init__(category: ErrorCategory, severity: ErrorSeverity, exception: Exception, context: ErrorContext, timestamp: str, traceback: str, resolved: bool = False, solution_attempted: str | None = None) → None

class src.smart_watch.core.ErrorHandler.ErrorHandler[source]

Bases : object

Gestionnaire centralisé des erreurs.

__init__()[source]

Initialise le gestionnaire d’erreurs.

Ce constructeur configure le logger pour le module ErrorHandler, initialise le registre des erreurs traitées, et prépare les gestionnaires spécialisés pour chaque catégorie d’erreur.

logger: logger dédié au module ErrorHandler.

error_registry: liste des erreurs traitées par le gestionnaire.

category_handlers: dictionnaire associant chaque catégorie d’erreur à sa méthode de gestion spécialisée.

handle_error(exception: Exception, context: ErrorContext, severity: ErrorSeverity, category: ErrorCategory, reraise: bool = False, default_return: Any = None) → Any[source]

Traite une exception de manière centralisée, en enregistrant l’erreur, en la journalisant, et en appliquant un traitement spécialisé selon la catégorie et la gravité.

Peut relancer l’exception ou retourner une valeur par défaut.

Paramètres:

exception (Exception) – l’exception à traiter.
context (ErrorContext) – contexte additionnel lié à l’erreur.
severity (ErrorSeverity) – gravité de l’erreur.
category (ErrorCategory) – catégorie de l’erreur.
reraise (bool, optionnel) – si True, relance l’exception après traitement. Par défaut à False.
default_return (Any, optionnel) – valeur à retourner si aucun résultat n’est produit par le traitement spécialisé.

Renvoie:

résultat du traitement spécialisé, ou la valeur par défaut si aucun résultat n’est produit.

Type renvoyé:

Any

Lève:

Exception – relance l’exception d’origine si reraise est True.

_log_error(handled_error: HandledError)[source]

Enregistre une erreur gérée dans le système de logs avec différents niveaux de gravité.

Le traceback complet est géré par le décorateur pour éviter la duplication.

_apply_specialized_handling(handled_error: HandledError) → Any[source]

Applique un traitement spécialisé à une erreur gérée selon sa catégorie.

Cette méthode tente de récupérer un gestionnaire spécialisé pour la catégorie de l’erreur fournie. Si un gestionnaire est trouvé, il est exécuté avec l’erreur en paramètre. En cas d’exception lors de l’exécution du gestionnaire, une erreur est enregistrée dans le logger. Si aucun gestionnaire n’est disponible ou en cas d’échec, la méthode retourne None.

Paramètres:: handled_error (HandledError) – l’erreur à traiter, encapsulée dans un objet HandledError.
Renvoie:: le résultat du gestionnaire spécialisé si disponible et sans erreur, sinon None.
Type renvoyé:: Any

_handle_configuration_error(error: HandledError) → Any[source]

Gère les erreurs de configuration spécifiques et propose des solutions adaptées.

Cette méthode analyse l’exception contenue dans l’objet HandledError et, selon le type d’erreur (KeyError ou ValueError), elle renseigne une tentative de solution et suggère des actions correctives via le logger.

Paramètres:: error (HandledError) – l’objet d’erreur contenant l’exception à traiter.
Renvoie:: toujours None, cette méthode est utilisée pour ses effets de bord (journalisation et modification de l’objet d’erreur).
Type renvoyé:: Any

_handle_database_error(error: HandledError) → Any[source]

Gère les erreurs spécifiques liées à la base de données et propose des solutions.

Cette méthode analyse le message d’exception pour détecter des erreurs courantes telles que l’absence de table ou le verrouillage de la base de données. Elle consigne une solution adaptée dans le logger et met à jour l’attribut solution_attempted de l’objet d’erreur.

Paramètres:: error (HandledError) – l’objet représentant l’erreur interceptée, contenant l’exception et les informations associées.
Renvoie:: toujours None, cette méthode est utilisée pour ses effets de bord (journalisation et mise à jour de l’erreur).
Type renvoyé:: Any

_handle_network_error(error: HandledError) → Any[source]

Gère les erreurs liées au réseau en analysant le type d’exception et en proposant une solution.

Cette méthode vérifie si l’erreur est une erreur de connexion ou un timeout réseau, puis met à jour la tentative de solution dans l’objet HandledError et enregistre une suggestion dans le logger.

Paramètres:: error (HandledError) – l’objet contenant l’exception à traiter et les informations associées.
Renvoie:: toujours None, cette méthode ne retourne pas de valeur utile.
Type renvoyé:: Any

_handle_llm_error(error: HandledError) → Any[source]

Traite les erreurs liées au LLM et propose des solutions ou messages adaptés.

Paramètres:: error (HandledError) – l’erreur interceptée contenant l’exception à analyser.
Renvoie:: retourne un message d’erreur spécifique si un timeout est détecté, sinon None.
Type renvoyé:: Any

Notes

Modifie l’attribut solution_attempted de l’objet error selon le type d’erreur détecté.
Loggue une solution adaptée via le logger pour les erreurs de clé API ou de limite de taux.
Retourne un message d’erreur pour les timeouts afin de permettre la poursuite du traitement.

_handle_file_io_error(error: HandledError) → Any[source]

Gère les erreurs liées aux opérations d’entrée/sortie de fichiers.

Cette méthode analyse l’exception contenue dans l’objet HandledError et adapte le message de solution proposée selon le type d’erreur rencontré : - Si le fichier est introuvable (FileNotFoundError), elle précise le nom du fichier manquant. - Si les permissions sont insuffisantes (PermissionError), elle indique ce problème.

Paramètres:: error (HandledError) – l’objet contenant l’exception à traiter.
Renvoie:: toujours None, cette méthode modifie l’objet d’erreur en place.
Type renvoyé:: Any

_handle_parsing_error(error: HandledError) → Any[source]

Gère les erreurs de parsing des données d’entrée.

Cette méthode modifie l’attribut solution_attempted de l’erreur pour indiquer qu’une erreur de parsing a eu lieu, enregistre une information dans le logger pour suggérer de vérifier le format des données d’entrée, puis retourne None afin que la valeur par défaut définie par le décorateur soit utilisée.

Paramètres:: error (HandledError) – l’objet représentant l’erreur de parsing rencontrée.
Renvoie:: toujours None, pour permettre l’utilisation d’une valeur par défaut.
Type renvoyé:: Any

_handle_validation_error(error: HandledError) → Any[source]

Traite une erreur de validation et retourne une réponse structurée.

Cette méthode modifie l’attribut solution_attempted de l’objet error pour indiquer qu’une tentative de solution a été effectuée, puis retourne un dictionnaire contenant un message d’erreur et les détails de l’exception.

Paramètres:: error (HandledError) – l’objet représentant l’erreur de validation à traiter.
Renvoie:: un dictionnaire avec les clés “error” et “details” décrivant l’échec de la validation.
Type renvoyé:: Any

_handle_email_error(error: HandledError) → Any[source]

Traite les erreurs liées à l’envoi d’emails et propose une solution adaptée.

Cette méthode analyse le message d’exception associé à une erreur d’email, puis définit une tentative de solution en fonction du type d’erreur détectée (authentification ou connexion SMTP).

Paramètres:: error (HandledError) – l’objet représentant l’erreur à traiter, contenant l’exception d’origine.
Renvoie:: toujours None. La solution proposée est enregistrée dans l’attribut solution_attempted de l’objet error.
Type renvoyé:: Any

_handle_embeddings_error(error: HandledError) → Any[source]

Gère les erreurs spécifiques aux embeddings.

Paramètres:: error (HandledError) – l’objet d’erreur contenant l’exception à traiter.
Renvoie:: toujours None, cette méthode est utilisée pour ses effets de bord.
Type renvoyé:: Any

create_error_context(module: str, function: str, operation: str, data: Dict[str, Any] | None = None, user_message: str | None = None) → ErrorContext[source]

Crée un contexte d’erreur pour faciliter la gestion et le suivi des erreurs dans le module.

Paramètres:

module (str) – nom du module où l’erreur s’est produite.
function (str) – nom de la fonction concernée par l’erreur.
operation (str) – description de l’opération en cours lors de l’erreur.
data (Optional[Dict[str, Any]]) – données supplémentaires liées à l’erreur (par défaut None).
user_message (Optional[str]) – message destiné à l’utilisateur pour expliquer l’erreur (par défaut None).

Renvoie:

objet contenant toutes les informations contextuelles sur l’erreur.

Type renvoyé:

ErrorContext

get_error_summary() → Dict[str, Any][source]

Résume les erreurs enregistrées dans le registre d’erreurs.

Retourne un dictionnaire contenant le nombre total d’erreurs, la répartition par catégorie et par gravité, ainsi que les cinq dernières erreurs enregistrées avec leurs détails.

Renvoie:

Un dictionnaire avec les clés suivantes :

»total_errors » (int): Nombre total d’erreurs enregistrées.
»by_category » (dict): Répartition des erreurs par catégorie.
»by_severity » (dict): Répartition des erreurs par gravité.
»recent_errors » (list): Liste des cinq dernières erreurs, chacune sous forme de dictionnaire contenant :
- »category » (str): Catégorie de l’erreur.
- »severity » (str): Gravité de l’erreur.
- »exception » (str): Description de l’exception.
- »module » (str): Module où l’erreur s’est produite.
- »timestamp » (Any): Date et heure de l’erreur.

Type renvoyé:

Dict[str, Any]

clear_error_registry()[source]

Efface tous les enregistrements d’erreurs du registre interne.

Cette méthode vide le registre des erreurs, supprimant ainsi toutes les erreurs actuellement stockées. Elle peut être utilisée pour réinitialiser l’état des erreurs avant une nouvelle opération ou après un traitement.

Lève:: AttributeError – si le registre d’erreurs n’est pas initialisé correctement.

src.smart_watch.core.ErrorHandler.handle_errors(category: ErrorCategory, severity: ErrorSeverity, reraise: bool = False, default_return: Any = None, user_message: str | None = None)[source]

Décorateur pour gérer les erreurs lors de l’exécution d’une fonction, en utilisant un gestionnaire d’erreurs centralisé.

Ce décorateur intercepte les exceptions levées par la fonction décorée, crée un contexte d’erreur, et délègue le traitement au gestionnaire d’erreurs approprié. Il permet de personnaliser la catégorie et la sévérité de l’erreur, d’afficher un message utilisateur, et de choisir si l’exception doit être relancée ou non.

Le traceback complet est automatiquement capturé pour les erreurs de sévérité HIGH et CRITICAL.

Paramètres:

category (ErrorCategory) – catégorie de l’erreur à signaler.
severity (ErrorSeverity) – niveau de sévérité de l’erreur.
reraise (bool, optionnel) – si True, relance l’exception après traitement. Sinon, retourne default_return. Par défaut à False.
default_return (Any, optionnel) – valeur à retourner en cas d’erreur si reraise est False. Par défaut à None.
user_message (str, optionnel) – message personnalisé à afficher à l’utilisateur. Par défaut à None.

Renvoie:

Le décorateur appliqué à la fonction cible.

Type renvoyé:

Callable

src.smart_watch.core.ErrorHandler._get_global_error_handler() → ErrorHandler[source]

Retourne l’instance globale du gestionnaire d’erreurs.

Cette fonction vérifie si une instance globale de ErrorHandler existe déjà. Si ce n’est pas le cas, elle en crée une nouvelle et la retourne. Cela permet de garantir qu’une seule instance du gestionnaire d’erreurs est utilisée dans toute l’application.

Renvoie:: l’instance globale du gestionnaire d’erreurs.
Type renvoyé:: ErrorHandler

src.smart_watch.core.ErrorHandler.get_error_handler() → ErrorHandler[source]

Récupère l’instance globale du gestionnaire d’erreurs.

Cette fonction permet d’obtenir le gestionnaire d’erreurs utilisé globalement dans l’application. Elle est utile pour centraliser la gestion des exceptions et des erreurs.

Renvoie:: l’instance globale du gestionnaire d’erreurs.
Type renvoyé:: ErrorHandler