29.1. `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¶: Les ABI flags tels que définis par la PEP 3149, sur des systèmes POSIX où Python a été compilé normalement avec le script configure.

Nouveau dans la version 3.2.

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.

sys.base_exec_prefix¶: Défini au démarrage de Python, avant que site.py ne soit évalué, à la même valeur que exec_prefix. Hors d’un virtual environment, les valeurs resteront les mêmes; si site.py détecte qu’un environnement virtuel est utilisé, les valeurs de prefix et exec_prefix seront modifiées point pointer vers l’environnement virtuel, alors que base_prefix et base_exec_prefix pointeront toujours à la racine de l’installation de Python (celui utilisé pour créer l’environnement virtuel).

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 virtual environment, les valeurs resteront les mêmes; si site.py détecte qu’un environnement virtuel est utilisé, les valeurs de prefix et exec_prefix seront modifiées point pointer vers l’environnement virtuel, alors que base_prefix et base_exec_prefix pointeront 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 tuple 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é.

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.

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) n’est pas encodable avec sys.stdout.encoding avec le gestionnaire d’erreur sys.stdout.errors (qui est probablement 'strict'), elle sera encodée par sys.stdout.encoding avec 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’import 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.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 attrapé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.

sys.__displayhook__¶
sys.__excepthook__¶: Ces objets contiennent les valeurs originales de displayhook et excepthook au début du programme. Elles sont sauvegardées de façon à ce que displayhook et excepthook puisse être restaurées au cas où elles seraient remplacées par des objets cassés.

sys.exc_info()¶

Cette fonction renvoie un tuple de trois valeurs qui donnent 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 tuple contenant 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 (voir le Manuel de Référence) 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])¶

Quitte Python. C’est implémente en levant l’exception SystemExit, afin que toutes les actions de nettoyage spécifiées par des clauses finally des instructions try soient correctement exécutées. Il est aussi possible d’intercepter la tentative de sortie à un niveau au dessus.

The optional argument arg can be an integer giving the exit status (defaulting to zero), or another type of object. If it is an integer, zero is considered « successful termination » and any nonzero value is considered « abnormal termination » by shells and the like. Most systems require it to be in the range 0–127, and produce undefined results otherwise. Some systems have a convention for assigning specific meanings to specific exit codes, but these are generally underdeveloped; Unix programs generally use 2 for command line syntax errors and 1 for all other kind of errors. If another type of object is passed, None is equivalent to passing zero, and any other object is printed to stderr and results in an exit code of 1. In particular, sys.exit("some error message") is a quick way to exit a program when an error occurs.

Puisque la fonction exit() ne fait « que » lever une exception, elle ne fera quitter le processus que si elle est appelée depuis le fil d’exécution principal, et que l’exception n’est pas interceptée.

sys.flags¶

La struct sequence flags expose l’état des options de ligne de commande. Ces attributs sont en lecture seule.

attribut	option
`debug`	`-d`
`inspect`	`-i`
`interactive`	`-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`

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.

sys.float_info¶

Un struct sequence 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. 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 et la plus petite valeur plus grande que 1 représentable en float
`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
`max_exp`	DBL_MAX_EXP	plus grand nombre entier e tel que `radix*(e-1)` soit représentable sous forme de float* finit
`max_10_exp`	DBL_MAX_10_EXP	plus grand nombre entier e tel que `10**e` est dans l’intervalle des nombre flottants finis
`min`	DBL_MIN	plus petit nombre à virgule flottante positif normalisé
`min_exp`	DBL_MIN_EXP	plus petit entier e tel que `radix*(e-1)` est un float* normalisé
`min_10_exp`	DBL_MIN_10_EXP	plus petit nombre entier e tel que `10**e` est un nombre à virgule flottante normalisé
`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.getcheckinterval()¶: Renvoie le check interval de l’interpréteur, voir setcheckinterval().

Obsolète depuis la version 3.2: Utilisez plutôt getswitchinterval().

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 flags 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()¶

Return the name of the encoding used to convert Unicode filenames into system file names. The result value depends on the operating system:

Sur Mac OS X, l’encodage est 'utf-8'.
On Unix, the encoding is the user’s preference according to the result of nl_langinfo(CODESET).
On Windows NT+, file names are Unicode natively, so no conversion is performed. getfilesystemencoding() still returns 'mbcs', as this is the encoding that applications should use when they explicitly want to convert Unicode strings to byte strings that are equivalent when used as file names.
On Windows 9x, the encoding is 'mbcs'.

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

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.

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

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()¶

Return a named tuple describing the Windows version currently running. The named elements are major, minor, build, platform, service_pack, service_pack_minor, service_pack_major, suite_mask, and product_type. service_pack contains a string while all other values are integers. The components can also be accessed by name, so sys.getwindowsversion()[0] is equivalent to sys.getwindowsversion().major. For compatibility with prior versions, only the first 5 elements are retrievable by indexing.

platform may be one of the following values:

Constante	Plateforme
`0 (VER_PLATFORM_WIN32s)`	Win32s on Windows 3.1
`1 (VER_PLATFORM_WIN32_WINDOWS)`	Windows 95/98/ME
`2 (VER_PLATFORM_WIN32_NT)`	Windows NT/2000/XP/x64
`3 (VER_PLATFORM_WIN32_CE)`	Windows CE

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.

Disponibilité : Windows.

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

sys.get_coroutine_wrapper()¶: Renvoie None, ou un wrapper donné via set_coroutine_wrapper().

Nouveau dans la version 3.5: Voir la PEP 492 pour plus d’informations.

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¶

Une struct sequence 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(). La struct sequence 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 named tuple, 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.

sys.int_info¶

Un struct sequence 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

Nouveau dans la version 3.1.

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.

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

Pour les autres systèmes, les valeurs sont:

Système	Valeur pour `plateforme`
Linux	`'linux'`
Windows	`'win32'`
Windows/Cygwin	`'cygwin'`
Mac OS X	`'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.

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.prefix¶: Une chaîne donnant le préfixe de répertoire spécifique au site dans lequel les fichiers Python indépendants de la plate-forme sont installés. Par défaut, c’est '/usr/local'. Ceci peut être défini à la compilation en passant l’argument --prefix au script configure. La collection principale des modules de la bibliothèque Python est installée dans le dossier prefix/lib/pythonX.Y et les entêtes indépendantes de la plateforme (toutes sauf pyconfig.h) sont stockées dans prefix/include/pythonX.Y, où X.Y est le numéro de version de Python, par exemple 3.2.

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.setcheckinterval(interval)¶: Défini l“« intervalle de vérification » de l’interpréteur. Ce nombre entier détermine la fréquence à laquelle l’interpréteur effectue des tâches périodiques tels que la commutation de fil d’exécution et la gestion de signaux. La valeur par défaut est 100, ce qui signifie que le contrôle est effectué toutes les 100 instructions virtuelles Python. L’augmenter peut améliorer les performances des programmes utilisant des fils d’exécution. Le paramétrer à une valeur inférieure ou égale à zéro permet d’effectuer ces tâches à chaque instruction virtuelle, maximisant ainsi la réactivité mais aussi son surcoût.

Obsolète depuis la version 3.2: Cette fonction n’a plus aucun effet : La logique interne de commutation de fils d’exécution et de gestion des tâches asynchrones ayant été réécrite. Utilisez setswitchinterval() à la place.

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 imports 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.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 (voir settrace()), mais 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 thread, et il n’existe aucun moyen, du point de vue du profileur, de prendre conscience des changements de contextes entre threads, ç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.

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.

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', 'c_call', 'c_return', ou 'c_exception'. 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.

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.
'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 tuple (exception, valeur, traceback), la valeur renvoyée spécifie la nouvelle fonction de traçage locale.
'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.

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 plus d’informations sur les objets code et objets représentant une frame de la pile, consultez Hiérarchie des types standards.

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.

sys.settscdump(on_flag)¶: Activate dumping of VM measurements using the Pentium timestamp counter, if on_flag is true. Deactivate these dumps if on_flag is off. The function is available only if Python was compiled with --with-tsc. To understand the output of this dump, read Python/ceval.c in the Python sources.

CPython implementation detail: This function is intimately bound to CPython implementation details and thus not likely to be implemented elsewhere.

sys.set_coroutine_wrapper(wrapper)¶

Permet d’intercepter la création de coroutine (uniquement celles créés via async def, les générateurs décorés par types.coroutine() ou asyncio.coroutine() ne seront pas interceptés).

L’argument wrapper doit être soit :

un appelable qui accepte un argument (une coroutine);
None, pour réinitialiser le wrapper.

S’il est appelé deux fois, le nouveau wrapper remplace le précédent.

L’appelable wrapper ne peut pas définir de nouvelles coroutines, ni directement, ni indirectement :

def wrapper(coro):
    async def wrap(coro):
        return await coro
    return wrap(coro)
sys.set_coroutine_wrapper(wrapper)

async def foo():
    pass

# The following line will fail with a RuntimeError, because
# ``wrapper`` creates a ``wrap(coro)`` coroutine:
foo()

Voir aussi get_coroutine_wrapper().

Nouveau dans la version 3.5: Voir la PEP 492 pour plus d’informations.

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

sys.stdout¶

sys.stderr¶

objects fichier utilisé 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 plate-forme. Sous Windows, si le flux est interactif (c’est-à-dire si sa méthode isatty() donne True), l’encodage de la console est utilisée, sinon un encodage Windows. Sous d’autres plateformes, l’encodage local est utilisé (voir locale.getpreferredencoding()).

Sous toutes les plates-formes cependant, vous pouvez remplacer cette valeur en définissant la variable d’environnement PYTHONIOENCODING avant de démarrer Python.
En mode interactif, les entrées et sorties standards passent par un tampon d’une ligne. Autrement, elles passent par blocs dans un tampon, comme les fichiers textes classiques. Vous pouvez. Vous pouvez remplacer cette valeur avec l’option -u en ligne de commande.

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¶

Une struct sequence 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 Name and version of the thread library. It is a string, or None if this information is unknown.

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.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 tuple contenant les cinq 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}

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. « Programming languages – C. » A public draft of this standard is available at http://www.open-std.org/jtc1/sc22/wg14/www/docs/n1256.pdf.

29.1. `sys` — Paramètres et fonctions propres à des systèmes¶

Sujet précédent

Sujet suivant

Cette page

29.1. sys — Paramètres et fonctions propres à des systèmes¶

29.1. `sys` — Paramètres et fonctions propres à des systèmes¶