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 [-bBdEiOQsRStuUvVWxX3?] [-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" devrait être un
   nom de module Python valide, mais l’implémentation n’est pas tenue
   de le vérifier (par exemple, l’utilisation d’un trait d’union peut
   être autorisée).

   Les noms de paquets sont aussi autorisés. Quand un nom de paquet
   est donné à la place d’un module habituel, l’interpréteur exécutera
   "<pkg>.__main" comme module principal. Ce comportement est
   délibérement identique que pour un répertoire on un fichier zip
   donné à l’interpréteur comme argument à exécuter.

   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" sera
   le chemin complet d’accès au fichier du module. Comme pour l’option
   "-c", le répertoire courant sera ajouté au début de "sys.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

   Nouveau dans la version 2.4.

   Modifié dans la version 2.5: The named module can now be located
   inside a package.

   Modifié dans la version 2.7: Supply the package name to run a
   "__main__" submodule. sys.argv[0] is now set to ""-m"" while
   searching for the module (it was previously incorrectly set to
   ""-c"")

-

   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".

   Voir aussi:

     "runpy.run_path()"
        Fonctionnalité équivalente directement disponible en code
        Python

<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__".

   Modifié dans la version 2.5: Directories and zipfiles containing a
   "__main__.py" file at the top level are now considered valid Python
   scripts.

Si aucune option d’interface est donnée, "-i" est implicite,
"sys.argv[0]" est une chaine vide ("""") et le répertoire courant sera
ajouté au début de "sys.path".

Voir aussi: Lancement de l’interpréteur


1.1.2. Options génériques
-------------------------

-?
-h
--help

   Affiche une brève description de toutes les options de la ligne de
   commande.

   Modifié dans la version 2.5: The "--help" variant.

-V
--version

   Affiche seulement la version de Python. Par exemple :

      Python 2.5.1

   Modifié dans la version 2.5: The "--version" variant.


1.1.3. Options diverses
-----------------------

-b

   Issue a warning when comparing "unicode" with "bytearray". Issue an
   error when the option is given twice ("-bb").

   Note that, unlike the corresponding Python 3.x flag, this will
   **not** emit warnings for comparisons between "str" and "unicode".
   Instead, the "str" instance will be implicitly decoded to "unicode"
   and Unicode comparison used.

   Nouveau dans la version 2.6.

-B

   Si donné, Python ne tentera pas d’écrire de fichier ".pyc`" ou
   ".pyo" à l’importation des modules source. Voir aussi
   "PYTHONDONTWRITEBYTECODE".

   Nouveau dans la version 2.6.

-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".

   Nouveau dans la version 2.2.

-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".

-O

   Activer les optimisations de base. Cela modifie l’extension du
   fichier pour les fichiers compilés (*bytecode*) de ".pyc" à ".pyo".
   Voir aussi "PYTHONOPTIMIZE".

-OO

   Supprime les *docstrings* en plus des optimisations réalisées par
   "-O".

-Q <arg>

   Division control. The argument must be one of the following:

   "old"
      division of int/int and long/long return an int or long
      (*default*)

   "new"
      new division semantics, i.e. division of int/int and long/long
      returns a float

   "warn"
      old division semantics with a warning for int/int and long/long

   "warnall"
      old division semantics with a warning for all uses of the
      division operator

   Voir aussi:

     "Tools/scripts/fixdiv.py"
        for a use of "warnall"

     **PEP 230** – Gestion des alertes

-R

   Turn on hash randomization, so that the "__hash__()" values of str,
   bytes and datetime objects are « salted » with an unpredictable
   random value. Although they remain constant within an individual
   Python process, they are not predictable between repeated
   invocations of Python.

   This is intended to provide protection against a denial-of-service
   caused by carefully-chosen inputs that exploit the worst case
   performance of a dict construction, O(n^2) complexity.  See
   http://www.ocert.org/advisories/ocert-2011-003.html for details.

   Changing hash values affects the order in which keys are retrieved
   from a dict.  Although Python has never made guarantees about this
   ordering (and it typically varies between 32-bit and 64-bit
   builds), enough real-world code implicitly relies on this non-
   guaranteed behavior that the randomization is disabled by default.

   Voir aussi "PYTHONHASHSEED".

   Nouveau dans la version 2.6.8.

-s

   N’ajoute pas le répertoire utilisateur "site-packages" à
   "sys.path".

   Nouveau dans la version 2.6.

   Voir aussi: **PEP 370** – Répertoire site-packages propre à
     l’utilisateur.

-S

   Désactiver l’importation du module "site" et les modifications de
   "sys.path" spécifiques au site qu’elle implique.

-t

   Issue a warning when a source file mixes tabs and spaces for
   indentation in a way that makes it depend on the worth of a tab
   expressed in spaces.  Issue an error when the option is given twice
   ("-tt").

-u

   Force stdin, stdout and stderr to be totally unbuffered.  On
   systems where it matters, also put stdin, stdout and stderr in
   binary mode.

   Note that there is internal buffering in "file.readlines()" and
   Objets fichiers ("for line in sys.stdin") which is not influenced
   by this option.  To work around this, you will want to use
   "file.readline()" inside a "while 1:" loop.

   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 also "PYTHONVERBOSE".

-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é).

   Starting from Python 2.7, "DeprecationWarning" and its descendants
   are ignored by default.  The "-Wd" option can be used to re-enable
   them.

   Les avertissements peuvent aussi être contrôlés dans le programme
   Python en utilisant le module "warnings".

   The simplest form of argument is one of the following action
   strings (or a unique abbreviation) by themselves:

   "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.

   Voir aussi: "warnings" – le module qui gère les avertissements.

     **PEP 230** – Gestion des alertes

     "PYTHONWARNINGS"

-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.

-3

   Warn about Python 3.x possible incompatibilities by emitting a
   "DeprecationWarning" for features that are removed or significantly
   changed in Python 3 and can’t be detected using static code
   analysis.

   Nouveau dans la version 2.6.

   See Porting Python 2 Code to Python 3 for more details.


1.1.4. Options à ne pas utiliser
--------------------------------

-J

   Utilisation réservée à Jython.

-U

   Turns all string literals into unicodes globally.  Do not be
   tempted to use this option as it will probably break your world.
   It also produces ".pyc" files with a different magic number than
   normal.  Instead, you can enable unicode literals on a per-module
   basis by using:

      from __future__ import unicode_literals

   at the top of the file.  See "__future__" for details.

-X

   Reserved for alternative implementations of Python to use for their
   own purposes.


1.2. Variables d’environnement
==============================

These environment variables influence Python’s behavior, they are
processed before the command-line switches other than -E.  It is
customary that command-line switches override environmental variables
where there is a conflict.

PYTHONHOME

   Modifie l’emplacement des bibliothèques standards de Python. Par
   défaut, les bibliothèques sont recherchées dans
   "*préfixe*/lib/python*version*" et
   "*préfixe_exec*/lib/python*version*" où "*pré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" à
   "*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 par "os.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/python*version*" (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

   If this is the name of a readable file, the Python commands in that
   file are executed before the first prompt is displayed in
   interactive mode.  The file is executed in the same namespace where
   interactive commands are executed so that objects defined or
   imported in it can be used without qualification in the interactive
   session.  You can also change the prompts "sys.ps1" and "sys.ps2"
   in this file.

PYTHONY2K

   Set this to a non-empty string to cause the "time" module to
   require dates specified as strings to include 4-digit years,
   otherwise 2-digit years are converted based on rules described in
   the "time" module documentation.

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

   If this is set, Python ignores case in "import" statements.  This
   only works on Windows, OS X, OS/2, and RiscOS.

PYTHONDONTWRITEBYTECODE

   Si donné, Python ne tentera pas d’écrire de fichier ".pyc`" ou
   ".pyo" à l’importation des modules source. Voir aussi
   "PYTHONDONTWRITEBYTECODE".

   Nouveau dans la version 2.6.

PYTHONHASHSEED

   If this variable is set to "random", the effect is the same as
   specifying the "-R" option: a random value is used to seed the
   hashes of str, bytes and datetime objects.

   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.

   The integer must be a decimal number in the range [0,4294967295].
   Specifying the value 0 will lead to the same hash values as when
   hash randomization is disabled.

   Nouveau dans la version 2.6.8.

PYTHONIOENCODING

   Overrides the encoding used for stdin/stdout/stderr, in the syntax
   "encodingname:errorhandler".  The ":errorhandler" part is optional
   and has the same meaning as in "str.encode()".

   Nouveau dans la version 2.6.

PYTHONNOUSERSITE

   Si elle est définie, Python n’ajoute pas le répertoire "site-
   packages utilisateur" à "sys.path".

   Nouveau dans la version 2.6.

   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 utilisateur "site-packages" et
   Installation alternative : le schéma user pour "python setup.py
   install --user".

   Nouveau dans la version 2.6.

   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.

PYTHONHTTPSVERIFY

   If this environment variable is set specifically to "0", then it is
   equivalent to implicitly calling "ssl._https_verify_certificates()"
   with "enable=False" when "ssl" is first imported.

   Refer to the documentation of "ssl._https_verify_certificates()"
   for details.

   Nouveau dans la version 2.7.12.


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.

   Modifié dans la version 2.6: Previously, this variable was called
   "THREADDEBUG".

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.

PYTHONSHOWALLOCCOUNT

   If set and Python was compiled with "COUNT_ALLOCS" defined, Python
   will dump allocations counts into stderr on shutdown.

   Nouveau dans la version 2.7.15.

PYTHONSHOWREFCOUNT

   If set, Python will print the total reference count when the
   program finishes or after each statement in the interactive
   interpreter.

   Nouveau dans la version 2.7.15.
