3.9 `traceback` --- Imprime ou récupère une trace de la pile

Ce module fournit une interface standard pour extraire, formater et imprimer des traces de la pile de programmes Python. Il reproduit exactement le comportement de l'interpréteur Python quand il imprime une trace de la pile. C'est utile quand vous voulez imprimer des traces de la pile sous le contrôle du programme, par exemple quand on ``encapsule'' l'interpréteur.

Le module utilise des objets trace - c'est le type d'objet qui est stocké dans les variables sys.exc_traceback et sys.last_traceback et retourné comme le troisième élément de sys.exc_info().

Le module définit les fonctions suivantes:

print_tb(trace[, limite[, fichier]])

Imprime jusqu'à limite entrées de la trace de la pile à partir de trace. Si limite est omise ou vaut None, toutes les entrées sont imprimées. Si fichier est omis ou vaut None, le résultat sort sur sys.stderr; sinon il doit s'agir d'un fichier ou d'un objet de type fichier qui recevra le résultat.

print_exception(type, valeur, trace[, limite[, fichier]])

Affiche des informations sur les exceptions et jusqu'à limiteentrées de trace de la pile depuis trace vers fichier. Ceci diffère de print_tb() de la façon suivante: (1) si trace n'est pas None, un en-tête "Traceback (innermost last):" est imprimé; (2) le type et la valeur de l'exception sont affichés après la trace de la pile; (3) si type a pour valeur SyntaxError et que valeur a le format approprié, la ligne où l'erreur de syntaxe est apparue est imprimée, avec un signe indiquant la position approximative de l'erreur.

print_exc([limite[, fichier]])

Raccourci pour `print_exception(sys.exc_type,sys.exc_value, sys.exc_traceback, limite,fichier)'. (En fait, la fonction se sert de sys.exc_info() pour récupérer la même information sans avoir à se préoccuper des threads.)

print_last([limite[, fichier]])

Raccourci pour `print_exception(sys.last_type,sys.last_value, sys.last_traceback, limite,fichier)'.

print_stack([f[, limite[, fichier]]])

Cette fonction imprime une trace de la pile depuis son point d'invocation. L'argument optionnel f peut être utilisé pour spécifier une autre pile à démarrer. Les arguments optionnels limite et fichier ont la même signification que dans print_exception().

extract_tb(trace[, limite])

Retourne une liste de jusqu'à limite entrées de trace de la pile ``pré-traitées'', extraites de l'objet trace trace. Cela peut être utile pour un formattage différent des traces de pile. Si limite est omis ou vaut None, toutes les entrées sont extraites. Une entrée de la trace de pile ``pré-traitée'' est un quadruplet (nomfichier, numero_ligne, nom_fonction, texte) représentant l'information qui est habituellement affichée pour une trace de pile. Le texte est une chaîne de caractères dont on a enlevé les espaces de début et de fin; si le code source n'est pas disponible il vaut None.

extract_stack([f[, limite]])

Extrait la trace brute depuis la trace courante. La valeur de retour a le même format que pour extract_tb(). Les arguments optionnels f et limite ont la même signification que pour print_stack().

format_list(liste)

A partir d'une liste de tuples retournés par extract_tb() ou extract_stack(), retourne une liste de chaînes de caractères prêtes à être imprimées. Chaque chaîne dans la liste résultat correspond à l'élément de même index dans la liste des arguments. Chaque chaîne se termine par un caractère de fin de ligne; les chaînes peuvent aussi contenir des caractères de fin de ligne internes, pour les items dont la ligne de texte source n'est pas None.

format_exception_only(type, valeur)

Formatte la partie exception d'une trace. Les arguments sont le type et la valeur d'exception tels qu'ils sont donnés par sys.last_type et sys.last_value. La valeur de retour est une liste de chaînes de caractères, chacune se terminant par un caractère de fin de ligne. Normalement, la liste comprend une seule chaîne; cependant, pour les exceptions SyntaxError, elle contient plusieurs lignes qui, quand on les affiche, donne des informations détaillées sur l'endroit où l'erreur de syntaxe s'est produite. Le message indiquant quelle exception s'est produite est toujours la dernière chaîne de la liste.

format_exception(type, valeur, tb[, limite])

Formatte une trace de la pile et l'information sur l'exception. Les arguments ont la même signification que les arguments correspondants de print_exception(). La valeur de retour est une liste de chaînes de caractères, chacune se terminant par un caractère de fin de ligne et certaines en contenant en interne. Quand ces lignes sont concaténées et imprimées, c'est exactement le même texte qui est imprimé qu'avec print_exception().

format_tb(tb[, limite])

Raccourci pour format_list(extract_tb(tb, limit)).

format_stack([f[, limite]])

Raccourci pour format_list(extract_stack(f, limite)).

tb_lineno(tb)

Cette fonction retourne le numéro de ligne courant dans l'objet trace. C'est normalement la même valeur que le champ tb.tb_lineno de l'objet, mais quand l'optimisation est utilisée (avec l'indicateur -O) ce champ n'est pas mis à jour correctement; cette fonction calcule la valeur correcte.

Sous-sections

Exemple de traceback