Vous êtes sur la page 1sur 1058

Le tutoriel Python

Python est un langage de programmation puissant et facile à apprendre. Il dispose


de structures de données de haut niveau et permet une approche simple mais
efficace de la programmation orientée objet. Parce que sa syntaxe est élégante, que
son typage est dynamique et qu'il est interprété, Python est un langage idéal pour
l'écriture de scripts et le développement rapide d'applications dans de nombreux
domaines et sur la plupart des plateformes.

L'interpréteur Python et sa vaste bibliothèque standard sont disponibles librement,


sous forme de sources ou de binaires, pour toutes les plateformes majeures depuis
le site Internet https://www.python.org/ et peuvent être librement redistribués. Ce
même site distribue et pointe vers des modules, des programmes et des outils tiers.
Enfin, il constitue une source de documentation.

L'interpréteur Python peut être facilement étendu par de nouvelles fonctions et types
de données implémentés en C ou C++ (ou tout autre langage appelable depuis le C).
Python est également adapté comme langage d'extension pour personnaliser des
applications.

Dans ce tutoriel, nous introduisons, de façon informelle, les concepts de base ainsi
que les fonctionnalités du langage Python et de son écosystème. Il est utile de
disposer d'un interpréteur Python à portée de main pour mettre en pratique les
notions abordées. Si ce n'est pas possible, pas de souci, les exemples sont inclus et
le tutoriel est adapté à une lecture "hors ligne".

Pour une description des objets et modules de la bibliothèque standard, reportez-


vous à La bibliothèque standard. La référence du langage Python présente le
langage de manière plus formelle. Pour écrire des extensions en C ou en C++,
lisez Extension et intégration de l'interpréteur Python et Manuel de référence de l'API
Python/C. Des livres sont également disponibles qui couvrent Python dans le détail.

L'ambition de ce tutoriel n'est pas d'être exhaustif et de couvrir chaque fonctionnalité,


ni même toutes les fonctionnalités les plus utilisées. Il vise, en revanche, à introduire
les fonctionnalités les plus notables et à vous donner une bonne idée de la saveur et
du style du langage. Après l'avoir lu, vous serez capable de lire et d'écrire des
modules et des programmes Python et vous serez prêt à en apprendre davantage
sur les modules de la bibliothèque Python décrits dans La bibliothèque standard.

Pensez aussi à consulter le Glossaire.

 1. Mise en bouche
 2. Mode d'emploi de l'interpréteur Python
o 2.1. Lancement de l'interpréteur
 2.1.1. Passage d'arguments
 2.1.2. Mode interactif
o 2.2. L'interpréteur et son environnement
 2.2.1. Encodage du code source
 3. Introduction informelle à Python
o 3.1. Utilisation de Python comme une calculatrice
 3.1.1. Les nombres
 3.1.2. Chaînes de caractères
 3.1.3. Listes
o 3.2. Premiers pas vers la programmation
 4. D'autres outils de contrôle de flux
o 4.1. L'instruction if
o 4.2. L'instruction for
o 4.3. La fonction range()
o 4.4. Les instructions break, continue et les clauses else au sein des
boucles
o 4.5. L'instruction pass
o 4.6. Définir des fonctions
o 4.7. D'avantage sur la définition des fonctions
 4.7.1. Valeur par défaut des arguments
 4.7.2. Les arguments nommés
 4.7.3. Listes d'arguments arbitraires
 4.7.4. Séparation des listes d'arguments
 4.7.5. Fonctions anonymes
 4.7.6. Chaînes de documentation
 4.7.7. Annotations de fonctions
o 4.8. Aparté : le style de codage
 5. Structures de données
o 5.1. Compléments sur les listes
 5.1.1. Utilisation des listes comme des piles
 5.1.2. Utilisation des listes comme des files
 5.1.3. Compréhensions de listes
 5.1.4. Compréhensions de listes imbriquées
o 5.2. L'instruction del
o 5.3. Tuples et séquences
o 5.4. Ensembles
o 5.5. Dictionnaires
o 5.6. Techniques de boucles
o 5.7. Plus d'informations sur les conditions
o 5.8. Comparer des séquences avec d'autres types
 6. Modules
o 6.1. Les modules en détail
 6.1.1. Exécuter des modules comme des scripts
 6.1.2. Les dossiers de recherche de modules
 6.1.3. Fichiers Python "compilés"
o 6.2. Modules standards
o 6.3. La fonction dir()
o 6.4. Les paquets
 6.4.1. Importer * depuis un paquet
 6.4.2. Références internes dans un paquet
 6.4.3. Paquets dans plusieurs dossiers
 7. Les entrées/sorties
o 7.1. Formatage de données
 7.1.1. Les chaines de caractères formatées (f-strings)
 7.1.2. La méthode de chaine de caractères format()
 7.1.3. Formatage de chaînes à la main
 7.1.4. Anciennes méthodes de formatage de chaînes
o 7.2. Lecture et écriture de fichiers
 7.2.1. Méthodes des objets fichiers
 7.2.2. Sauvegarde de données structurées avec le module  json
 8. Erreurs et exceptions
o 8.1. Les erreurs de syntaxe
o 8.2. Exceptions
o 8.3. Gestion des exceptions
o 8.4. Déclencher des exceptions
o 8.5. Exceptions définies par l'utilisateur
o 8.6. Définition d'actions de nettoyage
o 8.7. Actions de nettoyage prédéfinies
 9. Classes
o 9.1. Objets et noms : préambule
o 9.2. Portées et espaces de nommage en Python
 9.2.1. Exemple de portées et d'espaces de nommage
o 9.3. Une première approche des classes
 9.3.1. Syntaxe de définition des classes
 9.3.2. Objets classes
 9.3.3. Objets instances
 9.3.4. Objets méthode
 9.3.5. Classes et variables d'instance
o 9.4. Remarques diverses
o 9.5. Héritage
 9.5.1. Héritage multiple
o 9.6. Variables privées
o 9.7. Trucs et astuces
o 9.8. Itérateurs
o 9.9. Générateurs
o 9.10. Expressions et générateurs
 10. Survol de la bibliothèque standard
o 10.1. Interface avec le système d'exploitation
o 10.2. Jokers sur les noms de fichiers
o 10.3. Paramètres passés en ligne de commande
o 10.4. Redirection de la sortie d'erreur et fin d'exécution
o 10.5. Recherche de motifs dans les chaînes
o 10.6. Mathématiques
o 10.7. Accès à internet
o 10.8. Dates et heures
o 10.9. Compression de données
o 10.10. Mesure des performances
o 10.11. Contrôle qualité
o 10.12. Piles fournies
 11. Survol de la bibliothèque standard -- Deuxième partie
o 11.1. Formatage de l'affichage
o 11.2. Gabarits (templates en anglais)
o 11.3. Traitement des données binaires
o 11.4. Fils d'exécution
o 11.5. Journalisation
o 11.6. Références faibles
o 11.7. Outils pour les listes
o 11.8. Arithmétique décimale à virgule flottante
 12. Environnements virtuels et paquets
o 12.1. Introduction
o 12.2. Création d'environnements virtuels
o 12.3. Gestion des paquets avec  pip
 13. Pour aller plus loin
 14. Édition interactive des entrées et substitution d'historique
o 14.1. Complétion automatique et édition de l'historique
o 14.2. Alternatives à l'interpréteur interactif
 15. Arithmétique en nombres à virgule flottante  : problèmes et limites
o 15.1. Erreurs de représentation
 16. Annexe
o 16.1. Mode interactif
 16.1.1. Gestion des erreurs
 16.1.2. Scripts Python exécutables
 16.1.3. Configuration du mode interactif
 16.1.4. Modules de personnalisation
1. Mise en bouche
Lorsqu'on travaille beaucoup sur ordinateur, on finit souvent par vouloir automatiser
certaines tâches : par exemple, effectuer une recherche et un remplacement sur un
grand nombre de fichiers de texte ; ou renommer et réorganiser des photos d'une
manière un peu compliquée. Pour vous, ce peut être créer une petite base de
données, une application graphique ou un simple jeu.

Quand on est un développeur professionnel, le besoin peut se faire sentir de


travailler avec des bibliothèques C/C++/Java, mais on trouve que le cycle habituel
écriture/compilation/test/compilation est trop lourd. Vous écrivez peut-être une suite
de tests pour une telle bibliothèque et vous trouvez que l'écriture du code de test est
pénible. Ou bien vous avez écrit un logiciel qui a besoin d'être extensible grâce à un
langage de script, mais vous ne voulez pas concevoir ni implémenter un nouveau
langage pour votre application.

Python est le langage parfait pour vous.

Vous pouvez écrire un script shell Unix ou des fichiers batch Windows pour certaines
de ces tâches. Les scripts shell sont appropriés pour déplacer des fichiers et modifier
des données textuelles, mais pas pour une application ayant une interface graphique
ni pour des jeux. Vous pouvez écrire un programme en C/C++/Java, mais cela peut
prendre beaucoup de temps, ne serait-ce que pour avoir une première maquette.
Python est plus facile à utiliser et il vous aidera à terminer plus rapidement votre
travail, que ce soit sous Windows, Mac OS X ou Unix.

Python reste facile à utiliser, mais c'est un vrai langage de programmation : il offre
une bien meilleure structure et prise en charge des grands programmes que les
scripts shell ou les fichiers batch. Par ailleurs, Python permet de beaucoup mieux
vérifier les erreurs que le langage C et, en tant que langage de très haut niveau, il
possède nativement des types de données très évolués tels que les tableaux de
taille variable ou les dictionnaires. Grâce à ses types de données plus universels,
Python est utilisable pour des domaines beaucoup plus variés que ne peuvent
l'être Awk ou même Perl. Pourtant, vous pouvez faire de nombreuses choses au
moins aussi facilement en Python que dans ces langages.

Python vous permet de découper votre programme en modules qui peuvent être
réutilisés dans d'autres programmes Python. Il est fourni avec une grande variété de
modules standards que vous pouvez utiliser comme base de vos programmes, ou
comme exemples pour apprendre à programmer. Certains de ces modules donnent
accès aux entrées/sorties, aux appels système, aux connecteurs réseaux et même
aux outils comme Tk pour créer des interfaces graphiques.
Python est un langage interprété, ce qui peut vous faire gagner un temps
considérable pendant le développement de vos programmes car aucune compilation
ni édition de liens n'est nécessaire. L'interpréteur peut être utilisé de manière
interactive, pour vous permettre d'expérimenter les fonctionnalités du langage,
d'écrire des programmes jetables ou de tester des fonctions lors d'un développement
incrémental. C'est aussi une calculatrice de bureau bien pratique.

Python permet d'écrire des programmes compacts et lisibles. Les programmes écrits
en Python sont généralement beaucoup plus courts que leurs équivalents en C, C++
ou Java. Et ceci pour plusieurs raisons :

 les types de données de haut niveau vous permettent d'exprimer des


opérations complexes en une seule instruction ;
 les instructions sont regroupées entre elles grâce à l'indentation, plutôt que
par l'utilisation d'accolades ;
 aucune déclaration de variable ou d'argument n'est nécessaire.

Python est extensible : si vous savez écrire un programme en C, une nouvelle


fonction ou module peut être facilement ajouté à l'interpréteur afin de l'étendre, que
ce soit pour effectuer des opérations critiques à vitesse maximale ou pour lier des
programmes en Python à des bibliothèques disponibles uniquement sous forme
binaire (par exemple des bibliothèques graphiques dédiées à un matériel). Une fois
que vous êtes à l'aise avec ces principes, vous pouvez relier l'interpréteur Python à
une application écrite en C et l'utiliser comme un langage d'extensions ou de
commandes pour cette application.

Au fait, le nom du langage provient de l'émission de la BBC « Monty Python's Flying


Circus » et n'a rien à voir avec les reptiles. Faire référence aux sketchs des Monty
Python dans la documentation n'est pas seulement permis, c'est encouragé !

Maintenant que vos papilles ont été chatouillées, nous allons pouvoir rentrer dans le
vif du sujet Python. Et comme la meilleure façon d'apprendre un langage est de
l'utiliser, ce tutoriel vous invite à jouer avec l'interpréteur au fur et à mesure de votre
lecture.

Dans le prochain chapitre, nous expliquons l'utilisation de l'interpréteur. Ce n'est pas


la section la plus passionnante, mais c'est un passage obligé pour que vous puissiez
mettre en pratique les exemples donnés plus loin.

Le reste du tutoriel présente diverses fonctionnalités du langage et du système


Python au travers d'exemples, en commençant par les expressions simples, les
instructions et les types de données, jusqu'à aborder des concepts avancés comme
les exceptions et les classes, en passant par les fonctions et modules.

2. Mode d'emploi de l'interpréteur Python


2.1. Lancement de l'interpréteur
L'interpréteur Python se trouve en général
comme /usr/local/bin/python3.7 sur ces machines où il est disponible ;
ajoutez /usr/local/bin au chemin de recherche de votre shell Unix afin de
pouvoir le lancer en tapant la commande :

python3.7

dans le shell. 1 Le choix du répertoire où se trouve l'interpréteur étant une option


d'installation, d'autres chemins sont possibles ; voyez avec votre gourou Python local
ou votre administrateur système (par exemple, /usr/local/python est un endroit
courant).

On Windows machines where you have installed Python from the Microsoft Store,
the python3.7 command will be available. If you have the py.exe launcher installed,
you can use the py command. See Digression : Définition des variables
d'environnement for other ways to launch Python.

Tapez un caractère de fin de fichier ( Ctrl-D sous Unix, Ctrl-Z sous Windows) dans


une invite de commande primaire provoque la fermeture de l'interpréteur avec un
code de sortie nul. Si cela ne fonctionne pas, vous pouvez fermer l'interpréteur en
tapant la commande quit().

The interpreter's line-editing features include interactive editing, history substitution


and code completion on systems that support the GNU Readline library. Perhaps the
quickest check to see whether command line editing is supported is typing Control-
P to the first Python prompt you get. If it beeps, you have command line editing; see
Appendix Édition interactive des entrées et substitution d'historique for an
introduction to the keys. If nothing appears to happen, or if ^P is echoed, command
line editing isn't available; you'll only be able to use backspace to remove characters
from the current line.

L'interpréteur fonctionne de façon similaire au shell Unix : lorsqu'il est appelé avec
l'entrée standard connectée à un périphérique tty, il lit et exécute les commandes de
façon interactive ; lorsqu'il est appelé avec un nom de fichier en argument ou avec un
fichier comme entrée standard, il lit et exécute un script depuis ce fichier.
Une autre façon de lancer l'interpréteur est python -c commande [arg] ....
Cela exécute les instructions de commande de façon analogue à l'option -c du shell.
Parce que les instructions Python contiennent souvent des espaces et d'autres
caractères spéciaux pour le shell, il est généralement conseillé de
mettre commande entre guillemets simples.

Certains modules Python sont aussi utiles en tant que scripts. Ils peuvent être
appelés avec python -m module [arg] ... qui exécute le fichier source
de module comme si vous aviez tapé son nom complet dans la ligne de commande.

Quand un fichier de script est utilisé, il est parfois utile de pouvoir lancer le script puis
d'entrer dans le mode interactif après coup. Cela est possible en passant -i avant le
script.

Tous les paramètres utilisables en ligne de commande sont documentés dans Ligne


de commande et environnement.

2.1.1. Passage d'arguments
Lorsqu'ils sont connus de l'interpréteur, le nom du script et les arguments
additionnels sont représentés sous forme d'une liste assignée à la variable argv du
module sys. Vous pouvez y accéder en exécutant import sys. La liste contient au
minimum un élément ; quand aucun script ni aucun argument n'est
donné, sys.argv[0] est une chaine vide. Quand '-' (qui représente l'entrée
standard) est passé comme nom de script, sys.argv[0] contient '-'. Quand -
c commande est utilisé, sys.argv[0] contient '-c'. Enfin, quand -m module est
utilisé, le nom complet du module est assigné à sys.argv[0]. Les options trouvées
après -c commande ou -m module ne sont pas lues comme options de l'interpréteur
Python mais laissées dans sys.argv pour être utilisées par le module ou la
commande.

2.1.2. Mode interactif
Lorsque des commandes sont lues depuis un tty, l'interpréteur est dit être en mode
interactif. Dans ce mode, il demande la commande suivante avec le prompt primaire,
en général trois signes plus-grand-que ( >>>) ; pour les lignes de continuation, il
affiche le prompt secondaire, par défaut trois points ( ...). L'interpréteur affiche un
message de bienvenue indiquant son numéro de version et une notice de copyright
avant d'afficher le premier prompt :

$ python3.7
Python 3.7 (default, Sep 16 2015, 09:25:04)
[GCC 4.8.2] on linux
Type "help", "copyright", "credits" or "license" for more
information.
>>>

Les lignes de continuation sont nécessaires pour entrer une construction multi-lignes.
Par exemple, regardez cette instruction if :

>>>

>>> the_world_is_flat = True


>>> if the_world_is_flat:
... print("Be careful not to fall off!")
...
Be careful not to fall off!

Pour plus d'informations sur le mode interactif, voir Mode interactif.

2.2. L'interpréteur et son environnement


2.2.1. Encodage du code source
Par défaut, Python considère que ses fichiers sources sont encodés en UTF-8. Dans
cet encodage, les caractères de la plupart des langues peuvent être utilisés
ensemble dans les chaînes de caractères, identifiants et commentaires. Notez que la
bibliothèque standard n'utilise que des caractères ASCII dans ses identifiants et que
nous considérons que c'est une bonne habitude que tout code portable devrait
suivre. Pour afficher correctement tous ces caractères, votre éditeur doit reconnaître
que le fichier est en UTF-8 et utiliser une police qui comprend tous les caractères
utilisés dans le fichier.

Pour annoncer un encodage différent de l'encodage par défaut, une ligne de


commentaire particulière doit être ajoutée en tant que première ligne du fichier. Sa
syntaxe est la suivante :

# -*- coding: encoding -*-

où encoding est un des codecs supporté par Python.

Par exemple, pour déclarer un encodage Windows-1252, la première ligne de votre


code source doit être :

# -*- coding: cp1252 -*-


Une exception à la règle première ligne est lorsque la première ligne est un shebang
UNIX. Dans ce cas, la déclaration de l'encodage doit être placée sur la deuxième
ligne du fichier. Par exemple :

#!/usr/bin/env python3
# -*- coding: cp1252 -*-

Notes

Sous Unix, par défaut, l'interpréteur Python 3.x n'est pas installé sous le nom
de python afin de ne pas entrer en conflit avec une éventuelle installation de Python
2.x.

3. Introduction informelle à Python


Dans les exemples qui suivent, les entrées et sorties se distinguent par la présence
ou l'absence d'invite (>>> et ...) : pour reproduire les exemples, vous devez taper tout
ce qui est après l'invite, au moment où celle-ci apparaît ; les lignes qui n'affichent pas
d'invite sont les sorties de l'interpréteur. Notez qu'une invite secondaire affichée
seule sur une ligne dans un exemple indique que vous devez entrer une ligne vide ;
ceci est utilisé pour terminer une commande multi-lignes.

Beaucoup d'exemples de ce manuel, même ceux saisis à l'invite de l'interpréteur,


incluent des commentaires. Les commentaires en Python commencent avec un
caractère croisillon, #, et s'étendent jusqu'à la fin de la ligne. Un commentaire peut
apparaître au début d'une ligne ou à la suite d'un espace ou de code, mais pas à
l'intérieur d'une chaîne de caractères littérale. Un caractère croisillon à l'intérieur
d'une chaîne de caractères est juste un caractère croisillon. Comme les
commentaires ne servent qu'à expliquer le code et ne sont pas interprétés par
Python, ils peuvent être ignorés lorsque vous tapez les exemples.

Quelques exemples :

# this is the first comment


spam = 1 # and this is the second comment
# ... and now a third!
text = "# This is not a comment because it's inside quotes."
3.1. Utilisation de Python comme une calculatrice
Essayons quelques commandes Python simples. Démarrez l'interpréteur et attendez
l'invite primaire, >>>. Ça ne devrait pas être long.

3.1.1. Les nombres
L'interpréteur agit comme une simple calculatrice : vous pouvez lui entrer une
expression et il vous affiche la valeur. La syntaxe des expressions est simple : les
opérateurs +, -, * et / fonctionnent comme dans la plupart des langages (par
exemple, Pascal ou C) ; les parenthèses peuvent être utilisées pour faire des
regroupements. Par exemple :

>>>

>>> 2 + 2
4
>>> 50 - 5*6
20
>>> (50 - 5*6) / 4
5.0
>>> 8 / 5 # division always returns a floating point number
1.6

Les nombres entiers (comme 2, 4, 20) sont de type int, alors que les décimaux
(comme 5.0, 1.6) sont de type float. Vous trouvez plus de détails sur les types
numériques plus loin dans ce tutoriel.

Les divisions (/) donnent toujours des float. Utilisez l'opérateur // pour effectuer


des divisions entières et donc obtenir un résultat entier. Pour obtenir le reste d'une
division entière, utilisez l'opérateur % :

>>>

>>> 17 / 3 # classic division returns a float


5.666666666666667
>>>
>>> 17 // 3 # floor division discards the fractional part
5
>>> 17 % 3 # the % operator returns the remainder of the
division
2
>>> 5 * 3 + 2 # result * divisor + remainder
17
En Python, il est possible de calculer des puissances avec l'opérateur ** 1 :

>>>

>>> 5 ** 2 # 5 squared
25
>>> 2 ** 7 # 2 to the power of 7
128

Le signe égal (=) est utilisé pour affecter une valeur à une variable. Dans ce cas,
aucun résultat n'est affiché avant l'invite suivante :

>>>

>>> width = 20
>>> height = 5 * 9
>>> width * height
900

Si une variable n'est pas "définie" (si aucune valeur ne lui a été affectée), son
utilisation produit une erreur :

>>>

>>> n # try to access an undefined variable


Traceback (most recent call last):
File "<stdin>", line 1, in <module>
NameError: name 'n' is not defined

Les nombres à virgule flottante sont tout à fait admis (NdT : Python utilise le
point . comme séparateur entre la partie entière et la partie décimale des nombres,
c'est la convention anglo-saxonne) ; les opérateurs avec des opérandes de types
différents convertissent l'opérande de type entier en type virgule flottante :

>>>

>>> 4 * 3.75 - 1
14.0

En mode interactif, la dernière expression affichée est affectée à la variable  _. Ainsi,
lorsque vous utilisez Python comme calculatrice, cela vous permet de continuer des
calculs facilement, par exemple :

>>>

>>> tax = 12.5 / 100


>>> price = 100.50
>>> price * tax
12.5625
>>> price + _
113.0625
>>> round(_, 2)
113.06

Cette variable doit être considérée comme une variable en lecture seule par
l'utilisateur. Ne lui affectez pas de valeur explicitement --- vous créeriez ainsi une
variable locale indépendante, avec le même nom, qui masquerait la variable native et
son fonctionnement magique.

En plus des int et des float, il existe les Decimal et les Fraction. Python gère


aussi les nombres complexes, en utilisant le suffixe j ou J pour indiquer la partie
imaginaire (tel que 3+5j).

3.1.2. Chaînes de caractères
En plus des nombres, Python sait aussi manipuler des chaînes de caractères, qui
peuvent être exprimées de différentes manières. Elles peuvent être écrites entre
guillemets simples ('...') ou entre guillemets ("...") sans distinction 2. \ peut
être utilisé pour protéger un guillemet :

>>>

>>> 'spam eggs' # single quotes


'spam eggs'
>>> 'doesn\'t' # use \' to escape the single quote...
"doesn't"
>>> "doesn't" # ...or use double quotes instead
"doesn't"
>>> '"Yes," they said.'
'"Yes," they said.'
>>> "\"Yes,\" they said."
'"Yes," they said.'
>>> '"Isn\'t," they said.'
'"Isn\'t," they said.'

En mode interactif, l'interpréteur affiche les chaînes de caractères entre guillemets.


Les guillemets et autres caractères spéciaux sont protégés avec des barres obliques
inverses (backslash en anglais). Bien que cela puisse être affiché différemment de
ce qui a été entré (les guillemets peuvent changer), les deux formats sont
équivalents. La chaîne est affichée entre guillemets si elle contient un guillemet
simple et aucun guillemet, sinon elle est affichée entre guillemets simples. La
fonction print() affiche les chaînes de manière plus lisible, en retirant les
guillemets et en affichant les caractères spéciaux qui étaient protégés par une barre
oblique inverse :

>>>

>>> '"Isn\'t," they said.'


'"Isn\'t," they said.'
>>> print('"Isn\'t," they said.')
"Isn't," they said.
>>> s = 'First line.\nSecond line.' # \n means newline
>>> s # without print(), \n is included in the output
'First line.\nSecond line.'
>>> print(s) # with print(), \n produces a new line
First line.
Second line.

Si vous ne voulez pas que les caractères précédés d'un \ soient interprétés comme
étant spéciaux, utilisez les chaînes brutes (raw strings en anglais) en préfixant la
chaîne d'un r :

>>>

>>> print('C:\some\name') # here \n means newline!


C:\some
ame
>>> print(r'C:\some\name') # note the r before the quote
C:\some\name

Les chaînes de caractères peuvent s'étendre sur plusieurs lignes. Utilisez alors des
triples guillemets, simples ou doubles : '''...''' ou """...""". Les retours à la
ligne sont automatiquement inclus, mais on peut l'empêcher en ajoutant \ à la fin de
la ligne. L'exemple suivant :

print("""\
Usage: thingy [OPTIONS]
-h Display this usage message
-H hostname Hostname to connect to
""")

produit l'affichage suivant (notez que le premier retour à la ligne n'est pas inclus) :

Usage: thingy [OPTIONS]


-h Display this usage message
-H hostname Hostname to connect to
Les chaînes peuvent être concaténées (collées ensemble) avec l'opérateur + et
répétées avec l'opérateur * :

>>>

>>> # 3 times 'un', followed by 'ium'


>>> 3 * 'un' + 'ium'
'unununium'

Plusieurs chaînes de caractères, écrites littéralement (c'est-à-dire entre guillemets),


côte à côte, sont automatiquement concaténées.

>>>

>>> 'Py' 'thon'


'Python'

Cette fonctionnalité est surtout intéressante pour couper des chaînes trop longues :

>>>

>>> text = ('Put several strings within parentheses '


... 'to have them joined together.')
>>> text
'Put several strings within parentheses to have them joined
together.'

Cela ne fonctionne cependant qu'avec les chaînes littérales, pas avec les variables ni
les expressions :

>>>

>>> prefix = 'Py'


>>> prefix 'thon' # can't concatenate a variable and a string
literal
File "<stdin>", line 1
prefix 'thon'
^
SyntaxError: invalid syntax
>>> ('un' * 3) 'ium'
File "<stdin>", line 1
('un' * 3) 'ium'
^
SyntaxError: invalid syntax

Pour concaténer des variables, ou des variables avec des chaînes littérales, utilisez
l'opérateur + :
>>>

>>> prefix + 'thon'


'Python'

Les chaînes de caractères peuvent être indexées (i.e. on peut accéder aux
caractères par leur position), le premier caractère d'une chaîne étant à la position 0.
Il n'existe pas de type distinct pour les caractères, un caractère est simplement une
chaîne de longueur 1 :

>>>

>>> word = 'Python'


>>> word[0] # character in position 0
'P'
>>> word[5] # character in position 5
'n'

Les indices peuvent également être négatifs, on compte alors en partant de la droite.
Par exemple :

>>>

>>> word[-1] # last character


'n'
>>> word[-2] # second-last character
'o'
>>> word[-6]
'P'

Notez que, comme -0 égale 0, les indices négatifs commencent par -1.

En plus d'accéder à un élément par son indice, il est aussi possible de "trancher"
(slice en anglais) une chaîne. Accéder à une chaîne par un indice permet d'obtenir
un caractère, trancher permet d'obtenir une sous-chaîne :

>>>

>>> word[0:2] # characters from position 0 (included) to 2


(excluded)
'Py'
>>> word[2:5] # characters from position 2 (included) to 5
(excluded)
'tho'
Notez que le début est toujours inclus et la fin toujours exclue. Cela assure
que s[:i] + s[i:] est toujours égal à s :

>>>

>>> word[:2] + word[2:]


'Python'
>>> word[:4] + word[4:]
'Python'

Les valeurs par défaut des indices de tranches ont une utilité ; le premier indice vaut
zéro par défaut (i.e. lorsqu'il est omis), le deuxième correspond par défaut à la taille
de la chaîne de caractères

>>>

>>> word[:2] # character from the beginning to position 2


(excluded)
'Py'
>>> word[4:] # characters from position 4 (included) to the end
'on'
>>> word[-2:] # characters from the second-last (included) to
the end
'on'

Pour mémoriser la façon dont les tranches fonctionnent, vous pouvez imaginer que
les indices pointent entre les caractères, le côté gauche du premier caractère ayant
la position 0. Le côté droit du dernier caractère d'une chaîne de n caractères a alors
pour indice n. Par exemple :

+---+---+---+---+---+---+
| P | y | t | h | o | n |
+---+---+---+---+---+---+
0 1 2 3 4 5 6
-6 -5 -4 -3 -2 -1

La première ligne de nombres donne la position des indices 0…6 dans la chaîne ; la
deuxième ligne donne l'indice négatif correspondant. La tranche de i à j est
constituée de tous les caractères situés entre les bords libellés i et j, respectivement.

Pour des indices non négatifs, la longueur d'une tranche est la différence entre ces
indices, si les deux sont entre les bornes. Par exemple, la longueur
de word[1:3] est 2.

Utiliser un indice trop grand produit une erreur :


>>>

>>> word[42] # the word only has 6 characters


Traceback (most recent call last):
File "<stdin>", line 1, in <module>
IndexError: string index out of range

Cependant, les indices hors bornes sont gérés silencieusement lorsqu'ils sont utilisés
dans des tranches :

>>>

>>> word[4:42]
'on'
>>> word[42:]
''

Les chaînes de caractères, en Python, ne peuvent pas être modifiées. On dit qu'elles
sont immuables. Affecter une nouvelle valeur à un indice dans une chaîne produit
une erreur :

>>>

>>> word[0] = 'J'


Traceback (most recent call last):
File "<stdin>", line 1, in <module>
TypeError: 'str' object does not support item assignment
>>> word[2:] = 'py'
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
TypeError: 'str' object does not support item assignment

Si vous avez besoin d'une chaîne différente, vous devez en créer une nouvelle :

>>>

>>> 'J' + word[1:]


'Jython'
>>> word[:2] + 'py'
'Pypy'

La fonction native len() renvoie la longueur d'une chaîne :

>>>

>>> s = 'supercalifragilisticexpialidocious'
>>> len(s)
34
Voir aussi
Type Séquence de Texte — str

Les chaînes de caractères sont des exemples de types séquences ; elles acceptent
donc les opérations classiques prises en charge par ces types.
Méthodes de chaînes de caractères

Les chaînes de caractères gèrent un large éventail de méthodes de transformations


basiques et de recherche.
Chaînes de caractères formatées littérales

Des chaînes littérales qui contiennent des expressions.


Syntaxe de formatage de chaîne

Informations sur le formatage des chaînes avec la méthode str.format().


Formatage de chaines à la printf

Description détaillée des anciennes méthodes de mise en forme, appelées lorsque


les chaînes de caractères sont à gauche de l'opérateur %.
3.1.3. Listes
Python connaît différents types de données combinés, utilisés pour regrouper
plusieurs valeurs. Le plus souple est la liste, qui peut être écrit comme une suite,
placée entre crochets, de valeurs (éléments) séparées par des virgules. Les
éléments d'une liste ne sont pas obligatoirement tous du même type, bien qu'à
l'usage ce soit souvent le cas.

>>>

>>> squares = [1, 4, 9, 16, 25]


>>> squares
[1, 4, 9, 16, 25]

Comme les chaînes de caractères (et toute autre type de sequence), les listes
peuvent être indicées et découpées :

>>>

>>> squares[0] # indexing returns the item


1
>>> squares[-1]
25
>>> squares[-3:] # slicing returns a new list
[9, 16, 25]
Toutes les opérations par tranches renvoient une nouvelle liste contenant les
éléments demandés. Cela signifie que l'opération suivante renvoie une copie
(superficielle) de la liste :

>>>

>>> squares[:]
[1, 4, 9, 16, 25]

Les listes gèrent aussi les opérations comme les concaténations :

>>>

>>> squares + [36, 49, 64, 81, 100]


[1, 4, 9, 16, 25, 36, 49, 64, 81, 100]

Mais à la différence des chaînes qui sont immuables, les listes sont muables : il est
possible de modifier leur contenu :

>>>

>>> cubes = [1, 8, 27, 65, 125] # something's wrong here


>>> 4 ** 3 # the cube of 4 is 64, not 65!
64
>>> cubes[3] = 64 # replace the wrong value
>>> cubes
[1, 8, 27, 64, 125]

Il est aussi possible d'ajouter de nouveaux éléments à la fin d'une liste avec la
méthode append() (les méthodes sont abordées plus tard) :

>>>

>>> cubes.append(216) # add the cube of 6


>>> cubes.append(7 ** 3) # and the cube of 7
>>> cubes
[1, 8, 27, 64, 125, 216, 343]

Des affectations de tranches sont également possibles, ce qui peut même modifier la
taille de la liste ou la vider complètement :

>>>

>>> letters = ['a', 'b', 'c', 'd', 'e', 'f', 'g']


>>> letters
['a', 'b', 'c', 'd', 'e', 'f', 'g']
>>> # replace some values
>>> letters[2:5] = ['C', 'D', 'E']
>>> letters
['a', 'b', 'C', 'D', 'E', 'f', 'g']
>>> # now remove them
>>> letters[2:5] = []
>>> letters
['a', 'b', 'f', 'g']
>>> # clear the list by replacing all the elements with an empty
list
>>> letters[:] = []
>>> letters
[]

La primitive len() s'applique aussi aux listes :

>>>

>>> letters = ['a', 'b', 'c', 'd']


>>> len(letters)
4

Il est possible d'imbriquer des listes (i.e. créer des listes contenant d'autres listes).
Par exemple :

>>>

>>> a = ['a', 'b', 'c']


>>> n = [1, 2, 3]
>>> x = [a, n]
>>> x
[['a', 'b', 'c'], [1, 2, 3]]
>>> x[0]
['a', 'b', 'c']
>>> x[0][1]
'b'

3.2. Premiers pas vers la programmation


Bien entendu, on peut utiliser Python pour des tâches plus compliquées que
d'additionner deux et deux. Par exemple, on peut écrire le début de la suite de
Fibonacci comme ceci :

>>>

>>> # Fibonacci series:


... # the sum of two elements defines the next
... a, b = 0, 1
>>> while a < 10:
... print(a)
... a, b = b, a+b
...
0
1
1
2
3
5
8

Cet exemple introduit plusieurs nouvelles fonctionnalités.

 La première ligne contient une affectation multiple : les variables a et b se


voient affecter simultanément leurs nouvelles valeurs 0 et 1. Cette méthode est
encore utilisée à la dernière ligne, pour démontrer que les expressions sur la partie
droite de l'affectation sont toutes évaluées avant que les affectations ne soient
effectuées. Ces expressions en partie droite sont toujours évaluées de la gauche
vers la droite.
 La boucle while s'exécute tant que la condition (ici : a < 10) reste vraie. En
Python, comme en C, tout entier différent de zéro est vrai et zéro est faux. La
condition peut aussi être une chaîne de caractères, une liste, ou en fait toute
séquence ; une séquence avec une valeur non nulle est vraie, une séquence vide est
fausse. Le test utilisé dans l'exemple est une simple comparaison. Les opérateurs de
comparaison standards sont écrits comme en
C : < (inférieur), > (supérieur), == (égal), <= (inférieur ou égal), >= (supérieur ou égal)
et != (non égal).
 Le corps de la boucle est indenté : l'indentation est la méthode utilisée par
Python pour regrouper des instructions. En mode interactif, vous devez saisir une
tabulation ou des espaces pour chaque ligne indentée. En pratique, vous aurez
intérêt à utiliser un éditeur de texte pour les saisies plus compliquées ; tous les
éditeurs de texte dignes de ce nom disposent d'une fonction d'auto-indentation.
Lorsqu'une expression composée est saisie en mode interactif, elle doit être suivie
d'une ligne vide pour indiquer qu'elle est terminée (car l'analyseur ne peut pas
deviner que vous venez de saisir la dernière ligne). Notez bien que toutes les lignes
à l'intérieur d'un bloc doivent être indentées au même niveau.
 La fonction print() écrit les valeurs des paramètres qui lui sont fournis. Ce
n'est pas la même chose que d'écrire l'expression que vous voulez afficher (comme
nous l'avons fait dans l'exemple de la calculatrice), en raison de la manière
qu'a print de gérer les paramètres multiples, les nombres décimaux et les chaînes.
Les chaînes sont affichées sans apostrophe et une espace est insérée entre les
éléments de telle sorte que vous pouvez facilement formater les choses, comme
ceci :

>>>

>>> i = 256*256
>>> print('The value of i is', i)
The value of i is 65536

Le paramètre nommé end peut servir pour enlever le retour à la ligne ou pour


terminer la ligne par une autre chaîne :

>>>

>>> a, b = 0, 1
>>> while a < 1000:
... print(a, end=',')
... a, b = b, a+b
...
0,1,1,2,3,5,8,13,21,34,55,89,144,233,377,610,987,

Notes

Puisque ** est prioritaire sur -, -3 ** 2 est interprété -(3 ** 2) et vaut donc -9.


Pour éviter cela et obtenir 9, utilisez des parenthèses : (-3) ** 2.

Contrairement à d'autres langages, les caractères spéciaux comme \n ont la même


signification entre guillemets ( "...") ou entre guillemets simples ( '...'). La seule
différence est que, dans une chaîne entre guillemets, il n'est pas nécessaire de
protéger les guillemets simples et vice-versa.

4. D'autres outils de contrôle de flux


Besides the while statement just introduced, Python uses the usual flow control
statements known from other languages, with some twists.
4.1. L'instruction if
L'instruction if est sans doute la plus connue. Par exemple :

>>>

>>> x = int(input("Please enter an integer: "))


Please enter an integer: 42
>>> if x < 0:
... x = 0
... print('Negative changed to zero')
... elif x == 0:
... print('Zero')
... elif x == 1:
... print('Single')
... else:
... print('More')
...
More

Il peut y avoir un nombre quelconque de parties elif et la partie else est


facultative. Le mot clé elif est un raccourci pour else if, mais permet de gagner un
niveau d'indentation. Une séquence if ... elif ... elif ... est par ailleurs
équivalente aux instructions switch ou case disponibles dans d'autres langages.

4.2. L'instruction for
L'instruction for que propose Python est un peu différente de celle que l'on peut
trouver en C ou en Pascal. Au lieu de toujours itérer sur une suite arithmétique de
nombres (comme en Pascal), ou de donner à l'utilisateur la possibilité de définir le
pas d'itération et la condition de fin (comme en C), l'instruction for en Python itère
sur les éléments d'une séquence (qui peut être une liste, une chaîne de
caractères…), dans l'ordre dans lequel ils apparaissent dans la séquence. Par
exemple :

>>>

>>> # Measure some strings:


... words = ['cat', 'window', 'defenestrate']
>>> for w in words:
... print(w, len(w))
...
cat 3
window 6
defenestrate 12
Si vous devez modifier la séquence sur laquelle s'effectue l'itération à l'intérieur de la
boucle (par exemple pour dupliquer ou supprimer un élément), il est plus que
recommandé de commencer par en faire une copie, celle-ci n'étant pas implicite. La
notation "par tranches" rend cette opération particulièrement simple :

>>>

>>> for w in words[:]: # Loop over a slice copy of the entire


list.
... if len(w) > 6:
... words.insert(0, w)
...
>>> words
['defenestrate', 'cat', 'window', 'defenestrate']

Avec for w in words:, l'exemple tenterait de créer une liste infinie, en


insérant defenestrate indéfiniment.

4.3. La fonction range()
Si vous devez itérer sur une suite de nombres, la fonction native range() est faite
pour cela. Elle génère des suites arithmétiques :

>>>

>>> for i in range(5):


... print(i)
...
0
1
2
3
4

Le dernier élément fourni en paramètre ne fait jamais partie de la liste


générée ; range(10) génère une liste de 10 valeurs, dont les valeurs vont de 0 à 9.
Il est possible de spécifier une valeur de début et une valeur d'incrément différentes
(y compris négative pour cette dernière, que l'on appelle également parfois le 'pas') :

range(5, 10)
5, 6, 7, 8, 9

range(0, 10, 3)
0, 3, 6, 9
range(-10, -100, -30)
-10, -40, -70

Pour itérer sur les indices d'une séquence, on peut combiner les
fonctions range() et len() :

>>>

>>> a = ['Mary', 'had', 'a', 'little', 'lamb']


>>> for i in range(len(a)):
... print(i, a[i])
...
0 Mary
1 had
2 a
3 little
4 lamb

Cependant, dans la plupart des cas, il est plus pratique d'utiliser la


fonction enumerate(). Voyez pour cela Techniques de boucles.

Une chose étrange se produit lorsqu'on affiche un range :

>>>

>>> print(range(10))
range(0, 10)

L'objet renvoyé par range() se comporte presque comme une liste, mais ce n'en est
pas une. Cet objet génère les éléments de la séquence au fur et à mesure de
l'itération, sans réellement produire la liste en tant que telle, économisant ainsi de
l'espace.

On appelle de tels objets des iterables, c'est à dire des objets qui conviennent à
des iterateurs, des fonctions ou constructions qui s'attendent à quelque chose duquel
ils peuvent tirer des éléments, successivement, jusqu'à épuisement. On a vu que
l'instruction for est un itérateur. La fonction list() en est un autre, qui crée des
listes à partir d'itérables :

>>>

>>> list(range(5))
[0, 1, 2, 3, 4]
Plus loin nous voyons d'autres fonctions qui donnent des itérables ou en prennent en
paramètre.

4.4. Les instructions break, continue et les


clauses else au sein des boucles
L'instruction break, comme en C, interrompt la boucle for ou while la plus
profonde.

Les boucles peuvent également disposer d'une instruction else ; celle-ci est


exécutée lorsqu'une boucle se termine alors que tous ses éléments ont été traités
(dans le cas d'un for) ou que la condition devient fausse (dans le cas d'un while),
mais pas lorsque la boucle est interrompue par une instruction break. L'exemple
suivant, qui effectue une recherche de nombres premiers, en est une démonstration :

>>>

>>> for n in range(2, 10):


... for x in range(2, n):
... if n % x == 0:
... print(n, 'equals', x, '*', n//x)
... break
... else:
... # loop fell through without finding a factor
... print(n, 'is a prime number')
...
2 is a prime number
3 is a prime number
4 equals 2 * 2
5 is a prime number
6 equals 2 * 3
7 is a prime number
8 equals 2 * 4
9 equals 3 * 3

(Oui, ce code est correct. Regardez attentivement : l'instruction else est rattachée à


la boucle for, et non à l'instruction if.)

Lorsqu'elle utilisée dans une boucle, la clause else est donc plus proche de celle
associée à une instruction try que de celle associée à une instruction if : la
clause else d'une instruction try s'exécute lorsqu'aucune exception n'est
déclenchée, et celle d'une boucle lorsque aucun break n'intervient. Plus plus
d'informations sur l'instruction try et le traitement des exceptions, consultez Gestion
des exceptions.
L'instruction continue, également empruntée au C, fait passer la boucle à son
itération suivante :

>>>

>>> for num in range(2, 10):


... if num % 2 == 0:
... print("Found an even number", num)
... continue
... print("Found a number", num)
Found an even number 2
Found a number 3
Found an even number 4
Found a number 5
Found an even number 6
Found a number 7
Found an even number 8
Found a number 9

4.5. L'instruction pass
L'instruction pass ne fait rien. Elle peut être utilisée lorsqu'une instruction est
nécessaire pour fournir une syntaxe correcte, mais qu'aucune action ne doit être
effectuée. Par exemple :

>>>

>>> while True:


... pass # Busy-wait for keyboard interrupt (Ctrl+C)
...

On utilise couramment cette instruction pour créer des classes minimales :

>>>

>>> class MyEmptyClass:


... pass
...

Un autre cas d'utilisation du pass est de réserver un espace en phase de


développement pour une fonction ou un traitement conditionnel, vous permettant
ainsi de construire votre code à un niveau plus abstrait. L'instruction pass est alors
ignorée silencieusement :

>>>
>>> def initlog(*args):
... pass # Remember to implement this!
...

4.6. Définir des fonctions


On peut créer une fonction qui écrit la suite de Fibonacci jusqu'à une limite imposée :

>>>

>>> def fib(n): # write Fibonacci series up to n


... """Print a Fibonacci series up to n."""
... a, b = 0, 1
... while a < n:
... print(a, end=' ')
... a, b = b, a+b
... print()
...
>>> # Now call the function we just defined:
... fib(2000)
0 1 1 2 3 5 8 13 21 34 55 89 144 233 377 610 987 1597

Le mot-clé def introduit une définition de fonction. Il doit être suivi du nom de la


fonction et d'une liste, entre parenthèses, de ses paramètres. L'instruction qui
constitue le corps de la fonction débute à la ligne suivante et doit être indentée.

La première instruction d'une fonction peut, de façon facultative, être une chaîne de
caractères littérale ; cette chaîne de caractères sera alors la chaîne de
documentation de la fonction, appelée docstring (consultez la section Chaînes de
documentation pour en savoir plus). Il existe des outils qui utilisent ces chaînes de
documentation pour générer automatiquement une documentation en ligne ou
imprimée, ou pour permettre à l'utilisateur de naviguer de façon interactive dans le
code ; prenez-en l'habitude, c'est une bonne pratique que de documenter le code
que vous écrivez.

L'exécution d'une fonction introduit une nouvelle table de symboles utilisée par les
variables locales de la fonction. Plus précisément, toutes les affectations de variables
effectuées au sein d'une fonction stockent la valeur dans la table de symboles
locale ; en revanche, les références de variables sont recherchées dans la table de
symboles locale, puis dans la table de symboles locale des fonctions englobantes,
puis dans la table de symboles globale et finalement dans la table de noms des
primitives. Par conséquent, bien qu'elles puissent être référencées, il est impossible
d'affecter une valeur à une variable globale ou à une variable d'une fonction
englobante (sauf pour les variables globales désignées dans une
instruction global et pour les variables des fonctions englobantes désignées dans
une instruction nonlocal).

Les paramètres effectifs (arguments) d'une fonction sont introduits dans la table de
symboles locale de la fonction appelée au moment où elle est appelée ; par
conséquent, les passages de paramètres se font par valeur, la valeur étant toujours
une référence à un objet et non la valeur de l'objet lui-même. 1 Lorsqu'une fonction
appelle une autre fonction, une nouvelle table de symboles locale est créée pour cet
appel.

Une définition de fonction introduit le nom de la fonction dans la table de symboles


courante. La valeur du nom de la fonction est un type qui est reconnu par
l'interpréteur comme une fonction définie par l'utilisateur. Cette valeur peut être
affectée à un autre nom qui pourra alors être utilisé également comme une fonction.
Ceci fournit un mécanisme de renommage général :

>>>

>>> fib
<function fib at 10042ed0>
>>> f = fib
>>> f(100)
0 1 1 2 3 5 8 13 21 34 55 89

Si vous venez d'autres langages, vous pouvez penser que fib n'est pas une
fonction mais une procédure, puisqu'elle ne renvoie pas de résultat. En fait, même
les fonctions sans instruction return renvoient une valeur, quoique ennuyeuse.
Cette valeur est appelée None (c'est le nom d'une primitive). Écrire la valeur None est
normalement supprimé par l'interpréteur lorsqu'il s'agit de la seule valeur qui doit être
écrite. Vous pouvez le constater, si vous y tenez vraiment, en utilisant print() :

>>>

>>> fib(0)
>>> print(fib(0))
None

Il est facile d'écrire une fonction qui renvoie une liste de la série de Fibonacci au lieu
de l'afficher :

>>>

>>> def fib2(n): # return Fibonacci series up to n


... """Return a list containing the Fibonacci series up to
n."""
... result = []
... a, b = 0, 1
... while a < n:
... result.append(a) # see below
... a, b = b, a+b
... return result
...
>>> f100 = fib2(100) # call it
>>> f100 # write the result
[0, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89]

Cet exemple, comme d'habitude, illustre de nouvelles fonctionnalités de Python :

 L'instruction return provoque la sortie de la fonction en renvoyant une


valeur. return sans expression en paramètre renvoie None. Arriver à la fin d'une
fonction renvoie également None.
 L'instruction result.append(a) appelle une méthode de l'objet result qui
est une liste. Une méthode est une fonction qui "appartient" à un objet et qui est
nommée obj.methodname, où obj est un objet (il peut également s'agir d'une
expression) et methodname est le nom d'une méthode que le type de l'objet définit.
Différents types définissent différentes méthodes. Des méthodes de différents types
peuvent porter le même nom sans qu'il n'y ait d'ambigüité (vous pouvez définir vos
propres types d'objets et leurs méthodes en utilisant des classes, voir Classes). La
méthode append() donnée dans cet exemple est définie pour les listes ; elle ajoute
un nouvel élément à la fin de la liste. Dans cet exemple, elle est l'équivalent
de result = result + [a], mais elle est plus efficace.

4.7. D'avantage sur la définition des fonctions


Il est également possible de définir des fonctions avec un nombre variable
d'arguments. Trois syntaxes peuvent être utilisées, éventuellement combinées.

4.7.1. Valeur par défaut des arguments


La forme la plus utile consiste à indiquer une valeur par défaut pour certains
arguments. Ceci crée une fonction qui pourra être appelée avec moins d'arguments
que ceux présents dans sa définition. Par exemple :

def ask_ok(prompt, retries=4, reminder='Please try again!'):


while True:
ok = input(prompt)
if ok in ('y', 'ye', 'yes'):
return True
if ok in ('n', 'no', 'nop', 'nope'):
return False
retries = retries - 1
if retries < 0:
raise ValueError('invalid user response')
print(reminder)

Cette fonction peut être appelée de plusieurs façons :

 en ne fournissant que les arguments


obligatoires : ask_ok('Do you really want to quit?')
 en fournissant une partie des arguments
facultatifs : ask_ok('OK to overwrite the file?', 2)
 en fournissant tous les
arguments : ask_ok('OK to overwrite the file?', 2, 'Come on, only ye
s or no!')

Cet exemple présente également le mot-clé in. Celui-ci permet de tester si une


séquence contient une certaine valeur.

Les valeurs par défaut sont évaluées lors de la définition de la fonction dans la
portée de définition, de telle sorte que

i = 5

def f(arg=i):
print(arg)

i = 6
f()

affiche 5.

Avertissement important : la valeur par défaut n'est évaluée qu'une seule fois. Ceci
fait une différence lorsque cette valeur par défaut est un objet muable tel qu'une liste,
un dictionnaire ou des instances de la plupart des classes. Par exemple, la fonction
suivante accumule les arguments qui lui sont passés au fil des appels successifs :

def f(a, L=[]):


L.append(a)
return L
print(f(1))
print(f(2))
print(f(3))

Ceci affiche

[1]
[1, 2]
[1, 2, 3]

Si vous ne voulez pas que cette valeur par défaut soit partagée entre des appels
successifs, vous pouvez écrire la fonction de cette façon :

def f(a, L=None):


if L is None:
L = []
L.append(a)
return L

4.7.2. Les arguments nommés


Les fonctions peuvent également être appelées en utilisant des arguments
nommés sous la forme kwarg=value. Par exemple, la fonction suivante :

def parrot(voltage, state='a stiff', action='voom',


type='Norwegian Blue'):
print("-- This parrot wouldn't", action, end=' ')
print("if you put", voltage, "volts through it.")
print("-- Lovely plumage, the", type)
print("-- It's", state, "!")

accepte un argument obligatoire ( voltage) et trois arguments facultatifs


(state, action et type). Cette fonction peut être appelée de n'importe laquelle des
façons suivantes :

parrot(1000) # 1
positional argument
parrot(voltage=1000) # 1 keyword
argument
parrot(voltage=1000000, action='VOOOOOM') # 2 keyword
arguments
parrot(action='VOOOOOM', voltage=1000000) # 2 keyword
arguments
parrot('a million', 'bereft of life', 'jump') # 3
positional arguments
parrot('a thousand', state='pushing up the daisies') # 1
positional, 1 keyword

mais tous les appels qui suivent sont incorrects :

parrot() # required argument missing


parrot(voltage=5.0, 'dead') # non-keyword argument after a
keyword argument
parrot(110, voltage=220) # duplicate value for the same
argument
parrot(actor='John Cleese') # unknown keyword argument

Dans un appel de fonction, les arguments nommés doivent suivre les arguments
positionnés. Tous les arguments nommés doivent correspondre à l'un des arguments
acceptés par la fonction (par exemple, actor n'est pas un argument accepté par la
fonction parrot), mais leur ordre n'est pas important. Ceci inclut également les
arguments obligatoires (parrot(voltage=1000) est également correct). Aucun
argument ne peut recevoir une valeur plus d'une fois, comme l'illustre cet exemple
incorrect du fait de cette restriction :

>>>

>>> def function(a):


... pass
...
>>> function(0, a=0)
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
TypeError: function() got multiple values for keyword argument
'a'

Quand un dernier paramètre formel est présent sous la forme **name, il reçoit un


dictionnaire (voir Les types de correspondances — dict) contenant tous les
arguments nommés à l'exception de ceux correspondant à un paramètre formel. Ceci
peut être combiné à un paramètre formel sous la forme *name (décrit dans la section
suivante) qui lui reçoit un n-uplet contenant les arguments positionnés au-delà de la
liste des paramètres formels (*name doit être présent avant **name). Par exemple, si
vous définissez une fonction comme ceci :

def cheeseshop(kind, *arguments, **keywords):


print("-- Do you have any", kind, "?")
print("-- I'm sorry, we're all out of", kind)
for arg in arguments:
print(arg)
print("-" * 40)
for kw in keywords:
print(kw, ":", keywords[kw])

Elle pourrait être appelée comme ceci :

cheeseshop("Limburger", "It's very runny, sir.",


"It's really very, VERY runny, sir.",
shopkeeper="Michael Palin",
client="John Cleese",
sketch="Cheese Shop Sketch")

et, bien sûr, elle affiche :

-- Do you have any Limburger ?


-- I'm sorry, we're all out of Limburger
It's very runny, sir.
It's really very, VERY runny, sir.
----------------------------------------
shopkeeper : Michael Palin
client : John Cleese
sketch : Cheese Shop Sketch

Notez que Python garantit que l'ordre d'affichage des arguments est le même que
l'ordre dans lesquels ils sont fournis lors de l'appel à la fonction.

4.7.3. Listes d'arguments arbitraires


Pour terminer, l'option la moins fréquente consiste à indiquer qu'une fonction peut
être appelée avec un nombre arbitraire d'arguments. Ces arguments sont intégrés
dans un tuple (voir Tuples et séquences). Avant le nombre variable d'arguments,
zéro arguments normaux ou plus peuvent apparaître

def write_multiple_items(file, separator, *args):


file.write(separator.join(args))

Normalement, ces arguments variadiques sont les derniers paramètres, parce


qu'ils agrègent toutes les valeurs suivantes. Tout paramètre placé après le
paramètre *arg ne pourra être utilisé que par son nom.

>>>
>>> def concat(*args, sep="/"):
... return sep.join(args)
...
>>> concat("earth", "mars", "venus")
'earth/mars/venus'
>>> concat("earth", "mars", "venus", sep=".")
'earth.mars.venus'

4.7.4. Séparation des listes d'arguments


La situation inverse intervient lorsque les arguments sont déjà dans une liste ou un
tuple mais doivent être séparés pour un appel de fonction nécessitant des arguments
positionnés séparés. Par exemple, la primitive range() attend des
arguments start et stop distincts. S'ils ne sont pas disponibles séparément, écrivez
l'appel de fonction en utilisant l'opérateur * pour séparer les arguments présents
dans une liste ou un tuple :

>>>

>>> list(range(3, 6)) # normal call with separate


arguments
[3, 4, 5]
>>> args = [3, 6]
>>> list(range(*args)) # call with arguments unpacked
from a list
[3, 4, 5]

De la même façon, les dictionnaires peuvent fournir des arguments nommés en


utilisant l'opérateur ** :

>>>

>>> def parrot(voltage, state='a stiff', action='voom'):


... print("-- This parrot wouldn't", action, end=' ')
... print("if you put", voltage, "volts through it.", end='
')
... print("E's", state, "!")
...
>>> d = {"voltage": "four million", "state": "bleedin' demised",
"action": "VOOM"}
>>> parrot(**d)
-- This parrot wouldn't VOOM if you put four million volts
through it. E's bleedin' demised !
4.7.5. Fonctions anonymes
Avec le mot-clé lambda, vous pouvez créer de petites fonctions anonymes. En voici
une qui renvoie la somme de ses deux arguments : lambda a, b: a+b. Les
fonctions lambda peuvent être utilisées partout où un objet fonction est attendu. Elles
sont syntaxiquement restreintes à une seule expression. Sémantiquement, elles ne
sont que du sucre syntaxique pour une définition de fonction normale. Comme les
fonctions imbriquées, les fonctions lambda peuvent référencer des variables de la
portée englobante :

>>>

>>> def make_incrementor(n):


... return lambda x: x + n
...
>>> f = make_incrementor(42)
>>> f(0)
42
>>> f(1)
43

L'exemple précédent utilise une fonction anonyme pour renvoyer une fonction. Une
autre utilisation classique est de donner une fonction minimaliste directement en tant
que paramètre :

>>>

>>> pairs = [(1, 'one'), (2, 'two'), (3, 'three'), (4, 'four')]
>>> pairs.sort(key=lambda pair: pair[1])
>>> pairs
[(4, 'four'), (1, 'one'), (3, 'three'), (2, 'two')]

4.7.6. Chaînes de documentation
Voici quelques conventions concernant le contenu et le format des chaînes de
documentation.

La première ligne devrait toujours être courte et résumer de manière concise l'utilité
de l'objet. Afin d'être bref, nul besoin de rappeler le nom de l'objet ou son type, qui
sont accessibles par d'autres moyens (sauf si le nom est un verbe qui décrit une
opération). Cette ligne devrait commencer avec une majuscule et se terminer par un
point.
S'il y a d'autres lignes dans la chaîne de documentation, la deuxième ligne devrait
être vide, pour la séparer visuellement du reste de la description. Les autres lignes
peuvent alors constituer un ou plusieurs paragraphes décrivant le mode d'utilisation
de l'objet, ses effets de bord, etc.

L'analyseur de code Python ne supprime pas l'indentation des chaînes de caractères


littérales multi-lignes, donc les outils qui utilisent la documentation doivent si besoin
faire cette opération eux-mêmes. La convention suivante s'applique : la première
ligne non vide après la première détermine la profondeur d'indentation de l'ensemble
de la chaîne de documentation (on ne peut pas utiliser la première ligne qui est
généralement accolée aux guillemets d'ouverture de la chaîne de caractères et dont
l'indentation n'est donc pas visible). Les espaces "correspondant" à cette profondeur
d'indentation sont alors supprimés du début de chacune des lignes de la chaîne.
Aucune ligne ne devrait présenter un niveau d'indentation inférieur mais si cela
arrive, toutes les espaces situés en début de ligne doivent être supprimées.
L'équivalent des espaces doit être testé après expansion des tabulations
(normalement remplacés par 4 espaces).

Voici un exemple de chaîne de documentation multi-lignes :

>>>

>>> def my_function():


... """Do nothing, but document it.
...
... No, really, it doesn't do anything.
... """
... pass
...
>>> print(my_function.__doc__)
Do nothing, but document it.

No, really, it doesn't do anything.

4.7.7. Annotations de fonctions
Les annotations de fonction sont des métadonnées optionnelles décrivant les types
utilisés par une fonction définie par l'utilisateur (voir les PEP 3107 et PEP 484 pour
plus d'informations).

Les annotations sont stockées dans l'attribut __annotations__ de la fonction, sous


forme d'un dictionnaire, et n'ont aucun autre effet. Les annotations sur les
paramètres sont définies par deux points (:) après le nom du paramètre suivi d'une
expression donnant la valeur de l'annotation. Les annotations de retour sont définies
par -> suivi d'une expression, entre la liste des paramètres et les deux points de fin
de l'instruction def. L'exemple suivant a un paramètre positionnel, un paramètre
nommé et la valeur de retour annotés :

>>>

>>> def f(ham: str, eggs: str = 'eggs') -> str:


... print("Annotations:", f.__annotations__)
... print("Arguments:", ham, eggs)
... return ham + ' and ' + eggs
...
>>> f('spam')
Annotations: {'ham': <class 'str'>, 'return': <class 'str'>,
'eggs': <class 'str'>}
Arguments: spam eggs
'spam and eggs'

4.8. Aparté : le style de codage


Maintenant que vous êtes prêt à écrire des programmes plus longs et plus
complexes, il est temps de parler du style de codage. La plupart des langages
peuvent être écrits (ou plutôt formatés) selon différents styles ; certains sont plus
lisibles que d'autres. Rendre la lecture de votre code plus facile aux autres est
toujours une bonne idée et adopter un bon style de codage peut énormément vous y
aider.

En Python, la plupart des projets adhèrent au style défini dans la PEP 8 ; elle met en
avant un style de codage très lisible et agréable à l’œil. Chaque développeur Python
se doit donc de la lire et de s'en inspirer autant que possible ; voici ses principaux
points notables :

 Utilisez des indentations de 4 espaces et pas de tabulation.

4 espaces constituent un bon compromis entre une indentation courte (qui permet
une profondeur d'imbrication plus importante) et une longue (qui rend le code plus
facile à lire). Les tabulations introduisent de la confusion et doivent être proscrites
autant que possible.
 Faites en sorte que les lignes ne dépassent pas 79 caractères, au besoin en
insérant des retours à la ligne.

Vous facilitez ainsi la lecture pour les utilisateurs qui n'ont qu'un petit écran et, pour
les autres, cela leur permet de visualiser plusieurs fichiers côte à côte.
 Utilisez des lignes vides pour séparer les fonctions et les classes, ou pour
scinder de gros blocs de code à l'intérieur de fonctions.
 Lorsque c'est possible, placez les commentaires sur leurs propres lignes.
 Utilisez les chaînes de documentation.
 Utilisez des espaces autour des opérateurs et après les virgules, mais pas
juste à l'intérieur des parenthèses : a = f(1, 2) + g(3, 4).
 Name your classes and functions consistently; the convention is to
use UpperCamelCase for classes and lowercase_with_underscores for
functions and methods. Always use self as the name for the first method argument
(see Une première approche des classes for more on classes and methods).
 N'utilisez pas d'encodage exotique dès lors que votre code est censé être
utilisé dans des environnements internationaux. Par défaut, Python travaille en UTF-
8. Pour couvrir tous les cas, préférez le simple ASCII.
 De la même manière, n'utilisez que des caractères ASCII pour vos noms de
variables s'il est envisageable qu'une personne parlant une autre langue lise ou
doive modifier votre code.

Notes

1 En fait, appels par référence d'objets serait sans doute une description plus juste dans la
mesure où, si un objet muable est passé en argument, l'appelant verra toutes les
modifications qui lui auront été apportées par l'appelé (insertion d'éléments dans une liste…).

5. Structures de données
Ce chapitre reprend plus en détail quelques points déjà décrits précédemment et
introduit également de nouvelles notions.

5.1. Compléments sur les listes


Le type liste dispose de méthodes supplémentaires. Voici toutes les méthodes des
objets de type liste :

list.append(x)

Ajoute un élément à la fin de la liste. Équivalent à a[len(a):] = [x].

list.extend(iterable)

Étend la liste en y ajoutant tous les éléments de l'itérable. Équivalent


à a[len(a):] = iterable.
list.insert(i, x)

Insère un élément à la position indiquée. Le premier argument est la position de


l'élément courant avant lequel l'insertion doit s'effectuer,
donc a.insert(0, x) insère l'élément en tête de la liste
et a.insert(len(a), x) est équivalent à a.append(x).

list.remove(x)

Supprime de la liste le premier élément dont la valeur est égale à x. Une
exception ValueError est levée s'il n'existe aucun élément avec cette valeur.

list.pop([i])

Enlève de la liste l'élément situé à la position indiquée et le renvoie en valeur de


retour. Si aucune position n'est spécifiée, a.pop() enlève et renvoie le dernier
élément de la liste (les crochets autour du i dans la signature de la méthode
indiquent que ce paramètre est facultatif et non que vous devez placer des crochets
dans votre code ! Vous retrouverez cette notation fréquemment dans le Guide de
Référence de la Bibliothèque Python).

list.clear()

Supprime tous les éléments de la liste. Équivalent à del a[:].

list.index(x[, start[, end]])

Renvoie la position du premier élément de la liste dont la valeur égale x (en


commençant à compter les positions à partir de zéro). Une
exception ValueError est levée si aucun élément n'est trouvé.

Les arguments optionnels start et end sont interprétés de la même manière que dans


la notation des tranches et sont utilisés pour limiter la recherche à une sous-
séquence particulière. L'indice renvoyé est calculé relativement au début de la
séquence complète et non relativement à start.

list.count(x)

Renvoie le nombre d'éléments ayant la valeur x dans la liste.

list.sort(key=None, reverse=False)

Ordonne les éléments dans la liste (les arguments peuvent personnaliser


l'ordonnancement, voir sorted() pour leur explication).
list.reverse()

Inverse l'ordre des éléments dans la liste.

list.copy()

Renvoie une copie superficielle de la liste. Équivalent à a[:].

L'exemple suivant utilise la plupart des méthodes des listes :

>>>

>>> fruits = ['orange', 'apple', 'pear', 'banana', 'kiwi',


'apple', 'banana']
>>> fruits.count('apple')
2
>>> fruits.count('tangerine')
0
>>> fruits.index('banana')
3
>>> fruits.index('banana', 4) # Find next banana starting a
position 4
6
>>> fruits.reverse()
>>> fruits
['banana', 'apple', 'kiwi', 'banana', 'pear', 'apple', 'orange']
>>> fruits.append('grape')
>>> fruits
['banana', 'apple', 'kiwi', 'banana', 'pear', 'apple', 'orange',
'grape']
>>> fruits.sort()
>>> fruits
['apple', 'apple', 'banana', 'banana', 'grape', 'kiwi', 'orange',
'pear']
>>> fruits.pop()
'pear'

Vous avez probablement remarqué que les méthodes telles


que insert, remove ou sort, qui ne font que modifier la liste, n'affichent pas de
valeur de retour (elles renvoient None) 1. C'est un principe respecté par toutes les
structures de données variables en Python.

5.1.1. Utilisation des listes comme des piles


Les méthodes des listes rendent très facile leur utilisation comme des piles, où le
dernier élément ajouté est le premier récupéré (« dernier entré, premier sorti » ou
LIFO pour last-in, first-out en anglais). Pour ajouter un élément sur la pile, utilisez la
méthode append(). Pour récupérer l'objet au sommet de la pile, utilisez la
méthode pop() sans indicateur de position. Par exemple :

>>>

>>> stack = [3, 4, 5]


>>> stack.append(6)
>>> stack.append(7)
>>> stack
[3, 4, 5, 6, 7]
>>> stack.pop()
7
>>> stack
[3, 4, 5, 6]
>>> stack.pop()
6
>>> stack.pop()
5
>>> stack
[3, 4]

5.1.2. Utilisation des listes comme des files


Il est également possible d'utiliser une liste comme une file, où le premier élément
ajouté est le premier récupéré (« premier entré, premier sorti » ou FIFO pour first-in,
first-out) ; toutefois, les listes ne sont pas très efficaces pour réaliser ce type de
traitement. Alors que les ajouts et suppressions en fin de liste sont rapides, les
opérations d'insertions ou de retraits en début de liste sont lentes (car tous les autres
éléments doivent être décalés d'une position).

Pour implémenter une file, utilisez la classe collections.deque qui a été conçue


pour réaliser rapidement les opérations d'ajouts et de retraits aux deux extrémités.
Par exemple :

>>>

>>> from collections import deque


>>> queue = deque(["Eric", "John", "Michael"])
>>> queue.append("Terry") # Terry arrives
>>> queue.append("Graham") # Graham arrives
>>> queue.popleft() # The first to arrive now
leaves
'Eric'
>>> queue.popleft() # The second to arrive now
leaves
'John'
>>> queue # Remaining queue in order of
arrival
deque(['Michael', 'Terry', 'Graham'])

5.1.3. Compréhensions de listes
Les compréhensions de listes fournissent un moyen de construire des listes de
manière très concise. Une application classique est la construction de nouvelles
listes où chaque élément est le résultat d'une opération appliquée à chaque élément
d'une autre séquence ; ou de créer une sous-séquence des éléments satisfaisant
une condition spécifique.

Par exemple, supposons que l'on veuille créer une liste de carrés, comme :

>>>

>>> squares = []
>>> for x in range(10):
... squares.append(x**2)
...
>>> squares
[0, 1, 4, 9, 16, 25, 36, 49, 64, 81]

Notez que cela crée (ou remplace) une variable nommée x qui existe toujours après
l'exécution de la boucle. On peut calculer une liste de carrés sans effet de bord
avec :

squares = list(map(lambda x: x**2, range(10)))

ou, de manière équivalente :

squares = [x**2 for x in range(10)]

qui est plus court et lisible.

Une compréhension de liste consiste à placer entre crochets une expression suivie
par une clause for puis par zéro ou plus clauses for ou if. Le résultat est une
nouvelle liste résultat de l'évaluation de l'expression dans le contexte des
clauses for et if qui la suivent. Par exemple, cette compréhension de liste combine
les éléments de deux listes s'ils ne sont pas égaux :

>>>
>>> [(x, y) for x in [1,2,3] for y in [3,1,4] if x != y]
[(1, 3), (1, 4), (2, 3), (2, 1), (2, 4), (3, 1), (3, 4)]

et c'est équivalent à :

>>>

>>> combs = []
>>> for x in [1,2,3]:
... for y in [3,1,4]:
... if x != y:
... combs.append((x, y))
...
>>> combs
[(1, 3), (1, 4), (2, 3), (2, 1), (2, 4), (3, 1), (3, 4)]

Notez que l'ordre des instructions for et if est le même dans ces différents extraits
de code.

Si l'expression est un n-uplet (c'est-à-dire (x, y) dans cet exemple), elle doit être


entourée par des parenthèses :

>>>

>>> vec = [-4, -2, 0, 2, 4]


>>> # create a new list with the values doubled
>>> [x*2 for x in vec]
[-8, -4, 0, 4, 8]
>>> # filter the list to exclude negative numbers
>>> [x for x in vec if x >= 0]
[0, 2, 4]
>>> # apply a function to all the elements
>>> [abs(x) for x in vec]
[4, 2, 0, 2, 4]
>>> # call a method on each element
>>> freshfruit = [' banana', ' loganberry ', 'passion fruit ']
>>> [weapon.strip() for weapon in freshfruit]
['banana', 'loganberry', 'passion fruit']
>>> # create a list of 2-tuples like (number, square)
>>> [(x, x**2) for x in range(6)]
[(0, 0), (1, 1), (2, 4), (3, 9), (4, 16), (5, 25)]
>>> # the tuple must be parenthesized, otherwise an error is
raised
>>> [x, x**2 for x in range(6)]
File "<stdin>", line 1, in <module>
[x, x**2 for x in range(6)]
^
SyntaxError: invalid syntax
>>> # flatten a list using a listcomp with two 'for'
>>> vec = [[1,2,3], [4,5,6], [7,8,9]]
>>> [num for elem in vec for num in elem]
[1, 2, 3, 4, 5, 6, 7, 8, 9]

Les compréhensions de listes peuvent contenir des expressions complexes et des


fonctions imbriquées :

>>>

>>> from math import pi


>>> [str(round(pi, i)) for i in range(1, 6)]
['3.1', '3.14', '3.142', '3.1416', '3.14159']

5.1.4. Compréhensions de listes imbriquées


La première expression dans une compréhension de liste peut être n'importe quelle
expression, y compris une autre compréhension de liste.

Voyez l'exemple suivant d'une matrice de 3 par 4, implémentée sous la forme de 3


listes de 4 éléments :

>>>

>>> matrix = [
... [1, 2, 3, 4],
... [5, 6, 7, 8],
... [9, 10, 11, 12],
... ]

Cette compréhension de liste transpose les lignes et les colonnes :

>>>

>>> [[row[i] for row in matrix] for i in range(4)]


[[1, 5, 9], [2, 6, 10], [3, 7, 11], [4, 8, 12]]

Comme nous l'avons vu dans la section précédente, la compréhension de liste


imbriquée est évaluée dans le contexte de l'instruction for qui la suit, donc cet
exemple est équivalent à :

>>>
>>> transposed = []
>>> for i in range(4):
... transposed.append([row[i] for row in matrix])
...
>>> transposed
[[1, 5, 9], [2, 6, 10], [3, 7, 11], [4, 8, 12]]

lequel à son tour est équivalent à :

>>>

>>> transposed = []
>>> for i in range(4):
... # the following 3 lines implement the nested listcomp
... transposed_row = []
... for row in matrix:
... transposed_row.append(row[i])
... transposed.append(transposed_row)
...
>>> transposed
[[1, 5, 9], [2, 6, 10], [3, 7, 11], [4, 8, 12]]

Dans des cas concrets, il est toujours préférable d'utiliser des fonctions natives plutôt
que des instructions de contrôle de flux complexes. La fonction zip() ferait dans ce
cas un excellent travail :

>>>

>>> list(zip(*matrix))
[(1, 5, 9), (2, 6, 10), (3, 7, 11), (4, 8, 12)]

Voyez Séparation des listes d'arguments pour plus de détails sur l'astérisque de


cette ligne.

5.2. L'instruction del
Il existe un moyen de retirer un élément d'une liste à partir de sa position au lieu de
sa valeur : l'instruction del. Elle diffère de la méthode pop() qui, elle, renvoie une
valeur. L'instruction del peut également être utilisée pour supprimer des tranches
d'une liste ou la vider complètement (ce que nous avions fait auparavant en affectant
une liste vide à la tranche). Par exemple :

>>>

>>> a = [-1, 1, 66.25, 333, 333, 1234.5]


>>> del a[0]
>>> a
[1, 66.25, 333, 333, 1234.5]
>>> del a[2:4]
>>> a
[1, 66.25, 1234.5]
>>> del a[:]
>>> a
[]

del peut aussi être utilisée pour supprimer des variables :

>>>

>>> del a

À partir de là, référencer le nom a est une erreur (au moins jusqu'à ce qu'une autre
valeur lui soit affectée). Vous trouverez d'autres utilisations de la fonction del plus
tard.

5.3. Tuples et séquences
Nous avons vu que les listes et les chaînes de caractères ont beaucoup de
propriétés en commun, comme l'indiçage et les opérations sur des tranches. Ce sont
deux exemples de séquences (voir Types séquentiels — list, tuple, range). Comme
Python est un langage en constante évolution, d'autres types de séquences y seront
peut-être ajoutés. Il existe également un autre type standard de séquence :
le tuple (ou n-uplet, dénomination que nous utiliserons dans la suite de cette
documentation).

Un n-uplet consiste en différentes valeurs séparées par des virgules, par exemple :

>>>

>>> t = 12345, 54321, 'hello!'


>>> t[0]
12345
>>> t
(12345, 54321, 'hello!')
>>> # Tuples may be nested:
... u = t, (1, 2, 3, 4, 5)
>>> u
((12345, 54321, 'hello!'), (1, 2, 3, 4, 5))
>>> # Tuples are immutable:
... t[0] = 88888
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
TypeError: 'tuple' object does not support item assignment
>>> # but they can contain mutable objects:
... v = ([1, 2, 3], [3, 2, 1])
>>> v
([1, 2, 3], [3, 2, 1])

Comme vous pouvez le voir, les n-uplets sont toujours affichés entre parenthèses, de
façon à ce que des n-uplets imbriqués soient interprétés correctement ; ils peuvent
être saisis avec ou sans parenthèses, même si celles-ci sont souvent nécessaires
(notamment lorsqu'un n-uplet fait partie d'une expression plus longue). Il n'est pas
possible d'affecter de valeur à un élément d'un n-uplet ; par contre, il est possible de
créer des n-uplets contenant des objets muables, comme des listes.

Si les n-uplets peuvent sembler similaires aux listes, ils sont souvent utilisés dans
des cas différents et pour des raisons différentes. Les n-uplets sont immuables et
contiennent souvent des séquences hétérogènes d'éléments qui sont accédés par
« dissociation » (unpacking en anglais, voir plus loin) ou par indice (ou même par
attributs dans le cas des namedtuples). Les listes sont souvent muables et
contiennent des éléments généralement homogènes qui sont accédés par itération
sur la liste.

Un problème spécifique est la construction de n-uplets ne contenant aucun ou un


seul élément : la syntaxe a quelques tournures spécifiques pour s'en accommoder.
Les n-uplets vides sont construits par une paire de parenthèses vides ; un n-uplet
avec un seul élément est construit en faisant suivre la valeur par une virgule (il n'est
pas suffisant de placer cette valeur entre parenthèses). Pas très joli, mais efficace.
Par exemple :

>>>

>>> empty = ()
>>> singleton = 'hello', # <-- note trailing comma
>>> len(empty)
0
>>> len(singleton)
1
>>> singleton
('hello',)

L'instruction t = 12345, 54321, 'hello !' est un exemple d'un d'agrégation de


n-uplet (tuple packing en anglais) : les valeurs 12345, 54321 et hello ! sont
agrégées ensemble dans un n-uplet. L'opération inverse est aussi possible :
>>>

>>> x, y, z = t

Ceci est appelé, de façon plus ou moins appropriée, un dissociation de


séquence (sequence unpacking en anglais) et fonctionne pour toute séquence
placée à droite de l'expression. Cette dissociation requiert autant de variables dans
la partie gauche qu'il y a d'éléments dans la séquence. Notez également que cette
affectation multiple est juste une combinaison entre une agrégation de n-uplet et une
dissociation de séquence.

5.4. Ensembles
Python fournit également un type de donnée pour les ensembles. Un ensemble est
une collection non ordonnée sans élément dupliqué. Des utilisations basiques
concernent par exemple des tests d'appartenance ou des suppressions de doublons.
Les ensembles savent également effectuer les opérations mathématiques telles que
les unions, intersections, différences et différences symétriques.

Des accolades ou la fonction set() peuvent être utilisés pour créer des ensembles.


Notez que pour créer un ensemble vide, {} ne fonctionne pas, cela crée un
dictionnaire vide. Utilisez plutôt set().

Voici une brève démonstration :

>>>

>>> basket = {'apple', 'orange', 'apple', 'pear', 'orange',


'banana'}
>>> print(basket) # show that duplicates
have been removed
{'orange', 'banana', 'pear', 'apple'}
>>> 'orange' in basket # fast membership testing
True
>>> 'crabgrass' in basket
False

>>> # Demonstrate set operations on unique letters from two words


...
>>> a = set('abracadabra')
>>> b = set('alacazam')
>>> a # unique letters in a
{'a', 'r', 'b', 'c', 'd'}
>>> a - b # letters in a but not in
b
{'r', 'd', 'b'}
>>> a | b # letters in a or b or
both
{'a', 'c', 'r', 'd', 'b', 'm', 'z', 'l'}
>>> a & b # letters in both a and b
{'a', 'c'}
>>> a ^ b # letters in a or b but
not both
{'r', 'd', 'b', 'm', 'z', 'l'}

Tout comme pour les compréhensions de listes, il est possible d'écrire des


compréhensions d'ensembles :

>>>

>>> a = {x for x in 'abracadabra' if x not in 'abc'}


>>> a
{'r', 'd'}

5.5. Dictionnaires
Un autre type de donnée très utile, natif dans Python, est le dictionnaire (voir Les
types de correspondances — dict). Ces dictionnaires sont parfois présents dans
d'autres langages sous le nom de « mémoires associatives » ou de « tableaux
associatifs ». À la différence des séquences, qui sont indexées par des nombres, les
dictionnaires sont indexés par des clés, qui peuvent être de n'importe quel type
immuable ; les chaînes de caractères et les nombres peuvent toujours être des clés.
Des n-uplets peuvent être utilisés comme clés s'ils ne contiennent que des chaînes,
des nombres ou des n-uplets ; si un n-uplet contient un objet muable, de façon
directe ou indirecte, il ne peut pas être utilisé comme une clé. Vous ne pouvez pas
utiliser des listes comme clés, car les listes peuvent être modifiées en place en
utilisant des affectations par position, par tranches ou via des méthodes
comme append() ou extend().

Le plus simple est de considérer les dictionnaires comme des ensembles de


paires clé: valeur, les clés devant être uniques (au sein d'un dictionnaire). Une paire
d'accolades crée un dictionnaire vide : {}. Placer une liste de paires clé:valeur
séparées par des virgules à l'intérieur des accolades ajoute les valeurs
correspondantes au dictionnaire ; c'est également de cette façon que les
dictionnaires sont affichés.

Les opérations classiques sur un dictionnaire consistent à stocker une valeur pour
une clé et à extraire la valeur correspondant à une clé. Il est également possible de
supprimer une paire clé:valeur avec del. Si vous stockez une valeur pour une clé qui
est déjà utilisée, l'ancienne valeur associée à cette clé est perdue. Si vous tentez
d'extraire une valeur associée à une clé qui n'existe pas, une exception est levée.

Exécuter list(d) sur un dictionnaire d renvoie une liste de toutes les clés utilisées


dans le dictionnaire, dans l'ordre d'insertion (si vous voulez qu'elles soient
ordonnées, utilisez sorted(d)). Pour tester si une clé est dans le dictionnaire,
utilisez le mot-clé in.

Voici un petit exemple utilisant un dictionnaire :

>>>

>>> tel = {'jack': 4098, 'sape': 4139}


>>> tel['guido'] = 4127
>>> tel
{'jack': 4098, 'sape': 4139, 'guido': 4127}
>>> tel['jack']
4098
>>> del tel['sape']
>>> tel['irv'] = 4127
>>> tel
{'jack': 4098, 'guido': 4127, 'irv': 4127}
>>> list(tel)
['jack', 'guido', 'irv']
>>> sorted(tel)
['guido', 'irv', 'jack']
>>> 'guido' in tel
True
>>> 'jack' not in tel
False

Le constructeur dict() fabrique un dictionnaire directement à partir d'une liste de


paires clé-valeur stockées sous la forme de n-uplets :

>>>

>>> dict([('sape', 4139), ('guido', 4127), ('jack', 4098)])


{'sape': 4139, 'guido': 4127, 'jack': 4098}

De plus, il est possible de créer des dictionnaires par compréhension depuis un jeu
de clef et valeurs :

>>>

>>> {x: x**2 for x in (2, 4, 6)}


{2: 4, 4: 16, 6: 36}
Lorsque les clés sont de simples chaînes de caractères, il est parfois plus facile de
spécifier les paires en utilisant des paramètres nommés :

>>>

>>> dict(sape=4139, guido=4127, jack=4098)


{'sape': 4139, 'guido': 4127, 'jack': 4098}

5.6. Techniques de boucles
Lorsque vous faites une boucle sur un dictionnaire, les clés et leurs valeurs peuvent
être récupérées en même temps en utilisant la méthode items() :

>>>

>>> knights = {'gallahad': 'the pure', 'robin': 'the brave'}


>>> for k, v in knights.items():
... print(k, v)
...
gallahad the pure
robin the brave

Lorsque vous itérez sur une séquence, la position et la valeur correspondante


peuvent être récupérées en même temps en utilisant la fonction enumerate().

>>>

>>> for i, v in enumerate(['tic', 'tac', 'toe']):


... print(i, v)
...
0 tic
1 tac
2 toe

Pour faire des boucles sur deux séquences ou plus en même temps, les éléments
peuvent être associés par la fonction zip() :

>>>

>>> questions = ['name', 'quest', 'favorite color']


>>> answers = ['lancelot', 'the holy grail', 'blue']
>>> for q, a in zip(questions, answers):
... print('What is your {0}? It is {1}.'.format(q, a))
...
What is your name? It is lancelot.
What is your quest? It is the holy grail.
What is your favorite color? It is blue.

Pour faire une boucle en sens inverse sur une séquence, commencez par spécifier la
séquence dans son ordre normal, puis appliquez la fonction reversed() :

>>>

>>> for i in reversed(range(1, 10, 2)):


... print(i)
...
9
7
5
3
1

Pour parcourir les éléments d'une séquence de manière ordonnée, utilisez la


fonction sorted(), elle renvoie une nouvelle liste ordonnée sans altérer la source :

>>>

>>> basket = ['apple', 'orange', 'apple', 'pear', 'orange',


'banana']
>>> for f in sorted(set(basket)):
... print(f)
...
apple
banana
orange
pear

Il est parfois tentant de modifier une liste pendant son itération. Cependant, c'est
souvent plus simple et plus sûr de créer une nouvelle liste à la place.

>>>

>>> import math


>>> raw_data = [56.2, float('NaN'), 51.7, 55.3, 52.5,
float('NaN'), 47.8]
>>> filtered_data = []
>>> for value in raw_data:
... if not math.isnan(value):
... filtered_data.append(value)
...
>>> filtered_data
[56.2, 51.7, 55.3, 52.5, 47.8]
5.7. Plus d'informations sur les conditions
Les conditions utilisées dans une instruction while ou if peuvent contenir n'importe
quel opérateur, pas seulement des comparaisons.

Les opérateurs de comparaison in et not in testent si une valeur est présente ou


non dans une séquence. Les opérateurs is et is not testent si deux objets sont
vraiment le même objet ; ceci n'est important que pour des objets muables comme
des listes. Tous les opérateurs de comparaison ont la même priorité, qui est plus
faible que celle des opérateurs numériques.

Les comparaisons peuvent être enchaînées. Par exemple, a < b == c teste si a est


inférieur à b et si, de plus, b égale c.

Les comparaisons peuvent être combinées en utilisant les opérateurs


booléens and et or, le résultat d'une comparaison (ou de toute expression
booléenne) pouvant être inversé avec not. Ces opérateurs ont une priorité inférieure
à celle des opérateurs de comparaison ; entre eux, not a la priorité la plus élevée
et or la plus faible, de telle sorte que A and not B or C est équivalent
à (A and (not B)) or C. Comme toujours, des parenthèses peuvent être
utilisées pour exprimer l'instruction désirée.

Les opérateurs booléens and et or sont appelés opérateurs en circuit court : leurs


arguments sont évalués de la gauche vers la droite et l'évaluation s'arrête dès que le
résultat est déterminé. Par exemple, si A et C sont vrais et B est
faux, A and B and C n'évalue pas l'expression C. Lorsqu'elle est utilisée en tant
que valeur et non en tant que booléen, la valeur de retour d'un opérateur en circuit
court est celle du dernier argument évalué.

Il est possible d'affecter le résultat d'une comparaison ou d'une autre expression


booléenne à une variable. Par exemple :

>>>

>>> string1, string2, string3 = '', 'Trondheim', 'Hammer Dance'


>>> non_null = string1 or string2 or string3
>>> non_null
'Trondheim'

Notez qu'en Python, à la différence du C, des affectations ne peuvent pas intervenir


à l'intérieur d'expressions. Les programmeurs C râleront peut-être après cela, mais
cela évite des erreurs fréquentes que l'on rencontre en C, lorsque l'on tape = alors
que l'on voulait faire un test avec ==.

5.8. Comparer des séquences avec d'autres types


Des séquences peuvent être comparées avec d'autres séquences du même type. La
comparaison utilise un ordre lexicographique : les deux premiers éléments de
chaque séquence sont comparés et, s'ils diffèrent, cela détermine le résultat de la
comparaison ; s'ils sont égaux, les deux éléments suivants sont comparés à leur tour
et ainsi de suite jusqu'à ce que l'une des séquences soit épuisée. Si deux éléments à
comparer sont eux-mêmes des séquences du même type, alors la comparaison
lexicographique est effectuée récursivement. Si tous les éléments des deux
séquences sont égaux, les deux séquences sont alors considérées comme égales.
Si une séquence est une sous-séquence de l'autre, la séquence la plus courte est
celle dont la valeur est inférieure. La comparaison lexicographique des chaînes de
caractères utilise le code Unicode des caractères. Voici quelques exemples de
comparaisons entre séquences de même type :

(1, 2, 3) < (1, 2, 4)


[1, 2, 3] < [1, 2, 4]
'ABC' < 'C' < 'Pascal' < 'Python'
(1, 2, 3, 4) < (1, 2, 4)
(1, 2) < (1, 2, -1)
(1, 2, 3) == (1.0, 2.0, 3.0)
(1, 2, ('aa', 'ab')) < (1, 2, ('abc', 'a'), 4)

Comparer des objets de type différents avec < ou > est autorisé si les objets ont des
méthodes de comparaison appropriées. Par exemple, les types numériques sont
comparés via leur valeur numérique, donc 0 égale 0,0, etc. Dans les autres cas, au
lieu de donner un ordre imprévisible, l'interpréteur lève une exception TypeError.

Notes

1 D'autres langages renvoient l'objet modifié, ce qui permet de chaîner les méthodes comme
ceci : d->insert("a")->remove("b")->sort();.

6. Modules
Lorsque vous quittez et entrez à nouveau dans l'interpréteur Python, tout ce que
vous avez déclaré dans la session précédente est perdu. Afin de rédiger des
programmes plus longs, vous devez utiliser un éditeur de texte, préparer votre code
dans un fichier et exécuter Python avec ce fichier en paramètre. Cela s'appelle créer
un script. Lorsque votre programme grandit, vous pouvez séparer votre code dans
plusieurs fichiers. Ainsi, il vous est facile de réutiliser des fonctions écrites pour un
programme dans un autre sans avoir à les copier.

Pour gérer cela, Python vous permet de placer des définitions dans un fichier et de
les utiliser dans un script ou une session interactive. Un tel fichier est appelé
un module et les définitions d'un module peuvent être importées dans un autre
module ou dans le module main (qui est le module qui contient vos variables et
définitions lors de l'exécution d'un script au niveau le plus haut ou en mode interactif).

Un module est un fichier contenant des définitions et des instructions. Son nom de
fichier est le nom du module suffixé de .py. À l'intérieur d'un module, son propre
nom est accessible par la variable __name__. Par exemple, prenez votre éditeur
favori et créez un fichier fibo.py dans le répertoire courant qui contient :

# Fibonacci numbers module

def fib(n): # write Fibonacci series up to n


a, b = 0, 1
while a < n:
print(a, end=' ')
a, b = b, a+b
print()

def fib2(n): # return Fibonacci series up to n


result = []
a, b = 0, 1
while a < n:
result.append(a)
a, b = b, a+b
return result

Maintenant, ouvrez un interpréteur et importez le module en tapant :

>>>

>>> import fibo

Cela n'importe pas les noms des fonctions définies dans fibo directement dans la
table des symboles courants mais y ajoute simplement fibo. Vous pouvez donc
appeler les fonctions via le nom du module :

>>>
>>> fibo.fib(1000)
0 1 1 2 3 5 8 13 21 34 55 89 144 233 377 610 987
>>> fibo.fib2(100)
[0, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89]
>>> fibo.__name__
'fibo'

Si vous avez l'intention d'utiliser souvent une fonction, il est possible de lui assigner
un nom local :

>>>

>>> fib = fibo.fib


>>> fib(500)
0 1 1 2 3 5 8 13 21 34 55 89 144 233 377

6.1. Les modules en détail


Un module peut contenir aussi bien des instructions que des déclarations de
fonctions. Ces instructions permettent d'initialiser le module. Elles ne sont exécutées
que la première fois que le nom d'un module est trouvé dans un import 1 (elles sont
aussi exécutées lorsque le fichier est exécuté en tant que script).

Chaque module possède sa propre table de symboles, utilisée comme table de


symboles globaux par toutes les fonctions définies par le module. Ainsi l'auteur d'un
module peut utiliser des variables globales dans un module sans se soucier de
collisions de noms avec des variables globales définies par l'utilisateur du module.
Cependant, si vous savez ce que vous faites, vous pouvez modifier une variable
globale d'un module avec la même notation que pour accéder aux
fonctions : nommodule.nomelement.

Des modules peuvent importer d'autres modules. Il est courant, mais pas obligatoire,
de ranger tous les import au début du module (ou du script). Les noms des
modules importés sont insérés dans la table des symboles globaux du module qui
importe.

Il existe une variante de l'instruction import qui importe les noms d'un module


directement dans la table de symboles du module qui l'importe, par exemple :

>>>

>>> from fibo import fib, fib2


>>> fib(500)
0 1 1 2 3 5 8 13 21 34 55 89 144 233 377

Cela n'insère pas le nom du module depuis lequel les définitions sont récupérées
dans la table des symboles locaux (dans cet exemple, fibo n'est pas défini).

Il existe même une variante permettant d'importer tous les noms qu'un module
définit :

>>>

>>> from fibo import *


>>> fib(500)
0 1 1 2 3 5 8 13 21 34 55 89 144 233 377

Tous les noms ne commençant pas par un tiret bas ( _) sont importés. Dans la
grande majorité des cas, les développeurs n'utilisent pas cette syntaxe puisqu'en
important un ensemble indéfini de noms, des noms déjà définis peuvent se retrouver
masqués.

Notez qu'en général, importer * d'un module ou d'un paquet est déconseillé.


Souvent, le code devient difficilement lisible. Son utilisation en mode interactif est
acceptée pour gagner quelques secondes.

Si le nom du module est suivi par as, alors le nom suivant as est directement lié au
module importé.

>>>

>>> import fibo as fib


>>> fib.fib(500)
0 1 1 2 3 5 8 13 21 34 55 89 144 233 377

Dans les faits, le module est importé de la même manière qu'avec import fibo, la


seule différence est qu'il sera disponible sous le nom de fib.

C'est aussi valide en utilisant from, et a le même effet :

>>>

>>> from fibo import fib as fibonacci


>>> fibonacci(500)
0 1 1 2 3 5 8 13 21 34 55 89 144 233 377

Note
 

pour des raisons de performance, chaque module n'est importé qu'une fois par
session. Si vous changez le code d'un module vous devez donc redémarrer
l'interpréteur afin d'en voir l'impact ; ou, s'il s'agit simplement d'un seul module que
vous voulez tester en mode interactif, vous pouvez le ré-importer explicitement en
utilisant importlib.reload(), par
exemple : import importlib; importlib.reload(nommodule).

6.1.1. Exécuter des modules comme des scripts


Lorsque vous exécutez un module Python avec

python fibo.py <arguments>

le code du module est exécuté comme si vous l'aviez importé mais


son __name__ vaut "__main__". Donc, en ajoutant ces lignes à la fin du module :

if __name__ == "__main__":
import sys
fib(int(sys.argv[1]))

vous pouvez rendre le fichier utilisable comme script aussi bien que comme module
importable, car le code qui analyse la ligne de commande n'est lancé que si le
module est exécuté comme fichier « main » :

$ python fibo.py 50
0 1 1 2 3 5 8 13 21 34

Si le fichier est importé, le code n'est pas exécuté :

>>>

>>> import fibo


>>>

C'est typiquement utilisé soit pour proposer une interface utilisateur pour un module,
soit pour lancer les tests sur le module (exécuter le module en tant que script lance
les tests).
6.1.2. Les dossiers de recherche de modules
Lorsqu'un module nommé par exemple spam est importé, il est d'abord recherché
parmi les modules natifs puis, s'il n'est pas trouvé, l'interpréteur cherche un fichier
nommé spam.py dans une liste de dossiers donnée par la variable sys.path. Par
défaut, sys.path est initialisée à :

 le dossier contenant le script courant (ou le dossier courant si aucun script


n'est donné) ;
 PYTHONPATH (une liste de dossiers, utilisant la même syntaxe que la variable
shell PATH) ;
 la valeur par défaut, dépendante de l'installation.

Note

Sur les systèmes qui gèrent les liens symboliques, le dossier contenant le script
courant est résolu après avoir suivi le lien symbolique du script. Autrement dit, le
dossier contenant le lien symbolique n'est pas ajouté aux dossiers de recherche de
modules.

Après leur initialisation, les programmes Python peuvent modifier leur sys.path. Le
dossier contenant le script courant est placé au début de la liste des dossiers à
rechercher, avant les dossiers de bibliothèques. Cela signifie qu'un module dans ce
dossier, ayant le même nom qu'un module, sera chargé à sa place. C'est une erreur
typique, à moins que ce ne soit voulu. Voir Modules standards pour plus
d'informations.

6.1.3. Fichiers Python "compilés"


Pour accélérer le chargement des modules, Python cache une version compilée de
chaque module dans un fichier nommé module(version).pyc (ou version
représente le format du fichier compilé, typiquement une version de Python) dans le
dossier __pycache__. Par exemple, avec CPython 3.3, la version compilée
de spam.py serait __pycache__/spam.cpython-33.pyc. Cette règle de nommage
permet à des versions compilées par des versions différentes de Python de
coexister.

Python compare les dates de modification du fichier source et de sa version


compilée pour voir si le module doit être recompilé. Ce processus est entièrement
automatique. Par ailleurs, les versions compilées sont indépendantes de la
plateforme et peuvent donc être partagées entre des systèmes d'architectures
différentes.
Il existe deux situations où Python ne vérifie pas le cache : le premier cas est lorsque
le module est donné par la ligne de commande (cas où le module est toujours
recompilé, sans même cacher sa version compilée) ; le second cas est lorsque le
module n'a pas de source. Pour gérer un module sans source (où seule la version
compilée est fournie), le module compilé doit se trouver dans le dossier source et sa
source ne doit pas être présente.

Astuces pour les experts :

 vous pouvez utiliser les options -O ou -OO lors de l'appel à Python pour


réduire la taille des modules compilés. L'option -O supprime les
instructions assert et l'option -OO supprime aussi les documentations __doc__.
Cependant, puisque certains programmes ont besoin de ces __doc__, vous ne
devriez utiliser -OO que si vous savez ce que vous faites. Les modules "optimisés"
sont marqués d'un opt- et sont généralement plus petits. Les versions futures de
Python pourraient changer les effets de l'optimisation ;
 un programme ne s'exécute pas plus vite lorsqu'il est lu depuis un .pyc, il est
juste chargé plus vite ;
 le module compileall peut créer des fichiers .pyc pour tous les modules
d'un dossier ;
 vous trouvez plus de détails sur ce processus, ainsi qu'un organigramme des
décisions, dans la PEP 3147.

6.2. Modules standards
Python est accompagné d'une bibliothèque de modules standards, décrits dans la
documentation de la Bibliothèque Python, plus loin. Certains modules sont intégrés
dans l'interpréteur, ils exposent des outils qui ne font pas partie du langage mais qui
font tout de même partie de l'interpréteur, soit pour le côté pratique, soit pour exposer
des outils essentiels tels que l'accès aux appels système. La composition de ces
modules est configurable à la compilation et dépend aussi de la plateforme cible. Par
exemple, le module winreg n'est proposé que sur les systèmes Windows. Un
module mérite une attention particulière, le module sys, qui est présent dans tous les
interpréteurs Python. Les variables sys.ps1 et sys.ps2 définissent les chaînes
d'invites principales et secondaires :

>>>

>>> import sys


>>> sys.ps1
'>>> '
>>> sys.ps2
'... '
>>> sys.ps1 = 'C> '
C> print('Yuck!')
Yuck!
C>

Ces deux variables ne sont définies que si l'interpréteur est en mode interactif.

La variable sys.path est une liste de chaînes qui détermine les chemins de


recherche de modules pour l'interpréteur. Elle est initialisée à un chemin par défaut
pris de la variable d'environnement PYTHONPATH ou d'une valeur par défaut interne
si PYTHONPATH n'est pas définie. sys.path est modifiable en utilisant les opérations
habituelles des listes :

>>>

>>> import sys


>>> sys.path.append('/ufs/guido/lib/python')

6.3. La fonction dir()
La fonction interne dir() est utilisée pour trouver quels noms sont définis par un
module. Elle donne une liste de chaînes classées par ordre lexicographique :

>>>

>>> import fibo, sys


>>> dir(fibo)
['__name__', 'fib', 'fib2']
>>> dir(sys)
['__displayhook__', '__doc__', '__excepthook__', '__loader__',
'__name__',
'__package__', '__stderr__', '__stdin__', '__stdout__',
'_clear_type_cache', '_current_frames', '_debugmallocstats',
'_getframe',
'_home', '_mercurial', '_xoptions', 'abiflags', 'api_version',
'argv',
'base_exec_prefix', 'base_prefix', 'builtin_module_names',
'byteorder',
'call_tracing', 'callstats', 'copyright', 'displayhook',
'dont_write_bytecode', 'exc_info', 'excepthook', 'exec_prefix',
'executable', 'exit', 'flags', 'float_info', 'float_repr_style',
'getcheckinterval', 'getdefaultencoding', 'getdlopenflags',
'getfilesystemencoding', 'getobjects', 'getprofile',
'getrecursionlimit',
'getrefcount', 'getsizeof', 'getswitchinterval',
'gettotalrefcount',
'gettrace', 'hash_info', 'hexversion', 'implementation',
'int_info',
'intern', 'maxsize', 'maxunicode', 'meta_path', 'modules',
'path',
'path_hooks', 'path_importer_cache', 'platform', 'prefix',
'ps1',
'setcheckinterval', 'setdlopenflags', 'setprofile',
'setrecursionlimit',
'setswitchinterval', 'settrace', 'stderr', 'stdin', 'stdout',
'thread_info', 'version', 'version_info', 'warnoptions']

Sans paramètre, dir() liste les noms actuellement définis :

>>>

>>> a = [1, 2, 3, 4, 5]
>>> import fibo
>>> fib = fibo.fib
>>> dir()
['__builtins__', '__name__', 'a', 'fib', 'fibo', 'sys']

Notez qu'elle liste tous les types de noms : les variables, fonctions, modules, etc.

dir() ne liste ni les fonctions primitives, ni les variables internes. Si vous voulez les
lister, elles sont définies dans le module builtins :

>>>

>>> import builtins


>>> dir(builtins)
['ArithmeticError', 'AssertionError', 'AttributeError',
'BaseException',
'BlockingIOError', 'BrokenPipeError', 'BufferError',
'BytesWarning',
'ChildProcessError', 'ConnectionAbortedError',
'ConnectionError',
'ConnectionRefusedError', 'ConnectionResetError',
'DeprecationWarning',
'EOFError', 'Ellipsis', 'EnvironmentError', 'Exception',
'False',
'FileExistsError', 'FileNotFoundError', 'FloatingPointError',
'FutureWarning', 'GeneratorExit', 'IOError', 'ImportError',
'ImportWarning', 'IndentationError', 'IndexError',
'InterruptedError',
'IsADirectoryError', 'KeyError', 'KeyboardInterrupt',
'LookupError',
'MemoryError', 'NameError', 'None', 'NotADirectoryError',
'NotImplemented',
'NotImplementedError', 'OSError', 'OverflowError',
'PendingDeprecationWarning', 'PermissionError',
'ProcessLookupError',
'ReferenceError', 'ResourceWarning', 'RuntimeError',
'RuntimeWarning',
'StopIteration', 'SyntaxError', 'SyntaxWarning', 'SystemError',
'SystemExit', 'TabError', 'TimeoutError', 'True', 'TypeError',
'UnboundLocalError', 'UnicodeDecodeError', 'UnicodeEncodeError',
'UnicodeError', 'UnicodeTranslateError', 'UnicodeWarning',
'UserWarning',
'ValueError', 'Warning', 'ZeroDivisionError', '_',
'__build_class__',
'__debug__', '__doc__', '__import__', '__name__', '__package__',
'abs',
'all', 'any', 'ascii', 'bin', 'bool', 'bytearray', 'bytes',
'callable',
'chr', 'classmethod', 'compile', 'complex', 'copyright',
'credits',
'delattr', 'dict', 'dir', 'divmod', 'enumerate', 'eval', 'exec',
'exit',
'filter', 'float', 'format', 'frozenset', 'getattr', 'globals',
'hasattr',
'hash', 'help', 'hex', 'id', 'input', 'int', 'isinstance',
'issubclass',
'iter', 'len', 'license', 'list', 'locals', 'map', 'max',
'memoryview',
'min', 'next', 'object', 'oct', 'open', 'ord', 'pow', 'print',
'property',
'quit', 'range', 'repr', 'reversed', 'round', 'set', 'setattr',
'slice',
'sorted', 'staticmethod', 'str', 'sum', 'super', 'tuple',
'type', 'vars',
'zip']

6.4. Les paquets


Les paquets sont un moyen de structurer les espaces de nommage des modules
Python en utilisant une notation "pointée". Par exemple, le nom de
module A.B désigne le sous-module B du paquet A. De la même manière que
l'utilisation des modules évite aux auteurs de différents modules d'avoir à se soucier
des noms de variables globales des autres, l'utilisation des noms de modules avec
des points évite aux auteurs de paquets contenant plusieurs modules tel que NumPy
ou Pillow d'avoir à se soucier des noms des modules des autres.
Imaginez que vous voulez construire un ensemble de modules (un "paquet") pour
gérer uniformément les fichiers contenant du son et des données sonores. Il existe
un grand nombre de formats de fichiers pour stocker du son (généralement identifiés
par leur extension, par exemple .wav, .aiff, .au), vous avez donc besoin de créer
et maintenir un nombre croissant de modules pour gérer la conversion entre tous ces
formats. Vous voulez aussi pouvoir appliquer un certain nombre d'opérations sur ces
sons : mixer, ajouter de l'écho, égaliser, ajouter un effet stéréo artificiel, etc. Donc, en
plus des modules de conversion, vous allez écrire une myriade de modules
permettant d'effectuer ces opérations. Voici une structure possible pour votre paquet
(exprimée sous la forme d'une arborescence de fichiers :

sound/ Top-level package


__init__.py Initialize the sound package
formats/ Subpackage for file format
conversions
__init__.py
wavread.py
wavwrite.py
aiffread.py
aiffwrite.py
auread.py
auwrite.py
...
effects/ Subpackage for sound effects
__init__.py
echo.py
surround.py
reverse.py
...
filters/ Subpackage for filters
__init__.py
equalizer.py
vocoder.py
karaoke.py
...

Lorsqu'il importe des paquets, Python cherche dans chaque dossier de sys.path un
sous-dossier du nom du paquet.

Les fichiers __init__.py sont nécessaires pour que Python considère un dossier


contenant ce fichier comme un paquet. Cela évite que des dossiers ayant des noms
courants comme string ne masquent des modules qui auraient été trouvés plus
tard dans la recherche des dossiers. Dans le plus simple des
cas, __init__.py peut être vide, mais il peut aussi exécuter du code d'initialisation
pour son paquet ou configurer la variable __all__ (documentée plus loin).
Les utilisateurs d'un module peuvent importer ses modules individuellement, par
exemple :

import sound.effects.echo

charge le sous-module sound.effects.echo. Il doit alors être référencé par son


nom complet.

sound.effects.echo.echofilter(input, output, delay=0.7, atten=4)

Une autre manière d'importer des sous-modules est :

from sound.effects import echo

charge aussi le sous-module echo et le rend disponible sans avoir à indiquer le


préfixe du paquet. Il peut donc être utilisé comme ceci :

echo.echofilter(input, output, delay=0.7, atten=4)

Une autre méthode consiste à importer la fonction ou la variable désirée


directement :

from sound.effects.echo import echofilter

Le sous-module echo est toujours chargé mais ici la fonction echofilter() est


disponible directement :

echofilter(input, output, delay=0.7, atten=4)

Notez que lorsque vous utilisez from package import element, element peut


aussi bien être un sous-module, un sous-paquet ou simplement un nom déclaré dans
le paquet (une variable, une fonction ou une classe). L'instruction import cherche en
premier si element est défini dans le paquet ; s'il ne l'est pas, elle cherche à charger
un module et, si elle n'en trouve pas, une exception ImportError est levée.

Au contraire, en utilisant la
syntaxe import element.souselement.soussouselement,
chaque element sauf le dernier doit être un paquet. Le dernier element peut être
un module ou un paquet, mais ne peut être ni une fonction, ni une classe, ni une
variable définie dans l'élément précédent.
6.4.1. Importer * depuis un paquet
Qu'arrive-t-il lorsqu'un utilisateur écrit from sound.effects import * ?
Idéalement, on pourrait espérer que Python aille chercher tous les sous-modules du
paquet sur le système de fichiers et qu'ils seraient tous importés. Cela pourrait être
long et importer certains sous-modules pourrait avoir des effets secondaires
indésirables ou, du moins, désirés seulement lorsque le sous-module est importé
explicitement.

La seule solution, pour l'auteur du paquet, est de fournir un index explicite du


contenu du paquet. L'instruction import utilise la convention suivante : si le
fichier __init__.py du paquet définit une liste nommée __all__, cette liste est
utilisée comme liste des noms de modules devant être importés
lorsque from package import * est utilisé. Il est de la responsabilité de l'auteur
du paquet de maintenir cette liste à jour lorsque de nouvelles versions du paquet
sont publiées. Un auteur de paquet peut aussi décider de ne pas autoriser
d'importer * pour son paquet. Par exemple, le
fichier sound/effects/__init__.py peut contenir le code suivant :

__all__ = ["echo", "surround", "reverse"]

Cela signifie que from sound.effects import * importe les trois sous-modules


explicitement désignés du paquet sound.

Si __all__ n'est pas définie, l'instruction from sound.effects import *


n'importe pas tous les sous-modules du paquet sound.effects dans l'espace de
nommage courant mais s'assure seulement que le paquet sound.effects a été
importé (i.e. que tout le code du fichier __init__.py a été exécuté) et importe
ensuite les noms définis dans le paquet. Cela inclut tous les noms définis (et sous-
modules chargés explicitement) par __init__.py. Sont aussi inclus tous les sous-
modules du paquet ayant été chargés explicitement par une instruction import.
Typiquement :

import sound.effects.echo
import sound.effects.surround
from sound.effects import *

Dans cet exemple, les modules echo et surround sont importés dans l'espace de


nommage courant lorsque from...import est exécuté parce qu'ils sont définis
dans le paquet sound.effects (cela fonctionne aussi lorsque __all__ est définie).
Bien que certains modules ont été pensés pour n'exporter que les noms respectant
une certaine structure lorsque import * est utilisé, import * reste considéré
comme une mauvaise pratique dans du code à destination d'un environnement de
production.

Rappelez-vous que rien ne vous empêche


d'utiliser from paquet import sous_module_specifique ! C'est d'ailleurs la
manière recommandée, à moins que le module qui fait les importations ait besoin de
sous-modules ayant le même nom mais provenant de paquets différents.

6.4.2. Références internes dans un paquet


Lorsque les paquets sont organisés en sous-paquets (comme le paquet sound par
exemple), vous pouvez utiliser des importations absolues pour cibler des paquets
voisins. Par exemple, si le module sound.filters.vocoder a besoin du
module echo du paquet sound.effects, il peut
utiliser from sound.effects import echo.

Il est aussi possible d'écrire des importations relatives de la


forme from module import name. Ces importations relatives sont préfixées par
des points pour indiquer leur origine (paquet courant ou parent). Depuis le
module surround, par exemple vous pouvez écrire :

from . import echo


from .. import formats
from ..filters import equalizer

Notez que les importations relatives se fient au nom du module actuel. Puisque le
nom du module principal est toujours "__main__", les modules utilisés par le
module principal d'une application ne peuvent être importés que par des importations
absolues.

6.4.3. Paquets dans plusieurs dossiers


Les paquets possèdent un attribut supplémentaire, __path__, qui est une liste
initialisée avant l'exécution du fichier __init__.py, contenant le nom de son dossier
dans le système de fichiers. Cette liste peut être modifiée, altérant ainsi les futures
recherches de modules et sous-paquets contenus dans le paquet.

Bien que cette fonctionnalité ne soit que rarement utile, elle peut servir à élargir la
liste des modules trouvés dans un paquet.
Notes

En réalité, la déclaration d'une fonction est elle-même une instruction ; son exécution
enregistre le nom de la fonction dans la table des symboles globaux du module.

7. Les entrées/sorties
Il existe bien des moyens de présenter les sorties d'un programmes ; les données
peuvent être affichées sous une forme lisible par un être humain ou sauvegardées
dans un fichier pour une utilisation future. Ce chapitre présente quelques possibilités.

7.1. Formatage de données
Jusqu'ici, nous avons rencontré deux moyens d'écrire des données : les déclarations
d'expressions et la fonction print(). Une troisième méthode consiste à utiliser la
méthode write() des fichiers, avec le fichier de sortie standard référencé en tant
que sys.stdout. Voyez le Guide de Référence de la Bibliothèque Standard pour en
savoir plus.

Souvent vous voudrez plus de contrôle sur le formatage de vos sorties et aller au
delà d’un affichage de valeurs séparées par des espaces. Il y a plusieurs moyens de
les formater.

 Pour utiliser les expressions formatées, commencez une chaine de caractère


avec f ou F avant d’ouvrir vos guillemets doubles ou triples. Dans ces chaines de
caractère, vous pouvez entrer des expressions Python entre les caractères { et } qui
peuvent contenir des variables ou des valeurs littérales.

>>>

>>> year = 2016


>>> event = 'Referendum'
>>> f'Results of the {year} {event}'
'Results of the 2016 Referendum'
 La méthode str.format() sur les chaines de caractères exige un plus grand
effort manuel. Vous utiliserez toujours les caractères { et } pour indiquer où une
variable sera substituée et donner des détails sur son formatage, mais vous devrez
également fournir les informations à formater.
>>>

>>> yes_votes = 42_572_654


>>> no_votes = 43_132_495
>>> percentage = yes_votes / (yes_votes + no_votes)
>>> '{:-9} YES votes {:2.2%}'.format(yes_votes, percentage)
' 42572654 YES votes 49.67%'
 Enfin, vous pouvez construire des concaténations de tranches de chaînes
vous-même, et ainsi créer n'importe quel agencement. Le type des chaînes a des
méthodes utiles pour aligner des chaînes dans une largeur de taille fixe.

Lorsque qu'un affichage basique suffit, pour afficher simplement une variable pour en
inspecter le contenu, vous pouvez convertir n'importe quelle valeur en chaîne de
caractères en utilisant la fonction repr() ou la fonction str().

La fonction str() est destinée à représenter les valeurs sous une forme lisible par un
être humain, alors que la fonction repr() est destinée à générer des représentations
qui puissent être lues par l'interpréteur (ou qui lèvera une SyntaxError s'il n'existe
aucune syntaxe équivalente). Pour les objets qui n'ont pas de représentation
humaine spécifique, str() renvoie la même valeur que repr(). Beaucoup de valeurs,
comme les nombres ou les structures telles que les listes ou les dictionnaires, ont la
même représentation en utilisant les deux fonctions. Les chaînes de caractères, en
particulier, ont deux représentations distinctes.

Quelques exemples :

>>>

>>> s = 'Hello, world.'


>>> str(s)
'Hello, world.'
>>> repr(s)
"'Hello, world.'"
>>> str(1/7)
'0.14285714285714285'
>>> x = 10 * 3.25
>>> y = 200 * 200
>>> s = 'The value of x is ' + repr(x) + ', and y is ' + repr(y)
+ '...'
>>> print(s)
The value of x is 32.5, and y is 40000...
>>> # The repr() of a string adds string quotes and backslashes:
... hello = 'hello, world\n'
>>> hellos = repr(hello)
>>> print(hellos)
'hello, world\n'
>>> # The argument to repr() may be any Python object:
... repr((x, y, ('spam', 'eggs')))
"(32.5, 40000, ('spam', 'eggs'))"

Le module string contient une classe Template qui permet aussi de remplacer des


valeurs au sein de chaînes de caractères, en utilisant des marqueurs comme $x, et
en les remplaçant par les valeurs d'un dictionnaire, mais sa capacité à formater les
chaînes est plus limitée.

7.1.1. Les chaines de caractères formatées (f-strings)


Les chaines de caractères formatées (aussi appelées f-strings) vous permettent
d’inclure la valeur d’expressions Python dans des chaines de caractères en les
préfixant avec f ou F et écrire des expressions comme {expression}.

L'expression peut être suivie d'un spécificateur de format. Cela permet un plus grand
contrôle sur la façon dont la valeur est rendue. L'exemple suivant arrondit pi à trois
décimales après la virgule :

>>>

>>> import math


>>> print(f'The value of pi is approximately {math.pi:.3f}.')
The value of pi is approximately 3.142.

Donner un entier après le ':' indique la largeur minimale de ce champ en nombre de


caractères. C'est utile pour faire de jolis tableaux

>>>

>>> table = {'Sjoerd': 4127, 'Jack': 4098, 'Dcab': 7678}


>>> for name, phone in table.items():
... print(f'{name:10} ==> {phone:10d}')
...
Sjoerd ==> 4127
Jack ==> 4098
Dcab ==> 7678

D’autres modificateurs peuvent être utilisés pour convertir la valeur avant son
formatage. '!a' applique ascii(), '!s' applique str(), et '!r' applique repr() :

>>>
>>> animals = 'eels'
>>> print(f'My hovercraft is full of {animals}.')
My hovercraft is full of eels.
>>> print(f'My hovercraft is full of {animals!r}.')
My hovercraft is full of 'eels'.

Pour une référence sur ces spécifications de formats, voir le guide de référence pour
les Mini-langage de spécification de format.

7.1.2. La méthode de chaine de caractères format()


L'utilisation de base de la méthode str.format() ressemble à ceci :

>>>

>>> print('We are the {} who say "{}!"'.format('knights', 'Ni'))


We are the knights who say "Ni!"

Les accolades et les caractères à l'intérieur (appelés les champs de formatage) sont
remplacés par les objets passés en paramètres à la méthode str.format(). Un nombre
entre accolades se réfère à la position de l'objet passé à la méthode str.format().

>>>

>>> print('{0} and {1}'.format('spam', 'eggs'))


spam and eggs
>>> print('{1} and {0}'.format('spam', 'eggs'))
eggs and spam

Si des arguments nommés sont utilisés dans la méthode str.format(), leurs valeurs


sont utilisées en se basant sur le nom des arguments

>>>

>>> print('This {food} is {adjective}.'.format(


... food='spam', adjective='absolutely horrible'))
This spam is absolutely horrible.

Les arguments positionnés et nommés peuvent être combinés arbitrairement :

>>>

>>> print('The story of {0}, {1}, and {other}.'.format('Bill',


'Manfred',
other='Georg'))
The story of Bill, Manfred, and Georg.

If you have a really long format string that you don't want to split up, it would be nice
if you could reference the variables to be formatted by name instead of by position.
This can be done by simply passing the dict and using square brackets '[]' to access
the keys.

>>>

>>> table = {'Sjoerd': 4127, 'Jack': 4098, 'Dcab': 8637678}


>>> print('Jack: {0[Jack]:d}; Sjoerd: {0[Sjoerd]:d}; '
... 'Dcab: {0[Dcab]:d}'.format(table))
Jack: 4098; Sjoerd: 4127; Dcab: 8637678

Vous pouvez obtenir le même résultat en passant le tableau comme des arguments
nommés en utilisant la notation **

>>>

>>> table = {'Sjoerd': 4127, 'Jack': 4098, 'Dcab': 8637678}


>>> print('Jack: {Jack:d}; Sjoerd: {Sjoerd:d}; Dcab:
{Dcab:d}'.format(**table))
Jack: 4098; Sjoerd: 4127; Dcab: 8637678

C'est particulièrement utile en combinaison avec la fonction native vars() qui renvoie


un dictionnaire contenant toutes les variables locales.

A titre d’exemple, les lignes suivantes produisent un ensemble de colonnes alignées


de façon ordonnée donnant les entiers, leurs carrés et leurs cubes :

>>>

>>> for x in range(1, 11):


... print('{0:2d} {1:3d} {2:4d}'.format(x, x*x, x*x*x))
...
1 1 1
2 4 8
3 9 27
4 16 64
5 25 125
6 36 216
7 49 343
8 64 512
9 81 729
10 100 1000

Pour avoir une description complète du formatage des chaînes de caractères avec la
méthode str.format(), lisez : Syntaxe de formatage de chaîne.

7.1.3. Formatage de chaînes à la main


Voici le même tableau de carrés et de cubes, formaté à la main :

>>>

>>> for x in range(1, 11):


... print(repr(x).rjust(2), repr(x*x).rjust(3), end=' ')
... # Note use of 'end' on previous line
... print(repr(x*x*x).rjust(4))
...
1 1 1
2 4 8
3 9 27
4 16 64
5 25 125
6 36 216
7 49 343
8 64 512
9 81 729
10 100 1000

(Remarquez que l'espace séparant les colonnes vient de la manière


donc print() fonctionne : il ajoute toujours des espaces entre ses arguments.)

La méthode str.rjust() des chaînes de caractères justifie à droite une chaîne dans un


champ d'une largeur donnée en ajoutant des espaces sur la gauche. Il existe des
méthodes similaires str.ljust() et str.center(). Ces méthodes n'écrivent rien, elles
renvoient simplement une nouvelle chaîne. Si la chaîne passée en paramètre est
trop longue, elle n'est pas tronquée mais renvoyée sans modification ; cela peut
chambouler votre mise en page mais c'est souvent préférable à l'alternative, qui
pourrait mentir sur une valeur (et si vous voulez vraiment tronquer vos valeurs, vous
pouvez toujours utiliser une tranche, comme dans x.ljust(n)[:n]).

Il existe une autre méthode, str.zfill(), qui comble une chaîne numérique à gauche
avec des zéros. Elle comprend les signes plus et moins :

>>>

>>> '12'.zfill(5)
'00012'
>>> '-3.14'.zfill(7)
'-003.14'
>>> '3.14159265359'.zfill(5)
'3.14159265359'

7.1.4. Anciennes méthodes de formatage de chaînes


The % operator (modulo) can also be used for string formatting.
Given 'string' % values, instances of % in string are replaced with zero or more
elements of values. This operation is commonly known as string interpolation. For
example:

>>>

>>> import math


>>> print('The value of pi is approximately %5.3f.' % math.pi)
The value of pi is approximately 3.142.

Vous trouvez plus d'informations dans la section Formatage de chaines à la printf.

7.2. Lecture et écriture de fichiers


La fonction open() renvoie un objet fichier et est le plus souvent utilisée avec deux
arguments : open(nomfichier, mode).

>>>

>>> f = open('workfile', 'w')

Le premier argument est une chaîne contenant le nom du fichier. Le deuxième


argument est une autre chaîne contenant quelques caractères décrivant la façon
dont le fichier est utilisé. mode peut être 'r' quand le fichier n'est accédé qu'en
lecture, 'w' en écriture seulement (un fichier existant portant le même nom sera alors
écrasé) et 'a' ouvre le fichier en mode ajout (toute donnée écrite dans le fichier est
automatiquement ajoutée à la fin). 'r+' ouvre le fichier en mode lecture/écriture.
L'argument mode est optionnel, sa valeur par défaut est 'r'.

Normalement, les fichiers sont ouverts en mode texte, c'est-à-dire que vous lisez et
écrivez des chaînes de caractères depuis et dans ce fichier, suivant un encodage
donné. Si aucun encodage n'est spécifié, l'encodage par défaut dépend de la
plateforme (voir open()). 'b' collé à la fin du mode indique que le fichier doit être ouvert
en mode binaire c'est-à-dire que les données sont lues et écrites sous formes
d'octets (type bytes). Ce mode est à utiliser pour les fichiers contenant autre chose
que du texte.

En mode texte, le comportement par défaut, à la lecture, est de convertir les fin de
lignes spécifiques à la plateforme (\n sur Unix, \r\n sur Windows etc...) en simples \n.
Lors de l'écriture, le comportement par défaut est d'appliquer l'opération inverse :
les \n sont convertis dans leur équivalent sur la plateforme courante. Ces
modifications effectuées automatiquement sont normales pour du texte mais
détérioreraient des données binaires contenues dans un fichier de type JPEG ou EXE.
Soyez particulièrement attentifs à ouvrir ces fichiers binaires en mode binaire.

C'est une bonne pratique d'utiliser le mot-clé with lorsque vous traitez des fichiers.
Vous fermez ainsi toujours correctement le fichier, même si une exception est levée.
Utiliser with est aussi beaucoup plus court que d'utiliser l'équivalent avec des
blocs try-finally :

>>>

>>> with open('workfile') as f:


... read_data = f.read()
>>> f.closed
True

Si vous n'utilisez pas le mot clef with, vous devez appeler f.close() pour fermer le


fichier et immédiatement libérer les ressources système qu'il utilise. Si vous ne
fermez pas explicitement le fichier, le ramasse-miette de Python finira par détruire
l'objet et fermer le fichier pour vous, mais le fichier peut rester ouvert pendant un
moment. Un autre risque est que différentes implémentations de Python risquent
faire ce nettoyage à des moments différents.

Après la fermeture du fichier, que ce soit via une instruction with ou en


appelant f.close(), toute tentative d'utilisation de l'objet fichier échoue
systématiquement.

>>>

>>> f.close()
>>> f.read()
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
ValueError: I/O operation on closed file.
7.2.1. Méthodes des objets fichiers
Les derniers exemples de cette section supposent qu'un objet fichier appelé f a déjà
été créé.

To read a file's contents, call f.read(size), which reads some quantity of data and
returns it as a string (in text mode) or bytes object (in binary mode).  size is an
optional numeric argument. When size is omitted or negative, the entire contents of
the file will be read and returned; it's your problem if the file is twice as large as your
machine's memory. Otherwise, at most size characters (in text mode) or size bytes
(in binary mode) are read and returned. If the end of the file has been
reached, f.read() will return an empty string ('').

>>>

>>> f.read()
'This is the entire file.\n'
>>> f.read()
''

f.readline() lit une seule ligne du fichier ; un caractère de fin de ligne ( \n) est laissé à la
fin de la chaîne. Il n'est omis que sur la dernière ligne du fichier si celui-ci ne se
termine pas un caractère de fin de ligne. Ceci permet de rendre la valeur de retour
non ambigüe : si f.readline() renvoie une chaîne vide, c'est que la fin du fichier a été
atteinte, alors qu'une ligne vide est représentée par '\n' (une chaîne de caractères ne
contenant qu'une fin de ligne).

>>>

>>> f.readline()
'This is the first line of the file.\n'
>>> f.readline()
'Second line of the file\n'
>>> f.readline()
''

Pour lire ligne à ligne, vous pouvez aussi boucler sur l'objet fichier. C'est plus efficace
en terme de gestion mémoire, plus rapide et donne un code plus simple :

>>>

>>> for line in f:


... print(line, end='')
...
This is the first line of the file.
Second line of the file

Pour construire une liste avec toutes les lignes d'un fichier, il est aussi possible
d'utiliser list(f) ou f.readlines().

f.write(chaine) écrit le contenu de chaine dans le fichier et renvoie le nombre de


caractères écrits.

>>>

>>> f.write('This is a test\n')


15

Les autres types doivent être convertis, soit en une chaîne (en mode texte), soit en
objet bytes (en mode binaire) avant de les écrire :

>>>

>>> value = ('the answer', 42)


>>> s = str(value) # convert the tuple to string
>>> f.write(s)
18

f.tell() renvoie un entier indiquant la position actuelle dans le fichier, mesurée en


octets à partir du début du fichier lorsque le fichier est ouvert en mode binaire, ou un
nombre obscur en mode texte.

To change the file object's position, use f.seek(offset, whence). The position is


computed from adding offset to a reference point; the reference point is selected by
the whence argument. A whence value of 0 measures from the beginning of the file,
1 uses the current file position, and 2 uses the end of the file as the reference
point. whence can be omitted and defaults to 0, using the beginning of the file as the
reference point.

>>>

>>> f = open('workfile', 'rb+')


>>> f.write(b'0123456789abcdef')
16
>>> f.seek(5) # Go to the 6th byte in the file
5
>>> f.read(1)
b'5'
>>> f.seek(-3, 2) # Go to the 3rd byte before the end
13
>>> f.read(1)
b'd'

Sur un fichier en mode texte (ceux ouverts sans b dans le mode), seuls les
changements de position relatifs au début du fichier sont autorisés (sauf une
exception : se rendre à la fin du fichier avec seek(0, 2)) et les seules valeurs
possibles pour le paramètre decalage sont les valeurs renvoyées par f.tell(), ou zéro.
Toute autre valeur pour le paramètre decalage produit un comportement indéfini.

Les fichiers disposent de méthodes supplémentaires, telles


que isatty() et truncate() qui sont moins souvent utilisées ; consultez la Référence de la
Bibliothèque Standard pour avoir un guide complet des objets fichiers.

7.2.2. Sauvegarde de données structurées avec le


module json
Les chaînes de caractères peuvent facilement être écrites dans un fichier et relues.
Les nombres nécessitent un peu plus d'effort, car la méthode read() ne renvoie que
des chaînes. Elles doivent donc être passées à une fonction comme int(), qui prend
une chaîne comme '123' en entrée et renvoie sa valeur numérique 123. Mais dès que
vous voulez enregistrer des types de données plus complexes comme des listes, des
dictionnaires ou des instances de classes, le traitement lecture/écriture à la main
devient vite compliqué.

Plutôt que de passer son temps à écrire et déboguer du code permettant de


sauvegarder des types de données compliqués, Python permet d'utiliser JSON
(JavaScript Object Notation), un format répandu de représentation et d'échange de
données. Le module standard appelé json peut transformer des données
hiérarchisées Python en une représentation sous forme de chaîne de caractères. Ce
processus est nommé sérialiser. Reconstruire les données à partir de leur
représentation sous forme de chaîne est appelé déserialiser. Entre sa sérialisation et
sa dé-sérialisation, la chaîne représentant les données peut avoir été stockée ou
transmise à une autre machine.

Note

Le format JSON est couramment utilisé dans les applications modernes pour
échanger des données. Beaucoup de développeurs le maîtrise, ce qui en fait un
format de prédilection pour l'interopérabilité.

Si vous avez un objet x, vous pouvez voir sa représentation JSON en tapant


simplement :
>>>

>>> import json


>>> json.dumps([1, 'simple', 'list'])
'[1, "simple", "list"]'

Une variante de la fonction dumps(), nommée dump(), sérialise simplement l'objet


donné vers un fichier texte. Donc si f est un fichier texte ouvert en écriture, il est
possible de faire :

json.dump(x, f)

Pour reconstruire l'objet, si f est cette fois un fichier texte ouvert en lecture :

x = json.load(f)

Cette méthode de sérialisation peut sérialiser des listes et des dictionnaires. Mais
sérialiser d'autres types de données requiert un peu plus de travail. La
documentation du module json explique comment faire.

Voir aussi
 

Le module pickle

Au contraire de JSON, pickle est un protocole permettant la sérialisation d'objets


Python arbitrairement complexes. Il est donc spécifique à Python et ne peut pas être
utilisé pour communiquer avec d'autres langages. Il est aussi, par défaut, une source
de vulnérabilité : dé-sérialiser des données au format pickle provenant d'une source
malveillante et particulièrement habile peut mener à exécuter du code arbitraire.

8. Erreurs et exceptions
Jusqu'ici, les messages d'erreurs ont seulement été mentionnés. Mais si vous avez
essayé les exemples vous avez certainement vu plus que cela. En fait, il y a au
moins deux types d'erreurs à distinguer : les erreurs de syntaxe et les exceptions.
8.1. Les erreurs de syntaxe
Les erreurs de syntaxe, qui sont des erreurs d'analyse du code, sont peut-être celles
que vous rencontrez le plus souvent lorsque vous êtes encore en phase
d'apprentissage de Python :

>>>

>>> while True print('Hello world')


File "<stdin>", line 1
while True print('Hello world')
^
SyntaxError: invalid syntax

L'analyseur indique la ligne incriminée et affiche une petite « flèche » pointant vers le
premier endroit de la ligne où l'erreur a été détectée. L'erreur est causée (ou, au
moins, a été détectée comme telle) par le symbole placé avant la flèche. Dans cet
exemple la flèche est sur la fonction print() car il manque deux points (':') juste
avant. Le nom du fichier et le numéro de ligne sont affichés pour vous permettre de
localiser facilement l'erreur lorsque le code provient d'un script.

8.2. Exceptions
Même si une instruction ou une expression est syntaxiquement correcte, elle peut
générer une erreur lors de son exécution. Les erreurs détectées durant l'exécution
sont appelées des exceptions et ne sont pas toujours fatales : nous apprendrons
bientôt comment les traiter dans vos programmes. La plupart des exceptions
toutefois ne sont pas prises en charge par les programmes, ce qui génère des
messages d'erreurs comme celui-ci :

>>>

>>> 10 * (1/0)
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
ZeroDivisionError: division by zero
>>> 4 + spam*3
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
NameError: name 'spam' is not defined
>>> '2' + 2
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
TypeError: Can't convert 'int' object to str implicitly
La dernière ligne du message d'erreur indique ce qui s'est passé. Les exceptions
peuvent être de différents types et ce type est indiqué dans le message : les types
indiqués dans l'exemple sont ZeroDivisionError, NameError et TypeError. Le
texte affiché comme type de l'exception est le nom de l'exception native qui a été
déclenchée. Ceci est vrai pour toutes les exceptions natives mais n'est pas une
obligation pour les exceptions définies par l'utilisateur (même si c'est une convention
bien pratique). Les noms des exceptions standards sont des identifiants natifs (pas
des mots-clef réservés).

Le reste de la ligne fournit plus de détails en fonction du type de l'exception et de ce


qui l'a causée.

La partie précédente du message d'erreur indique le contexte dans lequel s'est


produite l'exception, sous la forme d'une trace de pile d'exécution. En général, celle-
ci contient les lignes du code source ; toutefois, les lignes lues à partir de l'entrée
standard ne sont pas affichées.

Vous trouvez la liste des exceptions natives et leur signification dans Exceptions


natives.

8.3. Gestion des exceptions


Il est possible d'écrire des programmes qui prennent en charge certaines exceptions.
Regardez l'exemple suivant, qui demande une saisie à l'utilisateur jusqu'à ce qu'un
entier valide ait été entré, mais permet à l'utilisateur d'interrompre le programme (en
utilisant Control-C ou un autre raccourci que le système accepte) ; notez qu'une
interruption générée par l'utilisateur est signalée en levant
l'exception KeyboardInterrupt. :

>>>

>>> while True:


... try:
... x = int(input("Please enter a number: "))
... break
... except ValueError:
... print("Oops! That was no valid number. Try
again...")
...

L'instruction try fonctionne comme ceci :

 premièrement, la clause try (instruction(s) placée(s) entre les mots-


clés try et except) est exécutée.
 si aucune exception n'intervient, la clause except est sautée et l'exécution de
l'instruction try est terminée.
 si une exception intervient pendant l'exécution de la clause try, le reste de
cette clause est sauté. Si le type d'exception levée correspond à un nom indiqué
après le mot-clé except, la clause except correspondante est exécutée, puis
l'exécution continue après l'instruction try.
 si une exception intervient et ne correspond à aucune exception mentionnée
dans la clause except, elle est transmise à l'instruction try de niveau supérieur ; si
aucun gestionnaire d'exception n'est trouvé, il s'agit d'une exception non gérée et
l'exécution s'arrête avec un message comme indiqué ci-dessus.

Une instruction try peut comporter plusieurs clauses except pour permettre la prise


en charge de différentes exceptions. Mais un seul gestionnaire, au plus, sera
exécuté. Les gestionnaires ne prennent en charge que les exceptions qui
interviennent dans la clause !try correspondante, pas dans d'autres gestionnaires de
la même instruction try. Mais une même clause except peut citer plusieurs
exceptions sous la forme d'un tuple entre parenthèses, comme dans cet exemple :

... except (RuntimeError, TypeError, NameError):


... pass

Une classe dans une clause except est compatible avec une exception si elle est de
la même classe ou d'une de ses classes dérivées. Mais l'inverse n'est pas vrai, une
clause except spécifiant une classe dérivée n'est pas compatible avec une classe
de base. Par exemple, le code suivant affiche B, C et D dans cet ordre :

class B(Exception):
pass

class C(B):
pass

class D(C):
pass

for cls in [B, C, D]:


try:
raise cls()
except D:
print("D")
except C:
print("C")
except B:
print("B")
Notez que si les clauses except avaient été inversées (avec except B en premier),
il aurait affiché B, B, B — la première clause except qui correspond est déclenchée.

La dernière clause except peut omettre le(s) nom(s) d'exception(s) et joue alors le


rôle de joker. C'est toutefois à utiliser avec beaucoup de précautions car il est facile
de masquer une vraie erreur de programmation par ce biais. Elle peut aussi être
utilisée pour afficher un message d'erreur avant de propager l'exception (en
permettant à un appelant de gérer également l'exception) :

import sys

try:
f = open('myfile.txt')
s = f.readline()
i = int(s.strip())
except OSError as err:
print("OS error: {0}".format(err))
except ValueError:
print("Could not convert data to an integer.")
except:
print("Unexpected error:", sys.exc_info()[0])
raise

L'instruction try ... except accepte également une clause else optionnelle qui,


lorsqu'elle est présente, doit se placer après toutes les clauses except. Elle est utile
pour du code qui doit être exécuté lorsqu'aucune exception n'a été levée par la
clause try. Par exemple :

for arg in sys.argv[1:]:


try:
f = open(arg, 'r')
except OSError:
print('cannot open', arg)
else:
print(arg, 'has', len(f.readlines()), 'lines')
f.close()

Il vaut mieux utiliser la clause else plutôt que d'ajouter du code à la clause try car


cela évite de capturer accidentellement une exception qui n'a pas été levée par le
code initialement protégé par l'instruction try ... except.

Quand une exception intervient, une valeur peut lui être associée, que l'on
appelle l'argument de l'exception. La présence de cet argument et son type
dépendent du type de l'exception.
La clause except peut spécifier un nom de variable après le nom de l'exception.
Cette variable est liée à une instance d'exception avec les arguments stockés
dans instance.args. Pour plus de commodité, l'instance de l'exception définit la
méthode __str__() afin que les arguments puissent être affichés directement sans
avoir à référencer .args. Il est possible de construire une exception, y ajouter ses
attributs, puis la lever plus tard.

>>>

>>> try:
... raise Exception('spam', 'eggs')
... except Exception as inst:
... print(type(inst)) # the exception instance
... print(inst.args) # arguments stored in .args
... print(inst) # __str__ allows args to be printed
directly,
... # but may be overridden in exception
subclasses
... x, y = inst.args # unpack args
... print('x =', x)
... print('y =', y)
...
<class 'Exception'>
('spam', 'eggs')
('spam', 'eggs')
x = spam
y = eggs

Si une exception a un argument, il est affiché dans la dernière partie du message


des exceptions non gérées.

Les gestionnaires d'exceptions n'interceptent pas que les exceptions qui sont levées
immédiatement dans leur clause try, mais aussi celles qui sont levées au sein de
fonctions appelées (parfois indirectement) dans la clause try. Par exemple :

>>>

>>> def this_fails():


... x = 1/0
...
>>> try:
... this_fails()
... except ZeroDivisionError as err:
... print('Handling run-time error:', err)
...
Handling run-time error: division by zero
8.4. Déclencher des exceptions
L'instruction raise permet au programmeur de déclencher une exception spécifique.
Par exemple :

>>>

>>> raise NameError('HiThere')


Traceback (most recent call last):
File "<stdin>", line 1, in <module>
NameError: HiThere

Le seul argument à raise indique l'exception à déclencher. Cela peut être soit une
instance d'exception, soit une classe d'exception (une classe dérivée
de Exception). Si une classe est donnée, elle est implicitement
instanciée via l'appel de son constructeur, sans argument :

raise ValueError # shorthand for 'raise ValueError()'

Si vous avez besoin de savoir si une exception a été levée mais que vous n'avez pas
intention de la gérer, une forme plus simple de l'instruction raise permet de
propager l'exception :

>>>

>>> try:
... raise NameError('HiThere')
... except NameError:
... print('An exception flew by!')
... raise
...
An exception flew by!
Traceback (most recent call last):
File "<stdin>", line 2, in <module>
NameError: HiThere

8.5. Exceptions définies par l'utilisateur


Les programmes peuvent nommer leurs propres exceptions en créant une nouvelle
classe d'exception (voir Classes pour en savoir plus sur les classes de Python). Les
exceptions sont typiquement dérivées de la classe Exception, directement ou non.
Les classes d'exceptions peuvent être définies pour faire tout ce qu'une autre classe
peut faire. Elles sont le plus souvent gardées assez simples, n'offrant que les
attributs permettant aux gestionnaires de ces exceptions d'extraire les informations
relatives à l'erreur qui s'est produite. Lorsque l'on crée un module qui peut
déclencher plusieurs types d'erreurs distincts, une pratique courante est de créer une
classe de base pour l'ensemble des exceptions définies dans ce module et de créer
des sous-classes spécifiques d'exceptions pour les différentes conditions d'erreurs :

class Error(Exception):
"""Base class for exceptions in this module."""
pass

class InputError(Error):
"""Exception raised for errors in the input.

Attributes:
expression -- input expression in which the error
occurred
message -- explanation of the error
"""

def __init__(self, expression, message):


self.expression = expression
self.message = message

class TransitionError(Error):
"""Raised when an operation attempts a state transition
that's not
allowed.

Attributes:
previous -- state at beginning of transition
next -- attempted new state
message -- explanation of why the specific transition is
not allowed
"""

def __init__(self, previous, next, message):


self.previous = previous
self.next = next
self.message = message

La plupart des exceptions sont définies avec des noms qui se terminent par "Error",
comme les exceptions standards.
Beaucoup de modules standards définissent leurs propres exceptions pour signaler
les erreurs possibles dans les fonctions qu'ils définissent. Plus d'informations sur les
classes sont présentées dans le chapitre Classes.

8.6. Définition d'actions de nettoyage


L'instruction try a une autre clause optionnelle qui est destinée à définir des actions
de nettoyage devant être exécutées dans certaines circonstances. Par exemple :

>>>

>>> try:
... raise KeyboardInterrupt
... finally:
... print('Goodbye, world!')
...
Goodbye, world!
KeyboardInterrupt
Traceback (most recent call last):
File "<stdin>", line 2, in <module>

If a finally clause is present, the finally clause will execute as the last task


before the try statement completes. The finally clause runs whether or not
the try statement produces an exception. The following points discuss more
complex cases when an exception occurs:

 If an exception occurs during execution of the try clause, the exception may


be handled by an except clause. If the exception is not handled by
an except clause, the exception is re-raised after the finally clause has been
executed.
 An exception could occur during execution of an except or else clause.
Again, the exception is re-raised after the finally clause has been executed.
 If the try statement reaches a break, continue or return statement,
the finally clause will execute just prior to
the break, continue or return statement's execution.
 If a finally clause includes a return statement, the returned value will be
the one from the finally clause's return statement, not the value from
the try clause's return statement.

For example:

>>>

>>> def bool_return():


... try:
... return True
... finally:
... return False
...
>>> bool_return()
False

A more complicated example:

>>>

>>> def divide(x, y):


... try:
... result = x / y
... except ZeroDivisionError:
... print("division by zero!")
... else:
... print("result is", result)
... finally:
... print("executing finally clause")
...
>>> divide(2, 1)
result is 2.0
executing finally clause
>>> divide(2, 0)
division by zero!
executing finally clause
>>> divide("2", "1")
executing finally clause
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
File "<stdin>", line 3, in divide
TypeError: unsupported operand type(s) for /: 'str' and 'str'

Comme vous pouvez le voir, la clause finally est exécutée dans tous les cas.
L'exception de type TypeError, déclenchée en divisant deux chaînes de caractères,
n'est pas prise en charge par la clause except et est donc propagée après que la
clause finally a été exécutée.

Dans les vraies applications, la clause finally est notamment utile pour libérer des
ressources externes (telles que des fichiers ou des connexions réseau), quelle qu'ait
été l'utilisation de ces ressources.
8.7. Actions de nettoyage prédéfinies
Certains objets définissent des actions de nettoyage standards qui doivent être
exécutées lorsque l'objet n'est plus nécessaire, indépendamment du fait que
l'opération ayant utilisé l'objet ait réussi ou non. Regardez l'exemple suivant, qui
tente d'ouvrir un fichier et d'afficher son contenu à l'écran :

for line in open("myfile.txt"):


print(line, end="")

Le problème avec ce code est qu'il laisse le fichier ouvert pendant une durée
indéterminée après que le code a fini de s'exécuter. Ce n'est pas un problème avec
des scripts simples, mais peut l'être au sein d'applications plus conséquentes.
L'instruction with permet d'utiliser certains objets comme des fichiers d'une façon
qui assure qu'ils seront toujours nettoyés rapidement et correctement.

with open("myfile.txt") as f:
for line in f:
print(line, end="")

Après l'exécution du bloc, le fichier f est toujours fermé, même si un problème est


survenu pendant l'exécution de ces lignes. D'autres objets qui, comme pour les
fichiers, fournissent des actions de nettoyage prédéfinies l'indiquent dans leur
documentation.

9. Classes
Les classes sont un moyen de réunir des données et des fonctionnalités. Créer une
nouvelle classe crée un nouveau type d'objet et ainsi de nouvelles instances de ce
type peuvent être construites. Chaque instance peut avoir ses propres attributs, ce
qui définit son état. Une instance peut aussi avoir des méthodes (définies par la
classe de l'instance) pour modifier son état.

La notion de classes en Python s'inscrit dans le langage avec un minimum de


syntaxe et de sémantique nouvelles. C'est un mélange des mécanismes rencontrés
dans C++ et Modula-3. Les classes fournissent toutes les fonctionnalités standards
de la programmation orientée objet : l'héritage de classes autorise les héritages
multiples, une classe dérivée peut surcharger les méthodes de sa ou ses classes de
base et une méthode peut appeler la méthode d'une classe de base qui possède le
même nom. Les objets peuvent contenir n'importe quel nombre ou type de données.
De la même manière que les modules, les classes participent à la nature dynamique
de Python : elles sont créées pendant l'exécution et peuvent être modifiées après
leur création.

Dans la terminologie C++, les membres des classes (y compris les données)
sont publics (sauf exception, voir Variables privées) et toutes les fonctions membres
sont virtuelles. Comme avec Modula-3, il n'y a aucune façon d'accéder aux membres
d'un objet à partir de ses méthodes : une méthode est déclarée avec un premier
argument explicite représentant l'objet et cet argument est transmis de manière
implicite lors de l'appel. Comme avec Smalltalk, les classes elles-mêmes sont des
objets. Il existe ainsi une sémantique pour les importer et les renommer. Au contraire
de C++ et Modula-3, les types natifs peuvent être utilisés comme classes de base
pour être étendus par l'utilisateur. Enfin, comme en C++, la plupart des opérateurs
natifs avec une syntaxe spéciale (opérateurs arithmétiques, indiçage, etc.) peuvent
être redéfinis pour les instances de classes.

En l'absence d'une terminologie communément admise pour parler des classes,


nous utilisons parfois des termes de Smalltalk et C++. Nous voulions utiliser les
termes de Modula-3 puisque sa sémantique orientée objet est plus proche de celle
de Python que C++, mais il est probable que seul un petit nombre de lecteurs les
connaissent.

9.1. Objets et noms : préambule


Les objets possèdent une existence propre et plusieurs noms peuvent être utilisés
(dans divers contextes) pour faire référence à un même objet. Ce concept est connu
sous le nom d'alias dans d'autres langages. Il n'apparaît pas au premier coup d'œil
en Python et il peut être ignoré tant qu'on travaille avec des types de base
immuables (nombres, chaînes, tuples). Cependant, les alias peuvent produire des
effets surprenants sur la sémantique d'un code Python mettant en jeu des objets
muables comme les listes, les dictionnaires et la plupart des autres types. En
général, leur utilisation est bénéfique au programme car les alias se comportent, d'un
certain point de vue, comme des pointeurs. Par exemple, transmettre un objet n'a
aucun coût car c'est simplement un pointeur qui est transmis par l'implémentation ; et
si une fonction modifie un objet passé en argument, le code à l'origine de l'appel voit
le changement. Ceci élimine le besoin d'avoir deux mécanismes de transmission
d'arguments comme en Pascal.
9.2. Portées et espaces de nommage en Python
Avant de présenter les classes, nous devons aborder la notion de portée en Python.
Les définitions de classes font d'habiles manipulations avec les espaces de
nommage, vous devez donc savoir comment les portées et les espaces de
nommage fonctionnent. Soit dit en passant, la connaissance de ce sujet est aussi
utile aux développeurs Python expérimentés.

Commençons par quelques définitions.

Un espace de nommage est une table de correspondance entre des noms et des


objets. La plupart des espaces de nommage sont actuellement implémentés sous
forme de dictionnaires Python, mais ceci n'est normalement pas visible (sauf pour les
performances) et peut changer dans le futur. Comme exemples d'espaces de
nommage, nous pouvons citer les primitives (fonctions comme abs() et les noms
des exceptions de base) ; les noms globaux dans un module ; et les noms locaux
lors d'un appel de fonction. D'une certaine manière, l'ensemble des attributs d'un
objet forme lui-même un espace de nommage. L'important à retenir concernant les
espaces de nommage est qu'il n'y a absolument aucun lien entre les noms de
différents espaces de nommage ; par exemple, deux modules différents peuvent
définir une fonction maximize sans qu'il n'y ait de confusion. Les utilisateurs des
modules doivent préfixer le nom de la fonction avec celui du module.

À ce propos, nous utilisons le mot attribut pour tout nom suivant un point. Par


exemple, dans l'expression z.real, real est un attribut de l'objet z.
Rigoureusement parlant, les références à des noms dans des modules sont des
références d'attributs : dans l'expression nommodule.nomfonction, nommodule est
un objet module et nomfonction est un attribut de cet objet. Dans ces conditions, il
existe une correspondance directe entre les attributs du module et les noms globaux
définis dans le module : ils partagent le même espace de nommage 1 !

Les attributs peuvent être en lecture seule ou modifiables. S'ils sont modifiables,
l'affectation à un attribut est possible. Les attributs de modules sont modifiables :
vous pouvez écrire nommodule.la_reponse = 42. Les attributs modifiables
peuvent aussi être effacés avec l'instruction del. Par
exemple, del nommodule.la_reponse supprime l'attribut la_reponse de l'objet
nommé nommodule.

Les espaces de nommage sont créés à différents moments et ont différentes durées
de vie. L'espace de nommage contenant les primitives est créé au démarrage de
l'interpréteur Python et n'est jamais effacé. L'espace de nommage globaux pour un
module est créé lorsque la définition du module est lue. Habituellement, les espaces
de nommage des modules durent aussi jusqu'à l'arrêt de l'interpréteur. Les
instructions exécutées par la première invocation de l'interpréteur, qu'elles soient
lues depuis un fichier de script ou de manière interactive, sont considérées comme
faisant partie d'un module appelé __main__, de façon qu'elles possèdent leur propre
espace de nommage (les primitives vivent elles-mêmes dans un module,
appelé builtins).

L'espace des noms locaux d'une fonction est créé lors de son appel, puis effacé
lorsqu'elle renvoie un résultat ou lève une exception non prise en charge (en fait,
« oublié » serait une meilleure façon de décrire ce qui se passe réellement). Bien
sûr, des invocations récursives ont chacune leur propre espace de nommage.

La portée est la zone textuelle d'un programme Python où un espace de nommage


est directement accessible. « Directement accessible » signifie ici qu'une référence
non qualifiée à un nom est cherchée dans l'espace de nommage.

Bien que les portées soient déterminées de manière statique, elles sont utilisées de
manière dynamique. À n'importe quel moment de l'exécution, il y a au minimum trois
portées imbriquées dont les espaces de nommage sont directement accessibles :

 la portée la plus au centre, celle qui est consultée en premier, contient les
noms locaux ;
 les portées des fonctions englobantes, qui sont consultées en commençant
avec la portée englobante la plus proche, contiennent des noms non-locaux mais
aussi non-globaux ;
 l'avant-dernière portée contient les noms globaux du module courant ;
 la portée englobante, consultée en dernier, est l'espace de nommage
contenant les primitives.

Si un nom est déclaré comme global, alors toutes les références et affectations vont
directement dans la portée intermédiaire contenant les noms globaux du module.
Pour pointer une variable qui se trouve en dehors de la portée la plus locale, vous
pouvez utiliser l'instruction nonlocal. Si une telle variable n'est pas
déclarée nonlocal, elle est en lecture seule (toute tentative de la modifier crée
simplement une nouvelle variable dans la portée la plus locale, en laissant inchangée
la variable du même nom dans sa portée d'origine).

Habituellement, la portée locale référence les noms locaux de la fonction courante.


En dehors des fonctions, la portée locale référence le même espace de nommage
que la portée globale : l'espace de nommage du module. Les définitions de classes
créent un nouvel espace de nommage dans la portée locale.
Il est important de réaliser que les portées sont déterminées de manière textuelle : la
portée globale d'une fonction définie dans un module est l'espace de nommage de
ce module, quelle que soit la provenance de l'appel à la fonction. En revanche, la
recherche réelle des noms est faite dynamiquement au moment de l'exécution.
Cependant la définition du langage est en train d'évoluer vers une résolution statique
des noms au moment de la « compilation », donc ne vous basez pas sur une
résolution dynamique (en réalité, les variables locales sont déjà déterminées de
manière statique) !

A special quirk of Python is that -- if no global or nonlocal statement is in effect --


assignments to names always go into the innermost scope. Assignments do not copy
data --- they just bind names to objects. The same is true for deletions: the
statement del x removes the binding of x from the namespace referenced by the
local scope. In fact, all operations that introduce new names use the local scope: in
particular, import statements and function definitions bind the module or function
name in the local scope.

L'instruction global peut être utilisée pour indiquer que certaines variables existent


dans la portée globale et doivent être reliées en local ; l'instruction nonlocal indique
que certaines variables existent dans une portée supérieure et doivent être reliées en
local.

9.2.1. Exemple de portées et d'espaces de nommage


Ceci est un exemple montrant comment utiliser les différentes portées et espaces de
nommage, et comment global et nonlocal modifient l'affectation de variable :

def scope_test():
def do_local():
spam = "local spam"

def do_nonlocal():
nonlocal spam
spam = "nonlocal spam"

def do_global():
global spam
spam = "global spam"

spam = "test spam"


do_local()
print("After local assignment:", spam)
do_nonlocal()
print("After nonlocal assignment:", spam)
do_global()
print("After global assignment:", spam)

scope_test()
print("In global scope:", spam)

Ce code donne le résultat suivant :

After local assignment: test spam


After nonlocal assignment: nonlocal spam
After global assignment: nonlocal spam
In global scope: global spam

Vous pouvez constater que l'affectation locale (qui est effectuée par défaut) n'a pas
modifié la liaison de spam dans scope_test. L'affectation nonlocal a changé la
liaison de spam dans scope_test et l'affectation global a changé la liaison au
niveau du module.

Vous pouvez également voir qu'aucune liaison pour spam n'a été faite avant
l'affectation global.

9.3. Une première approche des classes


Le concept de classe introduit un peu de syntaxe nouvelle, trois nouveaux types
d'objets ainsi que quelques nouveaux éléments de sémantique.

9.3.1. Syntaxe de définition des classes


La forme la plus simple de définition d'une classe est la suivante :

class ClassName:
<statement-1>
.
.
.
<statement-N>

Les définitions de classes, comme les définitions de fonctions (définitions def),


doivent être exécutées avant d'avoir un effet. Vous pouvez tout à fait placer une
définition de classe dans une branche d'une instruction conditionnelle if ou encore à
l'intérieur d'une fonction.
Dans la pratique, les déclarations dans une définition de classe sont généralement
des définitions de fonctions mais d'autres déclarations sont permises et parfois utiles
(nous revenons sur ce point plus tard). Les définitions de fonction à l'intérieur d'une
classe ont normalement une forme particulière de liste d'arguments, dictée par les
conventions d'appel aux méthodes (à nouveau, tout ceci est expliqué plus loin).

Quand une classe est définie, un nouvel espace de nommage est créé et utilisé
comme portée locale --- Ainsi, toutes les affectations de variables locales entrent
dans ce nouvel espace de nommage. En particulier, les définitions de fonctions y
lient le nom de la nouvelle fonction.

À la fin de la définition d'une classe, un objet classe est créé. C'est, pour simplifier,
une encapsulation du contenu de l'espace de nommage créé par la définition de
classe. Nous revoyons les objets classes dans la prochaine section. La portée locale
initiale (celle qui prévaut avant le début de la définition de la classe) est ré-instanciée
et l'objet de classe est lié ici au nom de classe donné dans l'en-tête de définition de
classe (ClassName dans l'exemple).

9.3.2. Objets classes
Les objets classes prennent en charge deux types d'opérations : des références à
des attributs et l'instanciation.

Les références d'attributs utilisent la syntaxe standard utilisée pour toutes les


références d'attributs en Python : obj.nom. Les noms d'attribut valides sont tous les
noms qui se trouvaient dans l'espace de nommage de la classe quand l'objet classe
a été créé. Donc, si la définition de classe est de cette forme :

class MyClass:
"""A simple example class"""
i = 12345

def f(self):
return 'hello world'

alors MyClass.i et MyClass.f sont des références valides à des attributs,


renvoyant respectivement un entier et un objet fonction. Les attributs de classes
peuvent également être affectés, de sorte que vous pouvez modifier la valeur
de MyClass.i par affectation. __doc__ est aussi un attribut valide, renvoyant
la docstring appartenant à la classe : "A simple example class".
L'instanciation de classes utilise la notation des fonctions. Considérez simplement
que l'objet classe est une fonction sans paramètre qui renvoie une nouvelle instance
de la classe. Par exemple (en considérant la classe définie ci-dessus) :

x = MyClass()

crée une nouvelle instance de la classe et affecte cet objet à la variable locale x.

L'opération d'instanciation (en "appelant" un objet classe) crée un objet vide. De


nombreuses classes aiment créer des instances personnalisées correspondant à un
état initial spécifique. À cet effet, une classe peut définir une méthode spéciale
nommée __init__(), comme ceci :

def __init__(self):
self.data = []

Quand une classe définit une méthode __init__(), l'instanciation de la classe


appelle automatiquement __init__() pour la nouvelle instance de la classe. Donc,
dans cet exemple, l'initialisation d'une nouvelle instance peut être obtenue par :

x = MyClass()

Bien sûr, la méthode __init__() peut avoir des arguments pour une plus grande
flexibilité. Dans ce cas, les arguments donnés à l'opérateur d'instanciation de classe
sont transmis à __init__(). Par exemple

>>>

>>> class Complex:


... def __init__(self, realpart, imagpart):
... self.r = realpart
... self.i = imagpart
...
>>> x = Complex(3.0, -4.5)
>>> x.r, x.i
(3.0, -4.5)

9.3.3. Objets instances
Now what can we do with instance objects? The only operations understood by
instance objects are attribute references. There are two kinds of valid attribute
names: data attributes and methods.
Les attributs 'données' correspondent à des "variables d'instance" en Smalltalk et
aux "membres de données" en C++. Les attributs 'données' n'ont pas à être
déclarés. Comme les variables locales, ils existent dès lors qu'ils sont assignés une
première fois. Par exemple, si x est l'instance de MyClass créée ci-dessus, le code
suivant affiche la valeur 16, sans laisser de trace :

x.counter = 1
while x.counter < 10:
x.counter = x.counter * 2
print(x.counter)
del x.counter

L'autre type de référence à un attribut d'instance est une méthode. Une méthode est
une fonction qui "appartient à" un objet (en Python, le terme de méthode n'est pas
unique aux instances de classes : d'autres types d'objets peuvent aussi avoir des
méthodes. Par exemple, les objets listes ont des méthodes
appelées append, insert, remove, sort et ainsi de suite. Toutefois, dans la
discussion qui suit, sauf indication contraire, nous utilisons le terme de méthode
exclusivement en référence à des méthodes d'objets instances de classe).

Les noms de méthodes valides d'un objet instance dépendent de sa classe. Par
définition, tous les attributs d'une classe qui sont des objets fonctions définissent les
méthodes correspondantes de ses instances. Donc, dans notre exemple, x.f est
une référence valide à une méthode car MyClass.f est une fonction, mais
pas x.i car MyClass.i n'en est pas une. Attention cependant, x.f n'est pas la
même chose que MyClass.f --- Il s'agit d'un objet méthode, pas d'un objet fonction.

9.3.4. Objets méthode
Le plus souvent, une méthode est appelée juste après avoir été liée :

x.f()

Dans l'exemple de la classe MyClass, cela renvoie la chaîne de


caractères hello world. Toutefois, il n'est pas nécessaire d'appeler la méthode
directement : x.f est un objet méthode, il peut être gardé de côté et être appelé plus
tard. Par exemple :

xf = x.f
while True:
print(xf())
affiche hello world jusqu'à la fin des temps.

Que se passe-t-il exactement quand une méthode est appelée ? Vous avez dû
remarquer que x.f() a été appelée dans le code ci-dessus sans argument, alors
que la définition de la méthode f() spécifie bien qu'elle prend un argument. Qu'est-il
arrivé à l'argument ? Python doit sûrement lever une exception lorsqu'une fonction
qui requiert un argument est appelée sans -- même si l'argument n'est pas utilisé…

En fait, vous avez peut-être deviné la réponse : la particularité des méthodes est que
l'objet est passé comme premier argument de la fonction. Dans notre exemple,
l'appel x.f() est exactement équivalent à MyClass.f(x). En général, appeler une
méthode avec une liste de n arguments est équivalent à appeler la fonction
correspondante avec une liste d'arguments créée en ajoutant l'instance de l'objet de
la méthode avant le premier argument.

Si vous ne comprenez toujours pas comment les méthodes fonctionnent, un coup


d'œil à l'implémentation vous aidera peut-être. Lorsque un attribut d'une instance est
référencé et que ce n'est pas un attribut 'données', sa classe est recherchée. Si le
nom correspond à un attribut valide et que c'est un objet fonction, un objet méthode
est créé en générant un objet abstrait qui regroupe (des pointeurs vers) l'objet
instance et l'objet fonction qui vient d'être trouvé : c'est l'objet méthode. Quand l'objet
méthode est appelé avec une liste d'arguments, une nouvelle liste d'arguments est
construite à partir de l'objet instance et de la liste des arguments. L'objet fonction est
alors appelé avec cette nouvelle liste d'arguments.

9.3.5. Classes et variables d'instance


En général, les variables d'instance stockent des informations relatives à chaque
instance alors que les variables de classe servent à stocker les attributs et méthodes
communes à toutes les instances de la classe :

class Dog:

kind = 'canine' # class variable shared by all


instances

def __init__(self, name):


self.name = name # instance variable unique to each
instance

>>> d = Dog('Fido')
>>> e = Dog('Buddy')
>>> d.kind # shared by all dogs
'canine'
>>> e.kind # shared by all dogs
'canine'
>>> d.name # unique to d
'Fido'
>>> e.name # unique to e
'Buddy'

Comme nous l'avons vu dans Objets et noms : préambule, les données


partagées muable (telles que les listes, dictionnaires, etc.) peuvent avoir des effets
surprenants. Par exemple, la liste tricks dans le code suivant ne devrait pas être
utilisée en tant que variable de classe car, dans ce cas, une seule liste est partagée
par toutes les instances de Dog :

class Dog:

tricks = [] # mistaken use of a class variable

def __init__(self, name):


self.name = name

def add_trick(self, trick):


self.tricks.append(trick)

>>> d = Dog('Fido')
>>> e = Dog('Buddy')
>>> d.add_trick('roll over')
>>> e.add_trick('play dead')
>>> d.tricks # unexpectedly shared by all dogs
['roll over', 'play dead']

Une conception correcte de la classe est d'utiliser une variable d'instance à la place :

class Dog:

def __init__(self, name):


self.name = name
self.tricks = [] # creates a new empty list for each
dog

def add_trick(self, trick):


self.tricks.append(trick)

>>> d = Dog('Fido')
>>> e = Dog('Buddy')
>>> d.add_trick('roll over')
>>> e.add_trick('play dead')
>>> d.tricks
['roll over']
>>> e.tricks
['play dead']

9.4. Remarques diverses
Les attributs 'données' surchargent les méthodes avec le même nom ; pour éviter
des conflits de nommage, qui peuvent causer des bugs difficiles à trouver dans de
grands programmes, il est sage d'adopter certaines conventions qui minimisent les
risques de conflits. Parmi les conventions possibles, on peut citer la mise en
majuscule des noms de méthodes, le préfixe des noms d'attributs 'données' par une
chaîne courte et unique (parfois juste la caractère souligné) ou l'utilisation de verbes
pour les méthodes et de noms pour les attributs 'données'.

Les attributs 'données' peuvent être référencés par des méthodes comme par des
utilisateurs ordinaires ("clients") d'un objet. En d'autres termes, les classes ne sont
pas utilisables pour implémenter des types de données purement abstraits. En fait, il
n'est pas possible en Python d'imposer de masquer des données — tout est basé sur
des conventions (d'un autre côté, l'implémentation de Python, écrite en C, peut
complètement masquer les détails d'implémentation et contrôler l'accès à un objet si
nécessaire ; ceci peut être utilisé par des extensions de Python écrites en C).

Les clients doivent utiliser les attributs 'données' avec précaution --- ils pourraient
mettre le désordre dans les invariants gérés par les méthodes avec leurs propres
valeurs d'attributs. Remarquez que les clients peuvent ajouter leurs propres attributs
'données' à une instance d'objet sans altérer la validité des méthodes, pour autant
que les noms n'entrent pas en conflit --- là aussi, adopter une convention de
nommage peut éviter bien des problèmes.

Il n'y a pas de notation abrégée pour référencer des attributs 'données' (ou les autres
méthodes !) depuis les méthodes. Nous pensons que ceci améliore en fait la lisibilité
des méthodes : il n'y a aucune chance de confondre variables locales et variables
d'instances quand on regarde le code d'une méthode.

Souvent, le premier argument d'une méthode est nommé self. Ce n'est qu'une


convention : le nom self n'a aucune signification particulière en Python. Notez
cependant que si vous ne suivez pas cette convention, votre code risque d'être
moins lisible pour d'autres programmeurs Python et il est aussi possible qu'un
programme qui fasse l'introspection de classes repose sur une telle convention.
Tout objet fonction qui est un attribut de classe définit une méthode pour des
instances de cette classe. Il n'est pas nécessaire que le texte de définition de la
fonction soit dans la définition de la classe : il est possible d'affecter un objet fonction
à une variable locale de la classe. Par exemple :

# Function defined outside the class


def f1(self, x, y):
return min(x, x+y)

class C:
f = f1

def g(self):
return 'hello world'

h = g

Maintenant, f, g et h sont toutes des attributs de la classe C et font référence à des


fonctions objets. Par conséquent, ce sont toutes des méthodes des instances
de C --- h est exactement identique à g. Remarquez qu'en pratique, ceci ne sert qu'à
embrouiller le lecteur d'un programme.

Les méthodes peuvent appeler d'autres méthodes en utilisant des méthodes qui sont
des attributs de l'argument self :

class Bag:
def __init__(self):
self.data = []

def add(self, x):


self.data.append(x)

def addtwice(self, x):


self.add(x)
self.add(x)

Les méthodes peuvent faire référence à des noms globaux de la même manière que
les fonctions. La portée globale associée à une méthode est le module contenant la
définition de la classe (la classe elle-même n'est jamais utilisée en tant que portée
globale). Alors qu'il est rare d'avoir une bonne raison d'utiliser des données globales
dans une méthode, il y a de nombreuses utilisations légitimes de la portée globale :
par exemple, les fonctions et modules importés dans une portée globale peuvent être
utilisés par des méthodes, de même que les fonctions et classes définies dans cette
même portée. Habituellement, la classe contenant la méthode est elle-même définie
dans cette portée globale et, dans la section suivante, nous verrons de bonnes
raisons pour qu'une méthode référence sa propre classe.

Toute valeur est un objet et a donc une classe (appelée aussi son type). Elle est
stockée dans objet.__class__.

9.5. Héritage
Bien sûr, ce terme de "classe" ne serait pas utilisé s'il n'y avait pas d'héritage. La
syntaxe pour définir une sous-classe est de cette forme :

class DerivedClassName(BaseClassName):
<statement-1>
.
.
.
<statement-N>

Le nom BaseClassName doit être défini dans une portée contenant la définition de la


classe dérivée. À la place du nom d'une classe de base, une expression est aussi
autorisée. Ceci peut être utile, par exemple, lorsque la classe est définie dans un
autre module :

class DerivedClassName(modname.BaseClassName):

L'exécution d'une définition de classe dérivée se déroule comme pour une classe de
base. Quand l'objet de la classe est construit, la classe de base est mémorisée. Elle
est utilisée pour la résolution des références d'attributs : si un attribut n'est pas trouvé
dans la classe, la recherche se poursuit en regardant dans la classe de base. Cette
règle est appliquée récursivement si la classe de base est elle-même dérivée d'une
autre classe.

Il n'y a rien de particulier dans l'instanciation des classes


dérivées : DerivedClassName() crée une nouvelle instance de la classe. Les
références aux méthodes sont résolues comme suit : l'attribut correspondant de la
classe est recherché, en remontant la hiérarchie des classes de base si nécessaire,
et la référence de méthode est valide si cela conduit à une fonction.

Les classes dérivées peuvent surcharger des méthodes de leurs classes de base.
Comme les méthodes n'ont aucun privilège particulier quand elles appellent d'autres
méthodes d'un même objet, une méthode d'une classe de base qui appelle une autre
méthode définie dans la même classe peut en fait appeler une méthode d'une classe
dérivée qui la surcharge (pour les programmeurs C++ : toutes les méthodes de
Python sont en effet "virtuelles").

Une méthode dans une classe dérivée peut aussi, en fait, vouloir étendre plutôt que
simplement remplacer la méthode du même nom de sa classe de base. L'appel
direct à la méthode de la classe de base s'écrit
simplement BaseClassName.nomMethode(self, arguments). C'est parfois utile
également aux clients (notez bien que ceci ne fonctionne que si la classe de base est
accessible en tant que BaseClassName dans la portée globale).

Python définit deux fonctions primitives pour gérer l'héritage :

 utilisez isinstance() pour tester le type d'une


instance : isinstance(obj, int) renvoie True seulement si obj.__class__ est
égal à int ou à une autre classe dérivée de int ;
 utilisez issubclass() pour tester l'héritage d'une
classe : issubclass(bool, int) renvoie True car la classe bool est une sous-
classe de int.
Cependant, issubclass(float, int) renvoie False car float n'est pas une
sous-classe de int.

9.5.1. Héritage multiple
Python gère également une forme d'héritage multiple. Une définition de classe ayant
plusieurs classes de base est de cette forme :

class DerivedClassName(Base1, Base2, Base3):


<statement-1>
.
.
.
<statement-N>

Dans la plupart des cas, vous pouvez vous représenter la recherche d'attributs dans
les classes parentes comme étant : le plus profond d'abord, de gauche à droite, sans
chercher deux fois dans la même classe si elle apparaît plusieurs fois dans la
hiérarchie. Ainsi, si un attribut n'est pas trouvé dans DerivedClassName, il est
recherché dans Base1, puis (récursivement) dans les classes de base de Base1 ; s'il
n'y est pas trouvé, il est recherché dans Base2 et ses classes de base, et ainsi de
suite.
Dans les faits, c'est un peu plus complexe que ça ; l'ordre de la recherche (method
resolution order, ou MRO en anglais) change dynamiquement pour gérer des appels
coopératifs à super(). Cette approche est connue sous le nom de la "appel de la
méthode la plus proche" (call-next-method en anglais) dans d'autres langages avec
héritage multiple. Elle est plus puissante que le simple appel à super que l'on trouve
dans les langages à héritage simple.

L'ordre défini dynamiquement est nécessaire car tous les cas d'héritage multiple
comportent une ou plusieurs relations en losange (où au moins une classe peut être
accédée à partir de plusieurs chemins en partant de la classe la plus basse). Par
exemple, puisque toutes les classes héritent de object, tout héritage multiple ouvre
plusieurs chemins pour atteindre object. Pour qu'une classe de base ne soit pas
appelée plusieurs fois, l'algorithme dynamique linéarise l'ordre de recherche d'une
façon qui préserve l'ordre d'héritage, de la gauche vers la droite, spécifié dans
chaque classe, qui appelle chaque classe parente une seule fois, qui est monotone
(ce qui signifie qu'une classe peut être sous-classée sans affecter l'ordre d'héritage
de ses parents). Prises ensemble, ces propriétés permettent de concevoir des
classes de façon fiable et extensible dans un contexte d'héritage multiple. Pour plus
de détails, consultez http://www.python.org/download/releases/2.3/mro/.

9.6. Variables privées
Les membres "privés", qui ne peuvent être accédés que depuis l'intérieur d'un objet,
n'existent pas en Python. Toutefois, il existe une convention respectée par la majorité
du code Python : un nom préfixé par un tiret bas (comme _spam) doit être considéré
comme une partie non publique de l'API (qu'il s'agisse d'une fonction, d'une méthode
ou d'un attribut 'données'). Il doit être vu comme un détail d'implémentation pouvant
faire l'objet de modifications futures sans préavis.

Dès lors qu'il y a un cas d'utilisation valable pour avoir des attributs privés aux
classes (notamment pour éviter des conflits avec des noms définis dans des sous-
classes), il existe un support (certes limité) pour un tel mécanisme, appelé name
mangling. Tout identifiant de la forme __spam (avec au moins deux tirets bas en tête
et au plus un à la fin) est remplacé textuellement par _classname__spam,
où classname est le nom de la classe sans le ou les premiers tirets-bas. Ce
"découpage" est effectué sans tenir compte de la position syntaxique de l'identifiant,
tant qu'il est présent dans la définition d'une classe.

Ce changement de nom est utile pour permettre à des sous-classes de surcharger


des méthodes sans casser les appels de méthodes à l'intérieur d'une classe. Par
exemple :
class Mapping:
def __init__(self, iterable):
self.items_list = []
self.__update(iterable)

def update(self, iterable):


for item in iterable:
self.items_list.append(item)

__update = update # private copy of original update()


method

class MappingSubclass(Mapping):

def update(self, keys, values):


# provides new signature for update()
# but does not break __init__()
for item in zip(keys, values):
self.items_list.append(item)

L'exemple si dessus fonctionnerait même si MappingSubclass introduisait un


identifieur __update puisqu'il a été remplacé avec _Mapping__update dans la
classe Mapping et _MappingSubclass__update dans la
classe MappingSubclass respectivement.

Notez que ces règles sont conçues avant tout pour éviter les accidents ; il reste
possible d'accéder ou de modifier une variable considérée comme privée. Ceci peut
même être utile dans certaines circonstances, comme au sein du débogueur.

Remarquez que le code que vous passez à exec(), eval() ne considère pas le


nom de la classe appelante comme étant la classe courante ; le même effet
s'applique à la directive global dont l'effet est, de la même façon, restreint au code
compilé dans le même ensemble de byte-code. Les mêmes restrictions s'appliquent
à getattr(), setattr() et delattr(), ainsi qu'aux références directes
à __dict__.

9.7. Trucs et astuces
Il est parfois utile d'avoir un type de donnée similaire au "record" du Pascal ou
au struct du C, qui regroupent ensemble quelques attributs 'données' nommés. La
définition d'une classe vide remplit parfaitement ce besoin :

class Employee:
pass
john = Employee() # Create an empty employee record

# Fill the fields of the record


john.name = 'John Doe'
john.dept = 'computer lab'
john.salary = 1000

À du code Python qui s'attend à recevoir un type de donnée abstrait spécifique, on


peut souvent fournir une classe qui simule les méthodes de ce type. Par exemple, à
une fonction qui formate des données extraites d'un objet fichier, vous pouvez lui
passer comme argument une instance d'une classe qui implémente les
méthodes read() et readline() en puisant ses données à partir d'un tampon de
chaînes de caractères.

Les objets méthodes d'instances ont aussi des attributs : m.__self__ est l'instance


d'objet avec la méthode m() et m.__func__ est l'objet fonction correspondant à la
méthode.

9.8. Itérateurs
Vous avez maintenant certainement remarqué que l'on peut itérer sur la plupart des
objets conteneurs en utilisant une instruction for :

for element in [1, 2, 3]:


print(element)
for element in (1, 2, 3):
print(element)
for key in {'one':1, 'two':2}:
print(key)
for char in "123":
print(char)
for line in open("myfile.txt"):
print(line, end='')

Ce style est simple, concis et pratique. L'utilisation d'itérateurs imprègne et unifie


Python. En arrière plan, l'instruction for appelle la fonction iter() sur l'objet
conteneur. Cette fonction renvoie un objet itérateur qui définit la
méthode __next__(), laquelle accède aux éléments du conteneur un par un.
Lorsqu'il n'y a plus d'élément, __next__() lève une exception StopIteration qui
indique à la boucle de l'instruction for de se terminer. Vous pouvez appeler la
méthode __next__() en utilisant la fonction native next(). Cet exemple montre
comment tout cela fonctionne :
>>>

>>> s = 'abc'
>>> it = iter(s)
>>> it
<iterator object at 0x00A1DB50>
>>> next(it)
'a'
>>> next(it)
'b'
>>> next(it)
'c'
>>> next(it)
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
next(it)
StopIteration

Une fois compris les mécanismes de gestion des itérateurs, il est simple d'ajouter ce
comportement à vos classes. Définissez une méthode __iter__() qui renvoie un
objet disposant d'une méthode __next__(). Si la classe définit elle-même la
méthode __next__(), alors __iter__() peut simplement renvoyer self :

class Reverse:
"""Iterator for looping over a sequence backwards."""
def __init__(self, data):
self.data = data
self.index = len(data)

def __iter__(self):
return self

def __next__(self):
if self.index == 0:
raise StopIteration
self.index = self.index - 1
return self.data[self.index]
>>>

>>> rev = Reverse('spam')


>>> iter(rev)
<__main__.Reverse object at 0x00A1DB50>
>>> for char in rev:
... print(char)
...
m
a
p
s

9.9. Générateurs
Les générateurs sont des outils simples et puissants pour créer des itérateurs. Ils
sont écrits comme des fonctions classiques mais utilisent
l'instruction yield lorsqu'ils veulent renvoyer des données. À chaque fois qu'il est
appelé par next(), le générateur reprend son exécution là où il s'était arrêté (en
conservant tout son contexte d'exécution). Un exemple montre très bien combien les
générateurs sont simples à créer :

def reverse(data):
for index in range(len(data)-1, -1, -1):
yield data[index]
>>>

>>> for char in reverse('golf'):


... print(char)
...
f
l
o
g

Tout ce qui peut être fait avec des générateurs peut également être fait avec des
itérateurs basés sur des classes, comme décrit dans le paragraphe précédent. Ce
qui rend les générateurs si compacts, c'est que les
méthodes __iter__() et __next__() sont créées automatiquement.

Une autre fonctionnalité clé est que les variables locales ainsi que le contexte
d'exécution sont sauvegardés automatiquement entre les appels. Cela simplifie
d'autant plus l'écriture de ces fonctions et rend leur code beaucoup plus lisible
qu'avec une approche utilisant des variables d'instance telles
que self.index et self.data.

En plus de la création automatique de méthodes et de la sauvegarde du contexte


d'exécution, les générateurs lèvent automatiquement une
exception StopIteration lorsqu'ils terminent leur exécution. La combinaison de
ces fonctionnalités rend très simple la création d'itérateurs, sans plus d'effort que
l'écriture d'une fonction classique.
9.10. Expressions et générateurs
Des générateurs simples peuvent être codés très rapidement avec des expressions
utilisant la même syntaxe que les compréhensions de listes, mais en utilisant des
parenthèses à la place des crochets. Ces expressions sont conçues pour des
situations où le générateur est utilisé tout de suite dans une fonction. Ces
expressions sont plus compactes mais moins souples que des définitions complètes
de générateurs et ont tendance à être plus économes en mémoire que leur
équivalent en compréhension de listes.

Exemples :

>>>

>>> sum(i*i for i in range(10)) # sum of squares


285

>>> xvec = [10, 20, 30]


>>> yvec = [7, 5, 3]
>>> sum(x*y for x,y in zip(xvec, yvec)) # dot product
260

>>> from math import pi, sin


>>> sine_table = {x: sin(x*pi/180) for x in range(0, 91)}

>>> unique_words = set(word for line in page for word in


line.split())

>>> valedictorian = max((student.gpa, student.name) for student


in graduates)

>>> data = 'golf'


>>> list(data[i] for i in range(len(data)-1, -1, -1))
['f', 'l', 'o', 'g']

Notes de bas de page

Il existe une exception : les modules disposent d'un attribut secret en lecture seule
appelé __dict__ qui renvoie le dictionnaire utilisé pour implémenter l'espace de
nommage du module ; le nom __dict__ est un attribut mais pas un nom global.
Évidemment, si vous l'utilisez, vous brisez l'abstraction de l'implémentation des
espaces de nommage. Il est donc réservé à des choses comme les débogueurs
post-mortem.

10. Survol de la bibliothèque standard


10.1. Interface avec le système d'exploitation
Le module os propose des dizaines de fonctions pour interagir avec le système
d'exploitation :

>>>

>>> import os
>>> os.getcwd() # Return the current working directory
'C:\\Python37'
>>> os.chdir('/server/accesslogs') # Change current working
directory
>>> os.system('mkdir today') # Run the command mkdir in the
system shell
0

Veillez bien à utiliser import os plutôt que from os import *,


sinon os.open() cache la primitive open() qui fonctionne différemment.

Les primitives dir() et help() sont des aides utiles lorsque vous travaillez en mode


interactif avez des gros modules comme os :

>>>

>>> import os
>>> dir(os)
<returns a list of all module functions>
>>> help(os)
<returns an extensive manual page created from the module's
docstrings>

Pour la gestion des fichiers et dossiers, le module shutil expose une interface plus


abstraite et plus facile à utiliser :

>>>

>>> import shutil


>>> shutil.copyfile('data.db', 'archive.db')
'archive.db'
>>> shutil.move('/build/executables', 'installdir')
'installdir'

10.2. Jokers sur les noms de fichiers


Le module glob fournit une fonction pour construire des listes de fichiers à partir de
motifs :

>>>

>>> import glob


>>> glob.glob('*.py')
['primes.py', 'random.py', 'quote.py']

10.3. Paramètres passés en ligne de commande


Typiquement, les outils en ligne de commande ont besoin de lire les paramètres qui
leur sont donnés. Ces paramètres sont stockés dans la variable argv du
module sys sous la forme d'une liste. Par exemple, l'affichage suivant vient de
l'exécution de python demo.py one two three depuis la ligne de commande :

>>>

>>> import sys


>>> print(sys.argv)
['demo.py', 'one', 'two', 'three']

The argparse module provides a more sophisticated mechanism to process


command line arguments. The following script extracts one or more filenames and an
optional number of lines to be displayed:

import argparse

parser = argparse.ArgumentParser(prog = 'top',


description = 'Show top lines from each file')
parser.add_argument('filenames', nargs='+')
parser.add_argument('-l', '--lines', type=int, default=10)
args = parser.parse_args()
print(args)
When run at the command line with python top.py --
lines=5 alpha.txt beta.txt, the script
sets args.lines to 5 and args.filenames to ['alpha.txt', 'beta.txt'].

10.4. Redirection de la sortie d'erreur et fin


d'exécution
Le module sys a aussi des attributs pour stdin, stdout et stderr. Ce dernier est utile
pour émettre des messages d'avertissement ou d'erreur qui restent visibles même
si stdout est redirigé :

>>>

>>> sys.stderr.write('Warning, log file not found starting a new


one\n')
Warning, log file not found starting a new one

Le moyen le plus direct de terminer un script est d'utiliser sys.exit().

10.5. Recherche de motifs dans les chaînes


Le module re fournit des outils basés sur les expressions rationnelles permettant des
opérations complexes sur les chaînes. C'est une solution optimisée, utilisant une
syntaxe concise, pour rechercher des motifs complexes ou effectuer des
remplacements complexes dans les chaînes :

>>>

>>> import re
>>> re.findall(r'\bf[a-z]*', 'which foot or hand fell fastest')
['foot', 'fell', 'fastest']
>>> re.sub(r'(\b[a-z]+) \1', r'\1', 'cat in the the hat')
'cat in the hat'

Lorsque les opérations sont simples, il est préférable d'utiliser les méthodes des
chaînes. Elles sont plus lisibles et plus faciles à déboguer :

>>>

>>> 'tea for too'.replace('too', 'two')


'tea for two'

10.6. Mathématiques
Le module math donne accès aux fonctions sur les nombres à virgule flottante
(float en anglais) de la bibliothèque C :

>>>

>>> import math


>>> math.cos(math.pi / 4)
0.70710678118654757
>>> math.log(1024, 2)
10.0

Le module random offre des outils pour faire des tirages aléatoires :

>>>

>>> import random


>>> random.choice(['apple', 'pear', 'banana'])
'apple'
>>> random.sample(range(100), 10) # sampling without
replacement
[30, 83, 16, 4, 8, 81, 41, 50, 18, 33]
>>> random.random() # random float
0.17970987693706186
>>> random.randrange(6) # random integer chosen from range(6)
4

Le module statistics permet de calculer des valeurs statistiques basiques


(moyenne, médiane, variance…) :

>>>

>>> import statistics


>>> data = [2.75, 1.75, 1.25, 0.25, 0.5, 1.25, 3.5]
>>> statistics.mean(data)
1.6071428571428572
>>> statistics.median(data)
1.25
>>> statistics.variance(data)
1.3720238095238095
Le projet SciPy <https://scipy.org> contient beaucoup d'autres modules dédiés aux
calculs numériques.

10.7. Accès à internet
Il existe beaucoup de modules permettant d'accéder à internet et gérer les protocoles
réseaux. Les deux plus simples sont urllib.request qui permet de récupérer des
données à partir d'une URL et smtplib pour envoyer des courriers électroniques :

>>>

>>> from urllib.request import urlopen


>>> with urlopen('http://tycho.usno.navy.mil/cgi-bin/timer.pl')
as response:
... for line in response:
... line = line.decode('utf-8') # Decoding the binary
data to text.
... if 'EST' in line or 'EDT' in line: # look for
Eastern Time
... print(line)

<BR>Nov. 25, 09:43:32 PM EST

>>> import smtplib


>>> server = smtplib.SMTP('localhost')
>>> server.sendmail('soothsayer@example.org',
'jcaesar@example.org',
... """To: jcaesar@example.org
... From: soothsayer@example.org
...
... Beware the Ides of March.
... """)
>>> server.quit()

(Notez que le deuxième exemple a besoin d'un serveur mail tournant localement.)

10.8. Dates et heures
Le module datetime propose des classes pour manipuler les dates et les heures de
manière simple ou plus complexe. Bien que faire des calculs de dates et d'heures
soit possible, la priorité de l'implémentation est mise sur l'extraction efficace des
attributs pour le formatage et la manipulation. Le module gère aussi les objets
dépendant des fuseaux horaires

>>>

>>> # dates are easily constructed and formatted


>>> from datetime import date
>>> now = date.today()
>>> now
datetime.date(2003, 12, 2)
>>> now.strftime("%m-%d-%y. %d %b %Y is a %A on the %d day of
%B.")
'12-02-03. 02 Dec 2003 is a Tuesday on the 02 day of December.'

>>> # dates support calendar arithmetic


>>> birthday = date(1964, 7, 31)
>>> age = now - birthday
>>> age.days
14368

10.9. Compression de données
Les formats d'archivage et de compression les plus communs sont directement gérés
par les modules zlib, gzip, bz2, lzma, zipfile et tarfile

>>>

>>> import zlib


>>> s = b'witch which has which witches wrist watch'
>>> len(s)
41
>>> t = zlib.compress(s)
>>> len(t)
37
>>> zlib.decompress(t)
b'witch which has which witches wrist watch'
>>> zlib.crc32(s)
226805979

10.10. Mesure des performances


Certains utilisateurs de Python sont très intéressés par les performances de
différentes approches d'un même problème. Python propose un outil de mesure
répondant simplement à ces questions.
Par exemple, pour échanger deux variables, il peut être tentant d'utiliser
l'empaquetage et le dépaquetage de tuples plutôt que la méthode traditionnelle. Le
module timeit montre rapidement le léger gain de performance obtenu :

>>>

>>> from timeit import Timer


>>> Timer('t=a; a=b; b=t', 'a=1; b=2').timeit()
0.57535828626024577
>>> Timer('a,b = b,a', 'a=1; b=2').timeit()
0.54962537085770791

En opposition à timeit et sa granularité fine, profile et pstats fournissent des


outils permettant d'identifier les parties les plus gourmandes en temps d'exécution
dans des volumes de code plus grands.

10.11. Contrôle qualité
Une approche possible pour développer des applications de très bonne qualité est
d'écrire des tests pour chaque fonction au fur et à mesure de son développement,
puis d'exécuter ces tests fréquemment lors du processus de développement.

Le module doctest cherche des tests dans les chaînes de documentation. Un test


ressemble à un simple copier-coller d'un appel et son résultat depuis le mode
interactif. Cela améliore la documentation en fournissant des exemples tout en
prouvant qu'ils sont justes :

def average(values):
"""Computes the arithmetic mean of a list of numbers.

>>> print(average([20, 30, 70]))


40.0
"""
return sum(values) / len(values)

import doctest
doctest.testmod() # automatically validate the embedded tests

Le module unittest requiert plus d'efforts que le module doctest mais il permet


de construire un jeu de tests plus complet que l'on fait évoluer dans un fichier
séparé :
import unittest

class TestStatisticalFunctions(unittest.TestCase):

def test_average(self):
self.assertEqual(average([20, 30, 70]), 40.0)
self.assertEqual(round(average([1, 5, 7]), 1), 4.3)
with self.assertRaises(ZeroDivisionError):
average([])
with self.assertRaises(TypeError):
average(20, 30, 70)

unittest.main() # Calling from the command line invokes all


tests

10.12. Piles fournies
Python adopte le principe des "piles fournies". Vous pouvez le constater au travers
des fonctionnalités évoluées et solides fournies par ses plus gros paquets. Par
exemple :

 Les modules xmlrpc.client et xmlrpc.server permettent d'appeler des


fonctions à distance quasiment sans effort. En dépit du nom des modules, aucune
connaissance du XML n'est nécessaire.
 Le paquet email est une bibliothèque pour gérer les messages électroniques,
incluant les MIME et autres encodages basés sur la RFC 2822. Contrairement
à smtplib et poplib qui envoient et reçoivent des messages, le paquet email est
une boite à outils pour construire, lire des structures de messages complexes
(comprenant des pièces jointes) ou implémenter des encodages et protocoles.
 Le paquet json permet de lire et d'écrire du JSON, format d'encodage de
données répandu. Le module csv gère la lecture et l'écriture de données stockées
sous forme de valeurs séparées par des virgules dans des fichiers (Comma-
Separated Values en anglais), format typiquement interopérable avec les bases de
données et les feuilles de calculs. Pour la lecture du XML, utilisez les
paquets xml.etree.ElementTree, xml.dom et xml.sax. Combinés, ces modules
et paquets simplifient grandement l'échange de données entre les applications
Python et les autres outils.
 Le module sqlite3 est une abstraction de la bibliothèque SQLite, permettant
de manipuler une base de données persistante, accédée et manipulée en utilisant
une syntaxe SQL quasi standard.
 L'internationalisation est possible grâce à de nombreux paquets tels
que gettext, locale ou codecs.
11. Survol de la bibliothèque standard --
Deuxième partie
Cette deuxième partie aborde des modules plus à destination des programmeurs
professionnels. Ces modules sont rarement nécessaires dans de petits scripts.

11.1. Formatage de l'affichage
Le module reprlib est une variante de la fonction repr(), spécialisé dans
l'affichage concis de conteneurs volumineux ou fortement imbriqués :

>>>

>>> import reprlib


>>> reprlib.repr(set('supercalifragilisticexpialidocious'))
"{'a', 'c', 'd', 'e', 'f', 'g', ...}"

Le module pprint propose un contrôle plus fin de l'affichage des objets, aussi bien


natifs que ceux définis par l'utilisateur, de manière à être lisible par l'interpréteur.
Lorsque le résultat fait plus d'une ligne, il est séparé sur plusieurs lignes et est
indenté pour rendre la structure plus visible :

>>>

>>> import pprint


>>> t = [[[['black', 'cyan'], 'white', ['green', 'red']],
[['magenta',
... 'yellow'], 'blue']]]
...
>>> pprint.pprint(t, width=30)
[[[['black', 'cyan'],
'white',
['green', 'red']],
[['magenta', 'yellow'],
'blue']]]

Le module textwrap formate des paragraphes de texte pour tenir sur un écran


d'une largeur donnée :

>>>

>>> import textwrap


>>> doc = """The wrap() method is just like fill() except that it
returns
... a list of strings instead of one big string with newlines to
separate
... the wrapped lines."""
...
>>> print(textwrap.fill(doc, width=40))
The wrap() method is just like fill()
except that it returns a list of strings
instead of one big string with newlines
to separate the wrapped lines.

Le module locale utilise une base de données des formats spécifiques à chaque


région pour les dates, nombres, etc. L'attribut grouping de la fonction de formatage
permet de formater directement des nombres avec un séparateur :

>>>

>>> import locale


>>> locale.setlocale(locale.LC_ALL, 'English_United States.1252')
'English_United States.1252'
>>> conv = locale.localeconv() # get a mapping of
conventions
>>> x = 1234567.8
>>> locale.format("%d", x, grouping=True)
'1,234,567'
>>> locale.format_string("%s%.*f", (conv['currency_symbol'],
... conv['frac_digits'], x), grouping=True)
'$1,234,567.80'

11.2. Gabarits (templates en anglais)


Le module string contient une classe polyvalente : Template. Elle permet d'écrire
des gabarits (templates en anglais) avec une syntaxe simple, dans le but d'être
utilisable par des non-développeurs. Ainsi, vos utilisateurs peuvent personnaliser leur
application sans la modifier.

Le format utilise des marqueurs formés d'un $ suivi d'un identifiant Python valide
(caractères alphanumériques et tirets-bas). Entourer le marqueur d'accolades permet
de lui coller d'autres caractères alphanumériques sans intercaler une espace.
Écrire $$ produit un simple $ :

>>>

>>> from string import Template


>>> t = Template('${village}folk send $$10 to $cause.')
>>> t.substitute(village='Nottingham', cause='the ditch fund')
'Nottinghamfolk send $10 to the ditch fund.'

La méthode substitute() lève une exception KeyError lorsqu'un marqueur n'a


pas été fourni, ni dans un dictionnaire, ni sous forme d'un paramètre nommé. Dans
certains cas, lorsque la donnée à appliquer peut n'être fournie que partiellement par
l'utilisateur, la méthode safe_substitute() est plus appropriée car elle laisse tels
quels les marqueurs manquants :

>>>

>>> t = Template('Return the $item to $owner.')


>>> d = dict(item='unladen swallow')
>>> t.substitute(d)
Traceback (most recent call last):
...
KeyError: 'owner'
>>> t.safe_substitute(d)
'Return the unladen swallow to $owner.'

Les classes filles de Template peuvent définir leur propre délimiteur. Typiquement,


un script de renommage de photos par lots peut choisir le symbole pourcent comme
marqueur pour les champs tels que la date actuelle, le numéro de l'image ou son
format :

>>>

>>> import time, os.path


>>> photofiles = ['img_1074.jpg', 'img_1076.jpg', 'img_1077.jpg']
>>> class BatchRename(Template):
... delimiter = '%'
>>> fmt = input('Enter rename style (%d-date %n-seqnum %f-
format): ')
Enter rename style (%d-date %n-seqnum %f-format): Ashley_%n%f

>>> t = BatchRename(fmt)
>>> date = time.strftime('%d%b%y')
>>> for i, filename in enumerate(photofiles):
... base, ext = os.path.splitext(filename)
... newname = t.substitute(d=date, n=i, f=ext)
... print('{0} --> {1}'.format(filename, newname))

img_1074.jpg --> Ashley_0.jpg


img_1076.jpg --> Ashley_1.jpg
img_1077.jpg --> Ashley_2.jpg
Une autre utilisation des gabarits consiste à séparer la logique métier des détails
spécifiques à chaque format de sortie. Il est ainsi possible de générer des gabarits
spécifiques pour les fichiers XML, texte, HTML…

11.3. Traitement des données binaires


Le module struct expose les fonctions pack() et unpack() permettant de
travailler avec des données binaires. L'exemple suivant montre comment parcourir
un entête de fichier ZIP sans recourir au module zipfile. Les
marqueurs "H" et "I" représentent des nombres entiers non signés, stockés
respectivement sur deux et quatre octets. Le "<" indique qu'ils ont une taille
standard et utilisent la convention petit-boutiste :

import struct

with open('myfile.zip', 'rb') as f:


data = f.read()

start = 0
for i in range(3): # show the first 3 file
headers
start += 14
fields = struct.unpack('<IIIHH', data[start:start+16])
crc32, comp_size, uncomp_size, filenamesize, extra_size =
fields

start += 16
filename = data[start:start+filenamesize]
start += filenamesize
extra = data[start:start+extra_size]
print(filename, hex(crc32), comp_size, uncomp_size)

start += extra_size + comp_size # skip to the next header

11.4. Fils d'exécution
Des tâches indépendantes peuvent être exécutées de manière non séquentielle en
utilisant des fils d'exécution (threading en anglais). Les fils d'exécution peuvent être
utilisés pour améliorer la réactivité d'une application qui interagit avec l'utilisateur
pendant que d'autres traitements sont exécutés en arrière-plan. Une autre utilisation
typique est de séparer sur deux fils d'exécution distincts les entrées / sorties et le
calcul.
Le code suivant donne un exemple d'utilisation du module threading exécutant des
tâches en arrière-plan pendant que le programme principal continue de s'exécuter :

import threading, zipfile

class AsyncZip(threading.Thread):
def __init__(self, infile, outfile):
threading.Thread.__init__(self)
self.infile = infile
self.outfile = outfile

def run(self):
f = zipfile.ZipFile(self.outfile, 'w',
zipfile.ZIP_DEFLATED)
f.write(self.infile)
f.close()
print('Finished background zip of:', self.infile)

background = AsyncZip('mydata.txt', 'myarchive.zip')


background.start()
print('The main program continues to run in foreground.')

background.join() # Wait for the background task to finish


print('Main program waited until background was done.')

Le principal défi des applications avec plusieurs fils d'exécution consiste à


coordonner ces fils qui partagent des données ou des ressources. Pour ce faire, le
module threading expose quelques outils dédiés à la synchronisation comme les
verrous (locks en anglais), les événements (events en anglais), les variables
conditionnelles (condition variables en anglais) et les sémaphores (semaphore en
anglais).

Bien que ces outils soient puissants, de petites erreurs de conception peuvent
engendrer des problèmes difficiles à reproduire. Donc, l'approche classique pour
coordonner des tâches est de restreindre l'accès d'une ressource à un seul fil
d'exécution et d'utiliser le module queue pour alimenter ce fil d'exécution en requêtes
venant d'autres fils d'exécution. Les applications utilisant des Queue pour leurs
communication et coordination entre fils d'exécution sont plus simples à concevoir,
plus lisibles et plus fiables.
11.5. Journalisation
Le module logging est un système de journalisation complet. Dans son utilisation la
plus élémentaire, les messages sont simplement envoyés dans un fichier ou
sur sys.stderr :

import logging
logging.debug('Debugging information')
logging.info('Informational message')
logging.warning('Warning:config file %s not found',
'server.conf')
logging.error('Error occurred')
logging.critical('Critical error -- shutting down')

Cela produit l'affichage suivant :

WARNING:root:Warning:config file server.conf not found


ERROR:root:Error occurred
CRITICAL:root:Critical error -- shutting down

Par défaut, les messages d'information et de débogage sont ignorés, les autres sont
envoyés vers la sortie standard. Il est aussi possible d'envoyer les messages par
courriel, datagrammes, en utilisant des connecteurs réseau ou vers un serveur
HTTP. Des nouveaux filtres permettent d'utiliser des sorties différentes en fonction
de la priorité du message : DEBUG, INFO, WARNING, ERROR et CRITICAL.

La configuration de la journalisation peut être effectuée directement dans le code


Python ou peut être chargée depuis un fichier de configuration, permettant de
personnaliser la journalisation sans modifier l'application.

11.6. Références faibles
Python gère lui-même la mémoire (par comptage des références pour la plupart des
objets et en utilisant un ramasse-miettes (garbage collector en anglais) pour éliminer
les cycles). La mémoire est libérée rapidement lorsque sa dernière référence est
supprimée.

Cette approche fonctionne bien pour la majorité des applications mais, parfois, il est
nécessaire de surveiller un objet seulement durant son utilisation par quelque chose
d'autre. Malheureusement, le simple fait de le suivre crée une référence qui rend
l'objet permanent. Le module weakref expose des outils pour suivre les objets sans
pour autant créer une référence. Lorsqu'un objet n'est pas utilisé, il est
automatiquement supprimé du tableau des références faibles et une fonction de
rappel (callback en anglais) est appelée. Un exemple typique est le cache d'objets
coûteux à créer :

>>>

>>> import weakref, gc


>>> class A:
... def __init__(self, value):
... self.value = value
... def __repr__(self):
... return str(self.value)
...
>>> a = A(10) # create a reference
>>> d = weakref.WeakValueDictionary()
>>> d['primary'] = a # does not create a reference
>>> d['primary'] # fetch the object if it is still
alive
10
>>> del a # remove the one reference
>>> gc.collect() # run garbage collection right
away
0
>>> d['primary'] # entry was automatically removed
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
d['primary'] # entry was automatically removed
File "C:/python37/lib/weakref.py", line 46, in __getitem__
o = self.data[key]()
KeyError: 'primary'

11.7. Outils pour les listes


Beaucoup de structures de données peuvent être représentées avec les listes
natives. Cependant, d'autres besoins peuvent émerger pour des structures ayant des
caractéristiques différentes, typiquement en termes de performance.

Le module array fournit un objet array() ne permettant de stocker que des listes


homogènes mais d'une manière plus compacte. L'exemple suivant montre une liste
de nombres stockés chacun sur deux octets non signés (marqueur "H") plutôt que
d'utiliser 16 octets comme l'aurait fait une liste classique :

>>>
>>> from array import array
>>> a = array('H', [4000, 10, 700, 22222])
>>> sum(a)
26932
>>> a[1:3]
array('H', [10, 700])

Le module collections fournit la classe deque(). Elle ressemble à une liste mais


est plus rapide pour l'insertion ou l'extraction des éléments par la gauche et plus
lente pour accéder aux éléments du milieu. Ces objets sont particulièrement adaptés
pour construire des queues ou des algorithmes de parcours d'arbres en largeur (ou
BFS, pour Breadth First Search en anglais) :

>>>

>>> from collections import deque


>>> d = deque(["task1", "task2", "task3"])
>>> d.append("task4")
>>> print("Handling", d.popleft())
Handling task1
unsearched = deque([starting_node])
def breadth_first_search(unsearched):
node = unsearched.popleft()
for m in gen_moves(node):
if is_goal(m):
return m
unsearched.append(m)

En plus de fournir des implémentations de listes alternatives, la bibliothèque fournit


des outils tels que bisect, un module contenant des fonctions de manipulation de
listes triées :

>>>

>>> import bisect


>>> scores = [(100, 'perl'), (200, 'tcl'), (400, 'lua'), (500,
'python')]
>>> bisect.insort(scores, (300, 'ruby'))
>>> scores
[(100, 'perl'), (200, 'tcl'), (300, 'ruby'), (400, 'lua'), (500,
'python')]

Le module heapq permet d'implémenter des tas (heap en anglais) à partir de simples


listes. La valeur la plus faible est toujours à la première position (indice 0). C'est utile
dans les cas où l'application accède souvent à l'élément le plus petit mais sans
vouloir classer entièrement la liste :
>>>

>>> from heapq import heapify, heappop, heappush


>>> data = [1, 3, 5, 7, 9, 2, 4, 6, 8, 0]
>>> heapify(data) # rearrange the list into
heap order
>>> heappush(data, -5) # add a new entry
>>> [heappop(data) for i in range(3)] # fetch the three smallest
entries
[-5, 0, 1]

11.8. Arithmétique décimale à virgule flottante


Le module decimal exporte la classe Decimal : elle est spécialisée dans le calcul
de nombres décimaux représentés en virgule flottante. Par rapport à la classe
native float, elle est particulièrement utile pour :

 les applications traitant de finance et autres utilisations nécessitant une


représentation décimale exacte,
 le contrôle de la précision,
 le contrôle sur les arrondis pour répondre à des obligations légales ou
réglementaires,
 suivre les décimales significatives, ou
 les applications pour lesquelles l'utilisateur attend des résultats identiques aux
calculs faits à la main.

Par exemple, calculer 5 % de taxe sur une facture de 70 centimes donne un résultat
différent en nombre à virgule flottante binaire et décimale. La différence devient
significative lorsqu'on arrondit le résultat au centime près :

>>>

>>> from decimal import *


>>> round(Decimal('0.70') * Decimal('1.05'), 2)
Decimal('0.74')
>>> round(.70 * 1.05, 2)
0.73

Le résultat d'un calcul donné par Decimal conserve les zéros non-significatifs. La


classe conserve automatiquement quatre décimales significatives pour des
opérandes à deux décimales significatives. La classe Decimal imite les
mathématiques telles qu'elles pourraient être effectuées à la main, évitant les
problèmes typiques de l'arithmétique binaire à virgule flottante qui n'est pas capable
de représenter exactement certaines quantités décimales.

La représentation exacte de la classe Decimal lui permet de faire des calculs de


modulo ou des tests d'égalité qui ne seraient pas possibles avec une représentation
à virgule flottante binaire :

>>>

>>> Decimal('1.00') % Decimal('.10')


Decimal('0.00')
>>> 1.00 % 0.10
0.09999999999999995

>>> sum([Decimal('0.1')]*10) == Decimal('1.0')


True
>>> sum([0.1]*10) == 1.0
False

Le module decimal permet de faire des calculs avec autant de précision que


nécessaire :

>>>

>>> getcontext().prec = 36
>>> Decimal(1) / Decimal(7)
Decimal('0.142857142857142857142857142857142857')

12. Environnements virtuels et paquets


12.1. Introduction
Les programmes Python utilisent souvent des paquets et modules qui ne font pas
partie de la bibliothèque standard. Ils nécessitent aussi, parfois, une version
spécifique d'une bibliothèque, par exemple parce qu'un certain bug a été corrigé ou
encore que le programme a été implémenté en utilisant une version obsolète de
l'interface de cette bibliothèque.

Cela signifie qu'il n'est pas toujours possible, pour une installation unique de Python,
de couvrir tous les besoins de toutes les applications. Basiquement, si une
application A dépend de la version 1.0 d'un module et qu'une application B dépend
de la version 2.0, ces dépendances entrent en conflit et installer la version 1.0 ou 2.0
laisse une des deux applications incapable de fonctionner.
La solution est de créer un environnement virtuel, un dossier auto-suffisant qui
contient une installation de Python pour une version particulière de Python ainsi que
des paquets additionnels.

Différentes applications peuvent alors utiliser des environnements virtuels différents.


Pour résoudre l'exemple précédent où il existe un conflit de dépendances,
l'application A a son environnement virtuel avec la version 1.0 installée pendant que
l'application B a un autre environnement virtuel avec la version 2.0. Si l'application B
requiert que la bibliothèque soit mise à jour à la version 3.0, cela n'affecte pas
l'environnement de A.

12.2. Création d'environnements virtuels


Le module utilisé pour créer et gérer des environnements virtuels
s'appelle venv. venv installe en général la version de Python la plus récente dont vous
disposez. Si plusieurs versions de Python sont sur votre système, vous pouvez
choisir une version particulière en exécutant python3.X où X indique la version de
votre choix.

Pour créer un environnement virtuel, décidez d'un dossier où vous voulez le placer et
exécutez le module venv comme un script avec le chemin du dossier :

python3 -m venv tutorial-env

Cela crée le dossier tutorial-env (s'il n'existe pas) et des sous-dossiers contenant une


copie de l'interpréteur Python, de la bibliothèque standard et quelques autres fichiers
utiles.

Une fois l'environnement virtuel créé, vous pouvez l'activer.

Sur Windows, lancez :

tutorial-env\Scripts\activate.bat

Sur Unix et MacOS, lancez :

source tutorial-env/bin/activate

(Ce script est écrit pour le shell bash. Si vous utilisez csh ou fish, utilisez les
variantes activate.csh ou activate.fish.)
Activer l'environnement virtuel change le prompt de votre ligne de commande pour
afficher le nom de l'environnement virtuel que vous utilisez. Cela modifie aussi
l'environnement afin, lorsque vous tapez python, d'exécuter la version spécifique de
Python installée dans l'environnement. Par exemple :

$ source ~/envs/tutorial-env/bin/activate
(tutorial-env) $ python
Python 3.5.1 (default, May 6 2016, 10:59:36)
...
>>> import sys
>>> sys.path
['', '/usr/local/lib/python35.zip', ...,
'~/envs/tutorial-env/lib/python3.5/site-packages']
>>>

12.3. Gestion des paquets avec pip


Vous pouvez installer, mettre à jour et supprimer des paquets en utilisant un
programme appelé pip. Par défaut, pip installe les paquets du Python Package
Index, <https://pypi.org>. Vous pouvez parcourir le Python Package Index avec un
navigateur ou utiliser la fonction de recherche (assez) limitée de pip :

(tutorial-env) $ pip search astronomy


skyfield - Elegant astronomy for Python
gary - Galactic astronomy and gravitational
dynamics.
novas - The United States Naval Observatory
NOVAS astronomy library
astroobs - Provides astronomy ephemeris to plan
telescope observations
PyAstronomy - A collection of astronomy related tools
for Python.
...

pip a plusieurs sous-commandes : search, install, uninstall, freeze, etc. Consultez le


guide Installation de modules Python pour une documentation exhaustive sur pip.

Vous pouvez installer la dernière version d'un paquet en indiquant son nom :

(tutorial-env) $ pip install novas


Collecting novas
Downloading novas-3.1.1.3.tar.gz (136kB)
Installing collected packages: novas
Running setup.py install for novas
Successfully installed novas-3.1.1.3

Vous pouvez installer une version spécifique d'un paquet en donnant le nom du
paquet suivi de == et du numéro de version souhaitée :

(tutorial-env) $ pip install requests==2.6.0


Collecting requests==2.6.0
Using cached requests-2.6.0-py2.py3-none-any.whl
Installing collected packages: requests
Successfully installed requests-2.6.0

Si vous relancez cette commande, pip remarque que la version demandée est déjà


installée et ne fait rien. Vous pouvez fournir un numéro de version différent pour
récupérer cette version ou lancer pip install --upgrade pour mettre à jour le paquet à la
dernière version :

(tutorial-env) $ pip install --upgrade requests


Collecting requests
Installing collected packages: requests
Found existing installation: requests 2.6.0
Uninstalling requests-2.6.0:
Successfully uninstalled requests-2.6.0
Successfully installed requests-2.7.0

pip uninstall suivi d'un ou plusieurs noms de paquets les supprime de votre


environnement virtuel.

pip show affiche des informations à propos d'un paquet précis :

(tutorial-env) $ pip show requests


---
Metadata-Version: 2.0
Name: requests
Version: 2.7.0
Summary: Python HTTP for Humans.
Home-page: http://python-requests.org
Author: Kenneth Reitz
Author-email: me@kennethreitz.com
License: Apache 2.0
Location: /Users/akuchling/envs/tutorial-env/lib/python3.4/site-
packages
Requires:

pip list liste tous les paquets installés dans l'environnement virtuel :


(tutorial-env) $ pip list
novas (3.1.1.3)
numpy (1.9.2)
pip (7.0.3)
requests (2.7.0)
setuptools (16.0)

pip freeze produit une liste similaire des paquets installés mais l'affichage adopte un
format que pip install peut lire. La convention habituelle est de mettre cette liste dans
un fichier requirements.txt :

(tutorial-env) $ pip freeze > requirements.txt


(tutorial-env) $ cat requirements.txt
novas==3.1.1.3
numpy==1.9.2
requests==2.7.0

Le fichier requirements.txt peut alors être ajouté dans un système de gestion de


versions comme faisant partie de votre application. Les utilisateurs peuvent alors
installer tous les paquets nécessaires à l'application avec install -r :

(tutorial-env) $ pip install -r requirements.txt


Collecting novas==3.1.1.3 (from -r requirements.txt (line 1))
...
Collecting numpy==1.9.2 (from -r requirements.txt (line 2))
...
Collecting requests==2.7.0 (from -r requirements.txt (line 3))
...
Installing collected packages: novas, numpy, requests
Running setup.py install for novas
Successfully installed novas-3.1.1.3 numpy-1.9.2 requests-2.7.0

pip reconnait beaucoup d'autres options, documentées dans le guide Installation de


modules Python. Lorsque vous avez écrit un paquet, si vous voulez le rendre
disponible sur PyPI, lisez le guide Distribuer des modules Python.

13. Pour aller plus loin


La lecture de ce tutoriel a probablement renforcé votre intérêt pour Python et vous
devez être impatient de l'utiliser pour résoudre des vrais problèmes. Où aller pour en
apprendre plus ?
Ce tutoriel fait partie de la documentation de Python, et la documentation de Python
est vaste :

 La bibliothèque standard :

Nous vous conseillons de naviguer dans le manuel, c'est une référence complète
(quoique laconique) sur les types, fonctions et modules de la bibliothèque standard.
La distribution standard de Python inclut énormément de code supplémentaire. Il
existe des modules pour lire les courriels, récupérer des documents via HTTP,
générer des nombres aléatoires, analyser les paramètres de la ligne de commande,
écrire des programmes CGI, compresser des données et beaucoup d'autres
fonctions. Une balade dans la documentation de la bibliothèque vous donnera une
idée de ce qui est disponible.
 Installation de modules Python explique comment installer des paquets écrits
par d'autres utilisateurs de Python.
 La référence du langage Python contient une explication détaillée de la
syntaxe et sémantique de Python. C'est une lecture fastidieuse, mais elle a sa place
dans une documentation exhaustive.

D'autres ressources :

 https://www.python.org est le site principal pour Python. Il contient du code, de


la documentation, des liens vers d'autres sites traitant de Python partout sur Internet.
Il est répliqué dans différents endroits autour du globe, comme en Europe, au Japon
et en Australie. Ces répliques peuvent dans certains cas être plus rapides que le site
principal, en fonction de l'endroit où vous vous trouvez.
 https://docs.python.org/fr/ offre un accès rapide à la documentation de Python
en français.
 https://pypi.org (The Python Package Index en anglais, pour le "répertoire des
paquets Python") : auparavant surnommé "La Fromagerie" 1 (The Cheese Shop en
anglais), c'est un catalogue de modules Python disponibles au téléchargement,
construit par les utilisateurs. Lorsque vous commencez à distribuer du code, vous
pouvez l'inscrire ici afin que les autres puissent le trouver.
 https://code.activestate.com/recipes/langs/python/  : "The Python Cookbook"
est un recueil assez imposant d'exemples de code, de modules et de scripts. Les
contributions les plus remarquables y sont regroupées dans le livre "Python
Cookbook" (O'Reilly & Associates, ISBN 0-596-00797-3).
 http://www.pyvideo.org regroupe des liens vers des vidéos relatives à Python,
enregistrées lors de conférences ou de réunions de groupes d'utilisateurs.
 https://scipy.org : le projet "The Scientific Python" contient des modules pour
manipuler et calculer rapidement sur des tableaux. Le projet héberge aussi divers
paquets sur l'algèbre linéaire, les transformées de Fourier, des résolveurs non-
linéaires, différentes distributions de nombres aléatoires, l'analyse statistique et
d'autres choses du domaine scientifique.

Pour poser des questions ou remonter des problèmes liés à Python, vous pouvez
écrire sur le forum comp.lang.python ou les envoyer à la liste de diffusion <python-
list@python.org>. Le forum et la liste de diffusion sont liées, un message publié sur
l'un sera automatiquement transféré sur l'autre. Des centaines de messages y sont
publiés chaque jour, posant (ou répondant à) des questions, suggérant de nouvelles
fonctionnalités et annonçant des nouveaux modules. Les archives sont disponibles
à https://mail.python.org/pipermail/.

Avant de publier un message, assurez-vous d'avoir lu la liste de la Foire Aux


Questions (aussi appelée FAQ). La FAQ répond à beaucoup de questions
fréquentes et contient probablement une solution à votre problème.

Notes

1 « Cheese Shop » est un sketch de Monty Python : un client entre dans une
fromagerie, mais peu importe le fromage que demande le client, le vendeur dit qu’il
n’en a pas.

14. Édition interactive des entrées et


substitution d'historique
Certaines versions de l'interpréteur Python prennent en charge l'édition de la ligne
d'entrée courante et la substitution d'historique, similaires aux facilités que l'on trouve
dans le shell Korn et dans le shell GNU Bash. Ces implémentations utilisent la
bibliothèque GNU Readline, qui gère plusieurs styles d'édition. La bibliothèque a sa
propre documentation, nous ne la dupliquons pas ici.

14.1. Complétion automatique et édition de


l'historique
La complétion de noms de variables et de modules est automatiquement activée au
démarrage de l'interpréteur. Ainsi, la touche Tab invoque la fonction de complétion ;
la recherche s'effectue dans les noms d'instructions Python, les noms des variables
locales et les noms de modules disponibles. Pour les expressions pointées telles
que string.a, l'expression est évaluée jusqu'au dernier '.' avant de suggérer les
options disponibles à partir des attributs de l'objet résultant de cette évaluation.
Notez bien que ceci peut exécuter une partie du code de l'application si un objet
disposant d'une méthode __getattr__() fait partie de l'expression. La
configuration par défaut sauvegarde l'historique dans un fichier
nommé .python_history dans votre dossier d'utilisateur. L'historique est ainsi
conservé entre les sessions interactives successives.

14.2. Alternatives à l'interpréteur interactif


Cette facilité constitue un énorme pas en avant comparé aux versions précédentes
de l'interpréteur. Toutefois, il reste des fonctions à implémenter comme l'indentation
correcte sur les lignes de continuation (l'analyseur sait si une indentation doit
suivre) ; le mécanisme de complétion devrait utiliser la table de symboles de
l'interpréteur. Une commande pour vérifier (ou même suggérer) les correspondances
de parenthèses, de guillemets, etc., serait également utile.

Une alternative améliorée de l'interpréteur interactif est développée depuis


maintenant quelques temps : IPython. Il fournit la complétion, l'exploration d'objets et
une gestion avancée de l'historique. Il peut également être personnalisé en
profondeur et embarqué dans d'autres applications. Un autre environnement
interactif amélioré similaire est bpython.

15. Arithmétique en nombres à virgule


flottante : problèmes et limites
Les nombres à virgule flottante sont représentés, au niveau matériel, en fractions de
nombres binaires (base 2). Par exemple, la fraction décimale

0.125

a la valeur 1/10 + 2/100 + 5/1000 et, de la même manière, la fraction binaire

0.001

a la valeur 0/2 + 0/4 + 1/8. Ces deux fractions ont une valeur identique, la seule
différence est que la première est une fraction décimale, la seconde est une fraction
binaire.

Malheureusement, la plupart des fractions décimales ne peuvent pas avoir de


représentation exacte en fractions binaires. Par conséquent, en général, les nombres
à virgule flottante que vous donnez sont seulement approximés en fractions binaires
pour être stockés dans la machine.

Le problème est plus simple à aborder en base 10. Prenons par exemple, la fraction
1/3. Vous pouvez l'approximer en une fraction décimale :

0.3

ou, mieux,

0.33

ou, mieux,

0.333

etc. Peu importe le nombre de décimales que vous écrivez, le résultat ne vaut jamais
exactement 1/3, mais c'est une estimation s'en approchant toujours mieux.

De la même manière, peu importe combien de décimales en base 2 vous utilisez, la


valeur décimale 0.1 ne peut pas être représentée exactement en fraction binaire. En
base 2, 1/10 est le nombre périodique suivant

0.0001100110011001100110011001100110011001100110011...

En se limitant à une quantité finie de bits, on ne peut obtenir qu'une approximation.


Sur la majorité des machines aujourd'hui, les nombres à virgule flottante sont
approximés par une fraction binaire avec les 53 premiers bits comme numérateur et
une puissance de deux au dénominateur. Dans le cas de 1/10, la fraction binaire
est 3602879701896397 / 2 ** 55 qui est proche mais ne vaut pas exactement 1/10.

Du fait de la manière dont les flottants sont affichés par l'interpréteur, il est facile
d'oublier que la valeur stockée est une approximation de la fraction décimale
d'origine. Python n'affiche qu'une approximation décimale de la valeur stockée en
binaire. Si Python devait afficher la vraie valeur décimale de l'approximation binaire
stockée pour 0,1, il afficherait

>>>

>>> 0.1
0.1000000000000000055511151231257827021181583404541015625
C'est bien plus de décimales que ce qu'attendent la plupart des utilisateurs, donc
Python affiche une valeur arrondie afin d'améliorer la lisibilité

>>>

>>> 1 / 10
0.1

Rappelez-vous simplement que, bien que la valeur affichée ressemble à la valeur


exacte de 1/10, la valeur stockée est la représentation la plus proche en fraction
binaire.

Il existe beaucoup de nombres décimaux qui partagent une même approximation en


fraction binaire. Par
exemple, 0.1, 0.10000000000000001 et 0.1000000000000000055511151231257827021181583
404541015625 ont tous pour approximation 3602879701896397 / 2 ** 55. Puisque
toutes ces valeurs décimales partagent la même approximation, chacune peut être
affichée tout en respectant eval(repr(x)) == x.

Historiquement, le mode interactif de Python et la primitive repr() choisissaient la


version avec 17 décimales significatives, 0.10000000000000001. Python, depuis la
version 3.1 (sur la majorité des systèmes) est maintenant capable de choisir la plus
courte représentation et n'affiche que 0.1.

Ce comportement est inhérent à la nature même de la représentation des nombres à


virgule flottante dans la machine : ce n'est pas un bogue dans Python et ce n'est pas
non plus un bogue dans votre code. Vous pouvez observer le même type de
comportement dans tous les autres langages utilisant le support matériel pour le
calcul des nombres à virgule flottante (bien que certains langages ne rendent pas
visible la différence par défaut, ou pas dans tous les modes d'affichage).

Pour obtenir un affichage plus plaisant, les fonctions de formatage de chaînes de


caractères peuvent limiter le nombre de décimales significatives affichées :

>>>

>>> format(math.pi, '.12g') # give 12 significant digits


'3.14159265359'

>>> format(math.pi, '.2f') # give 2 digits after the point


'3.14'

>>> repr(math.pi)
'3.141592653589793'
Il est important de comprendre que tout cela n'est, au sens propre, qu'une illusion  :
vous demandez simplement à Python d'arrondir la valeur stockée réellement dans la
machine à l'affichage.

Une autre conséquence du fait que 0,1 n'est pas exactement stocké 1/10 est que la
somme de trois valeurs de 0,1 ne donne pas 0,3 non plus :

>>>

>>> .1 + .1 + .1 == .3
False

Aussi, puisque 0,1 ne peut pas être stocké avec une représentation plus proche de
sa valeur exacte 1/10, comme 0,3 qui ne peut pas être plus proche de sa valeur
exacte 3/10, arrondir au préalable avec la fonction round() n'aide en rien :

>>>

>>> round(.1, 1) + round(.1, 1) + round(.1, 1) == round(.3, 1)


False

Bien que les nombres ne peuvent se rapprocher plus de la valeur qu’on attend qu’ils
aient, la fonction round() peut être utile à postériori pour arrondir deux valeurs
inexactes et pouvoir les comparer :

>>>

>>> round(.1 + .1 + .1, 10) == round(.3, 10)


True

L'arithmétique des nombres binaires à virgule flottante réserve beaucoup de


surprises de ce genre. Le problème avec "0.1" est expliqué en détails ci-dessous,
dans la section "Erreurs de représentation". Voir The Perils of Floating Point pour
une liste plus complète de ce genre de surprises.

Même s'il est vrai qu'il n'existe pas de réponse simple, ce n'est pas la peine de vous
méfier outre mesure des nombres à virgule flottante ! Les erreurs, en Python, dans
les opérations de nombres à virgule flottante sont dues au matériel sous-jacent et,
sur la plupart des machines, sont de l'ordre de 1 sur 2**53 par opération. C'est plus
que suffisant pour la plupart des tâches, mais vous devez garder à l'esprit que ce ne
sont pas des opérations décimales et que chaque opération sur des nombres à
virgule flottante peut souffrir d'une nouvelle erreur.
Bien que des cas pathologiques existent, pour la plupart des cas d'utilisations
courants vous obtiendrez le résultat attendu à la fin en arrondissant simplement au
nombre de décimales désirées à l'affichage avec str(). Pour un contrôle fin sur la
manière dont les décimales sont affichées, consultez dans Syntaxe de formatage de
chaîne les spécifications de formatage de la méthode str.format().

Pour les cas requérant une représentation décimale exacte, le module decimal peut


être utile : il implémente l'arithmétique décimale et peut donc être un choix adapté
pour des applications nécessitant une grande précision.

Une autre forme d'arithmétique exacte est implémentée dans le module fractions qui


se base sur les nombres rationnels (donc 1/3 peut y être représenté exactement).

Si vous êtes un utilisateur intensif des opérations sur les nombres à virgule flottante,
nous vous conseillons de considérer le paquet Numerical Python ainsi que les
paquets pour les opérations statistiques et mathématiques fournis par le projet
SciPy. Consultez <https://scipy.org>.

Python fournit des outils qui peuvent être utiles dans les rares occasions où vous
voulez réellement connaître la valeur exacte d'un nombre à virgule flottante. La
méthode float.as_integer_ratio() donne la valeur du nombre sous forme de fraction :

>>>

>>> x = 3.14159
>>> x.as_integer_ratio()
(3537115888337719, 1125899906842624)

Puisque le ratio est exact, il peut être utilisé pour recréer la valeur originale sans
perte :

>>>

>>> x == 3537115888337719 / 1125899906842624


True

La méthode float.hex() donne le nombre en hexadécimal (base 16), donnant ici aussi


la valeur exacte stockée par la machine :

>>>

>>> x.hex()
'0x1.921f9f01b866ep+1'
Cette représentation hexadécimale petit être utilisée pour reconstruire, sans
approximation, le float :

>>>

>>> x == float.fromhex('0x1.921f9f01b866ep+1')
True

Puisque cette représentation est exacte, elle est pratique pour échanger des valeurs
entre différentes versions de Python (indépendamment de la machine) ou d'autres
langages qui comprennent ce format (tels que Java et C99).

Une autre fonction utile est math.fsum(), elle aide à diminuer les pertes de précision
lors des additions. Elle surveille les décimales perdues au fur et à mesure que les
valeurs sont ajoutées au total. Cela peut faire une différence au niveau de la
précision globale en empêchant les erreurs de s'accumuler jusqu'à affecter le résultat
final :

>>> sum([0.1] * 10) == 1.0


False
>>> math.fsum([0.1] * 10) == 1.0
True

15.1. Erreurs de représentation
Cette section explique en détail l'exemple du "0.1" et montre comment vous pouvez
effectuer une analyse exacte de ce type de cas par vous-même. Nous supposons
que la représentation binaire des nombres flottants vous est familière.

Le terme Erreur de représentation (representation error en anglais) signifie que la


plupart des fractions décimales ne peuvent être représentées exactement en binaire.
C'est la principale raison pour laquelle Python (ou Perl, C, C++, Java, Fortran et
beaucoup d'autres) n'affiche habituellement pas le résultat exact en décimal.

Pourquoi ? 1/10 n'est pas représentable de manière exacte en fraction binaire.


Cependant, toutes les machines d'aujourd'hui (novembre 2000) suivent la norme
IEEE-754 en ce qui concerne l'arithmétique des nombres à virgule flottante et la
plupart des plateformes utilisent un « IEEE-754 double précision » pour représenter
les floats de Python. Les « IEEE-754 double précision » utilisent 53 bits de précision
donc, à la lecture, l'ordinateur essaie de convertir 0,1 dans la fraction la plus proche
possible de la forme J/2**N avec J un nombre entier d'exactement 53 bits. Pour
réécrire
1 / 10 ~= J / (2**N)

en

J ~= 2**N / 10

en se rappelant que J fait exactement 53 bits (donc >= 2**52 mais < 2**53), la


meilleure valeur possible pour N est 56 :

>>>

>>> 2**52 <= 2**56 // 10 < 2**53


True

Donc 56 est la seule valeur possible pour N qui laisse exactement 53 bits pour J. La
meilleure valeur possible pour J est donc ce quotient, arrondi :

>>>

>>> q, r = divmod(2**56, 10)


>>> r
6

Puisque la retenue est plus grande que la moitié de 10, la meilleure approximation
est obtenue en arrondissant par le haut :

>>>

>>> q+1
7205759403792794

Par conséquent la meilleure approximation possible pour 1/10 en « IEEE-754 double


précision » est celle au-dessus de 2**56, soit :

7205759403792794 / 2 ** 56

Diviser le numérateur et le dénominateur par deux réduit la fraction à :

3602879701896397 / 2 ** 55

Notez que puisque l'arrondi a été fait vers le haut, le résultat est en réalité
légèrement plus grand que 1/10 ; si nous n'avions pas arrondi par le haut, le quotient
aurait été légèrement plus petit que 1/10. Mais dans aucun cas il ne
vaut exactement 1/10 !

Donc l'ordinateur ne "voit" jamais 1/10 : ce qu'il voit est la fraction exacte donnée ci-
dessus, la meilleure approximation utilisant les nombres à virgule flottante double
précision de l'« IEEE-754 » :

>>>

>>> 0.1 * 2 ** 55
3602879701896397.0

Si nous multiplions cette fraction par 10**30, nous pouvons observer les valeurs de
ses 55 décimales de poids fort :

>>>

>>> 3602879701896397 * 10 ** 55 // 2 ** 55
1000000000000000055511151231257827021181583404541015625

La valeur stockée dans l'ordinateur est donc égale à


0,1000000000000000055511151231257827021181583404541015625. Au lieu
d'afficher toutes les décimales, beaucoup de langages (dont les vieilles versions de
Python) arrondissent le résultat à la 17e décimale significative :

>>>

>>> format(0.1, '.17f')


'0.10000000000000001'

Les modules fractions et decimal rendent simples ces calculs :

>>>

>>> from decimal import Decimal


>>> from fractions import Fraction

>>> Fraction.from_float(0.1)
Fraction(3602879701896397, 36028797018963968)

>>> (0.1).as_integer_ratio()
(3602879701896397, 36028797018963968)

>>> Decimal.from_float(0.1)
Decimal('0.100000000000000005551115123125782702118158340454101562
5')
>>> format(Decimal.from_float(0.1), '.17')
'0.10000000000000001'

16. Annexe
16.1. Mode interactif
16.1.1. Gestion des erreurs
Quand une erreur se produit, l'interpréteur affiche un message d'erreur et la trace
d'appels. En mode interactif, il revient à l'invite de commande primaire ; si l'entrée
provient d'un fichier, l'interpréteur se termine avec un code de sortie non nul après
avoir affiché la trace d'appels (les exceptions gérées par une clause except dans une
instruction try ne sont pas considérées comme des erreurs dans ce contexte).
Certaines erreurs sont inconditionnellement fatales et provoquent la fin du
programme avec un code de sortie non nul ; les incohérences internes et, dans
certains cas, les pénuries de mémoire sont traitées de la sorte. Tous les messages
d'erreur sont écrits sur le flux d'erreur standard ; l'affichage normal des commandes
exécutées est écrit sur la sortie standard.

Taper le caractère d'interruption (généralement Ctrl+C ou Supprimer) au niveau de


l'invite de commande primaire annule l'entrée et revient à l'invite 1. Saisir une
interruption tandis qu'une commande s'exécute lève une
exception KeyboardInterrupt qui peut être gérée par une instruction try.

16.1.2. Scripts Python exécutables


Sur les systèmes Unix, un script Python peut être rendu directement exécutable,
comme un script shell, en ajoutant la ligne

#!/usr/bin/env python3.5

(en supposant que l'interpréteur est dans le PATH de l'utilisateur) au début du script
et en rendant le fichier exécutable. '#!' doivent être les deux premiers caractères du
fichier. Sur certaines plateformes, cette première ligne doit finir avec une fin de ligne
de type Unix ('\n') et pas de type Windows ('\r\n'). Notez que le caractère croisillon, '#',
est utilisé pour initier un commentaire en Python.

Un script peut être rendu exécutable en utilisant la commande chmod.

$ chmod +x myscript.py

Sur les systèmes Windows il n'y a pas de "mode exécutable". L'installateur Python
associe automatiquement les fichiers en .py avec python.exe de telle sorte qu'un
double clic sur un fichier Python le lance comme un script. L'extension peut aussi
être .pyw. Dans ce cas, la console n'apparait pas.

16.1.3. Configuration du mode interactif


En mode interactif, il peut être pratique de faire exécuter quelques commandes au
lancement de l’interpréteur. Configurez la variable
d'environnement PYTHONSTARTUP avec le nom d'un fichier contenant les
instructions à exécuter, à la même manière du .profile pour un shell Unix.

Ce fichier n'est lu qu'en mode interactif, pas quand Python lit les instructions depuis
un fichier, ni quand /dev/tty est donné explicitement comme fichier source (pour tout
le reste, Python se comporte alors comme dans une session interactive). Les
instructions de ce fichier sont exécutées dans le même espace de nommage que vos
commandes, donc les objets définis et modules importés peuvent être utilisés
directement dans la session interactive. Dans ce fichier, il est aussi possible de
changer les invites de commande sys.ps1 et sys.ps2.

Si vous voulez exécuter d'autres fichiers du dossier courant au démarrage, vous


pouvez le programmer dans le fichier de démarrage global, par exemple avec le
code suivant : if os.path.isfile('.pythonrc.py'): exec(open('.pythonrc.py').read()). Et si vous
voulez exécuter le fichier de démarrage depuis un script, vous devez le faire
explicitement dans le script :

import os
filename = os.environ.get('PYTHONSTARTUP')
if filename and os.path.isfile(filename):
with open(filename) as fobj:
startup_file = fobj.read()
exec(startup_file)
16.1.4. Modules de personnalisation
Python peut être personnalisé via les modules sitecustomize et usercustomize. Pour
découvrir comment ils fonctionnent, vous devez d'abord trouver l'emplacement de
votre dossier « site-packages » utilisateur. Démarrez Python et exécutez ce code :

>>>

>>> import site


>>> site.getusersitepackages()
'/home/user/.local/lib/python3.5/site-packages'

Vous pouvez maintenant y créer un fichier usercustomize.py et y écrire ce que vous


voulez. Il est toujours pris en compte par Python, peu importe le mode, sauf lorsque
vous démarrez avec l'option -s qui désactive l'importation automatique.

sitecustomize fonctionne de la même manière mais est généralement créé par un


administrateur et stocké dans le dossier site-packages global. Il est importé
avant usercustomize. Pour plus de détails, consultez la documentation de site.

Notes

1 Un problème avec GNU Readline peut l'en empêcher.


Installation et utilisation de Python
Cette partie de la documentation est consacrée aux informations générales au sujet
de l'installation de l'environnement Python sur différentes plateformes, l'invocation de
l'interpréteur et des choses qui facilitent le travail avec Python.

 1. Ligne de commande et environnement


o 1.1. Ligne de commande
 1.1.1. Options de l'interface
 1.1.2. Options génériques
 1.1.3. Options diverses
 1.1.4. Options à ne pas utiliser
o 1.2. Variables d'environnement
 1.2.1. Variables en mode débogage
 2. Utilisation de Python sur les plateformes Unix
o 2.1. Récupérer et installer la dernière version de Python
 2.1.1. Sur Linux
 2.1.2. Sur FreeBSD et OpenBSD
 2.1.3. Sur OpenSolaris
o 2.2. Compiler Python
o 2.3. Fichiers et chemins liés à Python
o 2.4. Divers
 3. Utilisation de Python sur Windows
o 3.1. L'installateur complet
 3.1.1. Étapes d'installation
 3.1.2. Suppression de la limitation  MAX_PATH
 3.1.3. Installation sans l'interface utilisateur
 3.1.4. Installation sans téléchargement
 3.1.5. Modification d'une installation
o 3.2. Le paquet Microsoft Store
 3.2.1. Problèmes connus
o 3.3. Les paquets  nuget.org
o 3.4. Le paquet intégrable
 3.4.1. Application Python
 3.4.2. Embarquer Python
o 3.5. Paquets alternatifs
o 3.6. Configurer Python
 3.6.1. Digression : Définition des variables d'environnement
 3.6.2. Trouver l'exécutable Python
o 3.7. UTF-8 mode
o 3.8. Lanceur Python pour Windows
 3.8.1. Pour commencer
 3.8.1.1. Depuis la ligne de commande
 3.8.1.2. Environnements virtuels
 3.8.1.3. À partir d'un script
 3.8.1.4. À partir d'associations de fichiers
 3.8.2. Lignes Shebang
 3.8.3. Arguments dans les lignes  shebang
 3.8.4. Personnalisation
 3.8.4.1. Personnalisation via des fichiers INI
 3.8.4.2. Personnalisation des versions Python par défaut
 3.8.5. Diagnostics
o 3.9. Recherche de modules
o 3.10. Modules supplémentaires
 3.10.1. PyWin32
 3.10.2. cx_Freeze
 3.10.3. WConio
o 3.11. Compiler Python sous Windows
o 3.12. Autres plateformes
 4. Utilisation de Python sur un Macintosh
o 4.1. Obtenir et installer MacPython
 4.1.1. Comment exécuter un script Python
 4.1.2. Lancer des scripts avec une interface graphique
 4.1.3. Configuration
o 4.2. L'IDE
o 4.3. Installation de paquets Python additionnels
o 4.4. Programmation d'interface graphique sur le Mac
o 4.5. Distribuer des Applications Python sur le Mac
o 4.6. Autres ressources
 5. Editors and IDEs

1. Ligne de commande et environnement


L'interpréteur CPython analyse la ligne de commande et l'environnement à la
recherche de différents paramètres.

CPython implementation detail: Le format des lignes de commande utilisé par


d'autres implémentations peut s'avérer différent. Voir Autres implémentations pour
plus d'informations.
1.1. Ligne de commande
Quand vous invoquez Python, vous pouvez spécifier n’importe laquelle de ces
options :

python [-bBdEhiIOqsSuvVWx?] [-c command | -m module-name | script


| - ] [args]

Le cas d'utilisation le plus courant est, bien entendu, la simple invocation d'un script :

python myscript.py

1.1.1. Options de l'interface
L'interface de l’interpréteur ressemble à celle du shell UNIX mais fournit quelques
méthodes d'invocation supplémentaires :

 Quand l'interpréteur est appelé avec l'entrée standard connectée à un


périphérique tty, il lit les lignes de commande et les exécute jusqu'à ce qu'un
caractère EOF (caractère fin de fichier, que vous pouvez produire avec Ctrl-D sous
UNIX ou Ctrl-Z, Enter sous Windows) soit lu.
 Quand l'interpréteur est appelé avec un argument correspondant à un nom de
fichier ou avec un fichier comme entrée standard, il lit et exécute le script contenu
dans ce fichier.
 Quand l'interpréteur est appelé avec un argument correspondant à un
répertoire, il lit et exécute un script d’un certain nom dans ce répertoire.
 Quand l'interpréteur est appelé avec l'option -c commande, il exécute la ou
les instructions Python données comme commande. Ici commande peut contenir
plusieurs instructions séparées par des fins de ligne. Les blancs en début de ligne ne
sont pas ignorés dans les instructions Python !
 Quand l'interpréteur est appelé avec l'option -m nom-de-module, le module
donné est recherché dans le chemin des modules Python et est exécuté en tant que
script.

En mode non-interactif, toute l’entrée est analysée avant d’être exécutée.


Une option d'interface termine la liste des options consommées par l'interpréteur ;
tous les arguments atterrissent dans sys.argv — notez que le premier élément, à
l'indice zéro (sys.argv|0]), est une chaîne de caractères indiquant la source du
programme.

-c <command>
Exécute le code Python dans command. command peut être une ou plusieurs
instructions, séparées par des fins de ligne, dont les espaces en début de ligne sont
significatives, comme dans le code d’un module.

Si cette option est donnée, le premier élément de sys.argv est "-c" et le répertoire


courant est ajouté au début de sys.path (permettant aux modules de ce répertoire
d'être importés comme des modules de premier niveau).

-m <module-name>
Parcourt sys.path à la recherche du module donné et exécute son contenu en tant
que module __main__.

L'argument étant un nom de module, vous ne devez pas fournir d’extension de fichier
(.py). Le nom du module doit être un nom de module Python valide, absolu, mais
l'implémentation peut ne pas l'imposer (par exemple, l'utilisation d'un trait d'union
peut être autorisée).

Les noms de paquets sont aussi autorisés (ainsi que les paquets-espace de
nommage, namespace packages en anglais). Quand un nom de paquet est donné à
la place d'un simple module, l'interpréteur exécute <pkg>.__main__ comme module
principal. Ce comportement est délibérément identique au traitement d'un dossier ou
d'un fichier zip donné en argument à l'interpréteur comme script.

Note
 

Cette option ne peut pas être utilisée avec les modules natifs et les modules
d'extension écrits en C, étant donné qu'ils ne possèdent pas de fichiers modules en
Python. Cependant, elle peut toujours être utilisée pour les modules pré-compilés,
même si le fichier source original n'est pas disponible.

Si cette option est donnée, le premier élément de sys.argv est le chemin complet


d'accès au fichier du module (pendant que le fichier est recherché, le premier
élément est mis à "-m"). Comme avec l'option -c, le dossier courant est ajouté au
début de sys.path.
-I option can be used to run the script in isolated mode where sys.path contains
neither the current directory nor the user's site-packages directory.
All PYTHON* environment variables are ignored, too.

De nombreux modules de la bibliothèque standard contiennent du code qui est


invoqué quand ils sont exécutés comme scripts. Un exemple est le module timeit :

python -m timeit -s 'setup here' 'benchmarked code here'


python -m timeit -h # for details
Voir aussi
runpy.run_module()

Fonctionnalité équivalente directement disponible en code Python

PEP 338 -- Exécuter des modules en tant que scripts

Modifié dans la version 3.1: Fournir le nom d'un paquet pour exécuter un sous-
module __main__.

Modifié dans la version 3.4: les paquets-espaces de nommage sont aussi gérés

-
Lit les commandes depuis l'entrée standard (sys.stdin). Si l'entrée standard est un
terminal, l'option -i est activée implicitement.

Si cette option est donnée, le premier élément de sys.argv est "-" et le dossier


courant est ajouté au début de sys.path.

<script>
Exécute le code Python contenu dans script, qui doit être un chemin d'accès (absolu
ou relatif) à un fichier, faisant référence à un fichier Python, à un répertoire contenant
un fichier __main__.py ou à un fichier zip contenant un fichier __main__.py.

Si cette option est donnée, le premier élément de sys.argv est le nom du script tel
que donné sur la ligne de commande.

Si le nom du script se réfère directement à un fichier Python, le répertoire contenant


ce fichier est ajouté au début de sys.path et le fichier est exécuté en tant que
module __main__.
Si le nom du script fait référence à un dossier ou à un fichier zip, le nom du script est
ajouté au début de sys.path et le fichier __main__.py à cet endroit est exécuté en
tant que module __main__.

-I option can be used to run the script in isolated mode where sys.path contains


neither the script's directory nor the user's site-packages directory.
All PYTHON* environment variables are ignored, too.

Voir aussi
runpy.run_path()

Fonctionnalité équivalente directement disponible en code Python

Si aucune option d'interface n'est donnée, l'option -i est activée


implicitement, sys.argv[0] est une chaine vide ("") et le dossier courant est ajouté
au début de sys.path. Aussi, la complétion par tabulation et l'édition de l'historique
sont automatiquement activés, s'ils sont disponibles sur votre système (voir Readline
configuration).

Voir aussi
 

Lancement de l'interpréteur

Modifié dans la version 3.4: Activation automatique de la complétion par tabulation et


édition de l'historique.

1.1.2. Options génériques
-?
-h
--help
Affiche une brève description de toutes les options de la ligne de commande.

-V
--version
Affiche la version de Python et termine. Par exemple :

Python 3.7.0b2+
Lorsque l'option est doublée, affiche davantage d'informations sur la manière dont
Python a été compilé, comme :

Python 3.7.0b2+ (3.7:0c076caaa8, Sep 22 2018, 12:04:24)


[GCC 6.2.0 20161005]

Nouveau dans la version 3.6: L'option -VV.

1.1.3. Options diverses
-b
Affiche un avertissement (warning en anglais) lors d'une comparaison d'un objet de
type bytes ou bytearray avec un objet de type str ou un objet de
type bytes avec un objet de type int. Lève une erreur si cette option est doublée ( -
bb).

Modifié dans la version 3.5: Concerne les comparaisons de bytes avec int.

-B
S'il est donné, Python ne tente pas d'écrire de fichier .pyc ou .pyo à l'importation
des modules sources. Voir aussi PYTHONDONTWRITEBYTECODE.

--check-hash-based-pycs default|always|never
Contrôle la façon dont sont validés les fichiers .pyc avec empreinte (voir Invalidation
de bytecode mis en cache). Quand la valeur est default, les caches de fichiers de
code intermédiaire sont validés en fonction de leur sémantique par défaut. Quand la
valeur est always, tous les fichiers .pyc, qu'ils soient vérifiés ou non, sont validés
par rapport à leurs fichiers sources correspondants. Quand la valeur est never, les
fichiers .pyc ne sont pas validés par rapport à leurs fichiers sources correspondants.

La sémantique des fichiers .pyc générés en fonction de l'horodatage n'est pas


affectée par cette option.

-d
Active la sortie de l'analyseur en mode débogage (pour les experts uniquement, en
fonction des options de compilation). Voir aussi PYTHONDEBUG.

-E
Ignore toutes les variables d'environnement PYTHON* qui pourraient être définies.
Par exemple, PYTHONPATH et PYTHONHOME.
-i
Quand un script est passé comme premier argument ou que l'option -c est utilisée,
entre en mode interactif après avoir exécuté le script ou la commande, même
lorsque sys.stdin ne semble pas être un terminal. Le fichier PYTHONSTARTUP n'est
pas lu.

Cela peut être utile pour examiner les variables globales ou une trace de la pile
lorsque le script lève une exception. Voir aussi PYTHONINSPECT.

-I
Lance Python en mode isolé. Cela implique aussi -E et -s. En mode
isolé, sys.path ne contient ni le répertoire du script ni le répertoire site-packages de
l'utilisateur. Toutes les variables d'environnement PYTHON* sont aussi ignorées.
Davantage de restrictions peuvent être imposées pour éviter que l'utilisateur n'injecte
du code malicieux.

Nouveau dans la version 3.4.

-O
Enlève les instructions assert et tout le code qui dépend de la valeur de __debug__.
Ajoute .opt-1 au nom de fichier du code intermédiaire (bytecode), avant
l'extension .pyc (voir la PEP 488). Voir aussi PYTHONOPTIMIZE.

Modifié dans la version 3.5: modifie les noms de fichiers .pyc suivant la PEP 488.

-OO
Agit comme -O et ignore aussi les docstrings. Ajoute .opt-2 au nom de fichier du
code intermédiaire (bytecode), avant l'extension .pyc (voir la PEP 488).

Modifié dans la version 3.5: modifie les noms de fichiers .pyc suivant la PEP 488.

-q
N'affiche pas le copyright et la version, même en mode interactif.

Nouveau dans la version 3.2.

-R
Active l'imprévisibilité du hachage. Cette option ne produit un effet que si la variable
d'environnement PYTHONHASHSEED est mise à 0, puisque l'imprévisibilité du hachage
est activée par défaut.
Sur les versions précédentes de Python, cette option activait l'imprévisibilité des
empreintes de manière à ce que les __hash__() de chaînes, bytes
et datetime soient "salés" avec une valeur aléatoire non prévisible. Bien que ce sel
soit constant durant le déroulement d'un processus Python, il n'est pas prévisible
pour des invocations répétées de code Python.

L'imprévisibilité des empreintes a pour objectif de se protéger contre les dénis de


service qui utiliseraient des valeurs d'entrée judicieusement choisies afin de forcer la
construction des dictionnaires dans le pire cas, c'est-à-dire avec une complexité en
O(n2). Voir http://www.ocert.org/advisories/ocert-2011-003.html pour obtenir les
détails.

PYTHONHASHSEED vous permet de définir vous-même la valeur du sel pour


l'algorithme de calcul des empreintes.

Modifié dans la version 3.7: cette option n'est plus ignorée.

Nouveau dans la version 3.2.3.

-s
N'ajoute pas le répertoire utilisateur site-packages à sys.path.

Voir aussi
 

PEP 370 — Répertoire site-packages propre à l'utilisateur


-S
Désactive l’importation du module site et les modifications locales
de sys.path qu’il implique. Désactive aussi ces manipulations si site est importé
explicitement plus tard (appelez site.main() si vous voulez les déclencher).

-u
Force les flux de sortie et d'erreur standards à ne pas utiliser de tampon. Cette option
n'a pas d'effet sur le flux d'entrée standard.

Voir aussi PYTHONUNBUFFERED.

Modifié dans la version 3.7: la couche texte des flux de sortie et d'erreur standards
n'utilise maintenant plus de tampon.

-v
Affiche un message chaque fois qu'un module est initialisé, montrant l'emplacement
(nom du fichier ou module natif) à partir duquel il est chargé. Lorsque l'option est
doublée (-vv), affiche un message pour chaque fichier vérifié lors de la recherche du
module. Fournit aussi des informations sur le nettoyage des modules à la fin. Voir
aussi PYTHONVERBOSE.

-W arg
Contrôle des avertissements. Le mécanisme d'avertissement de Python, par défaut,
affiche les messages d'avertissement sur sys.stderr. Un message d'avertissement
type est de la forme suivante :

file:line: category: message

Par défaut, chaque avertissement est affiché une seule fois pour chaque ligne de
source où il se trouve. Cette option définit à quelle fréquence afficher ces
avertissements.

L'option -W peut être répétée ; lorsqu'un avertissement correspond à plus d'une


option, l'action associée à la dernière correspondance est effectuée. Les options -
W invalides sont ignorées (cependant, un message d'avertissement est affiché sur les
options invalides au moment où le premier avertissement est généré).

Les avertissements peuvent aussi être contrôlés en utilisant la variable


d'environnement PYTHONWARNINGS et depuis un programme Python en utilisant le
module warnings.

Les configurations les plus simples forcent l'application de l'action à tous les
avertissements émis par un processus (même ceux qui auraient été ignorés par
défaut) :

-Wdefault # Warn once per call location


-Werror # Convert to exceptions
-Walways # Warn every time
-Wmodule # Warn once per calling module
-Wonce # Warn once per Python process
-Wignore # Never warn

Les noms des actions peuvent être abrégés à votre convenance (par exemple. -
Wi, -Wd, -Wa, -We), l'interpréteur fait la résolution vers le nom adéquat.

Voir Le filtre des avertissements et Rédaction de filtres d'avertissement pour plus de


détails.
-x
Saute la première ligne du code source, autorisant ainsi les directives de type #!
cmd non conformes au standard Unix. L'objectif est de proposer une astuce
spécifique pour le DOS.

-X
Réservée pour les options spécifiques aux différentes implémentations. CPython
reconnaît actuellement les valeurs suivantes :

 -X faulthandler pour activer faulthandler ;
 -X showrefcount pour afficher le compteur des références et le nombre de
blocs mémoire utilisés lorsque le programme se termine ou après chaque entrée de
l'interpréteur interactif. Ceci ne fonctionne que sur les versions compilées en mode
débogage.
 -X tracemalloc pour lancer le suivi des allocations mémoire par Python en
utilisant le module tracemalloc. Par défaut, seul l'appel (la frame en anglais) le
plus récent est stocké dans la trace de la pile d'appels. Utilisez -
X tracemalloc=NFRAME pour lancer le suivi avec une limite des traces
à NFRAME appels. Voir tracemalloc.start() pour plus d'informations.
 -X showalloccount pour afficher à la fin de l'exécution du programme le
total des objets alloués pour chaque type. Ceci ne fonctionne que si Python a été
compilé avec l'option COUNT_ALLOCS.
 -X importtime affiche le temps mis pour chaque importation. Le temps total
par module est affiché (y compris le temps pris par les importations imbriquées) ainsi
que le temps propre du module (c-à-d sans les importations imbriquées). Notez que
l'affichage peut être perturbé dans une application avec de multiples fils d'exécution.
L'utilisation classique est python3 -X importtime -c 'import asyncio'. Voir
aussi PYTHONPROFILEIMPORTTIME.
 -X dev: active le "mode développeur" de CPython, injectant des vérifications
à l'exécution qui ne sont pas actives par défaut. Ce n'est pas plus verbeux que le
mode par défaut si le code est correct : les avertissements supplémentaires ne sont
émis que quand un problème est détecté. Effets du mode développeur :

o ajoute le filtre default pour les avertissements, comme l'option -


W default.
o Installe des points d'entrée (hook en anglais) pour le débogage dans
les allocateurs de mémoire : voir la fonction C PyMem_SetupDebugHooks().
o Active le module faulthandler pour décharger la pile d'appels de
Python en cas de crash.
o Active le mode de débogage d'asyncio.
o Set the dev_mode attribute of sys.flags to True.
 -X utf8 active le mode UTF-8 pour les interfaces avec le système
d'exploitation, prenant le dessus sur le mode par défaut qui s'appuie sur la
configuration régionale. -X utf8=0 désactive explicitement le mode UTF-8 (même
s'il avait du s'activer automatiquement). Voir PYTHONUTF8 pour plus de détails.

Il est aussi possible de passer des valeurs arbitraires et de les récupérer par le
dictionnaire sys._xoptions.

Modifié dans la version 3.2: l'option -X a été ajoutée.

Nouveau dans la version 3.3: option -X faulthandler.

Nouveau dans la version 3.4: options -X showrefcount et -X tracemalloc .

Nouveau dans la version 3.6: option -X showalloccount.

Nouveau dans la version 3.7: les options -X importtime, -X dev et -X utf8.

1.1.4. Options à ne pas utiliser


-J
Utilisation réservée à Jython.

1.2. Variables d'environnement
Les variables d'environnement suivantes modifient le comportement de Python. Elles
sont analysées avant les options de la ligne de commande, autres que -E ou -I. Il est
d'usage que les options de la ligne de commande prennent le pas sur les variables
d'environnement en cas de conflit.

PYTHONHOME
Modifie l'emplacement des bibliothèques standards de Python. Par défaut, les
bibliothèques sont recherchées
dans préfixe/lib/pythonversion et préfixe_exec/lib/pythonversion où p
réfixe et préfixe_exec sont des répertoires qui dépendent de l'installation (leur
valeur par défaut étant /usr/local).

Quand PYTHONHOME est défini à un simple répertoire, sa valeur remplace à la


fois préfixe et préfixe_exec. Pour spécifier des valeurs différentes à ces
variables, définissez PYTHONHOME à préfixe:préfixe_exec.

PYTHONPATH
Augmente le chemin de recherche par défaut des fichiers de modules. Le format est
le même que pour PATH du shell : un ou plusieurs chemins de répertoires séparés
par os.pathsep (par exemple, le caractère deux-points sous Unix et point-virgule
sous Windows). Les répertoires qui n'existent pas sont ignorés silencieusement.

En plus des répertoires normaux, des entrées individuelles de PYTHONPATH peuvent


faire référence à des fichiers zip contenant des modules en pur Python (soit sous
forme de code source, soit sous forme compilée). Les modules d'extensions ne
peuvent pas être importés à partir de fichiers zip.

Le chemin de recherche par défaut dépend de l'installation mais commence


généralement par préfixe/lib/pythonversion (voir PYTHONHOME ci-dessus). Il
est toujours ajouté à PYTHONPATH.

Comme indiqué ci-dessus dans Options de l'interface, un répertoire supplémentaire


est inséré dans le chemin de recherche devant PYTHONPATH. Le chemin de
recherche peut être manipulé depuis un programme Python avec la
variable sys.path.

PYTHONSTARTUP
S'il s'agit d'un nom de fichier accessible en lecture, les commandes Python de ce
fichier sont exécutées avant que la première invite ne soit affichée en mode interactif.
Le fichier est exécuté dans le même espace de nommage que les commandes
interactives, de manière à ce que les objets définis ou importés puissent être utilisés
sans qualificatif dans la session interactive. Vous pouvez aussi changer les
invites sys.ps1 et sys.ps2 ainsi que le point d'entrée (hook en
anglais) sys.__interactivehook__ dans ce fichier.

PYTHONOPTIMIZE
Si elle est définie à une chaîne non vide, c'est équivalent à spécifier l'option -O. Si
elle est définie à un entier, c'est équivalent à spécifier l'option -O plusieurs fois.

PYTHONBREAKPOINT
Si elle est définie, elle fait référence à un appelable en utilisant la notation des
chemins délimités par des points. Le module contenant l'appelable est importé et
l'appelable est alors lancé par l'implémentation par défaut
de sys.breakpointhook(), elle-même étant appelée par la fonction
native breakpoint(). Si elle n'est pas définie ou définie par une chaîne vide, elle
vaut la même chose que pdb.set_trace. La définir à la chaîne "0" entraine que
l'implémentation par défaut de sys.breakpointhook() ne fait rien et s'interrompt
immédiatement.
Nouveau dans la version 3.7.

PYTHONDEBUG
Si elle est définie à une chaîne non vide, c'est équivalent à spécifier l'option -d. Si
elle est définie à un entier, c'est équivalent à spécifier l'option -d plusieurs fois.

PYTHONINSPECT
Si elle est définie à une chaîne non vide, c'est équivalent à spécifier l'option -i.

Cette variable peut aussi être modifiée par du code Python en


utilisant os.environ pour forcer le mode introspectif à la fin du programme.

PYTHONUNBUFFERED
Si elle est définie à une chaîne non vide, c'est équivalent à spécifier l'option -u.

PYTHONVERBOSE
Si elle est définie à une chaîne non vide, c'est équivalent à spécifier l'option -v. Si
elle est définie à un entier, c'est équivalent à spécifier l'option -v plusieurs fois.

PYTHONCASEOK
Si elle est définie, Python ignore la casse dans les instructions import. Ceci ne
fonctionne que sous Windows et OS X.

PYTHONDONTWRITEBYTECODE
Si elle est définie et n'est pas une chaîne vide, Python n'écrit pas de fichier .pyc à
l'importation des modules sources. C'est équivalent à spécifier l'option -B.

PYTHONHASHSEED
Si cette variable n'est pas définie ou définie à random, une valeur aléatoire est
utilisée pour saler les empreintes des objets de type chaine, bytes et datetime.

Si PYTHONHASHSEED est définie à une valeur entière, elle est utilisée comme valeur
de salage pour générer les empreintes des types utilisant l'imprévisibilité du
hachage.

L'objectif est d'avoir des empreintes reproductibles, pour des tests de l'interpréteur
lui-même ou pour qu'un groupe de processus Python puisse partager des
empreintes.
Le nombre entier doit être écrit en base 10 et être compris entre 0 et 4 294 967 295.
Spécifier la valeur 0 désactive l'imprévisibilité des empreintes.

Nouveau dans la version 3.2.3.

PYTHONIOENCODING
Si la variable est définie sous la
forme nom_encodage:gestionnaire_erreur avant le lancement de l'interpréteur,
cela prend le pas sur l'encodage utilisé pour l'entrée standard, la sortie standard ou
la sortie d'erreur. nom_encodage et :gestionnaire_erreur sont facultatifs tous
les deux et possèdent la même signification que dans str.encode().

Pour la sortie d'erreur, la partie :gestionnaire_erreur est ignorée : le


gestionnaire est toujours 'backslashreplace'.

Modifié dans la version 3.4: la partie nom_encodage est maintenant optionnelle.

Modifié dans la version 3.6: sous Windows, l'encodage spécifié par cette variable est
ignoré pour le tampon des consoles interactives à moins
que PYTHONLEGACYWINDOWSSTDIO ne soit aussi spécifié. Les fichiers et tubes
(pipes en anglais) redirigés vers les flux standards ne sont pas concernés.

PYTHONNOUSERSITE
Si elle est définie, Python n'ajoute pas le répertoire site-
packages propre à l'utilisateur à sys.path.

Voir aussi
 

PEP 370 — Répertoire site-packages propre à l'utilisateur


PYTHONUSERBASE
Définit le répertoire base utilisateur. Celui-ci est utilisé pour déterminer le
chemin du répertoire site-packages propre à l'utilisateur et
des schémas d'installation de Distutils pour python setup.py install --user.

Voir aussi

PEP 370 — Répertoire site-packages propre à l'utilisateur

PYTHONEXECUTABLE
Si cette variable d'environnement est définie, sys.argv[0] est définie à cette valeur
au lieu de la valeur fournie par l'exécutable. Ne fonctionne que sur Mac OS X.

PYTHONWARNINGS
C'est équivalent à spécifier l'option -W. Si la valeur est une chaîne séparée par des
virgules, c'est équivalent à spécifier l'option -W plusieurs fois. Dans ce cas, les filtres
spécifiés en derniers prennent le pas sur ceux qui les précèdent dans la liste.

Les configurations les plus simples forcent l'application de l'action à tous les
avertissements émis par un processus (même ceux qui auraient été ignorés par
défaut) :

PYTHONWARNINGS=default # Warn once per call location


PYTHONWARNINGS=error # Convert to exceptions
PYTHONWARNINGS=always # Warn every time
PYTHONWARNINGS=module # Warn once per calling module
PYTHONWARNINGS=once # Warn once per Python process
PYTHONWARNINGS=ignore # Never warn

Voir Le filtre des avertissements et Rédaction de filtres d'avertissement pour plus de


détails.

PYTHONFAULTHANDLER
Si elle est définie à une chaîne non vide, faulthandler.enable() est appelée au
démarrage : ceci installe un gestionnaire pour les
signaux SIGSEGV, SIGFPE, SIGABRT, SIGBUS et SIGILL afin de générer une trace
de la pile d'appels. C'est équivalent à spécifier l'option -X faulthandler.

Nouveau dans la version 3.3.

PYTHONTRACEMALLOC
Si elle est définie à une chaîne non vide, lance le suivi des allocations mémoire par
Python en utilisant le module tracemalloc. La valeur de la variable définit le
nombre maximum d'appels (les frames en anglais) stockés dans la trace de pile
d'appels. Par exemple, PYTHONTRACEMALLOC=1 ne stocke que l'appel le plus récent.
Voir tracemalloc.start() pour davantage d'informations.

Nouveau dans la version 3.4.

PYTHONPROFILEIMPORTTIME
Si elle est définie et n'est pas une chaîne vide, Python affiche le temps pris par les
importations. C'est exactement équivalent à donner -X importtime en ligne de
commande.

Nouveau dans la version 3.7.

PYTHONASYNCIODEBUG
Si elle est définie à une chaîne non vide, active le mode debogage du
module asyncio.

Nouveau dans la version 3.4.

PYTHONMALLOC
Définit l'allocateur mémoire de Python ou installe des points d'entrée (hooks en
anglais) de débogage.

Définit la famille d'allocateurs mémoire utilisés par Python :

 default: utilise les allocateurs de mémoire par défaut.


 malloc : utilise la fonction malloc() de la bibliothèque C standard pour tous
les domaines (PYMEM_DOMAIN_RAW, PYMEM_DOMAIN_MEM, PYMEM_DOMAIN_OBJ).
 pymalloc : utilise l’allocateur pymalloc pour les
domaines PYMEM_DOMAIN_MEM ainsi que PYMEM_DOMAIN_OBJ et utilise la
fonction malloc() pour le domaine PYMEM_DOMAIN_RAW.

Installe des points d'entrée de débogage :

 debug : installe des points d'entrée de débogage pour l'allocateur de mémoire


par défaut.
 malloc_debug: same as malloc but also install debug hooks.
 pymalloc_debug: same as pymalloc but also install debug hooks.

Reportez-vous au chapitre default-memory-allocators et à la
fonction PyMem_SetupDebugHooks() (configure des points d'entrée de débogage
sur les allocateurs de mémoire de Python).

Modifié dans la version 3.7: l'allocateur default a été ajouté.

Nouveau dans la version 3.6.

PYTHONMALLOCSTATS
Si elle est définie à une chaîne non vide, Python affiche des statistiques relatives à
l’allocateur mémoire pymalloc chaque fois qu'un objet est créé par ce gestionnaire,
ainsi qu'à la fin de l'exécution du programme.

Cette variable est ignorée si la variable d'environnement PYTHONMALLOC est utilisée


pour forcer l'allocateur malloc() de la bibliothèque C standard ou si Python est
configuré sans le support de pymalloc.

Modifié dans la version 3.6: cette variable peut maintenant être utilisée avec Python
compilé en mode release. Elle n'a pas d'effet si elle est définie à une chaine vide.

PYTHONLEGACYWINDOWSFSENCODING
Si elle est définie et n’est pas une chaîne vide, l'encodage par défaut respectivement
du système de fichiers et des erreurs reviennent à leur valeur pré-3.6,
respectivement 'mbcs' et 'replace'. Sinon, les nouvelles valeurs par
défaut "UTF-8" et "surrogatepass" sont utilisées.

Vous pouvez aussi activer ceci à l'exécution


avec sys._enablelegacywindowsfsencoding().

Disponibilité : Windows.

Nouveau dans la version 3.6: voir la PEP 529 pour plus d'informations.

PYTHONLEGACYWINDOWSSTDIO
Si elle est définie et n’est pas une chaîne vide, n'utilise pas les lecteur et écrivain de
la nouvelle console. Cela signifie que les caractères Unicode sont encodés avec
l'encodage de la console active plutôt qu'en UTF-8.

Cette variable est ignorée si les flux standards sont redirigés (vers des fichiers ou
des tubes) plutôt que pointant vers des mémoires tampons de console.

Disponibilité : Windows.

Nouveau dans la version 3.6.

PYTHONCOERCECLOCALE
Si elle est définie à la valeur 0, l'application en ligne de commande principale Python
ne prend pas en compte les configurations régionales C et POSIX à base ASCII,
mais bascule sur une alternative basée sur l'UTF-8 qui doit posséder plus de
possibilités.
Si cette variable n'est pas définie (ou est définie à une valeur autre que 0), que la
variable d'environnement de configuration régionale LC_ALL est également non
définie et que la configuration régionale indiquée dans la catégorie LC_TYPE est soit
la région par défaut C, soit la région POSIX qui demande explicitement de l'ASCII,
alors l'interpréteur en ligne de commande Python essaie de configurer les
paramètres régionaux pour la catégorie LC_TYPE dans l'ordre suivant avant de
charger l'exécutable de l'interpréteur :

 C.UTF-8
 C.utf8
 UTF-8

Si la définition d'une des configurations régionales fonctionne, la variable


d'environnement LC_TYPE est aussi définie ainsi dans l'environnement du processus
avant que l'exécutable Python ne soit initialisé. Ceci assure que, en plus d'être vue
par l'interpréteur lui-même et tous les autres composants prenant en charge la
configuration régionale dans le même processus (telle que la bibliothèque
GNU readline), la configuration mise à jour est aussi valable pour les sous-
processus (indépendamment du fait qu'ils utilisent un interpréteur Python ou non)
ainsi que pour les opérations qui font appel à l'environnement (qui utiliseraient sinon
la configuration régionale C courante, tel que c'est le cas pour la propre fonction
Python locale.getdefaultlocale()).

La configuration d'une de ces variables régionales (soit explicitement, soit via le


mécanisme décrit ci-dessus) active automatiquement surrogateescape pour
la gestion des erreurs de sys.stdin et sys.stdout (sys.stderr continue
d'utiliser backslashreplace comme pour toute autre configuration régionale). Ce
comportement relatif à la gestion des flux standards peut être surchargé, comme
d'habitude, par PYTHONIOENCODING.

À fin de débogage, définir PYTHONCOERCECLOCALE=warn indique à Python d'émettre


les messages d'avertissement sur stderr si la configuration régionale est activée,
ou si une configuration régionale qui aurait activé est toujours active quand
l'interpréteur Python est initialisé.

Notez également que même si la contrainte sur la configuration régionale est


désactivée, ou si elle ne trouve pas une configuration satisfaisante et
échoue, PYTHONUTF8 s'active par défaut avec une configuration régionale par défaut
à base ASCII. Ces fonctionnalités doivent être désactivées pour forcer l'interpréteur à
utiliser ASCII en lieu et place de UTF-8 pour les interfaces avec le système.

Disponibilité : systèmes de type UNIX.


Nouveau dans la version 3.7: voir la PEP 538 pour plus d'informations.

PYTHONDEVMODE
Si cette variable d'environnement est définie et non vide, active le "mode
développeur" de CPython. Voir l'option -X dev.

Nouveau dans la version 3.7.

PYTHONUTF8
Si elle vaut 1, active le mode UTF-8 pour l'interpréteur, où UTF-8 est utilisé pour
encoder le texte en interface avec le système, quelle que soit la configuration
régionale en vigueur.

Ce qui signifie que :

 sys.getfilesystemencoding() renvoie 'UTF-8' (l'encodage défini par la


configuration régionale est ignoré).
 locale.getpreferredencoding() renvoie 'UTF-8' (l'encodage défini par
la configuration régionale est ignoré et le paramètre do_setlocale de la fonction
n'a aucun effet).
 sys.stdin, sys.stdout et sys.stderr utilisent tous l'UTF-8 pour
l'encodage du texte, avec le gestionnaire d'erreurs surrogateescape activé
pour sys.stdin et sys.stdout (sys.stderr continue
d'utiliser backslashreplace comme pour le mode par défaut où il prend en compte
la configuration régionale).

En raison des changements apportés à ces API de bas-niveau, les API de haut-
niveau ont un comportement par défaut différent :

 les arguments en ligne de commande, les variables d'environnement et les


noms de fichiers sont décodés en texte en utilisant l'UTF-8.
 os.fsdecode() et os.fsencode() utilisent l'encodage UTF-8.
 open(), io.open() et codecs.open() utilisent l'encodage UTF-8 par
défaut. Cependant, elles utilisent le gestionnaire d'erreurs "strict" par défaut, de
manière à ce qu'ouvrir un fichier binaire en mode texte lève une exception plutôt que
de produire de la donnée sans aucun sens.

Notez que la configuration des flux standards en mode UTF-8 peut être surchargée
par PYTHONIOENCODING (de la même manière qu'elles peuvent l'être dans le mode
par défaut qui est configuré pour la région locale).
Si elle vaut 0, l'interpréteur fonctionne dans le mode configuré pour la région locale
(mode par défaut).

Définir une valeur autre (non vide) entraine une erreur pendant l'initialisation de
l'interpréteur.

Si cette variable d'environnement n'est pas définie, l'interpréteur se configure pour


utiliser la configuration régionale en cours, à moins que cette configuration régionale
ne soit identifiée comme ASCII (comme décrit pour PYTHONCOERCECLOCALE), et que
soit la contrainte est désactivée, soit elle échoue. Dans cette configuration régionale,
l'interpréteur active par défaut le mode UTF-8 à moins que vous n'indiquiez
explicitement de ne pas le faire.

Également disponible en tant qu'option -X utf8.

Nouveau dans la version 3.7: voir la PEP 540 pour plus d'informations.

1.2.1. Variables en mode débogage


Définir ces variables n'a d'effet que si Python a été compilé en mode débogage,
c'est-à-dire que l'option de compilation --with-pydebug a été spécifiée.

PYTHONTHREADDEBUG
Si elle est définie, Python affiche des informations de débogage relatives aux
différents fils d'exécution.

PYTHONDUMPREFS
Si elle est définie, Python affiche (de manière brute) les objets et les compteurs de
références toujours existant après la fermeture de l'interpréteur.

2. Utilisation de Python sur les


plateformes Unix
2.1. Récupérer et installer la dernière version de
Python
2.1.1. Sur Linux
Python est pré-installé sur la plupart des distributions Linux, et est disponible en
paquet sur toutes les autres. Cependant, il y a certaines fonctionnalités que vous
voudrez utiliser qui ne seront pas disponibles sur le paquet de votre distribution.
Vous pouvez facilement compiler la dernière version de Python depuis les sources.

Dans le cas où Python n'est pas pré-installé et n'est pas dans les dépôts non plus,
vous pouvez facilement faire les paquets pour votre propre distribution. Jetez un œil
à ces liens :

Voir aussi
https://www.debian.org/doc/manuals/maint-guide/first.fr.html

pour les utilisateurs de Debian


https://en.opensuse.org/Portal:Packaging

pour les utilisateurs d'OpenSuse


https://docs-old.fedoraproject.org/en-
US/Fedora_Draft_Documentation/0.1/html/RPM_Guide/ch-creating-rpms.html

pour les utilisateurs de Fedora


http://www.slackbook.org/html/package-management-making-packages.html

pour les utilisateurs de Slackware

2.1.2. Sur FreeBSD et OpenBSD


 Utilisateurs de FreeBSD, pour installer le paquet, utilisez :

 pkg install python3


 Utilisateurs d'OpenBSD, pour installer le paquet, utilisez :

 pkg_add -r python

 pkg_add
ftp://ftp.openbsd.org/pub/OpenBSD/4.2/packages/<insert your
architecture here>/python-<version>.tgz

Par exemple les utilisateurs d'i386 récupèrent la version 2.5.1 de Python en faisant :

pkg_add
ftp://ftp.openbsd.org/pub/OpenBSD/4.2/packages/i386/python-
2.5.1p2.tgz
2.1.3. Sur OpenSolaris
Vous pouvez récupérer Python depuis OpenCSW. Différentes versions de Python
sont disponibles et peuvent être installées. Exemple : pkgutil -i python27.

2.2. Compiler Python
Si vous voulez compiler CPython vous-même, la première chose à faire est de
récupérer le code source. Vous pouvez télécharger la dernière version ou faire
un clone. (Si vous voulez contribuer à des correctifs, il vous faut un clone.)

Le processus de compilation est le suivant :

./configure
make
make install

Les options de configuration et mises en garde pour certaines plateformes Unix


spécifiques sont largement documentées dans le fichier README.rst à la racine du
dossier des sources Python.

Avertissement

make install peut écraser ou cacher le binaire python3. make altinstall est donc


recommandé à la place de make install puisqu'il installe
seulement exec_prefix/bin/pythonversion.

2.3. Fichiers et chemins liés à Python


Ceux-ci sont sujets à des différences en fonction des conventions locales
d'installation ; prefix (${prefix}) et exec_prefix (${exec_prefix}) sont dépendants de
l’installation et doivent être interprétés comme pour des logiciels GNU ; ils peuvent
être égaux.

Par exemple, sur la plupart des systèmes Linux, leur valeur par défaut est /usr.

Fichier/dossier Signification

Emplacement recommandé de
exec_prefix/bin/python3
l'interpréteur.
Fichier/dossier Signification

prefix/lib/pythonversion, exec_prefix/lib/python Emplacements recommandés des dossiers


version contenant les modules standards.

Emplacements recommandés des dossiers


prefix/include/pythonversion, exec_prefix/inclu contenant les entêtes nécessaires au
de/pythonversion développement d'extensions Python et à
l'intégration de l'interpréteur.

2.4. Divers
Pour utiliser facilement des scripts Python sur Unix, vous devez les rendre
exécutables, par exemple avec

$ chmod +x script

et mettre un shebang approprié en haut du script. Un bon choix est généralement

#!/usr/bin/env python3

qui cherche l’interpréteur Python dans le PATH complet. Cependant, certains


systèmes Unix peuvent ne pas avoir la commande env, donc vous devrez
littéralement écrire /usr/bin/python3 en tant que chemin d’interpréteur.

Pour utiliser des commandes shell dans vos scripts Python, regardez le


module subprocess.

3. Utilisation de Python sur Windows


Ce document a pour but de donner une vue d'ensemble des comportements
spécifiques à Windows dont vous devriez être au courant si vous utilisez Python sur
Microsoft Windows.

Contrairement à la plupart des systèmes Unix, Windows n'inclut pas d'installation de


Python par défaut. Pour rendre Python disponible, l’équipe CPython a compilé des
installateurs (paquets MSI) pour chaque release depuis plusieurs années. Ces
installateurs sont principalement destinés à une installation par utilisateur de Python,
avec l’interpréteur et la bibliothèque standard utilisés par un seul utilisateur. Cet
installateur peut aussi installer Python pour tous les utilisateurs sur une seule
machine et un fichier ZIP séparé est disponible pour intégrer Python dans d'autres
applications.

Comme spécifié dans la PEP 11, une release Python ne gère qu'une plateforme


Windows alors que Microsoft considère la plateforme sous support étendu. Ce qui
veut dire que Python 3.7 supporte Windows Vista et plus. Si vous avez besoin de
compatibilité Windows XP, vous devez utiliser Python 3.4.

Il existe un certain nombre d'installateurs différents disponibles pour Windows,


chacun avec certains avantages et inconvénients.

L'installateur complet contient tous les composants et est la meilleure option pour les
développeurs utilisant Python pour tout type de projet.

Le paquet Microsoft Store est une simple installation de Python qui convient à


l'exécution de scripts, de paquets et à l’utilisation d’IDLE ou d'autres environnements
de développement. Il nécessite Windows 10, mais peut être installé en toute sécurité
sans endommager d'autres programmes. Il fournit également de nombreuses
commandes pratiques pour lancer Python et ses outils.

Les paquets nuget.org sont des installations légères destinées aux systèmes


d'intégration continue. Ils peuvent être utilisés pour créer des packages Python ou
exécuter des scripts, mais ne sont pas modifiables et n'ont pas d'outils d'interface
utilisateur.

Le paquet intégrable est un paquet minimal de Python approprié pour l'intégration


dans une plus grande application.

3.1. L'installateur complet
3.1.1. Étapes d'installation
Quatre installateurs Python 3.7 sont disponibles au téléchargement — deux de
chaque pour les versions 32-bit et 64-bit de l'interpréteur. L'installateur web est
léger, et téléchargera automatiquement les composants nécessaires. L'installateur
hors-ligne inclut les composants nécessaires pour une installation par défaut et n'a
besoin d'une connexion internet que pour des fonctionnalités optionnelles.
Voir Installation sans téléchargement pour d'autres moyens d’éviter des
téléchargements durant l'installation.

Après avoir lancé l'installateur, deux options s'affichent :


Si vous sélectionnez "Installer Maintenant" (Install Now):

 Vous n'aurez pas besoin d'avoir les droits d'administrateur (sauf si une mise à


jour de la bibliothèque d'exécution C est nécessaire ou si vous installez le Lanceur
Python pour Windows pour tous les utilisateurs)
 Python sera installé dans votre répertoire utilisateur
 Le Lanceur Python pour Windows sera installé suivant l'option en bas de la
première page
 La bibliothèque standard, la suite de tests, le lanceur et pip seront installés
 Si l'option est cochée, le dossier d'installation sera ajouté à votre PATH
 Les raccourcis ne seront visibles que pour l'utilisateur actuel

Sélectionner "Personnaliser l'installation" ( Customize installation) vous


permettra de sélectionner les fonctionnalités à installer, le chemin d'installation et
d'autres options ou des options post-installation. Pour installer des binaires ou
symboles de débogage, vous devrez utiliser cette option.

Pour effectuer une installation pour tous les utilisateurs, vous devez sélectionner
"Personnaliser l'installation". Dans ce cas :

 Vous pouvez avoir à donner une approbation ou des identifiants


administrateur
 Python sera installé dans le dossier Program Files
 Le Lanceur Python pour Windows sera installé dans le dossier Windows
 Des fonctionnalités optionnelles peuvent être sélectionnées durant
l'installation
 La bibliothèque standard peut être pré-compilée en code intermédiaire
(bytecode en anglais)
 Si sélectionné, le chemin d'installation sera ajouté au PATH système
 Les raccourcis sont disponibles pour tous les utilisateurs

3.1.2. Suppression de la limitation MAX_PATH
Historiquement les chemins sous Windows étaient limités 260 caractères. Cela
impliquait que les chemins plus longs n'étaient pas résolus, et seraient une cause
d'erreurs.

Dans les dernières versions de Windows, cette limitation peut être étendue à
approximativement 32.000 caractères. Votre administrateur devra activer la stratégie
de groupe "Enable Win32 long paths" ou mettre la valeur du
registre HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\FileSys
tem@LongPathsEnabled à 1.

This allows the open() function, the os module and most other path functionality to


accept and return paths longer than 260 characters.

Après avoir changé l'option si-dessus, aucune configuration supplémentaire n'est


requise.

Modifié dans la version 3.6: Gestion des chemins longs.

3.1.3. Installation sans l'interface utilisateur


Toutes les options disponibles dans l'installateur graphique peuvent aussi être
spécifiées dans l'invite de commande, permettant à des installateurs scriptés de
répliquer une installation sur plusieurs machines sans interaction humaine. Ces
options peuvent aussi être ajoutées sans enlever l'interface graphique pour changer
les valeurs par défauts.

Pour complétement cacher l'interface de l'installateur et installer Python


silencieusement, passez l'option /quiet. Pour sauter les interactions utilisateur mais
afficher la progression et les erreurs, passez l'option /passive.
L'option /uninstall peut être passée pour immédiatement démarrer la suppression
de Python -- Aucune confirmation ne sera demandée.
Toutes les autres options sont passées sous la forme name=value, ou value est
normalement soit 0 pour désactiver une fonctionnalité, soit 1 pour activer une
fonctionnalité, soit un chemin. Ci-dessous la liste complète des options.

Nom Description Valeur par défaut

Effectue une installation pour


InstallAllUsers 0
tous les utilisateurs.

Sélection basée sur


TargetDir Le dossier d'installation
InstallAllUsers

Le dossier d'installation par %ProgramFiles%\Python X


DefaultAllUsersTa
défaut pour les installations pour .Y ou %ProgramFiles(x86)%
rgetDir
tous les utilisateurs \Python X.Y

%LocalAppData
%\Programs\PythonXY ou %L
Le dossier d'installation par
DefaultJustForMe ocalAppData
défaut pour des installations juste
TargetDir %\Programs\PythonXY-32 o
pour soi
u %LocalAppData
%\Programs\PythonXY-64

Le dossier d'installation
DefaultCustomTar
personnalisé par défaut affiché (vide)
getDir
par l'interface utilisateur

Crée les associations de fichiers si


AssociateFiles 1
le lanceur est aussi installé.
Compile tous les
CompileAll 0
fichiers .py en .pyc.

Ajoute les
PrependPath dossiers install et Scripts à  0
PATH et assigne .PY à PATHEXT

Crée des raccourcis pour


Shortcuts l'interpréteur, la documentation et 1
IDLE si installé.

Include_doc Installe le manuel Python 1

Include_debug Installe les binaires de débogage 0

Installe les fichiers d'en-tête et les


Include_dev 1
bibliothèques développeur
Nom Description Valeur par défaut
Installe python.exe et les
Include_exe 1
fichiers connexes

Installe le Lanceur Python pour


Include_launcher 1
Windows.

Installe le Lanceur Python pour


InstallLauncherAll
Windows pour tous les 1
Users
utilisateurs.

Installe la bibliothèque standard


Include_lib 1
et les modules d'extension

Include_pip Installe pip et setuptools 1

Installe les symboles de débogage


Include_symbols 0
(*.pdb)

Include_tcltk Installe Tcl/Tk et IDLE 1

Installe la suite de tests de la


Include_test 1
bibliothèque standard

Include_tools Installe les scripts utilitaires 1

Installe seulement le lanceur. Ceci


LauncherOnly écrasera la plupart des autres 0
options.

Désactive la plupart de l'interface


SimpleInstall 0
d'installation

Un message personnalisé à
SimpleInstallDescr afficher quand l'interface
(vide)
iption d'installation simplifiée est
utilisée.

Par exemple, pour installer silencieusement Python sur tout le système, vous
pourriez utilisez la commande suivante (depuis une invite de commande
administrateur) :

python-3.7.0.exe /quiet InstallAllUsers=1 PrependPath=1


Include_test=0
Pour permettre à l'utilisateur d'installer facilement une copie de Python sans la suite
de tests, vous pouvez proposer un raccourci avec la commande suivante. Cela
affichera une page initiale simplifiée et interdira la personnalisation :

python-3.7.0.exe InstallAllUsers=0 Include_launcher=0


Include_test=0
SimpleInstall=1 SimpleInstallDescription="Just for me, no
test suite."

(Notez qu'omettre le lanceur omet aussi les associations de fichiers, et n'est


recommandé que pour les installations par utilisateur quand il y a aussi une
installation complète sur le système qui a inclus de lanceur.)

Les options listées ci-dessus peuvent aussi être passées dans un fichier
nommé unattend.xml à côté de l'exécutable. Ce fichier spécifie une liste d'options
et de valeurs. Quand une valeur est donnée en tant qu'attribut, elle sera convertie en
nombre si possible. Les valeurs données en élément texte sont toujours laissées en
tant que chaînes de caractères. Ce fichier d'exemple propose les mêmes options que
l'exemple précédent :

<Options>
<Option Name="InstallAllUsers" Value="no" />
<Option Name="Include_launcher" Value="0" />
<Option Name="Include_test" Value="no" />
<Option Name="SimpleInstall" Value="yes" />
<Option Name="SimpleInstallDescription">Just for me, no test
suite</Option>
</Options>

3.1.4. Installation sans téléchargement


Comme certaines fonctionnalités de Python ne sont pas incluses dans l'installateur
initial, la sélection de certaines de ces fonctionnalités peut demander une connexion
Internet. Pour éviter ce besoin, tous les composants nécessaires peuvent être
téléchargés à la demande pour créer un installateur complet qui ne demandera plus
de connexion Internet indépendamment des options sélectionnées. Notez que ce
téléchargement peut être plus gros que nécessaire, mais lorsqu'un un grand nombre
d'installations doivent être faites, il est très utile d'avoir une copie locale.

Exécutez la commande suivante depuis l'invite de commande pour télécharger tous


les fichiers requis possibles. Rappelez-vous de remplacer python-3.7.0.exe par le
nom actuel de votre installateur, et pour créer des couches dans leurs propres
dossiers pour éviter les conflits entre fichiers du même nom.
python-3.7.0.exe /layout [optional target directory]

Vous pouvez aussi spécifier l'option /quiet pour masquer la progression.

3.1.5. Modification d'une installation


Une fois Python installé, vous pouvez ajouter ou supprimer des fonctionnalités
depuis l'outil Windows Programs and Features (Programmes et Fonctionnalités).
Sélectionnez la ligne Python et choisissez "Uninstall/Change" (Désinstaller/Modifier)
pour ouvrir l'installateur en mode maintenance.

"Modify" vous permet d'ajouter ou d'enlever des fonctionnalités en modifiant les


cases à cocher (les cases inchangées n'installeront ou ne supprimeront rien).
Certaines options ne peuvent pas être modifiées dans ce mode, comme le dossier
d'installation. Pour modifier ces options, vous devrez ré-installer Python entièrement.

"Repair" vérifiera tous les fichiers qui doivent être installés avec les paramètres
actuels le sont, et remplacera ceux qui ont étés supprimés ou modifiés.

"Uninstall" désinstallera Python entièrement, à l'exception du Lanceur Python pour


Windows qui à sa propre ligne dans Programs and Features.

3.2. Le paquet Microsoft Store


Nouveau dans la version 3.7.2.

Note

Le paquet Microsoft Store est actuellement considéré comme instable le temps que


ses interactions avec d'autres outils et d'autres copies de Python soient évaluées.
Bien que Python lui-même soit stable, cette méthode d'installation peut modifier son
comportement et ses capacités durant les versions de Python 3.7.

Le paquet Microsoft Store est un interpréteur Python facilement installable qui est


destiné principalement à une utilisation interactive, par exemple, par des étudiants.

Pour installer le paquet, assurez-vous d'avoir les dernières mises à jour de Windows
10 et de chercher dans l'application Microsoft Store “Python 3.7”. Assurez-vous que
l'application que vous sélectionnez est publiée par la Python Software Foundation et
installez-la.

Avertissement
Python sera toujours disponible gratuitement sur le Microsoft Store. Si vous êtes
invité à payer, vous n'avez pas sélectionné le bon paquet.

Après l'installation, Python peut être lancé depuis le menu Démarrer. Il est aussi
disponible à partir de n'importe quelle invite de commande ou session PowerShell en
entrant python. De plus, pip et IDLE peuvent être utilisés en entrant pip ou idle .
IDLE peut également être trouvé dans le menu Démarrer.

Les trois commandes sont également disponibles avec les suffixes de numéro de
version, par exemple, python3.exe et python3.x.exe ainsi
que python.exe (ou 3.x est la version spécifique que vous souhaitez lancer, tel
que 3.7).

Les environnements virtuels peuvent être créés avec python -m venv et activés et


utilisés normalement.

Si vous avez installé une autre version de Python et l'avez ajoutée à votre variable
d'environnement PATH, elle sera disponible en tant que python.exe plutôt que celle
de la boutique Microsoft. Pour accéder à la nouvelle installation,
utilisez python3.exe ou python3.x.exe.

Pour supprimer Python, depuis les paramètres Windows ouvrez Apps and


Features (Applications et Fonctionnalités), ou bien trouvez Python dans le menu
Démarrer et cliquez avec le bouton droit pour sélectionner désinstaller. La
désinstallation supprimera tous les paquets que vous avez installés directement dans
cette installation Python, mais ne supprimera aucun environnement virtuel

3.2.1. Problèmes connus
Actuellement, le lanceur py.exe ne peut pas être utilisé pour démarrer Python
lorsqu'il a été installé à partir de la boutique Microsoft.

En raison de restrictions sur les applications Microsoft Store, les scripts Python
peuvent ne pas avoir un accès en écriture complet aux emplacements partagés tels
que TEMP et le registre. Au lieu de cela, il écrira sur une copie privée. Si vos scripts
doivent modifier les emplacements partagés, vous devrez installer le programme
d'installation complet.

3.3. Les paquets nuget.org
Nouveau dans la version 3.5.2.
Le paquet nuget.org est un environnement Python de taille réduite destiné à être
utilisé sur des systèmes d'intégration et de génération continus qui n'ont pas Python
d'installé. Alors que nuget est “le gestionnaire de package pour .NET”, il fonctionne
également parfaitement bien pour les packages contenant des outils de build-time.

Visitez nuget.org pour les informations les plus à jour sur l'utilisation de nuget. Ce qui
suit est un résumé suffisant pour les développeurs Python.

L'outil de ligne de commande nuget.exe peut être téléchargé directement à partir


de https://aka.ms/nugetclidl, par exemple, à l'aide de curl ou de PowerShell.
Avec l'outil, la dernière version de Python pour les machines 64 bits ou 32 bits est
installée à l'aide de :

nuget.exe install python -ExcludeVersion -OutputDirectory .


nuget.exe install pythonx86 -ExcludeVersion -OutputDirectory .

Pour sélectionner une version particulière, ajoutez un -Version 3.x.y. Le


répertoire d'installation être modifié (de .), et le paquet sera installé dans un sous-
répertoire. Par défaut, le sous-répertoire est nommé comme le paquet, et sans
l'option -ExcludeVersion, ce nom inclura la version spécifique installée. À
l'intérieur du sous-répertoire se trouve un répertoire tools qui contient l'installation
Python :

# Without -ExcludeVersion
> .\python.3.5.2\tools\python.exe -V
Python 3.5.2

# With -ExcludeVersion
> .\python\tools\python.exe -V
Python 3.5.2

En général, les paquets nuget ne peuvent pas êtres mis à jour et les versions plus
récentes doivent être installées côte à côte et référencées à l'aide du chemin d'accès
complet. Vous pouvez également supprimer le répertoire du paquet manuellement et
l'installer à nouveau. De nombreux systèmes CI le feront automatiquement s'ils ne
conservent pas les fichiers entre les builds.

À côté du répertoire tools est un répertoire build\native. Il contient un fichier de


propriétés MSBuild python.props qui peut être utilisé dans un projet C++ pour
référencer l'installation de Python. L'inclusion des paramètres utilisera
automatiquement les en-têtes et les bibliothèques d'importation dans votre build.
Les pages d’information sur nuget.org sont www.nuget.org/packages/python pour la
version 64 Bits et www.nuget.org/packages/pythonx86 pour la version 32 Bits.

3.4. Le paquet intégrable


Nouveau dans la version 3.5.

La distribution embarquée est un fichier ZIP contenant un environnement Python


minimal. Il est destiné à agir dans le cadre d'une autre application, plutôt que d'être
directement accessible par les utilisateurs finaux.

Une fois extrait, la distribution intégrée est (presque) entièrement isolée du système
de l'utilisateur, y compris les variables d'environnement, les paramètres du registre
système et les paquets installés. La bibliothèque standard est incluse en tant que
fichiers pré-compilés et optimisés .pyc dans un fichier ZIP,
et python3.dll, python37.dll, python.exe et pythonw.exe sont tous
fournis. Tcl/Tk (y compris tous les dépendants, telles que IDLE), pip et la
documentation Python ne sont pas inclus.

Note

La distribution intégrée n'inclut pas le Microsoft C Runtime et il est de la


responsabilité de l'installateur d'application de le fournir. Le runtime peut avoir déjà
été installé sur le système d'un utilisateur précédemment ou automatiquement via
Windows Update, et peut être détecté en trouvant ucrtbase.dll dans le répertoire
système.

Les paquets tiers doivent être installés par le programme d'installation de l'application
parallèlement à la distribution embarquée. L'utilisation de pip pour gérer les
dépendances comme pour une installation Python régulière n'est pas prise en charge
avec cette distribution, mais il reste possible d'inclure et d'utiliser pip pour les mises à
jour automatiques. En général, les paquets tiers doivent être traités dans le cadre de
l'application (vendoring) afin que le développeur puisse assurer la compatibilité avec
les versions plus récentes avant de fournir des mises à jour aux utilisateurs.

Les deux cas d'utilisation recommandés pour cette distribution sont décrits ci-
dessous.
3.4.1. Application Python
Une application écrite en Python n'exige pas nécessairement que les utilisateurs
soient au courant de ce fait. La distribution embarquée peut être utilisée dans ce cas
pour inclure une version privée de Python dans un package d'installation. Selon la
façon dont il devrait être transparent (ou inversement, à quel point il doit paraître
professionnel), il y a deux options.

L'utilisation d'un exécutable spécialisé en tant que lanceur nécessite de la


programmation, mais fournit l'expérience la plus transparente pour les utilisateurs.
Avec un lanceur personnalisé, il n'y a pas d'indications évidentes que le programme
s'exécute sur Python : les icônes peuvent être personnalisées, les informations de la
société et de la version peuvent être spécifiées, et les associations de fichiers se
comportent correctement. Dans la plupart des cas, un lanceur personnalisé devrait
simplement pouvoir appeler Py_Main avec une ligne de commande codée en dur.

L'approche la plus simple consiste à fournir un fichier batch ou un raccourci généré


qui appelle directement le python.exe ou pythonw.exe avec les arguments de
ligne de commande requis. Dans ce cas, l'application semble être Python et non son
nom réel, et les utilisateurs peuvent avoir du mal à le distinguer des autres processus
Python en cours d'exécution ou des associations de fichiers.

Avec cette dernière approche, les packages doivent être installés en tant que
répertoires à côté de l'exécutable Python pour s'assurer qu'ils soient visibles par
Python. Avec le lanceur spécialisé, les paquets peuvent être installés dans d'autres
emplacements car il y a une possibilité de spécifier le chemin de recherche avant de
lancer l'application.

3.4.2. Embarquer Python
Les applications écrites en code natif nécessitent souvent une certaine forme de
langage de scripting, et la distribution Python intégrée peut être utilisée à cette fin.
En général, la majorité de l'application est dans le code natif, qui soit
invoque python.exe soit utilise directement python3.dll. Dans les deux cas,
l'extraction de la distribution intégrée dans un sous-répertoire de l'installation de
l'application est suffisante pour fournir un interpréteur Python chargeable.

Comme pour l'utilisation de l'application, les paquets peuvent être installés sur
n'importe quel emplacement, car il est possible de spécifier des chemins de
recherche avant d'initialiser l'interpréteur. Sinon, il n'y a pas de différences
fondamentales entre l'utilisation de la distribution embarquée et une installation
classique.
3.5. Paquets alternatifs
À part la distribution standard CPython, il y a des paquets modifiés incluant des
fonctionnalités additionnelles. La liste qui suit est une liste de versions populaires et
de leurs fonctionnalités principales :

ActivePython

Installeur avec une compatibilité multi-plateforme, de la documentation, et PyWin32

Anaconda

Des modules scientifiques populaires (comme numpy, scipy et pandas) et le


gestionnaire de paquets conda.

Canopy

Un "environnement d'analyse complet Python" avec des éditeurs et autres outils de


développement.

WinPython

Distribution spécifique à Windows avec des paquets scientifiques pré-compilés et


des outils pour construire des paquets.

Notez que ces paquets peuvent ne pas inclure la dernière version de Python ou
d'autres bibliothèques, et ne sont pas maintenus ni supportés par les core
devs Python.

3.6. Configurer Python
Pour exécuter Python confortablement à partir d'une invite de commandes, vous
pouvez envisager de modifier certaines variables d'environnement par défaut dans
Windows. Bien que l'installateur offre une option pour configurer les
variables PATH et PATHEXT pour vous, ce n'est fiable que pour une seule installation
à l'échelle du système. Si vous utilisez régulièrement plusieurs versions de Python,
pensez à utiliser le Lanceur Python pour Windows.
3.6.1. Digression : Définition des variables
d'environnement
Windows permet de configurer les variables d'environnement de façon permanente
au niveau de l'utilisateur et du système, ou temporairement dans une invite de
commandes.

Pour définir temporairement les variables d'environnement, ouvrez l'invite de


commandes et utilisez la commande set :

C:\>set PATH=C:\Program Files\Python 3.7;%PATH%


C:\>set PYTHONPATH=%PYTHONPATH%;C:\My_python_lib
C:\>python

Ces modifications s'appliqueront à toutes les autres commandes exécutées dans


cette console et seront héritées par toutes les applications démarrées à partir de
cette console.

Un nom de variable entre des signes pour cent sera remplacé par sa valeur, vous
permettant d'ajouter votre nouvelle valeur au début ou à la fin.
Ajouter python.exe au début de PATH est un moyen courant de s'assurer que la
version correcte de Python est lancée.

Pour modifier définitivement les variables d'environnement par défaut, recherchez


« modifier les variables d'environnement », via le menu démarrer, ou ouvrez
« Propriétés Système », Paramètres Système Avancés et cliquez sur le
bouton Variables d'Environnement. Dans cette boîte de dialogue, vous pouvez
ajouter ou modifier des variables utilisateurs et systèmes. Pour modifier les variables
systèmes, vous avez besoin d'un accès non restreint à votre ordinateur (c'est-à-dire
aux droits d'administrateur).

Note

Windows va concaténer les variables utilisateurs après les variables systèmes, ce


qui peut provoquer des résultats inattendus lors de la modification de PATH.

La variable PYTHONPATH est utilisée par toutes les versions de Python 2 et Python 3,


vous ne devez donc pas configurer cette variable de façon permanente à moins
qu'elle n'ajoute que du code compatible avec toutes les versions de Python
installées.
Voir aussi
https://www.microsoft.com/en-us/wdsi/help/folder-variables

Variables d'environnement dans Windows NT


https://technet.microsoft.com/en-us/library/cc754250.aspx

La commande SET, pour modifier temporairement les variables d'environnement


https://technet.microsoft.com/en-us/library/cc755104.aspx

La commande SETX, pour modifier de façon permanente les variables


d'environnement
https://support.microsoft.com/en-us/help/310519/how-to-manage-environment-
variables-in-windows-xp

Comment gérer les variables d'environnement sous Windows XP


https://www.chem.gla.ac.uk/~louis/software/faq/q1.html

Définir les variables d'environnement, Louis J. Farrugia

3.6.2. Trouver l'exécutable Python


Modifié dans la version 3.5.

En plus d'utiliser l'entrée du menu Démarrer automatiquement créée pour


l'interpréteur Python, vous souhaiterez peut-être démarrer Python depuis l'invite de
commandes. L'installateur a une option pour installer cela pour vous.

Sur la première page de l'installateur, une option intitulée "Ajouter Python au PATH"
peut être sélectionnée pour que l'installateur ajoute l'emplacement d'installation dans
le PATH. L'emplacement du dossier Scripts\ y est également ajouté. Cela vous
permet de taper Python pour exécuter l'interpréteur, et pip pour l'installateur de
paquets. Ainsi, vous pouvez également exécuter vos scripts avec les options de ligne
de commande, voir la documentation Ligne de commande.

Si vous n'activez pas cette option au moment de l'installation, vous pouvez toujours
ré-exécuter l'installateur, sélectionner Modifier et l'activer. Vous pouvez également
modifier manuellement le PATH à l'aide des instructions de Digression : Définition des
variables d'environnement. Vous devez définir votre variable
d'environnement PATH pour inclure le répertoire de votre installation Python, délimité
par un point-virgule des autres entrées. Une variable d'exemple pourrait ressembler
à ceci (en supposant que les deux premières entrées existaient déjà) :

C:\WINDOWS\system32;C:\WINDOWS;C:\Program Files\Python 3.7


3.7. UTF-8 mode
Nouveau dans la version 3.7.

Windows still uses legacy encodings for the system encoding (the ANSI Code Page).
Python uses it for the default encoding of text files
(e.g. locale.getpreferredencoding()).

This may cause issues because UTF-8 is widely used on the internet and most Unix
systems, including WSL (Windows Subsystem for Linux).

You can use UTF-8 mode to change the default text encoding to UTF-8. You can
enable UTF-8 mode via the -X utf8 command line option, or
the PYTHONUTF8=1 environment variable. See PYTHONUTF8 for enabling UTF-8
mode, and Digression : Définition des variables d'environnement for how to modify
environment variables.

When UTF-8 mode is enabled:

 locale.getpreferredencoding() returns 'UTF-8' instead of the system


encoding. This function is used for the default text encoding in many places,
including open(), Popen, Path.read_text(), etc.
 sys.stdin, sys.stdout, and sys.stderr all use UTF-8 as their text
encoding.
 You can still use the system encoding via the "mbcs" codec.

Note that adding PYTHONUTF8=1 to the default environment variables will affect all
Python 3.7+ applications on your system. If you have any Python 3.7+ applications
which rely on the legacy system encoding, it is recommended to set the environment
variable temporarily or use the -X utf8 command line option.

Note

Even when UTF-8 mode is disabled, Python uses UTF-8 by default on Windows for:
 Console I/O including standard I/O (see PEP 528 for details).
 The filesystem encoding (see PEP 529 for details).
3.8. Lanceur Python pour Windows
Nouveau dans la version 3.3.

Le lanceur Python pour Windows est un utilitaire qui facilite la recherche et


l'exécution de différentes versions de Python. Il permet aux scripts (ou à la ligne de
commande) d'indiquer une préférence pour une version Python spécifique, cherchera
et exécutera cette version.

Contrairement à la variable PATH, le lanceur sélectionne correctement la version la


plus appropriée de Python. Il préfère les installations par utilisateur sur celles du
système, et les trie par version plutôt que d'utiliser la version la plus récente installée.

Le lanceur a été initialement spécifié dans PEP 397.

3.8.1. Pour commencer
3.8.1.1. Depuis la ligne de commande

Modifié dans la version 3.6.

Les installations systèmes de Python 3.3 et ultérieur mettent le lanceur dans


votre PATH. Le lanceur est compatible avec toutes les versions disponibles de
Python, peu importe lesquelles sont installées. Pour vérifier que le lanceur est
disponible, exécutez la commande suivante dans l'invite de commandes :

py

Vous devriez voir se lancer la dernière version de Python installée — il peut être
quitté normalement, et tous les arguments de ligne de commande supplémentaires
spécifiés seront envoyés directement à Python.

Si plusieurs versions de Python sont installées (par exemple, 2.7 et 3.7), vous aurez
remarqué que Python 3.7 se lance -- pour lancer Python 2.7, essayez la commande :

py -2.7

Si vous voulez que la dernière version de Python 2.x que vous avez installé, essayez
la commande :

py -2

Remarquez que la dernière version de Python 2.x démarre.


Si vous voyez l'erreur suivante, le lanceur n'est pas installé :

'py' is not recognized as an internal or external command,


operable program or batch file.

Les installations par utilisateur de Python n'ajoutent pas le lanceur à PATH sauf si


l'option a été sélectionnée lors de l'installation.

3.8.1.2. Environnements virtuels

Nouveau dans la version 3.5.

Si le lanceur est exécuté sans version de Python explicite et qu'un environnement


virtuel (créé avec le module de la bibliothèque standard venv ou l'outil
externe virtualenv) est actif, le lanceur exécute l'interpréteur de l'environnement
virtuel plutôt que l'interpréteur global. Pour exécuter l'interpréteur global, désactivez
l'environnement virtuel ou spécifiez explicitement la version Python globale.

3.8.1.3. À partir d'un script

Créons un script Python de test, créez un fichier appelé hello.py avec le contenu


suivant

#! python
import sys
sys.stdout.write("hello from Python %s\n" % (sys.version,))

À partir du répertoire dans lequel se trouve hello.py, exécutez la commande :

py hello.py

Vous devriez voir le numéro de version du Python 2.x le plus récemment installé.
Maintenant, essayez de changer la première ligne en :

#! python3

La commande doit maintenant afficher les dernières informations de Python 3.x.


Comme pour les exemples de ligne de commande ci-dessus, vous pouvez spécifier
un qualificateur de version plus explicite. En supposant que vous avez installé
Python 2.6, essayez de changer la première ligne à #! python2.6 et vous devriez
trouver les informations de version 2.6 imprimées.
Notez que, contrairement à l'utilisation interactive, un "python" nu utilisera la dernière
version de Python 2.x que vous avez installé. C'est pour la compatibilité ascendante
et pour la compatibilité avec UNIX, où la commande python fait généralement
référence à Python 2.

3.8.1.4. À partir d'associations de fichiers

Le lanceur aurait dû être associé à des fichiers Python (des fichiers


comme .py, .pyw, .pyc) lorsqu'il a été installé. Cela signifie que lorsque vous
double-cliquez sur l'un de ces fichiers à partir de l'Explorateur Windows, le lanceur
sera utilisé, et donc vous pouvez utiliser les mêmes installations décrites ci-dessus
pour que le script spécifie la version qui doit être utilisée.

L'avantage principal de ceci est qu'un seul lanceur peut prendre en charge plusieurs
versions de Python en même temps en fonction du contenu de la première ligne.

3.8.2. Lignes Shebang
Si la première ligne d'un fichier de script commence par #!, elle est connue sous le
nom de ligne "shebang". Linux et d'autres systèmes basés sur Unix ont une prise en
charge native de ces lignes et les shebangs sont couramment utilisés sur ces
systèmes pour indiquer comment un script doit être exécuté. Ce lanceur permet aux
mêmes installations d'être utilisés avec des scripts Python sur Windows et les
exemples ci-dessus démontrent leur utilisation.

Pour permettre aux shebang dans les scripts Python d'être portables entre UNIX et
Windows, ce lanceur prend en charge un certain nombre de commandes
« virtuelles » pour spécifier l'interpréteur à utiliser. Les commandes virtuelles prises
en charge sont :

 /usr/bin/env python
 /usr/bin/python
 /usr/local/bin/python
 python

Par exemple, si la première ligne de votre script commence par

#! /usr/bin/python

Le Python par défaut sera trouvé et utilisé. Comme de nombreux scripts Python
écrits pour fonctionner sur UNIX auront déjà cette ligne, ils devraient fonctionner
avec le lanceur sans modification. Si vous écrivez un nouveau script sur Windows et
que vous pensez qu'il sera utile sur UNIX, vous devez utiliser l'une des
lignes shebang commençant par /usr.

Les commandes virtuelles ci-dessus peuvent être suffixées avec une version
explicite (soit seulement la version principale, soit la version principale et mineure).
De plus la version 32-bit peut être demandée en ajoutant -32 après le numéro de
version mineur. Par exemple /usr/bin/python2.7-32 demande d’utiliser la
version 32-bit de Python 2.7.

Nouveau dans la version 3.7: Depuis la version 3.7 du lanceur Python, il est possible
de demander une version 64-bit en utilisant le suffixe -64. De plus il est possible de
spécifier une version majeure et une architecture sans version mineure (par
exemple /usr/bin/python3-64).

La forme /usr/bin/env de ligne shebang possède une autre propriété spéciale.


Avant de rechercher les interpréteurs Python installés, cette forme recherche d'abord
l'exécutable dans le PATH. Cela correspond au comportement du programme
Unix env, qui effectue une recherche dans PATH.

3.8.3. Arguments dans les lignes shebang


Les lignes shebang peuvent également spécifier des options supplémentaires à
passer à l'interpréteur Python. Par exemple, si vous avez une ligne shebang :

#! /usr/bin/python -v

Alors, Python sera démarré avec l'option -v

3.8.4. Personnalisation
3.8.4.1. Personnalisation via des fichiers INI

Deux fichiers .ini seront recherchés par le lanceur -- py.ini dans le répertoire


"Application Data" de l'utilisateur actuel (c'est-à-dire le répertoire retourné en
appelant la fonction Windows SHGetFolderPath avec CSIDL_LOCAL_APPDATA)
et py.ini dans le même répertoire que le lanceur. Les mêmes fichiers .ini sont
utilisés à la fois pour la version « console » du lanceur (c'est-à-dire py.exe) et pour
la version « fenêtrée » (c'est-à-dire pyw.exe).

La personnalisation spécifiée dans le "répertoire de l'application" aura la priorité sur


celle à côté de l'exécutable, de sorte qu'un utilisateur, qui peut ne pas avoir accès en
écriture au fichier .ini à côté du lanceur, peut substituer des commandes dans ce
fichier .ini global)
3.8.4.2. Personnalisation des versions Python par défaut

Dans certains cas, un qualificateur de version peut être inclus dans une commande
pour dicter quelle version de Python sera utilisée par la commande. Un qualificateur
de version commence par un numéro de version majeure et peut éventuellement être
suivi d'un point (.) et d'un spécificateur de version secondaire. De plus il est possible
de préciser si une implémentation 32 ou 64 bit doit être demandée en ajoutant -
32 ou -64.

Par exemple, une ligne shebang valant #!python n'a pas de qualificateur de


version, tandis que #!python3 a un qualificateur de version qui ne spécifie qu'une
version majeure.

Si aucun qualificateur de version n'est trouvé dans une commande, la variable


d'environnement PY_PYTHON peut être définie pour spécifier le qualificateur de
version par défaut. Si non définie, la valeur par défaut est 3. La variable peut
spécifier n’importe quelle valeur qui peut être passée dans la ligne de commande
telle que 3, 3.7, 3.7-32 ou 3.7-64. (Notez que l’option -64 est seulement
disponible avec le lanceur inclus avec Python 3.7 ou plus récent.)

Si aucun qualificateur de version mineure n'est trouvé, la variable


d'environnement PY_PYTHON{major} (où {major} est le qualificateur de version
principale actuelle tel que déterminé ci-dessus) peut être définie pour spécifier la
version complète. Si aucune option de ce type n'est trouvée, le lanceur énumérera
les versions de Python installées et utilisera la dernière version mineure trouvée pour
la version principale, qui est probablement la plus récemment installée dans cette
famille.

Sur Windows 64-bits avec les implémentations 32-bits et 64-bits de la même version
Python (major.minor) installée, la version 64-bit est toujours préférée. Cela est vrai
pour les implémentations 32-bits et 64-bits du lanceur – un lanceur 32-bits préfère
exécuter une installation Python de 64-bits de la version spécifiée si elle est
disponible. Le comportement du lanceur est donc prévisible en sachant seulement
quelles versions sont installées sur le PC et sans tenir compte de l'ordre dans lequel
ils ont été installés (i.e., sans savoir si une version 32 ou 64-bit de Python et le
lanceur correspondant a été installé en dernier). Comme indiqué ci-dessus, un
suffixe optionnel -32 ou -64 peut être utilisé sur un spécificateur de version pour
modifier ce comportement.

Exemples :
 Si aucune option pertinente n'est définie, les
commandes python et python2 utiliseront la dernière version de Python 2.x
installée et la commande python3 utilisera le dernier Python 3.x installé.
 Les commandes python3.1 et python2.7 ne consultent aucune option du
tout car les versions sont entièrement spécifiées.
 Si PY_PYTHON=3, les commandes python et python3 utiliseront la dernière
version de Python 3 installée.
 Si PY_PYTHON=3.1-32, la commande python utilisera l'implémentation 32-
bits de 3.1 alors que la commande python3 utilisera le dernier Python installé
(PY_PYTHON n'a pas été considéré du tout comme une version majeure a été
spécifiée.)
 Si PY_PYTHON=3 et PY_PYTHON3=3.1, les
commandes python et python3 utiliseront spécifiquement 3.1

En plus des variables d'environnement, les mêmes paramètres peuvent être


configurés dans le .INI utilisé par le lanceur. La section dans le fichier INI est
appelée [defaults] et le nom de la clé sera le même que les variables
d'environnement sans le préfixe PY_ principal (et notez que les noms de clés dans le
fichier INI sont insensibles à la case.) Le contenu d'une variable d'environnement
remplacera les éléments spécifiés dans le fichier INI.

Par exemple :

 Le paramètre PY_PYTHON=3.1 équivaut au fichier INI contenant :
[defaults]
python=3.1
 Le paramètre PY_PYTHON=3 et PY_PYTHON3=3.1 équivaut au
fichier INI contenant :
[defaults]
python=3
python3=3.1

3.8.5. Diagnostics
Si une variable d'environnement PYLAUNCH_DEBUG est définie (à n'importe quelle
valeur), le lanceur affichera des informations de diagnostic sur stderr (c'est-à-dire sur
la console). Bien que ces informations parviennent à être en même temps
nombreuses et concises, elles devraient vous permettre de voir quelles versions de
Python ont été trouvées, pourquoi une version particulière a été choisie et la ligne de
commande exacte utilisée pour exécuter le Python cible.
3.9. Recherche de modules
Python stocke généralement sa bibliothèque (et donc votre dossier site-packages)
dans le répertoire d'installation. Donc, si vous aviez installé Python
dans C:\Python\, la bibliothèque par défaut résiderait dans C:\Python\Lib\ et
les modules tiers devraient être stockés dans C:\Python\Lib\site-packages\.

Pour remplacer complètement sys.path, créez un fichier ._pth portant le même


nom que le DLL ( python37._pth) ou l'exécutable (python._pth) et spécifiez une
ligne pour chaque chemin à ajouter à sys.path. Le fichier basé sur le nom de la
DLL remplace celui basé sur l'exécutable, qui permet aux chemins d'être restreints
pour tout programme chargeant le runtime si désiré.

Lorsque le fichier existe, toutes les variables de registre et d'environnement sont


ignorées, le mode isolé est activé et site n'est pas importé, sauf si une ligne du
fichier spécifie import site. Les chemins et les lignes vides commençant
par # sont ignorés. Chaque chemin d'accès peut être absolu ou relatif à
l'emplacement du fichier. Les importations autres que vers site ne sont pas
autorisées, ni n'importe quelle instruction Python.

Notez que les fichiers .pth (sans underscore précédant le pth) seront traités


normalement par le module site lorsque import site a été spécifié.

Lorsque aucun fichier ._pth n'est trouvé, voilà comment sys.path est construit sur


Windows :

 Une entrée vide est ajoutée au début, qui correspond au répertoire courant.
 Si la variable d'environnement PYTHONPATH existe, comme décrit
dans Variables d'environnement, ses entrées sont ajoutées ensuite. Notez que sur
Windows, les chemins d'accès de cette variable doivent être séparés par des points-
virgules, pour les distinguer des deux points utilisés dans les identificateurs de
lecteur (C:\ etc.).
 Des "chemins d'accès d'application" supplémentaires peuvent être ajoutés
dans le registre en tant que sous-clés
de \SOFTWARE\Python\PythonCore{version}\PythonPath sous les
ruches HKEY_CURRENT_USER et HKEY_LOCAL_MACHINE. Les sous-clés qui ont des
chaînes de chemin délimitées par des points-virgules comme valeur par défaut
entraînent l'ajout de chaque chemin d'accès à sys.path. (Notez que tous les
installateurs connus utilisent seulement HKLM, donc HKCU est généralement vide.)
 Si la variable d'environnement PYTHONHOME est définie, elle est supposée
comme "Python Home". Sinon, le chemin de l'exécutable principal de Python est
utilisé pour chercher un "fichier de repère" (soit Lib\os.py ou pythonXY.zip) pour
déduire le "Python Home". Si un "Python Home" est trouvé, les sous-répertoires
correspondants ajoutés à sys.path (Lib, plat-win, etc) sont basés sur ce dossier.
Sinon, le chemin d'accès Python principal est construit à partir du PythonPath stocké
dans le registre.
 Si le "Python Home" ne peut pas être trouvé, PYTHONPATH n'est pas spécifié
dans l'environnement et aucune entrée de registre ne peut être trouvée, un chemin
par défaut avec des entrées relatives est utilisé (par exemple .\Lib ; .\plat-win,
etc.).

Si un fichier pyvenv.cfg se trouve à côté de l'exécutable principal ou dans le


répertoire un niveau au-dessus de l'exécutable, les variantes suivantes s'appliquent :

 Si home est un chemin absolu et PYTHONHOME n'est pas défini, ce chemin


d'accès est utilisé au lieu du chemin d'accès à l'exécutable principal lors de la
déduction de l'emplacement du home.

Le résultat final de tout ceci est :

 Lors de l'exécution de python.exe, ou tout autre .exe dans le répertoire


principal de Python (soit une version installée, soit directement à partir du répertoire
PCbuild), le chemin principal est déduit et les chemins d'accès principaux dans le
Registre sont ignorés. D'autres "chemins d'application" dans le registre sont toujours
lus.
 Lorsque Python est hébergé dans un autre fichier .exe (répertoire différent,
intégré via COM, etc.), le "Python Home" ne sera pas déduit, de sorte que le chemin
d'accès principal du registre est utilisé. D'autres "chemins d'application" dans le
registre sont toujours lus.
 Si Python ne peut pas trouver son "home" et il n'y a pas de valeur de registre
(.exe gelé, une installation très étrange) vous obtenez un chemin d'accès avec
certains chemins par défaut, mais relatif.

Pour ceux qui veulent intégrer Python dans leur application ou leur distribution, les
conseils suivants empêcheront les conflits avec d'autres installations :

 Incluez un fichier ._pth à côté de votre exécutable contenant les répertoires à


inclure. Ceci ignorera les chemins répertoriés dans le registre et les variables
d'environnement, et ignorera également site à moins que import site soit listé.
 Si vous chargez python3.dll ou python37.dll dans votre propre
exécutable, appelez explicitement Py_SetPath() ou (au
moins) Py_SetProgramName() avant Py_Initialize().
 Effacer et/ou écraser PYTHONPATH et configurez PYTHONHOME avant de lancer
le python.exe de votre application.
 Si vous ne pouvez pas utiliser les suggestions précédentes (par exemple,
vous êtes une distribution qui permet aux gens d'exécuter python.exe directement),
assurez-vous que le point de repère Lib\os.py existe dans votre répertoire
d'installation. (Notez qu'il ne sera pas détecté à l'intérieur d'un fichier ZIP, mais un
fichier ZIP correctement nommé sera détecté à la place.)

Ceux-ci garantiront que les fichiers d'une installation à l'échelle du système n'auront
pas la priorité sur la copie de la bibliothèque standard livrée avec votre application.
Sinon, vos utilisateurs pourraient rencontrer des problèmes en utilisant votre
application. Notez que la première suggestion est la meilleure, car les autres peuvent
encore être sensibles aux chemins non-standard dans le registre et le site-
packages utilisateur.

Modifié dans la version 3.6:

 Ajout de la gestion des ._pth et suppression de


l'option applocal de pyvenv.cfg.
 Ajout de pythonXX.zip comme point de repère potentiel lorsqu'il est
directement adjacent à l'exécutable.
Obsolète depuis la version 3.6:

Les modules spécifiés dans le registre sous Modules (pas PythonPath) peuvent


être importés par importlib.machinery.WindowsRegistryFinder. Ce Finder
est activé sur Windows dans 3.6.0 et plus récent, mais il pourrait être nécessaire de
l'ajouter explicitement à sys.meta_path à l'avenir.

3.10. Modules supplémentaires
Même si Python a l'ambition d'être portable parmi toutes les plates-formes, il existe
des fonctionnalités propres à Windows. Certains modules, à la fois dans la
bibliothèque standard et externe, et des exemples existent pour utiliser ces
fonctionnalités.

Les modules standard de Windows sont documentés dans Services spécifiques à


MS Windows.

3.10.1. PyWin32
Le module PyWin32 de Mark Hammond est une collection de modules pour un
support avancé spécifique à Windows. Cela inclut les services pour :

 Component Object Model (COM)


 Appels à l'API Win32
 Registre
 Journal d'événement
 Microsoft Foundation Classes (MFC) interfaces utilisateur

PythonWin est un exemple d'application MFC livrée avec PyWin32. Il s'agit d'un IDE
embarqué avec débogueur intégré.

Voir aussi
Win32 How Do I...?

par Tim Golden


Python and COM

par David et Paul Boddie


3.10.2. cx_Freeze
cx_Freeze est une extension distutils (voir Extension de Distutils) qui encapsule
des scripts Python dans des programmes exécutables Windows (Fichiers *.exe).
Lorsque vous l'avez fait, vous pouvez distribuer votre application sans demander à
vos utilisateurs d'installer Python.

3.10.3. WConio
Depuis la couche avancée de gestion de terminal de Python, curses, est limité aux
systèmes de type UNIX, il existe une bibliothèque exclusive à Windows : Windows
Console I/O for Python.

WConio est un wrapper pour les fichiers Turbo-C CONIO.H, utilisé pour créer des


interfaces texte utilisateur.

3.11. Compiler Python sous Windows


Si vous voulez compiler CPython vous-même, la première chose à faire est obtenir
la source. Vous pouvez télécharger soit la source de la dernière version ou tout
simplement prendre un checkout.

L'arborescence source contient une solution de compilation et des fichiers projet pour
Microsoft Visual Studio 2015, qui est le compilateur utilisé pour générer les versions
officielles de Python. Ces fichiers se trouvent dans le répertoire PCbuild.

Consultez PC/readme.txt pour des informations générales sur le processus de


construction.
Pour les modules d'extension, consultez Construire des extensions C et C++ sur
Windows.

Voir aussi
Python + Windows + distutils + SWIG + gcc MinGW

ou "Creating Python extensions in C/C++ with SWIG and compiling them with
MinGW gcc under Windows" ou "Installing Python extension with distutils and without
Microsoft Visual C++" par Sébastien Sauvage, 2003

MingW -- Python extensions

3.12. Autres plateformes
Avec le développement continu de Python, certaines plateformes qui étaient
auparavant prises en charge ne sont plus prises en charge (en raison du manque
d'utilisateurs ou de développeurs). Voir PEP 11 pour plus de détails sur toutes les
plateformes non prises en charge.

 Windows CE est toujours pris en charge.


 L’installateur Cygwin offre d’installer l’interpréteur Python (cf. Cygwin package
source, Maintainer releases)

Voir Python pour Windows pour des instructions détaillées sur les plateformes avec
installateurs pré-compilés.

4. Utilisation de Python sur un Macintosh


Auteur

Bob Savage <bobsavage@mac.com>

Python sur un Macintosh exécutant Mac OS X est en principe très similaire à Python
sur n'importe quelle autre plateforme Unix, mais il y a un certain nombre de
fonctionnalités additionnelle telle que l'IDE et le gestionnaire de paquets qui méritent
d'être soulignées.

4.1. Obtenir et installer MacPython


Mac OS X 10.8 contient déjà Python 2.7 pré-installé par Apple. Si vous le souhaitez,
vous êtes invités à installer la version la plus récente de Python 3 à partir du site de
Python (https://www.python.org). Une version "binaire universelle" de Python, qui
s'exécute nativement sur les nouveaux processeurs Intel de Mac et les processeurs
PPC, CPUs hérités de Mac, y est disponible.
Vous obtiendrez un certain nombre de choses après installation:

 A Python 3.7 folder in your Applications folder. In here you find IDLE, the


development environment that is a standard part of official Python distributions; and
PythonLauncher, which handles double-clicking Python scripts from the Finder.
 Un framework /Library/Frameworks/Python.framework, qui inclut
l’exécutable Python et ses bibliothèques. L’installateur ajoute ce chemin à
votre PATH. Pour désinstaller MacPython, vous pouvez simplement supprimer ces
trois choses. Un lien symbolique vers l'exécutable Python est placé
dans /usr/local/bin/.

Le build Python fourni par Apple est installé


dans /System/Library/Frameworks/Python.framework et /usr/bin/python.
Vous ne devriez jamais les modifier ou supprimer, car ils sont contrôlés et utilisés par
Apple (ou d'autres logiciels). Rappelez vous que si vous choisissez d'installer un
Python plus récent depuis python.org, vous aurez deux installations de Python
différentes et fonctionnelles sur votre ordinateur, il est donc important que vos
chemins et utilisations soit cohérentes avec ce que vous voulez faire.

IDLE inclut un menu d'aide qui vous permet d’accéder à la documentation Python. Si


vous êtes entièrement novice, vous devriez commencer par lire le tutoriel
d'introduction dans ce document.

Si vous êtes familier avec Python sur d'autres plateformes Unix, vous devriez lire la
section sur comment exécuter des scripts Python depuis un shell Unix.

4.1.1. Comment exécuter un script Python


Le meilleur moyen de démarrer avec Python sur Max OS X est d'utiliser
l'environnement de développement intégré IDLE, voir la section L'IDE et utilisez le
menu d'aide (Help) quand l'IDE est lancé.

Si vous souhaitez exécuter des scripts Python depuis l'invite de commande dans la
fenêtre Terminal, ou depuis le Finder, vous avez d'abord besoin d'un éditeur pour
créer votre script. Max OS X propose un certain nombre d’éditeurs shell Unix
standards, dont vim et emacs. Si vous voulez une interface plus
Mac, BBEdit ou TextWrangler de Bare Bones Software
(voir http://www.barebones.com/products/bbedit/index.html) sont de bons choix, tout
comme TextMate (voir https://macromates.com/). D'autres éditeurs existent
comme Gvim (http://macvim-dev.github.io/macvim/)
et Aquamacs (http://aquamacs.org/).
Pour exécuter votre script depuis la fenêtre Terminal, vous devez vous assurer
que /usr/local/bin est dans le chemin de recherche de votre shell (PATH).

Pour exécuter votre script depuis le Finder vous avez deux options :

 Glissez-le vers PythonLauncher
 Sélectionnez PythonLauncher en tant qu'application par défaut pour ouvrir
votre script (ou n'importe quel script .py) depuis la fenêtre info de votre Finder puis
double-cliquez votre script. PythonLauncher a des préférences variées pour
contrôler comment votre script est exécuté. Glisser des options permets de les
changer pour une invocation, ou utilisez le menu Préférences pour changer les
choses globalement.
4.1.2. Lancer des scripts avec une interface graphique
Avec les anciennes versions de Python, il y a une bizarrerie Max OS X dont vous
devez être au courant : les programmes qui communiquent avec le gestionnaires de
fenêtre Aqua (en d'autres termes, tout ce qui a une interface graphique) doivent être
exécutés de façon spécifique. Utilisez pythonw au lieu de python pour exécuter ce
genre de scripts.

With Python 3.7, you can use either python or pythonw.

4.1.3. Configuration
Python sur OS X respecte tous les standards Unix pour les variables
d'environnement comme PYTHONPATH, mais définir ces variables pour des
programmes exécutés depuis le Finder n'est pas standard car le Finder ne lit pas
votre .profile ou .cshrc au démarrage. Vous devez créer un
fichier ~/.MacOSX/environment.plist. Voir le document technique d'Apple
QA1067 pour plus de détails.

Pour plus d'informations sur l'installation de paquets Python dans MacPython, voir la


section Installation de paquets Python additionnels.

4.2. L'IDE
MacPython est livré avec l'environnement de développement standard IDLE. Une
bonne introduction sur l’utilisation d'IDLE peut être trouvée
à http://www.hashcollision.org/hkn/python/idle_intro/index.html.
4.3. Installation de paquets Python additionnels
Il y a plusieurs méthodes pour installer des paquets Python supplémentaires :

 Les paquets peuvent être installés en


utilisant distutils (python setup.py install).
 Beaucoup de paquets peuvent aussi être installés via
l'extension setuptools ou pip, voir https://pip.pypa.io/.
4.4. Programmation d'interface graphique sur le
Mac
Il y a plusieurs options pour construire des applications avec interface graphique sur
le Mac avec Python.

PyObjC est un binding Python vers le framework Objective-C/Cocoa d'Apple, qui


est la base de la plupart des développements modernes sur Mac. Des informations
sur PyObjC sont disponible à https://pypi.org/project/pyobjc/.

La boîte à outils standard de Python pour des interfaces graphique est tkinter,


basé sur la boite a outils multi-plateformes Tk (https://www.tcl.tk). Une version
native Aqua de Tk est empaquetée avec OS X par Apple, et la dernière version peut
être téléchargée et installée depuis https://www.activestate.com ; elle peut aussi être
construite depuis les sources.

wxPython est une boîte à outils multi-plateformes pour interfaces graphique


populaire qui tourne nativement sur Mac OS X. Les paquets et la documentation sont
disponibles sur https://www.wxpython.org.

PyQt est une boîte à outils multi-plateformes pour interfaces graphique populaire qui
tourne nativement sur Mac OS X. Plus d'informations disponible
sur https://riverbankcomputing.com/software/pyqt/intro.

4.5. Distribuer des Applications Python sur le Mac


L'outil standard pour déployer des applications Python sur le Mac est py2app. Plus
d'information sur l'installation et l'utilisation
de py2app sur http://undefined.org/python/#py2app.
4.6. Autres ressources
La liste de diffusion courriel MacPython est une excellente ressource support pour
les utilisateurs et développeurs Python sur Mac :

https://www.python.org/community/sigs/current/pythonmac-sig/

Une autre ressource utile est le wiki MacPython :

https://wiki.python.org/moin/MacPython

5. Editors and IDEs


There are a number of IDEs that support Python programming language. Many
editors and IDEs provide syntax highlighting, debugging tools, and PEP 8 checks.

Please go to Python Editors and Integrated Development Environments for a


comprehensive list.
La référence du langage Python
Cette documentation décrit la syntaxe et la « sémantique interne » du langage. Elle
peut être laconique, mais essaye d'être exhaustive et exacte. La sémantique des
objets natifs secondaires, des fonctions, et des modules est documentée dans La
bibliothèque standard. Pour une présentation informelle du langage, voyez plutôt Le
tutoriel Python. Pour les développeurs C ou C++, deux manuels supplémentaires
existent : Extension et intégration de l'interpréteur Python survole l'écriture
d'extensions, et Manuel de référence de l'API Python/C décrit l'interface C/C++ en
détail.

 1. Introduction
o 1.1. Autres implémentations
o 1.2. Notations
 2. Analyse lexicale
o 2.1. Structure des lignes
o 2.2. Autres lexèmes
o 2.3. Identifiants et mots-clés
o 2.4. Littéraux
o 2.5. Opérateurs
o 2.6. Délimiteurs
 3. Modèle de données
o 3.1. Objets, valeurs et types
o 3.2. Hiérarchie des types standards
o 3.3. Méthodes spéciales
o 3.4. Coroutines
 4. Modèle d'exécution
o 4.1. Structure d'un programme
o 4.2. Noms et liaisons
o 4.3. Exceptions
 5. Le système d'importation
o 5.1. importlib
o 5.2. Les paquets
o 5.3. Recherche
o 5.4. Chargement
o 5.5. Le chercheur dans  path
o 5.6. Remplacement du système d'importation standard
o 5.7. Importations relatives au paquet
o 5.8. Cas particulier de __main__
o 5.9. Idées d'amélioration
o 5.10. Références
 6. Expressions
o 6.1. Conversions arithmétiques
o 6.2. Atomes
o 6.3. Primaires
o 6.4. Expression await
o 6.5. L'opérateur puissance
o 6.6. Arithmétique unaire et opérations sur les bits
o 6.7. Opérations arithmétiques binaires
o 6.8. Opérations de décalage
o 6.9. Opérations binaires bit à bit
o 6.10. Comparaisons
o 6.11. Opérations booléennes
o 6.12. Expressions conditionnelles
o 6.13. Expressions lambda
o 6.14. Listes d'expressions
o 6.15. Ordre d'évaluation
o 6.16. Priorités des opérateurs
 7. Les instructions simples
o 7.1. Les expressions
o 7.2. Les assignations
o 7.3. L'instruction assert
o 7.4. L'instruction pass
o 7.5. L'instruction del
o 7.6. L'instruction return
o 7.7. L'instruction yield
o 7.8. L'instruction raise
o 7.9. L'instruction break
o 7.10. L'instruction continue
o 7.11. L'instruction import
o 7.12. L'instruction global
o 7.13. L'instruction nonlocal
 8. Instructions composées
o 8.1. L'instruction if
o 8.2. L'instruction while
o 8.3. L'instruction for
o 8.4. L'instruction try
o 8.5. L'instruction with
o 8.6. Définition de fonctions
o 8.7. Définition de classes
o 8.8. Coroutines
 9. Composants de plus haut niveau
o 9.1. Programmes Python complets
o 9.2. Fichier d'entrée
o 9.3. Entrée interactive
o 9.4. Entrée d'expression
 10. Spécification complète de la grammaire
1. Introduction
Ce manuel de référence décrit le langage de programmation Python. Il n'a pas
vocation à être un tutoriel.

Nous essayons d'être le plus précis possible et nous utilisons le français (NdT : ou
l’anglais pour les parties qui ne sont pas encore traduites) plutôt que des
spécifications formelles, sauf pour la syntaxe et l’analyse lexicale. Nous espérons
ainsi rendre ce document plus compréhensible pour un grand nombre de lecteurs,
même si cela laisse un peu de place à l’ambiguïté. En conséquence, si vous arrivez
de Mars et que vous essayez de ré-implémenter Python à partir de cet unique
document, vous devrez faire des hypothèses et, finalement, vous aurez certainement
implémenté un langage sensiblement différent. D’un autre côté, si vous utilisez
Python et que vous vous demandez quelles règles s’appliquent pour telle partie du
langage, vous devriez trouver une réponse satisfaisante ici. Si vous souhaitez voir
une définition plus formelle du langage, nous acceptons toutes les bonnes volontés
(ou bien inventez une machine pour nous cloner ☺).

S’agissant du manuel de référence d’un langage, il est dangereux de rentrer


profondément dans les détails d’implémentation ; l’implémentation peut changer et
d’autres implémentations du même langage peuvent fonctionner différemment. En
même temps, CPython est l’implémentation de Python la plus répandue (bien que
d’autres implémentations gagnent en popularité) et certaines de ses bizarreries
méritent parfois d’être mentionnées, en particulier lorsque l’implémentation impose
des limitations supplémentaires. Par conséquent, vous trouvez de courtes "notes
d’implémentation" saupoudrées dans le texte.

Chaque implémentation de Python est livrée avec un certain nombre de modules


natifs. Ceux-ci sont documentés dans La bibliothèque standard. Quelques modules
natifs sont mentionnés quand ils interagissent significativement avec la définition du
langage.

1.1. Autres implémentations
Bien qu’il existe une implémentation Python qui soit de loin la plus populaire, il existe
d’autres implémentations qui présentent un intérêt particulier pour différents publics.

Parmi les implémentations les plus connues, nous pouvons citer :

CPython
C’est l’implémentation originelle et la plus entretenue de Python, écrite en C. Elle
implémente généralement en premier les nouvelles fonctionnalités du langage.

Jython

Python implémenté en Java. Cette implémentation peut être utilisée comme langage
de script pour les applications Java ou pour créer des applications utilisant des
bibliothèques Java. Elle est également souvent utilisée pour créer des tests de
bibliothèques Java. Plus d’informations peuvent être trouvées sur the Jython
website (site en anglais).

Python pour .NET

Cette implémentation utilise en fait l’implémentation CPython, mais c’est une


application .NET et permet un accès aux bibliothèques .NET. Elle a été créée par
Brian Lloyd. Pour plus d’informations, consultez la page d’accueil Python pour
.NET (site en anglais).

IronPython

Un autre Python pour .NET. Contrairement à Python.NET, il s’agit d’une


implémentation Python complète qui génère du code intermédiaire (IL) .NET et
compile le code Python directement en assemblages .NET. Il a été créé par Jim
Hugunin, le programmeur à l’origine de Jython. Pour plus d’informations, voir the
IronPython website (site en anglais).

PyPy

Une implémentation de Python complètement écrite en Python. Elle apporte des


fonctionnalités avancées introuvables dans d'autres implémentations, telles que le
fonctionnement sans pile (stackless en anglais) et un compilateur à la volée (Just in
Time compiler en anglais). L'un des objectifs du projet est d'encourager
l'expérimentation du langage lui-même en facilitant la modification de l'interpréteur
(puisqu'il est écrit en Python). Des informations complémentaires sont disponibles
sur la page d'accueil du projet PyPy (site en anglais).

Chacune de ces implémentations diffère d'une manière ou d'une autre par rapport au
langage décrit dans ce manuel, ou comporte des spécificités que la documentation
standard de Python ne couvre pas. Reportez-vous à la documentation spécifique à
l'implémentation pour déterminer ce que vous devez savoir sur l'implémentation que
vous utilisez.
1.2. Notations
Les descriptions de l'analyse lexicale et de la syntaxe utilisent une notation de
grammaire BNF modifiée. Le style utilisé est le suivant :

name ::= lc_letter (lc_letter | "_")*


lc_letter ::= "a"..."z"

La première ligne indique qu'un name est un lc_letter suivi d'une suite de zéro ou


plus lc_letters ou tiret bas. Un lc_letter est, à son tour, l'un des
caractères 'a' à 'z' (cette règle est effectivement respectée pour les noms définis
dans les règles lexicales et grammaticales de ce document).

Chaque règle commence par un nom (qui est le nom que la règle définit) et ::=. Une
barre verticale (|) est utilisée pour séparer les alternatives ; c'est l'opérateur le moins
prioritaire de cette notation. Une étoile ( *) signifie zéro ou plusieurs répétitions de
l'élément précédent ; de même, un plus (+) signifie une ou plusieurs répétitions, et
une expression entre crochets ([ ]) signifie zéro ou une occurrence (en d'autres
termes, l'expression encadrée est facultative). Les opérateurs * et + agissent aussi
étroitement que possible ; les parenthèses sont utilisées pour le regroupement. Les
chaînes littérales sont entourées de guillemets anglais ". L'espace n'est utilisée que
pour séparer les lexèmes. Les règles sont normalement contenues sur une seule
ligne ; les règles avec de nombreuses alternatives peuvent être formatées avec
chaque ligne représentant une alternative (et donc débutant par une barre verticale,
sauf la première).

Dans les définitions lexicales (comme dans l'exemple ci-dessus), deux autres
conventions sont utilisées : deux caractères littéraux séparés par des points de
suspension signifient le choix d'un seul caractère dans la plage donnée (en incluant
les bornes) de caractères ASCII. Une phrase entre les signes inférieur et supérieur
(<...>) donne une description informelle du symbole défini ; par exemple, pour
décrire la notion de "caractère de contrôle" si nécessaire.

Même si la notation utilisée est presque la même, il existe une grande différence
entre la signification des définitions lexicales et syntaxiques : une définition lexicale
opère sur les caractères individuels de l'entrée, tandis qu'une définition syntaxique
opère sur le flux de lexèmes générés par l'analyse lexicale. Toutes les notations sous
la forme BNF dans le chapitre suivant (« Analyse lexicale ») sont des définitions
lexicales ; les notations dans les chapitres suivants sont des définitions syntaxiques.
2. Analyse lexicale
Un programme Python est lu par un analyseur syntaxique (parser en anglais). En
entrée de cet analyseur syntaxique, nous trouvons des lexèmes (tokens en anglais),
produits par un analyseur lexical. Ce chapitre décrit comment l'analyseur lexical
découpe le fichier en lexèmes.

Python lit le texte du programme comme des suites de caractères Unicode ;


l'encodage du fichier source peut être spécifié par une déclaration d'encodage et
vaut par défaut UTF-8, voir la PEP 3120 pour les détails. Si le fichier source ne peut
pas être décodé, une exception SyntaxError (erreur de syntaxe) est levée.

2.1. Structure des lignes


Un programme en Python est divisé en lignes logiques.

2.1.1. Lignes logiques
La fin d'une ligne logique est représentée par le lexème NEWLINE. Les instructions
ne peuvent pas traverser les limites des lignes logiques, sauf quand NEWLINE est
autorisé par la syntaxe (par exemple, entre les instructions des instructions
composées). Une ligne logique est constituée d'une ou plusieurs lignes physiques en
fonction des règles, explicites ou implicites, de continuation de ligne.

2.1.2. Lignes physiques
Une ligne physique est une suite de caractères terminée par une séquence de fin de
ligne. Dans les fichiers sources et les chaînes de caractères, n'importe quelle
séquence de fin de ligne des plateformes standards peut être utilisée ; Unix utilise le
caractère ASCII LF (pour linefeed, saut de ligne en français), Windows utilise la
séquence CR LF (carriage return suivi de linefeed) et Macintosh utilisait le caractère
ASCII CR. Toutes ces séquences peuvent être utilisées, quelle que soit la
plateforme. La fin de l'entrée est aussi une fin de ligne physique implicite.

Lorsque vous encapsulez Python, les chaînes de code source doivent être passées
à l'API Python en utilisant les conventions du C standard pour les caractères de fin
de ligne : le caractère \n, dont le code ASCII est LF.
2.1.3. Commentaires
Un commentaire commence par le caractère croisillon ( #, hash en anglais et qui
ressemble au symbole musical dièse, c'est pourquoi il est souvent improprement
appelé caractère dièse) situé en dehors d'une chaine de caractères littérale et se
termine à la fin de la ligne physique. Un commentaire signifie la fin de la ligne logique
à moins qu'une règle de continuation de ligne implicite ne s'applique. Les
commentaires sont ignorés au niveau syntaxique, ce ne sont pas des lexèmes.

2.1.4. Déclaration d'encodage
Si un commentaire placé sur la première ou deuxième ligne du script Python
correspond à l'expression rationnelle coding[=:]\s*([-\w.]+), ce commentaire
est analysé comme une déclaration d'encodage ; le premier groupe de cette
expression désigne l'encodage du fichier source. Cette déclaration d'encodage doit
être seule sur sa ligne et, si elle est sur la deuxième ligne, la première ligne doit
aussi être une ligne composée uniquement d'un commentaire. Les formes
recommandées pour l'expression de l'encodage sont

# -*- coding: <encoding-name> -*-

qui est reconnue aussi par GNU Emacs et

# vim:fileencoding=<encoding-name>

qui est reconnue par VIM de Bram Moolenaar.

Si aucune déclaration d'encodage n'est trouvée, l'encodage par défaut est utilisé :
UTF-8. En plus, si les premiers octets du fichier sont l'indicateur d'ordre des octets
UTF-8 (b'\xef\xbb\xbf', BOM en anglais pour byte order mark), le fichier est
considéré comme étant en UTF-8 (cette convention est reconnue, entre autres,
par notepad de Microsoft).

Si un encodage est déclaré, le nom de l'encodage doit être reconnu par Python.
L'encodage est utilisé pour toute l'analyse lexicale, y compris les chaînes de
caractères, les commentaires et les identifiants.

2.1.5. Continuation de ligne explicite


Deux lignes physiques, ou plus, peuvent être jointes pour former une seule ligne
logique en utilisant la barre oblique inversée ( \) selon la règle suivante : quand la
ligne physique se termine par une barre oblique inversée qui ne fait pas partie d'une
chaine de caractères ou d'un commentaire, la ligne immédiatement suivante lui est
adjointe pour former une seule ligne logique, en supprimant la barre oblique inversée
et le caractère de fin de ligne. Par exemple :

if 1900 < year < 2100 and 1 <= month <= 12 \


and 1 <= day <= 31 and 0 <= hour < 24 \
and 0 <= minute < 60 and 0 <= second < 60: # Looks like a
valid date
return 1

Une ligne que se termine par une barre oblique inversée ne peut pas avoir de
commentaire. La barre oblique inversée ne permet pas de continuer un
commentaire. La barre oblique inversée ne permet pas de continuer un lexème, sauf
s'il s'agit d'une chaîne de caractères (par exemple, les lexèmes autres que les
chaînes de caractères ne peuvent pas être répartis sur plusieurs lignes en utilisant
une barre oblique inversée). La barre oblique inversée n'est pas autorisée ailleurs sur
la ligne, en dehors d'une chaîne de caractères.

2.1.6. Continuation de ligne implicite


Les expressions entre parenthèses, crochets ou accolades peuvent être réparties sur
plusieurs lignes sans utiliser de barre oblique inversée. Par exemple :

month_names = ['Januari', 'Februari', 'Maart', # These are


the
'April', 'Mei', 'Juni', # Dutch names
'Juli', 'Augustus', 'September', # for the
months
'Oktober', 'November', 'December'] # of the year

Les lignes continuées implicitement peuvent avoir des commentaires. L'indentation


des lignes de continuation n'est pas importante. Une ligne blanche est autorisée
comme ligne de continuation. Il ne doit pas y avoir de lexème NEWLINE entre des
lignes implicitement continuées. Les lignes continuées implicitement peuvent être
utilisées dans des chaînes entre triples guillemets (voir ci-dessous) ; dans ce cas,
elles ne peuvent pas avoir de commentaires.

2.1.7. Lignes vierges
Une ligne logique qui ne contient que des espaces, tabulations, caractères de saut
de page (formfeed en anglais) ou commentaires est ignorée (c'est-à-dire que le
lexème NEWLINE n'est pas produit). Pendant l'édition interactive d'instructions, la
gestion des lignes vierges peut différer en fonction de l'implémentation de la boucle
REPL. Dans l'interpréteur standard, une ligne complètement vierge (c'est-à-dire ne
contenant strictement rien, même pas une espace ou un commentaire) termine une
instruction multi-lignes.

2.1.8. Indentation
Des espaces ou tabulations au début d’une ligne logique sont utilisées pour
connaître le niveau d’indentation de la ligne, qui est ensuite utilisé pour déterminer
comment les instructions sont groupées.

Les tabulations sont remplacées (de la gauche vers la droite) par une à huit espaces
de manière à ce que le nombre de caractères remplacés soit un multiple de huit
(nous avons ainsi la même règle que celle d'Unix). Le nombre total d'espaces
précédant le premier caractère non blanc détermine alors le niveau d'indentation de
la ligne. L'indentation ne peut pas être répartie sur plusieurs lignes physiques à l'aide
de barres obliques inversées ; les espaces jusqu'à la première barre oblique inversée
déterminent l'indentation.

L'indentation est déclarée inconsistante et rejetée si, dans un même fichier source, le
mélange des tabulations et des espaces est tel que la signification dépend du
nombre d'espaces que représente une tabulation. Une exception TabError est
levée dans ce cas.

Note de compatibilité entre les plateformes : en raison de la nature des éditeurs


de texte sur les plateformes non Unix, il n'est pas judicieux d'utiliser un mélange
d'espaces et de tabulations pour l'indentation dans un seul fichier source. Il convient
également de noter que des plateformes peuvent explicitement limiter le niveau
d'indentation maximal.

Un caractère de saut de page peut être présent au début de la ligne ; il est ignoré
pour les calculs d'indentation ci-dessus. Les caractères de saut de page se trouvant
ailleurs avec les espaces en tête de ligne ont un effet indéfini (par exemple, ils
peuvent remettre à zéro le nombre d'espaces).

Les niveaux d'indentation de lignes consécutives sont utilisés pour générer les
lexèmes INDENT et DEDENT, en utilisant une pile, de cette façon :

Avant que la première ligne du fichier ne soit lue, un « zéro » est posé sur la pile ; il
ne sera plus jamais enlevé. Les nombres empilés sont toujours strictement
croissants de bas en haut. Au début de chaque ligne logique, le niveau d'indentation
de la ligne est comparé au sommet de la pile. S'ils sont égaux, il ne se passe rien.
S'il est plus grand, il est empilé et un lexème INDENT est produit. S'il est plus petit,
il doit être l'un des nombres présents dans la pile ; tous les nombres de la pile qui
sont plus grands sont retirés et, pour chaque nombre retiré, un lexème DEDENT est
produit. À la fin du fichier, un lexème DEDENT est produit pour chaque nombre
supérieur à zéro restant sur la pile.

Voici un exemple de code Python correctement indenté (bien que très confus) :

def perm(l):
# Compute the list of all permutations of l
if len(l) <= 1:
return [l]
r = []
for i in range(len(l)):
s = l[:i] + l[i+1:]
p = perm(s)
for x in p:
r.append(l[i:i+1] + x)
return r

L'exemple suivant montre plusieurs erreurs d'indentation :

def perm(l): # error: first line indented


for i in range(len(l)): # error: not indented
s = l[:i] + l[i+1:]
p = perm(l[:i] + l[i+1:]) # error: unexpected indent
for x in p:
r.append(l[i:i+1] + x)
return r # error: inconsistent dedent

En fait, les trois premières erreurs sont détectées par l'analyseur syntaxique ; seule
la dernière erreur est trouvée par l'analyseur lexical (l'indentation de return r ne
correspond à aucun niveau dans la pile).

2.1.9. Espaces entre lexèmes


Sauf au début d'une ligne logique ou dans les chaînes de caractères, les caractères
« blancs » espace, tabulation et saut de page peuvent être utilisés de manière
interchangeable pour séparer les lexèmes. Un blanc n'est nécessaire entre deux
lexèmes que si leur concaténation pourrait être interprétée comme un lexème
différent (par exemple, ab est un lexème, mais a b comporte deux lexèmes).
2.2. Autres lexèmes
Outre NEWLINE, INDENT et DEDENT, il existe les catégories de lexèmes
suivantes : identifiants, mots clés, littéraux, opérateurs et délimiteurs. Les blancs
(autres que les fins de lignes, vus auparavant) ne sont pas des lexèmes mais servent
à délimiter les lexèmes. Quand une ambiguïté existe, le lexème correspond à la plus
grande chaîne possible qui forme un lexème licite, en lisant de la gauche vers la
droite.

2.3. Identifiants et mots-clés
Les identifiants (aussi appelés noms) sont décrits par les définitions lexicales
suivantes.

La syntaxe des identifiants en Python est basée sur l'annexe UAX-31 du standard
Unicode avec les modifications définies ci-dessous ; consultez la PEP 3131 pour
plus de détails.

Dans l'intervalle ASCII (U+0001..U+007F), les caractères licites pour les identifiants
sont les mêmes que pour Python 2.x : les lettres minuscules et majuscules de A à Z,
le souligné (ou underscore) _ et, sauf pour le premier caractère, les chiffres de 0 à 9.

Python 3.0 introduit des caractères supplémentaires en dehors de l'intervalle ASCII


(voir la PEP 3131). Pour ces caractères, la classification utilise la version de la
« base de données des caractères Unicode » telle qu'incluse dans le
module unicodedata.

Les identifiants n'ont pas de limite de longueur. La casse est prise en compte.

identifier ::= xid_start xid_continue*


id_start ::= <all characters in general categories Lu, Ll,
Lt, Lm, Lo, Nl, the underscore, and characters with the
Other_ID_Start property>
id_continue ::= <all characters in id_start, plus characters in
the categories Mn, Mc, Nd, Pc and others with the
Other_ID_Continue property>
xid_start ::= <all characters in id_start whose NFKC
normalization is in "id_start xid_continue*">
xid_continue ::= <all characters in id_continue whose NFKC
normalization is in "id_continue*">

Les codes de catégories Unicode cités ci-dessus signifient :


 Lu — lettres majuscules
 Ll — lettres minuscules
 Lt — lettres majuscules particulières (catégorie titlecase de l'Unicode)
 Lm — lettres modificatives avec chasse
 Lo — autres lettres
 Nl — nombres lettres (par exemple, les nombres romains)
 Mn — symboles que l'on combine avec d'autres (accents ou autres) sans
générer d'espace (nonspacing marks en anglais)
 Mc — symboles que l'on combine avec d'autres en générant une espace
(spacing combining marks en anglais)
 Nd — chiffres (arabes et autres)
 Pc — connecteurs (tirets et autres lignes)
 Other_ID_Start -- liste explicite des caractères de PropList.txt pour la
compatibilité descendante
 Other_ID_Continue — pareillement

Tous les identifiants sont convertis dans la forme normale NFKC pendant l'analyse
syntaxique : la comparaison des identifiants se base sur leur forme NFKC.

A non-normative HTML file listing all valid identifier characters for Unicode 4.1 can be
found at https://www.unicode.org/Public/13.0.0/ucd/DerivedCoreProperties.txt

2.3.1. Mots-clés
Les identifiants suivants sont des mots réservés par le langage et ne peuvent pas
être utilisés en tant qu'identifiants normaux. Ils doivent être écrits exactement comme
ci-dessous :

False await else import pass


None break except in raise
True class finally is return
and continue for lambda try
as def from nonlocal while
assert del global not with
async elif if or yield

2.3.2. Classes réservées pour les identifiants


Certaines classes d'identifiants (outre les mots-clés) ont une signification particulière.
Ces classes se reconnaissent par des caractères de soulignement en tête et en
queue d'identifiant :

_*
L'identifiant spécial _ n'est pas importé par from module import *. Il est utilisé
dans l'interpréteur interactif pour stocker le résultat de la dernière évaluation ; il est
stocké dans le module builtins. Lorsque vous n'êtes pas en mode interactif, _ n'a
pas de signification particulière et n'est pas défini. Voir la section L'instruction import.

Note
 

Le nom _ est souvent utilisé pour internationaliser l'affichage ; reportez-vous à la


documentation du module gettext pour plus d'informations sur cette convention.
__*__

System-defined names, informally known as "dunder" names. These names are


defined by the interpreter and its implementation (including the standard library).
Current system names are discussed in the Méthodes spéciales section and
elsewhere. More will likely be defined in future versions of Python. Any use
of __*__ names, in any context, that does not follow explicitly documented use, is
subject to breakage without warning.

__*

Noms privés pour une classe. Les noms de cette forme, lorsqu'ils sont utilisés dans
le contexte d'une définition de classe, sont réécrits sous une forme modifiée pour
éviter les conflits de noms entre les attributs « privés » des classes de base et les
classes dérivées. Voir la section Identifiants (noms).

2.4. Littéraux
Les littéraux sont des notations pour indiquer des valeurs constantes de certains
types natifs.

2.4.1. Littéraux de chaînes de caractères et de suites


d'octets
Les chaînes de caractères littérales sont définies par les définitions lexicales
suivantes :

stringliteral ::= [stringprefix](shortstring | longstring)


stringprefix ::= "r" | "u" | "R" | "U" | "f" | "F"
| "fr" | "Fr" | "fR" | "FR" | "rf" | "rF" |
"Rf" | "RF"
shortstring ::= "'" shortstringitem* "'" | '"'
shortstringitem* '"'
longstring ::= "'''" longstringitem* "'''" | '"""'
longstringitem* '"""'
shortstringitem ::= shortstringchar | stringescapeseq
longstringitem ::= longstringchar | stringescapeseq
shortstringchar ::= <any source character except "\" or newline
or the quote>
longstringchar ::= <any source character except "\">
stringescapeseq ::= "\" <any source character>
bytesliteral ::= bytesprefix(shortbytes | longbytes)
bytesprefix ::= "b" | "B" | "br" | "Br" | "bR" | "BR" | "rb"
| "rB" | "Rb" | "RB"
shortbytes ::= "'" shortbytesitem* "'" | '"' shortbytesitem*
'"'
longbytes ::= "'''" longbytesitem* "'''" | '"""'
longbytesitem* '"""'
shortbytesitem ::= shortbyteschar | bytesescapeseq
longbytesitem ::= longbyteschar | bytesescapeseq
shortbyteschar ::= <any ASCII character except "\" or newline or
the quote>
longbyteschar ::= <any ASCII character except "\">
bytesescapeseq ::= "\" <any ASCII character>

Une restriction syntaxique non indiquée par ces règles est qu'aucun blanc n'est
autorisé entre le stringprefix ou bytesprefix et le reste du littéral. Le jeu de
caractères source est défini par la déclaration d'encodage ; il vaut UTF-8 si aucune
déclaration d'encodage n'est donnée dans le fichier source ; voir la
section Déclaration d'encodage.

Description en français : les deux types de littéraux peuvent être encadrés par une
paire de guillemets simples (') ou doubles ("). Ils peuvent aussi être encadrés par
une paire de trois guillemets simples ou une paire de trois guillemets doubles (on
appelle alors généralement ces chaînes entre triples guillemets). La barre oblique
inversée peut être utilisée pour échapper des caractères qui auraient sinon une
signification spéciale, tels que le retour à la ligne, la barre oblique inversée elle-
même ou le guillemet utilisé pour délimiter la chaîne.

Les littéraux de suites d'octets sont toujours préfixés par 'b' ou 'B' ; cela crée une
instance de type bytes au lieu du type str. Ils ne peuvent contenir que des
caractères ASCII ; les octets dont la valeur est supérieure ou égale à 128 doivent
être exprimés à l'aide d'échappements.

Les chaînes et suites d'octets littérales peuvent être préfixées par la


lettre 'r' ou 'R' ; de telles chaînes sont appelées chaines brutes (raw strings en
anglais) et traitent la barre oblique inversée comme un caractère normal. En
conséquence, les chaînes littérales '\U' et '\u' ne sont pas considérées comme
spéciales. Comme les littéraux Unicode de Python 2.x se comportent différemment,
la syntaxe 'ur' n'est pas reconnue en Python 3.x.

Nouveau dans la version 3.3: le préfixe 'rb' a été ajouté comme synonyme


de 'br' pour les littéraux de suites d'octets.

Nouveau dans la version 3.3: le support du préfixe historique pour les chaînes
Unicode a été réintroduit afin de simplifier la maintenance de code compatible
Python 2.x et 3.x. Voir la PEP 414 pour davantage d'informations.

Une chaîne littérale qui contient 'f' ou 'F' dans le préfixe est une chaîne de


caractères littérale formatée ; lisez Chaînes de caractères formatées littérales.
Le 'f' peut être combiné avec 'r' mais pas avec 'b' ou 'u', donc les chaînes de
caractères formatées sont possibles mais les littéraux de suites d'octets ne peuvent
pas l'être.

Dans les chaînes entre triples guillemets, les sauts de ligne et guillemets peuvent ne
pas être échappés (et sont donc pris en compte), mais trois guillemets non échappés
à la suite terminent le littéral (on entend par guillemet le caractère utilisé pour
commencer le littéral, c'est-à-dire ' ou ").

À moins que le préfixe 'r' ou 'R' ne soit présent, les séquences d'échappement


dans les littéraux de chaînes et suites d'octets sont interprétées comme elles le
seraient par le C Standard. Les séquences d'échappement reconnues sont :

Séquence
Signification Notes
d'échappement
barre oblique inversée et retour à la ligne
\newline
ignorés

\\ barre oblique inversée (\)

\' guillemet simple (')

\" guillemet double (")

\a cloche ASCII (BEL)

\b retour arrière ASCII (BS)

\f saut de page ASCII (FF)

\n saut de ligne ASCII (LF)


Séquence
Signification Notes
d'échappement

\r retour à la ligne ASCII (CR)

\t tabulation horizontale ASCII (TAB)

\v tabulation verticale ASCII (VT)

\ooo caractère dont le code est ooo en octal (1,3)

caractère dont le code est ooo en


\xhh (2,3)
hexadécimal

Les séquences d'échappement reconnues seulement dans les chaînes littérales


sont :

Séquence
Signification Notes
d'échappement

caractère dont le nom est name dans la base de


\N{name} (4)
données Unicode
\uxxxx caractère dont le code est xxxx en hexadécimal (5)

caractère dont le code est xxxxxxxx en


\Uxxxxxxxx (6)
hexadécimal sur 32 bits

Notes :

1. Comme dans le C Standard, jusqu'à trois chiffres en base huit sont acceptés.
2. Contrairement au C Standard, il est obligatoire de fournir deux chiffres
hexadécimaux.
3. Dans un littéral de suite d'octets, un échappement hexadécimal ou octal est
un octet dont la valeur est donnée. Dans une chaîne littérale, un échappement est un
caractère Unicode dont le code est donné.

4. Modifié dans la version 3.3: Ajout du support pour les alias de noms 1.

5. Exactement quatre chiffres hexadécimaux sont requis.


6. N'importe quel caractère Unicode peut être encodé de cette façon.
Exactement huit chiffres hexadécimaux sont requis.

Contrairement au C standard, toutes les séquences d'échappement non reconnues


sont laissées inchangées dans la chaîne, c'est-à-dire que la barre oblique inversée
est laissée dans le résultat (ce comportement est utile en cas de débogage : si une
séquence d'échappement est mal tapée, la sortie résultante est plus facilement
reconnue comme source de l'erreur). Notez bien également que les séquences
d'échappement reconnues uniquement dans les littéraux de chaînes de caractères
ne sont pas reconnues pour les littéraux de suites d'octets.

Modifié dans la version 3.6: Les séquences d'échappement non reconnues


produisent un avertissement DeprecationWarning. Dans les futures versions de
Python, elles génèreront une erreur de syntaxe.

Même dans une chaîne littérale brute, les guillemets peuvent être échappés avec
une barre oblique inversée mais la barre oblique inversée reste dans le résultat ; par
exemple, r"\"" est une chaîne de caractères valide composée de deux caractères :
une barre oblique inversée et un guillemet double ; r"\" n'est pas une chaîne de
caractères valide (même une chaîne de caractères brute ne peut pas se terminer par
un nombre impair de barres obliques inversées). Plus précisément, une chaîne
littérale brute ne peut pas se terminer par une seule barre oblique inversée (puisque
la barre oblique inversée échappe le guillemet suivant). Notez également qu'une
simple barre oblique inversée suivie d'un saut de ligne est interprétée comme deux
caractères faisant partie du littéral et non comme une continuation de ligne.

2.4.2. Concaténation de chaînes de caractères


Plusieurs chaînes de caractères ou suites d'octets adjacentes (séparées par des
blancs), utilisant éventuellement des conventions de guillemets différentes, sont
autorisées. La signification est la même que leur concaténation.
Ainsi, "hello" 'world' est l'équivalent de "helloworld". Cette fonctionnalité
peut être utilisée pour réduire le nombre de barres obliques inverses, pour diviser de
longues chaînes de caractères sur plusieurs lignes ou même pour ajouter des
commentaires à des portions de chaînes de caractères. Par exemple :

re.compile("[A-Za-z_]" # letter or underscore


"[A-Za-z0-9_]*" # letter, digit or underscore
)

Notez que cette fonctionnalité agit au niveau syntaxique mais est implémentée au
moment de la compilation. Pour concaténer les expressions des chaînes de
caractères au moment de l'exécution, vous devez utiliser l'opérateur +. Notez
également que la concaténation littérale peut utiliser un style différent de guillemets
pour chaque composant (et même mélanger des chaînes de caractères brutes et des
chaînes de caractères entre triples guillemets). Enfin, les chaînes de caractères
formatées peuvent être concaténées avec des chaînes de caractères ordinaires.
2.4.3. Chaînes de caractères formatées littérales
Nouveau dans la version 3.6.

Une chaine de caractères formatée littérale ou f-string est une chaine de caractères


littérale préfixée par 'f' ou 'F'. Ces chaines peuvent contenir des champs à
remplacer, c'est-à-dire des expressions délimitées par des accolades {}. Alors que
les autres littéraux de chaines ont des valeurs constantes, les chaines formatées
sont de vraies expressions évaluées à l'exécution.

Les séquences d'échappement sont décodées comme à l'intérieur des chaînes de


caractères ordinaires (sauf lorsqu'une chaîne de caractères est également marquée
comme une chaîne brute). Après décodage, la grammaire s'appliquant au contenu
de la chaîne de caractères est :

f_string ::= (literal_char | "{{" | "}}" |


replacement_field)*
replacement_field ::= "{" f_expression ["!" conversion] [":"
format_spec] "}"
f_expression ::= (conditional_expression | "*" or_expr)
("," conditional_expression | "," "*"
or_expr)* [","]
| yield_expression
conversion ::= "s" | "r" | "a"
format_spec ::= (literal_char | NULL | replacement_field)*
literal_char ::= <any code point except "{", "}" or NULL>

Les portions qui sont en dehors des accolades sont traitées comme les littéraux, sauf
les doubles accolades '{{' ou '}}' qui sont remplacées par la simple accolade
correspondante. Une simple accolade ouvrante '{' marque le début du champ à
remplacer, qui commence par une expression Python. Après l'expression, il peut y
avoir un champ de conversion, introduit par un point d'exclamation '!'. Une
spécification de format peut aussi être ajoutée, introduite par le caractère deux-
points ':'. Le champ à remplacer se termine par une accolade fermante '}'.

Les expressions dans les chaînes de caractères formatées littérales sont traitées
comme des expressions Python normales entourées de parenthèses, à quelques
exceptions près. Une expression vide n'est pas autorisée et une
expression lambda doit être explicitement entourée de parenthèses. Les expressions
de remplacement peuvent contenir des sauts de ligne (par exemple dans les chaînes
de caractères entre triples guillemets) mais elles ne peuvent pas contenir de
commentaire. Chaque expression est évaluée dans le contexte où la chaîne de
caractères formatée apparaît, de gauche à droite.
Modifié dans la version 3.7: Prior to Python 3.7, an await expression and
comprehensions containing an async for clause were illegal in the expressions in
formatted string literals due to a problem with the implementation.

Si une conversion est spécifiée, le résultat de l'évaluation de l'expression est converti


avant d'être formaté. La conversion '!s' appelle str() sur le résultat, '!
r' appelle repr() et '!a' appelle ascii().

Le résultat est ensuite formaté en utilisant le protocole de format(). La spécification


du format est passée à la méthode __format__() de l'expression ou du résultat de
la conversion. Une chaîne vide est passée lorsque la spécification de format est
omise. Le résultat formaté est alors inclus dans la valeur finale de la chaîne
complète.

Les spécifications de format peuvent inclure des champs de remplacement


imbriqués. Ces champs imbriqués peuvent inclure leurs propres champs de
conversion et spécifications de format mais l'imbrication ne doit pas aller plus
profond. Le mini-langage de spécification de format est le même que celui utilisé par
la méthode .format() du type str.

Les chaînes formatées littérales peuvent être concaténées mais les champs à
remplacer ne peuvent pas être divisés entre les littéraux.

Quelques exemples de chaines formatées littérales :

>>>

>>> name = "Fred"


>>> f"He said his name is {name!r}."
"He said his name is 'Fred'."
>>> f"He said his name is {repr(name)}." # repr() is equivalent
to !r
"He said his name is 'Fred'."
>>> width = 10
>>> precision = 4
>>> value = decimal.Decimal("12.34567")
>>> f"result: {value:{width}.{precision}}" # nested fields
'result: 12.35'
>>> today = datetime(year=2017, month=1, day=27)
>>> f"{today:%B %d, %Y}" # using date format specifier
'January 27, 2017'
>>> number = 1024
>>> f"{number:#0x}" # using integer format specifier
'0x400'
Une conséquence de partager la même syntaxe avec les chaînes littérales normales
est que les caractères dans les champs à remplacer ne doivent pas entrer en conflit
avec le guillemet utilisé pour encadrer la chaine formatée littérale :

f"abc {a["x"]} def" # error: outer string literal ended


prematurely
f"abc {a['x']} def" # workaround: use different quoting

La barre oblique inversée (ou antislash) n'est pas autorisée dans les expressions des
champs à remplacer et son utilisation génère une erreur :

f"newline: {ord('\n')}" # raises SyntaxError

Pour inclure une valeur où l'échappement par barre oblique inversée est nécessaire,
vous devez créer une variable temporaire.

>>> newline = ord('\n')


>>> f"newline: {newline}"
'newline: 10'

Une chaine formatée littérale ne peut pas être utilisée en tant que docstring, même si
elle ne comporte pas d'expression.

>>>

>>> def foo():


... f"Not a docstring"
...
>>> foo.__doc__ is None
True

Consultez aussi la PEP 498 qui propose l'ajout des chaines formatées littérales
et str.format() qui utilise un mécanisme similaire pour formater les chaînes de
caractères.

2.4.4. Littéraux numériques
Il existe trois types de littéraux numériques : les entiers, les nombres à virgule
flottante et les nombres imaginaires. Il n'y a pas de littéraux complexes (les nombres
complexes peuvent être construits en ajoutant un nombre réel et un nombre
imaginaire).
Notez que les littéraux numériques ne comportent pas de signe ; une phrase telle
que -1 est en fait une expression composée de l'opérateur unitaire - et du littéral 1.

2.4.5. Entiers littéraux
Les entiers littéraux sont décrits par les définitions lexicales suivantes :

integer ::= decinteger | bininteger | octinteger | hexinteger


decinteger ::= nonzerodigit (["_"] digit)* | "0"+ (["_"] "0")*
bininteger ::= "0" ("b" | "B") (["_"] bindigit)+
octinteger ::= "0" ("o" | "O") (["_"] octdigit)+
hexinteger ::= "0" ("x" | "X") (["_"] hexdigit)+
nonzerodigit ::= "1"..."9"
digit ::= "0"..."9"
bindigit ::= "0" | "1"
octdigit ::= "0"..."7"
hexdigit ::= digit | "a"..."f" | "A"..."F"

Il n'y a pas de limite pour la longueur des entiers littéraux, sauf celle relative à la
capacité mémoire.

Les tirets bas sont ignorés pour déterminer la valeur numérique du littéral. Ils
peuvent être utilisés pour grouper les chiffres afin de faciliter la lecture. Un souligné
peut être placé entre des chiffres ou après la spécification de la base telle que 0x.

Notez que placer des zéros en tête de nombre pour un nombre décimal différent de
zéro n'est pas autorisé. Cela permet d'éviter l’ambigüité avec les littéraux en base
octale selon le style C que Python utilisait avant la version 3.0.

Quelques exemples d'entiers littéraux :

7 2147483647 0o177 0b100110111


3 79228162514264337593543950336 0o377 0xdeadbeef
100_000_000_000 0b_1110_0101

Modifié dans la version 3.6: Les tirets bas ne sont pas autorisés pour grouper les
littéraux.

2.4.6. Nombres à virgule flottante littéraux


Les nombres à virgule flottante littéraux sont décrits par les définitions lexicales
suivantes :
floatnumber ::= pointfloat | exponentfloat
pointfloat ::= [digitpart] fraction | digitpart "."
exponentfloat ::= (digitpart | pointfloat) exponent
digitpart ::= digit (["_"] digit)*
fraction ::= "." digitpart
exponent ::= ("e" | "E") ["+" | "-"] digitpart

Notez que la partie entière et l'exposant sont toujours interprétés comme étant en
base 10. Par exemple, 077e010 est licite et désigne le même nombre que 77e10. La
plage autorisée pour les littéraux de nombres à virgule flottante dépend de
l'implémentation. Comme pour les entiers littéraux, les soulignés permettent de
grouper des chiffres.

Quelques exemples de nombres à virgule flottante littéraux :

3.14 10. .001 1e100 3.14e-10 0e0 3.14_15_93

Modifié dans la version 3.6: Les tirets bas ne sont pas autorisés pour grouper les
littéraux.

2.4.7. Imaginaires littéraux
Les nombres imaginaires sont décrits par les définitions lexicales suivantes :

imagnumber ::= (floatnumber | digitpart) ("j" | "J")

Un littéral imaginaire produit un nombre complexe dont la partie réelle est 0.0. Les
nombres complexes sont représentés comme une paire de nombres à virgule
flottante et possèdent les mêmes restrictions concernant les plages autorisées. Pour
créer un nombre complexe dont la partie réelle est non nulle, ajoutez un nombre à
virgule flottante à votre littéral imaginaire. Par exemple (3+4j). Voici d'autres
exemples de littéraux imaginaires :

3.14j 10.j 10j .001j 1e100j 3.14e-10j 3.14_15_93j

2.5. Opérateurs
Les lexèmes suivants sont des opérateurs :

+ - * ** / // % @
<< >> & | ^ ~
< > <= >= == !=
2.6. Délimiteurs
Les lexèmes suivants servent de délimiteurs dans la grammaire :

( ) [ ] { }
, : . ; @ = ->
+= -= *= /= //= %= @=
&= |= ^= >>= <<= **=

Le point peut aussi apparaître dans les littéraux de nombres à virgule flottante et
imaginaires. Une suite de trois points possède une signification spéciale : c'est une
ellipse littérale. La deuxième partie de la liste, les opérateurs d'assignation
augmentés, servent de délimiteurs pour l'analyseur lexical mais sont aussi des
opérateurs.

Les caractères ASCII suivants ont une signification spéciale en tant que partie
d'autres lexèmes ou ont une signification particulière pour l'analyseur lexical :

' " # \

Les caractères ASCII suivants ne sont pas utilisés en Python. S'ils apparaissent en
dehors de chaines littérales ou de commentaires, ils produisent une erreur :

$ ? `

Notes

1 http://www.unicode.org/Public/11.0.0/ucd/NameAliases.txt

3. Modèle de données
3.1. Objets, valeurs et types
Objects are Python's abstraction for data. All data in a Python program is
represented by objects or by relations between objects. (In a sense, and in
conformance to Von Neumann's model of a "stored program computer", code is also
represented by objects.)

Chaque objet possède un identifiant, un type et une valeur. L'identifiant d'un objet ne


change jamais après sa création ; vous pouvez vous le représenter comme l'adresse
de l'objet en mémoire. L'opérateur is compare les identifiants de deux objets ; la
fonction id() renvoie un entier représentant cet identifiant.

CPython implementation detail: en CPython, id(x) est l'adresse mémoire où est


stocké x.

Le type de l'objet détermine les opérations que l'on peut appliquer à l'objet (par
exemple, « a-t-il une longueur ? ») et définit aussi les valeurs possibles pour les
objets de ce type. La fonction type() renvoie le type de l'objet (qui est lui-même un
objet). Comme l'identifiant, le type d'un objet ne peut pas être modifié 1.

La valeur de certains objets peut changer. Les objets dont la valeur peut changer
sont dits muables (mutable en anglais) ; les objets dont la valeur est définitivement
fixée à leur création sont dits immuables (immutable en anglais). La valeur d'un objet
conteneur immuable qui contient une référence vers un objet muable peut varier
lorsque la valeur de l'objet muable change ; cependant, le conteneur est quand
même considéré comme immuable parce que l'ensemble des objets qu'il contient ne
peut pas être modifié. Ainsi, l'immuabilité n'est pas strictement équivalente au fait
d'avoir une valeur non modifiable, c'est plus subtil. La muabilité d'un objet est définie
par son type ; par exemple, les nombres, les chaînes de caractères et les tuples sont
immuables alors que les dictionnaires et les listes sont muables.

Un objet n'est jamais explicitement détruit ; cependant, lorsqu'il ne peut plus être
atteint, il a vocation à être supprimé par le ramasse-miettes (garbage-collector en
anglais). L'implémentation peut retarder cette opération ou même ne pas la faire du
tout — la façon dont fonctionne le ramasse-miette est particulière à chaque
implémentation, l'important étant qu'il ne supprime pas d'objet qui peut encore être
atteint.

CPython implementation detail: CPython utilise aujourd'hui un mécanisme de


compteur de références avec une détection, en temps différé et optionnelle, des
cycles d'objets. Ce mécanisme supprime la plupart des objets dès qu'ils ne sont plus
accessibles mais il ne garantit pas la suppression des objets où il existe des
références circulaires. Consultez la documentation du module gc pour tout ce qui
concerne la suppression des cycles. D'autres implémentations agissent différemment
et CPython pourrait évoluer. Ne vous reposez pas sur la finalisation immédiate des
objets devenus inaccessibles (ainsi, vous devez toujours fermer les fichiers
explicitement).

Notez que si vous utilisez les fonctionnalités de débogage ou de trace de


l'implémentation, il est possible que des références qui seraient normalement
supprimées soient toujours présentes. Notez aussi que capturer une exception avec
l'instruction try...except peut conserver des objets en vie.

Certains objets font référence à des ressources « externes » telles que des fichiers
ouverts ou des fenêtres. Ces objets libèrent ces ressources au moment où ils sont
supprimés, mais comme le ramasse-miettes ne garantit pas qu'il supprime tous les
objets, ces objets fournissent également un moyen explicite de libérer la ressource
externe, généralement sous la forme d'une méthode close(). Nous incitons
fortement les programmeurs à fermer explicitement de tels objets. Les
instructions try...finally et with sont très pratiques pour cela.

Certains objets contiennent des références à d'autres objets ; on les


appelle conteneurs. Comme exemples de conteneurs, nous pouvons citer les tuples,
les listes et les dictionnaires. Les références sont parties intégrantes de la valeur
d'un conteneur. Dans la plupart des cas, lorsque nous parlons de la valeur d'un
conteneur, nous parlons des valeurs, pas des identifiants des objets contenus ;
cependant, lorsque nous parlons de la muabilité d'un conteneur, seuls les identifiants
des objets immédiatement contenus sont concernés. Ainsi, si un conteneur
immuable (comme un tuple) contient une référence à un objet muable, sa valeur
change si cet objet muable est modifié.

Presque tous les comportements d'un objet dépendent du type de l'objet. Même son
identifiant est concerné dans un certain sens : pour les types immuables, les
opérations qui calculent de nouvelles valeurs peuvent en fait renvoyer une référence
à n'importe quel objet existant avec le même type et la même valeur, alors que pour
les objets muables cela n'est pas autorisé. Par exemple,
après a = 1 ; b = 1, a et b peuvent ou non se référer au même objet avec la
valeur un, en fonction de l'implémentation. Mais après c = [] ; d = [], il est
garanti que c et d font référence à deux listes vides distinctes nouvellement créées.
Notez que c = d = [] attribue le même objet à c et d.

3.2. Hiérarchie des types standards


Vous trouvez ci-dessous une liste des types natifs de Python. Des modules
d'extension (écrits en C, Java ou d'autres langages) peuvent définir des types
supplémentaires. Les futures versions de Python pourront ajouter des types à cette
hiérarchie (par exemple les nombres rationnels, des tableaux d'entiers stockés
efficacement, etc.), bien que de tels ajouts se trouvent souvent plutôt dans la
bibliothèque standard.
Quelques descriptions des types ci-dessous contiennent un paragraphe listant des
« attributs spéciaux ». Ces attributs donnent accès à l'implémentation et n'ont, en
général, pas vocation à être utilisés. Leur définition peut changer dans le futur.

None

Ce type ne possède qu'une seule valeur. Il n'existe qu'un seul objet avec cette
valeur. Vous accédez à cet objet avec le nom natif None. Il est utilisé pour signifier
l'absence de valeur dans de nombreux cas, par exemple pour des fonctions qui ne
retournent rien explicitement. Sa valeur booléenne est fausse.

NotImplemented

Ce type ne possède qu'une seule valeur. Il n'existe qu'un seul objet avec cette
valeur. Vous accédez à cet objet avec le nom natif NotImplemented. Les méthodes
numériques et les comparaisons riches doivent renvoyer cette valeur si elles
n'implémentent pas l'opération pour les opérandes fournis (l'interpréteur essaie alors
l'opération en permutant les opérandes ou tout autre stratégie de contournement, en
fonction de l'opérateur). Sa valeur booléenne est vraie.

Consultez Implémentation des opérations arithmétiques pour davantage de détails.

Ellipse

Ce type ne possède qu'une seule valeur. Il n'existe qu'un seul objet avec cette
valeur. Vous accédez à cet objet avec le littéral ... ou le nom natif Ellipsis. Sa
valeur booléenne est vraie.

numbers.Number

Ces objets sont créés par les littéraux numériques et renvoyés en tant que résultats
par les opérateurs et les fonctions arithmétiques natives. Les objets numériques sont
immuables ; une fois créés, leur valeur ne change pas. Les nombres Python sont
bien sûr très fortement corrélés aux nombres mathématiques mais ils sont soumis
aux limitations des représentations numériques par les ordinateurs.

Python distingue les entiers, les nombres à virgule flottante et les nombres
complexes :

numbers.Integral

Ils représentent des éléments de l'ensemble mathématique des entiers (positifs ou


négatifs).

Il existe deux types d'entiers :


Entiers (int)

Ils représentent les nombres, sans limite de taille, sous réserve de pouvoir être
stockés en mémoire (virtuelle). Afin de pouvoir effectuer des décalages et appliquer
des masques, on considère qu'ils ont une représentation binaire. Les nombres
négatifs sont représentés comme une variante du complément à 2, qui donne
l'illusion d'une chaîne infinie de bits de signe s'étendant vers la gauche.

Booléens (bool)

Ils représentent les valeurs faux et vrai. Deux objets, False et True, sont les seuls


objets booléens. Le type booléen est un sous-type du type entier et les valeurs
booléennes se comportent comme les valeurs 0 (pour False) et 1 (pour True) dans
presque tous les contextes. L'exception concerne la conversion en chaîne de
caractères où "False" et "True" sont renvoyées.

Les règles pour la représentation des entiers ont pour objet de donner l'interprétation
la plus naturelle pour les opérations de décalage et masquage qui impliquent des
entiers négatifs.

numbers.Real (float)

Ils représentent les nombres à virgule flottante en double précision, tels que
manipulés directement par la machine. Vous dépendez donc de l'architecture
machine sous-jacente (et de l'implémentation C ou Java) pour les intervalles gérés et
le traitement des débordements. Python ne gère pas les nombres à virgule flottante
en précision simple ; les gains en puissance de calcul et mémoire, qui sont
généralement la raison de l'utilisation des nombres en simple précision, sont
annihilés par le fait que Python encapsule de toute façon ces nombres dans des
objets. Il n'y a donc aucune raison de compliquer le langage avec deux types de
nombres à virgule flottante.

numbers.Complex (complex)

Ils représentent les nombres complexes, sous la forme d'un couple de nombres à
virgule flottante en double précision, tels que manipulés directement par la machine.
Les mêmes restrictions s'appliquent que pour les nombres à virgule flottante. La
partie réelle et la partie imaginaire d'un nombre complexe z peuvent être demandées
par les attributs en lecture seule z.real et z.imag.

Séquences

Ils représentent des ensembles de taille finie indicés par des entiers positifs ou nuls.
La fonction native len() renvoie le nombre d'éléments de la séquence. Quand la
longueur d'une séquence est n, l'ensemble des indices contient les entiers 0, 1 ..., n-
1. On accède à l'élément d'indice i de la séquence a par a[i].

Les séquences peuvent aussi être découpées en tranches (slicing en


anglais) : a[i:j] sélectionne tous les éléments d'indice k tel que i <= k < j. Quand
on l'utilise dans une expression, la tranche est du même type que la séquence. Ceci
veut dire que l'ensemble des indices de la tranche est renuméroté de manière à
partir de 0.

Quelques séquences gèrent le « découpage étendu » (extended slicing en anglais)


avec un troisième paramètre : a[i:j:k] sélectionne tous les éléments
de a d'indice x où x = i + n*k, avec n >= 0 et i <= x < j.

Les séquences se différencient en fonction de leur muabilité :

Séquences immuables

Un objet de type de séquence immuable ne peut pas être modifié une fois qu'il a été
créé. Si l'objet contient des références à d'autres objets, ces autres objets peuvent
être muables et peuvent être modifiés ; cependant, les objets directement référencés
par un objet immuable ne peuvent pas être modifiés.

Les types suivants sont des séquences immuables :

Chaînes de caractères

Une chaîne de caractères (string en anglais) est une séquence de valeurs qui
représentent des caractères Unicode. Tout caractère dont le code est dans
l'intervalle U+0000 - U+10FFFF peut être représenté dans une chaîne. Python ne
possède pas de type char ; à la place, chaque caractère Unicode dans la chaîne est
représenté par un objet chaîne de longueur 1. La fonction native ord() convertit un
caractère Unicode de la représentation en chaîne vers un entier dans
l'intervalle 0 - 10FFFF ; la fonction chr() convertit un entier de
l'intervalle 0 - 10FFFF vers l'objet chaîne de
longueur 1 correspondant. str.encode() peut être utilisée pour convertir un
objet str vers bytes selon l'encodage spécifié et bytes.decode() effectue
l'opération inverse.

n-uplets (ou tuples)

Les éléments d'un tuple sont n'importe quels objets Python. Les tuples de deux ou
plus éléments sont formés par une liste d'expressions dont les éléments sont
séparés par des virgules. Un tuple composé d'un seul élément (un « singleton ») est
formé en suffixant une expression avec une virgule (une expression en tant que telle
ne crée pas un tuple car les parenthèses doivent rester disponibles pour grouper les
expressions). Un tuple vide peut être formé à l'aide d'une paire de parenthèses vide.

Bytes

Les objets bytes sont des tableaux immuables. Les éléments sont des octets (donc
composés de 8 bits), représentés par des entiers dans l'intervalle 0 à 255 inclus. Les
littéraux bytes (tels que b'abc') et la fonction native constructeur bytes() peuvent
être utilisés pour créer des objets bytes. Aussi, un objet bytes peut être décodé vers
une chaîne via la méthode decode().

Séquences muables

Les séquences muables peuvent être modifiées après leur création. Les notations de
tranches et de sous-ensembles peuvent être utilisées en tant que cibles d'une
assignation ou de l'instruction del (suppression).

Il existe aujourd'hui deux types intrinsèques de séquences muables :

Listes

N'importe quel objet Python peut être élément d'une liste. Les listes sont créées en
plaçant entre crochets une liste d'expressions dont les éléments sont séparés par
des virgules (notez que les listes de longueur 0 ou 1 ne sont pas des cas
particuliers).

Tableaux d'octets

Un objet bytearray est un tableau muable. Il est créé par la fonction native


constructeur bytearray(). À part la propriété d'être muable (et donc de ne pas
pouvoir calculer son empreinte par hachage), un tableau d'octets possède la même
interface et les mêmes fonctionnalités qu'un objet immuable bytes.

Le module d'extension array fournit un autre exemple de type de séquence muable,


de même que le module collections.

Ensembles

Ils représentent les ensembles d'objets, non ordonnés, finis et dont les éléments sont
uniques. Tels quels, ils ne peuvent pas être indicés. Cependant, il est possible
d'itérer dessus et la fonction native len() renvoie le nombre d'éléments de
l'ensemble. Les utilisations classiques des ensembles sont les tests d'appartenance
rapides, la suppression de doublons dans une séquence et le calcul d'opérations
mathématiques telles que l'intersection, l'union, la différence et le complémentaire.
Pour les éléments des ensembles, les mêmes règles concernant l'immuabilité
s'appliquent que pour les clés de dictionnaires. Notez que les types numériques
obéissent aux règles normales pour les comparaisons numériques : si deux nombres
sont égaux (pour l'opération de comparaison, par exemple 1 et 1.0), un seul élément
est conservé dans l'ensemble.

Actuellement, il existe deux types d'ensembles natifs :

Ensembles

Ils représentent les ensembles muables. Un ensemble est créé par la fonction native
constructeur set() et peut être modifié par la suite à l'aide de différentes méthodes,
par exemple add().

Ensembles gelés

Ils représentent les ensembles immuables. Ils sont créés par la fonction native
constructeur frozenset(). Comme un ensemble gelé est immuable et hachable, il
peut être utilisé comme élément d'un autre ensemble ou comme clé de dictionnaire.

Tableaux de correspondances

Ils représentent les ensembles finis d'objets indicés par des ensembles index
arbitraires. La notation a[k] sélectionne l'élément indicé par k dans le tableau de
correspondance a ; elle peut être utilisée dans des expressions, comme cible d'une
assignation ou avec l'instruction del. La fonction native len() renvoie le nombre
d'éléments du tableau de correspondances.

Il n'existe actuellement qu'un seul type natif pour les tableaux de correspondances :

Dictionnaires

Ils représentent les ensembles finis d'objets indicés par des valeurs presque
arbitraires. Les seuls types de valeurs non reconnus comme clés sont les valeurs
contenant des listes, des dictionnaires ou les autres types muables qui sont
comparés par valeur plutôt que par l'identifiant de l'objet. La raison de cette limitation
est qu'une implémentation efficace de dictionnaire requiert que l'empreinte par
hachage des clés reste constante dans le temps. Les types numériques obéissent
aux règles normales pour les comparaisons numériques : si deux nombres sont
égaux pour l'opération de comparaison, par exemple 1 et 1.0, alors ces deux
nombres peuvent être utilisés indifféremment pour désigner la même entrée du
dictionnaire.

Dictionaries preserve insertion order, meaning that keys will be produced in the same
order they were added sequentially over the dictionary. Replacing an existing key
does not change the order, however removing a key and re-inserting it will add it to
the end instead of keeping its old place.

Les dictionnaires sont muables : ils peuvent être créés par la


notation {...} (reportez-vous à la section Agencements de dictionnaires).

Les modules d'extensions dbm.ndbm et dbm.gnu apportent d'autres exemples de


types tableaux de correspondances, de même que le module collections.

Modifié dans la version 3.7: Dictionaries did not preserve insertion order in versions
of Python before 3.6. In CPython 3.6, insertion order was preserved, but it was
considered an implementation detail at that time rather than a language guarantee.

Types appelables

Ce sont les types sur lesquels on peut faire un appel de fonction (lisez la
section Appels) :

Fonctions allogènes

Un objet fonction allogène (ou fonction définie par l'utilisateur, mais ce n'est pas
forcément l'utilisateur courant qui a défini cette fonction) est créé par la définition
d'une fonction (voir la section Définition de fonctions). Il doit être appelé avec une
liste d'arguments contenant le même nombre d'éléments que la liste des paramètres
formels de la fonction.

Attributs spéciaux :

Attribut Signification

Chaîne de documentation de la fonction


Accessible
__doc__ ou None s'il n'en existe pas ; n'est pas héritée
en écriture
par les sous-classes

Accessible
__name__ Nom de la fonction
en écriture

qualified name de la fonction


Accessible
__qualname__
en écriture
Nouveau dans la version 3.3.

Nom du module où la fonction est définie Accessible


__module__
ou None si ce nom n'est pas disponible. en écriture
__defaults__ Tuple contenant les valeurs des arguments Accessible
par défaut pour ceux qui en sont dotés en écriture
Attribut Signification

ou None si aucun argument n'a de valeur par


défaut.

Objet code représentant le corps de la Accessible


__code__
fonction compilée. en écriture

Référence pointant vers le dictionnaire


Accessible
contenant les variables globales de la
__globals__ en lecture
fonction — l'espace de noms global du
seule
module dans lequel la fonction est définie.

Espace de nommage accueillant les attributs Accessible


__dict__
de la fonction. en écriture
None ou tuple de cellules qui contient un lien
Accessible
pour chaque variable libre de la fonction.
__closure__ en lecture
Voir ci-dessous pour les informations
seule
relatives à l'attribut cell_contents.

Dictionnaire contenant les annotations des


paramètres. Les clés du dictionnaire sont les
noms des paramètres et la clé "return" est
Accessible
__annotations__ utilisée pour les annotations de la valeur
en écriture
renvoyée. Les entrées du dictionnaire ne sont
présentes que si les paramètres sont
effectivement annotés.

Dictionnaire contenant les valeurs par défaut Accessible


__kwdefaults__
pour les paramètres passés par mot-clé. en écriture

La plupart des attributs étiquetés « Accessible en écriture » vérifient le type de la


valeur qu'on leur assigne.

Les objets fonctions acceptent également l'assignation et la lecture d'attributs


arbitraires. Vous pouvez utiliser cette fonctionnalité pour, par exemple, associer des
métadonnées aux fonctions. La notation classique par point est utilisée pour définir et
lire de tels attributs. Notez que l'implémentation actuelle accepte seulement les
attributs de fonction sur les fonctions définies par l'utilisateur. Les attributs de
fonction pour les fonctions natives seront peut-être acceptés dans le futur.

Un objet cellule possède un attribut cell_contents. Il peut être utilisé pour obtenir


la valeur de la cellule et pour en définir la valeur.
Vous trouvez davantage d'informations sur la définition de fonctions dans le code de
cet objet ; la description des types internes est donnée plus bas.

Méthodes d'instances

Un objet méthode d'instance combine une classe, une instance de classe et tout
objet appelable (normalement une fonction définie par l'utilisateur).

Attributs spéciaux en lecture seule : __self__ est l'objet instance de


classe, __func__ est l'objet fonction ; __doc__ est la documentation de la méthode
(comme __func__.__doc__) ; __name__ est le nom de la méthode
(comme __func__.__name__) ; __module__ est le nom du module où la méthode
est définie ou None s'il n'est pas disponible.

Les méthodes savent aussi accéder (mais pas modifier) les attributs de la fonction de
l'objet fonction sous-jacent.

Les objets méthodes définies par l'utilisateur peuvent être créés quand vous
récupérez un attribut de classe (par exemple via une instance de cette classe) si cet
attribut est un objet fonction définie par l'utilisateur ou un objet méthode de classe.

Quand un objet méthode d'instance est créé à partir d'un objet fonction définie par
l'utilisateur via une des instances, son attribut __self__ est l'instance et l'objet
méthode est réputé lié. Le nouvel attribut de la méthode __func__ est l'objet
fonction original.

Quand un objet méthode définie par l'utilisateur est créé à partir d'un autre objet
méthode de la classe ou de l'instance, son comportement est identique à l'objet
fonction sauf pour l'attribut __func__ de la nouvelle instance qui n'est pas l'objet
méthode original mais son attribut __func__.

Quand un objet méthode d'instance est créé à partir d'un autre objet méthode de la
classe ou de l'instance, son attribut __self__ est la classe elle-même et son
attribut __func__ est l'objet fonction sous-jacent la méthode de classe.

Quand un objet méthode d'instance est appelé, la fonction sous-jacente ( __func__)


est appelée et l'objet instance de la classe ( __self__) est inséré en tête de liste des
arguments. Par exemple, si C est une classe qui contient la définition d'une
fonction f() et que x est une instance de C, alors appeler x.f(1) est équivalent à
appeler C.f(x, 1).

Quand un objet méthode d'instance est dérivé à partir d'un objet méthode de classe,
l'instance de classe stockée dans __self__ est en fait la classe elle-même. Ainsi,
appeler x.f(1) ou C.f(1) est équivalent à appeler f(C, 1) où f est la fonction
sous-jacente.

Notez que la transformation d'objet fonction en objet méthode d'instance se produit à


chaque fois que l'attribut est récupéré à partir de l'instance. Dans certains cas,
assigner l'attribut à une variable locale et appeler cette variable locale constitue une
bonne optimisation. Notez aussi que cette transformation n'a lieu que pour les
fonctions définies par l'utilisateur : les autres objets appelables (et les objets non
appelables) sont récupérés sans transformation. Il est aussi important de noter que
les fonctions définies par l'utilisateur qui sont attributs d'une instance de classe ne
sont pas converties en méthodes liées ; ceci n'a lieu que pour les fonctions qui sont
attributs de la classe.

Fonctions générateurs

Une fonction ou une méthode qui utilise l'instruction yield (voir la


section L'instruction yield) est appelée fonction générateur. Une telle fonction,
lorsqu'elle est appelée, retourne toujours un objet itérateur qui peut être utilisé pour
exécuter le corps de la fonction : appeler la méthode iterator.__next__() de
l'itérateur exécute la fonction jusqu'à ce qu'elle renvoie une valeur à l'aide de
l'instruction yield. Quand la fonction exécute l'instruction return ou se termine,
une exception StopIteration est levée et l'itérateur a atteint la fin de l'ensemble de
valeurs qu'il peut renvoyer.

Fonctions coroutines

Une fonction ou méthode définie en utilisant async def est appelée fonction


coroutine. Une telle fonction, quand elle est appelée, renvoie un objet coroutine. Elle
peut contenir des expressions await ou async with ou des
instructions async for. Voir également la section Objets coroutines.

Fonctions générateurs asynchrones

Une fonction ou une méthode définie avec async def et qui utilise


l'instruction yield est appelée fonction générateur asynchrone. Une telle fonction,
quand elle est appelée, renvoie un objet itérateur asynchrone qui peut être utilisé
dans des instructions async for pour exécuter le corps de la fonction.

Appeler la méthode aiterator.__anext__() de l'itérateur asynchrone renvoie


un awaitable qui, lorsqu'on l'attend, s'exécute jusqu'à ce qu'il fournisse une valeur à
l'aide de l'expression yield. Quand la fonction exécute une instruction return (sans
valeur) ou arrive à la fin, une exception StopAsynciteration est levée et l'itérateur
asynchrone a atteint la fin de l'ensemble des valeurs qu'il peut produire.
Fonctions natives

Un objet fonction native est une enveloppe autour d'une fonction C. Nous pouvons
citer len() et math.sin() (math est un module standard natif) comme fonctions
natives. Le nombre et le type des arguments sont déterminés par la fonction C. Des
attributs spéciaux en lecture seule existent : __doc__ contient la chaîne de
documentation de la fonction (ou None s'il n'y en a pas) ; __name__ est le nom de la
fonction ; __self__ est défini à None ; __module__ est le nom du module où la
fonction est définie ou None s'il n'est pas disponible.

Méthodes natives

Ce sont des fonctions natives déguisées, contenant un objet passé à une fonction C
en tant qu'argument supplémentaire implicite. Un exemple de méthode native
est une_liste.append() (une_liste étant un objet liste). Dans ce cas, l'attribut
spécial en lecture seule __self__ est défini à l'objet une_liste.

Classes

Les classes sont des appelables. Ces objets sont normalement utilisés pour créer
des instances d'elles-mêmes mais des variations sont possibles pour les types de
classes qui surchargent __new__(). Les arguments de l'appel sont passés
à __new__() et, dans le cas classique, __new__() initialise une nouvelle instance.

Instances de classe

Les instances d'une classe peuvent devenir des appelables si vous définissez la
méthode __call__() de leur classe.

Modules

Les modules constituent l'organisation de base du code Python et sont créés par
le mécanisme d'import soit avec l'instruction import, soit en appelant des fonctions
telles que importlib.import_module() ou la fonction native __import__(). Un
objet module possède un espace de nommage implémenté par un objet dictionnaire
(c'est le dictionnaire référencé par l'attribut __globals__ des fonctions définies dans
le module). Les références à un attribut sont traduites en recherches dans ce
dictionnaire, par exemple m.x est équivalent à m.__dict__["x"]. Un objet module
ne contient pas l'objet code utilisé pour initialiser le module (puisque celui-ci n'est
plus nécessaire une fois l'initialisation terminée).

L'assignation d'un attribut met à jour le dictionnaire d'espace de nommage du


module, par exemple m.x = 1 est équivalent à m.__dict__["x"] = 1.
Attributs prédéfinis (en lecture-écriture) : __name__ est le nom du
module ; __doc__ est la chaîne de documentation du module (ou None s'il n'y en a
pas) ; __annotations__ (optionnel) est un dictionnaire contenant les annotations
de variables collectées durant l'exécution du corps du module ; __file__ est le
chemin vers le fichier à partir duquel le module a été chargé, s'il a été chargé depuis
un fichier. L'attribut __file__ peut être manquant pour certains types de modules,
tels que les modules C qui sont statiquement liés à l'interpréteur ; pour les modules
d'extension chargés dynamiquement à partir d'une bibliothèque partagée, c'est le
chemin vers le fichier de la bibliothèque partagée.

Attribut spécial en lecture seule : __dict__ est l'objet dictionnaire répertoriant


l'espace de nommage du module.

CPython implementation detail: en raison de la manière dont CPython nettoie les


dictionnaires de modules, le dictionnaire du module est effacé quand le module n'est
plus visible, même si le dictionnaire possède encore des références actives. Pour
éviter ceci, copiez le dictionnaire ou gardez le module dans votre champ de visibilité
tant que vous souhaitez utiliser le dictionnaire directement.
Classes déclarées par le développeur

Le type d'une classe déclarée par le développeur est créé au moment de la définition
de la classe (voir la section Définition de classes). Une classe possède un espace de
nommage implémenté sous la forme d'un objet dictionnaire. Les références vers les
attributs de la classe sont traduits en recherches dans ce dictionnaire, par
exemple C.x est traduit en C.__dict__["x"] (bien qu'il existe un certain nombre
de fonctions automatiques qui permettent de trouver des attributs par d'autres
moyens). Si le nom d'attribut n'est pas trouvé dans ce dictionnaire, la recherche
continue dans les classes de base. Les classes de base sont trouvées en utilisant
l'ordre de résolution des méthodes (method resolution order en anglais, ou
MRO) C3 qui a un comportement cohérent même en présence d'héritages en
"diamant", où différentes branches d'héritages conduisent vers un ancêtre commun.
Vous trouverez plus de détails sur l'ordre de résolution des méthodes MRO C3 utilisé
par Python dans la documentation de la version 2.3 disponible
sur https://www.python.org/download/releases/2.3/mro/.

Quand une référence à un attribut de classe (disons la classe C) pointe vers un objet
méthode de classe, elle est transformée en objet méthode d'instance dont
l'attribut __self__ est C. Quand elle pointe vers un objet méthode statique, elle est
transformée en objet encapsulé par l'objet méthode statique. Reportez-vous à la
section Implémentation de descripteurs pour une autre manière dont les attributs
d'une classe diffèrent de ceux réellement contenus dans son __dict__.
Les assignations d'un attribut de classe mettent à jour le dictionnaire de la classe,
jamais le dictionnaire d'une classe de base.

Un objet classe peut être appelé (voir ci-dessus) pour produire une instance de
classe (voir ci-dessous).

Attributs spéciaux : __name__ est le nom de la classe ; __module__ est le nom du


module dans lequel la classe est définie ; __dict__ est le dictionnaire contenant
l'espace de nommage de la classe ; __bases__ est un tuple contenant les classes
de base, dans l'ordre d'apparition dans la liste des classes de base ; __doc__ est la
chaîne de documentation de la classe (ou None si elle n'existe
pas) ; __annotations__ (optionnel) est un dictionnaire contenant les annotations
de variables collectées durant l'exécution du corps de la classe.

Instances de classes

Une instance de classe est créée en appelant un objet classe (voir ci-dessus). Une
instance de classe possède un espace de nommage implémenté sous la forme d'un
dictionnaire qui est le premier endroit où sont recherchées les références aux
attributs. Quand un attribut n'est pas trouvé dans ce dictionnaire et que la classe de
l'instance contient un attribut avec ce nom, la recherche continue avec les attributs
de la classe. Si un attribut de classe est trouvé et que c'est un objet fonction définie
par l'utilisateur, il est transformé en objet méthode d'instance dont
l'attribut __self__ est l'instance. Les objets méthodes statiques et méthodes de
classe sont aussi transformés ; reportez-vous ci-dessous à « Classes ». Lisez la
section Implémentation de descripteurs pour une autre façon de récupérer les
attributs d'une classe, où la récupération via ses instances peut différer des objets
réellement stockés dans le __dict__ de la classe. Si aucun attribut de classe n'est
trouvé et que la classe de l'objet possède une méthode __getattr__(), cette
méthode est appelée pour rechercher une correspondance.

Les assignations et suppressions d'attributs mettent à jour le dictionnaire de


l'instance, jamais le dictionnaire de la classe. Si la classe possède une
méthode __setattr__() ou __delattr__(), elle est appelée au lieu de mettre à
jour le dictionnaire de l'instance directement.

Les instances de classes peuvent prétendre être des nombres, des séquences ou
des tableaux de correspondance si elles ont des méthodes avec des noms spéciaux.
Voir la section Méthodes spéciales.

Attributs spéciaux : __dict__ est le dictionnaire des attributs ; __class__ est la


classe de l'instance.
Objets Entrées-Sorties (ou objets fichiers)

Un objet fichier représente un fichier ouvert. Différents raccourcis existent pour créer


des objets fichiers : la fonction native open() et
aussi os.popen(), os.fdopen() ou la méthode makefile() des objets
connecteurs (et sûrement d'autres fonctions ou méthodes fournies par les modules
d'extensions).

Les objets sys.stdin, sys.stdout et sys.stderr sont initialisés à des objets


fichiers correspondant à l'entrée standard, la sortie standard et le flux d'erreurs de
l'interpréteur ; ils sont tous ouverts en mode texte et se conforment donc à l'interface
définie par la classe abstraite io.TextIOBase.

Types internes

Quelques types utilisés en interne par l'interpréteur sont accessibles à l'utilisateur.


Leur définition peut changer dans les futures versions de l'interpréteur mais ils sont
donnés ci-dessous à fin d'exhaustivité.

Objets Code

Un objet code représente le code Python sous sa forme compilée en bytecode. La


différence entre un objet code et un objet fonction est que l'objet fonction contient
une référence explicite vers les globales de la fonction (le module dans lequel elle
est définie) alors qu'un objet code ne contient aucun contexte ; par ailleurs, les
valeurs par défaut des arguments sont stockées dans l'objet fonction, pas dans
l'objet code (parce que ce sont des valeurs calculées au moment de l'exécution).
Contrairement aux objets fonctions, les objets codes sont immuables et ne
contiennent aucune référence (directe ou indirecte) à des objets muables.

Special read-only attributes: co_name gives the function name; co_argcount is the


number of positional arguments (including arguments with default
values); co_nlocals is the number of local variables used by the function (including
arguments); co_varnames is a tuple containing the names of the local variables
(starting with the argument names); co_cellvars is a tuple containing the names of
local variables that are referenced by nested functions; co_freevars is a tuple
containing the names of free variables; co_code is a string representing the
sequence of bytecode instructions; co_consts is a tuple containing the literals used
by the bytecode; co_names is a tuple containing the names used by the
bytecode; co_filename is the filename from which the code was
compiled; co_firstlineno is the first line number of the function; co_lnotab is a
string encoding the mapping from bytecode offsets to line numbers (for details see
the source code of the interpreter); co_stacksize is the required stack
size; co_flags is an integer encoding a number of flags for the interpreter.
Les drapeaux suivants sont codés par des bits dans co_flags : le bit 0x04 est
positionné à 1 si la fonction utilise la syntaxe *arguments pour accepter un nombre
arbitraire d'arguments positionnels ; le bit 0x08 est positionné à 1 si la fonction utilise
la syntaxe **keywords pour accepter un nombre arbitraire d'arguments nommés ; le
bit 0x20 est positionné à 1 si la fonction est un générateur.

Les déclarations de fonctionnalité


future from __future__ import division utilisent aussi des bits
dans co_flags pour indiquer si l'objet code a été compilé avec une fonctionnalité
future : le bit 0x2000 est positionné à 1 si la fonction a été compilée avec la division
future activée ; les bits 0x10 et 0x1000 étaient utilisés dans les versions antérieures
de Python.

Les autres bits de co_flags sont réservés à un usage interne.

Si l'objet code représente une fonction, le premier élément dans co_consts est la


chaîne de documentation de la fonction (ou None s'il n'y en a pas).

Objets cadres

Un objet cadre représente le cadre d'exécution. Il apparait dans des objets traces
(voir plus loin) et est passé comme argument aux fonctions de traçage actives.

Attributs spéciaux en lecture seule : f_back pointe vers le cadre précédent


(l'appelant) ou None si c'est le pied de la pile d'appel ; f_code est l'objet code en
cours d'exécution dans ce cadre ; f_locals est le dictionnaire dans lequel sont
cherchées les variables locales ; f_globals est utilisé pour les variables
globales ; f_builtins est utilisé pour les noms natifs ; f_lasti donne l'instruction
précise (c'est un indice dans la chaîne de bytecode de l'objet code).

Attributs spéciaux en lecture-écriture : f_trace, s'il n'est pas None, c'est une


fonction appelée à différentes occasions durant l'exécution du code (elle est utilisée
par le débogueur). Normalement, un événement est déclenché pour chaque ligne de
code source — ce comportement peut être désactivé en
définissant f_trace_lines à False.

Une implémentation peut autoriser le déclenchement des


événements opcode par opcode en définissant f_trace_opcodes à True. Notez
que cela peut conduire à un comportement erratique de l'interpréteur si des
exceptions levées la fonction de traçage s'échappent vers la fonction en train d'être
tracée.
f_lineno est le numéro de la ligne courante du cadre — écrire dedans depuis une
fonction trace fait sauter à la ligne demandée (seulement pour le cadre le plus bas).
Un débogueur peut implémenter une commande « sauter vers » (aussi appelée
« Définir la prochaine instruction » ou Set Next Statement en anglais) en écrivant
dans f_lineno.

Les objets cadres comprennent une méthode :

frame.clear()

Cette méthode efface toutes les références aux variables locales conservées dans le
cadre. Par ailleurs, si le cadre est celui d'un générateur, le générateur se termine.
Ceci permet de casser des références cycliques qui incluent des objets cadres (par
exemple, lors de la capture d'une exception et du stockage de la pile d'appels pour
une utilisation future).

RuntimeError est levée si le cadre est en cours d'exécution.

Nouveau dans la version 3.4.

Objets traces

Les objets traces représentent la pile de traces d'une exception. Un objet trace est
implicitement créé quand une exception apparaît et peut être explicitement créé en
appelant types.TracebackType.

Pour les traces créées implicitement, quand l'interpréteur recherche un gestionnaire


d'exception en remontant la pile d'exécution, un objet trace est inséré devant l'objet
trace courant à chaque nouveau niveau. Quand il entre dans le gestionnaire
d'exception, la pile d'appels est rendue accessible au programme (voir la
section L'instruction try). Elle est accessible par le troisième élément du tuple
renvoyé par sys.exc_info() et comme attribut __traceback__ de l'exception qui
est traitée.

Quand le programme ne contient aucun gestionnaire adéquat, la pile de traces est


écrite (joliment formatée) sur la sortie d'erreur standard ; si l'interpréteur est interactif,
elle est rendue disponible pour l'utilisateur en tant que sys.last_traceback.

Pour les traces créées explicitement, il revient au créateur de la trace de déterminer


comment les attributs tb_next doivent être liés pour former la pile complète des
traces.

Attributs spéciaux en lecture seule : tb_frame pointe vers le cadre d'exécution du


niveau courant ; tb_lineno donne le numéro de ligne où l'exception a été
levée ; tb_lasti indique l'instruction précise. Le numéro de ligne et la dernière
instruction dans la trace peuvent différer du numéro de ligne de l'objet cadre si
l'exception a eu lieu dans une instruction try sans qu'il n'y ait de
clause except adéquate ou sans clause finally.

Attributs spéciaux en lecture-écriture tb_next est le niveau suivant dans la pile


d'exécution (en direction du cadre où l'exception a eu lieu) ou None s'il n'y a pas de
niveau suivant.

Modifié dans la version 3.7: Les objets de traces d'appels peuvent maintenant être
explicitement instanciés depuis le code Python et l'attribut tb_next des instances
existantes peut être mis à jour.

Objets tranches

Un objet tranche est utilisé pour représenter des découpes des


méthodes __getitem__(). Ils sont aussi créés par la fonction native slice().

Attributs spéciaux en lecture seule : start est la borne inférieure ; stop est la borne


supérieure ; step est la valeur du pas ; chaque attribut vaut None s'il est omis. Ces
attributs peuvent être de n'importe quel type.

Les objets tranches comprennent une méthode :

slice.indices(self, length)

Cette méthode prend un argument entier length et calcule les informations de la


tranche que l'objet découpe décrit s'il est appliqué à une séquence
de length éléments. Elle renvoie un tuple de trois entiers ; respectivement, ce sont
les indices de début et fin ainsi que le pas de découpe. Les indices manquants ou en
dehors sont gérés de manière cohérente avec les tranches normales.

Objets méthodes statiques

Les objets méthodes statiques permettent la transformation des objets fonctions en


objets méthodes décrits au-dessus. Un objet méthode statique encapsule tout autre
objet, souvent un objet méthode définie par l'utilisateur. Quand un objet méthode
statique est récupéré depuis une classe ou une instance de classe, l'objet réellement
renvoyé est un objet encapsulé, qui n'a pas vocation à être transformé encore une
fois. Les objets méthodes statiques ne sont pas appelables en tant que tels, bien que
les objets qu'ils encapsulent le soient souvent. Les objets méthodes statiques sont
créés par le constructeur natif staticmethod().

Objets méthodes de classes


Un objet méthode de classe, comme un objet méthode statique, encapsule un autre
objet afin de modifier la façon dont cet objet est récupéré depuis les classes et
instances de classes. Le comportement des objets méthodes de classes dans le cas
d'une telle récupération est décrit plus haut, dans « méthodes définies par
l'utilisateur ». Les objets méthodes de classes sont créés par le constructeur
natif classmethod().

3.3. Méthodes spéciales
Une classe peut implémenter certaines opérations que l'on invoque par une syntaxe
spéciale (telles que les opérations arithmétiques ou la découpe en tranches) en
définissant des méthodes aux noms particuliers. C'est l'approche utilisée par Python
pour la surcharge d'opérateur, permettant à une classe de définir son propre
comportement vis-à-vis des opérateurs du langage. Par exemple, si une classe
définit une méthode __getitem__() et que x est une instance de cette classe,
alors x[i] est globalement équivalent à type(x).__getitem__(x, i). Sauf
lorsque c'est mentionné, toute tentative d'appliquer une opération alors que la
méthode appropriée n'est pas définie lève une exception
(typiquement AttributeError ou TypeError).

Définir une méthode spéciale à None indique que l'opération correspondante n'est


pas disponible. Par exemple, si une classe assigne None à __iter__(), vous ne
pouvez pas itérer sur la classe et appeler iter() sur une instance
lève TypeError (sans se replier sur __getitem__()) 2.

Lorsque vous implémentez une classe qui émule un type natif, il est important que
cette émulation n'implémente que ce qui fait sens pour l'objet qui est modélisé. Par
exemple, la recherche d'éléments individuels d'une séquence peut faire sens, mais
pas l'extraction d'une tranche (un exemple est l'interface de NodeList dans le
modèle objet des documents W3C).

3.3.1. Personnalisation de base
object.__new__(cls[, ...])

Appelée pour créer une nouvelle instance de la classe cls. La


méthode __new__() est statique (c'est un cas particulier, vous n'avez pas besoin de
la déclarer comme telle) qui prend comme premier argument la classe pour laquelle
on veut créer une instance. Les autres arguments sont ceux passés à l'expression de
l'objet constructeur (l'appel à la classe). La valeur de retour de __new__() doit être
l'instance du nouvel objet (classiquement une instance de cls).
Une implémentation typique crée une nouvelle instance de la classe en invoquant la
méthode __new__() de la superclasse à l'aide
de super().__new__(cls[, ...]) avec les arguments adéquats, puis modifie
l'instance nouvellement créée en tant que de besoin avant de la renvoyer.

Si __new__() renvoie une instance de cls, alors la méthode __init__() de la


nouvelle instance est invoquée avec __init__(self[, ...]) où self est la
nouvelle instance et les autres arguments sont les mêmes que ceux passés
à __new__().

Si __new__() ne renvoie pas une instance de cls, alors la méthode __init__() de


la nouvelle instance n'est pas invoquée.

L'objectif de __new__() est principalement, pour les sous-classes de types


immuables (comme int, str ou tuple), d'autoriser la création sur mesure des
instances. Elle est aussi souvent surchargée dans les méta-classes pour
particulariser la création des classes.

object.__init__(self[, ...])

Appelée après la création de l'instance (par __new__()), mais avant le retour vers


l'appelant. Les arguments sont ceux passés à l'expression du constructeur de classe.
Si une classe de base possède une méthode __init__(), la
méthode __init__() de la classe dérivée, si elle existe, doit explicitement appeler
cette méthode pour assurer une initialisation correcte de la partie classe de base de
l'instance ; par exemple : super().__init__([args...]).

Comme __new__() et __init__() travaillent ensemble pour créer des objets


(__new__() pour le créer, __init__() pour le particulariser), __init__() ne doit
pas renvoyer de valeur None ; sinon une exception TypeError est levée à
l'exécution.

object.__del__(self)

Appelée au moment où une instance est sur le point d'être détruite. On l'appelle
aussi finaliseur ou (improprement) destructeur. Si une classe de base possède une
méthode __del__(), la méthode __del__() de la classe dérivée, si elle existe, doit
explicitement l'appeler pour s'assurer de l'effacement correct de la partie classe de
base de l'instance.

Il est possible (mais pas recommandé) que la méthode __del__() retarde la


destruction de l'instance en créant une nouvelle référence vers cet objet. Python
appelle ceci la résurrection d'objet. En fonction de l'implémentation, __del__() peut
être appelée une deuxième fois au moment où l'objet ressuscité va être détruit  ;
l'implémentation actuelle de CPython ne l'appelle qu'une fois.

Il n'est pas garanti que soient appelées les méthodes __del__() des objets qui
existent toujours quand l'interpréteur termine.

Note
 

del x n'appelle pas directement x.__del__() — la première décrémente le


compteur de références de x. La seconde n'est appelée que quand le compteur de
références de x atteint zéro.
CPython implementation detail: It is possible for a reference cycle to prevent the
reference count of an object from going to zero. In this case, the cycle will be later
detected and deleted by the cyclic garbage collector. A common cause of reference
cycles is when an exception has been caught in a local variable. The frame's locals
then reference the exception, which references its own traceback, which references
the locals of all frames caught in the traceback.
Voir aussi

Documentation du module gc.

Avertissement
 

En raison des conditions particulières qui règnent quand __del__() est appelée, les


exceptions levées pendant son exécution sont ignorées et, à la place, un
avertissement est affiché sur sys.stderr. En particulier :
 __del__() peut être invoquée quand du code arbitraire est en cours
d'exécution, et ce dans n'importe quel fil d'exécution. Si __del__() a besoin de
poser un verrou ou d'accéder à tout autre ressource bloquante, elle peut provoquer
un blocage mutuel (deadlock en anglais) car la ressource peut être déjà utilisée par
le code qui est interrompu pour exécuter la méthode __del__().
 __del__() peut être exécutée pendant que l'interpréteur se ferme. En
conséquence, les variables globales auxquelles elle souhaite accéder (y compris les
autres modules) peuvent déjà être détruites ou assignées à None. Python garantit
que les variables globales dont le nom commence par un tiret bas sont supprimées
de leur module avant que les autres variables globales ne le soient ; si aucune autre
référence vers ces variables globales n'existe, cela peut aider à s'assurer que les
modules importés soient toujours accessibles au moment où la
méthode __del__() est appelée.
object.__repr__(self)

Appelée par la fonction native repr() pour calculer la représentation « officielle » en


chaîne de caractères d'un objet. Tout est fait pour que celle-ci ressemble à une
expression Python valide pouvant être utilisée pour recréer un objet avec la même
valeur (dans un environnement donné). Si ce n'est pas possible, une chaîne de la
forme <...une description utile...> est renvoyée. La valeur renvoyée doit
être un objet chaîne de caractères. Si une classe définit __repr__() mais
pas __str__(), alors __repr__() est aussi utilisée quand une représentation
« informelle » en chaîne de caractères est demandée pour une instance de cette
classe.

Cette fonction est principalement utilisée à fins de débogage, il est donc important
que la représentation donne beaucoup d'informations et ne soit pas ambigüe.

object.__str__(self)

Appelée par str(objet) ainsi que les fonctions natives format() et print() pour


calculer une chaîne de caractères « informelle » ou joliment mise en forme de
représentation de l'objet. La valeur renvoyée doit être un objet string.

Cette méthode diffère de object.__repr__() car il n'est pas attendu


que __str__() renvoie une expression Python valide : une représentation plus
agréable à lire ou plus concise peut être utilisée.

C'est l'implémentation par défaut des appels à object.__repr__() du type


natif object.

object.__bytes__(self)

Appelée par bytes pour calculer une représentation en chaîne bytes d'un objet. Elle


doit renvoyer un objet bytes.

object.__format__(self, format_spec)

Appelée par la fonction native format() et, par extension, lors de l'évaluation


de formatted string literals et la méthode str.format(). Elle produit une chaîne de
caractères « formatée » représentant un objet. L'argument format_spec est une
chaîne de caractères contenant la description des options de formatage voulues.
L'interprétation de l'argument format_spec est laissée au type
implémentant __format__(). Cependant, la plupart des classes délèguent le
formatage aux types natifs ou utilisent une syntaxe similaire d'options de formatage.

Lisez Mini-langage de spécification de format pour une description de la syntaxe


standard du formatage.

La valeur renvoyée doit être un objet chaîne de caractères.

Modifié dans la version 3.4: La méthode __format__ de object lui-même lève


une TypeError si vous lui passez une chaîne non vide.

Modifié dans la version 3.7:  object.__format__(x, '') est maintenant


équivalent à str(x) plutôt qu'à format(str(self), '').

object.__lt__(self, other)

object.__le__(self, other)

object.__eq__(self, other)

object.__ne__(self, other)

object.__gt__(self, other)

object.__ge__(self, other)

Ce sont les méthodes dites de « comparaisons riches ». La correspondance entre


les symboles opérateurs et les noms de méthodes est la
suivante : x<y appelle x.__lt__(y), x<=y appelle x.__le__(y), x==y appelle x._
_eq__(y), x!=y appelle x.__ne__(y), x>y appelle x.__gt__(y) et x>=y appelle 
x.__ge__(y).

Une méthode de comparaison riche peut renvoyer le singleton NotImplemented si


elle n'implémente pas l'opération pour une paire donnée d'arguments. Par
convention, False et True sont renvoyées pour une comparaison qui a réussi.
Cependant, ces méthodes peuvent renvoyer n'importe quelle valeur donc, si
l'opérateur de comparaison est utilisé dans un contexte booléen (par exemple dans
une condition d'une instruction if), Python appelle bool() sur la valeur pour
déterminer si le résultat est faux ou vrai.

Par défaut, __ne__() délègue à __eq__() et renvoie le résultat inverse, sauf si


c'est NotImplemented. Il n'y a pas d'autres relations implicites pour les opérateurs
de comparaison. Par exemple, (x<y or x==y) n'implique pas x<=y. Pour obtenir
une relation d'ordre total automatique à partir d'une seule opération, reportez-vous
à functools.total_ordering().

Lisez le paragraphe __hash__() pour connaitre certaines notions importantes


relatives à la création d'objets hashable qui acceptent les opérations de comparaison
personnalisées et qui sont utilisables en tant que clés de dictionnaires.

Il n'y a pas de versions avec les arguments interchangés de ces méthodes (qui


seraient utilisées quand l'argument de gauche ne connaît pas l'opération alors que
l'argument de droite la connaît) ; en lieu et place, __lt__() et __gt__() sont la
réflexion l'une de l'autre, __le__() et __ge__() sont la réflexion l'une de l'autre
et __eq__() ainsi que __ne__() sont réflexives. Si les opérandes sont de types
différents et que l'opérande de droite est d'un type qui une sous-classe directe ou
indirecte du type de l'opérande de gauche, alors la méthode symétrique de
l'opérande de droite est prioritaire, sinon c'est la méthode de l'opérande de gauche
qui est prioritaire. Les sous-classes virtuelles ne sont pas prises en compte.

object.__hash__(self)

Appelée par la fonction native hash() et par les opérations sur les membres de
collections hachées (ce qui comprend set, frozenset et dict). __hash__() doit
renvoyer un entier. La seule propriété requise est que les objets qui sont égaux pour
la comparaison doivent avoir la même valeur de hachage ; il est conseillé de
mélanger les valeurs de hachage des composants d'un objet qui jouent un rôle de la
comparaison des objets, en les plaçant un tuple dont on calcule l'empreinte. Par
exemple :

def __hash__(self):
return hash((self.name, self.nick, self.color))
Note
 

hash() limite la valeur renvoyée d'un objet ayant une


méthode __hash__() personnalisée à la taille d'un Py_ssize_t. C'est
classiquement 8 octets pour une implémentation 64 bits et 4 octets sur une
implémentation 32 bits. Si la méthode __hash__() d'un objet doit être interopérable
sur des plateformes ayant des implémentations différentes, assurez-vous de vérifier
la taille du hachage sur toutes les plateformes. Une manière facile de le faire est la
suivante : python -c "import sys; print(sys.hash_info.width)".

Si une classe ne définit pas de méthode __eq__(), elle ne doit pas définir


l'opération __hash__() non plus ; si elle définit __eq__() mais pas __hash__(),
les instances ne peuvent pas être utilisées en tant qu'élément dans une collection de
hachables. Si une classe définit des objets mutables et implémente la
méthode __eq__(), elle ne doit pas implémenter __hash__() puisque
l'implémentation des collections hachables requiert que les clés soient des
empreintes immuables (si l'empreinte d'un objet change, il ne sera plus trouvé
correctement dans le stockage du dictionnaire).

Les classes définies par l'utilisateur possèdent des


méthodes __eq__() et __hash__() par défaut ; ces méthodes répondent que tous
les objets sont différents (sauf avec eux-mêmes) et x.__hash__() renvoie une
valeur telle que x == y implique à la fois x is y et hash(x) == hash(y).

Une classe qui surcharge __eq__() et qui ne définit pas __hash__() a sa


méthode __hash__() implicitement assignée à None. Quand la
méthode __hash__() d'une classe est None, une instance de cette classe
lève TypeError quand un programme essaie de demander son empreinte et elle est
correctement identifiée comme non hachable quand on
vérifie isinstance(obj, collections.abc.Hashable).

Si une classe qui surcharge __eq__() a besoin de conserver l'implémentation


de __hash__() de la classe parente, vous devez l'indiquer explicitement à
l'interpréteur en définissant __hash__ = <ClasseParente>.__hash__.

Si une classe ne surcharge pas __eq__() et veut supprimer le calcul des


empreintes, elle doit inclure __hash__ = None dans la définition de la classe. Une
classe qui définit sa propre méthode __hash__() qui lève
explicitement TypeError serait incorrectement identifiée comme hachable par un
appel à isinstance(obj, collections.abc.Hashable).

Note
 

Par défaut, les valeurs renvoyées par __hash__() pour les chaînes, bytes et


objets datetime sont salées avec une valeur aléatoire non prévisible. Bien qu'une
empreinte reste constante tout au long d'un processus Python, sa valeur n'est pas
prévisible entre deux invocations de Python.

C'est un comportement voulu pour se protéger contre un déni de service qui


utiliserait des entrées malicieusement choisies pour effectuer des insertions dans le
dictionnaire dans le pire cas, avec une complexité en O(n^2).
Lisez http://www.ocert.org/advisories/ocert-2011-003.html pour en obtenir les détails
(article en anglais).
Modifier les empreintes obtenues par hachage modifie l'ordre d'itération sur les sets.
Python n'a jamais donné de garantie sur cet ordre (d'ailleurs, l'ordre n'est pas le
même entre les implémentations 32 et 64 bits).

Voir aussi PYTHONHASHSEED.

Modifié dans la version 3.3: la randomisation des empreintes est activée par défaut.

object.__bool__(self)

Appelée pour implémenter les tests booléens et l'opération native bool() ; elle doit
renvoyer False ou True. Quand cette méthode n'est pas définie, __len__() est
appelée, si elle est définie, et l'objet est considéré vrai si le résultat est non nul. Si
une classe ne définit ni __len__() ni __bool__(), toutes ses instances sont
considérées comme vraies.

3.3.2. Personnalisation de l'accès aux attributs


Les méthodes suivantes peuvent être définies pour personnaliser l'accès aux
attributs (utilisation, assignation, suppression de x.name) pour les instances de
classes.

object.__getattr__(self, name)

Appelée lorsque l'accès par défaut à l'attribut échoue en


levant AttributeError (soit __getattribute__() lève AttributeError car na
me n'est pas un attribut de l'instance ou un attribut dans l'arborescence de la classe
de self ; ou __get__() de la propriété name lève AttributeError). Cette
méthode doit retourner soit la valeur (calculée) de l'attribut, soit lever une
exception AttributeError.

Notez que si l'attribut est trouvé par le mécanisme normal, __getattr__() n'est pas


appelée (c'est une asymétrie voulue entre __getattr__() et __setattr__()). Ce
comportement est adopté à la fois pour des raisons de performance et parce que,
sinon, __getattr__() n'aurait aucun moyen d'accéder aux autres attributs de
l'instance. Notez que, au moins pour ce qui concerne les variables d'instance, vous
pouvez simuler un contrôle total en n'insérant aucune valeur dans le dictionnaire des
attributs de l'instance (mais en les insérant dans un autre objet à la place). Lisez la
partie relative à la méthode __getattribute__() ci-dessous pour obtenir un
contrôle total effectif sur l'accès aux attributs.

object.__getattribute__(self, name)
Appelée de manière inconditionnelle pour implémenter l'accès aux attributs des
instances de la classe. Si la classe définit également __getattr__(), cette dernière
n'est pas appelée à moins que __getattribute__() ne l'appelle explicitement ou
ne lève une exception AttributeError. Cette méthode doit renvoyer la valeur
(calculée) de l'attribut ou lever une exception AttributeError. Afin d'éviter une
récursion infinie sur cette méthode, son implémentation doit toujours appeler la
méthode de la classe de base avec le même paramètre name pour accéder à
n'importe quel attribut dont elle a besoin. Par
exemple, object.__getattribute__(self, name).

Note
 

Cette méthode peut être shuntée lorsque la recherche porte sur les méthodes
spéciales en tant que résultat d'une invocation implicite via la syntaxe du langage ou
les fonctions natives. Lisez Recherche des méthodes spéciales.
object.__setattr__(self, name, value)

Appelée lors d'une assignation d'attribut. Elle est appelée à la place du mécanisme
normal (c'est-à-dire stocker la valeur dans le dictionnaire de l'instance). name est le
nom de l'attribut, value est la valeur à assigner à cet attribut.

Si __setattr__() veut assigner un attribut d'instance, elle doit appeler la méthode


de la classe de base avec le même nom, par
exemple object.__setattr__(self, name, value).

object.__delattr__(self, name)

Comme __setattr__() mais pour supprimer un attribut au lieu de l'assigner. Elle


ne doit être implémentée que si del obj.name a du sens pour cet objet.

object.__dir__(self)

Appelée quand dir() est appelée sur l'objet. Elle doit renvoyer une


séquence. dir() convertit la séquence renvoyée en liste et effectue le classement.

3.3.2.1. Personnalisation de l'accès aux attributs d'un module

Les noms spéciaux __getattr__ et __dir__ peuvent aussi être personnalisés pour


accéder aux attributs du module. La fonction __getattr__ au niveau du module doit
accepter un argument qui est un nom d'attribut et doit renvoyer la valeur calculée ou
lever une AttributeError. Si un attribut n'est pas trouvé dans l'objet module en
utilisant la recherche normale, c'est-à-dire object.__getattribute__(), alors
Python recherche __getattr__ dans le __dict__ du module avant de lever
une AttributeError. S'il la trouve, il l'appelle avec le nom de l'attribut et renvoie le
résultat.

The __dir__ function should accept no arguments, and return a sequence of strings


that represents the names accessible on module. If present, this function overrides
the standard dir() search on a module.

Pour une personnalisation plus fine du comportement d'un module (assignation des
attributs, propriétés, etc.), vous pouvez assigner l'attribut __class__ d'un objet
module à une sous-classe de types.ModuleType. Par exemple :

import sys
from types import ModuleType

class VerboseModule(ModuleType):
def __repr__(self):
return f'Verbose {self.__name__}'

def __setattr__(self, attr, value):


print(f'Setting {attr}...')
super().__setattr__(attr, value)

sys.modules[__name__].__class__ = VerboseModule
Note
 

Définir __getattr__ du module et __class__ pour le module affecte uniquement


les recherches qui utilisent la syntaxe d'accès aux attributs — accéder directement
aux globales d'un module (soit par le code dans le module, soit via une référence au
dictionnaire des variables globales du module) fonctionne toujours de la même
façon.

Modifié dans la version 3.5: l'attribut __class__ du module est maintenant en


lecture-écriture.

Nouveau dans la version 3.7: attributs __getattr__ et __dir__ du module.

Voir aussi
PEP 562 — __getattr__ et __dir__ pour un module

Décrit les fonctions __getattr__ et __dir__ des modules.


3.3.2.2. Implémentation de descripteurs

Les méthodes qui suivent s'appliquent seulement quand une instance de la classe
(dite classe descripteur) contenant la méthode apparaît dans une
classe propriétaire (owner en anglais) ; la classe descripteur doit figurer dans le
dictionnaire de la classe propriétaire ou dans le dictionnaire de la classe d'un des
parents. Dans les exemples ci-dessous, « l'attribut » fait référence à l'attribut dont le
nom est une clé du __dict__ de la classe propriétaire.

object.__get__(self, instance, owner)

Appelée pour obtenir l'attribut de la classe propriétaire (accès à un attribut de classe)


ou d'une instance de cette classe (accès à un attribut d'instance). owner est toujours
la classe propriétaire alors que instance est l'instance par laquelle on accède à
l'attribut ou None lorsque l'on accède par la classe owner. Cette méthode doit
renvoyer la valeur (calculée) de l'attribut ou lever une exception AttributeError.

object.__set__(self, instance, value)

Appelée pour définir l'attribut d'une instance instance de la classe propriétaire à la


nouvelle valeur value.

object.__delete__(self, instance)

Appelée pour supprimer l'attribut de l'instance instance de la classe propriétaire.

object.__set_name__(self, owner, name)

Appelée au moment où la classe propriétaire owner est créée. La classe descripteur


a été assignée à name.

Note
 

__set_name__() is only called implicitly as part of the type constructor, so it will


need to be called explicitly with the appropriate parameters when a descriptor is
added to a class after initial creation:
class A:
pass
descr = custom_descriptor()
A.attr = descr
descr.__set_name__(A, 'attr')
See Création de l'objet classe for more details.

Nouveau dans la version 3.6.

L'attribut __objclass__ est interprété par le module inspect comme spécifiant la


classe où cet objet a été défini (le définir correctement peut vous aider dans
l'introspection des classes dynamiques à l'exécution). Pour les appelables, cela peut
indiquer qu'une instance d'un certain type (ou d'une certaine sous-classe) est
attendue ou requise comme premier argument positionnel (par exemple, CPython
définit cet attribut pour les méthodes non liées qui sont implémentées en C).

3.3.2.3. Invocation des descripteurs

En général, un descripteur est un attribut d'objet dont le comportement est « lié »


(binding dehavior en anglais), c'est-à-dire que les accès aux attributs ont été
surchargés par des méthodes conformes au protocole des
descripteurs : __get__(), __set__() et __delete__(). Si l'une de ces méthodes
est définie pour un objet, il est réputé être un descripteur.

Le comportement par défaut pour la gestion d'un attribut est de définir, obtenir et
supprimer cet attribut du dictionnaire de l'objet. Par exemple, pour a.x Python
commence d'abord par rechercher a.__dict__['x'],
puis type(a).__dict__['x'] ; ensuite Python continue en remontant les classes
de base de type(a), en excluant les méta-classes.

Cependant, si la valeur cherchée est un objet qui définit une des méthodes de
descripteur, alors Python modifie son comportement et invoque la méthode du
descripteur à la place. Le moment où cela intervient dans la recherche citée ci-
dessus dépend de l'endroit où a été définie la méthode de descripteur et comment
elle a été appelée.

Le point de départ pour une invocation de descripteur est la liaison a.x. La façon


dont les arguments sont assemblés dépend de a :

Appel direct

Le plus simple et le plus rare des appels est quand l'utilisateur code directement
l'appel à la méthode du descripteur : x.__get__(a).

Liaison avec une instance

Si elle est liée à un objet instance, a.x est transformé en l'appel


suivant : type(a).__dict__['x'].__get__(a, type(a)).
Liaison avec une classe

Si elle est liée à une classe, A.x est transformé en l'appel


suivant : A.__dict__['x'].__get__(None, A).

Liaison super

Si a est une instance de super,


alors super(B, obj).m() recherche obj.__class__.__mro__ pour la classe de
base A immédiatement avant B puis invoque le descripteur avec l'appel
suivant : A.__dict__['m'].__get__(obj, obj.__class__).

Pour des liaisons avec des instances, la priorité à l'invocation du descripteur dépend
des méthodes que le descripteur a définies. Un descripteur peut définir n'importe
quelle combinaison de __get__(), __set__() et __delete__(). S'il ne définit
pas __get__(), alors accéder à l'attribut retourne l'objet descripteur lui-même sauf
s'il existe une valeur dans le dictionnaire de l'objet instance. Si le descripteur
définit __set__() ou __delete__(), c'est un descripteur de données ; s'il ne définit
aucune méthode, c'est un descripteur hors-donnée. Normalement, les descripteurs
de données définissent à la fois __get__() et __set__(), alors que les
descripteurs hors-données définissent seulement la méthode __get__(). Les
descripteurs de données qui définissent __set__() et __get__() sont toujours
prioritaires face à une redéfinition du dictionnaire de l'instance. En revanche, les
descripteurs hors-données peuvent être shuntés par les instances.

Les méthodes Python (y compris staticmethod() et classmethod()) sont


implémentées comme des descripteurs hors-donnée. De la même manière, les
instances peuvent redéfinir et surcharger les méthodes. Ceci permet à chaque
instance d'avoir un comportement qui diffère des autres instances de la même
classe.

La fonction property() est implémentée en tant que descripteur de données. Ainsi,


les instances ne peuvent pas surcharger le comportement d'une propriété.

3.3.2.4.  __slots__

Les __slots__ vous permettent de déclarer des membres d'une donnée (comme


une propriété) et d'interdire la création de __dict__ ou de __weakref__ (à moins qu'ils
ne soient explicitement déclarés dans le __slots__ ou présent dans le parent).

L'espace gagné par rapport à l'utilisation d'un __dict__ peut être significatif. La


recherche d'attribut peut aussi s'avérer beaucoup plus rapide.

object.__slots__
Cette variable de classe peut être assignée avec une chaîne, un itérable ou une
séquence de chaînes avec les noms de variables utilisés par les
instances. __slots__ réserve de la place pour ces variables déclarées et interdit la
création automatique de __dict__ et __weakref__ pour chaque instance.

3.3.2.4.1. Note sur l'utilisation de __slots__


 Lorsque vous héritez d'une classe sans __slots__, les
attributs __dict__ et __weakref__ des instances sont toujours accessibles.
 Sans variable __dict__, les instances ne peuvent pas assigner de nouvelles
variables (non listées dans la définition de __slots__). Les tentatives d'assignation
sur un nom de variable non listé lève AttributeError. Si l'assignation dynamique
de nouvelles variables est nécessaire, ajoutez '__dict__' à la séquence de
chaînes dans la déclaration __slots__.
 Sans variable __weakref__ pour chaque instance, les classes qui
définissent __slots__ ne gèrent pas les références faibles vers leurs instances. Si
vous avez besoin de gérer des références faibles, ajoutez '__weakref__' à la
séquence de chaînes dans la déclaration de __slots__.
 Les __slots__ sont implémentés au niveau de la classe en créant des
descripteurs (Implémentation de descripteurs) pour chaque nom de variable. Ainsi,
les attributs de classe ne peuvent pas être utilisés pour des valeurs par défaut aux
variables d'instances définies par __slots__ ; sinon, l'attribut de classe surchargerait
l'assignation par descripteur.
 L'action de la déclaration du __slots__ ne se limite pas à la classe où il est
défini. Les __slots__ déclarés par les parents sont disponibles dans les classes
enfants. Cependant, les sous-classes enfants ont un __dict__ et un __weakref__ à
moins qu'elles ne définissent aussi un __slots__ (qui ne doit contenir alors que les
noms supplémentaires du slot).
 Si une classe définit un slot déjà défini dans une classe de base, la variable
d'instance définie par la classe de base est inaccessible (sauf à utiliser le descripteur
de la classe de base directement). Cela rend la signification du programme indéfinie.
Dans le futur, une vérification sera ajoutée pour empêcher cela.
 Un __slot__ non vide ne fonctionne pas pour les classes dérivées des types
natifs à longueur variable tels que int, bytes et tuple.
 Tout itérable qui n'est pas une chaîne peut être assigné à un __slots__. Les
tableaux de correspondance peuvent aussi être utilisés ; cependant, dans le futur,
des significations spéciales pourraient être associées à chacune des clés.
 Les assignations de __class__ ne fonctionnent que si les deux classes ont le
même __slots__.
 L'héritage multiple avec plusieurs classes parentes qui ont des __slots__ est
possible, mais seul un parent peut avoir des attributs créés par __slots__ (les autres
classes parentes doivent avoir des __slots__ vides). La violation de cette règle
lève TypeError.
 If an iterator is used for __slots__ then a descriptor is created for each of the
iterator's values. However, the __slots__ attribute will be an empty iterator.
3.3.3. Personnalisation de la création de classes
Quand une classe hérite d'une classe parente, __init_subclass__ de la classe
parente est appelée. Ainsi, il est possible d'écrire des classes qui modifient le
comportement des sous-classes. Ce comportement est corrélé aux décorateurs de
classes mais, alors que les décorateurs de classes agissent seulement sur la classe
qu'ils décorent, __init_subclass__ agit uniquement sur les futures sous-classes
de la classe qui définit cette méthode.

classmethod  object.__init_subclass__(cls)

Cette méthode est appelée quand la classe est sous-classée. cls est alors la


nouvelle sous-classe. Si elle est définie en tant que méthode d'instance normale,
cette méthode est implicitement convertie en méthode de classe.

Les arguments nommés qui sont donnés à la nouvelle classe sont passés
à __init_subclass__ de la classe parente. Par souci de compatibilité avec les
autres classes qui utilisent __init_subclass__, vous devez enlever les arguments
nommés dont vous avez besoin et passer les autres à la classe de base, comme ci-
dessous :

class Philosopher:
def __init_subclass__(cls, default_name, **kwargs):
super().__init_subclass__(**kwargs)
cls.default_name = default_name

class AustralianPhilosopher(Philosopher, default_name="Bruce"):


pass

L'implémentation par défaut object.__init_subclass__ ne fait rien mais lève une


erreur si elle est appelée avec un argument.

Note
 

L'indication de méta-classe metaclass est absorbée par le reste du mécanisme de


types et n'est jamais passée à l'implémentation de __init_subclass__. La méta-
classe réelle (plutôt que l'indication explicite) peut être récupérée par type(cls).
Nouveau dans la version 3.6.

3.3.3.1. Méta-classes

Par défaut, les classes sont construites en utilisant type(). Le corps de la classe est
exécuté dans un nouvel espace de nommage et le nom de la classe est lié
localement au résultat de type(name, bases, namespace)`.

Le déroulement de création de la classe peut être personnalisé en passant


l'argument nommé metaclass dans la ligne de définition de la classe ou en héritant
d'une classe existante qui comporte déjà un tel argument. Dans l'exemple qui
suit, MyClass et MySubclass sont des instances de Meta :

class Meta(type):
pass

class MyClass(metaclass=Meta):
pass

class MySubclass(MyClass):
pass

Tout autre argument nommé spécifié dans la définition de la classe est passé aux
opérations de méta-classes décrites auparavant.

Quand la définition d'une classe est exécutée, les différentes étapes suivies sont :

 Les entrées MRO sont résolues ;


 la méta-classe appropriée est déterminée ;
 l'espace de nommage de la classe est préparé ;
 le corps de la classe est exécuté ;
 l'objet classe est crée.
3.3.3.2. Résolution des entrées MRO

Si une classe de base qui apparaît dans la définition d'une classe n'est pas une
instance de type, alors Python y recherche une méthode __mro_entries__. S'il la
trouve, il l'appelle avec le tuple original des classes de bases. Cette méthode doit
renvoyer un tuple de classes qui est utilisé à la place de la classe de base. Le tuple
peut être vide, dans ce cas la classe de base originale est ignorée.

Voir aussi
 
PEP 560 — Gestion de base pour les types modules et les types génériques
3.3.3.3. Détermination de la méta-classe appropriée

La méta-classe appropriée pour une définition de classe est déterminée de la


manière suivante :

 si aucune classe et aucune métaclasse n'est donnée, alors type() est


utilisée ;
 si une méta-classe explicite est donnée et que ce n'est pas une instance
de type(), alors elle est utilisée directement en tant que méta-classe ;
 Si une instance de type() est donnée comme méta-classe explicite ou
si bases est définie, alors la méta-classe la plus dérivée est utilisée.

La méta-classe la plus dérivée est choisie à partir des méta-classes explicitement


spécifiées (s'il y en a) et les méta-classes (c'est-à-dire les type(cls)) de toutes les
classes de base spécifiées. La méta-classe la plus dérivée est celle qui est un sous-
type de toutes ces méta-classes candidates. Si aucune des méta-classes candidates
ne remplit ce critère, alors la définition de la classe échoue en levant TypeError.

3.3.3.4. Préparation de l'espace de nommage de la classe

Once the appropriate metaclass has been identified, then the class namespace is
prepared. If the metaclass has a __prepare__ attribute, it is called
as namespace = metaclass.__prepare__(name, bases, **kwds) (where the
additional keyword arguments, if any, come from the class definition).
The __prepare__ method should be implemented as a classmethod(). The
namespace returned by __prepare__ is passed in to __new__, but when the final
class object is created the namespace is copied into a new dict.

Si la méta-classe ne possède pas d'attribut __prepare__, alors l'espace de


nommage de la classe est initialisé en tant que tableau de correspondances
ordonné.

Voir aussi
PEP 3115 — Méta-classes dans Python 3000

introduction de la fonction automatique __prepare__ de l'espace de nommage


3.3.3.5. Exécution du corps de la classe

Le corps de la classe est exécuté (approximativement)


avec exec(body, globals(), namespace). La principale différence avec un
appel normal à exec() est que la portée lexicale autorise le corps de la classe (y
compris les méthodes) à faire référence aux noms de la portée courante et des
portées externes lorsque la définition de classe a lieu dans une fonction.

Cependant, même quand une définition de classe intervient dans une fonction, les
méthodes définies à l'intérieur de la classe ne peuvent pas voir les noms définis en
dehors de la portée de la classe. On accède aux variables de la classe via le premier
paramètre des méthodes d'instance ou de classe, ou via la référence
implicite __class__ incluse dans la portée lexicale et décrite dans la section
suivante.

3.3.3.6. Création de l'objet classe

Quand l'espace de nommage a été rempli en exécutant le corps de la classe, l'objet


classe est créé en
appelant metaclass(name, bases, namespace, **kwds) (les arguments
nommés supplémentaires passés ici sont les mêmes que ceux passés
à __prepare__).

Cet objet classe est celui qui est référencé par la forme sans argument
de super(). __class__ est une référence implicite créée par le compilateur si une
méthode du corps de la classe fait référence soit à __class__, soit à super. Ceci
permet que la forme sans argument de super() identifie la classe en cours de
définition en fonction de la portée lexicale, tandis que la classe ou l'instance utilisée
pour effectuer l'appel en cours est identifiée en fonction du premier argument
transmis à la méthode.

CPython implementation detail: Dans CPython 3.6 et suivants, la


cellule __class__ est passée à la méta-classe en tant
qu'entrée __classcell__ dans l'espace de nommage de la classe. Si elle est
présente, elle doit être propagée à l'appel type .__ new__ pour que la classe soit
correctement initialisée. Ne pas le faire se traduit par un
avertissement DeprecationWarning dans Python 3.6 et un RuntimeError dans
Python 3.8.

Quand vous utilisez la méta-classe par défaut type ou toute autre méta-classe qui
finit par appeler type.__new__, les étapes de personnalisation supplémentaires
suivantes sont suivies après la création de l'objet classe :

 d'abord, type.__new__ récupère, dans l'espace de nommage de la classe,


tous les descripteurs qui définissent une méthode __set_name__() ;
 ensuite, toutes ces méthodes __set_name__ sont appelées avec la classe en
cours de définition et le nom assigné à chaque descripteur ;
 finalement, la méthode automatique __init_subclass__() est appelée sur
le parent immédiat de la nouvelle classe en utilisant l'ordre de résolution des
méthodes.

Après la création de l'objet classe, il est passé aux décorateurs de la classe, y


compris ceux inclus dans la définition de la classe (s'il y en a) et l'objet résultant est
lié à l'espace de nommage local en tant que classe définie.

Quand une nouvelle classe est créée via type.__new__, l'objet fourni en tant que
paramètre d'espace de nommage est copié vers un nouveau tableau de
correspondances ordonné et l'objet original est laissé de côté. La nouvelle copie est
encapsulée dans un mandataire en lecture seule qui devient l'attribut __dict__ de
l'objet classe.

Voir aussi
PEP 3135 — Nouvelle méthode super

Décrit la référence à la fermeture (closure en anglais) de la __class__ implicite


3.3.3.7. Cas d'utilisations des métaclasses

Les utilisations possibles des méta-classes sont immenses. Quelques pistes ont déjà
été explorées comme l'énumération, la gestion des traces, le contrôle des interfaces,
la délégation automatique, la création automatique de propriétés, les mandataires,
les frameworks ainsi que le verrouillage ou la synchronisation automatique de
ressources.

3.3.4. Personnalisation des instances et vérification des


sous-classes
Les méthodes suivantes sont utilisées pour surcharger le comportement par défaut
des fonctions natives isinstance() et issubclass().

En particulier, la méta-classe abc.ABCMeta implémente ces méthodes pour


autoriser l'ajout de classes de base abstraites (ABC pour Abstract Base Classes en
anglais) en tant que « classes de base virtuelles » pour toute classe ou type (y
compris les types natifs).

class.__instancecheck__(self, instance)

Renvoie True si instance doit être considérée comme une instance (directe ou


indirecte) de class. Si elle est définie, elle est appelée pour
implémenter isinstance(instance, class).
class.__subclasscheck__(self, subclass)

Renvoie True si subclass doit être considérée comme une sous-classe (directe ou


indirecte) de class. Si elle est définie, appelée pour
implémenter issubclass(subclass, class).

Notez que ces méthodes sont recherchées dans le type (la méta-classe) d'une
classe. Elles ne peuvent pas être définies en tant que méthodes de classe dans la
classe réelle. C'est cohérent avec la recherche des méthodes spéciales qui sont
appelées pour les instances, sauf qu'ici l'instance est elle-même une classe.

Voir aussi
PEP 3119 — Introduction aux classes de bases abstraites

Inclut la spécification pour la personnalisation du comportement


de isinstance() et issubclass() à
travers __instancecheck__() et __subclasscheck__(), avec comme motivation
pour cette fonctionnalité l'ajout les classes de base abstraites (voir le module abc) au
langage.
3.3.5. Émulation de types génériques
Vous pouvez implémenter la syntaxe générique des classes comme spécifié par
la PEP 484 (par exemple List[int]) en définissant une méthode spéciale :

classmethod  object.__class_getitem__(cls, key)

Renvoie un objet représentant la spécialisation d'une classe générique en fonction


des arguments types trouvés dans key.

Python recherche cette méthode dans l'objet de classe lui-même et, lorsqu'elle est
définie dans le corps de la classe, cette méthode est implicitement une méthode de
classe. Notez que ce mécanisme est principalement réservé à une utilisation avec
des indications de type statiques, d'autres utilisations sont déconseillées.

Voir aussi
 

PEP 560 — Gestion de base pour les types modules et les types génériques
3.3.6. Émulation d'objets appelables
object.__call__(self[, args...])
Appelée quand l'instance est « appelée » en tant que fonction ; si la méthode est
définie, x(arg1, arg2, ...) est un raccourci
pour x.__call__(arg1, arg2, ...).

3.3.7. Émulation de types conteneurs


The following methods can be defined to implement container objects. Containers
usually are sequences (such as lists or tuples) or mappings (like dictionaries), but
can represent other containers as well. The first set of methods is used either to
emulate a sequence or to emulate a mapping; the difference is that for a sequence,
the allowable keys should be the integers k for which 0 <= k < N where N is the
length of the sequence, or slice objects, which define a range of items. It is also
recommended that mappings provide the
methods keys(), values(), items(), get(), clear(), setdefault(), pop(), p
opitem(), copy(), and update() behaving similar to those for Python's standard
dictionary objects. The collections.abc module provides
a MutableMapping abstract base class to help create those methods from a base
set of __getitem__(), __setitem__(), __delitem__(), and keys(). Mutable
sequences should provide
methods append(), count(), index(), extend(), insert(), pop(), remove(), 
reverse() and sort(), like Python standard list objects. Finally, sequence types
should implement addition (meaning concatenation) and multiplication (meaning
repetition) by defining the
methods __add__(), __radd__(), __iadd__(), __mul__(), __rmul__() and __
imul__() described below; they should not define other numerical operators. It is
recommended that both mappings and sequences implement
the __contains__() method to allow efficient use of the in operator; for
mappings, in should search the mapping's keys; for sequences, it should search
through the values. It is further recommended that both mappings and sequences
implement the __iter__() method to allow efficient iteration through the container;
for mappings, __iter__() should iterate through the object's keys; for sequences, it
should iterate through the values.

object.__len__(self)

Appelée pour implémenter la fonction native len(). Elle doit renvoyer la longueur de


l'objet, un entier >= 0. Par ailleurs, un objet qui ne définit pas de
méthode __bool__() et dont la méthode __len__() renvoie zéro est considéré
comme valant False dans un contexte booléen.

CPython implementation detail: En CPython, la longueur doit valoir au


maximum sys.maxsize. Si la longueur est plus grande que sys.maxsize, des
propriétés (telles que len()) peuvent lever OverflowError. Afin d'éviter de
lever OverflowError lors de tests booléens, un objet doit définir la
méthode __bool__().
object.__length_hint__(self)

Called to implement operator.length_hint(). Should return an estimated length


for the object (which may be greater or less than the actual length). The length must
be an integer >= 0. The return value may also be NotImplemented, which is treated
the same as if the __length_hint__ method didn't exist at all. This method is
purely an optimization and is never required for correctness.

Nouveau dans la version 3.4.

Note
 

Le découpage est effectué uniquement à l'aide des trois méthodes suivantes. Un


appel comme
a[1:2] = b

est traduit en
a[slice(1, 2, None)] = b

et ainsi de suite. Les éléments manquants sont remplacés par None.


object.__getitem__(self, key)

Appelée pour implémenter l'évaluation de self[key]. Pour les types séquences, les
clés autorisées sont les entiers et les objets tranches (slice). Notez que
l'interprétation spéciale des indices négatifs (si la classe souhaite émuler un type
séquence) est du ressort de la méthode __getitem__(). Si key n'est pas du bon
type, une TypeError peut être levée ; si la valeur est en dehors de l'ensemble des
indices de la séquence (après interprétation éventuelle des valeurs négatives),
une IndexError doit être levée. Pour les tableaux de correspondances,
si key n'existe pas dans le conteneur, une KeyError doit être levée.

Note
 

for s'attend à ce qu'une IndexError soit levée en cas d'indice illégal afin de


détecter correctement la fin de la séquence.
object.__setitem__(self, key, value)
Appelée pour implémenter l'assignation à self[key]. La même note que
pour __getitem__() s'applique. Elle ne doit être implémentée que pour les
tableaux de correspondances qui autorisent les modifications de valeurs des clés,
ceux pour lesquels on peut ajouter de nouvelles clés ou, pour les séquences, celles
dont les éléments peuvent être remplacés. Les mêmes exceptions que pour la
méthode __getitem__() doivent être levées en cas de mauvaises valeurs de clés.

object.__delitem__(self, key)

Appelée pour implémenter la suppression de self[key]. La même note que


pour __getitem__() s'applique. Elle ne doit être implémentée que pour les
tableaux de correspondances qui autorisent les suppressions de clés ou pour les
séquences dont les éléments peuvent être supprimés de la séquence. Les mêmes
exceptions que pour la méthode __getitem__() doivent être levées en cas de
mauvaises valeurs de clés.

object.__missing__(self, key)

Appelée par dict.__getitem__() pour implémenter self[key] dans les sous-


classes de dictionnaires lorsque la clé n'est pas dans le dictionnaire.

object.__iter__(self)

Cette méthode est appelée quand un itérateur est requis pour un conteneur. Cette
méthode doit renvoyer un nouvel objet itérateur qui peut itérer sur tous les objets du
conteneur. Pour les tableaux de correspondances, elle doit itérer sur les clés du
conteneur.

Les objets itérateurs doivent aussi implémenter cette méthode ; ils doivent alors se
renvoyer eux-mêmes. Pour plus d'information sur les objets itérateurs, lisez Les
types itérateurs.

object.__reversed__(self)

Appelée (si elle existe) par la fonction native reversed() pour implémenter


l'itération en sens inverse. Elle doit renvoyer un nouvel objet itérateur qui itère sur
tous les objets du conteneur en sens inverse.

Si la méthode __reversed__() n'est pas fournie, la fonction native reversed() se


replie sur le protocole de séquence ( __len__() et __getitem__()). Les objets qui
connaissent le protocole de séquence ne doivent fournir __reversed__() que si
l'implémentation qu'ils proposent est plus efficace que celle de reversed().
The membership test operators (in and not in) are normally implemented as an
iteration through a container. However, container objects can supply the following
special method with a more efficient implementation, which also does not require the
object be iterable.

object.__contains__(self, item)

Appelée pour implémenter les opérateurs de test d'appartenance. Elle doit


renvoyer True si item est dans self et False sinon. Pour les tableaux de
correspondances, seules les clés sont considérées (pas les valeurs des paires clés-
valeurs).

Pour les objets qui ne définissent pas __contains__(), les tests d'appartenance


essaient d'abord d'itérer avec __iter__() puis avec le vieux protocole d'itération
sur les séquences via __getitem__(), reportez-vous à cette section dans la
référence du langage.

3.3.8. Émulation de types numériques


Les méthodes suivantes peuvent être définies pour émuler des objets numériques.
Les méthodes correspondant à des opérations qui ne sont pas autorisées pour la
catégorie de nombres considérée (par exemple, les opérations bit à bit pour les
nombres qui ne sont pas entiers) doivent être laissées indéfinies.

object.__add__(self, other)

object.__sub__(self, other)

object.__mul__(self, other)

object.__matmul__(self, other)

object.__truediv__(self, other)

object.__floordiv__(self, other)

object.__mod__(self, other)

object.__divmod__(self, other)

object.__pow__(self, other[, modulo])

object.__lshift__(self, other)

object.__rshift__(self, other)

object.__and__(self, other)
object.__xor__(self, other)

object.__or__(self, other)

Ces méthodes sont appelées pour implémenter les opérations arithmétiques binaires
(+, -, *, @, /, //, %, divmod(), pow(), **, <<, >>, &, ^, |). Par exemple, pour
évaluer l'expression x + y, où x est une instance d'une classe qui possède une
méthode __add__(), x.__add__(y) est appelée. La méthode __divmod__() doit
être l'équivalent d'appeler __floordiv__() et __mod__() ; elle ne doit pas être
reliée à __truediv__(). Notez que __pow__() doit être définie de manière à
accepter un troisième argument optionnel si la version ternaire de la fonction
native pow() est autorisée.

Si l'une de ces méthodes n'autorise pas l'opération avec les arguments donnés, elle
doit renvoyer NotImplemented.

object.__radd__(self, other)

object.__rsub__(self, other)

object.__rmul__(self, other)

object.__rmatmul__(self, other)

object.__rtruediv__(self, other)

object.__rfloordiv__(self, other)

object.__rmod__(self, other)

object.__rdivmod__(self, other)

object.__rpow__(self, other[, modulo])

object.__rlshift__(self, other)

object.__rrshift__(self, other)

object.__rand__(self, other)

object.__rxor__(self, other)

object.__ror__(self, other)

Ces méthodes sont appelées pour implémenter les opérations arithmétiques binaires
(+, -, *, @, /, //, %, divmod(), pow(), **, <<, >>, &, ^, |) avec des opérandes
renversés (intervertis). Ces fonctions ne sont appelées que si l'opérande de gauche
n'autorise pas l'opération correspondante 3 et si les opérandes sont de types
différents 4. Par exemple, pour évaluer l'expression x - y, où y est une instance
d'une classe qui possède une méthode __rsub__(), y.__rsub__(x) est appelée
si x.__sub__(y) renvoie NotImplemented.

Notez que la fonction ternaire pow() n'essaie pas d'appeler __rpow__() (les règles


de coercition seraient trop compliquées).

Note
 

Si le type de l'opérande de droite est une sous-classe du type de l'opérande de


gauche et que cette sous-classe fournit la méthode symétrique pour l'opération, cette
méthode sera appelée avant la méthode originelle de l'opérande gauche. Ce
comportement permet à des sous-classes de surcharger les opérations de leurs
ancêtres.
object.__iadd__(self, other)

object.__isub__(self, other)

object.__imul__(self, other)

object.__imatmul__(self, other)

object.__itruediv__(self, other)

object.__ifloordiv__(self, other)

object.__imod__(self, other)

object.__ipow__(self, other[, modulo])

object.__ilshift__(self, other)

object.__irshift__(self, other)

object.__iand__(self, other)

object.__ixor__(self, other)

object.__ior__(self, other)

Ces méthodes sont appelées pour implémenter les assignations arithmétiques


augmentées (+=, -=, *=, @=, /=, //=, %=, **=, <<=, >>=, &=, ^=, |=). Ces méthodes
doivent essayer d'effectuer l'opération « sur place » (c'est-à-dire de modifier self) et
de renvoyer le résultat (qui peut être, mais pas nécessairement, self). Si une
méthode spécifique n'est pas définie, l'assignation augmentée se replie vers la
méthode normale correspondante. Par exemple, si x est une instance d'une classe
qui possède une méthode __iadd__(), x += y est équivalent
à x = x.__iadd__(y) . Sinon, x.__add__(y) et y.__radd__(x) sont essayées,
comme pour l'évaluation de x + y. Dans certaines situations, les assignations
augmentées peuvent causer des erreurs inattendues (voir Pourquoi a_tuple[i] +=
['item'] lève-t-il une exception alors que l'addition fonctionne ?), mais ce
comportement est en fait partie intégrante du modèle de données.

object.__neg__(self)

object.__pos__(self)

object.__abs__(self)

object.__invert__(self)

Appelée pour implémenter les opérations arithmétiques unaires ( -, +, abs() et ~).

object.__complex__(self)

object.__int__(self)

object.__float__(self)

Appelées pour implémenter les fonctions natives complex(), int() et float().


Elles doivent renvoyer une valeur du type approprié.

object.__index__(self)

Appelée pour implémenter operator.index() et lorsque Python a besoin de


convertir sans perte un objet numérique en objet entier (pour un découpage ou dans
les fonctions natives bin(), hex() et oct()). La présence de cette méthode indique
que l'objet numérique est un type entier. Elle doit renvoyer un entier.

Note
 

Afin d'avoir un type de classe entier cohérent, lorsque __index__() est définie


alors __int__() doit aussi être définie et les deux doivent renvoyer la même valeur.
object.__round__(self[, ndigits])

object.__trunc__(self)

object.__floor__(self)

object.__ceil__(self)
Appelée pour implémenter la fonction native round() et les fonctions du
module math trunc(), floor() et ceil(). À moins que ndigits ne soit passé
à __round__(), toutes ces méthodes doivent renvoyer la valeur de l'objet tronquée
pour donner un Integral (typiquement un int).

Si __int__() n'est pas définie, alors la fonction native int() se replie


sur __trunc__().

3.3.9. Gestionnaire de contexte With


Un gestionnaire de contexte est un objet qui met en place un contexte prédéfini au
moment de l'exécution de l'instruction with. Le gestionnaire de contexte gère
l'entrée et la sortie de ce contexte d'exécution pour tout un bloc de code. Les
gestionnaires de contextes sont normalement invoqués en utilisant une
instruction with (décrite dans la section L'instruction with), mais ils peuvent aussi
être directement invoqués par leurs méthodes.

Les utilisations classiques des gestionnaires de contexte sont la sauvegarde et la


restauration d'états divers, le verrouillage et le déverrouillage de ressources, la
fermeture de fichiers ouverts, etc.

Pour plus d'informations sur les gestionnaires de contexte, lisez Le type gestionnaire
de contexte.

object.__enter__(self)

Entre dans le contexte d'exécution relatif à cet objet. L'instruction with lie la valeur


de retour de cette méthode à une (ou plusieurs) cible spécifiée par la clause  as de
l'instruction, si elle est spécifiée.

object.__exit__(self, exc_type, exc_value, traceback)

Sort du contexte d'exécution relatif à cet objet. Les paramètres décrivent l'exception
qui a causé la sortie du contexte. Si l'on sort du contexte sans exception, les trois
arguments sont à None.

Si une exception est indiquée et que la méthode souhaite supprimer l'exception


(c'est-à-dire qu'elle ne veut pas que l'exception soit propagée), elle doit
renvoyer True. Sinon, l'exception est traitée normalement à la sortie de cette
méthode.

Notez qu'une méthode __exit__() ne doit pas lever à nouveau l'exception qu'elle


reçoit ; c'est du ressort de l'appelant.
Voir aussi
PEP 343 — L'instruction with

La spécification, les motivations et des exemples de l'instruction with en Python.


3.3.10. Recherche des méthodes spéciales
Pour les classes définies par le développeur, l'invocation implicite de méthodes
spéciales n'est garantie que si ces méthodes sont définies par le type d'objet, pas
dans le dictionnaire de l'objet instance. Ce comportement explique pourquoi le code
suivant lève une exception :

>>>

>>> class C:
... pass
...
>>> c = C()
>>> c.__len__ = lambda: 5
>>> len(c)
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
TypeError: object of type 'C' has no len()

La raison de ce comportement vient de certaines méthodes spéciales telles


que __hash__() et __repr__() qui sont implémentées par tous les objets, y
compris les objets types. Si la recherche effectuée par ces méthodes utilisait le
processus normal de recherche, elles ne fonctionneraient pas si on les appelait sur
l'objet type lui-même :

>>>

>>> 1 .__hash__() == hash(1)


True
>>> int.__hash__() == hash(int)
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
TypeError: descriptor '__hash__' of 'int' object needs an
argument

Essayer d'invoquer une méthode non liée d'une classe de cette manière est parfois
appelé « confusion de méta-classe » et se contourne en shuntant l'instance lors de la
recherche des méthodes spéciales :

>>>
>>> type(1).__hash__(1) == hash(1)
True
>>> type(int).__hash__(int) == hash(int)
True

En plus de shunter les attributs des instances pour fonctionner correctement, la


recherche des méthodes spéciales implicites shunte aussi la
méthode __getattribute__() même dans la méta-classe de l'objet :

>>>

>>> class Meta(type):


... def __getattribute__(*args):
... print("Metaclass getattribute invoked")
... return type.__getattribute__(*args)
...
>>> class C(object, metaclass=Meta):
... def __len__(self):
... return 10
... def __getattribute__(*args):
... print("Class getattribute invoked")
... return object.__getattribute__(*args)
...
>>> c = C()
>>> c.__len__() # Explicit lookup via instance
Class getattribute invoked
10
>>> type(c).__len__(c) # Explicit lookup via type
Metaclass getattribute invoked
10
>>> len(c) # Implicit lookup
10

En shuntant le mécanisme de __getattribute__() de cette façon, cela permet


d'optimiser la vitesse de l'interpréteur moyennant une certaine manœuvre dans la
gestion des méthodes spéciales (la méthode spéciale doit être définie sur l'objet
classe lui-même afin d'être invoquée de manière cohérente par l'interpréteur).

3.4. Coroutines
3.4.1. Objets attendables (awaitables)
Un objet awaitable implémente généralement une méthode __await__(). Les
objets Coroutine renvoyés par les fonctions async def sont des awaitables.

Note
 

Les objets itérateur de générateur renvoyés par les générateurs décorés


par types.coroutine() ou asyncio.coroutine() sont aussi des awaitables,
mais ils n'implémentent pas __await__().
object.__await__(self)

Doit renvoyer un itérateur. Doit être utilisé pour implémenter les objets awaitable. Par
exemple, asyncio.Future implémente cette méthode pour être compatible avec les
expressions await.

Nouveau dans la version 3.5.

Voir aussi
 

PEP 492 pour les informations relatives aux objets awaitables.


3.4.2. Objets coroutines
Les objets Coroutine sont des objets awaitable. L'exécution d'une coroutine peut être
contrôlée en appelant __await__() et en itérant sur le résultat. Quand la coroutine
a fini de s'exécuter et termine, l'itérateur lève StopIteration et l'attribut value de
l'exception contient la valeur de retour. Si la coroutine lève une exception, elle est
propagée par l'itérateur. Les coroutines ne doivent pas lever directement des
exceptions StopIteration non gérées.

Les coroutines disposent aussi des méthodes listées ci-dessous, analogues à celles
des générateurs (voir Méthodes des générateurs-itérateurs). Cependant, au contraire
des générateurs, vous ne pouvez pas itérer directement sur des coroutines.

Modifié dans la version 3.5.2: Utiliser await plus d'une fois sur une coroutine lève
une RuntimeError.

coroutine.send(value)

Démarre ou reprend l'exécution d'une coroutine. Si value est None, c'est équivalent à


avancer l'itérateur renvoyé par __await__(). Si value ne vaut pas None, cette
méthode appelle la méthode send() de l'itérateur qui a causé la suspension de la
coroutine. Le résultat (valeur de retour, StopIteration ou une autre exception) est
le même que lorsque vous itérez sur la valeur de retour de __await__(), décrite ci-
dessus.

coroutine.throw(type[, value[, traceback]])
Lève l'exception spécifiée dans la coroutine. Cette méthode délègue à la
méthode throw() de l'itérateur qui a causé la suspension de la coroutine, s'il
possède une telle méthode. Sinon, l'exception est levée au point de suspension. Le
résultat (valeur de retour, StopIteration ou une autre exception) est le même que
lorsque vous itérez sur la valeur de retour de __await__(), décrite ci-dessus. Si
l'exception n'est pas gérée par la coroutine, elle est propagée à l'appelant.

coroutine.close()

Demande à la coroutine de faire le ménage et de se terminer. Si la coroutine est


suspendue, cette méthode délègue d'abord à la méthode close() de l'itérateur qui a
causé la suspension de la coroutine, s'il possède une telle méthode. Ensuite, elle
lève GeneratorExit au point de suspension, ce qui fait le ménage dans la
coroutine immédiatement. Enfin, la coroutine est marquée comme ayant terminé son
exécution, même si elle n'a jamais démarré.

Les objets coroutines sont automatiquement fermés en utilisant le processus décrit


au-dessus au moment où ils sont détruits.

3.4.3. Itérateurs asynchrones
Un itérateur asynchrone peut appeler du code asynchrone dans sa
méthode __anext__.

Les itérateurs asynchrones peuvent être utilisés dans des instructions async for.

object.__aiter__(self)

Doit renvoyer un objet itérateur asynchrone.

object.__anext__(self)

Doit renvoyer un awaitable qui se traduit par la valeur suivante de l'itérateur. Doit


lever une StopAsyncIteration quand l'itération est terminée.

Un exemple d'objet itérateur asynchrone :

class Reader:
async def readline(self):
...

def __aiter__(self):
return self

async def __anext__(self):


val = await self.readline()
if val == b'':
raise StopAsyncIteration
return val

Nouveau dans la version 3.5.

Modifié dans la version 3.7: Avant Python 3.7, __aiter__ pouvait renvoyer


un awaitable qui se résolvait potentiellement en un itérateur asynchrone.

À partir de Python 3.7, __aiter__ doit renvoyer un objet itérateur asynchrone.


Renvoyer autre chose entraine une erreur TypeError.

3.4.4. Gestionnaires de contexte asynchrones


Un gestionnaire de contexte asynchrone est un gestionnaire de contexte qui est
capable de suspendre son exécution dans ses
méthodes __aenter__ et __aexit__.

Les gestionnaires de contexte asynchrones peuvent être utilisés dans des


instructions async with.

object.__aenter__(self)

Cette méthode est sémantiquement équivalente à __enter__(), à la seule


différence près qu'elle doit renvoyer un awaitable.

object.__aexit__(self, exc_type, exc_value, traceback)

Cette méthode est sémantiquement équivalente à __exit__(), à la seule différence


près qu'elle doit renvoyer un awaitable.

Un exemple de classe de gestionnaire de contexte asynchrone :

class AsyncContextManager:
async def __aenter__(self):
await log('entering context')

async def __aexit__(self, exc_type, exc, tb):


await log('exiting context')

Nouveau dans la version 3.5.

Notes
1

Il est possible, dans certains cas, de changer le type d'un objet, sous certaines
conditions. Cependant, ce n'est généralement pas une bonne idée car cela peut
conduire à un comportement très étrange si ce n'est pas géré correctement.

Les
méthodes __hash__(), __iter__(), __reversed__() et __contains__() ont
une gestion particulière pour cela ; les autres lèvent toujours TypeError, mais le
font en considérant que None n'est pas un appelable.

n'autorise pas signifie ici que la classe ne possède pas de méthode adéquate ou que
la méthode renvoie NotImplemented. N'assignez pas None à la méthode si vous
voulez un repli vers la méthode symétrique de l'opérande de droite — cela aurait
pour effet de bloquer un tel repli.

Pour des opérandes de même type, on considère que si la méthode originelle (telle
que __add__()) échoue, l'opération n'est pas autorisée et donc la méthode
symétrique n'est pas appelée.

4. Modèle d'exécution
4.1. Structure d'un programme
Un programme Python est construit à partir de blocs de code. Un block est un
morceau de texte de programme Python qui est exécuté en tant qu'unité. Les
éléments suivants sont des blocs : un module, un corps de fonction et une définition
de classe. Chaque commande écrite dans l'interpréteur interactif de Python est un
bloc. Un fichier de script (un fichier donné en entrée standard à l'interpréteur ou
spécifié en tant qu'argument de ligne de commande à l'interpréteur) est un bloc de
code. Une commande de script (une commande spécifiée sur la ligne de commande
de l'interpréteur avec l'option -c) est un bloc de code. La chaîne passée en argument
aux fonctions natives eval() et exec() est un bloc de code.

Un bloc de code est exécuté dans un cadre d'exécution. Un cadre contient des
informations administratives (utilisées pour le débogage) et détermine où et comment
l'exécution se poursuit après la fin de l'exécution du bloc de code.
4.2. Noms et liaisons
4.2.1. Liaisons des noms
Les noms sont des références aux objets. Ils sont créés lors des opérations de
liaisons de noms (name binding en anglais).

Les constructions suivantes conduisent à des opérations de liaison à des noms : les
paramètres formels d'une fonction, les instructions import, les définitions de fonctions
et de classes (le nom de la classe ou de la fonction est lié au bloc qui la définit) et les
cibles qui sont des identifiants dans les assignations, les entêtes de boucles for ou
après as dans une instruction with ou une clause except. L'instruction import sous la
forme from ... import * lie tous les noms définis dans le module importé, sauf ceux
qui commencent par un tiret bas ('_'). Cette forme ne doit être utilisée qu'au niveau
du module.

Une cible qui apparaît dans une instruction del est aussi considérée comme une
liaison à un nom dans ce cadre (bien que la sémantique véritable soit de délier le
nom).

Chaque assignation ou instruction import a lieu dans un bloc défini par une définition
de classe ou de fonction ou au niveau du module (le bloc de code de plus haut
niveau).

Si un nom est lié dans un bloc, c'est une variable locale de ce bloc, à moins qu'il ne
soit déclaré nonlocal ou global. Si un nom est lié au niveau du module, c'est une
variable globale (les variables du bloc de code de niveau module sont locales et
globales). Si une variable est utilisée dans un bloc de code alors qu'elle n'y est pas
définie, c'est une variable libre.

Chaque occurrence d'un nom dans un programme fait référence à la liaison de ce


nom établie par les règles de résolution des noms suivantes.

4.2.2. Résolution des noms


La portée définit la visibilité d'un nom dans un bloc. Si une variable locale est définie
dans un bloc, sa portée comprend ce bloc. Si la définition intervient dans le bloc
d'une fonction, la portée s'étend à tous les blocs contenus dans celui qui comprend la
définition, à moins qu'un bloc intérieur ne définisse une autre liaison pour ce nom.

Quand un nom est utilisé dans un bloc de code, la résolution utilise la portée la plus
petite. L'ensemble de toutes les portées visibles dans un bloc de code
s'appelle l'environnement du bloc.
Quand un nom n'est trouvé nulle part, une exception NameError est levée. Si la portée
courante est celle d'une fonction et que le nom fait référence à une variable locale
qui n'a pas encore été liée au moment où le nom est utilisé, une
exception UnboundLocalError est levée. UnboundLocalError est une sous-classe
de NameError.

Si une opération de liaison intervient dans un bloc de code, toutes les utilisations du
nom dans le bloc sont considérées comme des références au bloc courant. Ceci peut
conduire à des erreurs quand un nom est utilisé à l'intérieur d'un bloc avant d'être lié.
La règle est subtile. Python n'attend pas de déclaration de variables et autorise les
opérations de liaison n'importe où dans un bloc de code. Les variables locales d'un
bloc de code peuvent être déterminées en parcourant tout le texte du bloc à la
recherche des opérations de liaisons.

Si l'instruction global apparaît dans un bloc, toutes les utilisations du nom spécifié


dans l'instruction font référence à la liaison de ce nom dans l'espace de nommage de
plus haut niveau. Les noms sont résolus dans cet espace de nommage de plus haut
niveau en recherchant l'espace des noms globaux, c'est-à-dire l'espace de nommage
du module contenant le bloc de code ainsi que dans l'espace de nommage natif,
celui du module builtins. La recherche commence dans l'espace de nommage
globaux. Si le nom n'y est pas trouvé, la recherche se poursuit dans l'espace de
nommage natif. L'instruction global doit précéder toute utilisation du nom considéré.

L'instruction global a la même porte qu'une opération de liaison du même bloc. Si la


portée englobante la plus petite pour une variable libre contient une
instruction global, la variable libre est considérée globale.

L'instruction nonlocal fait que les noms correspondants font référence aux variables


liées précédemment dans la portée de fonction englobante la plus petite
possible. SyntaxError est levée à la compilation si le nom donné n'existe dans aucune
portée de fonction englobante.

L'espace de nommage pour un module est créé automatiquement la première fois


que le module est importé. Le module principal d'un script s'appelle
toujours __main__.

Les blocs de définition de classe et les arguments de exec() ainsi que eval() sont


traités de manière spéciale dans le cadre de la résolution des noms. Une définition
de classe est une instruction exécutable qui peut utiliser et définir des noms. Toutes
ces références suivent les règles normales de la résolution des noms à l'exception
des variables locales non liées qui sont recherchées dans l'espace des noms
globaux. L'espace de nommage de la définition de classe devient le dictionnaire des
attributs de la classe. La portée des noms définis dans un bloc de classe est limitée
au bloc de la classe ; elle ne s'étend pas aux blocs de code des méthodes — y
compris les compréhensions et les expressions générateurs puisque celles-ci sont
implémentées en utilisant une portée de fonction. Ainsi, les instructions suivantes
échouent :

class A:
a = 42
b = list(a + i for i in range(10))

4.2.3. Noms natifs et restrictions d'exécution


CPython implementation detail: L'utilisateur ne doit pas toucher à __builtins__ ;
c'est et cela doit rester réservé aux besoins de l'implémentation. Les utilisateurs qui
souhaitent surcharger des valeurs dans l'espace de nommage natif
doivent importer le module builtins et modifier ses attributs judicieusement.

L'espace de nommage natif associé à l'exécution d'un bloc de code est effectivement
trouvé en cherchant le nom __builtins__ dans l'espace de nommage globaux ; ce doit
être un dictionnaire ou un module (dans ce dernier cas, le dictionnaire du module est
utilisé). Par défaut, lorsque l'on se trouve dans le module __main__, __builtins__ est le
module natif builtins ; lorsque l'on se trouve dans tout autre module, __builtins__ est un
pseudonyme du dictionnaire du module builtins lui-même.

4.2.4. Interaction avec les fonctionnalités dynamiques


La résolution des noms de variables libres intervient à l'exécution, pas à la
compilation. Cela signifie que le code suivant affiche 42 :

i = 10
def f():
print(i)
i = 42
f()

Les fonctions eval() et exec() n'ont pas accès à l'environnement complet pour


résoudre les noms. Les noms doivent être résolus dans les espaces de nommage
locaux et globaux de l'appelant. Les variables libres ne sont pas résolues dans
l'espace de nommage englobant le plus proche mais dans l'espace de nommage
globaux 1. Les fonctions eval() et exec() possèdent des arguments optionnels pour
surcharger les espaces de nommage globaux et locaux. Si seulement un espace de
nommage est spécifié, il est utilisé pour les deux.
4.3. Exceptions
Les exceptions sont un moyen de sortir du flot normal d'exécution d'un bloc de code
de manière à gérer des erreurs ou des conditions exceptionnelles. Une exception
est levée au moment où l'erreur est détectée ; elle doit être gérée par le bloc de code
qui l'entoure ou par tout bloc de code qui a, directement ou indirectement, invoqué le
bloc de code où l'erreur s'est produite.

L'interpréteur Python lève une exception quand il détecte une erreur à l'exécution
(telle qu'une division par zéro). Un programme Python peut aussi lever explicitement
une exception avec l'instruction raise. Les gestionnaires d'exception sont spécifiés
avec l'instruction try … except. La clause finally d'une telle instruction peut être utilisée
pour spécifier un code de nettoyage qui ne gère pas l'exception mais qui est exécuté
quoi qu'il arrive (exception ou pas).

Python utilise le modèle par terminaison de gestion des erreurs : un gestionnaire


d'exception peut trouver ce qui est arrivé et continuer l'exécution à un niveau plus
élevé, mais il ne peut pas réparer l'origine de l'erreur et ré-essayer l'opération qui a
échoué (sauf à entrer à nouveau dans le code en question par le haut).

Quand une exception n'est pas du tout gérée, l'interpréteur termine l'exécution du
programme ou retourne à la boucle interactive. Dans ces cas, il affiche une trace de
la pile d'appels, sauf si l'exception est SystemExit.

Les exceptions sont identifiées par des instances de classe. La


clause except sélectionnée dépend de la classe de l'instance : elle doit faire référence
à la classe de l'instance ou à une de ses classes ancêtres. L'instance peut être
transmise au gestionnaire et peut apporter des informations complémentaires sur les
conditions de l'exception.

Note
 

Les messages d'exception ne font pas partie de l'API Python. Leur contenu peut
changer d'une version de Python à une autre sans avertissement et le code ne doit
pas reposer sur ceux-ci s'il doit fonctionner sur plusieurs versions de l'interpréteur.

Reportez-vous aussi aux descriptions de l'instruction try dans la section L'instruction


try et de l'instruction raise dans la section L'instruction raise.

Notes
1

En effet, le code qui est exécuté par ces opérations n'est pas connu au moment où le
module est compilé.

5. Le système d'importation


Le code Python d'un module peut accéder à du code d'un autre module par un
mécanisme qui consiste à importer cet autre module. L'instruction import est la
façon la plus courante faire appel à ce système d'importation, mais ce n'est pas la
seule. Les fonctions telles
que importlib.import_module() et __import__() peuvent aussi être utilisées
pour mettre en œuvre le mécanisme d'importation.

L'instruction import effectue deux opérations ; elle cherche le module dont le nom a


été donné puis elle lie le résultat de cette recherche à un nom dans la portée locale.
L'opération de recherche de l'instruction import consiste à appeler la
fonction __import__() avec les arguments adéquats. La valeur renvoyée
par __import__() est utilisée pour effectuer l'opération de liaison avec le nom
fourni à l'instruction import. Reportez-vous à l'instruction import pour les détails
exacts de l'opération de liaison avec le nom.

Un appel direct à __import__() effectue seulement la recherche du module et, s'il


est trouvé, l'opération de création du module. Bien que des effets collatéraux
puissent se produire, tels que l'importation de paquets parents et la mise à jour de
divers caches (y compris sys.modules), il n'y a que l'instruction import qui
déclenche l'opération de liaison avec le nom.

Quand une instruction import est exécutée, la fonction native __import__() est


appelée. D'autres mécanismes d'appel au système d'importation (tels
que importlib.import_module()) peuvent choisir d'ignorer __import__() et
utiliser leurs propres solutions pour implémenter la sémantique d'importation.

Quand un module est importé pour la première fois, Python recherche le module et,
s'il est trouvé, créé un objet module 1 en l'initialisant. Si le module n'est pas trouvé,
une ModuleNotFoundError est levée. Python implémente plusieurs stratégies pour
rechercher le module d'un nom donné quand le mécanisme d'import est invoqué.
Ces stratégies peuvent être modifiées et étendues par divers moyens décrits dans
les sections suivantes.

Modifié dans la version 3.3: Le système d'importation a été mis à jour pour
implémenter complètement la deuxième partie de la PEP 302. Il n'existe plus de
mécanisme implicite d'importation (le système d'importation complet est
exposé via sys.meta_path). En complément, la gestion du paquet des noms natifs
a été implémenté (voir la PEP 420).

5.1. importlib
Le module importlib fournit une API riche pour interagir avec le système d'import.
Par exemple, importlib.import_module() fournit une API (que nous vous
recommandons) plus simple que la fonction native __import__() pour mettre en
œuvre le mécanisme d'import. Reportez-vous à la documentation de la
bibliothèque importlib pour obtenir davantage de détails.

5.2. Les paquets
Python ne connait qu'un seul type d'objet module et tous les modules sont donc de
ce type, que le module soit implémenté en Python, en C ou quoi que ce soit d'autre.
Pour aider à l'organisation des modules et fournir une hiérarchie des noms, Python
développe le concept de paquets.

Vous pouvez vous représenter les paquets comme des répertoires dans le système
de fichiers et les modules comme des fichiers dans ces répertoires. Mais ne prenez
pas trop cette analogie au pied de la lettre car les paquets et les modules ne
proviennent pas obligatoirement du système de fichiers. Dans le cadre de cette
documentation, nous utilisons cette analogie bien pratique des répertoires et des
fichiers. Comme les répertoires du système de fichiers, les paquets sont organisés
de manière hiérarchique et les paquets peuvent eux-mêmes contenir des sous-
paquets ou des modules.

Il est important de garder à l'esprit que tous les paquets sont des modules mais que
tous les modules ne sont pas des paquets. Formulé autrement, les paquets sont
juste un certain type de modules. Spécifiquement, tout module qui contient un
attribut __path__ est réputé être un paquet.

Tous les modules ont un nom. Les noms des sous-paquets sont séparés du nom du
paquet parent par des points (.), à l'instar de la syntaxe standard d'accès aux
attributs en Python. Ainsi, vous pouvez avoir un module nommé sys et un paquet
nommé email, qui à son tour possède un sous-paquet nommé email.mime avec un
module dans ce sous-paquet nommé email.mime.text.
5.2.1. Paquets classiques
Python définit deux types de paquets, les paquets classiques et les paquets espaces
de nommage. Les paquets classiques sont les paquets traditionnels tels qu'ils
existaient dans Python 3.2 et antérieurs. Un paquet classique est typiquement
implémenté sous la forme d'un répertoire contenant un fichier __init__.py. Quand
un paquet classique est importé, ce fichier __init__.py est implicitement exécuté.

Par exemple, l'arborescence suivante définit un paquet parent au niveau le plus


haut avec trois sous-paquets :

parent/
__init__.py
one/
__init__.py
two/
__init__.py
three/
__init__.py

Importer parent.one exécute
implicitement parent/__init__.py et parent/one/__init__.py. Les
importations postérieures de parent.two ou parent.three respectivement
exécutent parent/two/__init__.py ou parent/three/__init__.py respective
ment.

5.2.2. Paquets espaces de nommage


Un paquet-espace de nommage est la combinaison de plusieurs portions où chaque
portion fournit un sous-paquet au paquet parent. Les portions peuvent être situées à
différents endroits du système de fichiers. Les portions peuvent aussi être stockées
dans des fichiers zip, sur le réseau ou à tout autre endroit dans lequel Python
cherche pendant l'importation. Les paquets-espaces de nommage peuvent
correspondre directement à des objets du système de fichiers, ou pas ; ils peuvent
être des modules virtuels qui n'ont aucune représentation concrète.

Les paquets-espaces de nommage n'utilisent pas une liste ordinaire pour leur
attribut __path__. Ils utilisent en lieu et place un type itérable personnalisé qui
effectue automatiquement une nouvelle recherche de portions de paquets à la
tentative suivante d'importation dans le paquet si le chemin de leur paquet parent
(ou sys.path pour les paquets de plus haut niveau) change.
Pour les paquets-espaces de nommage, il n'existe pas de
fichier parent/__init__.py. En fait, il peut y avoir plusieurs
répertoires parent trouvés pendant le processus d'importation, où chacun est
apporté par une portion différente. Ainsi, parent/one n'est pas forcément
physiquement à côté de parent/two. Dans ce cas, Python crée un paquet-espace
de nommage pour le paquet de plus haut niveau parent dès que lui ou l'un de ses
sous-paquet est importé.

Voir aussi la PEP 420 pour les spécifications des paquets-espaces de nommage.

5.3. Recherche
Pour commencer la recherche, Python a besoin du nom qualifié du module (ou du
paquet, mais ici cela ne fait pas de différence) que vous souhaitez importer. Le nom
peut être donné en argument à l'instruction import ou comme paramètre aux
fonctions importlib.import_module() ou __import__().

Le nom est utilisé dans plusieurs phases de la recherche et peut être un chemin
séparé par des points pour un sous-module, par exemple truc.machin.bidule.
Dans ce cas, Python essaie d'abord d'importer truc puis truc.machin et
enfin truc.machin.bidule. Si n'importe laquelle des importations intermédiaires
échoue, une ModuleNotFoundError est levée.

5.3.1. Cache des modules


Le premier endroit vérifié pendant la recherche d'une importation est sys.modules.
Ce tableau de correspondances est utilisé comme cache de tous les modules déjà
importés, y compris les chemins intermédiaires. Ainsi, si truc.machin.bidule a
déjà été importé, sys.modules contient les entrées correspondantes
à truc, truc.machin et truc.machin.bidule. À chaque chemin correspond une
clé.

Pendant l'importation, le nom de module est cherché dans sys.modules et, s'il est


trouvé, la valeur associée est le module recherché et le processus est fini.
Cependant, si la valeur est None, alors une ModuleNotFoundError est levée. Si le
nom du module n'est pas trouvé, Python continue la recherche du module.

sys.modules est accessible en lecture-écriture. Supprimer une clé peut ne pas


détruire le module associé (car d'autres modules contiennent possiblement des
références vers ce module), mais cela invalide l'entrée du cache pour ce nom de
module. Python cherche alors un nouveau module pour ce nom. La clé peut aussi
être assignée à None de manière à forcer une ModuleNotFoundError lors de la
prochaine importation du module.

Attention cependant : s'il reste une référence à l'objet module et que vous invalidez
l'entrée dans le cache de sys.modules puis ré-importez le module, les deux objets
modules ne seront pas les mêmes. À l'inverse, importlib.reload() ré-utilise
le même objet module et ré-initialise simplement le contenu du module en ré-
exécutant le code du module.

5.3.2. Chercheurs et chargeurs
Si le module n'est pas trouvé dans sys.modules, alors Python utilise son protocole
d'importation pour chercher et charger le module. Ce protocole se compose de deux
objets conceptuels : les chercheurs et les chargeurs. Le travail du chercheur consiste
à trouver, à l'aide de différentes stratégies, le module dont le nom a été fourni. Les
objets qui implémentent ces deux interfaces sont connus sous le vocable
"importateurs" (ils renvoient une référence vers eux-mêmes quand ils trouvent un
module qui répond aux attentes).

Python inclut plusieurs chercheurs et importateurs par défaut. Le premier sait


comment trouver les modules natifs et le deuxième sait comment trouver les modules
gelés. Un troisième chercheur recherche les modules dans import path. import
path est une énumération sous forme de liste de chemins ou de fichiers zip. Il peut
être étendu pour rechercher aussi dans toute ressource qui dispose d'un identifiant
pour la localiser, une URL par exemple.

Le mécanisme d'importation est extensible, vous pouvez donc ajouter de nouveaux


chercheurs pour étendre le domaine de recherche des modules.

Les chercheurs ne chargent pas les modules. S'il trouve le module demandé, un
chercheur renvoie un spécificateur de module, qui contient toutes les informations
nécessaires pour importer le module ; celui-ci sera alors utilisé par le mécanisme
d'importation pour charger le module.

Les sections suivantes décrivent plus en détail le protocole utilisé par les chercheurs
et les chargeurs, y compris la manière de les créer et les enregistrer pour étendre le
mécanisme d'importation.

Modifié dans la version 3.4: Dans les versions précédentes de Python, les


chercheurs renvoyaient directement les chargeurs. Dorénavant, ils renvoient des
spécificateurs de modules qui contiennent les chargeurs. Les chargeurs sont encore
utilisés lors de l'importation mais ont moins de responsabilités.
5.3.3. Points d'entrées automatiques pour l'importation
Le mécanisme d'importation est conçu pour être extensible ; vous pouvez y insérer
des points d'entrée automatique (hooks en anglais). Il existe deux types de points
d'entrée automatique pour l'importation : les méta-points d'entrée et les points
d'entrée sur le chemin des importations.

Les méta-points d'entrée sont appelés au début du processus d'importation, juste


après la vérification dans le cache sys.modules mais avant tout le reste. Ceci
permet aux méta-points d'entrée de surcharger le traitement effectué sur sys.path,
les modules gelés ou même les modules natifs. L'enregistrement des méta-points
d'entrée se fait en ajoutant de nouveaux objets chercheurs à sys.meta_path,
comme décrit ci-dessous.

Les points d'entrée sur le chemin des importations sont appelés pendant le
traitement de sys.path (ou package.__path__), au moment où le chemin qui leur
correspond est atteint. Les points d'entrée sur le chemin des importations sont
enregistrés en ajoutant de nouveaux appelables à sys.path_hooks, comme décrit
ci-dessous.

5.3.4. Méta-chemins
Quand le module demandé n'est pas trouvé dans sys.modules, Python recherche
alors dans sys.meta_path qui contient une liste d'objets chercheurs dans des
méta-chemins. Ces chercheurs sont interrogés dans l'ordre pour voir s'ils savent
prendre en charge le module passé en paramètre. Les chercheurs dans les méta-
chemins implémentent une méthode find_spec() qui prend trois arguments : un
nom, un chemin d'import et (optionnellement) un module cible. Un chercheur dans
les méta-chemins peut utiliser n'importe quelle stratégie pour déterminer s'il est apte
à prendre en charge le module.

Si un chercheur dans les méta-chemins sait prendre en charge le module donné, il


renvoie un objet spécificateur. S'il ne sait pas, il renvoie None. Si le traitement
de sys.meta_path arrive à la fin de la liste sans qu'aucun chercheur n'a renvoyé un
objet spécificateur, alors une ModuleNotFoundError est levée. Toute autre
exception levée est simplement propagée à l'appelant, mettant fin au processus
d'importation.

La méthode find_spec() des chercheurs dans les méta-chemins est appelée avec


deux ou trois arguments. Le premier est le nom complètement qualifié du module à
importer, par exemple truc.machin.bidule. Le deuxième argument est l'ensemble
des chemins dans lesquels chercher. Pour les modules de plus haut niveau, le
deuxième argument est None mais pour les sous-modules ou les paquets, le
deuxième argument est la valeur de l'attribut __path__ du paquet parent. Si
l'attribut __path__ approprié n'est pas accessible, une ModuleNotFoundError est
levée. Le troisième argument est un objet module existant qui va être la cible du
chargement (plus tard). Le système d'importation ne passe le module cible en
paramètre que lors d'un rechargement.

Le méta-chemin peut être parcouru plusieurs fois pour une seule requête
d'importation. Par exemple, si nous supposons qu'aucun des modules concernés n'a
déjà été mis en cache, importer truc.machin.bidule effectue une première
importation au niveau le plus haut, en
appelant c_m_c.find_spec("truc", None, None) pour chaque chercheur dans
les méta-chemins (c_m_c). Après que truc a été importé, truc.machin est importé
en parcourant le méta-chemin une deuxième fois,
appelant c_m_c.find_spec("truc.machin", truc.__path__, None). Une
fois truc.machin importé, le parcours final
appelle c_m_c.find_spec("truc.machin.bidule", truc.machin.__path__, 
None).

Quelques chercheurs dans les méta-chemins ne gèrent que les importations de plus
haut niveau. Ces importateurs renvoient toujours None si on leur passe un deuxième
argument autre que None.

Le sys.meta_path de Python comprend trois chercheurs par défaut : un qui sait


importer les modules natifs, un qui sait importer les modules gelés et un qui sait
importer les modules depuis un chemin des importations (c'est le chercheur dans
path).

Modifié dans la version 3.4: La méthode find_spec() des chercheurs dans les


méta-chemins a remplacé find_module(), devenue obsolète. Bien qu'elle continue
de fonctionner comme avant, le mécanisme d'importation
essaie find_module() uniquement si le chercheur n'implémente
pas find_spec().

5.4. Chargement
Quand un spécificateur de module est trouvé, le mécanisme d'importation l'utilise (et
le chargeur qu'il contient) pour charger le module. Voici à peu près ce qui se passe
au sein de l'importation pendant la phase de chargement :

module = None
if spec.loader is not None and hasattr(spec.loader,
'create_module'):
# It is assumed 'exec_module' will also be defined on the
loader.
module = spec.loader.create_module(spec)
if module is None:
module = ModuleType(spec.name)
# The import-related module attributes get set here:
_init_module_attrs(spec, module)

if spec.loader is None:
if spec.submodule_search_locations is not None:
# namespace package
sys.modules[spec.name] = module
else:
# unsupported
raise ImportError
elif not hasattr(spec.loader, 'exec_module'):
module = spec.loader.load_module(spec.name)
# Set __loader__ and __package__ if missing.
else:
sys.modules[spec.name] = module
try:
spec.loader.exec_module(module)
except BaseException:
try:
del sys.modules[spec.name]
except KeyError:
pass
raise
return sys.modules[spec.name]

Notez les détails suivants :

 S'il existe un objet module dans sys.modules avec le même nom, import


l'aurait déjà renvoyé.
 Le module existe dans sys.modules avant que le chargeur exécute le code
du module. C'est crucial car le code du module peut (directement ou indirectement)
s'importer lui-même ; l'ajouter à sys.modules avant évite les récursions infinies
dans le pire cas et le chargement multiple dans le meilleur des cas.
 Si le chargement échoue, le module en cause (et seulement ce module) est
enlevé de sys.modules. Tout module déjà dans le cache de sys.modules et tout
module qui a été chargé avec succès par effet de bord doit rester dans le cache.
C'est différent dans le cas d'un rechargement où même le module qui a échoué est
conservé dans sys.modules.
 Après que le module est créé mais avant son exécution, le mécanisme
d'importation définit les attributs relatifs à l'importation ( _init_module_attrs dans
l'exemple de pseudo-code ci-dessus), comme indiqué brièvement dans
une section que nous abordons ensuite.
 L'exécution du module est le moment clé du chargement dans lequel l'espace
de nommage du module est peuplé. L'exécution est entièrement déléguée au
chargeur qui doit décider ce qui est peuplé et comment.
 Le modulé créé pendant le chargement et passé à exec_module() peut ne
pas être celui qui est renvoyé à la fin de l'importation 2.

Modifié dans la version 3.4: Le système d'importation a pris en charge les


responsabilités des chargeurs. Celles-ci étaient auparavant effectuées par la
méthode importlib.abc.Loader.load_module().

5.4.1. Chargeurs
Les chargeurs de modules fournissent la fonction critique du chargement : l'exécution
du module. Le mécanisme d'importation appelle la
méthode importlib.abc.Loader.exec_module() avec un unique argument,
l'objet module à exécuter. Toute valeur renvoyée par exec_module() est ignorée.

Les chargeurs doivent satisfaire les conditions suivantes :

 Si le module est un module Python (par opposition aux modules natifs ou aux
extensions chargées dynamiquement), le chargeur doit exécuter le code du module
dans l'espace des noms globaux du module ( module.__dict__).
 Si le chargeur ne peut pas exécuter le module, il doit lever une ImportError,
alors que toute autre exception levée durant exec_module() est propagée.

Souvent, le chercheur et le chargeur sont le même objet ; dans ce cas, la


méthode find_spec() doit juste renvoyer un spécificateur avec le chargeur défini
à self.

Les chargeurs de modules peuvent choisir de créer l'objet module pendant le


chargement en implémentant une méthode create_module(). Elle prend un
argument, l'objet spécificateur du module et renvoie le nouvel objet du module à
utiliser pendant le chargement. Notez que create_module() n'a besoin de définir
aucun attribut sur l'objet module. Si cette méthode renvoie None, le mécanisme
d'importation crée le nouveau module lui-même.

Nouveau dans la version 3.4: La méthode create_module() des chargeurs.


Modifié dans la version 3.4: La méthode load_module() a été remplacée
par exec_module() et le mécanisme d'import assume toutes les responsabilités du
chargement.

Par compatibilité avec les chargeurs existants, le mécanisme d'importation utilise la


méthode load_module() des chargeurs si elle existe et si le chargeur n'implémente
pas exec_module(). Cependant, load_module() est déclarée obsolète et les
chargeurs doivent implémenter exec_module() à la place.

La méthode load_module() doit implémenter toutes les fonctionnalités de


chargement décrites ci-dessus en plus de l'exécution du module. Toutes les
contraintes s'appliquent aussi, avec quelques précisions supplémentaires :

 S'il y a un objet module existant avec le même nom dans sys.modules, le


chargeur doit utiliser le module existant (sinon, importlib.reload() ne
fonctionnera pas correctement). Si le module considéré n'est pas trouvé
dans sys.modules, le chargeur doit créer un nouvel objet module et l'ajouter
à sys.modules.
 Le module doit exister dans sys.modules avant que le chargeur n'exécute le
code du module, afin d'éviter les récursions infinies ou le chargement multiple.
 Si le chargement échoue, le chargeur ne doit enlever de sys.modules que le
(ou les) module ayant échoué et seulement si le chargeur lui-même a chargé le
module explicitement.

Modifié dans la version 3.5: Un avertissement DeprecationWarning est levé


quand exec_module() est définie mais create_module() ne l'est pas.

Modifié dans la version 3.6: Une exception ImportError est levée


quand exec_module() est définie mais create_module() ne l'est pas.

5.4.2. Sous-modules
Quand un sous-module est chargé, quel que soit le mécanisme (par exemple avec
les instructions import, import-from ou avec la fonction native __import__()),
une liaison est créée dans l'espace de nommage du module parent vers l'objet sous-
module. Par exemple, si le paquet spam possède un sous-module foo, après
l'importation de spam.foo, spam possède un attribut foo qui est lié au sous-module.
Supposons que nous ayons l'arborescence suivante :

spam/
__init__.py
foo.py
bar.py

et que le contenu de spam/__init__.py soit :

from .foo import Foo


from .bar import Bar

alors exécuter les lignes suivantes crée des liens vers foo et bar dans le


module spam :

>>>

>>> import spam


>>> spam.foo
<module 'spam.foo' from '/tmp/imports/spam/foo.py'>
>>> spam.bar
<module 'spam.bar' from '/tmp/imports/spam/bar.py'>

Connaissant la façon habituelle dont Python effectue les liens, cela peut sembler
surprenant. Mais c'est en fait une fonctionnalité fondamentale du système
d'importation. Si vous avez quelque
part sys.modules['spam'] et sys.modules['spam.foo'] (comme dans c'est le
cas ci-dessus après l'importation), alors le dernier doit apparaître comme
l'attribut foo du premier.

5.4.3. Spécificateurs de modules
Le mécanisme d'importation utilise diverses informations de chaque module pendant
l'importation, spécialement avant le chargement. La plupart de ces informations sont
communes à tous les modules. Le but d'un spécificateur de module est d'encapsuler
ces informations relatives à l'importation au sein de chaque module.

Utiliser un spécificateur pendant l'importation permet de transférer l'état entre les


composants du système d'importation, par exemple entre le chercheur qui crée le
spécificateur de module et le chargeur qui l'exécute. Surtout, cela permet au
mécanisme d'importation d'effectuer toutes les opérations classiques de chargement,
alors que c'était le chargeur qui en avait la responsabilité quand il n'y avait pas de
spécificateur.

Le spécificateur de module est accessible par l'attribut __spec__ de l'objet module.


Lisez ModuleSpec pour davantage d'informations sur le contenu du spécificateur de
module.
Nouveau dans la version 3.4.

5.4.4. Attributs des modules importés


Le mécanisme d'importation renseigne ces attributs pour chaque objet module
pendant le chargement, sur la base du spécificateur de module et avant que le
chargeur n'exécute le module.

__name__
L'attribut __name__ doit contenir le nom complètement qualifié du module. Ce nom
est utilisé pour identifier de manière non équivoque le module dans le mécanisme
d'importation.

__loader__
L'attribut __loader__ doit pointer vers l'objet chargeur que le mécanisme
d'importation a utilisé pour charger le module. L'utilisation principale concerne
l'introspection, mais il peut être utilisé pour d'autres fonctionnalités relatives au
chargement. Par exemple, obtenir des données par l'intermédiaire du chargeur.

__package__
L'attribut __package__ du module doit être défini. Sa valeur doit être une chaîne de
caractères, qui peut être la même que son attribut __name__. Quand le module est
un paquet, la valeur de __package__ doit être définie à la même valeur que
son __name__. Quand le module n'est pas un paquet, __package__ doit être la
chaîne vide pour les modules de niveau le plus haut, et le nom du paquet parent
pour les sous-modules. Voir la PEP 366 pour plus de détails.

Cet attribut est utilisé à la place de __name__ pour calculer les importations relatives
explicites des modules principaux, comme défini dans la PEP 366. Il devrait avoir la
même valeur que __spec__.parent.

Modifié dans la version 3.6: La valeur de __package__ devrait être la même que


celle de __spec__.parent.

__spec__
L'attribut __spec__ doit contenir un lien vers le spécificateur de module qui a été
utilisé lors de l'importation du module. Définir __spec__ correctement s'applique
aussi pour l'initialisation des modules au démarrage de l'interpréteur. La seule
exception concerne __main__ où la valeur de __spec__ est None dans certains
cas.
Quand __package__ n'est pas défini, __spec__.parent est utilisé par défaut.

Nouveau dans la version 3.4.

Modifié dans la version 3.6:  __spec__.parent est utilisé par défaut


quand __package__ n'est pas défini.

__path__
Si le module est un paquet (classique ou espace de nommage),
l'attribut __path__ de l'objet module doit être défini. La valeur doit être un itérable
mais peut être vide si __path__ n'a pas de sens dans le contexte.
Si __path__ n'est pas vide, il doit produire des chaînes lorsque l'on itère dessus.
Vous trouvez plus de détails sur la sémantique de __path__ plus loin ci-dessous.

Les modules qui ne sont pas des paquets ne doivent pas avoir d'attribut __path__.

__file__
__cached__
__file__ est optionnel. S'il est défini, la valeur de cet attribut doit être une chaîne.
Le système d'importation peut décider de laisser __file__ indéfini si cela ne fait pas
sens de le définir (par exemple, lorsqu'on charge un module depuis une base de
données).

Si __file__ est défini, il peut être judicieux de définir l'attribut __cached__ dont la


valeur est le chemin vers une version compilée du code (par exemple, le
fichier bytecode). Le fichier n'a pas besoin d'exister pour définir cet attribut : le
chemin peut simplement pointer vers l'endroit où le fichier compilé aurait été placé
(voir la PEP 3147).

Vous pouvez aussi définir __cached__ quand __file__ n'est pas défini.


Cependant, ce scénario semble rare. Au final, c'est le chargeur qui utilise les valeurs
de __file__ ou __cached__. Donc, si le chargeur peut charger depuis un module
mis en cache mais ne peut pas charger depuis un fichier, ce scénario a du sens.

5.4.5. module.__path__
Par définition, si un module possède un attribut __path__, c'est un paquet.

L'attribut __path__ d'un paquet est utilisé pendant l'importation des sous-paquets.


Dans le mécanisme d'importation, son fonctionnement ressemble beaucoup
à sys.path, c'est-à-dire qu'il fournit une liste d'emplacements où rechercher les
modules pendant l'importation. Cependant, __path__ est beaucoup plus contraint
que sys.path.

__path__ doit être un itérable de chaînes de caractères, mais il peut être vide. Les
mêmes règles que pour sys.path s'appliquent au __path__ d'un paquet
et sys.path_hooks (dont la description est donnée plus bas) est consulté pendant
le parcours de __path__ du paquet.

Le fichier __init__.py d'un paquet peut définir ou modifier l'attribut __path__ d'un


paquet, et c'est ainsi qu'étaient implémentés les paquets-espaces de nommage
avant la PEP 420. Depuis l'adoption de la PEP 420, les paquets-espaces de
nommage n'ont plus besoin d'avoir des fichiers __init__.py qui ne font que de la
manipulation de __path__ ; le mécanisme d'importation définit
automatiquement __path__ correctement pour un paquet-espace de nommage.

5.4.6. Représentation textuelle d'un module


Par défaut, tous les modules ont une représentation textuelle utilisable. Cependant,
en utilisant les attributs définis ci-dessus et dans le spécificateur de module, vous
pouvez explicitement mieux contrôler l'affichage des objets modules.

Si le module possède un spécificateur ( __spec__), le mécanisme d'importation


essaie de générer une représentation avec celui-ci. S'il échoue ou s'il n'y a pas de
spécificateur, le système d'importation construit une représentation par défaut en
utilisant toute information disponible sur le module. Il tente
d'utiliser module.__name__, module.__file__ et module.__loader__ comme
entrées pour la représentation, avec des valeurs par défaut lorsque l'information est
manquante.

Les règles exactes utilisées sont :

 Si le module possède un attribut __spec__, la valeur est utilisée pour générer


la représentation. Les attributs name, loader, origin et has_location sont consultés.
 Si le module possède un attribut __file__, il est utilisé pour construire la
représentation du module.
 Si le module ne possède pas d'attribut __file__ mais possède
un __loader__ qui n'est pas None, alors la représentation du chargeur est utilisée
pour construire la représentation du module.
 Sinon, il utilise juste le __name__ du module dans la représentation.
Modifié dans la version 3.4: L'utilisation de loader.module_repr() est devenue
obsolète et le spécificateur de module est utilisé dorénavant par le mécanisme
d'importation pour générer la représentation textuelle du module.

Par compatibilité descendante avec Python 3.3, la représentation textuelle du


module est générée en appelant la méthode module_repr() du chargeur, si elle est
définie, avant même d'essayer l'approche décrite ci-dessus. Cependant, cette
méthode est obsolète.

5.4.7. Invalidation de bytecode mis en cache


Before Python loads cached bytecode from .pyc file, it checks whether the cache is
up-to-date with the source .py file. By default, Python does this by storing the
source's last-modified timestamp and size in the cache file when writing it. At runtime,
the import system then validates the cache file by checking the stored metadata in
the cache file against the source's metadata.

Python gère également les fichiers caches "avec empreintes", qui stockent une
empreinte (hash en anglais) du contenu de la source plutôt que des métadonnées. Il
existe deux variations des fichiers .pyc avec empreintes : vérifiés et non-vérifiés.
Pour les fichiers .pyc avec empreinte vérifiés, Python valide le fichier cache en
calculant l'empreinte du fichier source et compare les empreintes. Si l'empreinte
stockée dans le fichier cache est invalide, Python la recalcule et écrit un nouveau
fichier cache avec empreinte. Pour les fichiers .pyc avec empreinte non vérifiés,
Python considère simplement que le fichier cache est valide s'il existe. La validation
(ou non) des fichiers .pyc avec empreinte peut être définie avec l'option --check-
hash-based-pycs.

Modifié dans la version 3.7: Ajout des fichiers .pyc avec empreinte. Auparavant,


Python gérait les caches de bytecode sur la base de l'horodatage.

5.5. Le chercheur dans path


Comme indiqué précédemment, Python est livré par défaut avec plusieurs
chercheurs dans les méta-chemins. L'un deux, appelé chercheur dans
path (PathFinder), recherche dans le chemin des importations qui contient une
liste d'entrées dans path. Chaque entrée désigne un emplacement où rechercher des
modules.

Le chercheur dans path en tant que tel ne sait pas comment importer quoi que ce
soit. Il ne fait que parcourir chaque entrée de path et associe à chacune d'elle un
"chercheur d'entrée dans path" qui sait comment gérer le type particulier de chemin
considéré.

L'ensemble par défaut des "chercheurs d'entrée dans path" implémente toute la


sémantique pour trouver des modules dans le système de fichiers, gérer des fichiers
spéciaux tels que le code source Python (fichiers .py), le bytecode Python
(fichiers .pyc) et les bibliothèques partagées (par exemple les fichiers .so). Quand
le module zipimport de la bibliothèque standard le permet, les "chercheurs
d'entrée dans path" par défaut savent aussi gérer tous ces types de fichiers (autres
que les bibliothèques partagées) encapsulés dans des fichiers zip.

Les chemins ne sont pas limités au système de fichiers. Ils peuvent faire référence à
des URL, des requêtes dans des bases de données ou tout autre emplacement qui
peut être spécifié dans une chaîne de caractères.

Le chercheur dans path fournit aussi des points d'entrées (ou hooks) et des


protocoles de manière à pouvoir étendre et personnaliser les types de chemins dans
lesquels chercher. Par exemple, si vous voulez pouvoir chercher dans des URL
réseau, vous pouvez écrire une fonction « point d'entrée » qui implémente la
sémantique HTTP pour chercher des modules sur la toile. Ce point d'entrée (qui doit
être un appelable) doit renvoyer un chercheur d'entrée dans path qui gère le
protocole décrit plus bas et qui sera utilisé pour obtenir un chargeur de module sur la
toile.

Avertissement : cette section et la précédente utilisent toutes les deux le


terme chercheur, dans un cas chercheur dans les méta-chemins et dans
l'autre chercheur d'entrée dans path. Ces deux types de chercheurs sont très
similaires, gèrent des protocoles similaires et fonctionnent de manière semblable
pendant le processus d'importation, mais il est important de garder à l'esprit qu'ils
sont subtilement différents. En particulier, les chercheurs dans les méta-chemins
opèrent au début du processus d'importation, comme clé de parcours
de sys.meta_path.

Au contraire, les "chercheurs d'entrée dans path" sont, dans un sens, un détail


d'implémentation du chercheur dans path et, en fait, si le chercheur dans path était
enlevé de sys.meta_path, aucune des sémantiques des "chercheurs d'entrée
dans path" ne serait invoquée.

5.5.1. Chercheurs d'entrée dans path


Le chercheur dans path (path based finder en anglais) est responsable de trouver et
charger les modules et les paquets Python dont l'emplacement est spécifié par une
chaîne dite d'entrée dans path. La plupart de ces entrées désignent des
emplacements sur le système de fichiers, mais il n'y a aucune raison de les limiter à
ça.

En tant que chercheur dans les méta-chemins, un chercheur dans path implémente


le protocole find_spec() décrit précédemment. Cependant, il autorise des points
d'entrée (hooks en anglais) supplémentaires qui peuvent être utilisés pour
personnaliser la façon dont les modules sont trouvés et chargés depuis le chemin
des importations.

Trois variables sont utilisées par le chercheur dans


path : sys.path, sys.path_hooks et sys.path_importer_cache.
L'attribut __path__ des objets paquets est aussi utilisé. Il permet de personnaliser
encore davantage le mécanisme d'importation.

sys.path contient une liste de chaînes de caractères indiquant des emplacements


où chercher des modules ou des paquets. Elle est initialisée à partir de la variable
d'environnement PYTHONPATH et de plusieurs autres valeurs par défaut qui
dépendent de l'installation et de l'implémentation. Les entrées
de sys.path désignent des répertoires du système de fichiers, des fichiers zip et
possiblement d'autres "endroits" (lisez le module site) tels que des URL ou des
requêtes dans des bases de données où Python doit rechercher des
modules. sys.path ne doit contenir que des chaînes de caractères ou d'octets ;
tous les autres types sont ignorés. L'encodage des entrées de chaînes d'octets est
déterminé par chaque chercheur d'entrée dans path.

Le chercheur dans path est un chercheur dans les méta-chemins, donc le


mécanisme d'importation commence la recherche dans le chemin des
importations par un appel à la méthode find_spec() du chercheur dans path,
comme décrit précédemment. Quand l'argument path de find_spec() est donné,
c'est une liste de chemins à parcourir, typiquement un attribut __path__ pour une
importation à l'intérieur d'un paquet. Si l'argument path est None, cela indique une
importation de niveau le plus haut et sys.path est utilisée.

Le chercheur dans path itère sur chaque entrée dans le path et, pour chacune,


regarde s'il trouve un chercheur d'entrée dans path (PathEntryFinder) approprié à
cette entrée. Comme cette opération est coûteuse (elle peut faire appel à
plusieurs stat() pour cela), le chercheur dans path maintient un cache de
correspondance entre les entrées et les "chercheurs d'entrée dans path". Ce cache
est géré par sys.path_importer_cache (en dépit de son nom, ce cache stocke les
objets chercheurs plutôt que les simples objets importateurs). Ainsi, la recherche
coûteuse pour une entrée de path spécifique n'a besoin d'être effectuée qu'une seule
fois par le chercheur d'entrée dans path. Le code de l'utilisateur peut très bien
supprimer les entrées du cache sys.path_importer_cache, forçant ainsi le
chercheur dans path à effectuer une nouvelle fois la recherche sur chaque entrée 3.

Si une entrée n'est pas présente dans le cache, le chercheur dans path itère sur
chaque callable de sys.path_hooks. Chaque point d'entrée sur une entrée de
path de cette liste est appelé avec un unique argument, l'entrée dans laquelle
chercher. L'appelable peut soit renvoyer un chercheur d'entrée dans path apte à
prendre en charge l'entrée ou lever une ImportError. Une ImportError est
utilisée par le chercheur dans path pour signaler que le point d'entrée n'a pas trouvé
de chercheur d'entrée dans path pour cette entrée. L'exception est ignorée et
l'itération sur le chemin des importations se poursuit. Le point d'entrée doit attendre
qu'on lui passe soit une chaîne de caractères soit une chaîne d'octets ; l'encodage
des chaînes d'octets est à la main du point d'entrée (par exemple, ce peut être
l'encodage du système de fichiers, de l'UTF-8 ou autre chose) et, si le point d'entrée
n'arrive pas à décoder l'argument, il doit lever une ImportError.

Si l'itération sur sys.path_hooks se termine sans qu'aucun chercheur d'entrée


dans path ne soit renvoyé, alors la méthode find_spec() du chercheur
dans path stocke None dans le sys.path_importer_cache (pour indiquer qu'il n'y
a pas de chercheur pour cette entrée) et renvoie None, indiquant que ce chercheur
dans les méta-chemins n'a pas trouvé le module.

Si un chercheur d'entrée dans path est renvoyé par un des points


d'entrée de sys.path_hooks, alors le protocole suivant est utilisé pour demander
un spécificateur de module au chercheur, spécificateur qui sera utilisé pour charger
le module.

Le répertoire de travail courant — noté sous la forme d'une chaîne de caractères


vide — est géré d'une manière légèrement différente des autres entrées
de sys.path. D'abord, si le répertoire de travail courant s'avère ne pas exister,
aucune valeur n'est stockée dans sys.path_importer_cache. Ensuite, la valeur
pour le répertoire de travail courant est vérifiée à chaque recherche de module.
Enfin, le chemin utilisé pour sys.path_importer_cache et renvoyée
par importlib.machinery.PathFinder.find_spec() est le nom réel du
répertoire de travail courant et non pas la chaîne vide.

5.5.2. Protocole des chercheurs d'entrée dans path


Afin de gérer les importations de modules, l'initialisation des paquets et d'être
capables de contribuer aux portions des paquets-espaces de nommage, les
chercheurs d'entrée dans path doivent implémenter la méthode find_spec().
find_spec() takes two arguments: the fully qualified name of the module being
imported, and the (optional) target module. find_spec() returns a fully populated
spec for the module. This spec will always have "loader" set (with one exception).

To indicate to the import machinery that the spec represents a namespace portion,


the path entry finder sets "loader" on the spec to None and
"submodule_search_locations" to a list containing the portion.

Modifié dans la version 3.4: La


méthode find_spec() remplace find_loader() et find_module(), ces deux
méthodes étant dorénavant obsolètes mais restant utilisées si find_spec() n'est
pas définie.

Les vieux chercheurs d'entrée dans path peuvent implémenter une des deux


méthodes obsolètes à la place de find_spec(). Ces méthodes sont toujours prises
en compte dans le cadre de la compatibilité descendante. Cependant,
si find_spec() est implémentée par le chercheur d'entrée dans path, les méthodes
historiques sont ignorées.

La méthode find_loader() prend un argument, le nom complètement qualifié du


module en cours d'importation. find_loader() renvoie un couple dont le premier
élément est le chargeur et le second est une portion d'espace de nommage. Quand
le premier élément (c'est-à-dire le chargeur) est None, cela signifie que, bien que le
chercheur d'entrée dans path n'a pas de chargeur pour le module considéré, il sait
que cette entrée contribue à une portion d'espace de nommage pour le module
considéré. C'est presque toujours le cas quand vous demandez à Python d'importer
un paquet-espace de nommage qui n'est pas présent physiquement sur le système
de fichiers. Quand un chercheur d'entrée dans path renvoie None pour le chargeur,
la valeur du second élément du couple renvoyé doit être une séquence,
éventuellement vide.

Si find_loader() renvoie une valeur de chargeur qui n'est pas None, la portion est


ignorée et le chargeur est renvoyé par le chercheur dans path, mettant un terme à la
recherche dans les chemins.

À fin de compatibilité descendante avec d'autres implémentations du protocole


d'importation, beaucoup de chercheurs d'entrée dans path gèrent aussi la méthode
traditionnelle find_module() que l'on trouve dans les chercheurs dans les méta-
chemins. Cependant, les méthodes find_module() des chercheurs d'entrée
dans path ne sont jamais appelées avec un argument path (il est convenu qu'elles
enregistrent les informations relatives au chemin approprié au moment de leur appel
initial au point d'entrée).
La méthode find_module() des chercheurs d'entrée dans path est obsolète car
elle n'autorise pas le chercheur d'entrée dans path à contribuer aux portions
d'espaces de nommage des paquets-espaces de nommage. Si à la
fois find_loader() et find_module() sont définies pour un chercheur d'entrée
dans path, le système d'importation utilise toujours find_loader() plutôt
que find_module().

5.6. Remplacement du système d'importation


standard
La manière la plus fiable de remplacer tout le système d'importation est de supprimer
le contenu par défaut de sys.meta_path et de le remplacer complètement par un
chercheur dans les méta-chemins sur mesure.

S'il convient juste de modifier le comportement de l'instruction import sans affecter


les autres API qui utilisent le système d'importation, alors remplacer la fonction
native __import__() peut être suffisant. Cette technique peut aussi être employée
au niveau d'un module pour n'altérer le comportement des importations qu'à
l'intérieur de ce module.

To selectively prevent the import of some modules from a hook early on the meta
path (rather than disabling the standard import system entirely), it is sufficient to
raise ModuleNotFoundError directly from find_spec() instead of returning None.
The latter indicates that the meta path search should continue, while raising an
exception terminates it immediately.

5.7. Importations relatives au paquet


Les importations relatives commencent par une suite de points. Un seul point avant
indique une importation relative, démarrant avec le paquet actuel. Deux points ou
plus avant indiquent une importation relative au parent du paquet actuel, un niveau
par point avant le premier. Par exemple, en ayant le contenu suivant :

package/
__init__.py
subpackage1/
__init__.py
moduleX.py
moduleY.py
subpackage2/
__init__.py
moduleZ.py
moduleA.py

Dans subpackage1/moduleX.py ou subpackage1/__init__.py, les importations


suivantes sont des importations relatives valides :

from .moduleY import spam


from .moduleY import spam as ham
from . import moduleY
from ..subpackage1 import moduleY
from ..subpackage2.moduleZ import eggs
from ..moduleA import foo

Les importations absolues peuvent utiliser soit la syntaxe import <>,


soit from <> import <>, mais les importations relatives doivent seulement utiliser
la deuxième forme, la raison étant :

import XXX.YYY.ZZZ

devrait exposer XXX.YYY.ZZZ comme une expression utilisable,


mais .moduleY n’est pas une expression valide.

5.8. Cas particulier de __main__


Le module __main__ est un cas particulier pour le système d'importation de Python.
Comme indiqué par ailleurs, le module __main__ est initialisé directement au
démarrage de l'interpréteur, un peu comme sys et builtins. Cependant, au
contraire des deux cités précédemment, ce n'est pas vraiment un module natif.
Effectivement, la manière dont est initialisé __main__ dépend des drapeaux et
options avec lesquels l'interpréteur est lancé.

5.8.1. __main__.__spec__
En fonction de la manière dont __main__ est initialisé, __main__.__spec__ est
défini de manière conforme ou mis à None.

Quand Python est démarré avec l'option -m, __spec__ est défini à la valeur du


spécificateur du module ou paquet correspondant. Python peuple
aussi __spec__ quand le module __main__ est chargé en tant que partie de
l'exécution d'un répertoire, d'un fichier zip ou d'une entrée de sys.path.
Dans les autres cas, __main__.__spec__ est mis à None, car le code qui
peuple __main__ ne trouve pas de correspondance directe avec un module que l'on
importe :

 invite de commande interactive


 l'option -c
 lecture depuis l'entrée standard
 lecture depuis un fichier de code source ou de bytecode

Notez que __main__.__spec__ vaut toujours None dans le dernier cas, même si le


fichier pourrait techniquement être importé directement en tant que module. Utilisez
l'option -m si vous souhaitez disposer de métadonnées valides du module
dans __main__.

Notez aussi que même quand __main__ correspond à un module importable et


que __main__.__spec__ est défini en conséquence, ils seront toujours considérés
comme des modules distincts. Cela est dû au fait que le bloc encadré
par if __name__ == "__main__": ne s'exécute que quand le module est utilisé
pour peupler l'espace de nommage de __main__, et pas durant une importation
normale.

5.9. Idées d'amélioration
XXX Ce serait vraiment bien de disposer d'un diagramme.

XXX * (import_machinery.rst) Pourquoi pas une section dédiée aux attributs des
modules et paquets, développant ou remplaçant les entrées associées dans la page
de référence du modèle de données ?

XXX runpy, pkgutil et autres dans le manuel de la bibliothèque devraient comporter


un lien "Lisez aussi" en début de page pointant vers la section du nouveau
mécanisme d'import.

XXX Ajouter des explications sur les différentes manières dont __main__ est


initialisé ?

XXX Ajouter des informations sur les pièges et bizarreries de __main__ (c-à-d des
extraits de la PEP 395).
5.10. Références
Le mécanisme d'importation a considérablement évolué depuis les débuts de
Python. La spécification des paquets originale est toujours disponible, bien que
quelques détails ont changé depuis l'écriture de ce document.

La spécification originale de sys.meta_path se trouve dans la PEP 302. La PEP


420 contient des extensions significatives.

La PEP 420 a introduit les paquets-espaces de nommage pour Python 3.3. La PEP


420 a aussi introduit le protocole recherche du chargeur comme une alternative
à find_module().

La PEP 366 décrit l'ajout de l'attribut __package__ pour les importations relatives


explicites dans les modules principaux.

La PEP 328 a introduit les importations absolues et les importations relatives


explicites. Elle a aussi proposé __name__ pour la sémantique que la PEP
366 attribuait à __package__.

PEP 338 définit l'exécution de modules en tant que scripts.

PEP 451 ajoute l'encapsulation dans les objets spécificateurs de l'état des


importations, module par module. Elle reporte aussi la majorité des responsabilités
des chargeurs vers le mécanisme d'import. Ces changements permettent de
supprimer plusieurs API dans le système d'importation et d'ajouter de nouvelles
méthodes aux chercheurs et chargeurs.

Notes

Voir types.ModuleType.

L'implémentation de importlib évite d'utiliser directement la valeur de retour. À la


place, elle récupère l'objet module en recherchant le nom du module
dans sys.modules. L'effet indirect est que le module importé peut remplacer le
module de même nom dans sys.modules. C'est un comportement spécifique à
l'implémentation dont le résultat n'est pas garanti pour les autres implémentations de
Python.

3
Dans du code historique, il est possible de trouver des instances
de imp.NullImporter dans sys.path_importer_cache. Il est recommandé de
modifier ce code afin d'utiliser None à la place. Lisez Portage de code Python pour
plus de détails.

6. Expressions
Ce chapitre explique la signification des éléments des expressions en Python.

Notes sur la syntaxe : dans ce chapitre et le suivant, nous utilisons la notation BNF


étendue pour décrire la syntaxe, pas l'analyse lexicale. Quand une règle de syntaxe
est de la forme

name ::= othername

et qu'aucune sémantique n'est donnée, la sémantique de name est la même que


celle de othername.

6.1. Conversions arithmétiques
When a description of an arithmetic operator below uses the phrase "the numeric
arguments are converted to a common type", this means that the operator
implementation for built-in types works as follows:

 Si l'un des deux arguments est du type nombre complexe, l'autre est converti
en nombre complexe ;
 sinon, si l'un des arguments est un nombre à virgule flottante, l'autre est
converti en nombre à virgule flottante ;
 sinon, les deux doivent être des entiers et aucune conversion n'est
nécessaire.

Des règles supplémentaires s'appliquent pour certains opérateurs (par exemple, une
chaîne comme opérande de gauche pour l'opérateur %). Les extensions doivent
définir leurs propres règles de conversion.

6.2. Atomes
Les atomes sont les éléments de base des expressions. Les atomes les plus simples
sont les identifiants et les littéraux. Les expressions entre parenthèses, crochets ou
accolades sont aussi classées syntaxiquement comme des atomes. La syntaxe pour
les atomes est :

atom ::= identifier | literal | enclosure


enclosure ::= parenth_form | list_display | dict_display |
set_display
| generator_expression | yield_atom

6.2.1. Identifiants (noms)
Un identifiant qui apparaît en tant qu'atome est un nom. Lisez la section Identifiants
et mots-clés pour la définition lexicale et la section Noms et liaisons pour la
documentation sur les noms et les liaisons afférentes.

Quand un nom est lié à un objet, l'évaluation de l'atome produit cet objet. Quand le
nom n'est pas lié, toute tentative de l'évaluer lève une exception NameError.

Transformation des noms privés : lorsqu'un identificateur qui apparaît


textuellement dans la définition d'une classe commence par deux (ou plus)
caractères de soulignement et ne se termine pas par deux (ou plus) caractères de
soulignement, il est considéré comme un nom privé <private name> de cette classe.
Les noms privés sont transformés en une forme plus longue avant que le code ne
soit généré pour eux. La transformation insère le nom de la classe, avec les
soulignés enlevés et un seul souligné inséré devant le nom. Par exemple,
l'identificateur __spam apparaissant dans une classe nommée Ham est transformé
en _Ham__spam. Cette transformation est indépendante du contexte syntaxique dans
lequel l'identificateur est utilisé. Si le nom transformé est extrêmement long (plus de
255 caractères), l'implémentation peut le tronquer. Si le nom de la classe est
constitué uniquement de traits de soulignement, aucune transformation n'est
effectuée.

6.2.2. Littéraux
Python gère les littéraux de chaînes de caractères, de chaînes d'octets et de
plusieurs autres types numériques :

literal ::= stringliteral | bytesliteral


| integer | floatnumber | imagnumber

L'évaluation d'un littéral produit un objet du type donné (chaîne de caractères, chaîne
d'octets, entier, nombre à virgule flottante, nombre complexe) avec la valeur donnée.
La valeur peut être approximée dans le cas des nombres à virgule flottante et des
nombres imaginaires (complexes). Reportez-vous à la section Littéraux pour les
détails.

Tous les littéraux sont de types immuables et donc l'identifiant de l'objet est moins
important que sa valeur. Des évaluations multiples de littéraux avec la même valeur
(soit la même occurrence dans le texte du programme, soit une autre occurrence)
résultent dans le même objet ou un objet différent avec la même valeur.

6.2.3. Formes parenthésées
Une forme parenthésée est une liste d'expressions (cette liste est en fait optionnelle)
placée à l'intérieur de parenthèses :

parenth_form ::= "(" [starred_expression] ")"

Une liste d'expressions entre parenthèses produit ce que la liste de ces expressions
produirait : si la liste contient au moins une virgule, elle produit un n-uplet
(type tuple) ; sinon, elle produit l'expression elle-même (qui constitue donc elle-même
la liste d'expressions).

Une paire de parenthèses vide produit un objet n-uplet vide. Comme les n-uplets
sont immuables, la même règle que pour les littéraux s'applique (c'est-à-dire que
deux occurrences du n-uplet vide peuvent, ou pas, produire le même objet).

Notez que les tuples ne sont pas créés par les parenthèses mais par l'utilisation de la
virgule. L'exception est le tuple vide, pour lequel les parenthèses sont
requises (autoriser que « rien » ne soit pas parenthésé dans les expressions aurait
généré des ambigüités et aurait permis à certaines coquilles de passer inaperçu).

6.2.4. Agencements des listes, ensembles et


dictionnaires
Pour construire une liste, un ensemble ou un dictionnaire, Python fournit des
syntaxes spéciales dites « agencements » (displays en anglais), chaque agencement
comportant deux variantes :

 soit le contenu du conteneur est listé explicitement,


 soit il est calculé à l'aide de la combinaison d'une boucle et d'instructions de
filtrage, appelée une compréhension (dans le sens de ce qui sert à définir un
concept, par opposition à extension).

Les compréhensions sont constituées des éléments de syntaxe communs suivants :


comprehension ::= expression comp_for
comp_for ::= ["async"] "for" target_list "in" or_test
[comp_iter]
comp_iter ::= comp_for | comp_if
comp_if ::= "if" expression_nocond [comp_iter]

Une compréhension est constituée par une seule expression suivie par au moins une
clause for et zéro ou plus clauses for ou if. Dans ce cas, les éléments du
nouveau conteneur sont ceux qui auraient été produits si l'on avait considéré toutes
les clauses for ou if comme des blocs, imbriqués de la gauche vers la droite, et
évalué l'expression pour produire un élément à chaque fois que le bloc le plus
imbriqué était atteint.

Cependant, à part l'expression de l'itérable dans la clause for la plus à gauche, la


compréhension est exécutée dans une portée séparée, implicitement imbriquée.
Ceci assure que les noms assignés dans la liste cible ne « fuient » pas en dehors de
cette portée.

L'expression de l'itérable dans la clause for la plus à gauche est évaluée


directement dans la portée englobante puis passée en tant qu'argument à la portée
implicite imbriquée. Les clauses for suivantes et les filtres conditionnels de la
clause for la plus à gauche ne peuvent pas être évalués dans la portée englobante
car ils peuvent dépendre de valeurs obtenues à partir de l'itérable le plus à gauche.
Par exemple : [x*y for x in range(10) for y in range(x, x+10)].

Pour assurer que le résultat de la compréhension soit un conteneur du type


approprié, les expressions yield et yield from sont interdites dans la portée
implicite imbriquée (dans Python 3.7, de telles expressions lèvent
un DeprecationWarning à la compilation, dans Python 3.8 et suivants, elles
lèveront une SyntaxError).

Depuis Python 3.6, dans une fonction async def, une clause async for peut être


utilisée pour itérer sur un itérateur asynchrone. Une compréhension dans une
fonction async def consiste alors à avoir une clause for or async for suivie par
des clauses for ou async for additionnelles facultatives et, possiblement, des
expressions await. Si la compréhension contient soit des clauses async for, soit
des expressions await, elle est appelée compréhension asynchrone. Une
compréhension asynchrone peut suspendre l'exécution de la fonction coroutine dans
laquelle elle apparaît. Voir aussi la PEP 530.

Nouveau dans la version 3.6: Les compréhensions asynchrones ont été introduites.


Obsolète depuis la version 3.7:  yield et yield from sont obsolètes dans la portée
implicite imbriquée.

6.2.5. Agencements de listes
Un agencement de liste est une suite (possiblement vide) d'expressions à l'intérieur
de crochets :

list_display ::= "[" [starred_list | comprehension] "]"

Un agencement de liste produit un nouvel objet liste, dont le contenu est spécifié soit
par une liste d'expression soit par une compréhension. Quand une liste
d'expressions (dont les éléments sont séparés par des virgules) est fournie, ces
éléments sont évalués de la gauche vers la droite et placés dans l'objet liste, dans
cet ordre. Quand c'est une compréhension qui est fournie, la liste est construite à
partir des éléments produits par la compréhension.

6.2.6. Agencements d'ensembles
Un agencement d'ensemble (type set) est délimité par des accolades et se distingue
de l'agencement d'un dictionnaire par le fait qu'il n'y a pas de « deux points » : pour
séparer les clés et les valeurs :

set_display ::= "{" (starred_list | comprehension) "}"

Un agencement d'ensemble produit un nouvel objet ensemble muable, le contenu


étant spécifié soit par une séquence d'expression, soit par une compréhension.
Quand une liste (dont les éléments sont séparés par des virgules) est fournie, ses
éléments sont évalués de la gauche vers la droite et ajoutés à l'objet ensemble.
Quand une compréhension est fournie, l'ensemble est construit à partir des éléments
produits par la compréhension.

Un ensemble vide ne peut pas être construit par {} ; cette écriture construit un
dictionnaire vide.

6.2.7. Agencements de dictionnaires
Un agencement de dictionnaire est une série (possiblement vide) de couples clés-
valeurs entourée par des accolades :
dict_display ::= "{" [key_datum_list | dict_comprehension]
"}"
key_datum_list ::= key_datum ("," key_datum)* [","]
key_datum ::= expression ":" expression | "**" or_expr
dict_comprehension ::= expression ":" expression comp_for

Un agencement de dictionnaire produit un nouvel objet dictionnaire.

Si une séquence (dont les éléments sont séparés par des virgules) de couples clés-
valeurs est fournie, les couples sont évalués de la gauche vers la droite pour définir
les entrées du dictionnaire : chaque objet clé est utilisé comme clé dans le
dictionnaire pour stocker la donnée correspondante. Cela signifie que vous pouvez
spécifier la même clé plusieurs fois dans la liste des couples clés-valeurs et, dans ce
cas, la valeur finalement stockée dans le dictionnaire est la dernière donnée.

Une double astérisque ** demande de dépaqueter le dictionnaire. L'opérande doit


être un tableau de correspondances. Chaque élément du tableau de
correspondances est ajouté au nouveau dictionnaire. Les valeurs les plus récentes
remplacent les valeurs déjà définies par des couples clés-valeurs antérieurs ou par
d'autres dépaquetages de dictionnaires antérieurs.

Nouveau dans la version 3.5: le dépaquetage peut se faire vers un agencement de


dictionnaire, proposé à l'origine par la PEP 448.

Une compréhension de dictionnaire, au contraire des compréhensions de listes ou


d'ensembles, requiert deux expressions séparées par une virgule et suivies par les
clauses usuelles "for" et "if". Quand la compréhension est exécutée, les éléments
clés-valeurs sont insérés dans le nouveau dictionnaire dans l'ordre dans lequel ils
sont produits.

Les restrictions relatives aux types des clés sont données dans la section Hiérarchie
des types standards (pour résumer, le type de la clé doit être hachable, ce qui exclut
tous les objets muables). Les collisions entre les clés dupliquées ne sont pas
détectées ; la dernière valeur (celle qui apparaît le plus à droite dans l'agencement)
stockée prévaut pour une clé donnée.

6.2.8. Expressions génératrices
Une expression génératrice est une notation concise pour un générateur, entourée
de parenthèses :

generator_expression ::= "(" expression comp_for ")"


Une expression génératrice produit un nouvel objet générateur. Sa syntaxe est la
même que celle des compréhensions, sauf qu'elle est entourée de parenthèses au
lieu de crochets ou d'accolades.

Les variables utilisées dans une expression génératrice sont évaluées


paresseusement, au moment où la méthode __next__() de l'objet générateur est
appelée (de la même manière que pour les générateurs classiques). Cependant,
l'expression de l'itérable dans la clause for la plus à gauche est immédiatement
évaluée, de manière à ce qu'une erreur dans cette partie soit signalée à l'endroit où
l'expression génératrice est définie plutôt qu'à l'endroit où la première valeur est
récupérée. Les clauses for suivantes ne peuvent pas être évaluées dans la portée
implicite imbriquée car elles peuvent dépendre de valeurs obtenues à partir de
boucles for plus à gauche. Par
exemple, (x*y for x in range(10) for y in range(x, x+10)).

Les parenthèses peuvent être omises pour les appels qui ne possèdent qu'un seul
argument. Voir la section Appels pour les détails.

Pour éviter d'interférer avec l'opération attendue de l'expression générateur elle-


même, les expressions yield et yield from sont interdites dans les générateurs
définis de manière implicite (dans Python 3.7, ces expressions signalent
un DeprecationWarning à la compilation. En Python 3.8+ elles lèvent
une SyntaxError).

Si une expression génératrice contient une ou des


expressions async for ou await, elle est appelée expression génératrice
asynchrone <asynchronous generator expression>. Une expression génératrice
asynchrone produit un nouvel objet générateur asynchrone qui est un itérateur
asynchrone (voir Itérateurs asynchrones).

Nouveau dans la version 3.6: les expressions génératrices asynchrones ont été


introduites.

Modifié dans la version 3.7: Avant Python 3.7, les expressions génératrices


asynchrones ne pouvaient apparaître que dans les coroutines async def. À partir
de la version 3.7, toute fonction peut utiliser des expressions génératrices
asynchrones.

Obsolète depuis la version 3.7:  yield et yield from sont obsolètes dans la portée


implicite imbriquée.
6.2.9. Expressions yield
yield_atom ::= "(" yield_expression ")"
yield_expression ::= "yield" [expression_list | "from"
expression]

Une expression yield est utilisée pour définir une fonction générateur ou une


fonction génératrice asynchrone et ne peut donc être utilisée que dans le corps de la
définition d'une fonction. L'utilisation d'une expression yield dans le corps d'une
fonction entraîne que cette fonction devient un générateur et son utilisation dans le
corps d'une fonction async def entraine que cette fonction coroutine devient un
générateur asynchrone. Par exemple :

def gen(): # defines a generator function


yield 123

async def agen(): # defines an asynchronous generator function


yield 123

En raison des effets de bords sur la portée contenant, les expressions yield ne sont
pas autorisées dans la portée implicite utilisée dans l'implémentation des
compréhensions et des expressions générateurs (dans Python 3.7, de telles
expressions lèvent un DeprecationWarning à la compilation ; à partir de Python
3.8, elles lèveront une SyntaxError).

Obsolète depuis la version 3.7: Les expressions yield sont obsolètes dans la portée


implicite imbriquée utilisée dans l'implémentation des compréhensions et des
expressions générateurs.

Les fonctions génératrices sont décrites plus loin alors que les fonctions générateurs
asynchrones sont décrites séparément dans la section Fonctions génératrices
asynchrones.

Lorsqu'une fonction génératrice est appelée, elle renvoie un itérateur que l'on appelle
générateur. Ce générateur contrôle l'exécution de la fonction génératrice. L'exécution
commence lorsque l'une des méthodes du générateur est appelée. À ce moment,
l'exécution se déroule jusqu'à la première expression yield, où elle se suspend,
renvoyant la valeur de expression_list à l'appelant du générateur. Cette
suspension conserve tous les états locaux, y compris les liaisons en cours des
variables locales, le pointeur d'instruction, la pile d'évaluation interne et l'état de tous
les gestionnaires d'exceptions. Lorsque l'exécution reprend en appelant l'une des
méthodes du générateur, la fonction s'exécute exactement comme si
l'expression yield n'avait été qu'un simple appel externe. La valeur de
l'expression yield après reprise dépend de la méthode qui a permis la reprise de
l'exécution. Si c'est __next__() qui a été utilisée (typiquement via un for ou la
fonction native next()) alors le résultat est None. Sinon, si c'est send() qui a été
utilisée, alors le résultat est la valeur transmise à cette méthode.

Tout ceci rend les fonctions génératrices très similaires aux coroutines : elles
produisent plusieurs objets via des expressions yield, elles possèdent plus qu'un
seul point d'entrée et leur exécution peut être suspendue. La seule différence est
qu'une fonction génératrice ne peut pas contrôler où l'exécution doit se poursuivre
après une instruction yield ; ce contrôle est toujours du ressort de l'appelant au
générateur.

Les expressions yield sont autorisées partout dans un bloc try. Si l'exécution du


générateur ne reprend pas avant qu'il ne soit finalisé (parce que son compteur de
référence est tombé à zéro ou parce qu'il est nettoyé par le ramasse-miettes), la
méthode close() du générateur-itérateur est appelée, ce qui permet l'exécution de
toutes les clauses finally en attente.

L'utilisation de yield from <expr> traite l'expression passée en paramètre comme


un sous-itérateur. Toutes les valeurs produites par ce sous-itérateur sont directement
passées à l'appelant des méthodes du générateur courant. Toute valeur passée
par send() ou toute exception passée par throw() est transmise à l'itérateur sous-
jacent s'il possède les méthodes appropriées. Si ce n'est pas le cas,
alors send() lève une AttributeError ou une TypeError, alors que throw() ne
fait que propager l'exception immédiatement.

Quand l'itérateur sous-jacent a terminé, l'attribut value de


l'instance StopIteration qui a été levée devient la valeur produite par
l'expression yield. Elle peut être définie explicitement quand vous
levez StopIteration ou automatiquement que le sous-itérateur est un générateur
(en renvoyant une valeur par le sous-générateur).

Modifié dans la version 3.3:  yield from <expr> a été ajoutée pour déléguer le


contrôle du flot d'exécution à un sous-itérateur.

Les parenthèses peuvent être omises quand l'expression yield est la seule


expression à droite de l'instruction de l'instruction d'assignation.

Voir aussi
PEP 255 : Générateurs simples

La proposition d'ajouter à Python des générateurs et l'instruction yield.


PEP 342 -- Coroutines via des générateurs améliorés
Proposition d'améliorer l'API et la syntaxe des générateurs, de manière à pouvoir les
utiliser comme de simples coroutines.
PEP 380 -- Syntaxe pour déléguer à un sous-générateur

Proposition d'introduire la syntaxe yield_from, de manière à déléguer facilement


l'exécution à un sous-générateur.
PEP 525 : Générateurs asynchrones

La proposition qui a amélioré la PEP 492 en ajoutant des capacités de générateur


pour les coroutines.
6.2.9.1. Méthodes des générateurs-itérateurs

Cette sous-section décrit les méthodes des générateurs-itérateurs. Elles peuvent


être utilisées pour contrôler l'exécution des fonctions générateurs.

Notez que l'appel à une méthode ci-dessous d'un générateur alors que le générateur
est déjà en cours d'exécution lève une exception ValueError.

generator.__next__()

Démarre l'exécution d'une fonction générateur ou la reprend à la dernière


expression yield exécutée. Quand une fonction générateur est reprise par une
méthode __next__(), l'expression yield en cours s'évalue toujours à None.
L'exécution continue ensuite jusqu'à l'expression yield suivante, où le générateur
est à nouveau suspendu et la valeur de expression_list est renvoyée à la
méthode __next__() de l'appelant. Si le générateur termine sans donner une autre
valeur, une exception StopIteration est levée.

Cette méthode est normalement appelée implicitement, par exemple par une
boucle for ou par la fonction native next().

generator.send(value)

Reprend l'exécution et « envoie » une valeur à la fonction générateur.


L'argument value devient le résultat de l'expression yield courante. La
méthode send() renvoie la valeur suivante produite par le générateur ou
lève StopIteration si le générateur termine sans produire de nouvelle valeur.
Quand send() est utilisée pour démarrer le générateur, elle doit avoir None comme
argument, car il n'y a aucune expression yield qui peut recevoir la valeur.

generator.throw(type[, value[, traceback]])

Lève une exception de type type à l'endroit où le générateur est en pause et renvoie


la valeur suivante produite par la fonction générateur. Si le générateur termine sans
produire de nouvelle valeur, une exception StopIteration est levée. Si la fonction
génératrice ne gère pas l'exception passée ou lève une autre exception, alors cette
exception est propagée vers l'appelant.

generator.close()

Lève une GeneratorExit à l'endroit où la fonction génératrice a été mise en pause.


Si la fonction génératrice termine, est déjà fermée ou lève GeneratorExit (parce
qu'elle ne gère pas l'exception), close revient vers l'appelant. Si le générateur produit
une valeur, une RuntimeError est levée. Si le générateur lève une autre exception,
elle est propagée à l'appelant. La méthode close() ne fait rien si le générateur a
déjà terminé en raison d'une exception ou d'une fin normale.

6.2.9.2. Exemples

Voici un exemple simple qui montre le comportement des générateurs et des


fonctions génératrices :

>>>

>>> def echo(value=None):


... print("Execution starts when 'next()' is called for the
first time.")
... try:
... while True:
... try:
... value = (yield value)
... except Exception as e:
... value = e
... finally:
... print("Don't forget to clean up when 'close()' is
called.")
...
>>> generator = echo(1)
>>> print(next(generator))
Execution starts when 'next()' is called for the first time.
1
>>> print(next(generator))
None
>>> print(generator.send(2))
2
>>> generator.throw(TypeError, "spam")
TypeError('spam',)
>>> generator.close()
Don't forget to clean up when 'close()' is called.
Pour des exemples d'utilisation de yield from, lisez la PEP 380: Syntax for
Delegating to a Subgenerator dans « Les nouveautés de Python ».

6.2.9.3. Fonctions génératrices asynchrones

La présence d'une expression yield dans une fonction ou une méthode définie en


utilisant async def transforme cette fonction en fonction générateur asynchrone.

Quand une fonction génératrice asynchrone est appelée, elle renvoie un itérateur
asynchrone, autrement appelé objet générateur asynchrone. Cet objet contrôle
l'exécution de la fonction génératrice. Un objet générateur asynchrone est
typiquement utilisé dans une instruction async for à l'intérieur d'une fonction
coroutine de la même manière qu'un objet générateur serait utilisé dans une
instruction for.

L'appel d'une méthode du générateur asynchrone renvoie un objet awaitable et


l'exécution commence au moment où l'on atteint une instruction await le
concernant. À ce moment, l'exécution se déroule jusqu'à la première
expression yield, où elle est suspendue et renvoie la valeur
de expression_list à la coroutine en attente. Comme pour un générateur, la
suspension signifie que tous les états locaux sont conservés, y compris les liaisons
des variables locales, le pointeur d'instruction, la pile d'évaluation interne et l'état de
tous les gestionnaires d'exceptions. Lorsque l'exécution reprend parce que l'appelant
a atteint une instruction await sur l'objet suivant retourné par les méthodes du
générateur asynchrone, la fonction s'exécute exactement comme si
l'expression yield n'avait été qu'un simple appel externe. La valeur de
l'expression yield au moment de la reprise dépend de la méthode qui a relancé
l'exécution. Si c'est __anext__() qui a été utilisée, alors le résultat est None. Sinon,
si c'est asend() qui a été utilisée, alors le résultat est la valeur transmise à cette
méthode.

Dans une fonction génératrice asynchrone, les expressions yield sont autorisées


n'importe où dans une construction try. Cependant, si l'exécution d'un générateur
asynchrone n'a pas repris avant que le générateur ne soit finalisé (parce que son
compteur de référence a atteint zéro ou parce qu'il est nettoyé par le ramasse-
miettes), alors une expression yield dans une construction try pourrait ne pas
atteindre la clause finally en attente. Dans ce cas, c'est la responsabilité de la
boucle d'événements ou du programmateur exécutant le générateur asynchrone
d'appeler la méthode aclose() du générateur asynchrone et d'exécuter l'objet
coroutine résultant, permettant ainsi à toute clause finally en attente d'être
exécutée.
Pour effectuer correctement la finalisation, une boucle d'événements doit définir une
fonction finalizer qui prend un générateur-itérateur asynchrone, appelle sans
doute aclose() et exécute la coroutine. Ce finalizer peut s'enregistrer en
appelant sys.set_asyncgen_hooks(). Lors de la première itération, un
générateur-itérateur asynchrone stocke le finalizer enregistré à appeler lors de la
finalisation. Pour un exemple de référence relatif à une méthode de finalizer,
regardez l'implémentation
de asyncio.Loop.shutdown_asyncgens dans Lib/asyncio/base_events.py.

L'expression yield from <expr> produit une erreur de syntaxe quand elle est


utilisée dans une fonction génératrice asynchrone.

6.2.9.4. Méthodes des générateurs-itérateurs asynchrones

Cette sous-section décrit les méthodes des générateurs-itérateurs asynchrones.


Elles sont utilisées pour contrôler l’exécution des fonctions génératrices.

coroutine  agen.__anext__()

Renvoie un awaitable qui, quand il a la main, démarre l'exécution du générateur


asynchrone ou reprend son exécution à l'endroit de la dernière
expression yield exécutée. Quand une fonction générateur asynchrone est reprise
par une méthode __anext__(), l’expression yield en cours s’évalue toujours
à None dans le awaitable renvoyé, et elle continue son exécution jusqu’à
l’expression yield suivante. La valeur de expression_list de
l'expression yield est la valeur de l'exception StopIteration levée par la
coroutine qui termine. Si le générateur asynchrone termine sans produire d'autre
valeur, le awaitable lève une exception StopAsyncIteration qui signale que
l'itération asynchrone est terminée.

Cette méthode est normalement appelée implicitement par une boucle async for.

coroutine  agen.asend(value)

Renvoie un awaitable qui, lorsqu'il a la main, reprend l'exécution du générateur


asynchrone. Comme pour la méthode send() d'un générateur, elle « envoie » une
valeur value à la fonction générateur asynchrone et cet argument devient le résultat
de l'expression yield courante. Le awaitable renvoyé par la
méthode asend() renvoie la valeur suivante produite par le générateur comme
valeur de l'exception StopIteration levée ou lève StopAsyncIteration si le
générateur asynchrone termine sans produire de nouvelle valeur.
Quand asend() est appelée pour démarrer le générateur asynchrone, l'argument
doit être None car il n'y a pas d'expression yield pour recevoir la valeur.
coroutine  agen.athrow(type[, value[, traceback]])

Renvoie un awaitable qui lève une exception du type type à l'endroit où le


générateur asynchrone a été mis en pause et renvoie la valeur suivante produite par
la fonction génératrice comme valeur de l'exception StopIteration qui a été levée.
Si le générateur asynchrone termine sans produire de nouvelle valeur, une
exception StopAsyncIteration est levée par le awaitable. Si la fonction
génératrice ne traite pas l'exception reçue ou lève une autre exception alors, quand
le awaitable est lancé, cette exception est propagée vers l'appelant du awaitable.

coroutine  agen.aclose()

Renvoie un awaitable qui, quand il s'exécute, lève une


exception GeneratorExit dans la fonction génératrice asynchrone à l'endroit où le
générateur était en pause. Si la fonction génératrice asynchrone termine
normalement, est déjà fermée ou lève GeneratorExit (parce qu'elle ne gère pas
l'exception), alors le awaitable renvoyé lève une exception StopIteration. Tout
nouveau awaitable produit par un appel postérieur au générateur asynchrone lève
une exception StopAsyncIteration. Si le générateur asynchrone produit une
valeur, une RuntimeError est levée par le awaitable. Si le générateur asynchrone
lève une autre exception, elle est propagée à l'appelant du awaitable. Si le
générateur asynchrone a déjà terminé (soit par une exception, soit normalement),
alors tout nouvel appel à aclose() renvoie un awaitable qui ne fait rien.

6.3. Primaires
Les primaires (primary dans la grammaire formelle ci-dessous) représentent les
opérations qui se lient au plus proche dans le langage. Leur syntaxe est :

primary ::= atom | attributeref | subscription | slicing | call

6.3.1. Références à des attributs


Une référence à un attribut (attributeref dans la grammaire formelle ci-dessous) est
une primaire suivie par un point et un nom :

attributeref ::= primary "." identifier

La primaire doit s'évaluer à un objet d'un type qui gère les références aux attributs,
ce qui est le cas de la plupart des objets. Cet objet doit alors produire l'attribut dont le
nom est « identifier ». Cette production peut être personnalisée en surchargeant la
méthode __getattr__(). Si l'attribut n'est pas disponible, une
exception AttributeError est levée. Sinon, le type et la valeur de l'objet produit
sont déterminés par l'objet. Plusieurs évaluations successives d'une référence à un
même attribut peuvent produire différents objets.

6.3.2. Sélections
Une sélection (subscription dans la grammaire formelle ci-dessous) désigne un
élément dans un objet séquence (chaîne, n-uplet ou liste) ou tableau de
correspondances (dictionnaire) :

subscription ::= primary "[" expression_list "]"

La primaire doit s'appliquer à un objet qui gère les sélections (une liste ou un
dictionnaire par exemple). Les objets définis par l'utilisateur peuvent gérer les
sélections en définissant une méthode __getitem__().

Pour les objets natifs, deux types d'objets gèrent la sélection :

Si la primaire est un tableau de correspondances, la liste d'expressions


(expression_list dans la grammaire formelle ci-dessous) doit pouvoir être évaluée
comme un objet dont la valeur est une des clés du tableau de correspondances et la
sélection désigne la valeur qui correspond à cette clé (la liste d'expressions est un n-
uplet sauf si elle comporte exactement un élément).

Si la primaire est une séquence, la liste d'expressions (expression_list dans la


grammaire) doit pouvoir être évaluée comme un entier ou une tranche (comme
expliqué dans la section suivante).

La syntaxe formelle ne traite pas des cas d'indices négatifs dans les séquences ;
cependant, toutes les séquences natives possèdent une
méthode __getitem__() qui interprète les indices négatifs en ajoutant la longueur
de la séquence à l'indice (de manière à ce que x[-1] sélectionne le dernier élément
de x). La valeur résultante doit être un entier positif ou nul, inférieur au nombre
d'éléments dans la séquence ; la sélection désigne alors l'élément dont l'indice est
cette valeur (en comptant à partir de zéro). Comme la gestion des indices négatifs et
des tranches est faite par la méthode __getitem__(), les sous-classes qui
surchargent cette méthode doivent aussi savoir les gérer, de manière explicite.

Les éléments des chaînes sont des caractères. Un caractère n'est pas un type en
tant que tel, c'est une chaîne de longueur un.
6.3.3. Tranches
Une tranche (slicing dans la grammaire formelle ci-dessous) sélectionne un intervalle
d'éléments d'un objet séquence (par exemple une chaîne, un n-uplet ou une liste,
respectivement les types string, tuple et list). Les tranches peuvent être utilisées
comme des expressions ou des cibles dans les assignations ou les instructions del.
La syntaxe est la suivante :

slicing ::= primary "[" slice_list "]"


slice_list ::= slice_item ("," slice_item)* [","]
slice_item ::= expression | proper_slice
proper_slice ::= [lower_bound] ":" [upper_bound] [ ":" [stride] ]
lower_bound ::= expression
upper_bound ::= expression
stride ::= expression

Il existe une ambigüité dans la syntaxe formelle ci-dessus : tout ce qui ressemble à
une liste d'expressions (expression_list vue avant) ressemble aussi à une liste de
tranches (slice_list dans la grammaire ci-dessus). En conséquence, toute sélection
(subscription dans la grammaire) peut être interprétée comme une tranche. Plutôt
que de compliquer encore la syntaxe, l'ambigüité est levée en disant que, dans ce
cas, l'interprétation en tant que sélection (subscription) est prioritaire sur
l'interprétation en tant que tranche (c'est le cas si la liste de tranches ( slice_list) ne
contient aucune tranche en tant que telle).

La sémantique pour une tranche est définie comme suit. La primaire est indicée (en
utilisant la même méthode __getitem__() que pour les sélections normales) avec
une clé qui est construite à partir de la liste de tranches (slice_list dans la
grammaire), de cette manière : si la liste de tranches contient au moins une virgule
(,), la clé est un n-uplet contenant la conversion des éléments de la tranche ; sinon,
la conversion du seul élément de la tranche est la clé. La conversion d'un élément de
tranche qui est une expression est cette expression. La conversion d'une tranche en
tant que telle est un objet slice (voir la section Hiérarchie des types standards) dont
les attributs start, stop et step sont les valeurs des expressions données pour la
borne inférieure (lower_bound dans la grammaire), la borne supérieure
(upper_bound dans la grammaire) et le pas (stride dans la grammaire),
respectivement. En cas d'expression manquante, la valeur par défaut est None.

6.3.4. Appels
Un appel (call dans la grammaire ci-dessous) appelle un objet appelable (par
exemple, une fonction) avec, possiblement, une liste d'arguments :
call ::= primary "(" [argument_list [","] |
comprehension] ")"
argument_list ::= positional_arguments [","
starred_and_keywords]
["," keywords_arguments]
| starred_and_keywords [","
keywords_arguments]
| keywords_arguments
positional_arguments ::= ["*"] expression ("," ["*"] expression)*
starred_and_keywords ::= ("*" expression | keyword_item)
("," "*" expression | "," keyword_item)*
keywords_arguments ::= (keyword_item | "**" expression)
("," keyword_item | "," "**"
expression)*
keyword_item ::= identifier "=" expression

Une virgule finale (optionnelle) peut être présente, après les arguments positionnels
et par mots-clés, mais elle n'affecte pas la sémantique.

La primaire doit s'évaluer à un objet appelable (une fonction définie par l'utilisateur,
une fonction native, une méthode d'objet natif, un objet de classe, une méthode
d'instance de classe ou tout objet possédant une méthode __call__() est un
appelable). Toutes les expressions des arguments sont évaluées avant que l'appel
ne soit exécuté. Référez-vous à la section Définition de fonctions pour la syntaxe des
listes de paramètres formels.

Si des arguments par mots-clés sont présents, ils sont d'abord convertis en
arguments positionnels, comme suit. Pour commencer, une liste de slots vides est
créée pour les paramètres formels. S'il y a N arguments positionnels, ils sont placés
dans les N premiers slots. Ensuite, pour chaque argument par mot-clé, l'identifiant
est utilisé pour déterminer le slot correspondant (si l'identifiant est le même que le
nom du premier paramètre formel, le premier slot est utilisé, et ainsi de suite). Si
le slot est déjà rempli, une exception TypeError est levée. Sinon, la valeur de
l'argument est placée dans le slot, ce qui le remplit (même si l'expression est None,
cela remplit le slot). Quand tous les arguments ont été traités, les slots qui sont
toujours vides sont remplis avec la valeur par défaut correspondante dans la
définition de la fonction (les valeurs par défaut sont calculées, une seule fois, lorsque
la fonction est définie ; ainsi, un objet mutable tel qu'une liste ou un dictionnaire
utilisé en tant valeur par défaut sera partagé entre tous les appels qui ne spécifient
pas de valeur d argument pour ce slot ; on évite généralement de faire ça). S'il reste
des slots pour lesquels aucune valeur par défaut n'est définie, une
exception TypeError est levée. Sinon, la liste des slots remplie est utilisée en tant
que liste des arguments pour l'appel.
CPython implementation detail: Une implémentation peut fournir des fonctions
natives dont les paramètres positionnels n'ont pas de nom, même s'ils sont
« nommés » pour les besoins de la documentation. Ils ne peuvent donc pas être
spécifiés par mot-clé. En CPython, les fonctions implémentées en C qui
utilisent PyArg_ParseTuple() pour analyser leurs arguments en font partie.

S'il y a plus d'arguments positionnels que de slots de paramètres formels, une


exception TypeError est levée, à moins qu'un paramètre formel n'utilise la
syntaxe *identifier ; dans ce cas, le paramètre formel reçoit un n-uplet contenant
les arguments positionnels en supplément (ou un n-uplet vide s'il n'y avait pas
d'arguments positionnel en trop).

Si un argument par mot-clé ne correspond à aucun nom de paramètre formel, une


exception TypeError est levée, à moins qu'un paramètre formel n'utilise la
syntaxe **identifier ; dans ce cas, le paramètre formel reçoit un dictionnaire
contenant les arguments par mot-clé en trop (en utilisant les mots-clés comme clés
et les arguments comme valeurs pour ce dictionnaire), ou un (nouveau) dictionnaire
vide s'il n'y a pas d'argument par mot-clé en trop.

Si la syntaxe *expression apparaît dans l'appel de la fonction, expression doit


pouvoir s'évaluer à un itérable. Les éléments de ces itérables sont traités comme s'ils
étaient des arguments positionnels supplémentaires. Pour
l'appel f(x1, x2, *y, x3, x4), si y s'évalue comme une séquence y1, ..., yM,
c'est équivalent à un appel avec M+4 arguments
positionnels x1, x2, y1, ..., yM, x3, x4.

Une conséquence est que bien que la syntaxe *expression puisse


apparaître après les arguments par mots-clés explicites, ils sont traités avant les
arguments par mots-clés (et avant tout argument **expression -- voir ci-dessous).
Ainsi :

>>>

>>> def f(a, b):


... print(a, b)
...
>>> f(b=1, *(2,))
2 1
>>> f(a=1, *(2,))
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
TypeError: f() got multiple values for keyword argument 'a'
>>> f(1, *(2,))
1 2
Il est inhabituel que les syntaxes d'arguments par mots-clés et *expression soient
utilisés simultanément dans un même appel, ce qui fait que la confusion reste
hypothétique.

Si la syntaxe **expression apparaît dans un appel de fonction, expression doit


pouvoir s'évaluer comme un tableau de correspondances, dont le contenu est traité
comme des arguments par mots-clés supplémentaires. Si un mot-clé est déjà
présent (en tant qu'argument par mot-clé explicite, ou venant d'un autre
dépaquetage), une exception TypeError est levée.

Les paramètres formels qui utilisent la syntaxe *identifier ou **identifier ne


peuvent pas être utilisés comme arguments positionnels ou comme noms
d'arguments par mots-clés.

Modifié dans la version 3.5: Les appels de fonction acceptent n'importe quel nombre
de dépaquetages par * ou **. Des arguments positionnels peuvent suivre les
dépaquetages d'itérables (*) et les arguments par mots-clés peuvent suivre les
dépaquetages de dictionnaires (**). Proposé pour la première fois par la PEP 448.

Un appel renvoie toujours une valeur, possiblement None, à moins qu'il ne lève une
exception. La façon dont celle valeur est calculée dépend du type de l'objet
appelable.

Si c'est ---

une fonction définie par l'utilisateur :

le bloc de code de la fonction est exécuté, il reçoit la liste des arguments. La


première chose que le bloc de code fait est de lier les paramètres formels aux
arguments ; ceci est décrit dans la section Définition de fonctions. Quand le bloc de
code exécute l'instruction return, cela spécifie la valeur de retour de l'appel de la
fonction.

une fonction ou une méthode native :

le résultat dépend de l'interpréteur ; lisez Fonctions natives pour une description des


fonctions et méthodes natives.

un objet classe :

une nouvelle instance de cette classe est renvoyée.

une méthode d'instance de classe :


la fonction correspondante définie par l'utilisateur est appelée, avec la liste
d'arguments qui est plus grande d'un élément que la liste des arguments de l'appel  :
l'instance est placée en tête des arguments.

une instance de classe :

la classe doit définir une méthode __call__() ; l'effet est le même que si cette
méthode était appelée.

6.4. Expression await
Suspend l'exécution de la coroutine sur un objet awaitable. Ne peut être utilisée qu'à
l'intérieur d'une coroutine function.

await_expr ::= "await" primary

Nouveau dans la version 3.5.

6.5. L'opérateur puissance
L'opérateur puissance est plus prioritaire que les opérateurs unaires sur sa gauche  ;
il est moins prioritaire que les opérateurs unaires sur sa droite. La syntaxe est :

power ::= (await_expr | primary) ["**" u_expr]

Ainsi, dans une séquence sans parenthèse de puissance et d'opérateurs unaires, les
opérateurs sont évalués de droite à gauche (ceci ne contraint pas l'ordre d'évaluation
des opérandes) : -1**2 donne -1.

L'opérateur puissance possède la même sémantique que la fonction


native pow() lorsqu'elle est appelée avec deux arguments : il produit son argument
de gauche élevé à la puissance de son argument de droite. Les arguments
numériques sont d'abord convertis vers un type commun et le résultat est de ce type.

Pour les opérandes entiers, le résultat est du même type à moins que le deuxième
argument ne soit négatif ; dans ce cas, tous les arguments sont convertis en
nombres à virgule flottante et le résultat est un nombre à virgule flottante. Par
exemple, 10**2 renvoie 100 mais 10**-2 renvoie 0.01.

Élever 0.0 à une puissance négative entraîne une ZeroDivisionError. Élever un


nombre négatif à une puissance fractionnaire renvoie un nombre complexe (dans
les versions antérieures, cela levait une ValueError).
6.6. Arithmétique unaire et opérations sur les bits
Toute l'arithmétique unaire et les opérations sur les bits ont la même priorité :

u_expr ::= power | "-" u_expr | "+" u_expr | "~" u_expr

L'opérateur unaire - (moins) produit l'opposé de son argument numérique.

L'opérateur unaire + (plus) produit son argument numérique inchangé.

L'opérateur unaire ~ (inversion) produit l'inversion bit à bit de son argument entier.


L'inversion bit à bit de x est définie comme -(x+1). Elle s'applique uniquement aux
nombres entiers.

Dans ces trois cas, si l'argument n'est pas du bon type, une
exception TypeError est levée.

6.7. Opérations arithmétiques binaires


Les opérations arithmétiques binaires suivent les conventions pour les priorités.
Notez que certaines de ces opérations s'appliquent aussi à des types non
numériques. À part l'opérateur puissance, il n'y a que deux niveaux, le premier pour
les opérateurs multiplicatifs et le second pour les opérateurs additifs :

m_expr ::= u_expr | m_expr "*" u_expr | m_expr "@" m_expr |


m_expr "//" u_expr | m_expr "/" u_expr |
m_expr "%" u_expr
a_expr ::= m_expr | a_expr "+" m_expr | a_expr "-" m_expr

L'opérateur * (multiplication) produit le produit de ses arguments. Les deux


arguments doivent être des nombres ou alors le premier argument doit être un entier
et l'autre doit être une séquence. Dans le premier cas, les nombres sont convertis
dans un type commun puis sont multipliés entre eux. Dans le dernier cas, la
séquence est répétée ; une répétition négative produit une séquence vide.

L'opérateur @ (prononcé at en anglais) a vocation à multiplier des matrices. Aucun


type Python natif n'implémente cet opérateur.

Nouveau dans la version 3.5.

Les opérateurs / (division) et // (division entière ou floor division en anglais)


produisent le quotient de leurs arguments. Les arguments numériques sont d'abord
convertis vers un type commun. La division d'entiers produit un nombre à virgule
flottante alors que la division entière d'entiers produit un entier ; le résultat est celui
de la division mathématique suivie de la fonction floor appliquée au résultat. Une
division par zéro lève une exception ZeroDivisionError.

L'opérateur % (modulo) produit le reste de la division entière du premier argument par


le second. Les arguments numériques sont d'abord convertis vers un type commun.
Un zéro en second argument lève une exception ZeroDivisionError. Les
arguments peuvent être des nombres à virgule flottante, par
exemple 3.14%0.7 vaut 0.34 (puisque 3.14 égale 4*0.7+0.34). L'opérateur
modulo produit toujours un résultat du même signe que le second opérande (ou
zéro) ; la valeur absolue du résultat est strictement inférieure à la valeur absolue du
second opérande 1.

Les opérateurs division entière et modulo sont liés par la relation


suivante : x == (x//y)*y + (x%y). La division entière et le module sont aussi liés
à la fonction native divmod() : divmod(x, y) == (x//y, x%y) 2.

En plus de calculer le modulo sur les nombres, l'opérateur % est aussi surchargé par
les objets chaînes de caractères pour effectuer le formatage de chaîne « à
l'ancienne ». La syntaxe pour le formatage de chaînes est décrit dans la référence de
la bibliothèque Python, dans la section Formatage de chaines à la printf.

L'opérateur de division entière, l'opérateur modulo et la fonction divmod() ne sont


pas définis pour les nombres complexes. À la place, vous pouvez, si cela a du sens
pour ce que vous voulez faire, les convertir vers des nombres à virgule flottante en
utilisant la fonction abs().

L'opérateur + (addition) produit la somme de ses arguments. Les arguments doivent


être tous les deux des nombres ou des séquences du même type. Dans le premier
cas, les nombres sont convertis vers un type commun puis sont additionnés entre
eux. Dans le dernier cas, les séquences sont concaténées.

L'opérateur - (soustraction) produit la différence entre ses arguments. Les


arguments numériques sont d'abord convertis vers un type commun.

6.8. Opérations de décalage
Les opérations de décalage sont moins prioritaires que les opérations arithmétiques :

shift_expr ::= a_expr | shift_expr ("<<" | ">>") a_expr


Ces opérateurs prennent des entiers comme arguments. Ils décalent le premier
argument vers la gauche ou vers la droite du nombre de bits donné par le deuxième
argument.

Un décalage à droite de n bits est défini comme la division entière par pow(2,n). Un


décalage à gauche de n bits est défini comme la multiplication par pow(2,n).

6.9. Opérations binaires bit à bit


Chacune des trois opérations binaires bit à bit possède une priorité différente :

and_expr ::= shift_expr | and_expr "&" shift_expr


xor_expr ::= and_expr | xor_expr "^" and_expr
or_expr ::= xor_expr | or_expr "|" xor_expr

L'opérateur & produit le ET logique de ses arguments, qui doivent être des entiers.

L'opérateur ^ produit le OU EXCLUSIF (XOR) logique de ses arguments, qui doivent


être des entiers.

L'opérateur | produit le OU logique de ses arguments, qui doivent être des entiers.

6.10. Comparaisons
Au contraire du C, toutes les opérations de comparaison en Python possèdent la
même priorité, qui est plus faible que celle des opérations arithmétiques, décalages
ou binaires bit à bit. Toujours contrairement au C, les expressions telles
que a < b < c sont interprétées comme elles le seraient conventionnellement en
mathématiques :

comparison ::= or_expr (comp_operator or_expr)*


comp_operator ::= "<" | ">" | "==" | ">=" | "<=" | "!="
| "is" ["not"] | ["not"] "in"

Les comparaisons produisent des valeurs booléennes : True ou False.

Les comparaisons peuvent être enchaînées arbitrairement, par


exemple x < y <= z est équivalent à x < y and y <= z, sauf que y est évalué
seulement une fois (mais dans les deux cas, z n'est pas évalué du tout
si x < y s'avère être faux).
Formellement, si a, b, c, ..., y, z sont des expressions et op1, op2, ..., opN sont des
opérateurs de comparaison, alors a op1 b op2 c ... y opN z est équivalent
à a op1 b and b op2 c and ... y opN z, sauf que chaque expression est
évaluée au maximum une fois.

Notez que a op1 b op2 c n'implique aucune comparaison entre a et c. Ainsi, par


exemple, x < y > z est parfaitement légal (mais peut-être pas très élégant).

6.10.1. Comparaisons de valeurs
Les opérateurs <, >, ==, >=, <= et != comparent les valeurs de deux objets. Les
objets n'ont pas besoin d'être du même type.

Le chapitre Objets, valeurs et types indique que les objets ont une valeur (en plus
d'un type et d'un identifiant). La valeur d'un objet est une notion plutôt abstraite en
Python : par exemple, il n'existe pas de méthode canonique pour accéder à la valeur
d'un objet. De la même manière, il n'y a aucune obligation concernant la construction
de la valeur d'un objet, par exemple qu'elle prenne en compte toutes les données de
ses attributs. Les opérateurs de comparaison implémentent une notion particulière
de ce qu'est la valeur d'un objet. Vous pouvez vous le représenter comme une
définition indirecte de la valeur d'un objet, via l'implémentation de leur comparaison.

Comme tous les types sont des sous-types (directs ou indirects) de la


classe object, ils héritent du comportement de comparaison par défaut de object.
Les types peuvent personnaliser le comportement des comparaisons en
implémentant des méthodes de comparaisons riches, comme __lt__(), décrites
dans Personnalisation de base.

Le comportement par défaut pour le test d'égalité ( == et !=) se base sur les
identifiants des objets. Ainsi, un test d'égalité entre deux instances qui ont le même
identifiant est vrai, un test d'égalité entre deux instances qui ont des identifiants
différents est faux. La raison de ce choix est que Python souhaite que tous les objets
soient réflexifs, c'est-à-dire que x is y implique x == y.

La relation d'ordre (<, >, <= et >=) n'est pas fournie par défaut ; une tentative se
solde par une TypeError. La raison de ce choix est qu'il n'existe pas d'invariant
similaire à celui de l'égalité.

Le comportement du test d'égalité par défaut, à savoir que les instances avec des
identités différentes ne sont jamais égales, peut être en contradiction avec les types
qui définissent la « valeur » d'un objet et se basent sur cette « valeur » pour l'égalité.
De tels types doivent personnaliser leurs tests de comparaison et, en fait, c'est ce
qu'ont fait un certain nombre de types natifs.

La liste suivante décrit le comportement des tests d'égalité pour les types natifs les
plus importants.

 Beaucoup de types numériques natifs (Types numériques — int, float,


complex) et de types de la bibliothèque standard fractions.Fraction ainsi
que decimal.decimal peuvent être comparés, au sein de leur propre classe ou
avec d'autres objets de classes différentes. Une exception notable concerne les
nombres complexes qui ne gèrent pas la relation d'ordre. Dans les limites des types
concernés, la comparaison mathématique équivaut à la comparaison algorithmique,
sans perte de précision.

The not-a-number values float('NaN') and decimal.Decimal('NaN') are


special. Any ordered comparison of a number to a not-a-number value is false. A
counter-intuitive implication is that not-a-number values are not equal to themselves.
For example, if x = float('NaN'), 3 < x, x < 3 and x == x are all false,
while x != x is true. This behavior is compliant with IEEE 754.
 Les séquences binaires (instances du type bytes ou bytearray) peuvent
être comparées au sein de la classe et entre classes. La comparaison est
lexicographique, en utilisant la valeur numérique des éléments.
 Les chaînes de caractères (instances de str) respectent l'ordre
lexicographique en utilisant la valeur Unicode (le résultat de la fonction native ord())
des caractères 3.

Les chaînes de caractères et les séquences binaires ne peuvent pas être comparées
directement.
 Les séquences (instances de tuple, list ou range) peuvent être
comparées uniquement entre instances de même type, en sachant que les
intervalles (range) ne gèrent pas la relation d'ordre. Le test d'égalité entre ces types
renvoie faux et une comparaison entre instances de types différents lève
une TypeError.

Les séquences suivent l'ordre lexicographique en utilisant la comparaison de leurs


éléments, sachant que la réflexivité des éléments est appliquée.

Dans l'application de la réflexivité des éléments, la comparaison des collections


suppose que pour un élément de collection x, x == x est toujours vrai. Sur la base
de cette hypothèse, l'identité des éléments est d'abord testée, puis la comparaison
des éléments n'est effectuée que pour des éléments distincts. Cette approche donne
le même résultat qu'une comparaison stricte d'éléments, si les éléments comparés
sont réflexifs. Pour les éléments non réflexifs, le résultat est différent de celui de la
comparaison stricte des éléments, voire peut être surprenant : les valeurs non
réflexives qui ne sont pas des nombres, par exemple, aboutissent au comportement
suivant lorsqu'elles sont utilisées dans une liste :

>>>

>>> nan = float('NaN')


>>> nan is nan
True
>>> nan == nan
False <-- the defined non-reflexive behavior of
NaN
>>> [nan] == [nan]
True <-- list enforces reflexivity and tests
identity first

L'ordre lexicographique pour les collections natives fonctionne comme suit :

o Deux collections sont égales si elles sont du même type, ont la même
longueur et si les éléments correspondants de chaque paire sont égaux. Par
exemple, [1,2] == (1,2) est faux car les types sont différents.
o Les collections qui gèrent la relation d'ordre sont ordonnées comme
leur premier élément différent (par exemple, [1,2,x] <= [1,2,y] a la même
valeur que x <= y). Si un élément n'a pas de correspondant, la collection la plus
courte est la plus petite (par exemple, [1,2] < [1,2,3] est vrai).
 Les tableaux de correspondances (instances de dict) sont égales si et
seulement si toutes leurs paires (clé, valeur) sont égales. L'égalité des clés et des
valeurs met en œuvre la réflexivité.

Les comparaisons (<, >, <= et >=) lèvent TypeError.


 Les ensembles (instances de set ou frozenset) peuvent être comparés au
sein de leur propre type et entre types différents.

Les opérateurs d'inclusion et de sur-ensemble sont définis. Ces relations ne sont pas
des relations d'ordre total (par exemple, les deux ensembles {1,2} et {2,3} ne sont
pas égaux, l'un n'est pas inclus dans l'autre, l'un n'est pas un sur-ensemble de
l'autre). Ainsi, les ensembles ne sont pas des arguments appropriés pour les
fonctions qui dépendent d'un ordre total (par exemple, les
fonctions min(), max() et sorted() produisent des résultats indéfinis si on leur
donne des listes d'ensembles en entrée).

La comparaison des ensembles met en œuvre la réflexivité des éléments.


 La plupart des autres types natifs n'implémentent pas de méthodes de
comparaisons, ils héritent donc du comportement par défaut.

Les classes allogènes qui particularisent les opérations de comparaison doivent, si


possible, respecter quelques règles pour la cohérence :

 Le test d'égalité doit être réflexif. En d'autres termes, des objets identiques
doivent être égaux :

x is y implique x == y

 La comparaison doit être symétrique. En d'autres termes, les expressions


suivantes doivent donner le même résultat :

x == y et y == x

x != y et y != x

x < y et y > x

x <= y et y >= x

 La comparaison doit être transitive. Les exemples suivants (liste non


exhaustive) illustrent ce concept :

x > y and y > z implique x > z

x < y and y <= z implique x < z

 Si vous inversez la comparaison, cela doit en produire la négation booléenne.


En d'autres termes, les expressions suivantes doivent produire le même résultat :

x == y et not x != y

x < y et not x >= y (pour une relation d'ordre total)

x > y et not x <= y (pour une relation d'ordre total)

Ces deux dernières expressions s'appliquent pour les collections totalement


ordonnées (par exemple, les séquences mais pas les ensembles ou les tableaux de
correspondances). Regardez aussi le décorateur total_ordering().
 Le résultat de hash() doit être cohérent avec l'égalité. Les objets qui sont
égaux doivent avoir la même empreinte ou être marqués comme non-hachables.
Python ne vérifie pas ces règles de cohérence. En fait, l'utilisation de valeurs non
numériques est un exemple de non-respect de ces règles.

6.10.2. Opérations de tests d’appartenance à un


ensemble
Les opérateurs in et not in testent l’appartenance. x in s s’évalue
à True si x appartient à s et à False sinon. x not in s renvoie la négation
de x in s. Tous les types séquences et ensembles natifs gèrent ces opérateurs,
ainsi que les dictionnaires pour lesquels in teste si dictionnaire possède une clé
donnée. Pour les types conteneurs tels que les listes, n-uplets (tuple), ensembles
(set), ensembles gelés (frozen set), dictionnaires (dict) ou collections.deque,
l’expression x in y est équivalente à any(x is e or x == e for e in y).

Pour les chaînes de caractères et chaînes d'octets, x in y vaut True si et


seulement si x est une sous-chaîne de y. Un test équivalent est y.find(x) != -1.
Une chaîne vide est considérée comme une sous-chaîne de toute autre chaîne,
ainsi "" in "abc" renvoie True.

Pour les classes allogènes qui définissent la


méthode __contains__(), x in y renvoie True si y.__contains__(x) renvoie
vrai, et False sinon.

Pour les classes allogènes qui ne définissent pas __contains__() mais qui


définissent __iter__(), x in y vaut True s'il existe une valeur z telle que
l'expression x is z or x == z renvoie vrai lors de l'itération sur y. Si une
exception est levée pendant l'itération, c'est comme si in avait levé cette exception.

Enfin, le protocole d'itération « à l'ancienne » est essayé : si la classe


définit __getitem__(), x in y est True si et seulement si il existe un entier positif
ou nul i, représentant l'indice, tel que x is y[i] or x == y[i] et qu'aucun indice
inférieur ne lève d'exception IndexError (si toute autre exception est levée, c'est
comme si in avait levé cette exception).

L'opérateur not in est défini comme produisant le contraire de in.

6.10.3. Comparaisons d'identifiants
Les opérateurs is et is not testent l'égalité des identifiants des objets : x is y est
vrai si et seulement si x et y sont le même objet. L'identifiant d'un objet est déterminé
en utilisant la fonction id(). x is not y renvoie le résultat contraire de l'égalité des
identifiants 4.
6.11. Opérations booléennes
or_test ::= and_test | or_test "or" and_test
and_test ::= not_test | and_test "and" not_test
not_test ::= comparison | "not" not_test

Dans le contexte des opérations booléennes et quand des expressions sont utilisées
par des instructions de contrôle du flux d'exécution, les valeurs suivantes sont
considérées comme fausses : False, None, zéro quel que soit le type, la chaîne vide
et tout conteneur vide (y compris les chaînes, n-uplets, listes, dictionnaires,
ensembles, ensembles gelés). Toutes les autres valeurs sont considérées comme
vraies. Les objets allogènes peuvent personnaliser leur table de vérité en
implémentant une méthode __bool__().

L'opérateur not produit True si son argument est faux, False sinon.

L'expression x and y commence par évaluer x ; si x est faux, sa valeur est


renvoyée ; sinon, y est évalué et la valeur résultante est renvoyée.

L'expression x or y commence par évaluer x ; si x est vrai, sa valeur est renvoyée ;


sinon, y est évalué et la valeur résultante est renvoyée.

Notez que ni and ni or ne restreignent la valeur et le type qu'ils renvoient


à False et True : ils renvoient le dernier argument évalué. Ceci peut être utile, par
exemple : si une chaîne s doit être remplacée par une valeur par défaut si elle est
vide, l'expression s or 'truc' produit la valeur voulue. Comme not doit créer une
nouvelle valeur, il renvoie une valeur booléenne quel que soit le type de son
argument (par exemple, not 'truc' produit False plutôt que ''.

6.12. Expressions conditionnelles
conditional_expression ::= or_test ["if" or_test "else"
expression]
expression ::= conditional_expression | lambda_expr
expression_nocond ::= or_test | lambda_expr_nocond

Les expressions conditionnelles (parfois appelées « opérateur ternaire ») sont les


moins prioritaires de toutes les opérations Python.

L'expression x if C else y commence par évaluer la condition C. Si C est vrai,


alors x est évalué et sa valeur est renvoyée ; sinon, y est évalué et sa valeur est
renvoyée.

Voir la PEP 308 pour plus de détails sur les expressions conditionnelles.


6.13. Expressions lambda
lambda_expr ::= "lambda" [parameter_list] ":" expression
lambda_expr_nocond ::= "lambda" [parameter_list] ":"
expression_nocond

Les expressions lambda sont utilisées pour créer des fonctions anonymes.
L'expression lambda parameters: expression produit un objet fonction. Cet
objet anonyme se comporte comme un objet fonction défini par :

def <lambda>(parameters):
return expression

Voir la section Définition de fonctions pour la syntaxe des listes de paramètres.


Notez que les fonctions créées par des expressions lambda ne peuvent pas contenir
d'instructions ou d'annotations.

6.14. Listes d'expressions
expression_list ::= expression ("," expression)* [","]
starred_list ::= starred_item ("," starred_item)* [","]
starred_expression ::= expression | (starred_item ",")*
[starred_item]
starred_item ::= expression | "*" or_expr

Sauf lorsqu'elle fait partie d'un agencement de liste ou d'ensemble, une liste
d'expressions qui contient au moins une virgule produit un n-uplet (tuple). La
longueur du n-uplet est le nombre d'expressions dans la liste. Les expressions sont
évaluées de la gauche vers la droite.

Un astérisque * indique dépaquetage d'itérable (iterable unpacking en anglais). Son


opérande doit être un iterable. L'itérable est développé en une séquence d'éléments
qui sont inclus dans un nouvel objet tuple, list ou set à l'emplacement du
dépaquetage.

Nouveau dans la version 3.5: dépaquetage d'itérables dans les listes d'expressions,


proposé à l'origine par la PEP 448.

La virgule finale est nécessaire pour créer un singleton (c'est-à-dire un n-uplet


composé d'un seul élément) : elle est optionnelle dans tous les autres cas. Une
expression seule sans virgule finale ne crée pas un n-uplet mais produit la valeur de
cette expression (pour créer un tuple vide, utilisez une paire de parenthèses
vide : ()).
6.15. Ordre d'évaluation
Python évalue les expressions de la gauche vers la droite. Remarquez que lors de
l'évaluation d'une assignation, la partie droite de l'assignation est évaluée avant la
partie gauche.

Dans les lignes qui suivent, les expressions sont évaluées suivant l'ordre
arithmétique de leurs suffixes :

expr1, expr2, expr3, expr4


(expr1, expr2, expr3, expr4)
{expr1: expr2, expr3: expr4}
expr1 + expr2 * (expr3 - expr4)
expr1(expr2, expr3, *expr4, **expr5)
expr3, expr4 = expr1, expr2

6.16. Priorités des opérateurs


Le tableau suivant résume les priorités des opérateurs en Python, du moins
prioritaire au plus prioritaire. Les opérateurs qui sont dans la même case ont la
même priorité. À moins que la syntaxe ne soit explicitement indiquée, les opérateurs
sont binaires. Les opérateurs dans la même cases regroupent de la gauche vers la
droite (sauf pour la puissance qui regroupe de la droite vers la gauche).

Notez que les comparaisons, les tests d'appartenance et les tests d'identifiants
possèdent tous la même priorité et s'enchaînent de la gauche vers la droite comme
décrit dans la section Comparaisons.

Opérateur Description
lambda Expression lambda
if – else Expressions conditionnelle
or OR (booléen)
and AND (booléen)
not x NOT (booléen)
in, not in, is, is not, <,  Comparaisons, y compris les tests d'appartenance et les
<=, >, >=, !=, == tests d'identifiants
| OR (bit à bit)
^ XOR (bit à bit)
& AND (bit à bit)
Opérateur Description
<<, >> décalages
+, - Addition et soustraction

Multiplication, multiplication de matrices, division,


*, @, /, //, %
division entière, reste 5
+x, -x, ~x NOT (positif, négatif, bit à bit)
** Puissance 6
await x Expression await

x[indice], x[indice:ind
ice], x(arguments...), x indiçage, tranches, appel, référence à un attribut
.attribut

(expressions...),

Binding or parenthesized expression, list display,


[expressions...], {key: 
dictionary display, set display
value...}, {expressions
...}

Notes

1 Bien que abs(x%y) < abs(y) soit vrai mathématiquement, ce n'est pas toujours vrai


pour les nombres à virgule flottante en raison des arrondis. Par exemple, en supposant que
Python tourne sur une plateforme où les float sont des nombres à double précision IEEE
754, afin que -1e-100 % 1e100 soit du même signe que 1e100, le résultat calculé est -
1e-100 + 1e100, qui vaut exactement 1e100 dans ce standard. Or, la
fonction math.fmod() renvoie un résultat dont le signe est le signe du premier argument,
c'est-à-dire -1e-100 dans ce cas. La meilleure approche dépend de l'application.

2 Si x est très proche d'un multiple entier de y, il est possible que x/y soit supérieur de un
par rapport à (x-x%y)//y en raison des arrondis. Dans de tels cas, Python renvoie le
second résultat afin d'avoir divmod(x,y)[0] * y + x % y le plus proche de x.

3 Le standard Unicode distingue les points codes (code points en anglais, par


exemple U+0041) et les caractères abstraits (abstract characters en anglais, par exemple
« LATIN CAPITAL LETTER A »). Bien que la plupart des caractères abstraits de l'Unicode
ne sont représentés que par un seul point code, il y a un certain nombre de caractères
abstraits qui peuvent être représentés par une séquence de plus qu'un point code. Par
exemple, le caractère abstrait « LATIN CAPITAL LETTER C WITH CEDILLA » peut être
représenté comme un unique caractère précomposé au point code U+00C7, ou en tant que
séquence d'un caractère de base à la position U+0043 (LATIN CAPITAL LETTER C) du
code, suivi par un caractère combiné à la position U+0327 (COMBINING CEDILLA) du code.
Les opérateurs de comparaison des chaînes opèrent au niveau des points codes
Unicode. Cela peut être déroutant pour des humains. Par
exemple, "\u00C7" == "\u0043\u0327" renvoie False, bien que les deux
chaînes représentent le même caractère abstrait "LATIN CAPITAL LETTER C WITH
CEDILLA".

Pour comparer des chaînes au niveau des caractères abstraits (afin d'avoir quelque
chose d'intuitif pour les humains), utilisez unicodedata.normalize().

4 En raison du ramasse-miettes automatique et de la nature dynamique des descripteurs,


vous pouvez être confronté à un comportement semblant bizarre lors de certaines utilisations
de l'opérateur is, par exemple si cela implique des comparaisons entre des méthodes
d'instances ou des constantes. Allez vérifier dans la documentation pour plus d'informations.
5 L'opérateur % est aussi utilisé pour formater les chaînes de caractères ; il y possède la
même priorité.
6 L'opérateur puissance ** est moins prioritaire qu'un opérateur unaire arithmétique ou bit à
bit sur sa droite. Ainsi, 2**-1 vaut 0.5.

7. Les instructions simples


Une instruction simple est contenue dans une seule ligne logique. Plusieurs
instructions simples peuvent être écrites sur une seule ligne, séparées par des
points-virgules. La syntaxe d'une instruction simple est :

simple_stmt ::= expression_stmt


| assert_stmt
| assignment_stmt
| augmented_assignment_stmt
| annotated_assignment_stmt
| pass_stmt
| del_stmt
| return_stmt
| yield_stmt
| raise_stmt
| break_stmt
| continue_stmt
| import_stmt
| future_stmt
| global_stmt
| nonlocal_stmt
7.1. Les expressions
Les expressions sont utilisées (généralement de manière interactive) comme
instructions pour calculer et écrire des valeurs, appeler une procédure (une fonction
dont le résultat renvoyé n'a pas d'importance ; en Python, les procédures renvoient la
valeur None). D'autres utilisations des expressions sont autorisées et parfois utiles.
La syntaxe pour une expression en tant qu'instruction est :

expression_stmt ::= starred_expression

Ce genre d'instruction évalue la liste d'expressions (qui peut se limiter à une seule
expression).

En mode interactif, si la valeur n'est pas None, elle est convertie en chaîne en


utilisant la fonction native repr() et la chaîne résultante est écrite sur la sortie
standard sur sa propre ligne. Si le résultat est None, rien n'est écrit ce qui est usuel
pour les appels de procédures.

7.2. Les assignations
Les assignations sont utilisées pour lier ou relier des noms à des valeurs et modifier
des attributs ou des éléments d'objets muables :

assignment_stmt ::= (target_list "=")+ (starred_expression |


yield_expression)
target_list ::= target ("," target)* [","]
target ::= identifier
| "(" [target_list] ")"
| "[" [target_list] "]"
| attributeref
| subscription
| slicing
| "*" target

Voir la section Primaires pour la définition des syntaxes


de attributeref, subscription et slicing.

Une assignation évalue la liste d'expressions (gardez en mémoire que ce peut être
une simple expression ou une liste dont les éléments sont séparés par des virgules,
cette dernière produisant un n-uplet) et assigne l'unique objet résultant à chaque liste
cible, de la gauche vers la droite.

Une assignation est définie récursivement en fonction de la forme de la cible (une


liste). Quand la cible est une partie d'un objet muable (une référence à un attribut,
une sélection ou une tranche), l'objet muable doit effectuer l'assignation au final et
décider de sa validité, voire lever une exception si l'assignation n'est pas acceptable.
Les règles suivies par les différents types et les exceptions levées sont données
dans les définitions des types d'objets (voir la section Hiérarchie des types
standards).

L'assignation d'un objet à une liste cible, optionnellement entourée par des
parenthèses ou des crochets, est définie récursivement comme suit.

 Si la liste cible est une cible unique sans virgule de fin, optionnellement entre
parenthèses, l'objet est assigné à cette cible.
 Sinon : l'objet doit être un itérable avec le même nombre d'éléments qu'il y a
de cibles dans la liste cible ; les éléments sont assignés, de la gauche vers la droite,
vers les cibles correspondantes.

o Si la liste cible contient une cible préfixée par un astérisque, appelée


cible étoilée (starred target en anglais) : l'objet doit être un itérable avec au moins
autant d'éléments qu'il y a de cibles dans la liste cible, moins un. Les premiers
éléments de l'itérable sont assignés, de la gauche vers la droite, aux cibles avant la
cible étoilée. Les éléments de queue de l'itérable sont assignés aux cibles après la
cible étoilée. Une liste des éléments restants dans l'itérable est alors assignée à la
cible étoilée (cette liste peut être vide).
o Sinon : l'objet doit être un itérable avec le même nombre d'éléments
qu'il y a de cibles dans la liste cible ; les éléments sont assignés, de la gauche vers
la droite, vers les cibles correspondantes.

L'assignation d'un objet vers une cible unique est définie récursivement comme suit.

 Si la cible est une variable (un nom) :

o si le nom n'apparaît pas dans une


instruction global ou nonlocal (respectivement) du bloc de code courant, le nom
est lié à l'objet dans l'espace courant des noms locaux ;
o sinon le nom est lié à l'objet dans l'espace des noms globaux ou dans
un espace de nommage plus large déterminé par nonlocal, respectivement.
Le lien du nom est modifié si le nom était déjà lié. Ceci peut faire que le compteur de
références de l'objet auquel le nom était précédemment lié tombe à zéro, entrainant
la dé-allocation de l'objet et l'appel de son destructeur (s'il existe).
 Si la cible est une référence à un attribut : l'expression primaire de la
référence est évaluée. Elle doit produire un objet avec des attributs que l'on peut
assigner : si ce n'est pas le cas, une TypeError est levée. Python demande alors à
cet objet d'assigner l'attribut donné ; si ce n'est pas possible, une exception est levée
(habituellement, mais pas nécessairement, AttributeError).

Note : si l'objet est une instance de classe et que la référence à l'attribut apparaît des
deux côtés de l'opérateur d'assignation, l'expression "à droite", a.x peut accéder soit
à l'attribut d'instance ou (si cet attribut d'instance n'existe pas) à l'attribut de classe.
L'expression cible "à gauche" a.x est toujours définie comme un attribut d'instance,
en le créant si nécessaire. Ainsi, les deux occurrences de a.x ne font pas
nécessairement référence au même attribut : si l'expression "à droite" fait référence à
un attribut de classe, l'expression "à gauche" crée un nouvel attribut d'instance
comme cible de l'assignation :

class Cls:
x = 3 # class variable
inst = Cls()
inst.x = inst.x + 1 # writes inst.x as 4 leaving Cls.x as 3

Cette description ne s'applique pas nécessairement aux attributs des descripteurs,


telles que les propriétés créées avec property().
 Si la cible est une sélection : l'expression primaire de la référence est évaluée.
Elle doit produire soit un objet séquence mutable (telle qu'une liste) ou un objet
tableau de correspondances (tel qu'un dictionnaire). Ensuite, l'expression de la
sélection est évaluée.

Si la primaire est un objet séquence mutable (telle qu'une liste), la sélection doit
produire un entier. S'il est négatif, la longueur de la séquence lui est ajoutée. La
valeur résultante doit être un entier positif ou nul, plus petit que la longueur de la
séquence, et Python demande à la séquence d'assigner l'objet à l'élément se
trouvant à cet indice. Si l'indice est hors limites, une IndexError est levée (une
assignation à une sélection dans une séquence ne peut pas ajouter de nouveaux
éléments à une liste).

Si la primaire est un objet tableau de correspondances (tel qu'un dictionnaire), la


sélection doit être d'un type compatible avec le type des clés ; Python demande alors
au tableau de correspondances de créer un couple clé-valeur qui associe la sélection
à l'objet assigné. Ceci peut remplacer une correspondance déjà existante pour une
clé donnée ou insérer un nouveau couple clé-valeur.

Pour les objets allogènes, la méthode __setitem__() est appelée avec les


arguments appropriés.
 Si la cible est une tranche : l'expression primaire de la référence est évaluée.
Elle doit produire un objet séquence mutable (telle qu'une liste). L'objet assigné doit
être un objet séquence du même type. Ensuite, les expressions de la borne
inférieure et de la borne supérieure sont évaluées, dans la mesure où elles sont
spécifiées (les valeurs par défaut sont zéro et la longueur de la séquence). Les
bornes doivent être des entiers. Si une borne est négative, la longueur de la
séquence lui est ajoutée. Les bornes résultantes sont coupées pour être dans
l'intervalle zéro -- longueur de la séquence, inclus. Finalement, Python demande à
l'objet séquence de remplacer la tranche avec les éléments de la séquence à
assigner. La longueur de la tranche peut être différente de la longueur de la
séquence à assigner, ce qui modifie alors la longueur de la séquence cible, si celle-ci
le permet.
CPython implementation detail: Dans l'implémentation actuelle, la syntaxe pour les
cibles est similaire à celle des expressions. Toute syntaxe invalide est rejetée
pendant la phase de génération de code, ce qui produit des messages d'erreurs
moins détaillés.

Bien que la définition de l'assignation implique que le passage entre le côté gauche
et le côté droit soient « simultanés » (par exemple, a, b = b, a permute les deux
variables), le passage à l'intérieur des collections de variables que l'on assigne
intervient de la gauche vers la droite, ce qui peut entraîner quelques confusions. Par
exemple, le programme suivant affiche [0, 2] :

x = [0, 1]
i = 0
i, x[i] = 1, 2 # i is updated, then x[i] is updated
print(x)
Voir aussi
PEP 3132 -- dépaquetage étendu d'itérable

Spécification de la fonctionnalité *cible.
7.2.1. Les assignations augmentées
Une assignation augmentée est la combinaison, dans une seule instruction, d'une
opération binaire et d'une assignation :
augmented_assignment_stmt ::= augtarget augop (expression_list |
yield_expression)
augtarget ::= identifier | attributeref |
subscription | slicing
augop ::= "+=" | "-=" | "*=" | "@=" | "/=" |
"//=" | "%=" | "**="
| ">>=" | "<<=" | "&=" | "^=" | "|
="

Voir la section Primaires pour la définition des syntaxes des trois derniers symboles.

Une assignation augmentée évalue la cible (qui, au contraire des assignations


normales, ne peut pas être un dépaquetage) et la liste d'expressions, effectue
l'opération binaire (spécifique au type d'assignation) sur les deux opérandes et
assigne le résultat à la cible originale. La cible n'est évaluée qu'une seule fois.

Une assignation augmentée comme x += 1 peut être ré-écrite en x = x + 1 pour


obtenir un effet similaire, mais pas exactement équivalent. Dans la version
augmentée. x n'est évalué qu'une seule fois. Aussi, lorsque c'est possible, l'opération
concrète est effectuée sur place, c'est-à-dire que plutôt que de créer un nouvel objet
et l'assigner à la cible, c'est le vieil objet qui est modifié.

Au contraire des assignations normales, les assignations augmentées évaluent la


partie gauche avant d'évaluer la partie droite. Par
exemple, a[i] += f(x) commence par s'intéresser à a[i], puis Python
évalue f(x), effectue l'addition et, enfin, écrit le résultat dans a[i].

À l'exception de l'assignation de tuples et de cibles multiples dans une seule


instruction, l'assignation effectuée par une assignation augmentée est traitée de la
même manière qu'une assignation normale. De même, à l'exception du
comportement possible sur place, l'opération binaire effectuée par assignation
augmentée est la même que les opérations binaires normales.

Pour les cibles qui sont des références à des attributs, la même mise en garde sur
les attributs de classe et d'instances s'applique que pour les assignations normales.

7.2.2. Les assignations annotées


Une assignation annotée est la combinaison, dans une seule instruction, d'une
annotation de variable ou d'attribut et d'une assignation optionnelle :

annotated_assignment_stmt ::= augtarget ":" expression ["="


expression]
La différence avec une assignation normale (voir Les assignations) est qu'une seule
cible et qu'une seule valeur à droite ne sont autorisées.

Pour des noms simples en tant que cibles d'assignation, dans une portée de classe
ou de module, les annotations sont évaluées et stockées dans un attribut de classe
ou de module spécial, __annotations__, qui est un dictionnaire dont les clés sont
les noms de variables (réécrits si le nom est privé) et les valeurs sont les
annotations. Cet attribut est accessible en écriture et est automatiquement créé au
démarrage de l'exécution du corps de la classe ou du module, si les annotations sont
trouvées statiquement.

Pour les expressions en tant que cibles d'assignations, les annotations sont évaluées
dans la portée de la classe ou du module, mais ne sont pas stockées.

Si le nom est annoté dans la portée d'une fonction, alors ce nom est local à cette
portée. Les annotations ne sont jamais évaluées et stockées dans les portées des
fonctions.

Si la partie droite est présente, une assignation annotée effectue l'assignation en tant
que telle avant d'évaluer les annotations (là où c'est possible). Si la partie droite n'est
pas présente pour une cible d'expression, alors l'interpréteur évalue la cible sauf pour
le dernier appel à __setitem__() ou __setattr__().

Voir aussi
PEP 526 -- Syntaxe pour les annotations de variables

La proposition qui a ajouté la syntaxe pour annoter les types de variables (y compris
les variables de classe et les variables d'instance), au lieu de les exprimer par le
biais de commentaires.
PEP 484 -- Indices de type

La proposition qui a ajouté le module typing pour fournir une syntaxe standard pour


les annotations de type qui peuvent être utilisées dans les outils d'analyse statique et
les EDIs.

7.3. L'instruction assert
Les instructions assert sont une manière pratique d'insérer des tests de débogage
au sein d'un programme :

assert_stmt ::= "assert" expression ["," expression]

La forme la plus simple, assert expression, est équivalente à


if __debug__:
if not expression: raise AssertionError

La forme étendue, assert expression1, expression2, est équivalente à

if __debug__:
if not expression1: raise AssertionError(expression2)

Ces équivalences supposent que __debug__ et AssertionError font référence


aux variables natives ainsi nommées. Dans l'implémentation actuelle, la variable
native __debug__ vaut True dans des circonstances normales, False quand les
optimisations sont demandées (ligne de commande avec l'option -O). Le générateur
de code actuel ne produit aucun code pour une instruction assert quand vous
demandez les optimisations à la compilation. Notez qu'il est superflu d'inclure le code
source dans le message d'erreur pour l'expression qui a échoué : il est affiché dans
la pile d'appels.

Assigner vers __debug__ est illégal. La valeur de cette variable native est


déterminée au moment où l'interpréteur démarre.

7.4. L'instruction pass
pass_stmt ::= "pass"

pass est une opération vide --- quand elle est exécutée, rien ne se passe. Elle est
utile comme bouche-trou lorsqu'une instruction est syntaxiquement requise mais
qu'aucun code ne doit être exécuté. Par exemple :

def f(arg): pass # a function that does nothing (yet)

class C: pass # a class with no methods (yet)

7.5. L'instruction del
del_stmt ::= "del" target_list

La suppression est récursivement définie de la même manière que l'assignation.


Plutôt que de détailler cela de manière approfondie, voici quelques indices.

La suppression d'une liste cible (target_list dans la grammaire ci-dessus) supprime


récursivement chaque cible, de la gauche vers la droite.
La suppression d'un nom détruit le lien entre ce nom dans l'espace des noms locaux,
ou l'espace des noms globaux si ce nom apparaît dans une instruction global dans
le même bloc de code. Si le nom n'est pas lié, une exception NameError est levée.

La suppression d'une référence à un attribut, une sélection ou une tranche est


passée à l'objet primaire concerné : la suppression d'une tranche est en général
équivalente à l'assignation d'une tranche vide du type adéquat (mais ceci est au final
déterminé par l'objet que l'on tranche).

Modifié dans la version 3.2: Auparavant, il était illégal de supprimer un nom dans


l'espace des noms locaux si celui-ci apparaissait comme variable libre dans un bloc
imbriqué.

7.6. L'instruction return
return_stmt ::= "return" [expression_list]

return ne peut être placée qu'à l'intérieur d'une définition de fonction, pas à
l'intérieur d'une définition de classe.

Si une liste d'expressions (expression_list dans la grammaire ci-dessus) est


présente, elle est évaluée, sinon None est utilisée comme valeur par défaut.

return quitte l'appel à la fonction courante avec la liste d'expressions (ou None)


comme valeur de retour.

Quand return fait sortir d'une instruction try avec une clause finally, cette


clause finally est exécutée avant de réellement quitter la fonction.

Dans une fonction générateur, l'instruction return indique que le générateur est


terminé et provoque la levée d'une StopIteration. La valeur de retour (s'il y en a
une) est utilisée comme argument pour construire l'exception StopIteration et
devient l'attribut StopIteration.value.

Dans une fonction générateur asynchrone, une instruction return vide indique que


le générateur asynchrone est terminé et provoque la levée
d'une StopAsyncIteration. Une instruction return non vide est une erreur de
syntaxe dans une fonction générateur asynchrone.

7.7. L'instruction yield
yield_stmt ::= yield_expression
L'instruction yield est sémantiquement équivalente à une expression yield.
L'instruction yield peut être utilisée pour omettre les parenthèses qui seraient
autrement requises dans l'instruction équivalente d'expression yield. Par exemple,
les instructions yield

yield <expr>
yield from <expr>

sont équivalentes aux instructions expressions yield

(yield <expr>)
(yield from <expr>)

Les expressions et les instructions yield sont utilisées seulement dans la définition


des fonctions générateurs et apparaissent uniquement dans le corps de la fonction
générateur. L'utilisation de yield dans la définition d'une fonction est suffisant pour
que cette définition crée une fonction générateur au lieu d'une fonction normale.

Pour tous les détails sur la sémantique de yield, reportez-vous à la


section Expressions yield.

7.8. L'instruction raise
raise_stmt ::= "raise" [expression ["from" expression]]

Si aucune expression n'est présente, raise propage la dernière exception active


dans la portée courante. Si aucune exception n'est active dans la portée courante,
une exception RuntimeError est levée, indiquant que c'est une erreur.

Sinon, raise évalue la première expression en tant qu'objet exception. Ce doit être


une sous-classe ou une instance de BaseException. Si c'est une classe, l'instance
de l'exception est obtenue en instanciant la classe sans argument (au moment
voulu).

Le type de l'exception est la classe de l'instance de l'exception, la value est l'instance


elle-même.

Normalement, un objet trace d'appels est créé automatiquement quand une


exception est levée et il lui est rattaché comme attribut __traceback__, en lecture-
écriture. Vous pouvez créer une exception et définir votre propre trace d'appels d'un
seul coup en utilisant la méthode des exceptions with_traceback() (qui renvoie la
même instance d'exception avec sa trace d'appels passée en argument), comme
ceci :
raise Exception("foo occurred").with_traceback(tracebackobj)

La clause from est utilisée pour chaîner les exceptions : si vous la fournissez, la


seconde « expression » doit être une autre classe ou instance d'exception, qui est
rattachée à l'exception levée en tant qu'attribut __cause__ (en lecture-écriture). Si
l'exception levée n'est pas gérée, les deux exceptions sont affichées :

>>>

>>> try:
... print(1 / 0)
... except Exception as exc:
... raise RuntimeError("Something bad happened") from exc
...
Traceback (most recent call last):
File "<stdin>", line 2, in <module>
ZeroDivisionError: division by zero

The above exception was the direct cause of the following


exception:

Traceback (most recent call last):


File "<stdin>", line 4, in <module>
RuntimeError: Something bad happened

Un mécanisme similaire est mis en œuvre implicitement si une exception est levée à
l'intérieur d'un gestionnaire d'exception ou d'une clause finally : la première
exception est rattachée à l'attribut __context__ de la nouvelle exception :

>>>

>>> try:
... print(1 / 0)
... except:
... raise RuntimeError("Something bad happened")
...
Traceback (most recent call last):
File "<stdin>", line 2, in <module>
ZeroDivisionError: division by zero

During handling of the above exception, another exception


occurred:

Traceback (most recent call last):


File "<stdin>", line 4, in <module>
RuntimeError: Something bad happened
Le chaînage d'exceptions peut être explicitement supprimé en spécifiant None dans
la clause from :

>>>

>>> try:
... print(1 / 0)
... except:
... raise RuntimeError("Something bad happened") from None
...
Traceback (most recent call last):
File "<stdin>", line 4, in <module>
RuntimeError: Something bad happened

Des informations complémentaires sur les exceptions sont disponibles dans la


section Exceptions et sur la gestion des exceptions dans la section L'instruction try.

Modifié dans la version 3.3:  None est dorénavant autorisée en tant


que Y dans raise X from Y.

Nouveau dans la version 3.3: L'attribut __suppress_context__ pour supprimer


l'affichage automatique du contexte de l'exception.

7.9. L'instruction break
break_stmt ::= "break"

Une instruction break ne peut apparaître qu'à l'intérieur d'une boucle for ou while,


mais pas dans une définition de fonction ou de classe à l'intérieur de cette boucle.

Elle termine la boucle la plus imbriquée, shuntant l'éventuelle clause else de la


boucle.

Si une boucle for est terminée par un break, la cible qui contrôle la boucle garde sa
valeur.

Quand break passe le contrôle en dehors d'une instruction try qui comporte une


clause finally, cette clause finally est exécutée avant de quitter la boucle.

7.10. L'instruction continue
continue_stmt ::= "continue"

L'instruction continue ne peut apparaître qu'à l'intérieur d'une


boucle for ou while, mais pas dans une définition de fonction ou de classe ni dans
une clause finally, à l'intérieur de cette boucle. Elle fait continuer le flot
d'exécution au prochain cycle de la boucle la plus imbriquée.

Quand continue passe le contrôle en dehors d'une instruction try qui comporte


une clause finally, cette clause finally est exécutée avant de commencer le
cycle suivant de la boucle.

7.11. L'instruction import
import_stmt ::= "import" module ["as" identifier] ("," module
["as" identifier])*
| "from" relative_module "import" identifier
["as" identifier]
("," identifier ["as" identifier])*
| "from" relative_module "import" "("
identifier ["as" identifier]
("," identifier ["as" identifier])* [","] ")"
| "from" module "import" "*"
module ::= (identifier ".")* identifier
relative_module ::= "."* module | "."+

L'instruction de base import (sans clause from) est exécutée en deux étapes :

1. trouve un module, le charge et l'initialise si nécessaire


2. définit un ou des noms (name dans la grammaire ci-dessus) dans l'espace
des noms locaux de la portée où l'instruction import apparaît.

Quand l'instruction contient plusieurs clauses (séparées par des virgules), les deux
étapes sont menées séparément pour chaque clause, comme si les clauses étaient
séparées dans des instructions d'importations individuelles.

Les détails de la première étape, de recherche et de chargement des modules sont


décrits largement dans la section relative au système d'importation, qui décrit
également les différents types de paquets et modules qui peuvent être importés, de
même que les points d'entrée pouvant être utilisés pour personnaliser le système
d'importation. Notez que des erreurs dans cette étape peuvent indiquer soit que le
module n'a pas été trouvé, soit qu'une erreur s'est produite lors de l'initialisation du
module, ce qui comprend l'exécution du code du module.

Si le module requis est bien récupéré, il est mis à disposition de l'espace de


nommage local suivant l'une des trois façons suivantes :

 Si le nom du module est suivi par as, alors le nom suivant as est directement


lié au module importé.
 si aucun autre nom n'est spécifié et que le module en cours d'importation est
un module de niveau le plus haut, le nom du module est lié dans l'espace des noms
locaux au module importé ;
 si le module en cours d'importation n'est pas un module de plus haut niveau,
alors le nom du paquet de plus haut niveau qui contient ce module est lié dans
l'espace des noms locaux au paquet de plus haut niveau. Vous pouvez accéder au
module importé en utilisant son nom pleinement qualifié et non directement.

La forme from utilise un processus un peu plus complexe :

1. trouve le module spécifié dans la clause from, le charge et l'initialise si


nécessaire ;
2. pour chaque nom spécifié dans les clauses import :

1. vérifie si le module importé possède un attribut avec ce nom ;


2. si non, essaie d'importer un sous-module avec ce nom puis vérifie si le
module importé possède lui-même cet attribut ;
3. si l'attribut n'est pas trouvé, une ImportError est levée.
4. sinon, une référence à cette valeur est stockée dans l'espace des noms
locaux, en utilisant le nom de la clause as si elle est présente, sinon en utilisant le
nom de l'attribut.

Exemples :

import foo # foo imported and bound locally


import foo.bar.baz # foo.bar.baz imported, foo bound
locally
import foo.bar.baz as fbb # foo.bar.baz imported and bound as
fbb
from foo.bar import baz # foo.bar.baz imported and bound as
baz
from foo import attr # foo imported and foo.attr bound as
attr

Si la liste des noms est remplacée par une étoile ( '*'), tous les noms publics définis
dans le module sont liés dans l'espace des noms locaux de la portée où apparaît
l'instruction import.

Les noms publics définis par un module sont déterminés en cherchant dans l'espace


de nommage du module une variable nommée __all__ ; Si elle est définie, elle doit
être une séquence de chaînes désignant les noms définis ou importés par ce
module. Les noms donnés dans __all__ sont tous considérés publics et doivent
exister. Si __all__ n'est pas définie, l'ensemble des noms publics contient tous les
noms trouvés dans l'espace des noms du module qui ne commencent pas par un
caractère souligné (_). __all__ doit contenir toute l'API publique. Elle est destinée à
éviter l'exportation accidentelle d'éléments qui ne font pas partie de l'API (tels que
des modules de bibliothèques qui ont été importés et utilisés à l'intérieur du module).

La forme d'import avec astérisque --- from module import * --- est autorisée


seulement au niveau du module. Si vous essayez de l'utiliser dans une définition de
classe ou de fonction, cela lève une SyntaxError.

Quand vous spécifiez les modules à importer, vous n'avez pas besoin de spécifier
les noms absolus des modules. Quand un module ou un paquet est contenu dans un
autre paquet, il est possible d'effectuer une importation relative à l'intérieur du même
paquet de plus haut niveau sans avoir à mentionner le nom du paquet. En utilisant
des points en entête du module ou du paquet spécifié après from, vous pouvez
spécifier combien de niveaux vous souhaitez remonter dans la hiérarchie du paquet
courant sans spécifier de nom exact. Un seul point en tête signifie le paquet courant
où se situe le module qui effectue l'importation. Deux points signifient de remonter
d'un niveau. Trois points, remonter de deux niveaux et ainsi de suite. Ainsi, si vous
exécutez from . import mod dans un module du paquet pkg, vous importez
finalement pkg.mod. Et si vous
exécutez from ..souspkg2 import mod depuis pkg.souspkg1, vous importez
finalement pkg.souspkg2.mod. La spécification des importations relatives se situe
dans la section Importations relatives au paquet.

importlib.import_module() est fournie pour gérer les applications qui


déterminent dynamiquement les modules à charger.

7.11.1. L'instruction future
Une instruction future est une directive à l'attention du compilateur afin qu'un module
particulier soit compilé en utilisant une syntaxe ou une sémantique qui sera
disponible dans une future version de Python où cette fonctionnalité est devenue un
standard.

L'instruction future a vocation à faciliter les migrations vers les futures versions de


Python qui introduisent des changements incompatibles au langage. Cela permet
l'utilisation de nouvelles fonctionnalités module par module avant qu'une version
n'officialise cette fonctionnalité comme un standard.

future_stmt ::= "from" "__future__" "import" feature ["as"


identifier]
("," feature ["as" identifier])*
| "from" "__future__" "import" "(" feature ["as"
identifier]
("," feature ["as" identifier])* [","] ")"
feature ::= identifier

Une instruction future doit apparaître en haut du module. Les seules lignes


autorisées avant une instruction future sont :

 la chaîne de documentation du module (si elle existe),


 des commentaires,
 des lignes vides et
 d'autres instructions future.

La seule fonctionnalité dans Python 3.7 qui nécessite l'utilisation de


l'instruction future est annotations.

Toutes les fonctionnalités (feature dans la grammaire ci-dessus) autorisées par


l'instruction future sont toujours reconnues par Python 3. Cette liste
comprend absolute_import, division, generators, generator_stop, unicod
e_literals, print_function, nested_scopes et with_statement. Elles sont
toutes redondantes car elles sont de toute manière activées ; elles ne sont
conservées que par souci de compatibilité descendante.

Une instruction future est reconnue et traitée spécialement au moment de la


compilation : les modifications à la sémantique des constructions de base sont
souvent implémentées en générant un code différent. Il peut même arriver qu'une
nouvelle fonctionnalité ait une syntaxe incompatible (tel qu'un nouveau mot réservé) ;
dans ce cas, le compilateur a besoin d'analyser le module de manière différente. De
telles décisions ne peuvent pas être différées au moment de l'exécution.

Pour une version donnée, le compilateur sait quelles fonctionnalités ont été définies
et lève une erreur à la compilation si une instruction future contient une fonctionnalité
qui lui est inconnue.

La sémantique à l'exécution est la même que pour toute autre instruction


d'importation : il existe un module standard __future__, décrit plus loin, qui est
importé comme les autres au moment où l'instruction future est exécutée.

La sémantique particulière à l'exécution dépend des fonctionnalités apportées par


l'instruction future.

Notez que l'instruction suivante est tout à fait normale :


import __future__ [as name]

Ce n'est pas une instruction future ; c'est une instruction d'importation ordinaire qui
n'a aucune sémantique particulière ou restriction de syntaxe.

Le code compilé par des appels aux fonctions natives exec() et compile() dans


un module M comportant une instruction future utilise, par défaut, la nouvelle syntaxe
ou sémantique associée à l'instruction future. Ceci peut être contrôle par des
arguments optionnels à compile() — voir la documentation de cette fonction pour
les détails.

Une instruction future entrée à l'invite de l'interpréteur interactif est effective pour le


reste de la session de l'interpréteur. Si l'interpréteur est démarré avec l'option -i,
qu'un nom de script est passé pour être exécuté et que ce script contient une
instruction future, elle est effective pour la session interactive qui démarre après
l'exécution du script.

Voir aussi
PEP 236 — retour vers le __future__

La proposition originale pour le mécanisme de __future__.

7.12. L'instruction global
global_stmt ::= "global" identifier ("," identifier)*

L'instruction global est une déclaration qui couvre l'ensemble du bloc de code


courant. Elle signifie que les noms (identifier dans la grammaire ci-dessus) listés
doivent être interprétés comme globaux. Il est impossible d'assigner une variable
globale sans global, mais rappelez-vous que les variables libres peuvent faire
référence à des variables globales sans avoir été déclarées en tant que telles.

Les noms listés dans l'instruction global ne doivent pas être utilisés, dans le même
bloc de code, avant l'instruction global.

Les noms listés dans l'instruction global ne doivent pas être définis en tant que
paramètre formel, cible d'une boucle for, dans une définition de class, de fonction,
d'instruction import ou une annotation de variable.

CPython implementation detail: L'implémentation actuelle ne vérifie pas toutes ces


interdictions mais n'abusez pas de cette liberté car les implémentations futures
pourraient faire la vérification ou modifier le comportement du programme sans vous
avertir.
Note pour les programmeurs : global est une directive à l'attention de l'analyseur
syntaxique. Elle s'applique uniquement au code analysé en même temps que
l'instruction global. En particulier, une instruction global contenue dans une
chaîne ou un objet code fourni à la fonction native exec() n'affecte pas le
code contenant cet appel et le code contenu dans un telle chaîne n'est pas affecté
par une instruction global placée dans le code contenant l'appel. Il en est de même
pour les fonctions eval() et compile().

7.13. L'instruction nonlocal
nonlocal_stmt ::= "nonlocal" identifier ("," identifier)*

L'instruction nonlocal fait que les noms listés font référence aux variables liées
précédemment, dans la portée la plus petite entourant l'instruction, à l'exception des
variables globales. C'est important car le comportement par défaut pour les liaisons
consiste à chercher d'abord dans l'espace des noms locaux. Cette instruction permet
à du code encapsulé de se lier à des variables en dehors de la portée locale du code
mais sans avoir de portée globale (c'est-à-dire de niveau module).

Les noms (identifier dans la grammaire ci-dessus) listés dans l'instruction nonlocal,


au contraire de ceux listés dans une instruction global, doivent faire référence à
des liaisons pré-existantes dans les portées englobantes (en effet, la portée dans
laquelle devrait être créée la liaison ne peut pas être déterminée a priori).

Les noms listés dans l'instruction nonlocal ne doivent entrer en collision avec des
liaisons déjà établies dans la portée locale.

Voir aussi
PEP 3104 -- Accès à des noms en dehors de la portée locale

Les spécifications pour l'instruction nonlocal.

8. Instructions composées
Les instructions composées contiennent d'autres (groupes d’) instructions ; elles
affectent ou contrôlent l'exécution de ces autres instructions d'une manière ou d'une
autre. En général, une instruction composée couvre plusieurs lignes bien que, dans
sa forme la plus simple, une instruction composée peut tenir sur une seule ligne.
Les instructions if, while et for implémentent les constructions classiques de
contrôle de flux. try spécifie des gestionnaires d'exception et du code de nettoyage
pour un groupe d'instructions, tandis que l'instruction with permet l'exécution de
code d'initialisation et de finalisation autour d'un bloc de code. Les définitions de
fonctions et de classes sont également, au sens syntaxique, des instructions
composées.

Une instruction composée comporte une ou plusieurs « clauses ». Une clause se


compose d'un en-tête et d'une « suite ». Les en-têtes des clauses d'une instruction
composée particulière sont toutes placées au même niveau d'indentation. Chaque
en-tête de clause commence par un mot-clé spécifique et se termine par le caractère
deux-points (:) ; une suite est un groupe d'instructions contrôlées par une clause ;
une suite se compose, après les deux points de l'en-tête, soit d'une ou plusieurs
instructions simples séparées par des points-virgules si elles sont sur la même ligne
que l'en-tête, soit d'une ou plusieurs instructions en retrait sur les lignes suivantes.
Seule cette dernière forme d'une suite peut contenir des instructions composées ; ce
qui suit n'est pas licite, principalement parce qu'il ne serait pas clair de savoir à quelle
clause if se rapporterait une clause else placée en fin de ligne :

if test1: if test2: print(x)

Notez également que le point-virgule se lie plus étroitement que le deux-points dans
ce contexte, de sorte que dans l'exemple suivant, soit tous les appels print() sont
exécutés, soit aucun ne l'est :

if x < y < z: print(x); print(y); print(z)

En résumé :

compound_stmt ::= if_stmt


| while_stmt
| for_stmt
| try_stmt
| with_stmt
| funcdef
| classdef
| async_with_stmt
| async_for_stmt
| async_funcdef
suite ::= stmt_list NEWLINE | NEWLINE INDENT statement+
DEDENT
statement ::= stmt_list NEWLINE | compound_stmt
stmt_list ::= simple_stmt (";" simple_stmt)* [";"]
Notez que ces instructions se terminent toujours par un lexème NEWLINE suivi
éventuellement d'un DEDENT. Notez également que les clauses facultatives qui
suivent commencent toujours par un mot-clé qui ne peut pas commencer une
instruction. Ainsi, il n'y a pas d'ambiguïté (le problème du else dont on ne sait pas à
quel if il est relié est résolu en Python en exigeant que des
instructions if imbriquées soient indentées les unes par rapport aux autres).

L'agencement des règles de grammaire dans les sections qui suivent place chaque
clause sur une ligne séparée pour plus de clarté.

8.1. L'instruction if
L'instruction if est utilisée pour exécuter des instructions en fonction d'une
condition :

if_stmt ::= "if" expression ":" suite


("elif" expression ":" suite)*
["else" ":" suite]

Elle sélectionne exactement une des suites en évaluant les expressions une par une
jusqu'à ce qu'une soit vraie (voir la section Opérations booléennes pour la définition
de vrai et faux) ; ensuite cette suite est exécutée (et aucune autre partie de
l'instruction if n'est exécutée ou évaluée). Si toutes les expressions sont fausses, la
suite de la clause else, si elle existe, est exécutée.

8.2. L'instruction while
L'instruction while est utilisée pour exécuter des instructions de manière répétée
tant qu'une expression est vraie :

while_stmt ::= "while" expression ":" suite


["else" ":" suite]

Python évalue l'expression de manière répétée et, tant qu'elle est vraie, exécute la
première suite ; si l'expression est fausse (ce qui peut arriver même lors du premier
test), la suite de la clause else, si elle existe, est exécutée et la boucle se termine.

Une instruction break exécutée dans la première suite termine la boucle sans


exécuter la suite de la clause else. Une instruction continue exécutée dans la
première suite saute le reste de la suite et retourne au test de l'expression.
8.3. L'instruction for
L'instruction for est utilisée pour itérer sur les éléments d'une séquence (par
exemple une chaîne, un tuple ou une liste) ou un autre objet itérable :

for_stmt ::= "for" target_list "in" expression_list ":" suite


["else" ":" suite]

La liste des expressions (expression_list dans la grammaire ci-dessus) est évaluée


une seule fois ; elle doit produire un objet itérable. Un itérateur est créé pour le
résultat de cette liste d'expression. La suite est ensuite exécutée une fois pour
chaque élément fourni par l'itérateur, dans l'ordre renvoyé par l'itérateur. Chaque
élément est assigné, à tour de rôle, à la liste cible (target_list dans la grammaire ci-
dessus) en utilisant les règles des assignations (voir Les assignations), et ensuite la
suite est exécutée. Lorsque les éléments sont épuisés (ce qui est immédiat lorsque
la séquence est vide ou si un itérateur lève une exception StopIteration), la suite
de la clause else, si elle existe, est exécutée et la boucle se termine.

Une instruction break exécutée dans la première suite termine la boucle sans


exécuter la suite de la clause else. Une instruction continue exécutée dans la
première suite saute le reste de la suite et continue avec l'élément suivant, ou avec
la clause else s'il n'y a pas d'élément suivant.

La boucle for effectue des affectations aux variables de la liste cible, ce qui écrase


toutes les affectations antérieures de ces variables, y compris celles effectuées dans
la suite de la boucle for :

for i in range(10):
print(i)
i = 5 # this will not affect the for-loop
# because i will be overwritten with the
next
# index in the range

Les noms dans la liste cible ne sont pas supprimés lorsque la boucle est terminée
mais, si la séquence est vide, ils n'auront pas du tout été assignés par la boucle.
Petite astuce : la fonction native range() renvoie un itérateur sur des entiers
approprié pour émuler la boucle classique en Pascal sur des
entiers for i := a to b do ; par exemple, list(range(3)) renvoie la
liste [0, 1, 2].

Note
 

Il y a une subtilité lorsque la séquence est modifiée par la boucle (cela ne peut se
produire que pour les séquences mutables, c'est-à-dire les listes). Un compteur
interne est utilisé pour savoir quel est l'élément suivant, et ce compteur est
incrémenté à chaque itération. Lorsqu'il a atteint la longueur de la séquence, la
boucle se termine. Cela signifie que si la suite supprime l'élément courant (ou un
élément précédent) de la séquence, l'élément suivant est sauté (puisqu'il reçoit
l'indice de l'élément courant qui a déjà été traité). De même, si la suite insère un
élément avant l'élément courant, l'élément courant est traité une deuxième fois à la
prochaine itération. Ceci peut conduire à de méchants bugs, que vous pouvez éviter
en effectuant une copie temporaire d'une tranche ou de la séquence complète, par
exemple
for x in a[:]:
if x < 0: a.remove(x)

8.4. L'instruction try
L'instruction try spécifie les gestionnaires d'exception ou le code de nettoyage pour
un groupe d'instructions :

try_stmt ::= try1_stmt | try2_stmt


try1_stmt ::= "try" ":" suite
("except" [expression ["as" identifier]] ":" suite)
+
["else" ":" suite]
["finally" ":" suite]
try2_stmt ::= "try" ":" suite
"finally" ":" suite

La ou les clauses except spécifient un ou plusieurs gestionnaires d'exceptions. Si


aucune exception ne se produit dans la clause try, aucun gestionnaire d'exception
n'est exécuté. Lorsqu'une exception se produit dans la suite de try, Python
recherche un gestionnaire d'exception. Cette recherche inspecte les clauses except,
l'une après l'autre, jusqu'à trouver une correspondance. Une clause except vide
(c'est-à-dire sans expression), si elle est présente, doit être la dernière ; elle
correspond à toute exception. Pour une clause except avec une expression, cette
expression est évaluée et la clause correspond si l'objet résultant est « compatible »
avec l'exception. Un objet est réputé compatible avec une exception s'il est la classe
ou une classe de base de l'objet exception ou si c'est un tuple contenant un élément
qui est compatible avec l'exception.
Si aucune clause except ne correspond à l'exception, la recherche d'un gestionnaire
d'exception se poursuit dans le code englobant et dans la pile d'appels. 1

Si l'évaluation d'une expression dans l'en-tête d'une clause except lève une


exception, la recherche initiale d'un gestionnaire est annulée et une recherche
commence pour la nouvelle exception dans le code englobant et dans la pile
d'appels (c'est traité comme si l'instruction try avait levé l'exception).

Lorsqu'une clause d'exception correspond, l'exception est assignée à la cible


spécifiée après le mot-clé as dans cette clause except, si cette cible existe, et la
suite de clause except est exécutée. Toutes les clauses except doivent avoir un
bloc exécutable. Lorsque la fin de ce bloc est atteinte, l'exécution continue
normalement après l'ensemble de l'instruction try (cela signifie que si deux
gestionnaires imbriqués existent pour la même exception, et que l'exception se
produit dans la clause try du gestionnaire interne, le gestionnaire externe ne gère
pas l'exception).

Lorsqu'une exception a été assignée en utilisant as cible, elle est effacée à la fin


de la clause except. C'est comme si

except E as N:
foo

avait été traduit en

except E as N:
try:
foo
finally:
del N

Cela veut dire que l'exception doit être assignée à un nom différent pour pouvoir s'y
référer après la clause except. Les exceptions sont effacées parce qu'avec la trace
de la pile d'appels qui leur est attachée, elles créent un cycle dans les pointeurs de
références (avec le cadre de la pile), ce qui conduit à conserver tous les noms locaux
de ce cadre en mémoire jusqu'au passage du ramasse-miettes.

Avant l'exécution de la suite d'une clause except, les détails de l'exception sont


stockés dans le module sys et sont
accessibles via sys.exc_info(). sys.exc_info() renvoie un triplet composé de
la classe de l'exception, de l'instance d'exception et d'un objet trace (voir la
section Hiérarchie des types standards) identifiant le point du programme où
l'exception est survenue. Les valeurs de sys.exc_info() sont remises à leurs
anciennes valeurs (celles d'avant l'appel) au retour d'une fonction qui a géré une
exception.

La clause optionnelle else n'est exécutée que si l'exécution atteint la fin de la


clause try, aucune exception n'a été levée, et aucun return, continue,
ou break ont étés exécutés. Les exceptions dans la clause else ne sont pas gérées
par les clauses except précédentes.

Si finally est présente, elle spécifie un gestionnaire de "nettoyage". La


clause try est exécutée, y compris les clauses except et else. Si une exception se
produit dans l'une des clauses et n'est pas traitée, l'exception est temporairement
sauvegardée. La clause finally est exécutée. S'il y a une exception sauvegardée,
elle est levée à nouveau à la fin de la clause finally. Si la clause finally lève
une autre exception, l'exception sauvegardée est définie comme le contexte de la
nouvelle exception. Si la clause finally exécute une instruction return ou break,
l'exception sauvegardée est jetée :

>>>

>>> def f():


... try:
... 1/0
... finally:
... return 42
...
>>> f()
42

L'information relative à l'exception n'est pas disponible pour le programme pendant


l'exécution de la clause finally.

Lorsqu'une instruction return, break ou continue est exécutée dans la suite d'une


instruction try d'une construction try...finally, la clause finally est aussi
exécutée à la sortie. Une instruction continue est illégale dans une
clause finally (la raison est que l'implémentation actuelle pose problème --- il est
possible que cette restriction soit levée dans le futur).

La valeur de retour d'une fonction est déterminée par la dernière


instruction return exécutée. Puisque la clause finally s'exécute toujours, une
instruction return exécutée dans le finally sera toujours la dernière clause
exécutée :

>>>
>>> def foo():
... try:
... return 'try'
... finally:
... return 'finally'
...
>>> foo()
'finally'

Vous trouvez des informations supplémentaires relatives aux exceptions dans la


section Exceptions et, dans la section L'instruction raise, des informations relatives à
l'utilisation de l'instruction raise pour produire des exceptions.

8.5. L'instruction with
L'instruction with est utilisée pour encapsuler l'exécution d'un bloc avec des
méthodes définies par un gestionnaire de contexte (voir la section Gestionnaire de
contexte With). Cela permet d'utiliser de manière simple le patron de conception
classique try…except…finally.

with_stmt ::= "with" with_item ("," with_item)* ":" suite


with_item ::= expression ["as" target]

L'exécution de l'instruction with avec un seul « élément » (item dans la grammaire)


se déroule comme suit :

1. L'expression de contexte (l'expression donnée dans le with_item) est


évaluée pour obtenir un gestionnaire de contexte.
2. La méthode __exit__() du gestionnaire de contexte est chargée pour une
utilisation ultérieure.
3. La méthode __enter__() du gestionnaire de contexte est invoquée.
4. Si une cible (target dans la grammaire ci-dessus) a été incluse dans
l'instruction with, la valeur de retour de __enter__() lui est assignée.

Note

L'instruction with garantit que si la méthode __enter__() se termine sans erreur,


alors la méthode __exit__() est toujours appelée. Ainsi, si une erreur se produit
pendant l'assignation à la liste cible, elle est traitée de la même façon qu'une erreur
se produisant dans la suite. Voir l'étape 6 ci-dessous.
5. La suite est exécutée.
6. La méthode __exit__() du gestionnaire de contexte est invoquée. Si une
exception a causé la sortie de la suite, son type, sa valeur et sa pile d'appels sont
passés en arguments à __exit__(). Sinon, trois arguments None sont fournis.

Si l'on est sorti de la suite en raison d'une exception et que la valeur de retour de la
méthode __exit__() était fausse, l'exception est levée à nouveau. Si la valeur de
retour était vraie, l'exception est supprimée et l'exécution continue avec l'instruction
qui suit l'instruction with.

Si l'on est sorti de la suite pour une raison autre qu'une exception, la valeur de retour
de __exit__() est ignorée et l'exécution se poursuit à l'endroit normal pour le type
de sortie prise.

Avec plus d'un élément, les gestionnaires de contexte sont traités comme si
plusieurs instructions with étaient imbriquées :

with A() as a, B() as b:


suite

est équivalente à

with A() as a:
with B() as b:
suite

Modifié dans la version 3.1: Prise en charge de multiples expressions de contexte.

Voir aussi
PEP 343 — L'instruction « with »

La spécification, les motivations et des exemples de l'instruction with en Python.

8.6. Définition de fonctions
Une définition de fonction définit un objet fonction allogène (voir la section Hiérarchie
des types standards) :

funcdef ::= [decorators] "def" funcname "("


[parameter_list] ")"
["->" expression] ":" suite
decorators ::= decorator+
decorator ::= "@" dotted_name ["(" [argument_list
[","]] ")"] NEWLINE
dotted_name ::= identifier ("." identifier)*
parameter_list ::= defparameter ("," defparameter)* [","
[parameter_list_starargs]]
| parameter_list_starargs
parameter_list_starargs ::= "*" [parameter] ("," defparameter)*
["," ["**" parameter [","]]]
| "**" parameter [","]
parameter ::= identifier [":" expression]
defparameter ::= parameter ["=" expression]
funcname ::= identifier

Une définition de fonction est une instruction qui est exécutée. Son exécution lie le
nom de la fonction, dans l'espace de nommage local courant, à un objet fonction (un
objet qui encapsule le code exécutable de la fonction). Cet objet fonction contient
une référence à l'espace des noms globaux courant comme espace des noms
globaux à utiliser lorsque la fonction est appelée.

La définition de la fonction n'exécute pas le corps de la fonction ; elle n'est exécutée


que lorsque la fonction est appelée. 2

Une définition de fonction peut être encapsulée dans une ou plusieurs


expressions decorator ; les décorateurs sont évalués lorsque la fonction est définie,
dans la portée qui contient la définition de fonction ; le résultat doit être un appelable,
qui est invoqué avec l'objet fonction comme seul argument ; la valeur renvoyée est
liée au nom de la fonction en lieu et place de l'objet fonction. Lorsqu'il y a plusieurs
décorateurs, ils sont appliqués par imbrication ; par exemple, le code suivant

@f1(arg)
@f2
def func(): pass

est à peu près équivalent à

def func(): pass


func = f1(arg)(f2(func))

sauf que la fonction originale n'est pas temporairement liée au nom func.

Lorsqu'un ou plusieurs paramètres sont de la forme parameter = expression, on dit


que la fonction a des « valeurs de paramètres par défaut ». Pour un paramètre avec
une valeur par défaut, l’argument correspondant peut être omis lors de l'appel, la
valeur par défaut du paramètre est alors utilisée. Si un paramètre a une valeur par
défaut, tous les paramètres suivants jusqu'à " *" doivent aussi avoir une valeur par
défaut — ceci est une restriction syntaxique qui n'est pas exprimée dans la
grammaire.

Les valeurs par défaut des paramètres sont évaluées de la gauche vers la
droite quand la définition de la fonction est exécutée. Cela signifie que
l'expression est évaluée une fois, lorsque la fonction est définie, et que c'est la même
valeur « pré-calculée » qui est utilisée à chaque appel. C'est particulièrement
important à comprendre lorsqu'un paramètre par défaut est un objet mutable, tel
qu'une liste ou un dictionnaire : si la fonction modifie l'objet (par exemple en ajoutant
un élément à une liste), la valeur par défaut est modifiée. En général, ce n'est pas
l'effet voulu. Une façon d'éviter cet écueil est d'utiliser None par défaut et de tester
explicitement la valeur dans le corps de la fonction. Par exemple :

def whats_on_the_telly(penguin=None):
if penguin is None:
penguin = []
penguin.append("property of the zoo")
return penguin

La sémantique de l'appel de fonction est décrite plus en détail dans la


section Appels. Un appel de fonction assigne toujours des valeurs à tous les
paramètres mentionnés dans la liste des paramètres, soit à partir d'arguments
positionnels, d'arguments par mots-clés ou de valeurs par défaut. S'il y a un
paramètre de la forme "*identifier", il est initialisé à un tuple recevant les
paramètres positionnels en surplus, la valeur par défaut étant le tuple vide. S'il y a un
paramètre de la forme "**identifier", il est initialisé à un nouveau tableau
associatif ordonné qui récupère tous les arguments par mot-clé en surplus, la valeur
par défaut étant un tableau associatif vide. Les paramètres après " *" ou
"*identifier" sont forcément des paramètres par mot-clé et ne peuvent être
passés qu'en utilisant des arguments par mot-clé.

Les paramètres peuvent avoir une annotation sous la forme ": expression" après


le nom du paramètre. Tout paramètre peut avoir une annotation, même ceux de la
forme *identifier ou **identifier. Les fonctions peuvent avoir une annotation
pour la valeur de retour, sous la forme " -> expression" après la liste des
paramètres. Ces annotations peuvent prendre la forme de toute expression Python
valide. Leur présence ne change pas la sémantique de la fonction. Les valeurs des
annotations sont accessibles comme valeurs d'un dictionnaire dont les clés sont les
noms des paramètres et défini comme attribut __annotations__ de l'objet fonction.
Si annotations est importé de __future__, les annotations sont conservées sous
la forme de chaînes de caractères, permettant leur évaluation différée. Autrement,
elles sont interprétées en même temps que la déclaration des fonctions. Dans le
premier cas, les annotations peuvent être interprétées dans un ordre différent de
l'ordre dans lequel elles apparaissent dans le fichier.

Il est aussi possible de créer des fonctions anonymes (fonctions non liées à un nom),
pour une utilisation immédiate dans des expressions. Utilisez alors des expressions
lambda, décrites dans la section Expressions lambda. Notez qu'une expression
lambda est simplement un raccourci pour définir une fonction simple ; une fonction
définie par une instruction " def" peut être passée (en argument) ou assignée à un
autre nom, tout comme une fonction définie par une expression lambda. La forme
"def" est en fait plus puissante puisqu'elle permet l'exécution de plusieurs
instructions et les annotations.

Note pour les programmeurs : les fonctions sont des objets de première classe.
Une instruction "def" exécutée à l'intérieur d'une définition de fonction définit une
fonction locale qui peut être renvoyée ou passée en tant qu'argument. Les variables
libres utilisées dans la fonction imbriquée ont accès aux variables locales de la
fonction contenant le "def". Voir la section Noms et liaisons pour plus de détails.

Voir aussi
PEP 3107 — Annotations de fonctions

La spécification originale pour les annotations de fonctions.


PEP 484 — Indications de types

Définition de la signification standard pour les annotations : indications de types.


PEP 526 — Syntaxe pour les annotations de variables

Capacité d'indiquer des types pour les déclarations de variables, y compris les
variables de classes et les variables d'instances
PEP 563 — Évaluation différée des annotations

Gestion des références postérieures à l'intérieur des annotations en préservant les


annotations sous forme de chaînes à l'exécution au lieu d'une évaluation directe.

8.7. Définition de classes
Une définition de classe définit un objet classe (voir la section Hiérarchie des types
standards) :

classdef ::= [decorators] "class" classname [inheritance] ":"


suite
inheritance ::= "(" [argument_list] ")"
classname ::= identifier
Une définition de classe est une instruction qui est exécutée. La liste d'héritage
(inheritance entre crochets dans la grammaire ci-dessus) donne habituellement une
liste de classes de base (voir Méta-classes pour des utilisations plus avancées).
Donc chaque élément de la liste doit pouvoir être évalué comme un objet classe qui
autorise les sous-classes. Les classes sans liste d'héritage héritent, par défaut, de la
classe de base object ; d'où

class Foo:
pass

est équivalente à

class Foo(object):
pass

La suite de la classe est ensuite exécutée dans un nouveau cadre d'exécution


(voir Noms et liaisons), en utilisant un espace de nommage local nouvellement créé
et l'espace de nommage global d'origine (habituellement, la suite contient
principalement des définitions de fonctions). Lorsque la suite de la classe termine
son exécution, son cadre d'exécution est abandonné mais son espace des noms
locaux est sauvegardé 3. Un objet classe est alors créé en utilisant la liste d'héritage
pour les classes de base et l'espace de nommage sauvegardé comme dictionnaire
des attributs. Le nom de classe est lié à l'objet classe dans l'espace de nommage
local original.

L'ordre dans lequel les attributs sont définis dans le corps de la classe est préservé
dans le __dict__ de la nouvelle classe. Notez que ceci n'est fiable que juste après
la création de la classe et seulement pour les classes qui ont été définies en utilisant
la syntaxe de définition.

La création de classes peut être fortement personnalisée en utilisant


les métaclasses.

Les classes peuvent aussi être décorées : comme pour les décorateurs de fonctions,

@f1(arg)
@f2
class Foo: pass

est à peu près équivalent à

class Foo: pass


Foo = f1(arg)(f2(Foo))

Les règles d'évaluation pour les expressions de décorateurs sont les mêmes que
pour les décorateurs de fonctions. Le résultat est alors lié au nom de la classe.

Note pour les programmeurs : les variables définies dans la définition de classe


sont des attributs de classe ; elles sont partagées par les instances. Les attributs
d'instance peuvent être définis dans une méthode en utilisant self.name = value.
Les attributs de classe et d'instance sont accessibles par la notation " self.name", et
un attribut d'instance masque un attribut de classe de même nom lorsqu'on y accède
de cette façon. Les attributs de classe peuvent être utilisés comme valeurs par
défaut pour les attributs d'instances, mais l'utilisation de valeurs mutables peut
conduire à des résultats inattendus. Les descripteurs peuvent être utilisés pour créer
des variables d'instances avec des détails d'implémentation différents.

Voir aussi
PEP 3115 — Métaclasses dans Python 3000

La proposition qui a modifié la déclaration de métaclasses à la syntaxe actuelle, et la


sémantique pour la façon dont les classes avec métaclasses sont construites.
PEP 3129 — Décorateurs de classes

La proposition qui a ajouté des décorateurs de classe. Les décorateurs de fonction et


de méthode ont été introduits dans PEP 318.

8.8. Coroutines
Nouveau dans la version 3.5.

8.8.1. Définition de fonctions coroutines


async_funcdef ::= [decorators] "async" "def" funcname "("
[parameter_list] ")"
["->" expression] ":" suite

L'exécution de coroutines Python peut être suspendue et reprise à plusieurs endroits


(voir coroutine). Dans le corps d'une coroutine, tout
identificateur await ou async devient un mots-clé réservé ; les
expressions await, async for et async with ne peuvent être utilisées que dans
les corps de coroutines.

Les fonctions définies avec la syntaxe async def sont toujours des fonctions


coroutines, même si elles ne contiennent aucun mot-clé await ou async.
C'est une SyntaxError d'utiliser une expression yield from dans une coroutine.

Un exemple de fonction coroutine :

async def func(param1, param2):


do_stuff()
await some_coroutine()

8.8.2. L'instruction async for
async_for_stmt ::= "async" for_stmt

Un itérable asynchrone est capable d'appeler du code asynchrone dans


l'implémentation de sa méthode iter ; un itérateur asynchrone peut appeler du code
asynchrone dans sa méthode next.

L'instruction async for permet d'itérer facilement sur des itérateurs asynchrones.

Le code suivant :

async for TARGET in ITER:


BLOCK
else:
BLOCK2

est sémantiquement équivalent à :

iter = (ITER)
iter = type(iter).__aiter__(iter)
running = True
while running:
try:
TARGET = await type(iter).__anext__(iter)
except StopAsyncIteration:
running = False
else:
BLOCK
else:
BLOCK2

Voir aussi __aiter__() et __anext__() pour plus de détails.

C'est une SyntaxError d'utiliser une instruction async for en dehors d'une


fonction coroutine.
8.8.3. L'instruction async with
async_with_stmt ::= "async" with_stmt

Un gestionnaire de contexte asynchrone est un gestionnaire de contexte qui est


capable de suspendre l'exécution dans ses méthodes enter et exit.

Le code suivant :

async with EXPR as VAR:


BLOCK

est sémantiquement équivalent à :

mgr = (EXPR)
aexit = type(mgr).__aexit__
aenter = type(mgr).__aenter__(mgr)

VAR = await aenter


try:
BLOCK
except:
if not await aexit(mgr, *sys.exc_info()):
raise
else:
await aexit(mgr, None, None, None)

Voir aussi __aenter__() et __aexit__() pour plus de détails.

C'est une SyntaxError d'utiliser l'instruction async with en dehors d'une fonction


coroutine.

Voir aussi
PEP 492 — Coroutines avec les syntaxes async et await

La proposition qui a fait que les coroutines soient un concept propre en Python, et a
ajouté la syntaxe de prise en charge de celles-ci.

Notes

L'exception est propagée à la pile d'appels à moins qu'il n'y ait une
clause finally qui lève une autre exception, ce qui entraîne la perte de l'ancienne
exception. Cette nouvelle exception entraîne la perte pure et simple de l'ancienne.
2

Une chaîne littérale apparaissant comme première instruction dans le corps de la


fonction est transformée en attribut __doc__ de la fonction et donc en docstring de la
fonction.

Une chaîne littérale apparaissant comme première instruction dans le corps de la


classe est transformée en élément __doc__ de l'espace de nommage et donc
en docstring de la classe.

9. Composants de plus haut niveau


L'entrée de l'interpréteur Python peut provenir d'un certain nombre de sources : d'un
script passé en entrée standard ou en argument de programme, tapée de manière
interactive, à partir d'un fichier source de module, etc. Ce chapitre donne la syntaxe
utilisée dans ces différents cas.

9.1. Programmes Python complets


Bien que les spécifications d'un langage n'ont pas à préciser comment l'interpréteur
du langage est invoqué, il est utile d'avoir des notions sur ce qu'est un programme
Python complet. Un programme Python complet est exécuté dans un environnement
dont l'initialisation est minimale : tous les modules intégrés et standard sont
disponibles mais aucun n'a été initialisé, à l'exception de sys (divers services
système), builtins (fonctions natives, exceptions et None) et __main__. Ce dernier est
utilisé pour avoir des espaces de nommage locaux et globaux pour l'exécution du
programme complet.

La syntaxe d'un programme Python complet est celle d'un fichier d'entrée, dont la
description est donnée dans la section suivante.

L'interpréteur peut également être invoqué en mode interactif ; dans ce cas, il ne lit et
n'exécute pas un programme complet mais lit et exécute une seule instruction
(éventuellement composée) à la fois. L'environnement initial est identique à celui d'un
programme complet ; chaque instruction est exécutée dans l'espace de nommage
de __main__.
Un programme complet peut être transmis à l'interpréteur sous trois formes : avec
l'option -c chaîne en ligne de commande, avec un fichier passé comme premier
argument de ligne de commande ou comme entrée standard. Si le fichier ou l'entrée
standard est un périphérique tty, l'interpréteur entre en mode interactif ; sinon, il
exécute le fichier comme un programme complet.

9.2. Fichier d'entrée
Toutes les entrées lues à partir de fichiers non interactifs sont de la même forme :

file_input ::= (NEWLINE | statement)*

Cette syntaxe est utilisée dans les situations suivantes :

 lors de l'analyse d'un programme Python complet (à partir d'un fichier ou d'une
chaîne de caractères) ;
 lors de l'analyse d'un module ;
 lors de l'analyse d'une chaîne de caractères passée à la fonction exec().
9.3. Entrée interactive
L'entrée en mode interactif est analysée à l'aide de la grammaire suivante :

interactive_input ::= [stmt_list] NEWLINE | compound_stmt NEWLINE

Notez qu'une instruction composée (de niveau supérieur) doit être suivie d'une ligne
blanche en mode interactif ; c'est nécessaire pour aider l'analyseur à détecter la fin
de l'entrée.

9.4. Entrée d'expression
eval() est utilisée pour évaluer les expressions entrées. Elle ignore les espaces en
tête. L'argument de eval(), de type chaîne de caractères, doit être de la forme
suivante :

eval_input ::= expression_list NEWLINE*


10. Spécification complète de la
grammaire
Ceci est la grammaire de Python, exhaustive, telle qu'elle est lue par le générateur
d'analyseur, et utilisée pour analyser des fichiers sources en Python :

# Grammar for Python

# NOTE WELL: You should also follow all the steps listed at
# https://devguide.python.org/grammar/

# Start symbols for the grammar:


# single_input is a single interactive statement;
# file_input is a module or sequence of commands read from
an input file;
# eval_input is the input for the eval() functions.
# NB: compound_stmt in single_input is followed by extra NEWLINE!
single_input: NEWLINE | simple_stmt | compound_stmt NEWLINE
file_input: (NEWLINE | stmt)* ENDMARKER
eval_input: testlist NEWLINE* ENDMARKER

decorator: '@' dotted_name [ '(' [arglist] ')' ] NEWLINE


decorators: decorator+
decorated: decorators (classdef | funcdef | async_funcdef)

async_funcdef: 'async' funcdef


funcdef: 'def' NAME parameters ['->' test] ':' suite

parameters: '(' [typedargslist] ')'


typedargslist: (tfpdef ['=' test] (',' tfpdef ['=' test])* [',' [
'*' [tfpdef] (',' tfpdef ['=' test])* [',' ['**' tfpdef
[',']]]
| '**' tfpdef [',']]]
| '*' [tfpdef] (',' tfpdef ['=' test])* [',' ['**' tfpdef
[',']]]
| '**' tfpdef [','])
tfpdef: NAME [':' test]
varargslist: (vfpdef ['=' test] (',' vfpdef ['=' test])* [',' [
'*' [vfpdef] (',' vfpdef ['=' test])* [',' ['**' vfpdef
[',']]]
| '**' vfpdef [',']]]
| '*' [vfpdef] (',' vfpdef ['=' test])* [',' ['**' vfpdef
[',']]]
| '**' vfpdef [',']
)
vfpdef: NAME
stmt: simple_stmt | compound_stmt
simple_stmt: small_stmt (';' small_stmt)* [';'] NEWLINE
small_stmt: (expr_stmt | del_stmt | pass_stmt | flow_stmt |
import_stmt | global_stmt | nonlocal_stmt |
assert_stmt)
expr_stmt: testlist_star_expr (annassign | augassign (yield_expr|
testlist) |
('=' (yield_expr|testlist_star_expr))*)
annassign: ':' test ['=' test]
testlist_star_expr: (test|star_expr) (',' (test|star_expr))*
[',']
augassign: ('+=' | '-=' | '*=' | '@=' | '/=' | '%=' | '&=' | '|='
| '^=' |
'<<=' | '>>=' | '**=' | '//=')
# For normal and annotated assignments, additional restrictions
enforced by the interpreter
del_stmt: 'del' exprlist
pass_stmt: 'pass'
flow_stmt: break_stmt | continue_stmt | return_stmt | raise_stmt
| yield_stmt
break_stmt: 'break'
continue_stmt: 'continue'
return_stmt: 'return' [testlist]
yield_stmt: yield_expr
raise_stmt: 'raise' [test ['from' test]]
import_stmt: import_name | import_from
import_name: 'import' dotted_as_names
# note below: the ('.' | '...') is necessary because '...' is
tokenized as ELLIPSIS
import_from: ('from' (('.' | '...')* dotted_name | ('.' | '...')
+)
'import' ('*' | '(' import_as_names ')' |
import_as_names))
import_as_name: NAME ['as' NAME]
dotted_as_name: dotted_name ['as' NAME]
import_as_names: import_as_name (',' import_as_name)* [',']
dotted_as_names: dotted_as_name (',' dotted_as_name)*
dotted_name: NAME ('.' NAME)*
global_stmt: 'global' NAME (',' NAME)*
nonlocal_stmt: 'nonlocal' NAME (',' NAME)*
assert_stmt: 'assert' test [',' test]

compound_stmt: if_stmt | while_stmt | for_stmt | try_stmt |


with_stmt | funcdef | classdef | decorated | async_stmt
async_stmt: 'async' (funcdef | with_stmt | for_stmt)
if_stmt: 'if' test ':' suite ('elif' test ':' suite)* ['else' ':'
suite]
while_stmt: 'while' test ':' suite ['else' ':' suite]
for_stmt: 'for' exprlist 'in' testlist ':' suite ['else' ':'
suite]
try_stmt: ('try' ':' suite
((except_clause ':' suite)+
['else' ':' suite]
['finally' ':' suite] |
'finally' ':' suite))
with_stmt: 'with' with_item (',' with_item)* ':' suite
with_item: test ['as' expr]
# NB compile.c makes sure that the default except clause is last
except_clause: 'except' [test ['as' NAME]]
suite: simple_stmt | NEWLINE INDENT stmt+ DEDENT

test: or_test ['if' or_test 'else' test] | lambdef


test_nocond: or_test | lambdef_nocond
lambdef: 'lambda' [varargslist] ':' test
lambdef_nocond: 'lambda' [varargslist] ':' test_nocond
or_test: and_test ('or' and_test)*
and_test: not_test ('and' not_test)*
not_test: 'not' not_test | comparison
comparison: expr (comp_op expr)*
# <> isn't actually a valid comparison operator in Python. It's
here for the
# sake of a __future__ import described in PEP 401 (which really
works :-)
comp_op: '<'|'>'|'=='|'>='|'<='|'<>'|'!='|'in'|'not'
'in'|'is'|'is' 'not'
star_expr: '*' expr
expr: xor_expr ('|' xor_expr)*
xor_expr: and_expr ('^' and_expr)*
and_expr: shift_expr ('&' shift_expr)*
shift_expr: arith_expr (('<<'|'>>') arith_expr)*
arith_expr: term (('+'|'-') term)*
term: factor (('*'|'@'|'/'|'%'|'//') factor)*
factor: ('+'|'-'|'~') factor | power
power: atom_expr ['**' factor]
atom_expr: ['await'] atom trailer*
atom: ('(' [yield_expr|testlist_comp] ')' |
'[' [testlist_comp] ']' |
'{' [dictorsetmaker] '}' |
NAME | NUMBER | STRING+ | '...' | 'None' | 'True' |
'False')
testlist_comp: (test|star_expr) ( comp_for | (',' (test|
star_expr))* [','] )
trailer: '(' [arglist] ')' | '[' subscriptlist ']' | '.' NAME
subscriptlist: subscript (',' subscript)* [',']
subscript: test | [test] ':' [test] [sliceop]
sliceop: ':' [test]
exprlist: (expr|star_expr) (',' (expr|star_expr))* [',']
testlist: test (',' test)* [',']
dictorsetmaker: ( ((test ':' test | '**' expr)
(comp_for | (',' (test ':' test | '**' expr))*
[','])) |
((test | star_expr)
(comp_for | (',' (test | star_expr))* [',']))
)

classdef: 'class' NAME ['(' [arglist] ')'] ':' suite

arglist: argument (',' argument)* [',']

# The reason that keywords are test nodes instead of NAME is that
using NAME
# results in an ambiguity. ast.c makes sure it's a NAME.
# "test '=' test" is really "keyword '=' test", but we have no
such token.
# These need to be in a single rule to avoid grammar that is
ambiguous
# to our LL(1) parser. Even though 'test' includes '*expr' in
star_expr,
# we explicitly match '*' here, too, to give it proper
precedence.
# Illegal combinations and orderings are blocked in ast.c:
# multiple (test comp_for) arguments are blocked; keyword
unpackings
# that precede iterable unpackings are blocked; etc.
argument: ( test [comp_for] |
test '=' test |
'**' test |
'*' test )

comp_iter: comp_for | comp_if


sync_comp_for: 'for' exprlist 'in' or_test [comp_iter]
comp_for: ['async'] sync_comp_for
comp_if: 'if' test_nocond [comp_iter]

# not used in grammar, but may appear in "node" passed from


Parser to Compiler
encoding_decl: NAME

yield_expr: 'yield' [yield_arg]


yield_arg: 'from' test | testlist
La bibliothèque standard
Alors que La référence du langage Python décrit exactement la syntaxe et la
sémantique du langage Python, ce manuel de référence de la Bibliothèque décrit la
bibliothèque standard distribuée avec Python. Il décrit aussi certains composants
optionnels typiquement inclus dans les distributions de Python.

La bibliothèque standard de Python est très grande, elle offre un large éventail
d'outils comme le montre la longueur de la table des matières ci-dessous. La
bibliothèque contient des modules natifs (écrits en C) exposant les fonctionnalités du
système telles que les interactions avec les fichiers qui autrement ne seraient pas
accessibles aux développeurs Python, ainsi que des modules écrits en Python
exposant des solutions standardisées à de nombreux problèmes du quotidien du
développeur. Certains de ces modules sont définis explicitement pour encourager et
améliorer la portabilité des programmes Python en abstrayant des spécificités sous-
jacentes en API neutres.

Les installateurs de Python pour Windows incluent généralement la bibliothèque


standard en entier, et y ajoutent souvent d'autres composants. Pour les systèmes
d'exploitation Unix, Python est typiquement fourni sous forme d'une collection de
paquets, il peut donc être nécessaire d'utiliser le gestionnaire de paquets fourni par
le système d'exploitation pour obtenir certains composants optionnels.

Au delà de la bibliothèque standard, il existe une collection grandissante de plusieurs


milliers de composants (des programmes, des modules, ou des frameworks),
disponibles dans le Python Package Index.

 Introduction
o Notes sur la disponibilité
 Fonctions natives
 Constantes natives
o Constantes ajoutées par le module site
 Types natifs
o Valeurs booléennes
o Opérations booléennes --- and, or, not
o Comparaisons
o Types numériques — int, float, complex
o Les types itérateurs
o Types séquentiels — list, tuple, range
o Type Séquence de Texte — str
o Séquences Binaires --- bytes, bytearray, memoryview
o Types d'ensembles — set, frozenset
o Les types de correspondances — dict
o Le type gestionnaire de contexte
o Autres types natifs
o Attributs spéciaux
 Exceptions natives
o Classes de base
o Exceptions concrètes
o Avertissements
o Hiérarchie des exceptions
 Services de Manipulation de Texte
o string — Opérations usuelles sur des chaînes
o re — Opérations à base d'expressions rationnelles
o difflib — Utilitaires pour le calcul des deltas
o textwrap --- Encapsulation et remplissage de texte
o unicodedata — Base de données Unicode
o stringprep — Préparation des chaines de caractères internet
o readline — interface pour GNU readline
o rlcompleter — Fonction de complétion pour GNU readline
 Services autour des Données Binaires
o struct — manipulation de données agrégées sous forme binaire
comme une séquence d'octets
o codecs — Registre des codecs et classes de base associées
 Types de données
o datetime — Types de base pour la date et l'heure
o calendar — Fonctions calendaires générales
o collections — Types de données de conteneurs
o collections.abc --- Classes de base abstraites pour les conteneurs
o heapq — File de priorité basée sur un tas
o bisect — Algorithme de bissection de listes
o array — Tableaux efficaces de valeurs numériques
o weakref --- Weak references
o types --- Dynamic type creation and names for built-in types
o copy — Opérations de copie superficielle et récursive
o pprint — L’affichage élégant de données
o reprlib --- Alternate repr() implementation
o enum — Énumerations
 Modules numériques et mathématiques
o numbers — Classes de base abstraites numériques
o Fonctions mathématiques — math
o Fonctions mathématiques pour nombres complexes — cmath
o decimal — Arithmétique décimale en virgule fixe et flottante
o fractions — Nombres rationnels
o random --- Génère des nombres pseudo-aléatoires
o statistics — Fonctions mathématiques pour les statistiques
 Modules de programmation fonctionnelle
o itertools — Fonctions créant des itérateurs pour boucler
efficacement
o functools --- Fonctions de haut niveau et opérations sur des objets
appelables
o operator — Opérateurs standards en tant que fonctions
 Accès aux Fichiers et aux Dossiers
o pathlib — Chemins de système de fichiers orientés objet
o os.path — manipulation courante des chemins
o fileinput --- Iterate over lines from multiple input streams
o stat --- Interpreting stat() results
o filecmp – Comparaisons de fichiers et de répertoires
o tempfile — Génération de fichiers et répertoires temporaires
o glob --- Recherche de chemins de style Unix selon certains motifs
o fnmatch — Filtrage par motif des noms de fichiers Unix
o linecache — Accès direct aux lignes d'un texte
o shutil --- Opérations de haut niveau sur les fichiers
o macpath — Fonctions de manipulation de chemins pour Mac OS 9
 Persistance des données
o pickle --- Module de sérialisation d'objets Python
o copyreg — Enregistre les fonctions support de pickle
o shelve — Objet Python persistant
o marshal — Sérialisation interne des objets Python
o dbm --- Interfaces to Unix "databases"
o sqlite3 — Interface DB-API 2.0 pour bases de données SQLite
 Compression de donnée et archivage
o zlib — Compression compatible avec gzip
o gzip — Support pour les fichiers gzip
o bz2 — Prise en charge de la compression bzip2
o lzma — Compression via l'algorithme LZMA
o zipfile — Travailler avec des archives ZIP
o tarfile — Lecture et écriture de fichiers d'archives tar
 Formats de fichiers
o csv — Lecture et écriture de fichiers CSV
o configparser — Lecture et écriture de fichiers de configuration
o netrc — traitement de fichier netrc
o xdrlib --- Encode and decode XDR data
o plistlib --- Generate and parse Mac OS X .plist files
 Service de cryptographie
o hashlib --- Algorithmes de hachage sécurisés et synthèse de
messages
o hmac — Authentification de messages par hachage en combinaison
avec une clé secrète
o secrets — Générer des nombres aléatoires de façon sécurisée pour
la gestion des secrets
 Services génériques du système d'exploitation
o os — Diverses interfaces pour le système d'exploitation
o io --- Core tools for working with streams
o time — Accès au temps et conversions
o argparse -- Parseur d'arguments, d'options, et de sous-commandes
de ligne de commande
o getopt – Analyseur de style C pour les options de ligne de commande
o logging — Fonctionnalités de journalisation pour Python
o logging.config --- Logging configuration
o logging.handlers — Gestionnaires de journalisation
o Saisie de mot de passe portable
o curses --- Terminal handling for character-cell displays
o curses.textpad --- Text input widget for curses programs
o curses.ascii --- Utilities for ASCII characters
o curses.panel --- A panel stack extension for curses
o platform — Accès aux données sous-jacentes de la plateforme
o errno — Symboles du système errno standard
o ctypes — Bibliothèque Python d'appels à des fonctions externes
 Exécution concourante
o threading — Parallélisme basé sur les fils d’exécution (threads)
o multiprocessing — Parallélisme par processus
o Le paquet concurrent
o concurrent.futures --- Launching parallel tasks
o subprocess — Gestion de sous-processus
o sched --- Event scheduler
o queue — File synchronisée
o _thread — API bas niveau de gestion de fils d'exécution
o _dummy_thread --- Module de substitution pour le module _thread
o dummy_threading --- Module de substitution au module threading
 contextvars — Variables de contexte
o Variables de contexte
o Gestion de contexte manuelle
o Gestion avec asyncio
 Réseau et communication entre processus
o asyncio — Entrées/Sorties asynchrones
o socket — Gestion réseau de bas niveau
o ssl — Emballage TLS/SSL pour les objets connecteurs
o select --- Waiting for I/O completion
o selectors --- High-level I/O multiplexing
o asyncore — Gestionnaire de socket asynchrone
o asynchat --- Gestionnaire d'interfaces de connexion (socket)
commande/réponse asynchrones
o signal --- Set handlers for asynchronous events
o mmap --- Memory-mapped file support
 Traitement des données provenant d'Internet
o email — Un paquet de gestion des e-mails et MIME
o json — Encodage et décodage JSON
o mailcap — Manipulation de fichiers Mailcap
o mailbox — Manipuler les boîtes de courriels dans différents formats
o mimetypes --- Map filenames to MIME types
o base64 — Encodages base16, base32, base64 et base85
o binhex — Encode et décode les fichiers binhex4
o binascii --- Conversion entre binaire et ASCII
o quopri — Encode et décode des données MIME quoted-printable
o uu — Encode et décode les fichiers uuencode
 Outils de traitement de balises structurées
o html — Support du HyperText Markup Language
o html.parser --- Simple HTML and XHTML parser
o html.entities — Définitions des entités HTML générales
o Modules de traitement XML
o xml.etree.ElementTree --- The ElementTree XML API
o xml.dom — L'API Document Object Model
o xml.dom.minidom --- Minimal DOM implementation
o xml.dom.pulldom --- Support for building partial DOM trees
o xml.sax — Prise en charge des analyseurs SAX2
o xml.sax.handler --- Base classes for SAX handlers
o xml.sax.saxutils — Utilitaires SAX
o xml.sax.xmlreader --- Interface for XML parsers
o xml.parsers.expat --- Fast XML parsing using Expat
 Gestion des protocoles internet
o webbrowser --- Convenient Web-browser controller
o cgi --- Common Gateway Interface support
o cgitb — Gestionnaire d'exceptions pour les scripts CGI
o wsgiref — Outils et implémentation de référence de WSGI
o urllib — Modules de gestion des URLs
o urllib.request --- Extensible library for opening URLs
o urllib.response --- Response classes used by urllib
o urllib.parse --- Parse URLs into components
o urllib.error --- Classes d'exceptions levées par urllib.request
o urllib.robotparser — Analyseur de fichiers robots.txt
o http — modules HTTP
o http.client --- HTTP protocol client
o ftplib --- FTP protocol client
o poplib --- POP3 protocol client
o imaplib --- IMAP4 protocol client
o nntplib --- NNTP protocol client
o smtplib --- SMTP protocol client
o smtpd --- SMTP Server
o telnetlib --- Telnet client
o uuid — Objets UUID d'après la RFC 4122
o socketserver --- A framework for network servers
o http.server --- HTTP servers
o http.cookies — gestion d'état pour HTTP
o http.cookiejar --- Cookie handling for HTTP clients
o xmlrpc — Modules Serveur et Client XMLRPC
o xmlrpc.client --- XML-RPC client access
o xmlrpc.server --- Basic XML-RPC servers
o ipaddress --- IPv4/IPv6 manipulation library
 Services multimédia
o audioloop — Manipulation de données audio brutes
o aifc — Lis et écrit dans les fichiers AIFF et AIFC
o sunau --- Read and write Sun AU files
o wave --- Lecture et écriture des fichiers WAV
o chunk --- Read IFF chunked data
o colorsys — Conversions entre les systèmes de couleurs
o imghdr --- Determine the type of an image
o sndhdr — Détermine le type d'un fichier audio
o ossaudiodev --- Access to OSS-compatible audio devices
 Internationalisation
o gettext — Services d'internationalisation multilingue
o locale — Services d'internationalisation
 Frameworks d'applications
o turtle — Tortue graphique
o cmd — Interpréteurs en ligne de commande.
o shlex --- Simple lexical analysis
 Interfaces Utilisateur Graphiques avec Tk
o tkinter — Interface Python pour Tcl/Tk
o tkinter.ttk --- Tk themed widgets
o tkinter.tix --- Extension widgets for Tk
o tkinter.scrolledtext — Gadget texte avec barre de défilement
o IDLE
o Autres paquets d'interface graphique utilisateur
 Outils de développement
o typing — Prise en charge des annotations de type
o pydoc — Générateur de documentation et système d’aide en ligne
o doctest --- Test interactive Python examples
o unittest — Framework de tests unitaires
o unittest.mock — Bibliothèque d'objets simulacres
o unittest.mock --- getting started
o 2to3 — Traduction automatique de code en Python 2 vers Python 3
o test --- Regression tests package for Python
o test.support --- Utilities for the Python test suite
o test.support.script_helper --- Utilities for the Python execution
tests
 Débogueur et instrumentation
o bdb — Framework de débogage
o faulthandler --- Dump the Python traceback
o pdb — Le débogueur Python
o The Python Profilers
o timeit — Mesurer le temps d'exécution de fragments de code
o trace --- Trace or track Python statement execution
o tracemalloc --- Trace memory allocations
 Paquets et distribution de paquets logiciels
o distutils — Création et installation des modules Python
o ensurepip --- Bootstrapping the pip installer
o venv — Création d'environnements virtuels
o zipapp — Gestion des archives zip exécutables Python
 Environnement d'exécution Python
o sys — Paramètres et fonctions propres à des systèmes
o sysconfig --- Provide access to Python's configuration information
o builtins — Objets natifs
o __main__ — Point d'entrée des scripts
o warnings --- Contrôle des alertes
o dataclasses — Classes de Données
o contextlib — Utilitaires pour les contextes s'appuyant sur
l'instruction with
o abc — Classes de Base Abstraites
o atexit — Gestionnaire de fin de programme
o traceback --- Print or retrieve a stack traceback
o __future__ — Définitions des futurs
o gc --- Garbage Collector interface
o inspect --- Inspect live objects
o site --- Site-specific configuration hook
 Interpréteurs Python personnalisés
o code --- Interpreter base classes
o codeop — Compilation de code Python
 Importer des modules
o zipimport — Importer des modules à partir d'archives Zip
o pkgutil --- Package extension utility
o modulefinder — Identifie les modules utilisés par un script
o runpy --- Locating and executing Python modules
o importlib --- The implementation of import
 Services du Langage Python
o parser — Accès aux arbres syntaxiques
o ast — Arbres Syntaxiques Abstraits
o symtable --- Access to the compiler's symbol tables
o symbol — Constantes utilisées dans les Arbres Syntaxiques
o token --- Constantes utilisées avec les arbres d'analyse Python (parse
trees)
o keyword — Tester si des chaînes sont des mot-clés Python
o tokenize — Analyseur lexical de Python
o tabnanny — Détection d'indentation ambiguë
o pyclbr --- Python module browser support
o py_compile — Compilation de sources Python
o compileall — Génération du code intermédiaire des bibliothèques
Python
o dis – Désassembleur pour le code intermédiaire de Python
o pickletools --- Tools for pickle developers
 Services divers
o formatter --- Generic output formatting
 Services spécifiques à MS Windows
o msilib --- Read and write Microsoft Installer files
o msvcrt --- Useful routines from the MS VC++ runtime
o winreg --- Windows registry access
o winsound --- Sound-playing interface for Windows
 Services spécifiques à Unix
o posix — Les appels système POSIX les plus courants
o pwd --- The password database
o spwd — La base de données de mots de passe shadow
o grp --- The group database
o crypt --- Function to check Unix passwords
o termios — Le style POSIX le contrôle TTY
o tty — Fonctions de gestion du terminal
o pty — Outils de manipulation de pseudo-terminaux
o fcntl --- The fcntl and ioctl system calls
o pipes — Interface au pipelines shell
o resource --- Resource usage information
o nis — Interface à Sun's NIS (pages jaunes)
o syslog --- Unix syslog library routines
 Modules remplacés
o optparse --- Parser for command line options
o imp --- Access the import internals
 Modules non Documentés
o Modules spécifiques à une plateforme
Introduction
La "Bibliothèque Python" contient divers composants dans différentes catégories.

Elle contient des types de données qui seraient normalement considérés comme
"fondamentaux" au langage, tel que les nombres et les listes. Pour ces types, le
cœur du langage en définit les écritures littérales et impose quelques contraintes
sémantiques, sans les définir exhaustivement. (Cependant le cœur du langage
impose quelques propriétés comme l'orthographe des attributs ou les
caractéristiques des opérateurs.)

La bibliothèque contient aussi des fonctions et des exceptions natives, pouvant être
utilisées par tout code Python sans import. Certaines sont définies par le noyau de
Python, bien qu'elles ne soient pas toutes essentielles.

La grande majorité de la bibliothèque consiste cependant en une collection de


modules. Cette collection peut être parcourue de différentes manières. Certains
modules sont rédigés en C et inclus dans l'interpréteur Python, d'autres sont écrits en
Python et leur source est importée. Certains modules fournissent des interfaces
extrêmement spécifiques à Python, tel que l'affichage d'une pile d'appels, d'autres
fournissent des interfaces spécifiques à un système d'exploitation, comme l'accès à
du matériel spécifique. D'autres fournissent des interfaces spécifiques à un domaine
d'application, comme le World Wide Web. Certains modules sont disponibles dans
toutes les versions et implémentations de Python, d'autres ne sont disponibles que si
le système sous-jacent les gère ou en a besoin. Enfin, d'autres ne sont disponibles
que si Python à été compilé avec une certaine option.

Cette documentation organise les modules "de l'intérieur vers l'extérieur",


documentant en premier les fonctions natives, les types de données et exceptions,
puis les modules, groupés par chapitre, par thématiques.

Ça signifie que si vous commencez à lire cette documentation du début, et sautez au


chapitre suivant lorsqu'elle vous ennuie, vous aurez un aperçu global des modules et
domaines couverts par cette bibliothèque. Bien sûr vous n'avez pas à la lire comme
un roman, vous pouvez simplement survoler la table des matières (au début), ou
chercher une fonction, un module, ou un mot dans l'index (à la fin). Et si vous
appréciez apprendre sur des sujets au hasard, choisissez une page au hasard (avec
le module random) et lisez un chapitre ou deux. Peu importe l'ordre que vous
adopterez, commencez par le chapitre Fonctions natives, car les autres chapitres
présument que vous en avez une bonne connaissance.
Que le spectacle commence !

Notes sur la disponibilité


 Une note "Disponibilité : Unix " signifie que cette fonction est communément
implémentée dans les systèmes Unix. Une telle note ne prétend pas l'existence de la
fonction sur un système d'exploitation particulier.
 Si ce n'est pas mentionné séparément, toutes les fonctions se réclamant
"Disponibilité : Unix" sont gérées sur Mac OS X, qui est basé sur Unix.

Fonctions natives
L'interpréteur Python propose quelques fonctions et types natifs qui sont toujours
disponibles. Ils sont listés ici par ordre alphabétique.

Fonctions
natives
abs() delattr() hash() memoryview() set()

all() dict() help() min() setattr()

any() dir() hex() next() slice()

ascii() divmod() id() object() sorted()

bin() enumerate() input() oct() staticmethod()

bool() eval() int() open() str()

breakpoint() exec() isinstance() ord() sum()

bytearray() filter() issubclass() pow() super()

bytes() float() iter() print() tuple()

callable() format() len() property() type()

chr() frozenset() list() range() vars()

classmethod() getattr() locals() repr() zip()

compile() globals() map() reversed() __import__()

complex() hasattr() max() round()

abs(x)
Donne la valeur absolue d'un nombre. L'argument peut être un nombre entier ou un
nombre à virgule flottante. Si l'argument est un nombre complexe, son module est
donné.

all(iterable)
Donne True si tous les éléments de iterable sont vrais (ou s'il est vide), équivaut à :

def all(iterable):
for element in iterable:
if not element:
return False
return True
any(iterable)
Donne True si au moins un élément de iterable est vrai. Faux est aussi donné dans
le cas où iterable est vide, équivaut à :

def any(iterable):
for element in iterable:
if element:
return True
return False

ascii(object)
Donne, tout comme repr(), une chaîne contenant une représentation affichable
d'un objet, en transformant les caractères non ASCII donnés par repr() en utilisant
des séquences d'échappement \x, \u ou \U. Cela génère une chaîne similaire à ce
que renvoie repr() dans Python 2.

bin(x)
Convertit un nombre entier en binaire dans une chaîne avec le préfixe 0b. Le résultat
est une expression Python valide. Si x n'est pas un int, il doit définir une méthode
__index__() donnant un nombre entier, voici quelques exemples :

>>> bin(3)
'0b11'
>>> bin(-10)
'-0b1010'

Que le préfixe 0b soit souhaité ou non, vous pouvez utiliser les moyens suivants.

>>> format(14, '#b'), format(14, 'b')


('0b1110', '1110')
>>> f'{14:#b}', f'{14:b}'
('0b1110', '1110')

Voir aussi format() pour plus d'information.

class  bool([x])
Donne une valeur booléenne, c'est à dire soit True, soit False. x est converti en
utilisant la procédure standard d'évaluation de valeur de vérité. Si x est faux, ou
omis, elle donne False, sinon, elle donne True. La classe bool hérite de la
classe int (voir Types numériques — int, float, complex). Il n'est pas possible d'en
hériter. Ses seules instances sont False et True (voir Valeurs booléennes).

Modifié dans la version 3.7: x est désormais un argument exclusivement optionnel.

breakpoint(*args, **kws)
Cette fonction vous place dans le débogueur lorsqu'elle est appelée. Plus
précisément, elle appelle sys.breakpointhook(), en lui passant les
arguments args et kws. Par
défaut, sys.breakpointhook() appelle pdb.set_trace() qui n'attend aucun
argument. Dans ce cas, c'est purement une fonction de commodité donc vous n'avez
pas à importer explicitement pdb ou à taper plus de code pour entrer dans le
débogueur. Cependant, sys.breakpointhook() peut-être paramétré pour une
autre fonction et breakpoint() l'appellera automatiquement, vous permettant ainsi
de basculer dans le débogueur de votre choix.

Nouveau dans la version 3.7.

class  bytearray([source[, encoding[, errors]]])
Donne un nouveau tableau d'octets. La classe bytearray est une séquence muable
de nombre entiers dans l'intervalle 0 <= x < 256. Il possède la plupart des méthodes
des séquences variables, décrites dans Types de séquences muables, ainsi que la
plupart des méthodes de la classe bytes, voir Opérations sur les bytes et bytearray.

Le paramètre optionnel source peut être utilisé pour initialiser l'array de quelques


manières différentes :

 Si c'est une chaîne, vous devez aussi donner les paramètre encoding pour


l'encodage (et éventuellement errors). La fonction bytearray() convertit ensuite la
chaîne en bytes via la méthode str.encode().
 Si c'est un entier, l'array aura cette taille et sera initialisé de null bytes.
 Si c'est un objet conforme à l'interface buffer, un buffer en lecture seule de
l'objet sera utilisé pour initialiser l'array.
 Si c'est un itérable, il doit itérer sur des nombres entier dans
l'intervalle 0 <= x < 256, qui seront utilisés pour initialiser le contenu de l'array.

Sans argument, un array de taille vide est crée.

Voir Séquences Binaires --- bytes, bytearray, memoryview et Objets bytearray.

class  bytes([source[, encoding[, errors]]])
Donne un nouvel objet bytes, qui est une séquence immuable de nombre entiers
dans l'intervalle 0 <= x <= 256. Les bytes est une version immuable
de bytearray -- avec les mêmes méthodes d'accès, et le même comportement lors
de l'indexation ou la découpe.

En conséquence, les arguments du constructeur sont les mêmes que


pour bytearray().

Les objets bytes peuvent aussi être créés à partir de littéraux, voir Littéraux de


chaînes de caractères et de suites d'octets.

Voir aussi Séquences Binaires --- bytes, bytearray, memoryview, Objets bytes,


et Opérations sur les bytes et bytearray.

callable(object)
Return True if the object argument appears callable, False if not. If this
returns True, it is still possible that a call fails, but if it is False, calling object will
never succeed. Note that classes are callable (calling a class returns a new
instance); instances are callable if their class has a __call__() method.

Nouveau dans la version 3.2: Cette fonction à d'abord été supprimée avec Python
3.0 puis elle à été remise dans Python 3.2.

chr(i)
Renvoie la chaîne représentant un caractère dont le code de caractère Unicode est
le nombre entier i. Par exemple, chr(97) renvoie la chaîne de caractères 'a',
tandis que chr(8364) renvoie '€'. Il s'agit de l'inverse de ord().

L'intervalle valide pour cet argument est de 0 à 1114111 (0x10FFFF en base 16).


Une exception ValueError sera levée si i est en dehors de l'intervalle.

@classmethod
Transforme une méthode en méthode de classe.
Une méthode de classe reçoit implicitement la classe en premier argument, tout
comme une méthode d'instance reçoit l'instance. Voici comment déclarer une
méthode de classe :

class C:
@classmethod
def f(cls, arg1, arg2, ...): ...

La forme @classmethod est un decorator de fonction — consultez Définition de


fonctions pour plus de détails.

Elle peut être appelée soit sur la classe (comme C.f()) ou sur une instance
(comme C().f()). L'instance est ignorée, sauf pour déterminer sa classe. Si la
méthode est appelée sur une instance de classe fille, c'est la classe fille qui sera
donnée en premier argument implicite.

Les méthodes de classe sont différentes des méthodes statiques du C++ ou du Java.
Si c'est elles sont vous avez besoin, regardez du côté de staticmethod().

Pour plus d'informations sur les méthodes de classe, consultez Hiérarchie des types
standards.

compile(source, filename, mode, flags=0, dont_inherit=False, optimize=-1)
Compile source en un objet code ou objet AST. Les objets code peuvent être
exécutés par exec() ou eval(). source peut soit être une chaîne, un objet bytes,
ou un objet AST. Consultez la documentation du module ast pour des informations
sur la manipulation d'objets AST.

L'argument filename doit nommer le fichier duquel le code à été lu. Donnez quelque


chose de reconnaissable lorsqu'il n'a pas été lu depuis un fichier
(typiquement "<string>").

L'argument mode indique quel type de code doit être compilé : 'exec' si source est
une suite d'instructions, 'eval' pour une seule expression, ou 'single' si il ne
contient qu'une instruction interactive (dans ce dernier cas, les résultats
d'expressions donnant autre chose que None seront affichés).

Les arguments optionnels flags et dont_inherit contrôlent quelle instructions


future affecte la compilation de source. Si aucun des deux n'est présent (ou que les
deux sont à 0) le code est compilé avec les mêmes instructions future que le code
appelant compile(). Si l'argument flags est fourni mais que dont_inherit ne l'est pas
(ou vaut 0), alors les instructions futures utilisées seront celles spécifiées par flags en
plus de celles qui auraient été utilisées. Si dont_inherit est un entier différent de
zéro, flags est utilisé seul -- les instructions futures déclarées autour de l'appel
à compile sont ignorées.

Les instructions futures sont spécifiées par des bits, il est ainsi possible d'en spécifier
plusieurs en les combinant avec un ou binaire. Les bits requis pour spécifier une
certaine fonctionnalité se trouvent dans l'attribut compiler_flag de la
classe Feature du module __future__.

L'argument optimize indique le niveau d'optimisation du compilateur. La valeur par


défaut est -1 qui prend le niveau d'optimisation de l'interpréteur tel que reçu via
l'option -O. Les niveau explicites sont : 0 (pas
d'optimisation, __debug__ est True), 1 (les assert sont
supprimés, __debug__ est False) ou 2 (les docstrings sont également supprimés).

Cette fonction lève une SyntaxError si la source n'est pas valide, et ValueError si


la source contient des octets null.

Si vous voulez transformer du code Python en sa représentation AST,


voyez ast.parse().

Note
 

Lors de la compilation d'une chaîne de plusieurs lignes de code avec les


modes 'single' ou 'eval', celle-ci doit être terminée d'au moins un retour à la
ligne. Cela permet de faciliter la distinction entre les instructions complètes et
incomplètes dans le module code.

Avertissement
 

Il est possible de faire planter l'interpréteur Python avec des chaînes suffisamment
grandes ou complexes lors de la compilation d'un objet AST à cause de la limitation
de la profondeur de la pile d'appels.

Modifié dans la version 3.2: Autorise l'utilisation de retours à la ligne Mac et


Windows. Aussi, la chaîne donnée à 'exec' n'a plus besoin de terminer par un
retour à la ligne. Ajout du paramètre optimize.

Modifié dans la version 3.5: Précédemment, l'exception TypeError était levée


quand un caractère nul était rencontré dans source.

class  complex([real[, imag]])
Donne un nombre complexe de valeur real + imag\*1j, ou convertit une chaîne
ou un nombre en nombre complexe. Si le premier paramètre est une chaîne, il sera
interprété comme un nombre complexe et la fonction doit être appelée dans second
paramètre. Le second paramètre ne peut jamais être une chaîne. Chaque argument
peut être de n'importe quel type numérique (même complexe). Si imag est omis, sa
valeur par défaut est zéro, le constructeur effectue alors une simple conversion
numérique comme le font int ou float. Si aucun argument n'est fourni, donne 0j.

Note
 

Lors de la conversion depuis une chaîne, elle ne doit pas contenir d'espaces autour
des opérateurs binaires + ou -. Par exemple complex('1+2j') est bon,
mais complex('1 + 2j') lève une ValueError.

Le type complexe est décrit dans Types numériques — int, float, complex.

Modifié dans la version 3.6: Les chiffres peuvent être groupés avec des tirets bas
comme dans les expressions littérales.

delattr(object, name)
C'est un cousin de setattr(). Les arguments sont un objet et une chaîne. La
chaîne doit être le nom de l'un des attributs de l'objet. La fonction supprime l'attribut
nommé, si l'objet l'y autorise. Par exemple delattr(x, 'foobar') est l'équivalent
de del x.foobar.

class  dict(**kwarg)
class  dict(mapping, **kwarg)
class  dict(iterable, **kwarg)
Créé un nouveau dictionnaire. L'objet dict est la classe du dictionnaire.
Voir dict et Les types de correspondances — dict pour vous documenter sur cette
classe.

Pour les autres conteneurs, voir les classes natives list, set, et typle. ainsi que le
module collections.

dir([object])
Sans arguments, elle donne la liste des noms dans l'espace de nommage local. Avec
un argument, elle essaye de donner une liste d'attributs valides pour cet objet.

Si l'objet à une méthode __dir__(), elle est appelée et doit donner une liste
d'attributs. Cela permet aux objets
implémentant __getattr__() ou __getattribute__() de personnaliser ce que
donnera dir().

Si l'objet ne fournit pas de méthode __dir__(), la fonction fait de son mieux en


rassemblant les informations de l'attribut __dict__ de l'objet, si défini, et depuis son
type. La liste résultante n'est pas nécessairement complète, et peut être inadaptée
quand l'objet a un __getattr__() personnalisé.

Le mécanisme par défaut de dir() se comporte différemment avec différents types


d'objets, car elle préfère donner une information pertinente plutôt qu'exhaustive :

 Si l'objet est un module, la liste contiendra les noms des attributs du module.
 Si l'objet est un type ou une classe, la liste contiendra les noms de ses
attributs, et récursivement, des attributs de ses parents.
 Autrement, la liste contient les noms des attributs de l'objet, le nom des
attributs de la classe, et récursivement des attributs des parents de la classe.

La liste donnée est triée par ordre alphabétique, par exemple :

>>> import struct


>>> dir() # show the names in the module namespace
['__builtins__', '__name__', 'struct']
>>> dir(s