"traceback" --- Imprimir o recuperar un seguimiento de pila
***********************************************************

**Código fuente:** Lib/traceback.py

======================================================================

Este módulo brinda una interfaz estándar para extraer, formatear y
mostrar trazas de pilas de programas de Python. Dicho módulo copia el
comportamiento del intérprete de Python cuando muestra una traza de
pila. Es útil a la hora de querer mostrar trazas de pilas bajo el
control del programa, como si de un *wrapper* alrededor del intérprete
se tratara.

El módulo utiliza objetos *traceback* --- Este es el tipo de objeto
que se almacena en la variable "sys.last_traceback" y es retornada
como el tercer elemento de "sys.exc_info()".

El módulo define las siguientes funciones:

traceback.print_tb(tb, limit=None, file=None)

   Muestra hasta *limit* entradas de trazas de pila desde el objeto
   *traceback* *tb* (empezando desde el marco de la llamada) si
   *limit* es positivo. De lo contrario, muestra las últimas
   "abs(limit)" entradas. Si *limit* es omitido o "None", todas las
   entradas se muestran. Si *file* es omitido o "None", la salida va a
   "sys.stderr"; de lo contrario, debería ser un archivo o un objeto
   de tipo similar a un archivo para recibir la salida.

   Distinto en la versión 3.5: Soporte para *limit* negativo añadido

traceback.print_exception(etype, value, tb, limit=None, file=None, chain=True)

   Muestra información de excepciones y entradas de trazas de pila
   desde el objeto *traceback* *tb* a *file*. Esto difiere de
   "print_tb()" de las siguientes maneras:

   * si *tb* no es "None", muestra una cabecera "Traceback (most
     recent call last):"

   * muestra la excepción *etype* y *value* después de la traza de
     pila

   * si *type(value)* es "SyntaxError" y *value* tiene el formato
     apropiado, muestra la línea donde el error sintáctico ha ocurrido
     con un cursor indicando la posición aproximada del error.

   El argumento opcional *limit* tiene el mismo significado que para
   "print_tb()". Si *chain* es verdad (por defecto), entonces
   excepciones encadenadas ("__cause__" o "__context__" atributos de
   la excepción) también se imprimirán, como lo hace el propio
   intérprete al imprimir una excepción no controlada.

   Distinto en la versión 3.5: El argumento *etype* es ignorado e
   infiere desde el tipo de *value*.

traceback.print_exc(limit=None, file=None, chain=True)

   Esto es un atajo para "print_exception(*sys.exc_info(), limit,
   file, chain)".

traceback.print_last(limit=None, file=None, chain=True)

   Esto es un atajo para "print_exception(sys.last_type,
   sys.last_value, sys.last_traceback, limit, file, chain)". En
   general, solo funciona después de que una excepción ha alcanzado un
   *promt* interactivo (ver "sys.last_type").

traceback.print_stack(f=None, limit=None, file=None)

   Muestra hasta *limit* entradas de trazas de pila (empezando desde
   el punto de invocación) si *limit* es positivo. De lo contrario,
   muestra las últimas "abs(limit)" entradas. Si *limit* es omitido o
   "None", todas las entradas se muestran. El argumento opcional *f*
   puede ser usado para especificar un marco de pila alternativo para
   empezar. El argumento opcional *file* tiene el mismo significado
   que para "print_tb()".

   Distinto en la versión 3.5: Soporte para *limit* negativo añadido

traceback.extract_tb(tb, limit=None)

   Retorna un objeto "StackSummary" representando una lista de
   entradas de trazas de pila "pre-procesadas" extraídas del objeto
   *traceback* *tb*. Esto es útil para el formateo alternativo de
   trazas de pila. El argumento opcional *limit* tiene el mismo
   significado que para "print_tb()". Una entrada de traza de pila
   "pre-procesada" es un objeto "FrameSummary" que contiene los
   atributos "filename", "lineno", "name", y "line" representando la
   información que normalmente es mostrada por una traza de pila. El
   atributo "line" es una cadena con espacios en blanco iniciales y
   finales *stripped*; si la fuente no está disponible, es "None".

traceback.extract_stack(f=None, limit=None)

   Extrae el seguimiento de pila crudo desde el marco de pila actual.
   El valor retornado tiene el mismo formato que para "extract_tb()".
   Los argumentos opcionales *f* y *limit* tienen el mismo significado
   que para "print_stack()".

traceback.format_list(extracted_list)

   Dada una lista de tuplas u objetos "FrameSummary" según lo
   retornado por "extract_tb()" o "extract_stack()", retorna una lista
   de cadenas preparadas para ser mostradas. Cada cadena en la lista
   resultante corresponde con el elemento con el mismo índice en la
   lista de argumentos. Cada cadena finaliza en una nueva línea; las
   cadenas pueden contener nuevas líneas internas también, para
   aquellos elementos cuya línea de texto de origen no es "None".

traceback.format_exception_only(etype, value)

   Formatea la parte de excepción de un seguimiento de pila. Los
   argumentos son el tipo de excepción y el valor como los dados por
   "sys.last_type" y "sys.last_value". El valor retornado es una lista
   de cadenas, acabando cada una en una nueva línea. Normalmente, la
   lista contiene una sola cadena; sin embargo, para las excepciones
   "SyntaxError", esta lista contiene múltiples líneas que (cuando se
   muestran), imprimen información detallada sobre dónde ha ocurrido
   el error sintáctico. El mensaje indicador de qué excepción ha
   ocurrido es siempre la última cadena de la lista.

traceback.format_exception(etype, value, tb, limit=None, chain=True)

   Formatea una traza de pila y la información de la excepción. Los
   argumentos tienen el mismo significado que los argumentos
   correspondientes a "print_exception()". El valor retornado es una
   lista de cadenas, acabando cada una en una nueva línea y algunas
   contienen nuevas líneas internas. Cuando estas líneas son
   concatenadas y mostradas, exactamente el mismo texto es mostrado
   como hace "print_exception()".

   Distinto en la versión 3.5: El argumento *etype* es ignorado e
   infiere desde el tipo de *value*.

traceback.format_exc(limit=None, chain=True)

   Esto es como "print_exc(limit)" pero retorna una cadena en lugar de
   imprimirlo en un archivo.

traceback.format_tb(tb, limit=None)

   Un atajo para "format_list(extract_tb(tb, limit))".

traceback.format_stack(f=None, limit=None)

   Un atajo para "format_list(extract_stack(f, limit))".

traceback.clear_frames(tb)

   Limpia las variables locales de todos los marcos de pila en un
   seguimiento de pila *tb* llamando al método "clear()" de cada
   objeto de marco.

   Nuevo en la versión 3.4.

traceback.walk_stack(f)

   Recorre una pila siguiendo "f.f_back" desde el marco dado,
   produciendo el marco y el número de línea de cada marco. Si *f* es
   "None", la pila actual es usada. Este auxiliar es usado con
   "StackSummary.extract()".

   Nuevo en la versión 3.5.

traceback.walk_tb(tb)

   Recorre un seguimiento de pila siguiendo "tb_next" produciendo el
   marco y el número de línea de cada marco. Este auxiliar es usado
   con "StackSummary.extract()".

   Nuevo en la versión 3.5.

El módulo también define las siguientes clases:


Objetos "TracebackException"
============================

Nuevo en la versión 3.5.

Los objetos "TracebackException" son creados a partir de excepciones
reales para capturar datos para su posterior impresión de una manera
ligera.

class traceback.TracebackException(exc_type, exc_value, exc_traceback, *, limit=None, lookup_lines=True, capture_locals=False)

   Captura una excepción para su posterior procesado. *limit*,
   *lookup_lines* y *capture_locals* son como para la clase
   "StackSummary".

   Tenga en cuenta que cuando se capturan locales, también se muestran
   en el rastreo.

   __cause__

      Una clase "TracebackException" del original "__cause__".

   __context__

      Una clase "TracebackException" del original "__context__".

   __suppress_context__

      El valor "__suppress_context__" de la excepción original.

   stack

      Una clase "StackSummary" representando el seguimiento de pila.

   exc_type

      La clase del seguimiento de pila original.

   filename

      Para errores sintácticos - el nombre del archivo donde el error
      ha ocurrido.

   lineno

      Para errores sintácticos - el número de línea donde el error ha
      ocurrido.

   text

      Para errores sintácticos - el texto donde el error ha ocurrido.

   offset

      Para errores sintácticos - el *offset* en el texto donde el
      error ha ocurrido.

   msg

      Para errores sintácticos - el mensaje de error del compilador.

   classmethod from_exception(exc, *, limit=None, lookup_lines=True, capture_locals=False)

      Captura una excepción para su posterior procesado. *limit*,
      *lookup_lines* y *capture_locals* son como para la clase
      "StackSummary".

      Tenga en cuenta que cuando se capturan locales, también se
      muestran en el rastreo.

   format(*, chain=True)

      Formatea la excepción.

      Si *chain* no es "True", "__cause__" y "__context__" no serán
      formateados.

      El valor retornado es un generador de cadenas, donde cada una
      acaba en una nueva línea y algunas contienen nuevas líneas
      internas. "print_exception()" es un contenedor alrededor de este
      método que simplemente muestra las líneas de un archivo.

      El mensaje que indica qué excepción ocurrió siempre es la última
      cadena en la salida.

   format_exception_only()

      Formatea la parte de la excepción de un seguimiento de pila.

      El valor retornado es un generador de cadenas, donde cada una
      acaba en una nueva línea.

      Normalmente, el generador emite una sola cadena, sin embargo,
      para excepciones "SyntaxError", este emite múltiples líneas que
      (cuando son mostradas) imprimen información detallada sobre
      dónde ha ocurrido el error sintáctico.

      El mensaje que indica qué excepción ocurrió siempre es la última
      cadena en la salida.


Objetos "StackSummary"
======================

Nuevo en la versión 3.5.

Los objetos "StackSummary" representan una pila de llamadas lista para
formatear.

class traceback.StackSummary

   classmethod extract(frame_gen, *, limit=None, lookup_lines=True, capture_locals=False)

      Construye un objeto "StackSummary" desde un generador de marcos
      (tal como es retornado por "walk_stack()" o "walk_tb()").

      Si *limit* es suministrado, solo esta cantidad de cuadros son
      tomados de *frame_gen*. Si *lookup_lines* es "False", los objeto
      "FrameSummary" retornados aún no han leído sus líneas, lo que
      hace que el costo de crear "StackSummary" será más barato (lo
      que puede ser valioso si no se formatea). Si *capture_locals* es
      "True", las variables locales en cada "FrameSummary" son
      capturadas como representaciones de objetos.

   classmethod from_list(a_list)

      Construye un objeto "StackSummary" desde una lista suministrada
      de objetos "FrameSummary" o una lista antigua de tuplas. Cada
      tupa debe ser una 4-tupla con nombre de archivo, número de
      líneas, nombre, línea como los elementos.

   format()

      Retorna una lista de cadenas lista para mostrarse. Cada cadena
      en la lista resultante corresponde a un único marco de la pila.
      Cada cadena termina en una nueva línea;las cadenas también
      pueden contener nuevas líneas internas, para aquellos elementos
      con líneas de texto fuente.

      Para secuencias largas del mismo marco y línea, se muestran las
      primeras repeticiones, seguidas de una línea de resumen que
      indica el número exacto de repeticiones adicionales.

      Distinto en la versión 3.6: Las secuencias largas de cuadros
      repetidos ahora se abrevian.


Objetos "FrameSummary"
======================

Nuevo en la versión 3.5.

Los objetos "FrameSummary" representan un único marco en el
seguimiento de pila.

class traceback.FrameSummary(filename, lineno, name, lookup_line=True, locals=None, line=None)

   Representa un único marco en el seguimiento de pila o pila que es
   formateado o mostrado. Opcionalmente, puede tener una versión en
   cadena de los marcos locales incluidos en él. Si *lookup_line* es
   "False", el código fuente no se busca hasta que "FrameSummary"
   tenga el atributo "line" accedido (lo que también sucede cuando lo
   conviertes en una tupla). "line" puede proporcionarse directamente
   y evitará que se realicen búsquedas de línea. *locals* es un
   diccionario de variables locales opcional y, si se proporciona, las
   representaciones de variables se almacenan en el resumen para su
   posterior visualización.


Ejemplos de seguimiento de pila
===============================

Este ejemplo sencillo implementa un bucle de lectura, evaluación e
impresión básico, similar a (pero menos útil) el bucle del intérprete
interactivo estándar de Python. Para una implementación más completa
del bucle del intérprete, ir al módulo "code"

   import sys, traceback

   def run_user_code(envdir):
       source = input(">>> ")
       try:
           exec(source, envdir)
       except Exception:
           print("Exception in user code:")
           print("-"*60)
           traceback.print_exc(file=sys.stdout)
           print("-"*60)

   envdir = {}
   while True:
       run_user_code(envdir)

El siguiente ejemplo demuestra las diferentes manera para mostrar y
formatear la excepción y el seguimiento de pila:

   import sys, traceback

   def lumberjack():
       bright_side_of_death()

   def bright_side_of_death():
       return tuple()[0]

   try:
       lumberjack()
   except IndexError:
       exc_type, exc_value, exc_traceback = sys.exc_info()
       print("*** print_tb:")
       traceback.print_tb(exc_traceback, limit=1, file=sys.stdout)
       print("*** print_exception:")
       # exc_type below is ignored on 3.5 and later
       traceback.print_exception(exc_type, exc_value, exc_traceback,
                                 limit=2, file=sys.stdout)
       print("*** print_exc:")
       traceback.print_exc(limit=2, file=sys.stdout)
       print("*** format_exc, first and last line:")
       formatted_lines = traceback.format_exc().splitlines()
       print(formatted_lines[0])
       print(formatted_lines[-1])
       print("*** format_exception:")
       # exc_type below is ignored on 3.5 and later
       print(repr(traceback.format_exception(exc_type, exc_value,
                                             exc_traceback)))
       print("*** extract_tb:")
       print(repr(traceback.extract_tb(exc_traceback)))
       print("*** format_tb:")
       print(repr(traceback.format_tb(exc_traceback)))
       print("*** tb_lineno:", exc_traceback.tb_lineno)

La salida para el ejemplo podría ser similar a esto:

   *** print_tb:
     File "<doctest...>", line 10, in <module>
       lumberjack()
   *** print_exception:
   Traceback (most recent call last):
     File "<doctest...>", line 10, in <module>
       lumberjack()
     File "<doctest...>", line 4, in lumberjack
       bright_side_of_death()
   IndexError: tuple index out of range
   *** print_exc:
   Traceback (most recent call last):
     File "<doctest...>", line 10, in <module>
       lumberjack()
     File "<doctest...>", line 4, in lumberjack
       bright_side_of_death()
   IndexError: tuple index out of range
   *** format_exc, first and last line:
   Traceback (most recent call last):
   IndexError: tuple index out of range
   *** format_exception:
   ['Traceback (most recent call last):\n',
    '  File "<doctest...>", line 10, in <module>\n    lumberjack()\n',
    '  File "<doctest...>", line 4, in lumberjack\n    bright_side_of_death()\n',
    '  File "<doctest...>", line 7, in bright_side_of_death\n    return tuple()[0]\n',
    'IndexError: tuple index out of range\n']
   *** extract_tb:
   [<FrameSummary file <doctest...>, line 10 in <module>>,
    <FrameSummary file <doctest...>, line 4 in lumberjack>,
    <FrameSummary file <doctest...>, line 7 in bright_side_of_death>]
   *** format_tb:
   ['  File "<doctest...>", line 10, in <module>\n    lumberjack()\n',
    '  File "<doctest...>", line 4, in lumberjack\n    bright_side_of_death()\n',
    '  File "<doctest...>", line 7, in bright_side_of_death\n    return tuple()[0]\n']
   *** tb_lineno: 10

El siguiente ejemplo muestra las diferentes maneras de imprimir y
formatear la pila:

   >>> import traceback
   >>> def another_function():
   ...     lumberstack()
   ...
   >>> def lumberstack():
   ...     traceback.print_stack()
   ...     print(repr(traceback.extract_stack()))
   ...     print(repr(traceback.format_stack()))
   ...
   >>> another_function()
     File "<doctest>", line 10, in <module>
       another_function()
     File "<doctest>", line 3, in another_function
       lumberstack()
     File "<doctest>", line 6, in lumberstack
       traceback.print_stack()
   [('<doctest>', 10, '<module>', 'another_function()'),
    ('<doctest>', 3, 'another_function', 'lumberstack()'),
    ('<doctest>', 7, 'lumberstack', 'print(repr(traceback.extract_stack()))')]
   ['  File "<doctest>", line 10, in <module>\n    another_function()\n',
    '  File "<doctest>", line 3, in another_function\n    lumberstack()\n',
    '  File "<doctest>", line 8, in lumberstack\n    print(repr(traceback.format_stack()))\n']

Este último ejemplo demuestra las últimas funciones de formateo:

   >>> import traceback
   >>> traceback.format_list([('spam.py', 3, '<module>', 'spam.eggs()'),
   ...                        ('eggs.py', 42, 'eggs', 'return "bacon"')])
   ['  File "spam.py", line 3, in <module>\n    spam.eggs()\n',
    '  File "eggs.py", line 42, in eggs\n    return "bacon"\n']
   >>> an_error = IndexError('tuple index out of range')
   >>> traceback.format_exception_only(type(an_error), an_error)
   ['IndexError: tuple index out of range\n']
