# 5. 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ção internas 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 :keyword:` finally`, `__context__` é automaticamente definida como a última exceção capturada; se a nova exceção não for tratada, o traceback exibido eventualmente incluirá as exceçõ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.

## 5.1. 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 internas. Não é para ser herdada diretamente por classes definidas pelo usuário (para isso, use `Exception`). Se `str()` 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 retorno 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 `BufferError`

  Levantado quando uma operação relacionada a buffer não puder ser realizada.

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

## 5.2. Exceções concretas

As seguintes exceções são as que geralmente são levantados.

exception `AssertionError`

  Levantado quando uma instrução `assert` falha.

exception `AttributeError`

  Levantado quando uma referência de atributo (consulte attribute-reference) 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étodos `io.IOBase.read()` e `io.IOBase.readline()` retornam uma string vazia quando pressionam o EOF.)

exception `FloatingPointError`

  Raised when a floating point operation fails. This exception is always defined, but can only be raised when Python is configured with the `--with-fpectl` option, or the `WANT_SIGFPE_HANDLER` symbol is defined in the `pyconfig.h` file.

exception `GeneratorExit`

  Levantado quando gerador ou coroutine está fechado; veja `generator.close()` e `coroutine.close()`. Herda diretamente de `BaseException` em vez de `Exception`, já que tecnicamente não é um erro.

exception `ImportError`

  Levantado quando a instrução `import` tem problemas ao tentar carregar um módulo. Também é gerado quando o “from list” em `from ... import` tem um nome que não pode ser encontrado.

  Os atributos `name` e `path` podem ser configurados usando argumentos somente de palavra-chave 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` e `path`.

exception `ModuleNotFoundError`

  Uma subclasse de `ImportError` que é levantada por `import` quando um módulo não pôde ser localizado. Também é levantada quando `None` é encontrado em `sys.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 sileciosamente 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 tratam `Exception` 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` e `NotImplemented` não são intercambiáveis, mesmo que tenham nomes e propósitos similares. Veja `NotImplemented` 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 I/O 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 terão valor `None` se não forem especificads. Por compatibilidade com versões anteriores, se três argumentos são passados, o atributo `args` 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 de `errno`. Este comportamento ocorre apenas durante a construção direta ou por meio de um apelido de `OSError`, 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 atributo `winerror` não existe.

  `strerror`

    A mensagem de erro correspondente, conforme fornecida pelo sistema operacional. É formatada pelas funções C `perror()` no POSIX e `FormatMessage()` no Windows.

  `filename`
  `filename2`

    Para exceções que envolvem um caminho do sistema de arquivos (como `open()` ou `os.unlink()`), `filename` é o nome do arquivo passado para a função. Para funções que envolvem dois caminhos de sistema de arquivos (como: func: os.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` e `mmap.error` foram fundidos em `OSError`, 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 (veja `sys.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ódulo `weakref`.

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âmetro `value` para o construtor da exceção.

  If a generator function defined in the presence of a `from __future__ import generator_stop` directive raises `StopIteration`, it will be converted into a `RuntimeError` (retaining the `StopIteration` as the new exception’s cause).

  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: Introduced the RuntimeError transformation.

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`

  Levatada quando o analisador encontra um erro de sintaxe. Isso pode ocorrer em uma instrução `import`, em uma chamada às funções embutidas `exec()` ou `eval()`, ou ao ler o script inicial ou entrada padrão (também interativamente).

  Instâncias desta classe têm atributos `filename`, `lineno`, `offset` e `text` 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`

  Esta exceção é levantada pela função `sys.exit()`. Ele herda de `BaseException` em vez de exc:Exception para que não seja acidentalmente capturado pelo código que captura `Exception`. Isso permite que a exceção se propague corretamente e faça com que o interpretador saia. Quando não é tratado, o interpretador Python sai; nenhum traceback (situação da pilha de execução) é impresso. O construtor aceita o mesmo argumento opcional passado para `sys.exit()`. Se o valor for um inteiro, ele especifica o status de saída do sistema (passado para a função C `exit()`); se for `None`, o status de saída é zero; se tiver outro tipo (como uma string), o valor do objeto é exibido e o status de saída é um.

  Uma chamada para `sys.exit()` é traduzida em uma exceção para que os tratadores de limpeza (cláusulas :keyword:finally` das instruções `try`) possam ser executados, e para que um depurador possa executar um script sem correr o risco de perder o controle. A função `os._exit()` pode ser usada se for absolutamente necessário sair imediatamente (por exemplo, no processo filho após uma chamada para `os.fork()`).

  `code`

    O status de saída ou mensagem de erro transmitida ao construtor. (O padrão é `None`.)

exception `TypeError`

  Levantada quando uma operação ou função é aplicada a um objeto de tipo inadequado. O valor associado é uma string que fornece detalhes sobre a incompatibilidade de tipo.

  Essa exceção pode ser levantada pelo código do usuário para indicar que uma tentativa de operação em um objeto não é suportada e não deveria ser. Se um objeto deve ter suporte a uma dada operação, mas ainda não forneceu uma implementação, `NotImplementedError` é a exceção apropriada a ser levantada.

  Passar argumentos do tipo errado (por exemplo, passar uma `list` quando um `int` é esperado) deve resultar em uma `TypeError`, mas passar argumentos com o valor errado (por exemplo, um número fora limites esperados) deve resultar em uma `ValueError`.

exception `UnboundLocalError`

  Levantada quando uma referência é feita a uma variável local em uma função ou método, mas nenhum valor foi vinculado a essa variável. Esta é uma subclasse de `NameError`.

exception `UnicodeError`

  Levantada quando ocorre um erro de codificação ou decodificação relacionado ao Unicode. É uma subclasse de `ValueError`.

  `UnicodeError` possui atributos que descrevem o erro de codificação ou decodificação. Por exemplo, `err.object[err.start:err.end]` fornece a entrada inválida específica na qual o codec falhou.

  `encoding`

    O nome da codificação que levantou o erro.

  `reason`

    Uma string que descreve o erro de codec específico.

  `object`

    O objeto que o codec estava tentando codificar ou decodificar.

  `start`

    O primeiro índice de dados inválidos em `object`.

  `end`

    O índice após os últimos dados inválidos em `object`.

exception `UnicodeEncodeError`

  Levantada quando ocorre um erro relacionado ao Unicode durante a codificação. É uma subclasse de `UnicodeError`.

exception `UnicodeDecodeError`

  Levantada quando ocorre um erro relacionado ao Unicode durante a decodificação. É uma subclasse de `UnicodeError`.

exception `UnicodeTranslateError`

  Levantada quando ocorre um erro relacionado ao Unicode durante a tradução. É uma subclasse de `UnicodeError`.

exception `ValueError`

  Levantada quando uma operação ou função recebe um argumento que tem o tipo certo, mas um valor inadequado, e a situação não é descrita por uma exceção mais precisa, como `IndexError`.

exception `ZeroDivisionError`

  Levantada quando o segundo argumento de uma divisão ou operação de módulo é zero. O valor associado é uma string que indica o tipo dos operandos e a operação.

As seguintes exceções são mantidas para compatibilidade com versões anteriores; a partir do Python 3.3, eles são apelidos de `OSError`.

exception `EnvironmentError`

exception `IOError`

exception `WindowsError`

  Disponível apenas no Windows.

### 5.2.1. Exceções de sistema operacional

As seguintes exceções são subclasses de `OSError`, elas são levantadas dependendo do código de erro do sistema.

exception `BlockingIOError`

  Levantada quando uma operação bloquearia em um objeto (por exemplo, soquete) definido para operação sem bloqueio. Corresponde a `errno` `EAGAIN`, `EALREADY`, `EWOULDBLOCK` e `EINPROGRESS`.

  Além daquelas de `OSError`, `BlockingIOError` pode ter mais um atributo:

  `characters_written`

    Um inteiro contendo o número de caracteres gravados no fluxo antes de ser bloqueado. Este atributo está disponível ao usar as classes de E/S em buffer do módulo `io`.

exception `ChildProcessError`

  Levantada quando uma operação em um processo filho falha. Corresponde a `errno` `ECHILD`.

exception `ConnectionError`

  Uma classe base para problemas relacionados à conexão.

  Suas subclasses são `BrokenPipeError`, `ConnectionAbortedError`, `ConnectionRefusedError` e `ConnectionResetError`.

exception `BrokenPipeError`

  Uma subclasse de `ConnectionError`, levantada ao tentar escrever em um encadeamento enquanto a outra extremidade foi fechada, ou tentar escrever em um soquete que foi desligado para escrita. Corresponde a `errno` `EPIPE` e `ESHUTDOWN`.

exception `ConnectionAbortedError`

  Uma subclasse de `ConnectionError`, levantada quando uma tentativa de conexão é cancelada pelo par. Corresponde a `errno` `ECONNABORTED`.

exception `ConnectionRefusedError`

  Uma subclasse de `ConnectionError`, levantada quando uma tentativa de conexão é recusada pelo par. Corresponde a `errno` `ECONNREFUSED`.

exception `ConnectionResetError`

  Uma subclasse de `ConnectionError`, levantada quando a conexão é reiniciada pelo par. Corresponde a `errno` `ECONNRESET`.

exception `FileExistsError`

  Levantada ao tentar criar um arquivo ou diretório que já existe. Corresponde a `errno` `EEXIST`.

exception `FileNotFoundError`

  Levantada quando um arquivo ou diretório é solicitado, mas não existe. Corresponde a `errno` `ENOENT`.

exception `InterruptedError`

  Levantada quando uma chamada do sistema é interrompida por um sinal de entrada. Corresponde a `errno` `EINTR`.

  Alterado na versão 3.5: Python agora tenta novamente chamadas de sistema quando uma syscall é interrompida por um sinal, exceto se o tratador de sinal levanta uma exceção (veja PEP 475 para a justificativa), em vez de levantar `InterruptedError`.

exception `IsADirectoryError`

  Levantada quando uma operação de arquivo (como `os.remove()`) é solicitada em um diretório. Corresponde a `errno` `EISDIR`.

exception `NotADirectoryError`

  Levantada quando uma operação de diretório (como `os.listdir()`) é solicitada em algo que não é um diretório. Corresponde a `errno` `ENOTDIR`.

exception `PermissionError`

  Levantada ao tentar executar uma operação sem os direitos de acesso adequados – por exemplo, permissões do sistema de arquivos. Corresponde a `errno` `EACCES` e `EPERM`.

exception `ProcessLookupError`

  Levantada quando um determinado processo não existe. Corresponde a `errno` `ESRCH`.

exception `TimeoutError`

  Levantada quando uma função do sistema expirou no nível do sistema. Corresponde a `errno` `ETIMEDOUT`.

Novo na versão 3.3: Todas as subclasses de `OSError` acima foram adicionadas.

Ver também

PEP 3151 - Reworking the OS and IO exception hierarchy

## 5.3. Avisos

The following exceptions are used as warning categories; see the `warnings` module for more information.

exception `Warning`

  Classe base para categorias de aviso.

exception `UserWarning`

  Classe base para avisos gerados pelo código do usuário.

exception `DeprecationWarning`

  Base class for warnings about deprecated features.

exception `PendingDeprecationWarning`

  Base class for warnings about features which will be deprecated in the future.

exception `SyntaxWarning`

  Classe base para avisos sobre sintaxe duvidosa.

exception `RuntimeWarning`

  Classe base para avisos sobre comportamento duvidoso de tempo de execução.

exception `FutureWarning`

  Base class for warnings about constructs that will change semantically in the future.

exception `ImportWarning`

  Classe base para avisos sobre prováveis erros na importação de módulos.

exception `UnicodeWarning`

  Classe base para avisos relacionados a Unicode.

exception `BytesWarning`

  Classe base para avisos relacionados a `bytes` e `bytearray`.

exception `ResourceWarning`

  Classe base para avisos relacionados a uso de recursos.

  Novo na versão 3.2.

## 5.4. Hierarquia das exceções

A hierarquia de classes para exceções embutidas é:

    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