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.

Exception context

When raising a new exception while another exception is already being handled, the new exception’s __context__ attribute is automatically set to the handled exception. An exception may be handled when an except or finally clause, or a with statement, is used.

This 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ó.

Inheriting from built-in exceptions

User code can create subclasses that inherit from an exception type. It’s recommended to only subclass one exception type at a time to avoid any possible conflicts between how the bases handle the args attribute, as well as due to possible memory layout incompatibilities.

CPython implementation detail: Most built-in exceptions are implemented in C for efficiency, see: Objects/exceptions.c. Some have custom memory layouts which makes it impossible to create a subclass that inherits from multiple exception types. The memory layout of a type is an implementation detail and might change between Python versions, leading to new conflicts in the future. Therefore, it’s recommended to avoid subclassing multiple exception types altogether.

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 a str() 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 nuevo traceback 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 BufferError

Se genera cuando buffer no se puede realizar una operación relacionada.

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 por codecs.lookup().

Excepciones específicas

Las siguientes excepciones son las excepciones que normalmente se generan.

exception AssertionError

Se genera cuando se produce un error en una instrucción assert.

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 el io. IOBase.read() y io.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() y coroutine.close(). Hereda directamente de BaseException en lugar de Exception 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 en from ... import tiene un nombre que no se puede encontrar.

Los atributos name y path 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 y path.

exception ModuleNotFoundError

Una subclase de ImportError que se genera mediante import cuando no se pudo encontrar un módulo. También se genera cuando None se encuentra en sys.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 por Exception y, por lo tanto, prevenir que el intérprete salga.

Nota

Catching a KeyboardInterrupt requires special consideration. Because it can be raised at unpredictable points, it may, in some circumstances, leave the running program in an inconsistent state. It is generally best to allow KeyboardInterrupt to end the program as quickly as possible or avoid raising it entirely. (See Note on Signal Handlers and Exceptions.)

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 y NotImplemented no son intercambiables, a pesar de que tienen nombres y propósitos similares. Consulte NotImplemented 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 o disk 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 especifican. Para compatibilidad con versiones anteriores, si se pasan tres argumentos, el atributo args 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 final errno. Este comportamiento solo ocurre cuando se construye OSError 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 atributo errno se determina a partir del código de error de Windows y el argumento errno se ignora. En otras plataformas, el argumento winerror se ignora y el atributo winerror 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, y FormatMessage() en Windows.

filename
filename2

Para las excepciones que involucran una ruta del sistema de archivos (como open() o os.unlink()), filename es el nombre del archivo pasado a la función. Para las funciones que involucran dos rutas del sistema de archivos (como os.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 y mmap.error se han fusionado en OSError, 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 constructor filename2 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 (ver sys.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ódulo weakref .

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 es None.

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ámetro value para constructor de la excepción.

Si un generador lanza directa o indirectamente StopIteration, se convierte en RuntimeError (conservando StopIteration 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 en RuntimeError.

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(message, details)

Raised when the parser encounters a syntax error. This may occur in an import statement, in a call to the built-in functions compile(), exec(), or eval(), or when reading the initial script or standard input (also interactively).

The str() of the exception instance returns only the error message. Details is a tuple whose members are also available as separate attributes.

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.

For errors in f-string fields, the message is prefixed by «f-string: » and the offsets are offsets in a text constructed from the replacement expression. For example, compiling f’Bad {a b} field” results in this args attribute: (“f-string: …”, (“”, 1, 4, “(a b)n”)).

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 de BaseException en lugar de Exception para que no sea gestionada accidentalmente por el código que captura Exception. 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 a sys.exit(). Si el valor es un entero, especifica el estado de salida del sistema (se pasa a la función exit() de C); si es None, 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 de try) puedan ejecutarse, y para que un depurador pueda ejecutar un script sin correr el riesgo de perder el control. La función os._exit() se puede usar si es absolutamente necesario salir (por ejemplo, en el proceso secundario después de una llamada a os.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 un int) debería dar como resultado TypeError, pero pasar argumentos con el valor incorrecto (por ejemplo, un número fuera límites esperados) debería dar como resultado ValueError.

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.

start

El primer índice de datos no válidos en object.

end

El índice después de los últimos datos no válidos en object.

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

Raised when an operation would block on an object (e.g. socket) set for non-blocking operation. Corresponds to errno EAGAIN, EALREADY, EWOULDBLOCK and EINPROGRESS.

Además de los de OSError, BlockingIOError puede tener un atributo más:

characters_written

Un entero que contiene el número de caracteres escritos en la secuencia antes de que se bloquee. Este atributo está disponible cuando se utilizan las clases de E/S almacenadas en el modulo io.

exception ChildProcessError

Raised when an operation on a child process failed. Corresponds to errno ECHILD.

exception ConnectionError

Una clase base para problemas relacionados con la conexión.

Las subclases son BrokenPipeError, ConnectionAbortedError, ConnectionRefusedError y ConnectionResetError.

exception BrokenPipeError

A subclass of ConnectionError, raised when trying to write on a pipe while the other end has been closed, or trying to write on a socket which has been shutdown for writing. Corresponds to errno EPIPE and ESHUTDOWN.

exception ConnectionAbortedError

A subclass of ConnectionError, raised when a connection attempt is aborted by the peer. Corresponds to errno ECONNABORTED.

exception ConnectionRefusedError

A subclass of ConnectionError, raised when a connection attempt is refused by the peer. Corresponds to errno ECONNREFUSED.

exception ConnectionResetError

A subclass of ConnectionError, raised when a connection is reset by the peer. Corresponds to errno ECONNRESET.

exception FileExistsError

Raised when trying to create a file or directory which already exists. Corresponds to errno EEXIST.

exception FileNotFoundError

Raised when a file or directory is requested but doesn’t exist. Corresponds to 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

Raised when a file operation (such as os.remove()) is requested on a directory. Corresponds to errno EISDIR.

exception NotADirectoryError

Raised when a directory operation (such as os.listdir()) is requested on something which is not a directory. On most POSIX platforms, it may also be raised if an operation attempts to open or traverse a non-directory file as if it were a directory. Corresponds to errno ENOTDIR.

exception PermissionError

Raised when trying to run an operation without the adequate access rights - for example filesystem permissions. Corresponds to errno EACCES and EPERM.

exception ProcessLookupError

Raised when a given process doesn’t exist. Corresponds to errno ESRCH.

exception TimeoutError

Raised when a system function timed out at the system level. Corresponds to 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.

Ignorado por los filtros de advertencia predeterminados, excepto en el módulo __main__ (PEP 565). Habilitando Modo Desarrollo de Python muestra esta advertencia.

The deprecation policy is described in PEP 387.

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.

Ignorado por los filtros de advertencia predeterminados. Habilitando Modo Desarrollo de Python muestra esta advertencia.

The deprecation policy is described in PEP 387.

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.

Ignorado por los filtros de advertencia predeterminados. Habilitando Modo Desarrollo de Python muestra esta advertencia.

exception UnicodeWarning

Clase base para advertencias relacionadas con Unicode.

exception BytesWarning

Clase base para advertencias relacionadas con bytes y bytearray.

exception ResourceWarning

Clase base para advertencias relacionadas con el uso de recursos.

Ignorado por los filtros de advertencia predeterminados. Habilitando Modo Desarrollo de Python muestra esta advertencia.

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