Exceções do Python KeyError e como corrigi-las

Até mesmo os programadores mais experientes cometem erros de codificação. Para os programadores de Python, esses erros se enquadram em uma de duas categorias: erros ou exceções.

Os erros estão relacionados principalmente à sintaxe. Eles devem ser corrigidos para que o programa seja executado. Uma exceção, por outro lado, ocorre quando o código está sintaticamente correto, mas algo interrompe o programa quando ele está em execução. 

Neste tutorial, examinaremos uma das exceções mais comuns encontradas por programadores novos e experientes: a exceção KeyError. Abordaremos os detalhes do site KeyError do Python, fornecendo exemplos e diferentes técnicas para lidar com esse tipo de exceção. Se você quiser aprender a identificar e corrigir erros em Python, confira também nosso tutorial Exception & Error Handling in Python. 

O que é uma exceção KeyError?

Em Python, a exceção KeyError é uma das exceções internas projetadas para lidar com uma ampla gama de condições de erro comuns. Uma exceção KeyError pode ser entendida como uma subclasse, juntamente com IndexError, da exceção LookupError mais geral, todas elas objetos da classe Exception.

Especificamente, uma exceção KeyError é gerada quando um programador tenta acessar uma chave que não existe em um dicionário. Um dicionário, para referência, é uma estrutura de dados que armazena dados em pares de valores-chave, e o valor em um dicionário é acessado por meio de sua chave - daí o nome, KeyError. 

Python KeyError Causas comuns e exemplos

Vejamos um exemplo usando um dicionário de países e suas capitais:

dictionary_capitals = {'Madrid': 'Spain',
 'Lisboa': 'Portugal', 'London': 'United Kingdom'}

Para pesquisar informações em nosso dicionário, precisamos especificar a chave entre colchetes e o Python retornará o valor associado.

dictionary_capitals['Madrid']

'Spain'

Se tentarmos acessar uma chave que não está no dicionário, o Python nos dará a nossa mensagem de erro de exceção KeyError. 

dictionary_capitals['Rome']

Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
KeyError: 'Rome'

Também podemos encontrar a exceção KeyError quando tentamos acessar chaves inexistentes em outros objetos de mapeamento do Python que adotam a forma de um dicionário. Por exemplo, o objeto os.environ retorna um dicionário que armazena as variáveis ambientais do usuário como chaves, juntamente com seus valores associados.

No código a seguir, tentamos acessar o valor associado à chave USERS no dicionário os.environ. Como USERS não estava no dicionário os.environ, nosso código nos dá um KeyError.

#Calling a non-existent environmental variable
os.environ['USERS']
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/Library/Frameworks/Python.framework/Versions/3.9/lib/python3.9/os.py", line 679, in __getitem__
    raise KeyError(key) from None
KeyError: 'USERS'

Como você pode ver, os dicionários são muito comuns em Python. Outro exemplo é a implementação de algo mais abstrato chamado hashmap. Para saber mais sobre hashmaps, consulte nosso tutorial Guide to Python Hashmaps.

Como lidar com as exceções KeyError do Python

Vamos explorar os métodos para lidar com as exceções do KeyError. Temos duas estratégias: Podemos evitar KeyError ou capturar KeyError com o tratamento de erros. 

Prevenção de KeyError

Como vimos, o Python lançará um KeyError se tentarmos acessar uma chave inexistente. Para evitar isso, podemos acessar as chaves em um dicionário usando o método .get() para tornar nosso código mais tolerante. Se, ao usar esse método, você encontrar uma chave inexistente, o Python retornará um valor None em vez de um KeyError. Essa é uma boa abordagem.

print(dictionary_capitals.get('Prague'))

None

Como alternativa, poderíamos verificar se uma chave existe antes de acessá-la. Essa maneira de evitar exceções é conhecida como "Look Before You Leap" (Olhe antes de pular), ou LBYL, para abreviar. Nesse caso, poderíamos usar as instruções if para verificar se a chave existe e, se não existir, podemos tratar o problema na cláusula else.

capital = "Prague"
if capital in dictionary_capitals.keys():
    value = dictionary_capitals[capital]
else:
    print("The key {} is not present in the dictionary".format(capital)) 

Captura de KeyError com tratamento de exceções

Uma segunda abordagem é conhecida como "É mais fácil pedir perdão do que permissão". O EAFP, como é chamado, é na verdade a maneira mais padrão de lidar com exceções no Python. 

A adoção do estilo de codificação EAFP significa que assumimos a existência de chaves válidas e capturamos exceções se a suposição for falsa. Enquanto a nossa abordagem LBYL se baseia em declarações if/else, a abordagem EAFP se baseia em cláusulas try/except. 

No exemplo a seguir, em vez de verificar se a chave está presente, tentamos acessar a chave desejada. Se, por algum motivo, a chave não estiver presente, então apenas capturamos o KeyError na cláusula except e o tratamos adequadamente.

capital = "Prague"
try:
     value = dictionary_capitals[capital]
except KeyError:
     print("The key {} is not present in the dictionary".format(capital)) 

Gerenciamento avançado de KeyError em Python

Uso do defaultdict para tratamento automático de chaves

Vemos que, sempre que tentarmos acessar uma chave que não está presente em nosso dicionário, o Python retornará uma exceção KeyError. O método .get() que analisamos foi uma abordagem tolerante a erros que funcionou bem, mas não foi otimizada.

O módulo Collections oferece defaultdict, que é uma abordagem mais otimizada para lidar com entradas de dicionário. Ao contrário dos dicionários padrão que lançam um KeyError se tentarmos acessar uma chave inexistente, um defaultdict nos permite especificar um valor padrão que é retornado sempre que uma chave não é encontrada. O código a seguir mostra como você pode importar defaultdict de Collections e criar um valor padrão com uma função lambda. Se você estiver confuso sobre as funções lambda, consulte nosso Tutorial de lambda do Python para saber mais.

from collections import defaultdict 

# Defining the dict 
capitals = defaultdict(lambda: "The key doesn't exist") 
capitals['Madrid'] = 'Spain'
capitals['Lisboa'] = 'Portugal'
print(capitals['Madrid']) 
print(capitals['Lisboa']) 
print(capitals['Ankara'])

Spain
Portugal
The key doesn't exist

Levantamento de KeyErrors deliberadamente

Por fim, devemos dizer que, em algumas circunstâncias, pode ser apropriado criar deliberadamente um KeyError para impor determinadas restrições.

Sabemos que, em muitos casos, as funções dependem da disponibilidade de dados específicos para realizar suas operações. Portanto, o acionamento manual de um KeyError garante que a função falhe de forma clara e previsível quando os dados necessários estiverem faltando. Nesses casos, a mensagem de erro fornecida pelo site KeyError nos ajuda a entender exatamente o que estava errado com a entrada fornecida, o que facilita a depuração.

Vamos esclarecer com um exemplo. Aqui, criamos uma função que recebe um dicionário como argumento. O usuário precisa fornecer ao dicionário as chaves corretas para que a função funcione corretamente. Criamos uma função nesse caso porque queremos saber imediatamente se as chaves estão faltando, em vez de permitir que os erros persistam mais adiante no código. 

def my_function(my_dict): 
    if 'critical_key' not in my_dict: 
        raise KeyError('critical_key is missing from the dictionary. Please modify the dictionary')

Conclusão

Esperamos que você tenha gostado deste artigo. KeyError é uma das exceções mais comuns que um desenvolvedor Python encontrará. Dominar a arte de lidar com erros e exceções é uma parte fundamental para que você se torne um programador Python forte. Saiba mais sobre outras técnicas de programação funcional e outros fundamentos de codificação com nossas trilhas de habilidades Python Programming e Python Fundamentals. Além disso, confira nosso tutorial Python Sets and Set Theory para saber mais sobre os conceitos adjacentes.