Exceções embutidas¶
No Python, todas as exceções devem ser instâncias de uma classe derivada de BaseException
. Em uma instrução try
com uma cláusula except
que menciona uma classe específica, essa cláusula também lida com qualquer classe de exceção derivada dessa classe (mas não com as classes de exceção a partir das quais ela é derivada). Duas classes de exceção que não são relacionadas por subclasse nunca são equivalentes, mesmo que tenham o mesmo nome.
As exceções embutidas listadas abaixo podem ser geradas pelo interpretador ou pelas funções embutidas. Exceto onde mencionado, eles têm um “valor associado” indicando a causa detalhada do erro. Pode ser uma sequência ou uma tupla de vários itens de informação (por exemplo, um código de erro e uma sequência que explica o código). O valor associado geralmente é passado como argumentos para o construtor da classe de exceção.
O código do usuário pode gerar exceções embutidas. Isso pode ser usado para testar um manipulador de exceções ou para relatar uma condição de erro “exatamente como” a situação na qual o interpretador gera a mesma exceção; mas lembre-se de que nada impede o código do usuário de gerar um erro inadequado.
As classes de exceções embutidas podem ser usadas como subclasses para definir novas exceções; Os programadores são incentivados a derivar novas exceções da classe Exception
ou de uma de suas subclasses, e não de BaseException
. Mais informações sobre a definição de exceções estão disponíveis no Tutorial do Python em Exceções definidas pelo usuário.
Ao gerar (ou levantar novamente) uma exceção em uma cláusula except
ou finally
, __context__
é automaticamente definida como a última exceção capturada; se a nova exceção não for tratada, o traceback exibido eventualmente incluirá a(s) exceção(ões) de origem e a exceção final.
Ao levantar uma nova exceção (em vez de usar um raise
simples para aumentar novamente a exceção que está sendo tratada), o contexto implícito da exceção pode ser complementado com uma causa explícita usando from
com raise
:
raise new_exc from original_exc
A expressão a seguir from
deve ser uma exceção ou None
. Ela será definida como __cause__
na exceção levantada. A definição de __cause__
também define implicitamente o atributo __suppress_context__
como True
, de modo que o uso de raise new_exc from None
substitui efetivamente a exceção antiga pela nova para fins de exibição (por exemplo, convertendo KeyError
para AttributeError
), deixando a exceção antiga disponível em __context__
para introspecção durante a depuração.
O código de exibição padrão do traceback mostra essas exceções encadeadas, além do traceback da própria exceção. Uma exceção explicitamente encadeada em __cause__
sempre é mostrada quando presente. Uma exceção implicitamente encadeada em __context__
é mostrada apenas se __cause__
for None
e __suppress_context__
for falso.
Em qualquer um dos casos, a exceção em si sempre é mostrada após todas as exceções encadeadas, de modo que a linha final do traceback sempre mostre a última exceção que foi levantada.
Classes base¶
As seguintes exceções são usadas principalmente como classes base para outras exceções.
-
exception
BaseException
¶ A classe base para todas as exceções embutidas. Não é para ser herdada diretamente por classes definidas pelo usuário (para isso, use
Exception
). Sestr()
for chamado em uma instância desta classe, a representação do(s) argumento(s) para a instância será retornada ou a string vazia quando não houver argumentos.-
args
¶ A tupla de argumentos fornecidos ao construtor de exceções. Algumas exceções embutidas (como
OSError
) esperam um certo número de argumentos e atribuem um significado especial aos elementos dessa tupla, enquanto outras são normalmente chamadas apenas com uma única string que fornece uma mensagem de erro.
-
with_traceback
(tb)¶ Esse método define tb como o novo traceback para a exceção e retorna o objeto de exceção. Geralmente é usado no código de manipulação de exceção como este:
try: ... except SomeException: tb = sys.exc_info()[2] raise OtherException(...).with_traceback(tb)
-
-
exception
Exception
¶ Todas as exceções embutidas que não saem para o sistema são derivadas dessa classe. Todas as exceções definidas pelo usuário também devem ser derivadas dessa classe.
-
exception
ArithmeticError
¶ A classe base para as exceções embutidas levantadas para vários erros aritméticos:
OverflowError
,ZeroDivisionError
,FloatingPointError
.
-
exception
LookupError
¶ A classe base para as exceções levantadas quando uma chave ou índice usado em um mapeamento ou sequência é inválido:
IndexError
,KeyError
. Isso pode ser levantado diretamente porcodecs.lookup()
.
Exceções concretas¶
As seguintes exceções são as que geralmente são levantados.
-
exception
AttributeError
¶ Levantado quando uma referência de atributo (consulte Attribute references) ou atribuição falha. (Quando um objeto não oferece suporte a referências ou atribuições de atributos,
TypeError
é levantado.)
-
exception
EOFError
¶ Levantado quando a função
input()
atinge uma condição de fim de arquivo (EOF) sem ler nenhum dado. (Note: os métodosio.IOBase.read()
eio.IOBase.readline()
retornam uma string vazia quando pressionam o EOF.)
-
exception
FloatingPointError
¶ Não usado atualmente.
-
exception
GeneratorExit
¶ Levantado quando um gerador ou uma corrotina está fechado(a); veja
generator.close()
ecoroutine.close()
. Herda diretamente deBaseException
em vez deException
, já que tecnicamente não é um erro.
-
exception
ImportError
¶ Levantada quando a instrução
import
tem problemas ao tentar carregar um módulo. Também é gerado quando o “from list” emfrom ... import
tem um nome que não pode ser encontrado.Os atributos
name
epath
podem ser configurados usando argumentos somente-nomeados para o construtor. Quando configurados, eles representam o nome do módulo que foi tentado ser importado e o caminho para qualquer arquivo que acionou a exceção, respectivamente.Alterado na versão 3.3: Adicionados os atributos
name
epath
.
-
exception
ModuleNotFoundError
¶ Uma subclasse de
ImportError
que é levantada porimport
quando um módulo não pôde ser localizado. Também é levantada quandoNone
é encontrado emsys.modules
.Novo na versão 3.6.
-
exception
IndexError
¶ Levantada quando um índice de alguma sequência está fora do intervalo. (Índices de fatia são truncados silenciosamente para cair num intervalo permitido; se um índice não for um inteiro,
TypeError
é levantada.)
-
exception
KeyError
¶ Levantada quando uma chave de mapeamento (dicionário) não é encontrada no conjunto de chaves existentes.
-
exception
KeyboardInterrupt
¶ Levantada quando um usuário aperta a tecla de interrupção (normalmente Control-C ou Delete). Durante a execução, uma checagem de interrupção é feita regularmente. A exceção herda de
BaseException
para que não seja capturada acidentalmente por códigos que tratamException
e assim evita que o interpretador saia.
-
exception
MemoryError
¶ Levantada quando uma operação fica sem memória mas a situação ainda pode ser recuperada (excluindo alguns objetos). O valor associado é uma string que indica o tipo de operação (interna) que ficou sem memória. Observe que, por causa da arquitetura de gerenciamento de memória subjacente (função
malloc()
do C), o interpretador pode não ser capaz de se recuperar completamente da situação; no entanto, levanta uma exceção para que um traceback possa ser impresso, no caso de um outro programa ser a causa.
-
exception
NameError
¶ Levantada quando um nome local ou global não é encontrado. Isso se aplica apenas a nomes não qualificados. O valor associado é uma mensagem de erro que inclui o nome que não pode ser encontrado.
-
exception
NotImplementedError
¶ Essa exceção é derivada da
RuntimeError
. Em classes base, definidas pelo usuário, os métodos abstratos devem gerar essa exceção quando requerem que classes derivadas substituam o método, ou enquanto a classe está sendo desenvolvida, para indicar que a implementação real ainda precisa ser adicionada.Nota
Não deve ser usada para indicar que um operador ou método não será mais suportado – nesse caso deixe o operador / método indefinido ou, se é uma subclasse, defina-o como
None
.Nota
NotImplementedError
eNotImplemented
não são intercambiáveis, mesmo que tenham nomes e propósitos similares. VejaNotImplemented
para detalhes e casos de uso.
-
exception
OSError
([arg])¶ -
exception
OSError
(errno, strerror[, filename[, winerror[, filename2]]]) Esta exceção é levantada quando uma função do sistema retorna um erro relacionado ao sistema, incluindo falhas do tipo E/S como “file not found” ou “disk full” (não para tipos de argumentos não permitidos ou outro erro acessório).
A segunda forma do construtor definir os atributos correspondentes, descritos abaixo. Os atributos usarão o valor padrão
None
se não forem especificados. Por compatibilidade com versões anteriores, se três argumentos são passados, o atributoargs
contêm somente uma tupla de 2 elementos, os dois primeiros argumentos do construtor.O construtor geralmente retorna uma subclasse de
OSError
, como descrito abaixo em OS exceptions . A subclasse particular depende do valor final deerrno
. Este comportamento ocorre apenas durante a construção direta ou por meio de um apelido deOSError
, e não é herdado na criação de subclasses.-
errno
¶ Um código de erro numérico da variável C
errno
.
-
winerror
¶ No Windows, isso fornece o código de erro nativo do Windows. O atributo
errno
é então uma tradução aproximada, em termos POSIX, desse código de erro nativo.No Windows, se o argumento de construtor winerror for um inteiro, o atributo
errno
é determinado a partir do código de erro do Windows e o argumento errno é ignorado. Em outras plataformas, o argumento winerror é ignorado e o atributowinerror
não existe.
-
strerror
¶ A mensagem de erro correspondente, conforme fornecida pelo sistema operacional. É formatada pelas funções C
perror()
no POSIX eFormatMessage()
no Windows.
-
filename
¶ -
filename2
¶ Para exceções que envolvem um caminho do sistema de arquivos (como
open()
ouos.unlink()
),filename
é o nome do arquivo passado para a função. Para funções que envolvem dois caminhos de sistema de arquivos (comoos.rename()
),filename2
corresponde ao segundo nome de arquivo passado para a função.
Alterado na versão 3.3:
EnvironmentError
,IOError
,WindowsError
,socket.error
,select.error
emmap.error
foram fundidos emOSError
, e o construtor pode retornar uma subclasse.Alterado na versão 3.4: O atributo
filename
agora é o nome do arquivo original passado para a função, ao invés do nome codificado ou decodificado da codificação do sistema de arquivos. Além disso, o argumento e o atributo de construtor filename2 foi adicionado.-
-
exception
OverflowError
¶ Levantada quando o resultado de uma operação aritmética é muito grande para ser representada. Isso não pode ocorrer para inteiros (que prefere levantar
MemoryError
a desistir). No entanto, por motivos históricos, OverflowError às vezes é levantada para inteiros que estão fora de um intervalo obrigatório. Devido à falta de padronização do tratamento de exceção de ponto flutuante em C, a maioria das operações de ponto flutuante não são verificadas.
-
exception
RecursionError
¶ Esta exceção é derivada de
RuntimeError
. É levantada quando o interpretador detecta que a profundidade máxima de recursão (vejasys.getrecursionlimit()
) foi excedida.Novo na versão 3.5: Anteriormente, uma
RuntimeError
simples era levantada.
-
exception
ReferenceError
¶ Esta exceção é levantada quando um intermediário de referência fraca, criado pela função
weakref.proxy()
, é usado para acessar um atributo do referente após ter sido coletado como lixo. Para mais informações sobre referências fracas, veja o móduloweakref
.
-
exception
RuntimeError
¶ Levantada quando um erro é detectado e não se encaixa em nenhuma das outras categorias. O valor associado é uma string indicando o que precisamente deu errado.
-
exception
StopIteration
¶ Levantada pela função embutida
next()
e o método__next__()
de um iterador para sinalizar que não há mais itens produzidos pelo iterador.O objeto exceção tem um único atributo
value
, que é fornecido como um argumento ao construir a exceção, e o padrão éNone
.Quando uma função geradora ou corrotina retorna, uma nova instância
StopIteration
é levantada, e o valor retornado pela função é usado como o parâmetrovalue
para o construtor da exceção.Se um código gerador direta ou indiretamente levantar
StopIteration
, ele é convertido em umaRuntimeError
(mantendo oStopIteration
como a nova causa da exceção).Alterado na versão 3.3: Adicionado o atributo
value
e a capacidade das funções geradoras de usá-lo para retornar um valor.Alterado na versão 3.5: Introduzida a transformação RuntimeError via
from __future__ import generator_stop
, consulte PEP 479.Alterado na versão 3.7: Habilita PEP 479 para todo o código por padrão: um erro
StopIteration
levantado em um gerador é transformado em umaRuntimeError
.
-
exception
StopAsyncIteration
¶ Deve ser levantada pelo método
__anext__()
de um objeto iterador assíncrono para parar a iteração.Novo na versão 3.5.
-
exception
SyntaxError
¶ Levantada quando o analisador encontra um erro de sintaxe. Isso pode ocorrer em uma instrução
import
, em uma chamada às funções embutidasexec()
oueval()
, ou ao ler o script inicial ou entrada padrão (também interativamente).Instâncias desta classe têm atributos
filename
,lineno
,offset
etext
para facilitar o acesso aos detalhes.str()
da instância de exceção retorna apenas a mensagem.
-
exception
IndentationError
¶ Classe base para erros de sintaxe relacionados a indentação incorreta. Esta é uma subclasse de
SyntaxError
.
-
exception
TabError
¶ Levantada quando o indentação contém um uso inconsistente de tabulações e espaços. Esta é uma subclasse de
IndentationError
.
-
exception
SystemError
¶ Levantada quando o interpretador encontra um erro interno, mas a situação não parece tão grave para fazer com que perca todas as esperanças. O valor associado é uma string que indica o que deu errado (em termos de baixo nível).
Você deve relatar isso ao autor ou mantenedor do seu interpretador Python. Certifique-se de relatar a versão do interpretador Python (
sys.version
; também é impresso no início de uma sessão Python interativa), a mensagem de erro exata (o valor associado da exceção) e se possível a fonte do programa que acionou o erro.
-
exception
SystemExit
¶ This exception is raised by the
sys.exit()
function. It inherits fromBaseException
instead ofException
so that it is not accidentally caught by code that catchesException
. This allows the exception to properly propagate up and cause the interpreter to exit. When it is not handled, the Python interpreter exits; no stack traceback is printed. The constructor accepts the same optional argument passed tosys.exit()
. If the value is an integer, it specifies the system exit status (passed to C’sexit()
function); if it isNone
, the exit status is zero; if it has another type (such as a string), the object’s value is printed and the exit status is one.A call to
sys.exit()
is translated into an exception so that clean-up handlers (finally
clauses oftry
statements) can be executed, and so that a debugger can execute a script without running the risk of losing control. Theos._exit()
function can be used if it is absolutely positively necessary to exit immediately (for example, in the child process after a call toos.fork()
).-
code
¶ The exit status or error message that is passed to the constructor. (Defaults to
None
.)
-
-
exception
TypeError
¶ Raised when an operation or function is applied to an object of inappropriate type. The associated value is a string giving details about the type mismatch.
This exception may be raised by user code to indicate that an attempted operation on an object is not supported, and is not meant to be. If an object is meant to support a given operation but has not yet provided an implementation,
NotImplementedError
is the proper exception to raise.Passing arguments of the wrong type (e.g. passing a
list
when anint
is expected) should result in aTypeError
, but passing arguments with the wrong value (e.g. a number outside expected boundaries) should result in aValueError
.
-
exception
UnboundLocalError
¶ Raised when a reference is made to a local variable in a function or method, but no value has been bound to that variable. This is a subclass of
NameError
.
-
exception
UnicodeError
¶ Raised when a Unicode-related encoding or decoding error occurs. It is a subclass of
ValueError
.UnicodeError
has attributes that describe the encoding or decoding error. For example,err.object[err.start:err.end]
gives the particular invalid input that the codec failed on.-
encoding
¶ The name of the encoding that raised the error.
-
reason
¶ A string describing the specific codec error.
-
object
¶ The object the codec was attempting to encode or decode.
-
-
exception
UnicodeEncodeError
¶ Raised when a Unicode-related error occurs during encoding. It is a subclass of
UnicodeError
.
-
exception
UnicodeDecodeError
¶ Raised when a Unicode-related error occurs during decoding. It is a subclass of
UnicodeError
.
-
exception
UnicodeTranslateError
¶ Raised when a Unicode-related error occurs during translating. It is a subclass of
UnicodeError
.
-
exception
ValueError
¶ Raised when an operation or function receives an argument that has the right type but an inappropriate value, and the situation is not described by a more precise exception such as
IndexError
.
-
exception
ZeroDivisionError
¶ Raised when the second argument of a division or modulo operation is zero. The associated value is a string indicating the type of the operands and the operation.
The following exceptions are kept for compatibility with previous versions;
starting from Python 3.3, they are aliases of OSError
.
-
exception
EnvironmentError
¶
-
exception
IOError
¶
-
exception
WindowsError
¶ Only available on Windows.
OS exceptions¶
The following exceptions are subclasses of OSError
, they get raised
depending on the system error code.
-
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
andEINPROGRESS
.In addition to those of
OSError
,BlockingIOError
can have one more attribute:
-
exception
ChildProcessError
¶ Raised when an operation on a child process failed. Corresponds to
errno
ECHILD
.
-
exception
ConnectionError
¶ A base class for connection-related issues.
Subclasses are
BrokenPipeError
,ConnectionAbortedError
,ConnectionRefusedError
andConnectionResetError
.
-
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 toerrno
EPIPE
andESHUTDOWN
.
-
exception
ConnectionAbortedError
¶ A subclass of
ConnectionError
, raised when a connection attempt is aborted by the peer. Corresponds toerrno
ECONNABORTED
.
-
exception
ConnectionRefusedError
¶ A subclass of
ConnectionError
, raised when a connection attempt is refused by the peer. Corresponds toerrno
ECONNREFUSED
.
-
exception
ConnectionResetError
¶ A subclass of
ConnectionError
, raised when a connection is reset by the peer. Corresponds toerrno
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
¶ Raised when a system call is interrupted by an incoming signal. Corresponds to
errno
EINTR
.Alterado na versão 3.5: Python now retries system calls when a syscall is interrupted by a signal, except if the signal handler raises an exception (see PEP 475 for the rationale), instead of raising
InterruptedError
.
-
exception
IsADirectoryError
¶ Raised when a file operation (such as
os.remove()
) is requested on a directory. Corresponds toerrno
EISDIR
.
-
exception
NotADirectoryError
¶ Raised when a directory operation (such as
os.listdir()
) is requested on something which is not a directory. Corresponds toerrno
ENOTDIR
.
-
exception
PermissionError
¶ Raised when trying to run an operation without the adequate access rights - for example filesystem permissions. Corresponds to
errno
EACCES
andEPERM
.
-
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
.
Novo na versão 3.3: All the above OSError
subclasses were added.
Ver também
PEP 3151 - Reworking the OS and IO exception hierarchy
Warnings¶
The following exceptions are used as warning categories; see the Warning Categories documentation for more details.
-
exception
Warning
¶ Base class for warning categories.
-
exception
UserWarning
¶ Base class for warnings generated by user code.
-
exception
DeprecationWarning
¶ Base class for warnings about deprecated features when those warnings are intended for other Python developers.
Ignored by the default warning filters, except in the
__main__
module (PEP 565). Enabling the Python Development Mode shows this warning.
-
exception
PendingDeprecationWarning
¶ Base class for warnings about features which are obsolete and expected to be deprecated in the future, but are not deprecated at the moment.
This class is rarely used as emitting a warning about a possible upcoming deprecation is unusual, and
DeprecationWarning
is preferred for already active deprecations.Ignored by the default warning filters. Enabling the Python Development Mode shows this warning.
-
exception
SyntaxWarning
¶ Base class for warnings about dubious syntax.
-
exception
RuntimeWarning
¶ Base class for warnings about dubious runtime behavior.
-
exception
FutureWarning
¶ Base class for warnings about deprecated features when those warnings are intended for end users of applications that are written in Python.
-
exception
ImportWarning
¶ Base class for warnings about probable mistakes in module imports.
Ignored by the default warning filters. Enabling the Python Development Mode shows this warning.
-
exception
UnicodeWarning
¶ Base class for warnings related to Unicode.
-
exception
ResourceWarning
¶ Base class for warnings related to resource usage.
Ignored by the default warning filters. Enabling the Python Development Mode shows this warning.
Novo na versão 3.2.
Exception hierarchy¶
The class hierarchy for built-in exceptions is:
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