Noms de variables Python — Règles, conventions et bonnes pratiques

Un nom de variable est l'étiquette que Python utilise pour retrouver une valeur en mémoire. Choisissez de bons noms et votre code se lit presque comme une phrase ; choisissez de mauvais noms et même vous aurez du mal à comprendre votre propre script une semaine plus tard. Ce chapitre couvre les règles strictes imposées par Python, les conventions informelles suivies par la communauté (PEP 8), les pièges comme l'éclipse des fonctions intégrées, et les motifs de soulignement spéciaux — le tout avec des exemples exécutables.

Règles strictes — Ce que Python impose

Avant les conventions, il y a des règles. Les enfreindre provoque une SyntaxError ou une NameError.

Caractères autorisés

Un nom de variable peut contenir des lettres (a-z, A-Z), des chiffres (0-9) et des tirets bas (_). Il doit commencer par une lettre ou un tiret bas — jamais par un chiffre. Les espaces, les traits d'union et les caractères spéciaux (%, #, @, -) ne sont pas autorisés.

# Valid names
user_name = "Alice"
_private = 42
value1 = 3.14
MAX_RETRIES = 5

# Invalid names — these all raise SyntaxError
# 1user = "bad"     # starts with a digit
# user-name = "bad" # hyphens are subtraction
# user name = "bad" # space is not allowed

Python est sensible à la casse

username, Username et USERNAME sont trois variables complètement différentes. C'est une source fréquente de bogues pour les débutants.

score = 10
Score = 20
SCORE = 30

print(score)   # 10
print(Score)   # 20
print(SCORE)   # 30

Les mots-clés réservés ne peuvent pas être utilisés comme noms

Python réserve certains mots pour le langage lui-même. En utiliser un comme nom de variable provoque une SyntaxError. Vous pouvez lister tous les mots-clés réservés avec le module keyword :

import keyword
print(keyword.kwlist)

Résultat (Python 3.12) :

['False', 'None', 'True', 'and', 'as', 'assert', 'async', 'await',
 'break', 'class', 'continue', 'def', 'del', 'elif', 'else', 'except',
 'finally', 'for', 'from', 'global', 'if', 'import', 'in', 'is',
 'lambda', 'nonlocal', 'not', 'or', 'pass', 'raise', 'return', 'try',
 'while', 'with', 'yield']

Erreurs courantes : utiliser list, str, int, type ou input comme noms de variables — ce sont des noms intégrés, pas des mots-clés réservés, donc Python ne lèvera pas de SyntaxError, mais vous éclipserez silencieusement la fonction intégrée et obtiendrez des erreurs déconcertantes plus tard (voir Éclipse des fonctions intégrées ci-dessous).

Conventions de nommage PEP 8

PEP 8 est le guide de style officiel de Python. Le suivre rend votre code immédiatement lisible par tout développeur Python.

Résumé des conventions

snake_case pour les variables et les fonctions

Le snake_case utilise des lettres en minuscules avec des tirets bas entre les mots. C'est le standard pour les variables et les fonctions en Python.

# PEP 8 compliant
first_name = "Alice"
last_name = "Smith"
total_price = 9.99
items_in_cart = 3

# Not PEP 8 (camelCase) — works, but avoid for variables
firstName = "Alice"   # JavaScript style, not Pythonic

ALL_CAPS pour les constantes

Par convention, un nom écrit entièrement en majuscules signale « cette valeur ne doit pas être modifiée ». Python n'impose pas l'immuabilité, mais la convention est universellement comprise.

MAX_CONNECTIONS = 100
TIMEOUT_SECONDS = 30
PI = 3.141592653589793

# Using the constant
if current_connections > MAX_CONNECTIONS:
    print("Connection limit reached")

CapWords pour les classes

Les noms de classes utilisent CapWords (également appelé PascalCase) : chaque mot commence par une lettre majuscule, sans tiret bas.

class UserProfile:
    pass

class HttpRequestError(Exception):
    pass

Noms descriptifs et significatifs

Le meilleur nom de variable dit au prochain lecteur ce que la valeur représente, et non comment elle est stockée. Visez des noms qui font lire une ligne de code comme une phrase.

# Unclear
r = 5
a = 3.14159 * r ** 2

# Clear
radius = 5
circle_area = 3.14159 * radius ** 2

print(circle_area)  # 78.53975

Quand les noms courts sont acceptables

Les noms d'une seule lettre (x, y, i, n) sont acceptables dans des contextes restreints et bien compris :

• Compteurs de boucle : for i in range(10):
• Formules mathématiques : y = m * x + b
• Coordonnées : (x, y) ou (row, col)

En dehors de ces contextes, préférez quelque chose de descriptif, même si c'est plus long.

Évitez les abréviations inutiles

Les abréviations économisent des frappes mais nuisent à la lisibilité. Utilisez des mots complets, sauf si l'abréviation est universellement connue.

# Unclear abbreviations
usr_nm = "alice"
tot_amt = 49.95
n_itm = 7

# Clear full names
username = "alice"
total_amount = 49.95
number_of_items = 7

Abréviations largement acceptées qu'il est acceptable de conserver : url, id, http, db, idx, num.

Motifs de soulignement

Python utilise les tirets bas dans les noms de variables pour communiquer une intention. Comprendre ces motifs vous aide à lire n'importe quelle base de code Python.

_single_leading — usage interne

Un nom commençant par un tiret bas est un signal aux autres développeurs : « ceci est un détail d'implémentation ; ne vous y fiez pas depuis l'extérieur de ce module ou de cette classe. » Python ne l'impose pas — c'est purement une convention.

class DataLoader:
    def __init__(self, path):
        self.path = path
        self._cache = {}   # internal; not part of the public API

    def load(self):
        if self.path not in self._cache:
            self._cache[self.path] = self._read_file()
        return self._cache[self.path]

    def _read_file(self):
        # "private" helper
        with open(self.path) as f:
            return f.read()

from module import * ignore également les noms qui commencent par _.

__double_leading — name mangling

Deux tirets bas au début déclenchent le name mangling de Python : __attr dans la classe Foo est stocké sous le nom _Foo__attr. Cela évite les écrasements accidentels dans les sous-classes.

class Base:
    def __init__(self):
        self.__secret = "hidden"

obj = Base()
# print(obj.__secret)      # AttributeError
print(obj._Base__secret)   # "hidden" — mangled name

Utilisez le name mangling avec parcimonie ; il rend le débogage plus difficile.

__dunder__ — méthodes spéciales

Les noms encadrés de deux tirets bas de chaque côté sont les méthodes et attributs spéciaux intégrés de Python (« dunder »). N'inventez jamais vos propres variables __name__ — Python réserve cet espace de noms.

class Point:
    def __init__(self, x, y):   # called when an instance is created
        self.x = x
        self.y = y

    def __repr__(self):          # called by repr() and in the REPL
        return f"Point({self.x}, {self.y})"

p = Point(3, 4)
print(p)          # Point(3, 4)
print(repr(p))    # Point(3, 4)

_ comme variable jetable

Un tiret bas seul _ est utilisé par convention comme variable « poubelle » lorsque vous devez capturer une valeur mais ne l'utiliserez pas.

# Unpack a tuple but only use two of three values
x, _, z = (1, 2, 3)
print(x, z)  # 1 3

# Loop counter when the index is not needed
for _ in range(5):
    print("hello")

Éclipse des fonctions intégrées

Les noms intégrés de Python (list, str, int, dict, type, input, print, id, min, max, sum, open, …) ne sont pas des mots-clés, donc Python vous laisse silencieusement les réutiliser comme noms de variables. C'est presque toujours un bogue.

# Dangerous — shadows the built-in list type
list = [1, 2, 3]
print(list)           # [1, 2, 3] — seems fine

new = list([4, 5])    # TypeError: 'list' object is not callable

Une fois que vous assignez list = [1, 2, 3], le nom list dans cette portée ne désigne plus le constructeur intégré. La correction consiste simplement à choisir un nom différent.

# Safe
numbers = [1, 2, 3]
more_numbers = list([4, 5])  # list() still works
print(more_numbers)          # [4, 5]

Fonctions intégrées couramment éclipsées par accident : id, input, type, str, int, float, list, dict, set, tuple, min, max, sum, filter, map, open, print.

Portée et noms de variables

Le nom d'une variable n'est visible qu'au sein de la portée où elle est définie. Deux variables dans des portées différentes peuvent partager le même nom sans conflit — mais cela peut prêter à confusion.

total = 0          # module-level variable

def calculate(prices):
    total = 0      # local variable — does NOT overwrite the module-level one
    for price in prices:
        total += price
    return total

result = calculate([10, 20, 30])
print(result)      # 60
print(total)       # 0  — unchanged

Pour en savoir plus sur la façon dont Python résout les noms (la règle LEGB), consultez Portée Python. Pour comprendre les variables globales et le mot-clé global, consultez Variables globales en Python.

Référence rapide

# Hard rules
user1 = "ok"        # letters, digits, underscores — fine
_private = "ok"     # leading underscore — fine
# 1user = "bad"     # SyntaxError: starts with digit
# my-var = "bad"    # SyntaxError: hyphens not allowed

# PEP 8 conventions
snake_case_var = 42           # variables and functions
MAX_VALUE = 100               # constants
# class names use CapWords (PascalCase)

# Underscore patterns
_internal = "internal use"    # single leading: hint "private"
_ = "throwaway"               # lone underscore: discard value

# What to avoid
# list = []      # shadows built-in
# str = "hello"  # shadows built-in
# if = True      # SyntaxError: reserved keyword

Pour une introduction plus large à la façon dont les variables sont créées et affectées en Python, consultez Variables Python. Pour savoir comment regrouper des variables liées, consultez Regrouper des variables en Python.

Pratique