Exceptions KeyError en Python et comment les corriger

Même les programmeurs les plus chevronnés commettent des erreurs. En Python, ces erreurs se répartissent en deux catégories : erreurs et exceptions.

Les erreurs sont principalement liées à la syntaxe. Il faut les corriger pour que le programme s’exécute. Une exception, en revanche, survient lorsque le code est syntaxiquement correct, mais qu’un imprévu interrompt le programme pendant son exécution. 

Dans ce tutoriel, nous allons étudier l’une des exceptions les plus fréquentes, que rencontrent aussi bien les débutants que les développeurs expérimentés : l’exception KeyError. Nous détaillerons le fonctionnement de KeyError en Python, avec des exemples et différentes techniques pour la gérer. Si vous souhaitez apprendre à identifier et corriger les erreurs en Python, consultez aussi notre tutoriel Exception & error handling in Python. 

Qu’est-ce qu’une exception KeyError ?

En Python, une exception KeyError fait partie des exceptions natives conçues pour couvrir de nombreux cas d’erreur courants. Elle peut être vue comme une sous-classe, avec IndexError, de l’exception plus générale LookupError, toutes étant des objets de la classe Exception.

Concrètement, une KeyError est levée lorsqu’un programme tente d’accéder à une clé qui n’existe pas dans un dictionnaire. Un dictionnaire est une structure de données qui stocke des informations sous forme de paires clé‑valeur, et l’on accède à la valeur via sa clé — d’où le nom KeyError. 

Causes fréquentes de KeyError en Python et exemples

Prenons un exemple avec un dictionnaire de pays et leurs capitales :

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

Pour interroger notre dictionnaire, il suffit d’indiquer la clé entre crochets ; Python renverra la valeur associée.

dictionary_capitals['Madrid']

'Spain'

Si nous essayons d’accéder à une clé absente du dictionnaire, Python renverra un message d’erreur KeyError. 

dictionary_capitals['Rome']

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

On peut aussi rencontrer une KeyError lorsqu’on accède à des clés inexistantes dans d’autres objets de type mappage qui se comportent comme des dictionnaires. Par exemple, l’objet os.environ renvoie un dictionnaire qui stocke les variables d’environnement de l’utilisateur comme clés avec leurs valeurs associées.

Dans le code ci-dessous, nous tentons d’accéder à la valeur associée à la clé USERS dans os.environ. Comme USERS n’est pas présent dans ce dictionnaire, Python lève une KeyError.

# Appel d'une variable d'environnement inexistante
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'

Les dictionnaires sont omniprésents en Python. Autre exemple : l’implémentation d’une structure plus abstraite appelée hashmap. Pour en savoir plus, consultez notre tutoriel Guide to Python hashmaps.

Gérer les exceptions KeyError en Python

Voyons comment gérer les KeyError. Deux stratégies s’offrent à nous : prévenir la survenue d’un KeyError ou intercepter le KeyError via la gestion d’exceptions. 

Prévenir les KeyError

Comme nous l’avons vu, Python lèvera une KeyError si nous accédons à une clé inexistante. Pour l’éviter, nous pouvons utiliser la méthode .get() pour accéder aux clés d’un dictionnaire et rendre notre code plus tolérant. Avec cette méthode, si la clé n’existe pas, Python renvoie None au lieu d’une KeyError. C’est une bonne approche de base.

print(dictionary_capitals.get('Prague'))

None

Autre possibilité : vérifier l’existence de la clé avant d’y accéder. Cette façon de prévenir les exceptions est connue sous le nom de « Look Before You Leap » (LBYL). Ici, on peut utiliser des instructions if pour vérifier si la clé existe et, si ce n’est pas le cas, traiter le problème dans le bloc 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)) 

Intercepter KeyError avec la gestion d’exceptions

La seconde approche est connue sous le nom « Easier to Ask Forgiveness Than Permission » (EAFP). C’est d’ailleurs la manière la plus courante de gérer les exceptions en Python. 

Adopter le style EAFP consiste à supposer que les clés existent et à intercepter les exceptions si cette hypothèse s’avère fausse. Alors que l’approche LBYL repose sur des blocs if/else, l’approche EAFP utilise des blocs try/except. 

Dans l’exemple suivant, au lieu de vérifier si la clé est présente, nous essayons directement d’y accéder. Si, pour une raison quelconque, la clé n’existe pas, nous intercepterons la KeyError dans le bloc except et la traiterons de manière appropriée.

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

Gestion avancée des KeyError en Python

Utiliser defaultdict pour gérer automatiquement les clés

Nous avons vu que, chaque fois que nous tentons d’accéder à une clé absente du dictionnaire, Python renvoie une KeyError. La méthode .get() est une approche tolérante aux erreurs qui fonctionne, mais elle n’est pas optimale.

Le module collections propose defaultdict, une solution plus efficace pour gérer les entrées des dictionnaires. Contrairement aux dictionnaires standards qui lèvent une KeyError lorsqu’on accède à une clé inexistante, un defaultdict permet de définir une valeur par défaut renvoyée quand la clé est introuvable. Le code suivant montre comment importer defaultdict depuis collections et définir une valeur par défaut avec une fonction lambda. Si les fonctions lambda vous laissent perplexe, consultez notre tutoriel Python lambda tutorial.

from collections import defaultdict 

# Définition du 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

Lever volontairement des KeyError

Enfin, dans certaines situations, il peut être pertinent de lever volontairement une KeyError pour faire respecter des contraintes.

Souvent, des fonctions dépendent de la présence de données spécifiques pour fonctionner correctement. Déclencher manuellement une KeyError garantit que la fonction échoue de manière claire et prévisible lorsque des données indispensables manquent. Dans ces cas, le message d’erreur associé à la KeyError indique précisément ce qui ne va pas dans l’entrée fournie, ce qui facilite le débogage.

Illustrons avec un exemple. Nous créons une fonction qui prend un dictionnaire en argument. L’utilisateur doit fournir un dictionnaire avec les bonnes clés pour que la fonction fonctionne correctement. Nous encapsulons cette vérification dans une fonction afin d’être alertés immédiatement si des clés manquent, plutôt que de laisser l’erreur se propager plus loin dans le code. 

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')

Conclusion

Nous espérons que cet article vous a été utile. KeyError fait partie des exceptions les plus courantes auxquelles un développeur Python sera confronté. Maîtriser l’art de la gestion des erreurs et des exceptions est essentiel pour devenir un·e excellent·e programmeur·se Python. Approfondissez d’autres techniques de programmation fonctionnelle et les fondamentaux du code avec nos parcours de compétences Python Programming et Python Fundamentals. Consultez également notre tutoriel Python sets and set theory pour explorer des notions connexes.