Ce document est relatif à une vieille version de Python qui n'est plus soutenue. Mettez à jour votre version et lisez Bienvenue sur la documentation de la version stable actuelle de Python.

# `sys` — Paramètres et fonctions propres à des systèmes

Ce module fournit un accès à certaines variables utilisées et maintenues par l'interpréteur, et à des fonctions interagissant fortement avec ce dernier. Ce module est toujours disponible.

`sys.``abiflags`

  Contient, sur les systèmes POSIX où Python a été compilé avec le script `configure`, les ABI flags tels que définis par la PEP 3149.

  Modifié dans la version 3.8: Les options par défaut sont devenues des chaines de caractères vides (l'option `m` pour pymalloc a été enlevée).

  Nouveau dans la version 3.2.

`sys.``addaudithook`(hook)

  Append the callable hook to the list of active auditing hooks for the current (sub)interpreter.

  Quand un événement d'audit est déclenché par la fonction `sys.audit()`, chaque point d'entrée est appelé dans l'ordre dans lequel il a été ajouté avec le nom de l'événement et le n-uplet des arguments. Les points d'entrées qui sont ajoutés par `PySys_AddAuditHook()` sont appelés les premiers, suivi par les fonctions de rappel ajoutées dans l'interpréteur en cours d'exécution. Les points d'entrées peuvent logger l'événement, lever une exception pour stopper l'opération ou terminer le processus entièrement.

  L'appel de `sys.addaudithook()` lèvera d'elle même un événement d'audit appelé `sys.addaudithook` sans arguments. Si n'importe quel hook lève une exception dérivée de `RuntimeError`, le nouveau point d'entrée ne sera pas ajouté et l'exception supprimée. Par conséquent, les appels ne peuvent pas supposer que leurs points d'entrées ont été ajoutés à moins de contrôler tous les points d'entrées existants.

  Voir la table d'évenements d'audit pour tous les événements levés par CPython et PEP 578 pour la discussion originale de ce design.

  Nouveau dans la version 3.8.

  Modifié dans la version 3.8.1: Les exceptions dérivées de `Exception` mais pas `RuntimeError` ne sont plus supprimées.

  CPython implementation detail: Quand le traçage est activé (voir `settrace()`), les hooks Python ne sont tracés que si la fonction a un membre `__cantrace__` dont la valeur est vraie. Autrement, les fonctions de traçage ignorent le hook.

`sys.``argv`

  La liste des arguments de la ligne de commande passés à un script Python. `argv[0]` est le nom du script (chemin complet, ou non, en fonction du système d'exploitation). Si la commande a été exécutée avec l'option `-c` de l'interpréteur, `argv[0]` vaut la chaîne `'-c'`. Si aucun nom de script n'a été donné à l'interpréteur Python, `argv[0]` sera une chaîne vide.

  Pour boucler sur l'entrée standard, ou la liste des fichiers donnés sur la ligne de commande, utilisez le module `fileinput`.

  Note

  Sous Unix, les arguments de ligne de commande sont passés par des octets depuis le système d'exploitation. Python les décode en utilisant l’encodage du système de fichiers et le gestionnaire d’erreur surrogateescape. Quand vous avez besoin des octets originaux, vous pouvez les récupérer avec `[os.fsencode(arg) for arg in sys.argv]`.

`sys.``audit`(event, *args)

  Déclenche un événement d'audit pour tous les points d'entrées d'audit actifs. event est une chaîne de caractères identifiant l'événement, et args peut contenir des arguments optionnels avec plus d'informations sur l'événement en question. Le nombre et types d'arguments pour un événement donné sont considérés comme une API publique et stable, et ne devraient pas être modifiés entre les versions.

  Par exemple, un événement d'audit est nommé `os.chdir`. Cet événement à un argument appelé path qui contiendras le nouveau répertoire de travail.

  `sys.audit()` appellera les point d'entrées (hooks en anglais) d'audits existants, en passant le nom de l'événement et ses arguments, et lèvera à nouveau la première exception de n'importe quel point d'entrée. En général, si une exception est levée, elle ne devrais pas être gérée et le processus devrait être terminé aussi rapidement que possible. Cela permet que les implémentations des points d'entrées décident comment répondre à des événements particuliers : Ils peuvent simplement logger l'événement ou arrêter l'opération en levant une exception.

  Les points d'entrées sont ajoutés en utilisant les fonctions `sys.addaudithook()` ou `PySys_AddAuditHook()`.

  L'équivalent natif de cette fonction est `PySys_Audit()`. L'utilisation de la fonction native est encouragée lorsque c'est possible.

  Voir le tableau d'événements d'audit pour tous les événements levés par CPython.

  Nouveau dans la version 3.8.

`sys.``base_exec_prefix`

  Set during Python startup, before `site.py` is run, to the same value as `exec_prefix`. If not running in a virtual environment, the values will stay the same; if `site.py` finds that a virtual environment is in use, the values of `prefix` and `exec_prefix` will be changed to point to the virtual environment, whereas `base_prefix` and `base_exec_prefix` will remain pointing to the base Python installation (the one which the virtual environment was created from).

  Nouveau dans la version 3.3.

`sys.``base_prefix`

  Défini au démarrage de Python, avant que `site.py` ne soit évalué, à la même valeur que `prefix`. Hors d'un environnement virtuel, les valeurs restent les mêmes ; si `site.py` détecte qu'un environnement virtuel est utilisé, les valeurs de `prefix` et `exec_prefix` sont modifiées pour pointer vers l'environnement virtuel, alors que `base_prefix` et `base_exec_prefix` pointent toujours à la racine de l'installation de Python (celui utilisé pour créer l'environnement virtuel).

  Nouveau dans la version 3.3.

`sys.``byteorder`

  Un indicateur de l'ordre natif des octets. Vaudra `'big'` sur les plateformes gros-boutistes (octet le plus significatif en premier), et `'little'` sur les plateformes petit-boutiste (octet le moins significatif en premier).

`sys.``builtin_module_names`

  Un n-uplet de chaînes de caractères donnant les noms de tous les modules compilés dans l'interpréteur Python. (Cette information n'est pas disponible autrement --- ``modules.keys()` liste seulement les modules importés.)

`sys.``call_tracing`(func, args)

  Appelle `func(*args)`, avec le traçage activé. L'état du traçage est sauvegardé et restauré après l'appel. Ceci est destiné à être appelé depuis un débogueur à partir d'un point de contrôle, pour déboguer récursivement un autre code.

`sys.``copyright`

  Une chaîne contenant le copyright relatif à l'interpréteur Python.

`sys.``_clear_type_cache`()

  Vide le cache interne de types. Le cache de types est utilisé pour accélérer les recherches d'attributs et de méthodes. N'utilisez cette fonction que pour libérer des références inutiles durant le débogage de fuite de référence.

  Cette fonction ne devrait être utilisée que pour un usage interne et spécialisé.

`sys.``_current_frames`()

  Renvoie un dictionnaire faisant correspondre chaque identifiant de fil d'exécution à la stack frame actuellement active pour ces fils d'exécution au moment où la fonction est appelée. Notez que les fonctions du module `traceback` peuvent construire une call stack à partir d'une telle frame.

  N'ayant pas besoin de la coopération des fils d'exécution bloqués, cette fonction est très utile pour déboguer un deadlock. Aussi, les call stack de ces fils d'exécution ne changeront pas tant qu'ils seront bloqués. La frame renvoyée pour un fil d'exécution non bloqué peut ne plus être liée à l'activité courante du fil d'exécution au moment où le code appelant examine la frame.

  Cette fonction ne devrait être utilisée que pour un usage interne et spécialisé.

  Lève un événement d'audit `sys._current_frames` sans arguments.

`sys.``breakpointhook`()

  Cette fonction auto-déclenchée (hook function en anglais) est appelée par la fonction native `breakpoint()`. Par défaut, elle vous place dans le débogueur `pdb`, mais elle peut être dirigée vers n'importe quelle autre fonction pour que vous puissiez choisir le débogueur utilisé.

  La signature de cette fonction dépend de ce qu'elle appelle. Par exemple, l'appel par défaut (e.g. `pdb.set_trace()`) n'attend pas d'argument, mais vous pourriez la lier à une fonction qui attend des arguments supplémentaires (positionnels et/ou mots-clés). La fonction native breakpoint() passe ses `*args` et `**kws` directement au travers. Tout ce que renvoie `breakpointhooks()` est renvoyé par `breakpoint()`.

  L'implémentation par défaut consulte d'abord la variable d'environnement `PYTHONBREAKPOINT`. Si elle vaut `"0"` alors cette fonction s'achève immédiatement (elle ne fait donc rien). Si la variable d'environnement n'est pas définie, ou s'il s'agit d'une chaîne vide, `pdb.set_trace()` est appelée. Sinon cette variable doit nommer une fonction à appeler, en utilisant la syntaxe d'importation de Python, par exemple `package.subpackage.module.function`. Dans ce cas, `package.subpackage.module` sera importé et le module devra contenir une fonction appelable `function()`. Celle-ci est lancée en lui passant `*args` et `*kws` et, quoique renvoie `function()`, `sys.breakpointhook()` retourne à la fonction native `breakpoint()`.

  Notez que si un problème apparaît au moment de l'importation de la fonction nommée dans `PYTHONBREAKPOINT`, une alerte `RuntimeWarning` est indiquée et le point d'arrêt est ignoré.

  Notez également que si `sys.breakpointhook()` est surchargé de manière programmatique, `PYTHONBREAKPOINT` n'est pas consulté.

  Nouveau dans la version 3.7.

`sys.``_debugmallocstats`()

  Affiche des informations bas-niveau sur la sortie d'erreur à propos de l'état de l'allocateur de mémoire de CPython.

  Si Python est configuré avec l'option --with-pydebug, il effectuera aussi quelques coûteuses vérifications de cohérence interne.

  Nouveau dans la version 3.3.

  CPython implementation detail: Cette fonction est spécifique à CPython. Le format de sa sortie n'est pas définit ici et pourrait changer.

`sys.``dllhandle`

  Nombre entier spécifiant le descripteur de la DLL Python.

  Disponibilité : Windows.

`sys.``displayhook`(value)

  Si value n'est pas `None`, cette fonction écrit `repr(value)` sur `sys.stdout`, et sauvegarde value dans `builtins._`. Si `repr(value)` ne peut pas être encodé avec `sys.stdout.encoding` en utilisant le gestionnaire d'erreur `sys.stdout.errors` (qui est probablement `'strict'`), elle sera encodée avec `sys.stdout.encoding` en utilisant le gestionnaire d'erreur `'backslashreplace'`.

  `sys.displayhook` est appelé avec le résultat de l'évaluation d'une expression entrée dans une session Python interactive. L'affichage de ces valeurs peut être personnalisé en assignant une autre fonction d'un argument à `sys.displayhook`.

  Pseudo-code :

      def displayhook(value):
          if value is None:
              return
          # Set '_' to None to avoid recursion
          builtins._ = None
          text = repr(value)
          try:
              sys.stdout.write(text)
          except UnicodeEncodeError:
              bytes = text.encode(sys.stdout.encoding, 'backslashreplace')
              if hasattr(sys.stdout, 'buffer'):
                  sys.stdout.buffer.write(bytes)
              else:
                  text = bytes.decode(sys.stdout.encoding, 'strict')
                  sys.stdout.write(text)
          sys.stdout.write("\n")
          builtins._ = value

  Modifié dans la version 3.2: Utiliser le gestionnaire d'erreur `'backslashreplace'` en cas d'`UnicodeEncodeError`.

`sys.``dont_write_bytecode`

  Si vrai, Python n'essaiera pas d'écrire de fichiers `.pyc` à l'importation de modules source. Cette valeur est initialement définie à `True` ou `False` en fonction de l'option de la ligne de commande `-B` et de la variable d'environnement `PYTHONDONDONTWRITEBYTECODE`, mais vous pouvez aussi la modifier vous-même pour contrôler la génération des fichiers de bytecode.

`sys.``pycache_prefix`

  If this is set (not `None`), Python will write bytecode-cache `.pyc` files to (and read them from) a parallel directory tree rooted at this directory, rather than from `__pycache__` directories in the source code tree. Any `__pycache__` directories in the source code tree will be ignored and new .pyc files written within the pycache prefix. Thus if you use `compileall` as a pre-build step, you must ensure you run it with the same pycache prefix (if any) that you will use at runtime.

  Un chemin relatif est interprété relativement au répertoire courant.

  Cette valeur est initialement définie basée sur la valeur de l'option de ligne de commande `-X` `pycache_prefix=PATH` ou la variable d'environnement `PYTHONPYCACHEPREFIX` (La ligne de commande est prioritaire). Si aucune des deux options n'est définie, alors la valeur est `None`.

  Nouveau dans la version 3.8.

`sys.``excepthook`(type, value, traceback)

  Cette fonction affiche la traceback et l'exception donnée sur `sys.stderr`.

  Lorsqu'une exception est levée et n'est pas interceptée, l'interpréteur appelle `sys.excepthook` avec trois arguments, la classe de l'exception, l'instance de l'exception, et un objet traceback. Dans une session interactive, cela se produit juste avant que le que l'invite soit rendue. Dans un programme Python, cela se produit juste avant que le programme quitte. La gestion de ces exceptions peut être personnalisé en affectant une autre fonction de trois arguments à `sys.excepthook`.

  Lève un événement d'audit `sys.excepthook` avec les arguments `hook`, `type`, `value`, `traceback`.

  Voir aussi

  La fonction `sys.unraisablehook()` gère les exceptions non-levables et la fonction `threading.excepthook()` gère les exceptions levées par `threading.Thread.run()`.

`sys.``__breakpointhook__`
`sys.``__displayhook__`
`sys.``__excepthook__`
`sys.``__unraisablehook__`

  Ces objets contiennent les valeurs originales de `breakpointhook`, `displayhook`, `excepthook` et `unraisablehook` au début du programme.Ils sont sauvegardés de façon à ce que `breakpointhook`, `displayhook`, `excepthook` et `unraisablehook` puissent être restaurés au cas où ils seraient remplacés par des objets cassés ou alternatifs.

  Nouveau dans la version 3.7: `__breakpointhook__`

  Nouveau dans la version 3.8: `__unraisablehook__`

`sys.``exc_info`()

  Cette fonction renvoie un triplet qui donne des informations sur l'exception actuellement traitée. L'information renvoyée est spécifique à la fois au fil d'exécution courant et à la stack frame courante. Si la stack frame actuelle ne traite pas d'exception, l'information est extraite de la stack frame parente, puis celle appelante, et ainsi de suite jusqu'à trouver une stack frame traitant une exception. Ici, "traiter une exception" signifie "exécute une clause except". Pour chaque stack frame, seule l'information à propos d'une exception actuellement traitée est accessible.

  Si aucune exception n'est actuellement traitée de toute la pile, un triplet de trois `None` sera renvoyé. Autrement, les valeurs renvoyées sont `(type, value, traceback)`. Respectivement type reçoit le type de l'exception traitée (une classe fille de `BaseException`), value reçoit l'instance de l'exception (une instance du type de l'exception), et traceback reçoit un objet traceback qui encapsule la pile d'appels au point où l'exception s'est produite à l'origine.

`sys.``exec_prefix`

  Une chaîne donnant le préfixe de dossier spécifique au site où les fichiers dépendant de la plateforme sont installés. Par défaut, c'est `'/usr/local'`. C'est configurable à la compilation avec l'option `--exec-prefix` du script configure. Tous les fichiers de configurations (tel que `pyconfig,h`) sont installés dans le dossier `exec_prefix/lib/pythonX.Y/config`, et les modules sous forme de bibliothèques partagées sont installés dans `exec_prefix/lib/pythonX.Y/lib-dynload`, où X.Y est le numéro de version de Python, par exemple `3.2`.

  Note

  Si un environment virtuel est actif, cette valeur sera modifiée par `site.py` pour pointer vers l'environnement virtuel. La valeur d'origine sera toujours disponible via `base_exec_prefix`.

`sys.``executable`

  Une chaîne donnant le chemin absolu vers l'interpréteur Python, un fichier binaire exécutable, sur les système sur lesquels ça à du sens. Si Python n'est pas capable de récupérer le chemin réel de son exécutable, `sys.executable` sera une chaîne vide ou `None`.

`sys.``exit`([arg])

  Raise a `SystemExit` exception, signaling an intention to exit the interpreter.

  L'argument optionnel arg peut être un nombre entier donnant l'état de sortie (zéro par défaut), ou un autre type d'objet. Pour les shells (et autres), si c'est un entier, zéro signifie "terminé avec succès", et toutes les autres valeurs signifient "terminé anormalement". La plupart des systèmes imposent qu'il se situe dans la plage 0--127, et leur comportement n'est pas défini pour les autres cas. Certains systèmes peu communs ont pour convention d'assigner un sens particulier à des valeur spécifiques. Les programmes Unix utilisent généralement 2 pour les erreurs de syntaxe dans les arguments de la ligne de commande, et 1 pour toutes les autres erreurs. Si un autre type est passé, `None` est équivalent à zéro, et tout autre objet est écrit sur `stderr` et donne un code de sortie 1. Typiquement, `sys.exit("some error message")` est un moyen rapide de quitter un programme en cas d'erreur.

  Since `exit()` ultimately "only" raises an exception, it will only exit the process when called from the main thread, and the exception is not intercepted. Cleanup actions specified by finally clauses of `try` statements are honored, and it is possible to intercept the exit attempt at an outer level.

  Modifié dans la version 3.6: Si une erreur survient lors du nettoyage après que l'interpréteur Python ait intercepté un `SystemExit` (typiquement une erreur en vidant les tampons des sorties standard), le code de sortie est changé à 120.

`sys.``flags`

  La named tuple flags expose l'état des options de ligne de commande. Ces attributs sont en lecture seule.

  attribut | option
  --- | ---
  `debug` | `-d`
  `inspect` | `-i`
  `interactive` | `-i`
  `isolated` | `-I`
  `optimize` | `-O` or `-OO`
  `dont_write_bytecode` | `-B`
  `no_user_site` | `-s`
  `no_site` | `-S`
  `ignore_environment` | `-E`
  `verbose` | `-v`
  `bytes_warning` | `-b`
  `quiet` | `-q`
  `hash_randomization` | `-R`
  `dev_mode` | `-X dev` (Python en mode développement)
  `utf8_mode` | `-X utf8`
  `int_max_str_digits` | `-X int_max_str_digits` (integer string conversion length limitation)

  Modifié dans la version 3.2: Ajout de l'attribut `quiet` pour la nouvelle option `-q`.

  Nouveau dans la version 3.2.3: L'attribut `hash_randomization`.

  Modifié dans la version 3.3: Suppression de l'attribut obsolète `division_warning`.

  Modifié dans la version 3.4: Ajout de l'attribut `isolated` pour l'option `-I` `isolated`.

  Modifié dans la version 3.7: Ajout de l'attribut `dev_mode` pour le nouveau Mode Développeur Python et l'attribut `utf8_mode` pour la nouvelle option `-X` `utf8`.

  Modifié dans la version 3.9.14: Added the `int_max_str_digits` attribute.

`sys.``float_info`

  Un named tuple contenant des informations à propos du type float. Il contient des informations de bas niveau à propos de la précision et de la représentation interne. Les valeurs correspondent aux différentes constantes à propos des nombres à virgule flottantes définies dans le fichier d'entête `float.h` pour le langage de programmation C. Voir la section 5.2.4.2.2 de 1999 ISO/IEC C standard [C99], Characteristics of floating types, pour plus de détails.

  attribut | macro float.h | explication
  --- | --- | ---
  `epsilon` | DBL_EPSILON | différence entre 1.0 et la plus petite valeur plus grande que 1.0 représentable en float Voir aussi : `math.ulp()`.
  `dig` | DBL_DIG | nombre maximum de décimales pouvant être représentées fidèlement dans un float (voir ci-dessous)
  `mant_dig` | DBL_MANT_DIG | précision : nombre de base-`radix` chiffres dans la mantisse du float
  `max` | DBL_MAX | plus grand `float` fini représentable positif
  `max_exp` | DBL_MAX_EXP | plus grand nombre entier e tel que `radix**(e-1)` soit un nombre à virgule flottante représentable fini
  `max_10_exp` | DBL_MAX_10_EXP | plus grand nombre entier e tel que `10**e` est dans l'intervalle des nombre flottants finis représentables
  `min` | DBL_MIN | plus petit nombre à virgule flottante positif normalisé représentable Utilisez `math.ulp(0.0)` pour obtenir le plus petit nombre a virgule positif dénormalisé représentable.
  `min_exp` | DBL_MIN_EXP | plus petit entier e tel que `radix**(e-1)` est un nombre à virgule flottante normalisé
  `min_10_exp` | DBL_MIN_10_EXP | minimum integer e such that `10**e` is a normalized float
  `radix` | FLT_RADIX | base de la représentation de l'exposant
  `rounds` | FLT_ROUNDS | constante, nombre entier représentant le mode d'arrondi utilisé pour les opérations arithmétiques. Elle reflète la valeur de la macro système FLT_ROUNDS au moment du démarrage de l'interpréteur. Voir section 5.2.4.4.2.2 de la norme C99 pour une explication des valeurs possibles et de leurs significations.

  L'attribut `sys.float_info.dig` nécessite plus d'explications : Si `s` est une chaîne représentant un nombre décimal avec au plus `sys.float_info.dig` chiffres significatifs, alors, convertir `s` en un nombre à virgule flottante puis à nouveau en chaîne redonnera la même valeur :

      >>> import sys
      >>> sys.float_info.dig
      15
      >>> s = '3.14159265358979'    # decimal string with 15 significant digits
      >>> format(float(s), '.15g')  # convert to float and back -> same value
      '3.14159265358979'

  Cependant, pour les chaînes avec plus de `sys.float_info.dig` chiffres significatifs, ce n'est pas toujours vrai :

      >>> s = '9876543211234567'    # 16 significant digits is too many!
      >>> format(float(s), '.16g')  # conversion changes value
      '9876543211234568'

`sys.``float_repr_style`

  Une chaîne indiquant comment la fonction `repr()` se comporte avec les nombres à virgule flottante. Si la chaîne a la valeur `'short'`, alors pour un float finit `x`, `repr(x)` essaye de donner une courte chaîne tel que `float(repr(x)) == x`. C'est le comportement typique à partir de Python 3.1. Autrement, `float_repr_style` a la valeur `'legacy'` et `repr(x)` se comporte comme les versions antérieures à 3.1.

  Nouveau dans la version 3.1.

`sys.``getallocatedblocks`()

  Renvoie le nombre de blocs mémoire actuellement alloués par l'interpréteur, peu importe leur taille. Cette fonction est principalement utile pour pister les fuites de mémoire. À cause des caches internes de l'interpréteur, le résultat peut varier d'un appel à l'autre. Appeler `_clear_type_cache()` et `gc.collect()` peut permettre d'obtenir des résultats plus prévisibles.

  Si Python n'arrive pas a calculer raisonnablement cette information, `getallocatedblocks()` est autorisé à renvoyer 0 à la place.

  Nouveau dans la version 3.4.

`sys.``getandroidapilevel`()

  Renvoie la version de l'API Android utilisée pour compiler sous forme d'un entier.

  Disponibilité : Android.

  Nouveau dans la version 3.7.

`sys.``getdefaultencoding`()

  Renvoie le nom du codage par défaut actuellement utilisé par l'implémentation Unicode pour coder les chaînes.

`sys.``getdlopenflags`()

  Renvoie la valeur actuelle des drapeaux utilisés par les appels de `dlopen()`. Les noms symboliques valeurs peuvent être trouvées dans le module `os`. (Ce sont les constantes `RTLD_xxx` e.g. `os.RTLD_LAZY`).

  Disponibilité : Unix.

`sys.``getfilesystemencoding`()

  Donne le nom de l'encodage utilisé pour les conversions entre les noms de fichiers Unicode et les noms de fichiers en octets. Pour une compatibilité optimale, les noms de fichiers devraient toujours être représentés sous forme de chaînes de caractères, cependant les représenter sous forme d'objet bytes est aussi accepté. Les fonctions acceptant ou renvoyant des noms de fichiers devraient supporter les deux (str ou bytes), et convertir en interne dans la représentation du système.

  Cet encodage est toujours compatible avec ASCII.

  Les fonctions `os.fsencode()` et `os.fsdecode()` devraient être utilisées pour s'assurer qu'un encodage et un gestionnaire d'erreurs correct sont utilisés.

  - Dans le mode UTF-8, l'encodage est `'utf-8'` sur toutes les plate-formes.

  - Sur macOS, l'encodage est `'utf-8'`.

  - Sur Unix, l'encodage est celui des paramètres régionaux.

  - Sur Windows, l'encodage peut être `'utf-8'` ou `'mbcs'`, en fonction des paramètres de l'utilisateur.

  - Sur Android, l'encodage est `'utf-8'`.

  - Sur VxWorks, l'encodage est `'utf-8'`.

  Modifié dans la version 3.2: `getfilesystemencoding()` ne peut plus renvoyer `None`.

  Modifié dans la version 3.6: Sur Windows, on est plus assurés d'obtenir `'mbcs'`. Voir la PEP 529 et `_enablelegacywindowsfsencoding()` pour plus d'informations.

  Modifié dans la version 3.7: Renvoie "utf-8" en mode UTF-8.

`sys.``getfilesystemencodeerrors`()

  Donne le nom du mode de gestion d'erreur utilisé lors de la conversion des noms de fichiers entre Unicode et octets. Le nom de l'encodage est renvoyé par `getfilesystemencoding()`.

  Les fonctions `os.fsencode()` et `os.fsdecode()` devraient être utilisées pour s'assurer qu'un encodage et un gestionnaire d'erreurs correct sont utilisés.

  Nouveau dans la version 3.6.

`sys.``get_int_max_str_digits`()

  Returns the current value for the integer string conversion length limitation. See also `set_int_max_str_digits()`.

  Nouveau dans la version 3.9.14.

`sys.``getrefcount`(object)

  Donne le nombre de référence de l'objet object. Le nombre renvoyé est généralement d'une référence de plus qu'attendu, puisqu'il compte la référence (temporaire) de l'argument à `getrefcount()`.

`sys.``getrecursionlimit`()

  Donne la limite actuelle de la limite de récursion, la profondeur maximum de la pile de l'interpréteur. Cette limite empêche Python de planter lors d'une récursion infinie à cause d'un débordement de la pile. Elle peut être modifiée par `setrecursionlimit()`.

`sys.``getsizeof`(object[, default])

  Donne la taille d'un objet en octets. L'objet peut être de n'importe quel type. Le résultat sera correct pour tous les objets natifs, mais le résultat peut ne pas être toujours vrai pour les extensions, la valeur étant dépendante de l'implémentation.

  Seule la mémoire directement attribuée à l'objet est prise en compte, pas la mémoire consommée par les objets vers lesquels il a des références.

  S'il est fourni, default sera renvoyé si l'objet ne fournit aucun moyen de récupérer sa taille. Sinon, une exception `TypeError` sera levée.

  `getsizeof()` appelle la méthode `__sizeof__` de l'objet, et s'il est géré par lui, ajoute le surcoût du ramasse-miettes.

  Voir la recursive sizeof recipe pour un exemple d'utilisation récursive de `getsizeof()` pour trouver la taille d'un contenant et de son contenu.

`sys.``getswitchinterval`()

  Renvoie la valeur du thread switch interval de l'interpréteur, voir `setswitchinterval()`.

  Nouveau dans la version 3.2.

`sys.``_getframe`([depth])

  Renvoie une frame de la pile d'appels. Si le nombre entier optionnel depth est donné, la frame donnée sera de depth appels depuis le haut de la pile. Si c'est plus profond que la hauteur de la pile, une exception `ValueError` est levée. La profondeur par défaut est zéro, donnant ainsi la frame du dessus de la pile.

  Raises an auditing event `sys._getframe` with no arguments.

  CPython implementation detail: Cette fonction ne devrait être utilisée que pour une utilisation interne et spécifique. Il n'est pas garanti qu'elle existe dans toutes les implémentations de Python.

`sys.``getprofile`()

  Renvoie la fonction de profilage tel que défini par `setprofile()`.

`sys.``gettrace`()

  Renvoie la fonction de traçage tel que définie par `settrace()`.

  CPython implementation detail: La fonction `gettrace()` ne sert que pour implémenter des débogueurs, des profilers, outils d'analyse de couverture, etc…. Son comportement dépend de l'implémentation et non du langage, elle n'est donc pas forcément disponible dans toutes les implémentations de Python.

`sys.``getwindowsversion`()

  Renvoie un n-uplet nommé décrivant la version de Windows en cours d'exécution. Les attributs nommés sont major, minor, build, platform, service_pack, service_pack_minor, service_pack_major, suite_mask, product_type et platform_version. service_pack contient une string, platform_version un triplet, et tous les autres sont des nombres entiers. Ces attributs sont également accessibles par leur nom, donc `sys.getwindowsversion()[0]` est équivalent à `sys.getwindowsversion().major`. Pour des raisons de compatibilité avec les versions antérieures, seuls les 5 premiers éléments sont accessibles par leur indice.

  platform sera `2 (VER_PLATFORM_WIN32_NT)`.

  product_type peut être une des valeurs suivantes :

  Constante | Signification
  --- | ---
  `1 (VER_NT_WORKSTATION)` | Le système une station de travail.
  `2 (VER_NT_DOMAIN_CONTROLLER)` | Le système est un contrôleur de domaine.
  `3 (VER_NT_SERVER)` | Le système est un serveur, mais pas un contrôleur de domaine.

  Cette fonction enveloppe la fonction Win32 `GetVersionEx()`. Voir la documentation de Microsoft sur `OSVERSIONINFOEX()` pour plus d'informations sur ces champs.

  platform_version returns the major version, minor version and build number of the current operating system, rather than the version that is being emulated for the process. It is intended for use in logging rather than for feature detection.

  Note

  platform_version derives the version from kernel32.dll which can be of a different version than the OS version. Please use `platform` module for achieving accurate OS version.

  Disponibilité : Windows.

  Modifié dans la version 3.2: Changé en un n-uplet nommé, et ajout de service_pack_minor, service_pack_major, suite_mask, et product_type.

  Modifié dans la version 3.6: Ajout de platform_version

`sys.``get_asyncgen_hooks`()

  Renvoie un objet asyncgen_hooks, qui est semblable à un `namedtuple` de la forme (firstiter, finalizer), où firstiter et finalizer sont soit `None` ou des fonctions qui prennent un asynchronous generator iterator comme argument, et sont utilisées pour planifier la finalisation d'un générateur asynchrone par un event loop.

  Nouveau dans la version 3.6: Voir la PEP 525 pour plus d'informations.

  Note

  Cette fonction à été ajoutée à titre provisoire (voir la PEP 411 pour plus d'informations.)

`sys.``get_coroutine_origin_tracking_depth`()

  Récupère le nombre de cadres d'exécution conservés par les coroutines pour le suivi de leur création, telle que défini par `set_coroutine_origin_tracking_depth()`.

  Nouveau dans la version 3.7.

  Note

  Cette fonction à été ajoutée à titre provisoire (Voir la PEP 411 pour plus d'informations.) Utilisez la uniquement à des fins de débogage.

`sys.``hash_info`

  Un named tuple donnant les paramètres de l'implémentation de la fonction de hachage de nombres. Pour plus d'informations sur le hachage des types numériques, consultez Hachage des types numériques.

  attribut | explication
  --- | ---
  `width` | Nombre de bits des valeurs de hash
  `modulus` | contient le premier P utilisé dans le modulo pour les hash numériques
  `inf` | valeur du hash pour un infini positif
  `nan` | valeur du hash pour un nan
  `imag` | multiplicateur utilisé pour la partie imaginaire d'un nombre complexe
  `algorithm` | nom de l'algorithme pour le hachage des str, bytes, et memoryview
  `hash_bits` | taille de la sortie interne de l'algorithme de hachage
  `seed_bits` | taille de la seed key utilisée par l'algorithme de hachage

  Nouveau dans la version 3.2.

  Modifié dans la version 3.4: Ajout de algorithm, hash_bits et seed_bits

`sys.``hexversion`

  Le numéro de version codé sous forme d'un seul nombre entier. Ce numéro augmente avec chaque version, y compris pour les versions hors production. Par exemple, pour vérifier que l'interpréteur Python est au moins la version 1.5, utilisez :

      if sys.hexversion >= 0x010502F0:
          # use some advanced feature
          ...
      else:
          # use an alternative implementation or warn the user
          ...

  Cet attribut s'appelle `hexversion` dans le sens où il ne semble avoir du sens que s'il est regardé après avoir été passé à la fonction native `hex()`. Le named tuple `sys.version_info` représente la même information d'une manière plus humaine.

  Consultez Version des API et ABI pour plus d'informations sur `hexversion`.

`sys.``implementation`

  Un objet contenant des informations sur l'implémentation de la version actuelle de l'interpréteur Python. Les attributs suivants existent obligatoirement sur toutes les implémentations Python.

  name est l'identifiant de l'implémentation, e.g. `'cpython'`. Cette chaîne est définie par l'implémentation de Python, mais sera toujours en minuscule.

  version est un n-uplet nommé, du même format que `sys.version_info`. Il représente la version de l'implementation de Python. C'est une information différente de la version du langage auquel l'interpréteur actuel se conforme (donnée par `sys.version_info`). Par exemple, pour PyPy 1.8 `sys.implementation.version` peut valoir `sys.version_info(1, 8, 0, 'final', 0)`, alors que `sys.version_info` peut valoir `sys.version_info(2, 7, 2, 'final', 0)`. Pour CPython ces deux valeurs sont identiques puisque c'est l'implémentation de référence.

  hexversion est la version de l'implémentation sous forme hexadécimale, comme `sys.hexversion`.

  cache_tag est la balise utilisée par le mécanisme d'importation dans les noms de fichiers des modules mis en cache. Par convention, il devrait se composer du nom et de la version de l'implémentation, comme ``cpython-33'`. Cependant, une implémentation Python peut utiliser une autre valeur si nécessaire. ``cache_tag` à `None` signifie que la mise en cache des modules doit être désactivée.

  `sys.implementation` peut contenir d'autres attributs spécifiques à l'implémentation de Python. Ces attributs spécifiques doivent commencer par un underscore, et ne sont pas documentés ici. Indépendamment de son contenu, `sys.implementation` ne change jamais durant l'exécution de l'interpréteur, ni entre les versions d'une même implémentation. (Il peut cependant changer entre les versions du langage Python.) Voir la PEP 421 pour plus d'informations.

  Nouveau dans la version 3.3.

  Note

  L'addition de nouveaux attributs requis doivent passer par le processus de PEP classique. Voir PEP 421 pour plus d'informations.

`sys.``int_info`

  Un named tuple qui contient des informations sur la représentation interne des entiers de Python. Les attributs sont en lecture seule.

  Attribut | Explication
  --- | ---
  `bits_per_digit` | nombre de bits utilisés pour chaque chiffre. Les entiers Python sont stockés en interne en base `2**int_info.bits_per_digit`
  `sizeof_digit` | taille en octets du type C utilisé pour représenter un chiffre
  `default_max_str_digits` | default value for `sys.get_int_max_str_digits()` when it is not otherwise explicitly configured.
  `str_digits_check_threshold` | minimum non-zero value for `sys.set_int_max_str_digits()`, `PYTHONINTMAXSTRDIGITS`, or `-X int_max_str_digits`.

  Nouveau dans la version 3.1.

  Modifié dans la version 3.9.14: Added `default_max_str_digits` and `str_digits_check_threshold`.

`sys.``__interactivehook__`

  Lorsque cet attribut existe, sa valeur est automatiquement appelée (sans argument) par l'interpréteur lors de son démarrage en mode interactif. L'appel se fait après que le fichier `PYTHONSTARTUP` soit lu, afin que vous puissiez y configurer votre fonction. Configuré par le module `site`.

  Lève un évènement d'audit `cpython.run_interactivehook` avec comme argument `hook`.

  Nouveau dans la version 3.4.

`sys.``intern`(string)

  Ajoute string dans le tableau des chaînes "internées" et renvoie la chaîne internée -- qui peut être string elle-même ou une copie. Interner une chaîne de caractères permet de gagner un peu de performance lors de l'accès aux dictionnaires -- si les clés du dictionnaire et la clé recherchée sont internées, les comparaisons de clés (après le hachage) pourront se faire en comparant les pointeurs plutôt que caractère par caractère. Normalement, les noms utilisés dans les programmes Python sont automatiquement internés, et les dictionnaires utilisés pour stocker les attributs de modules, de classes, ou d'instances ont aussi leurs clés internées.

  Les chaînes internées ne sont pas immortelles ; vous devez garder une référence à la valeur renvoyée par `intern()` pour en bénéficier.

`sys.``is_finalizing`()

  Donne `True` si l'interpréteur Python est en train de s'arrêter, et `False` dans le cas contraire.

  Nouveau dans la version 3.5.

`sys.``last_type`
`sys.``last_value`
`sys.``last_traceback`

  Ces trois variables ne sont pas toujours définies. Elles sont définies lorsqu'une exception n'est pas gérée et que l'interpréteur affiche un message d'erreur et une stacktrace. Elles sont là pour permettre à un utilisateur, en mode interactif, d'importer un module de débogage et de faire son débogage post-mortem sans avoir à ré-exécuter la commande qui a causé l'erreur. (L'utilisation typique pour entrer dans le débogueur post-mortem est `import pdb; pdb.pm()`, voir `pdb` pour plus d'informations.).

  La signification de ces variables est la même que celle des valeurs renvoyées par `exc_info()` ci-dessus.

`sys.``maxsize`

  Un entier donnant à la valeur maximale qu'une variable de type `Py_ssize_t` peut prendre. C'est typiquement `2**31 - 1` sur une plateforme 32 bits et `2**63 - 1`` sur une plateforme 64 bits.

`sys.``maxunicode`

  Un entier donnant la valeur du plus grand point de code Unicode, c'est-à-dire `1114111` (``0x10FFFF` en hexadécimal).

  Modifié dans la version 3.3: Avant la PEP 393, `sys.maxunicode` valait soit `0xFFFF` soit `0x10FFFF`, en fonction l'option de configuration qui spécifiait si les caractères Unicode étaient stockés en UCS-2 ou UCS-4.

`sys.``meta_path`

  Une liste d'objets meta path finder qui ont leur méthode `find_spec()` appelée pour voir si un des objets peut trouver le module à importer. La méthode `find_spec()` est appelée avec au moins le nom absolu du module importé. Si le module à importer est contenu dans un paquet, l'attribut `__path__` du paquet parent est donné en deuxième argument. La méthode renvoie un module spec, ou `None` si le module ne peut être trouvé.

  Voir aussi

  `importlib.abc.MetaPathFinder`

    La classe de base abstraite définissant l'interface des objets finder de `meta_path`.

  `importlib.machinery.ModuleSpec`

    La classe concrète dont `find_spec()` devrait renvoyer des instances.

  Modifié dans la version 3.4: Les Module specs ont été introduits en Python 3.4, par la PEP 451. Les versions antérieures de Python cherchaient une méthode appelée `find_module()`. Celle-ci est toujours appelée en dernier recours, dans le cas où une `meta_path` n'a pas de méthode `find_spec()`.

`sys.``modules`

  Un dictionnaire faisant correspondre des noms de modules à des modules déjà chargés. Il peut être manipulé, entre autre, pour forcer un module à être rechargé. Cependant, le remplacer ne fonctionnera pas forcément comme prévu et en supprimer des éléments essentiels peut planter Python.

`sys.``path`

  Une liste de chaînes de caractères spécifiant les chemins de recherche des modules, initialisée à partir de la variable d'environnement `PYTHONPATH` et d'une valeur par défaut dépendante de l'installation.

  Puisqu'il est initialisé au démarrage du programme, le premier élément de cette liste, `path[0]`, est le dossier contenant le script qui a été utilisé pour invoquer l'interpréteur Python. Si le dossier du script n'est pas disponible (typiquement, si l'interpréteur est invoqué interactivement ou si le script est lu à partir d'une entrée standard), `path[0]` sera une chaîne vide, qui indiquera à Python de chercher des modules dans le dossier actuel. Notez que le dossier du script est inséré avant les dossiers de `PYTHONPATH`.

  Un programme est libre de modifier cette liste pour ses propres besoins. Seuls des str ou des bytes ne devraient être ajoutés à `sys.path`, tous les autres types de données étant ignorés durant l'importation.

  Voir aussi

  Le module `site` décrit comment utiliser les fichiers .pth pour étendre `sys.path`.

`sys.``path_hooks`

  Une liste d'appelables d'un argument, path, pour essayer de créer un finder pour ce chemin. Si un finder peut être créé, il doit être renvoyé par l'appelable, sinon une `ImportError` doit être levée.

  Précisé à l'origine dans la PEP 302.

`sys.``path_importer_cache`

  Un dictionnaire faisant office de cache pour les objets finder. Les clés sont les chemins qui ont été passés à `sys.path_hooks` et les valeurs sont les finders trouvés. Si un chemin est valide selon le système de fichiers mais qu'aucun finder n'est trouvé dans `sys.path_hooks`, `None` est stocké.

  Précisé à l'origine dans la PEP 302.

  Modifié dans la version 3.3: `None` est stocké à la place de `imp.NullImporter` si aucun localisateur n'est trouvé.

`sys.``platform`

  Cette chaîne contient un identificateur de plateforme qui peut être typiquement utilisé pour ajouter des composants spécifiques à `sys.path`.

  Pour les systèmes Unix, sauf sur Linux et AIX, c'est le nom de l'OS en minuscules comme renvoyé par `uname -s` suivi de la première partie de la version comme renvoyée par `uname -r`, e.g. `'sunos5'` ou `'freebsd8'`, au moment où Python a été compilé. A moins que vous ne souhaitiez tester pour une version spécifique du système, vous pouvez faire comme suit :

      if sys.platform.startswith('freebsd'):
          # FreeBSD-specific code here...
      elif sys.platform.startswith('linux'):
          # Linux-specific code here...
      elif sys.platform.startswith('aix'):
          # AIX-specific code here...

  Pour les autres systèmes, les valeurs sont :

  Le système une station de travail. | Valeur pour `plateforme`
  --- | ---
  AIX | `'aix'`
  Linux | `'linux'`
  Windows | `'win32'`
  Windows/Cygwin | `'cygwin'`
  macOS | `'darwin'`

  Modifié dans la version 3.3: Sur Linux, `sys.platform` ne contient plus la version majeure, c'est toujours `'linux'`, au lieu de `'linux2'` ou `'linux3'`. Comme les anciennes versions de Python incluent le numéro de version, il est recommandé de toujours utiliser `startswith`, tel qu'utilisé ci-dessus.

  Modifié dans la version 3.8: Sur AIX, `sys.platform` ne contient plus la version majeure, c'est toujours `'aix'`, au lieu de `'aix5'` ou `'aix7'`. Comme les anciennes versions de Python incluent le numéro de version, il est recommandé de toujours utiliser `startswith`, tel qu'utilisé ci-dessus.

  Voir aussi

  `os.name` a une granularité plus grossière. `os.uname()` donne des informations sur la version dépendantes du système.

  Le module `platform` fournit des vérifications détaillées pour l'identité du système.

`sys.``platlibdir`

  Nom du dossier de la bibliothèque spécifique à la plateforme. Il est utilisé pour construire le chemin de vers la bibliothèque standard et les chemins vers les modules d'extensions installés.

  C'est égal à `"lib"` sur la plupart des plateformes. Sur Fedora et SuSE, c'est égal à `"lib64"` sur les plateformes 64-bits qui renvoient les chemins `sys.path` suivants (où `X.Y` et la version `majeure.mineur` de Python) :

  - `/usr/lib64/pythonX.Y/` : Bibliothèque standard (comme `os.py` du module `os`)

  - `/usr/lib64/pythonX.Y/lib-dynload/` : Modules d'extension C de la bibliothèque standard (comme le module `errno`, le nom du fichier exact est spécifique à la plateforme)

  - `/usr/lib/pythonX.Y/site-packages/` (toujours utiliser `lib`, et non `sys.platlibdir`) : modules tiers

  - `/usr/lib64/pythonX.Y/site-packages/` : Modules d'extension C de paquets tiers

  Nouveau dans la version 3.9.

`sys.``prefix`

  A string giving the site-specific directory prefix where the platform independent Python files are installed; on Unix, the default is `'/usr/local'`. This can be set at build time with the `--prefix` argument to the configure script. See Installation paths for derived paths.

  Note

  Si a environnement virtuel est activé, cette valeur sera changée par `site py` pour pointer vers l'environnement virtuel. La valeur donnée au moment de la compilation de Python sera toujours disponible, dans `base_prefix`.

`sys.``ps1`
`sys.``ps2`

  Chaînes spécifiant l'invite primaire et secondaire de l'interpréteur. Celles-ci ne sont définies que si l'interpréteur est en mode interactif. Dans ce cas, leurs valeurs initiales sont `'>>>'` et `'...'`. Si un objet qui n'est pas une chaîne est assigné à l'une ou l'autre variable, sa méthode `str()` sera appelée à chaque fois que l'interpréteur se prépare à lire une nouvelle commande interactive, c'est donc utilisable pour implémenter une invite dynamique.

`sys.``setdlopenflags`(n)

  Définit les options utilisées par l'interpréteur lors des appels à `dlopen()`, typiquement utilisé par l'interpréteur pour charger des modules d'extension. Permet entre autre de résoudre tardivement les symboles lors des importations de modules (si appelé `sys.setdlopenflags(0)`). Pour partager les symboles entre modules, appelez `sys.setdlopenflags(os.RTLD_GLOBAL)`. Les noms pour les valeurs de ces options peuvent être trouvés dans le module `os` (ce sont les constantes `RTLD_xxx`, comme `os.RTLD_LAZY`).

  Disponibilité : Unix.

`sys.``set_int_max_str_digits`(n)

  Set the integer string conversion length limitation used by this interpreter. See also `get_int_max_str_digits()`.

  Nouveau dans la version 3.9.14.

`sys.``setprofile`(profilefunc)

  Définit la fonction de profilage du système, qui vous permet d'implémenter un profileur de code source Python en Python. Voir le chapitre The Python Profilers pour plus d'informations sur le profileur Python. La fonction de profilage du système est appelée de la même façon que la fonction trace du système (voir `settrace()`), mais elle est appelée pour des évènements différents, par exemple elle n'est pas appelée à chaque ligne de code exécutée (seulement sur appel et retours, mais l'événement pour les retours est appelé même en cas d'exception). Cette fonction est locale au fil d'exécution, et il n'existe aucun moyen, du point de vue du profileur, de prendre conscience des changements de contextes entre fils d'exécution, ça n'a donc aucun sens d'utiliser cette fonction dans un contexte multithread. Sa valeur de retour n'est pas utilisée, elle peut simplement renvoyer `None`.

  Les fonctions de traçage doivent avoir trois arguments : frame, event, et arg. frame est la stack frame actuelle. event est une chaîne de caractères pouvant valoir : `'call'`, `'return'`, `'c_call'`, `'c_return'` ou `'c_exception'`. arg dépend du type de l'évènement.

  Lève un évènement d'audit `sys.setprofile` sans arguments.

  Les événements ont la signification suivante :

  `'call'`

    Une fonction est appelée (ou Python entre dans un autre bloc de code). La fonction de traçage est appelée, arg est `None`.

  `'return'`

    La fonction (ou un autre type de bloc) est sur le point de se terminer. La fonction de traçage est appelée, arg est la valeur qui sera renvoyée, ou `None` si l'événement est causé par la levée d'une exception.

  `'c_call'`

    Une fonction C est sur le point d'être appelée. C'est soit une fonction d'extension ou une fonction native. arg représente la fonction C.

  `'c_return'`

    Une fonction C a renvoyé une valeur. arg représente la fonction C.

  `'c_exception'`

    Une fonction C a levé une exception. arg représente la fonction C.

`sys.``setrecursionlimit`(limit)

  Définit la profondeur maximale de la pile de l'interpréteur Python à limit. Cette limite empêche une récursion infinie de provoquer un débordement de la pile C et ainsi un crash de Python.

  La limite haute dépend de la plate-forme. Un utilisateur pourrait avoir besoin de remonter la limite, lorsque son programme nécessite une récursion profonde, si sa plate-forme le permet. Cela doit être fait avec précaution, car une limite trop élevée peut conduire à un crash.

  Si la nouvelle limite est plus basse que la profondeur actuelle, une `RecursionError` est levée.

  Modifié dans la version 3.5.1: Une `RecursionError` est maintenant levée si la nouvelle limite est plus basse que la profondeur de récursion actuelle.

`sys.``setswitchinterval`(interval)

  Configure l'intervalle de bascule des fils d'exécution de l'interpréteur (en secondes). Ce nombre à virgule flottante détermine la durée idéale allouée aux fils d'exécution en cour d'exécution (durée appelée timeslices). Notez que la durée observée peut être plus grande, typiquement si des fonctions ou méthodes prenant beaucoup de temps sont utilisées. Aussi, le choix du fil d'exécution prenant la main à la fin de l'intervalle revient au système d'exploitation. L'interpréteur n'a pas son propre ordonnanceur.

  Nouveau dans la version 3.2.

`sys.``settrace`(tracefunc)

  Définit la fonction de traçage du système, qui vous permet d'implémenter un débogueur de code source Python en Python. Cette fonction est locale au fil d'exécution courant. Pour qu'un débogueur puisse gérer plusieurs fils d'exécution, il doit enregistrer sa fonction en appelant `settrace()` pour chaque fil d'exécution qu'il souhaite surveiller ou utilisez `threading.settrace()`.

  Les fonctions de traçage doivent avoir trois arguments : frame, event, et arg. frame est la stack frame actuelle. event est une chaîne de caractères pouvant valoir : `'call'`, `'line'`, `'return'`, `'exception'` ou `'opcode'`. arg dépend du type de l'évènement.

  La fonction de traçage est appelée (avec event à `'call'`) à chaque fois que l'interpréteur entre dans un nouveau scope. Elle doit renvoyer une référence à une fonction de traçage locale à utiliser pour ce scope, ou `None` si le Scope ne doit pas être tracé.

  La fonction de traçage doit renvoyer une référence à elle-même (ou à une autre fonction de traçage pour un traçage ultérieur dans cette portée), ou `None` pour désactiver le traçage dans cette portée.

  Si une erreur se produit dans la fonction de trace, elle sera désactivée, tout comme si `settrace(None)` avait été appelée.

  Les événements ont la signification suivante :

  `'call'`

    Une fonction est appelée (un un bloc de code). La fonction de traçage globale est appelée, arg est `None`, la valeur renvoyée donne la fonction de traçage locale.

  `'line'`

    L'interpréteur est sur le point d'exécuter une nouvelle ligne de code ou de ré-exécuter la condition d'une boucle. La fonction de traçage locale est appelée, arg vaut `None`, et la valeur de retour donne la nouvelle fonction de traçage locale. Voir `Objects/lnotab_notes.txt` pour une explication détaillée de ce mécanisme. Les évènements par ligne peuvent être désactivés pour un cadre d'exécution en mettant `f_trace_lines` à `False` pour ce cadre d'exécution.

  `'return'`

    La fonction (ou un autre type de bloc) est sur le point de se terminer. La fonction de traçage locale est appelée, arg est la valeur qui sera renvoyée, ou `None` si l'événement est causé par la levée d'une exception. La valeur renvoyée par la fonction de traçage est ignorée.

  `'exception'`

    Une exception est survenue. La fonction de traçage locale est appelée, arg est le triplet `(exception, valeur, traceback)`, la valeur renvoyée spécifie la nouvelle fonction de traçage locale.

  `'opcode'`

    L'interpréteur va exécuter un nouvel opcode (voyez `dis` pour plus de détails). La fonction de traçage locale est appelée ; arg vaut `None` ; la valeur retournée donne la nouvelle fonction de traçage locale. Le traçage ne se fait pas opcode par opcode par défaut : cela doit être explicitement requis en mettant `f_trace_opcodes` à `True` pour cette frame.

  Remarquez que, comme une exception se propage au travers de toute chaîne d'appelants, un événement `'exception'` est généré à chaque niveau.

  Pour une utilisation plus fine, il est possible de définir une fonction de traçage en assignant `frame.f_trace = tracefunc` explicitement, plutôt que de s'appuyer sur le fait qu'elle soit définie indirectement par la valeur de retour d'une fonction trace déjà installée. Cela est aussi demandé pour l'activation de la fonction de traçage dans le cadre, ce que `settrace()` ne fait pas. Notez que pour que cela fonctionne, une fonction globale de traçage doit avoir été installée avec `settrace()` afin d'activer le mécanisme de traçage au moment de l'exécution, mais il n'est pas nécessaire que ce soit la même fonction de traçage (Par exemple, cela pourrait être une fonction de traçage avec peu de surcharge qui retourne simplement `None` pour se désactiver immédiatement à chaque cadre).

  Pour plus d'informations sur les objets code et objets représentant une frame de la pile, consultez Hiérarchie des types standards.

  Lève un évènement d'audit `sys.settrace` sans arguments.

  CPython implementation detail: La fonction `settrace()` est destinée uniquement à l'implémentation de débogueurs, de profileurs, d'outils d'analyse de couverture et d'autres outils similaires. Son comportement fait partie de l'implémentation, plutôt que de la définition du langage, et peut donc ne pas être disponible dans toutes les implémentations de Python.

  Modifié dans la version 3.7: Ajout du type d’événement `'opcode'` ; les attributs `f_trace_lines` et `f_trace_opcodes` ont été ajoutés aux cadres d'exécution

`sys.``set_asyncgen_hooks`(firstiter, finalizer)

  Accepte deux arguments optionnels nommés, qui sont appelables qui acceptent un asynchronous generator iterator comme argument. L'appelable firsttiter sera appelé lorsqu'un générateur asynchrone sera itéré pour la première fois, et l'appelable finalizer sera appelé lorsqu'un générateur asynchrone est sur le point d'être détruit.

  Lève un évènement d'audit `sys.set_asyncgen_hooks_firstiter` sans arguments.

  Lève un événement d'audit `sys.set_asyncgen_hooks_finalizer` sans arguments.

  Deux événements d'audit sont levés car l'API sous-jacente consiste de deux appels, dont chacun doit lever son propre événement.

  Nouveau dans la version 3.6: Voir la PEP 525 pour plus de détails. Pour un exemple de finalizer, voir l'implémentation de `asyncio.Loop.shutdown_asyncgens` dans Lib/asyncio/base_events.py

  Note

  Cette fonction à été ajoutée à titre provisoire (voir la PEP 411 pour plus d'informations.)

`sys.``set_coroutine_origin_tracking_depth`(depth)

  Permet d'activer ou de désactiver le suivi d'origine de la coroutine. Lorsque cette option est activée, l'attribut `cr_origin` sur les objets de la coroutine contient un n-uplet de triplets (nom de fichier, numéro de ligne, nom de fonction) gardant la trace d'appels de l'endroit où l'objet coroutine a été créé, avec l'appel le plus récent en premier. Lorsqu'il est désactivé, la valeur de `cr_origin` est `None`.

  Pour l'activer, passez une valeur depth supérieure à zéro ; cela définit le nombre de cadres d'exécution dont les informations sont capturées. Pour le désactiver, mettez depth à zéro.

  Ce paramètre est spécifique au fil d'exécution courant.

  Nouveau dans la version 3.7.

  Note

  Cette fonction à été ajoutée à titre provisoire (Voir la PEP 411 pour plus d'informations.) Utilisez la uniquement à des fins de débogage.

`sys.``_enablelegacywindowsfsencoding`()

  Change l'encodage et le mode de gestion d'erreur par défaut du système de fichiers à mbcs et replace respectivement, par cohérence avec les versions de Python antérieures à la 3.6.

  Équivaut à définir la variable d'environnement `PYTHONLEGACYWINDOWSFSENCODING` avant de lancer Python.

  Disponibilité : Windows.

  Nouveau dans la version 3.6: Voir la PEP 529 pour plus d'informations.

`sys.``stdin`
`sys.``stdout`
`sys.``stderr`

  objets fichiers utilisés par l'interpréteur pour l'entrée standard, la sortie standard et la sortie d'erreurs :

  - `stdin` est utilisé pour toutes les entrées interactives (y compris les appels à `input()`)

  - `stdout` est utilisé pour la sortie de `print()`, des expression et pour les invites de `input()` ;

  - Les invites de l'interpréteur et ses messages d'erreur sont écrits sur `stderr`.

  Ces flux sont de classiques fichiers texte comme ceux renvoyés par la fonction `open()`. Leurs paramètres sont choisis comme suit :

  - L'encodage des caractères dépend de la plateforme. Les plateformes non Windows utilisent l'encodage défini dans les paramètres régionaux (voir `locale.getpreferredencoding()`).

    Sous Windows, UTF-8 est utilisé pour le périphérique de console. Les périphériques non-caractères tels que les fichiers de disque et les tubes (pipe en anglais) utilisent l'encodage des paramètres régionaux du système (c'est-à-dire la page de codes ANSI). Les périphériques de caractères non-console tels que NUL (par exemple où `isatty()` renvoie `True`) utilisent la valeur des pages de code d'entrée et de sortie de la console au démarrage, respectivement pour l’entrée standard et la sortie standard/sortie d'erreur. Cette valeur par défaut est l'encodage des paramètres régionaux système si le processus n'est pas attaché initialement à une console.

    Le comportement spécial de la console peut être redéfini en assignant la variable d'environnement PYTHONLEGACYWINDOWSSTDIO avant de démarrer Python. Dans ce cas, les pages de code de la console sont utilisées comme pour tout autre périphérique de caractères.

    Sous toutes les plateformes, vous pouvez redéfinir le codage de caractères en assignant la variable d'environnement `PYTHONIOENCODING` avant de démarrer Python ou en utilisant la nouvelle option de ligne de commande `-X` `utf8` et la variable d'environnement `PYTHONUTF8`. Toutefois, pour la console Windows, cela s'applique uniquement lorsque `PYTHONLEGACYWINDOWSSTDIO` est également défini.

  - When interactive, the `stdout` stream is line-buffered. Otherwise, it is block-buffered like regular text files. The `stderr` stream is line-buffered in both cases. You can make both streams unbuffered by passing the `-u` command-line option or setting the `PYTHONUNBUFFERED` environment variable.

  Modifié dans la version 3.9: Le `stderr` non interactif est maintenant mis en mémoire-tampon ligne par ligne plutôt qu'entièrement.

  Note

  Pour écrire ou lire des données binaires depuis ou vers les flux standards, utilisez l'objet sous-jacent `buffer`. Par exemple, pour écrire des octets sur `stdout`, utilisez `sys.stdout.buffer.write(b'abc')`.

  Cependant, si vous écrivez une bibliothèque (ou ne contrôlez pas dans quel contexte son code sera exécuté), sachez que les flux standards peuvent être remplacés par des objets de type fichier tel un `io.StringIO` qui n'ont pas l'attribut `buffer`.

`sys.``__stdin__`
`sys.``__stdout__`
`sys.``__stderr__`

  Ces objets contiennent les valeurs d'origine de `stdin`, `stderr` et `stdout` tel que présentes au début du programme. Ils sont utilisés pendant la finalisation, et peuvent être utiles pour écrire dans le vrai flux standard, peu importe si l'objet `sys.std*` a été redirigé.

  Ils peuvent également être utilisés pour restaurer les entrées / sorties d'origine, au cas où ils auraient été écrasés par des objets cassé, cependant la bonne façon de faire serait de sauvegarder explicitement les flux avant de les remplacer et ainsi pouvoir les restaurer.

  Note

  Dans certaines cas, `stdin`, `stdout` et `stderr` ainsi que les valeurs initiales `__stdin__`, `__stdout__` et `__stderr__` peuvent être `None`. C'est typiquement le cas pour les applications graphiques sur Windows qui ne sont pas connectées à une console, ou les applications Python démarrées avec pythonw.

`sys.``thread_info`

  Un named tuple contenant des informations sur l'implémentation des fils d'exécution.

  Attribut | Explication
  --- | ---
  `name` | Nom de l'implémentation des fils d'exécution : `'nt'` : Fils d'exécution Windows `'pthread'` : Fils d'exécution POSIX `'solaris'` : Fils d'exécution Solaris
  `lock` | Nom de l'implémentation du système de verrou : `'semaphore'` : Verrou utilisant une sémaphore `'mutex+cond'` : Un verrou utilisant un mutex et une condition variable `None` si cette information n'est pas connue
  `version` | Nom et version de l'implémentation des fils d'exécution, c'est une chaîne, ou `None` si ces informations sont inconnues.

  Nouveau dans la version 3.3.

`sys.``tracebacklimit`

  Lorsque cette variable contient un nombre entier, elle détermine la profondeur maximum de la pile d'appels affichée lorsqu'une exception non gérée se produit. La valeur par défaut est `1000`, lorsque cette valeur est égale ou inférieure à `0`, la pile d'appels n'est pas affichée, seul seuls le type et la valeur de l'exception sont le sont.

`sys.``unraisablehook`(unraisable, /)

  Gère une exception non levable (unraisable en anglais)

  Appelé lorsqu'une exception s'est produite mais qu'il n'y a aucun moyen pour Python de la gérer. Par exemple, lorsqu'un destructeur lève une exception ou durant le passage du ramasse-miettes (`gc.collect()`).

  Les arguments unraisable ont la signification suivante :

  - exc_type : le type de l'exception ;

  - exc_value: la valeur de l'exception, peut être `None` ;

  - exc_traceback : la pile d'appels pour cette exception, peut être `None` ;

  - err_msg : Message d'erreur, peut être `None`.

  - object : Objet causant l'exception, peut être `None`.

  Le point d'entrée par défaut formate err_msg et object de la façon suivante : `f'{err_msg}: {object!r}'`; sinon utilise "Exception ignored in" dans le message d'erreur si err_msg est à `None`.

  `sys.unraisablehook()` peut être remplacé pour contrôler comment les exceptions non levables (unraisable en anglais) sont gérées.

  Stocker exc_value en utilisant une fonction de rappel personnalisée peut créer un cycle de références. exc_value doit être nettoyée explicitement pour casser ce cycle lorsque l'exception n'est plus nécessaire.

  Storing object using a custom hook can resurrect it if it is set to an object which is being finalized. Avoid storing object after the custom hook completes to avoid resurrecting objects.

  Voir aussi `excepthook()` qui gère les exceptions non levables.

  Lève un événement d'audit `sys.unraisablehook` avec comme arguments `hook`, `unraisable` lorsqu'une exception qui ne peut être gérée se produit. L'objet `unraisable` est le même qui sera passé au point d'entrée. Si aucun point d'entrée n'est défini, `hook` peut être `None`.

  Nouveau dans la version 3.8.

`sys.``version`

  Une chaîne contenant le numéro de version de l'interpréteur Python, ainsi que d'autres informations comme le numéro de compilation et le compilateur utilisé. Cette chaîne est affichée lorsque l'interpréteur est démarré en mode interactif. N'essayez pas d'en extraire des informations de version, utilisez plutôt `version_info` et les fonctions fournies par le module `platform`.

`sys.``api_version`

  La version de l'API C pour cet interpréteur. Les développeurs peuvent trouver cette information utile en déboguant des conflits de versions entre Python et des modules d'extension.

`sys.``version_info`

  Un quintuplet contenant les composants du numéro de version : major, minor, micro, releaselevel et serial. Toutes les valeurs sauf releaselevel sont des nombres entiers. releaselevel peut valoir `'alpha'`, `'beta'`, `'candidate'`, ou `'final'`. La valeur de `version_info` pour Python 2.0 est `(2, 0, 0, 'final', 0)`. Ces attributs sont aussi accessibles par leur nom, ainsi `sys.version_info[0]` est équivalent à `sys.version_info.major`, et ainsi de suite.

  Modifié dans la version 3.1: Ajout des attributs nommés.

`sys.``warnoptions`

  C'est une spécificité de l'implémentation de la gestion des avertissements. Ne modifiez pas cette valeur. Reportez-vous au module `warnings` pour plus d'informations sur le gestionnaire d'avertissements.

`sys.``winver`

  Le numéro de version utilisé pour construire les clefs de registre sous Windows. Elle est stockée en tant que string resource 1000 dans la DLL Python. Cette valeur équivaut typiquement aux trois premiers caractères de `version`. Elle est fournie par le module `sys` à titre d'information, et la modifier n'a aucun effet sur les clés de registre utilisées par Python.

  Disponibilité : Windows.

`sys.``_xoptions`

  Un dictionnaire des différentes options spécifiques à l'implémentation passés en ligne de commande via l'option `-X`. Aux noms des options correspondent soit leur valeur, si elle est donnée explicitement, soit à `True`. Exemple :

      $ ./python -Xa=b -Xc
      Python 3.2a3+ (py3k, Oct 16 2010, 20:14:50)
      [GCC 4.4.3] on linux2
      Type "help", "copyright", "credits" or "license" for more information.
      >>> import sys
      >>> sys._xoptions
      {'a': 'b', 'c': True}

  CPython implementation detail: C'est un moyen spécifique à CPython pour accéder aux options passées via l'option `-X`. D'autres implémentations pourraient les exposer par d'autres moyens, ou pas du tout.

  Nouveau dans la version 3.2.

Citations

C99

  ISO/IEC 9899:1999. "Langages de programmation -- C." Un texte public de ce standard est disponible à http://www.open-std.org/jtc1/sc22/wg14/www/docs/n1256.pdf.