Excepciones incorporadas¶
En Python, todas las excepciones deben ser instancias de una clase que se derive de BaseException
. En una instrucción try
con una cláusula except
que menciona una clase determinada, esa cláusula también controla las clases de excepción derivadas de esa clase (excepto las clases de excepción de las que se deriva it). Dos clases de excepción que no están relacionadas mediante subclases nunca son equivalentes, incluso si tienen el mismo nombre.
Las excepciones predefinidas enumeradas a continuación pueden ser generadas por el intérprete o funciones predefinidas. Excepto donde se mencione lo contrario, tienen un associated value que indica la causa detallada del error. Esto podría una cadena de caracteres o una tupla elementos con grandes elementos de información (por ejemplo, un código de error y una cadena que explica el código). El valor asociado generalmente se pasa como argumentos al constructor de la clase de excepción.
El código de usuario puede generar excepciones predefinidas. Esto puede ser usado para probar un gestor de excepciones o para notificar una condición de error «igual» a la situación en la cual el intérprete lance la misma excepción; pero tenga en cuenta que no hay nada que impida que el código del usuario produzca un error inapropiado.
Las clases de excepción predefinidas pueden ser usadas como subclases para definir otras nuevas; se recomienda a los programadores que deriven nuevas excepciones a partir de la clase Exception
o de una de sus subclases, y no de BaseException
. Hay disponible más información sobre la definición de excepciones en el Tutorial de Python en Excepciones definidas por el usuario.
Al lanzar (o relanzar) una excepción en una clausula except
o finally
clausula __context__
se establece automáticamente en la ultima excepción detectada; si no se controla la nueva excepción, el seguimiento que finalmente se muestra como resultado incluirá las excepciones de origen y la excepción final.
When raising a new exception (rather than using a bare raise
to re-raise
the exception currently being handled), the implicit exception context can be
supplemented with an explicit cause by using from
with
raise
:
raise new_exc from original_exc
The expression following from
must be an exception or None
. It
will be set as __cause__
on the raised exception. Setting
__cause__
also implicitly sets the __suppress_context__
attribute to True
, so that using raise new_exc from None
effectively replaces the old exception with the new one for display
purposes (e.g. converting KeyError
to AttributeError
), while
leaving the old exception available in __context__
for introspection
when debugging.
La visualización por defecto de la traza de error muestra estas excepciones encadenadas además de la traza de la propia excepción. Siempre se muestra una excepción encadenada explícitamente en __cause__
cuando está presente. Una excepción implícitamente encadenada en __context__
solo se muestra si __cause__
es None
y __suppress_context__
es falso.
En cualquier caso, la excepción en sí siempre se muestra después de cualquier excepción encadenada para que la línea final del seguimiento siempre muestre la última excepción que se generó.
Clases base¶
Las siguientes excepciones se utilizan principalmente como clases base para otras excepciones.
-
exception
BaseException
¶ La clase base para todas las excepciones predefinidas. No está pensada para ser heredada directamente por las clases definidas por el usuario (para eso, use
Exception
). Si se llama astr()
en una instancia de esta clase, se retorna la representación de los argumentos de la instancia o la cadena vacía cuando no había argumentos.-
args
¶ La tupla de argumentos dada al constructor de excepción. Algunas excepciones predefinidas (como
OSError
) esperan un cierto número de argumentos y asignan un significado especial a los elementos de esta tupla, mientras que otras normalmente se llaman solo con una sola cadena que da un mensaje de error.
-
with_traceback
(tb)¶ Este método establece
tb
como el nuevotraceback
para la excepción y retorna el objeto de excepción. Normalmente se utiliza en código de control de excepciones como este:try: ... except SomeException: tb = sys.exc_info()[2] raise OtherException(...).with_traceback(tb)
-
-
exception
Exception
¶ Todas las excepciones predefinidas non-system-exiting, que no salen del sistema se derivan de esta clase. Todas las excepciones definidas por el usuario también deben derivarse de esta clase.
-
exception
ArithmeticError
¶ La clase base para las excepciones predefinidas que se generan para varios errores aritméticos:
OverflowError
,ZeroDivisionError
,FloatingPointError
.
-
exception
LookupError
¶ La clase base para las excepciones que se generan cuando una clave o índice utilizado en un mapa o secuencia que no es válido:
IndexError
,KeyError
. Esto se puede generar directamente porcodecs.lookup()
.
Excepciones específicas¶
Las siguientes excepciones son las excepciones que normalmente se generan.
-
exception
AttributeError
¶ Se genera cuando se produce un error en una referencia de atributo (ver Referencias de atributos) o la asignación falla. (Cuando un objeto no admite referencias de atributos o asignaciones de atributos en absoluto, se genera
TypeError
.)
-
exception
EOFError
¶ Se genera cuando la función
input()
alcanza una condición de fin de archivo (EOF) sin leer ningún dato. (Note que elio. IOBase.read()
yio.IOBase.readline()
retornan una cadena vacía cuando llegan a EOF.)
-
exception
FloatingPointError
¶ No se usa actualmente.
-
exception
GeneratorExit
¶ Se genera cuando un generator o coroutine está cerrado; ver
generator.close()
ycoroutine.close()
. Hereda directamente deBaseException
en lugar deException
ya que técnicamente no es un error.
-
exception
ImportError
¶ Se genera cuando la instrucción
import
tiene problemas al intentar cargar un módulo. También se produce cuando la from list enfrom ... import
tiene un nombre que no se puede encontrar.Los atributos
name
ypath
solo se pueden establecer utilizando argumentos de palabra clave en el constructor. Cuando se establece, representan el nombre del módulo que se intentó importar y la ruta de acceso a cualquier archivo que desencadenó la excepción, respectivamente.Distinto en la versión 3.3: Se han añadido los atributos
name
ypath
.
-
exception
ModuleNotFoundError
¶ Una subclase de
ImportError
que se genera medianteimport
cuando no se pudo encontrar un módulo. También se genera cuandoNone
se encuentra ensys.modules
.Nuevo en la versión 3.6.
-
exception
IndexError
¶ Se genera cuando un subíndice de secuencia está fuera del rango. (Los índices de la rebanada son truncados silenciosamente para caer en el intervalo permitido; si un índice no es un entero, se genera
TypeError
.)
-
exception
KeyError
¶ Se genera cuando no se encuentra una clave de asignación (diccionario) en el conjunto de claves existentes (mapa).
-
exception
KeyboardInterrupt
¶ Se genera cuando el usuario pulsa la tecla de interrupción (normalmente Control-C o Delete). Durante la ejecución, se realiza una comprobación de interrupciones con regularidad. La excepción hereda de
BaseException
para no ser detectada de forma accidental porException
y, por lo tanto, prevenir que el intérprete salga.
-
exception
MemoryError
¶ Se genera cuando una operación se queda sin memoria pero la situación aún puede ser recuperada (eliminando algunos objetos). El valor asociado es una cadena que indica que tipo de operación (interna) se quedó sin memoria. Tenga en cuenta que debido a la arquitectura de administración de memoria (función
malloc()
de C), el intérprete no siempre puede recuperarse completamente de esta situación; sin embargo, plantea una excepción para que se pueda imprimir un seguimiento de la pila, en caso de que un programa fuera de servicio fuera lo causa.
-
exception
NameError
¶ Se genera cuando no se encuentra un nombre local o global. Esto se aplica solo a nombres no calificados. El valor asociado es un mensaje de error que incluye el nombre que no se pudo encontrar.
-
exception
NotImplementedError
¶ Esta excepción se deriva de
RuntimeError
. En las clases base definidas por el usuario, los métodos abstractos deberían generar esta excepción cuando requieren clases derivadas para anular el método, o mientras se desarrolla la clase para indicar que la implementación real aún necesita ser agregada.Nota
No debe usarse para indicar que un operador o método no debe ser admitido en absoluto – en ese caso, deje el operador / método sin definir o, si es una subclase, se establece en
None
.Nota
NotImplementedError
yNotImplemented
no son intercambiables, a pesar de que tienen nombres y propósitos similares. ConsulteNotImplemented
para obtener detalles sobre cuándo usarlo.
-
exception
OSError
([arg])¶ -
exception
OSError
(errno, strerror[, filename[, winerror[, filename2]]]) Esta excepción se produce cuando una función del sistema retorna un error relacionado con el sistema, que incluye fallas de E/S como
file not found
odisk full
(no para tipos de argumentos ilegales u otros errores incidentales).La segunda forma del constructor establece los atributos correspondientes, que se describen a continuación. Los atributos predeterminados son
None
si no se especificam. Para compatibilidad con versiones anteriores, si se pasan tres argumentos, el atributoargs
contiene solo una tupla de 2 de los dos primeros argumentos del constructor.El constructor a menudo retorna una subclase de
OSError
, como se describe en OS exceptions a continuación. La subclase particular depende del valor finalerrno
. Este comportamiento solo ocurre cuando se construyeOSError
directamente o mediante un alias, y no se hereda al derivar.-
errno
¶ Un código de error numérico de la variable C,
errno
.
-
winerror
¶ En Windows, esto le proporciona el código de error nativo de Windows. El atributo
errno
es entonces una traducción aproximada, en términos POSIX, de ese código de error nativo.En Windows, si el argumento del constructor
winerror
es un entero, el atributoerrno
se determina a partir del código de error de Windows y el argumentoerrno
se ignora. En otras plataformas, el argumentowinerror
se ignora y el atributowinerror
no existe.
-
strerror
¶ El mensaje de error correspondiente, tal como lo proporciona el sistema operativo. Está formateado por las funciones de C,
perror()
en POSIX, yFormatMessage()
en Windows.
-
filename
¶ -
filename2
¶ Para las excepciones que involucran una ruta del sistema de archivos (como
open()
oos.unlink()
),filename
es el nombre del archivo pasado a la función. Para las funciones que involucran dos rutas del sistema de archivos (comoos.rename()
),filename2
corresponde al segundo nombre de archivo pasado a la función.
Distinto en la versión 3.3:
EnvironmentError
,IOError
,WindowsError
,socket.error
,select.error
ymmap.error
se han fusionado enOSError
, y el constructor puede retornar una subclase.Distinto en la versión 3.4: El atributo
filename
es ahora el nombre del archivo original pasado a la función, en lugar del nombre codificado o descodificado de la codificación del sistema de archivos. Además, se agregó el argumento constructorfilename2
y el atributo.-
-
exception
OverflowError
¶ Se genera cuando el resultado de una operación aritmética es demasiado grande para ser representado. Esto no puede ocurrir para los enteros (para lo cual es mejor elevar
MemoryError
que darse por vencido). Sin embargo, por razones históricas,OverflowError
a veces se genera para enteros que están fuera del rango requerido. Debido a la falta de estandarización del manejo de excepciones de coma flotante en C, la mayoría de las operaciones de coma flotante no se verifican.
-
exception
RecursionError
¶ Esta excepción se deriva de
RuntimeError
. Se eleva cuando el intérprete detecta que se excede la profundidad máxima de recursión (versys.getrecursionlimit()
).Nuevo en la versión 3.5: Anteriormente, se planteó un simple
RuntimeError
.
-
exception
ReferenceError
¶ Esta excepción se produce cuando un proxy de referencia débil, creado por la función
weakref.proxy()
, se utiliza para acceder a un atributo del referente después de que se ha recolectado basura. Para obtener más información sobre referencias débiles, consulte el móduloweakref
.
-
exception
RuntimeError
¶ Se genera cuando se detecta un error que no corresponde a ninguna de las otras categorías. El valor asociado es una cadena que indica exactamente qué salió mal.
-
exception
StopIteration
¶ Generado por la función incorporada
next()
y un iterator’s__next__()
para indicar que no hay más elementos producidos por el iterador.El objeto de excepción tiene un solo atributo
value
, que se proporciona como argumento al construir la excepción, y por defecto esNone
.Cuando se retorna una función generator o coroutine, se genera una nueva instancia
StopIteration
, y el valor retornado por la función se utiliza como parámetrovalue
para constructor de la excepción.Si un generador lanza directa o indirectamente
StopIteration
, se convierte enRuntimeError
(conservandoStopIteration
como la causa de la nueva excepción).Distinto en la versión 3.3: Se agregó el atributo *value* y la capacidad de las funciones del generador de usarlo para retornar un valor.
Distinto en la versión 3.5: Introdujo la transformación RuntimeError a través de
from __future__ import generator_stop
, ver PEP 479.Distinto en la versión 3.7: Habilitar PEP 479 para todo el código por defecto: a
StopIteration
generado en un generador se transforma enRuntimeError
.
-
exception
StopAsyncIteration
¶ Se debe generar mediante
__anext__()
de un objeto asynchronous iterator para detener la iteración.Nuevo en la versión 3.5.
-
exception
SyntaxError
¶ Se genera cuando el analizador (parser) encuentra un error de sintaxis. Esto puede ocurrir en una declaración
import
, en una llamada a las funciones predefinidasexec()
oeval()
, o al leer el script inicial o la entrada estándar (también de forma interactiva).The
str()
of the exception instance returns only the error message.-
filename
¶ The name of the file the syntax error occurred in.
-
lineno
¶ Which line number in the file the error occurred in. This is 1-indexed: the first line in the file has a
lineno
of 1.
-
offset
¶ The column in the line where the error occurred. This is 1-indexed: the first character in the line has an
offset
of 1.
-
text
¶ The source code text involved in the error.
-
-
exception
IndentationError
¶ Clase base para errores de sintaxis relacionados con sangría incorrecta. Esta es una subclase de
SyntaxError
.
-
exception
TabError
¶ Se genera cuando la sangría contiene un uso inconsistente de pestañas y espacios. Esta es una subclase de
IndentationError
.
-
exception
SystemError
¶ Se genera cuando el intérprete encuentra un error interno, pero la situación no parece tan grave como para abandonar toda esperanza. El valor asociado es una cadena que indica qué salió mal (a bajo nivel).
Debe informar esto al autor o responsable de su intérprete de Python. Asegúrese de informar la versión del intérprete de Python (
sys.version
; también se imprime al comienzo de una sesión interactiva de Python), el mensaje de error exacto (el valor asociado de la excepción) y, si es posible, la fuente del programa que activó el error.
-
exception
SystemExit
¶ Esta excepción es provocada por la función
sys.exit()
. Hereda deBaseException
en lugar deException
para que no sea gestionada accidentalmente por el código que capturaException
. Esto permite que la excepción se propague correctamente y que el intérprete salga. Cuando no se maneja, el intérprete de Python sale; no se imprime el seguimiento de pila. El constructor acepta el mismo argumento opcional pasado asys.exit()
. Si el valor es un entero, especifica el estado de salida del sistema (se pasa a la funciónexit()
de C); si esNone
, el estado de salida es cero; Si tiene otro tipo (como una cadena), se imprime el valor del objeto y el estado de salida es uno.Una llamada
sys.exit()
se traduce en una excepción para que los gestores de limpieza (finally
cláusulas detry
) puedan ejecutarse, y para que un depurador pueda ejecutar un script sin correr el riesgo de perder el control. La funciónos._exit()
se puede usar si es absolutamente necesario salir (por ejemplo, en el proceso secundario después de una llamada aos.fork()
).-
code
¶ El estado de salida o mensaje de error que se pasa al constructor. (El valor predeterminado es
None
.)
-
-
exception
TypeError
¶ Se genera cuando una operación o función se aplica a un objeto de tipo inapropiado. El valor asociado es una cadena que proporciona detalles sobre la falta de coincidencia de tipos.
El código de usuario puede generar esta excepción para indicar que un intento de operación en un objeto no es compatible y no debe serlo. Si un objeto está destinado a soportar una operación dada pero aún no ha proporcionado una implementación,
NotImplementedError
es la excepción adecuada para generar.Pasar argumentos del tipo incorrecto (por ejemplo, pasar a
list
cuando se espera unint
) debería dar como resultadoTypeError
, pero pasar argumentos con el valor incorrecto (por ejemplo, un número fuera límites esperados) debería dar como resultadoValueError
.
-
exception
UnboundLocalError
¶ Se genera cuando se hace referencia a una variable local en una función o método, pero no se ha vinculado ningún valor a esa variable. Esta es una subclase de
NameError
.
-
exception
UnicodeError
¶ Se genera cuando se produce un error de codificación o decodificación relacionado con Unicode. Es una subclase de
ValueError
.UnicodeError
tiene atributos que describen el error de codificación o decodificación. Por ejemplo,err.object[err.start:err.end]
proporciona la entrada inválida particular en la que falló el códec.-
encoding
¶ El nombre de la codificación que provocó el error.
-
reason
¶ Una cadena que describe el error de códec específico.
-
object
¶ El objeto que el códec intentaba codificar o decodificar.
-
-
exception
UnicodeEncodeError
¶ Se genera cuando se produce un error relacionado con Unicode durante la codificación. Es una subclase de
UnicodeError
.
-
exception
UnicodeDecodeError
¶ Se genera cuando se produce un error relacionado con Unicode durante la codificación. Es una subclase de
UnicodeError
.
-
exception
UnicodeTranslateError
¶ Se genera cuando se produce un error relacionado con Unicode durante la codificación. Es una subclase de
UnicodeError
.
-
exception
ValueError
¶ Se genera cuando una operación o función recibe un argumento que tiene el tipo correcto pero un valor inapropiado, y la situación no se describe con una excepción más precisa como
IndexError
.
-
exception
ZeroDivisionError
¶ Se genera cuando el segundo argumento de una operación de división o módulo es cero. El valor asociado es una cadena que indica el tipo de operandos y la operación.
Las siguientes excepciones se mantienen por compatibilidad con versiones anteriores; a partir de Python 3.3, son alias de OSError
.
-
exception
EnvironmentError
¶
-
exception
IOError
¶
-
exception
WindowsError
¶ Solo disponible en Windows.
Excepciones del sistema operativo¶
Las siguientes excepciones son subclases de OSError
, se generan según el código de error del sistema.
-
exception
BlockingIOError
¶ Se genera cuando una operación se bloquearía en un objeto (por ejemplo, un socket) configurado para una operación sin bloqueo. Corresponde a
errno
EAGAIN
,EALREADY
,EWOULDBLOCK
yEINPROGRESS
.Además de los de
OSError
,BlockingIOError
puede tener un atributo más:
-
exception
ChildProcessError
¶ Se genera cuando falla una operación en un proceso secundario. Corresponde
errno
ECHILD
.
-
exception
ConnectionError
¶ Una clase base para problemas relacionados con la conexión.
Las subclases son
BrokenPipeError
,ConnectionAbortedError
,ConnectionRefusedError
yConnectionResetError
.
-
exception
BrokenPipeError
¶ Una subclase de
ConnectionError
, que se genera cuando se intenta escribir en una tubería mientras el otro extremo se ha cerrado, o cuando se intenta escribir en un socket que se ha cerrado por escritura. Corresponde aerrno
EPIPE
yESHUTDOWN
.
-
exception
ConnectionAbortedError
¶ Una subclase de
ConnectionError
, que se genera cuando el par interrumpe un intento de conexión. Corresponde aerrno
ECONNABORTED
.
-
exception
ConnectionRefusedError
¶ Una subclase de
ConnectionError
, que se genera cuando el par interrumpe un intento de conexión. Corresponde aerrno
ECONNABORTED
.
-
exception
ConnectionResetError
¶ Una subclase de
ConnectionError
, que se genera cuando el par restablece una conexión. Corresponde aerrno
ECONNRESET
.
-
exception
FileExistsError
¶ Se genera al intentar crear un archivo o directorio que ya existe. Corresponde a
errno
EEXIST
.
-
exception
FileNotFoundError
¶ Se genera cuando se solicita un archivo o directorio pero no existe. Corresponde a
errno
ENOENT
.
-
exception
InterruptedError
¶ Se genera cuando una llamada entrante interrumpe una llamada del sistema. Corresponde a
errno
EINTR
.Distinto en la versión 3.5: Python ahora vuelve a intentar las llamadas del sistema cuando una señal interrumpe un syscall, excepto si el gestor señala generar una excepción (ver PEP 475 para la justificación), en lugar de lanzar
InterruptedError
.
-
exception
IsADirectoryError
¶ Se genera cuando se solicita una operación de archivo (como
os.remove()
) en un directorio. Corresponde a:errno
EISDIR
.
-
exception
NotADirectoryError
¶ Se genera cuando se solicita una operación de directorio (como
os.listdir()
) en algo que no es un directorio. Corresponde aerrno
ENOTDIR
.
-
exception
PermissionError
¶ Se genera cuando se intenta ejecutar una operación sin los derechos de acceso adecuados, por ejemplo, permisos del sistema de archivos. Corresponde a
errno
EACCES
yEPERM
.
-
exception
ProcessLookupError
¶ Generado cuando un proceso dado no existe. Corresponde a
errno
ESRCH
.
-
exception
TimeoutError
¶ Se genera cuando se agota el tiempo de espera de una función del sistema a nivel del sistema. Corresponde a
errno
ETIMEDOUT
.
Nuevo en la versión 3.3: Por lo anterior se agregaron las subclases OSError
.
Ver también
PEP 3151 - Reelaborando el sistema operativo y la jerarquía de excepciones E/S
Advertencias¶
Las siguientes excepciones se utilizan como categorías de advertencia; consulte la documentación de Categorías de advertencia para obtener más detalles.
-
exception
Warning
¶ Clase base para categorías de advertencia.
-
exception
UserWarning
¶ Clase base para advertencias generadas por código de usuario.
-
exception
DeprecationWarning
¶ Clase base para advertencias sobre características obsoletas cuando esas advertencias están destinadas a otros desarrolladores de Python.
-
exception
PendingDeprecationWarning
¶ Clase base para advertencias sobre características que están obsoletas y que se espera que sean obsoletas en el futuro, pero que no lo son en este momento.
Esta clase rara vez se usa para emitir una advertencia sobre una posible desaprobación próxima es inusual, y
DeprecationWarning
se prefiere para las desaprobaciones ya activas.
-
exception
SyntaxWarning
¶ Clase base para advertencias sobre sintaxis dudosa.
-
exception
RuntimeWarning
¶ Clase base para advertencias sobre comportamiento dudoso en tiempo de ejecución.
-
exception
FutureWarning
¶ Clase base para advertencias sobre características en desuso cuando esas advertencias están destinadas a usuarios finales de aplicaciones escritas en Python.
-
exception
ImportWarning
¶ Clase base para advertencias sobre posibles errores en la importación de módulos.
-
exception
UnicodeWarning
¶ Clase base para advertencias relacionadas con Unicode.
-
exception
ResourceWarning
¶ Clase base para advertencias relacionadas con el uso de recursos. Ignorado por los filtros de advertencia predeterminados.
Nuevo en la versión 3.2.
Jerarquía de excepción¶
La jerarquía de clases para las excepciones incorporadas es:
BaseException
+-- SystemExit
+-- KeyboardInterrupt
+-- GeneratorExit
+-- Exception
+-- StopIteration
+-- StopAsyncIteration
+-- ArithmeticError
| +-- FloatingPointError
| +-- OverflowError
| +-- ZeroDivisionError
+-- AssertionError
+-- AttributeError
+-- BufferError
+-- EOFError
+-- ImportError
| +-- ModuleNotFoundError
+-- LookupError
| +-- IndexError
| +-- KeyError
+-- MemoryError
+-- NameError
| +-- UnboundLocalError
+-- OSError
| +-- BlockingIOError
| +-- ChildProcessError
| +-- ConnectionError
| | +-- BrokenPipeError
| | +-- ConnectionAbortedError
| | +-- ConnectionRefusedError
| | +-- ConnectionResetError
| +-- FileExistsError
| +-- FileNotFoundError
| +-- InterruptedError
| +-- IsADirectoryError
| +-- NotADirectoryError
| +-- PermissionError
| +-- ProcessLookupError
| +-- TimeoutError
+-- ReferenceError
+-- RuntimeError
| +-- NotImplementedError
| +-- RecursionError
+-- SyntaxError
| +-- IndentationError
| +-- TabError
+-- SystemError
+-- TypeError
+-- ValueError
| +-- UnicodeError
| +-- UnicodeDecodeError
| +-- UnicodeEncodeError
| +-- UnicodeTranslateError
+-- Warning
+-- DeprecationWarning
+-- PendingDeprecationWarning
+-- RuntimeWarning
+-- SyntaxWarning
+-- UserWarning
+-- FutureWarning
+-- ImportWarning
+-- UnicodeWarning
+-- BytesWarning
+-- ResourceWarning