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.
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 desys.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 noms, 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 intégrés et les modules d’extension écrits en C, étant donné qu’il 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 desys.path
.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 -mtimeit -s 'setup here' 'benchmarked code here' python -mtimeit -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 noms sont supporté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 desys.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__
.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
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¶
1.1.3. Options diverses¶
-
-b
¶
Issue a warning when comparing
bytes
orbytearray
withstr
orbytes
withint
. Issue an error when the option is given twice (-bb
).
-
-B
¶
S’il est donné, Python ne tente pas d’écrire de fichier
.pyc`
ou.pyo
à l’importation des modules source. Voir aussiPYTHONDONTWRITEBYTECODE
.
-
-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
etPYTHONHOME
.
-
-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 lorsquesys.stdin
ne semble pas être un terminal. Le fichierPYTHONSTARTUP
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’environnementPYTHON*
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
¶
Active les optimisations basiques. Voir aussi
PYTHONOPTIMIZE
.
-
-q
¶
N’affiche pas le copyright et la version, même en mode interactif.
Nouveau dans la version 3.2.
-
-R
¶
Conservé pour compatibilité ascendante. Sur Python 3.3 ou supérieur, la randomisation des empreintes (hash en anglais) est activée par défaut.
Sur les versions précédentes de Python, cette option activait la randomisation des empreintes de manière à ce que les
__hash__()
de chaînes, bytes etdatetime
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.La randomisation 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(n^2). 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.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 desys.path
qu’il implique. Désactive aussi ces manipulations sisite
est importé explicitement plus tard (appelezsite.main()
si vous voulez les déclencher).
-
-u
¶
Désactive les mémoires tampons de la couche binaire des flux de la sortie standard (stdout) et de la sortie d’erreurs (stderr) (ils restent accessibles via leur attribut
buffer
). La couche d’entrée-sortie est mise en tampon ligne par ligne lors de l’écriture sur la console, ou par blocs si elle est redirigée sur un fichier non-interactif.Voir aussi
PYTHONUNBUFFERED
.
-
-v
¶
Print a message each time a module is initialized, showing the place (filename or built-in module) from which it is loaded. When given twice (
-vv
), print a message for each file that is checked for when searching for a module. Also provides information on module cleanup at exit. See alsoPYTHONVERBOSE
.
-
-W
arg
¶ Warning control. Python’s warning machinery by default prints warning messages to
sys.stderr
. A typical warning message has the following form: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 dans le programme Python en utilisant le module
warnings
.La forme la plus simple de l’argument est l’une des chaînes d’actions suivantes (ou une abréviation unique) :
ignore
- Ignore tous les avertissements.
default
- Demande explicitement le comportement par défaut (affiche chaque avertissement une fois par ligne de code source).
all
- Affiche un avertissement à chaque fois qu’il se produit (ce qui peut générer beaucoup de messages si l’avertissement est déclenché à plusieurs reprises, comme à l’intérieur d’une boucle).
module
- Affiche chaque avertissement uniquement la première fois qu’il apparaît dans chaque module.
once
- Affiche chaque avertissement uniquement la première fois qu’il apparaît dans le programme.
error
- Déclenche une exception au lieu d’afficher un message d’avertissement.
La forme complète de l’argument est :
action:message:category:module:line
Ici, action est tel qu’expliqué ci-dessus, mais s’applique uniquement aux messages qui correspondent aux champs restants. Les champs vides correspondent à toutes les valeurs ; les champs vides de fin peuvent être omis. Le champ message correspond au début du message d’avertissement affiché, cette expression est insensible à la casse. Le champ category correspond à la catégorie d’avertissement. Ce nom doit être un nom complet de classe ; La règle s’applique à tous les messages d’alertes construits avec une classe qui hérite de celle spécifiée. Le nom de la classe complète doit être donnée. Le champ module correspond au nom (pleinement qualifié) du module, cette correspondance est sensible à la casse. Le champ line correspond au numéro de ligne, où zéro correspond à n’importe quel numéro de ligne et correspond donc à l’option par défaut.
-
-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.Note
Les numéros de ligne dans les messages d’erreur seront décalés de un.
-
-X
¶
Réservée pour les options spécifiques aux différentes implémentations. CPython reconnaît actuellement les valeurs suivantes :
-X faulthandler
pour activerfaulthandler
;-X showrefcount
to enable the output of the total reference count and memory blocks (only works on debug builds);-X tracemalloc
pour lancer le suivi des allocations mémoire par Python en utilisant le moduletracemalloc
. 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. Voirtracemalloc.start()
pour plus d’informations.
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: It is now allowed to pass
-X
with CPython.Nouveau dans la version 3.3: option
-X faulthandler
.Nouveau dans la version 3.4: options
-X showrefcount
et-X tracemalloc
.
1.2. Variables d’environnement¶
Ces variables d’environnement 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
etpréfixe_exec/lib/pythonversion
oùpréfixe
etpré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 foispréfixe
etpréfixe_exec
. Pour spécifier des valeurs différentes à ces variables, définissezPYTHONHOME
àprefix:exec_prefix
.
-
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 paros.pathsep
(par exemple, 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
(voirPYTHONHOME
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 variablesys.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 noms 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
etsys.ps2
ainsi que la fonction automatique (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.
-
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
¶ If this is set to a non-empty string, Python won’t try to write
.pyc
files on the import of source modules. This is equivalent to specifying the-B
option.
-
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 chaines, bytes etdatetime
.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 la randomisation 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 compris entre 0 et 4 294 967 295. Spécifier la valeur 0 désactive la randomisation 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 dansstr.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.
-
PYTHONNOUSERSITE
¶ Si elle est définie, Python n’ajoute pas le répertoire
site-packages 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 utilisateursite-packages
et Installation alternative : le schéma user pourpython 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 à la même 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.
-
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 signauxSIGSEGV
,SIGFPE
,SIGABRT
,SIGBUS
etSIGILL
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. Voirtracemalloc.start()
pour davantage d’informations.Nouveau dans la version 3.4.
-
PYTHONASYNCIODEBUG
¶ Si elle est définie à une chaîne non vide, active le mode debogage du module
asyncio
.Nouveau dans la version 3.4.
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.
-
PYTHONMALLOCSTATS
¶ If set, Python will print memory allocation statistics every time a new object arena is created, and on shutdown.