sys — Параметры и функции, специфичные для системы

---

Этот модуль предоставляет доступ к некоторым переменным, используемым или поддерживаемым интерпретатором, а также к функциям, которые активно взаимодействуют с интерпретатором. Он всегда доступен.

sys.abiflags

На POSIX-системах, где Python был собран с помощью стандартного скрипта configure, он содержит флаги ABI, указанные в PEP 3149.

Added in version 3.2.

Изменено в версии 3.8: Флаги по умолчанию стали пустой строкой (флаг``m`` для pymalloc был удален).

Availability: Unix.

sys.addaudithook(hook)

Добавляет вызываемый hook в список активных крючков аудита для текущего (под)интерпретатора.

Когда событие аудита поднимается с помощью функции sys.audit(), каждый крючок будет вызван в том порядке, в котором он был добавлен, с именем события и кортежем аргументов. Сначала вызываются нативные хуки, добавленные с помощью PySys_AddAuditHook(), затем хуки, добавленные в текущем (под)интерпретаторе. Хуки могут регистрировать событие, вызывать исключение для прерывания операции или полностью завершать процесс.

Обратите внимание, что крючки аудита предназначены в первую очередь для сбора информации о внутренних или иных ненаблюдаемых действиях, как Python, так и библиотек, написанных на Python. Они не подходят для реализации «песочницы». В частности, вредоносный код может тривиально отключить или обойти крючки, добавленные с помощью этой функции. Как минимум, все чувствительные к безопасности крючки должны быть добавлены с помощью C API PySys_AddAuditHook() перед инициализацией среды выполнения, а любые модули, позволяющие произвольно модифицировать память (например, ctypes), должны быть полностью удалены или тщательно контролироваться.

Поднимает auditing event sys.addaudithook без аргументов.

Смотрите audit events table для всех событий, вызванных CPython, и PEP 578 для обсуждения оригинального дизайна.

Added in version 3.8.

Изменено в версии 3.8.1: Исключения, возникающие из Exception, но не из RuntimeError, больше не подавляются.

Детали реализации CPython: Если трассировка включена (см. settrace()), крючки Python отслеживаются только в том случае, если вызываемый модуль имеет член __cantrace__, который установлен в значение true. В противном случае функции трассировки будут пропускать хук.

sys.argv

Список аргументов командной строки, передаваемых скрипту Python. argv[0] - это имя скрипта (зависит от операционной системы, является ли оно полным именем пути или нет). Если команда была выполнена с помощью опции командной строки -c интерпретатора, argv[0] устанавливается в строку '-c'. Если интерпретатору Python не было передано имя скрипта, argv[0] - пустая строка.

Чтобы перебрать стандартный ввод или список файлов, заданных в командной строке, смотрите модуль fileinput.

См. также sys.orig_argv.

Примечание

В Unix аргументы командной строки передаются байтами из ОС. Python декодирует их с помощью кодировки файловой системы и обработчика ошибок «surrogateescape». Если вам нужны исходные байты, вы можете получить их по [os.fsencode(arg) for arg in sys.argv].

sys.audit(event, *args)

Вызывает событие аудита и запускает все активные крючки аудита. event - это строка, идентифицирующая событие, а args может содержать необязательные аргументы с дополнительной информацией о событии. Количество и типы аргументов для данного события считаются общедоступным и стабильным API и не должны изменяться между релизами.

Например, одно событие аудита имеет имя os.chdir. Это событие имеет один аргумент path, который будет содержать запрашиваемый новый рабочий каталог.

sys.audit() вызовет существующие крючки аудита, передав имя события и аргументы, и повторно вызовет первое исключение из любого крючка. В общем случае, если возникло исключение, его не следует обрабатывать, а процесс должен быть завершен как можно быстрее. Это позволяет реализаторам хуков решать, как реагировать на конкретные события: они могут просто зарегистрировать событие или прервать операцию, вызвав исключение.

Крючки добавляются с помощью функций sys.addaudithook() или PySys_AddAuditHook().

Родной эквивалент этой функции - PySys_Audit(). По возможности лучше использовать родную функцию.

Все события, вызываемые CPython, см. в разделе audit events table.

Added in version 3.8.

sys.base_exec_prefix

Устанавливается во время запуска Python, перед запуском site.py, в то же значение, что и exec_prefix. Если virtual environment не запущен, значения останутся прежними; если site.py обнаружит, что используется виртуальная среда, значения prefix и exec_prefix будут изменены, чтобы указывать на виртуальную среду, тогда как base_prefix и base_exec_prefix останутся указывать на базовую установку Python (ту, из которой была создана виртуальная среда).

Added in version 3.3.

sys.base_prefix

Устанавливается во время запуска Python, перед запуском site.py, в то же значение, что и prefix. Если virtual environment не запущен, значения останутся прежними; если site.py обнаружит, что используется виртуальная среда, значения prefix и exec_prefix будут изменены, чтобы указывать на виртуальную среду, тогда как base_prefix и base_exec_prefix останутся указывать на базовую установку Python (ту, из которой была создана виртуальная среда).

Added in version 3.3.

sys.byteorder

Индикатор собственного порядка байтов. Имеет значение 'big' на платформах с big-endian (старший байт первый) и 'little' на платформах с little-endian (младший байт первый).

sys.builtin_module_names

Кортеж строк, содержащий имена всех модулей, скомпилированных в данный интерпретатор Python. (Эта информация недоступна никаким другим способом — modules.keys() перечисляет только импортированные модули).

См. также список sys.stdlib_module_names.

sys.call_tracing(func, args)

Вызовите func(*args), пока трассировка включена. Состояние трассировки сохраняется, а затем восстанавливается. Это предназначено для вызова из отладчика с контрольной точки, для рекурсивной отладки или профилирования другого кода.

Трассировка приостанавливается при вызове функции трассировки, заданной значением settrace() или setprofile(), чтобы избежать бесконечной рекурсии. call_tracing() включает явную рекурсию функции трассировки.

sys.copyright

Строка, содержащая авторское право, относящееся к интерпретатору Python.

sys._clear_type_cache()

Очистите внутренний кэш типов. Кэш типов используется для ускорения поиска атрибутов и методов. Используйте эту функцию только для удаления ненужных ссылок при отладке утечки ссылок.

Эта функция должна использоваться только для внутренних и специализированных целей.

Не рекомендуется, начиная с версии 3.13: Вместо этого используйте более общую функцию _clear_internal_caches().

sys._clear_internal_caches()

Очистите все внутренние кэши, связанные с производительностью. Используйте эту функцию только для освобождения ненужных ссылок и блоков памяти при поиске утечек.

Added in version 3.13.

sys._current_frames()

Возвращает словарь, отображающий идентификатор каждого потока на самый верхний кадр стека, активный в этом потоке на момент вызова функции. Обратите внимание, что функции в модуле traceback могут построить стек вызовов с учетом такого фрейма.

Это наиболее полезно для отладки тупиковых ситуаций: функция не требует сотрудничества тупиковых потоков, и стеки вызовов таких потоков замораживаются до тех пор, пока они остаются в тупике. Кадр, возвращаемый для не заблокированного потока, может не иметь никакого отношения к текущей активности этого потока к тому моменту, когда вызывающий код изучит этот кадр.

Эта функция должна использоваться только для внутренних и специализированных целей.

Поднимает auditing event sys._current_frames без аргументов.

sys._current_exceptions()

Возвращает словарь, отображающий идентификатор каждого потока на самое верхнее исключение, активное в этом потоке на момент вызова функции. Если поток в данный момент не обрабатывает исключение, он не включается в словарь результатов.

Это наиболее полезно для статистического профилирования.

Эта функция должна использоваться только для внутренних и специализированных целей.

Поднимает auditing event sys._current_exceptions без аргументов.

Изменено в версии 3.12: Каждое значение в словаре теперь представляет собой один экземпляр исключения, а не три кортежа, как в случае с sys.exc_info().

sys.breakpointhook()

Эта функция-хук вызывается встроенным breakpoint(). По умолчанию она перебрасывает вас в отладчик pdb, но ее можно установить на любую другую функцию, чтобы вы могли выбирать, какой отладчик будет использоваться.

Сигнатура этой функции зависит от того, что она вызывает. Например, привязка по умолчанию (например, pdb.set_trace()) не ожидает никаких аргументов, но вы можете привязать ее к функции, которая ожидает дополнительных аргументов (позиционных и/или ключевых). Встроенная функция breakpoint() передает свои *args и **kws напрямую. Все, что возвращает breakpointhooks(), возвращается из breakpoint().

Реализация по умолчанию сначала обращается к переменной окружения PYTHONBREAKPOINT. Если она установлена в значение "0", то функция возвращается немедленно, то есть не работает. Если переменная окружения не установлена или установлена в пустую строку, вызывается pdb.set_trace(). В противном случае эта переменная должна называть функцию для запуска, используя номенклатуру Python с точечным импортом, например package.subpackage.module.function. В этом случае будет импортирована package.subpackage.module, а результирующий модуль должен содержать вызываемую функцию с именем function(). Он запускается, передавая *args и **kws, и все, что возвращает function(), sys.breakpointhook() возвращает встроенной функции breakpoint().

Обратите внимание, что если при импорте вызываемой переменной с именем PYTHONBREAKPOINT что-то пойдет не так, то будет выдано сообщение RuntimeWarning и точка останова будет проигнорирована.

Также обратите внимание, что если sys.breakpointhook() переопределяется программно, то PYTHONBREAKPOINT не обращается.

Added in version 3.7.

sys._debugmallocstats()

Выведите на stderr низкоуровневую информацию о состоянии аллокатора памяти CPython.

Если Python имеет значение built in debug mode (configure --with-pydebug option), он также выполняет несколько дорогостоящих проверок внутренней согласованности.

Added in version 3.3.

Детали реализации CPython: Эта функция специфична для CPython. Точный формат вывода здесь не определен и может измениться.

sys.dllhandle

Целое число, указывающее дескриптор библиотеки Python DLL.

Availability: Windows.

sys.displayhook(value)

Если значение не равно None, эта функция печатает repr(value) в sys.stdout и сохраняет значение в builtins._. Если repr(value) нельзя закодировать в sys.stdout.encoding с помощью обработчика ошибок sys.stdout.errors (а это, вероятно, 'strict'), закодируйте его в sys.stdout.encoding с помощью обработчика ошибок 'backslashreplace'.

sys.displayhook вызывается по результату оценки expression, введенной в интерактивной сессии Python. Отображение этих значений можно настроить, назначив sys.displayhook другую одноаргументную функцию.

Псевдокод:

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

Изменено в версии 3.2: Используйте обработчик ошибок 'backslashreplace' на UnicodeEncodeError.

sys.dont_write_bytecode

Если это значение верно, Python не будет пытаться записывать .pyc файлы при импорте исходных модулей. Это значение изначально установлено в True или False в зависимости от опции командной строки -B и переменной окружения PYTHONDONTWRITEBYTECODE, но вы можете установить его самостоятельно, чтобы контролировать генерацию файлов байткода.

sys._emscripten_info

Кортеж named tuple, содержащий информацию об окружении на платформе wasm32-emscripten. Именованный кортеж является предварительным и может измениться в будущем.

_emscripten_info.emscripten_version

Версия Emscripten в виде кортежа интов (мажор, минор, микро), например (3, 1, 8).

_emscripten_info.runtime

Строка времени выполнения, например, агент пользователя браузера, 'Node.js v14.18.2' или 'UNKNOWN'.

_emscripten_info.pthreads

True, если Python скомпилирован с поддержкой pthreads в Emscripten.

_emscripten_info.shared_memory

True, если Python скомпилирован с поддержкой общей памяти.

Availability: Emscripten.

Added in version 3.11.

sys.pycache_prefix

Если это значение установлено (не None), Python будет записывать файлы .pyc байткод-кеша в (и читать их из) параллельное дерево каталогов, корнем которого является этот каталог, а не из __pycache__ каталогов в дереве исходного кода. Любые __pycache__ каталоги в дереве исходного кода будут проигнорированы, а новые .pyc файлы будут записаны в префикс pycache. Таким образом, если вы используете compileall в качестве шага предварительной сборки, вы должны убедиться, что вы запускаете его с тем же префиксом pycache (если таковой имеется), который вы будете использовать во время выполнения.

Относительный путь интерпретируется относительно текущего рабочего каталога.

Изначально это значение устанавливается на основе значения параметра -X pycache_prefix=PATH параметра командной строки или переменной окружения PYTHONPYCACHEPREFIX (приоритет имеет командная строка). Если ни то, ни другое не установлено, значение будет None.

Added in version 3.8.

sys.excepthook(type, value, traceback)

Эта функция выводит заданный откат трассы и исключение в sys.stderr.

Когда возникает исключение, отличное от SystemExit, и оно не поймано, интерпретатор вызывает sys.excepthook с тремя аргументами: класс исключения, экземпляр исключения и объект traceback. В интерактивном сеансе это происходит непосредственно перед возвратом управления в подсказку; в программе на Python это происходит непосредственно перед выходом из программы. Обработку таких исключений верхнего уровня можно настроить, назначив sys.excepthook другую функцию с тремя аргументами.

Поднимает auditing event sys.excepthook с аргументами hook, type, value, traceback.

См.также

Функция sys.unraisablehook() обрабатывает неустранимые исключения, а функция threading.excepthook() - исключения, вызванные threading.Thread.run().

sys.__breakpointhook__

sys.__displayhook__

sys.__excepthook__

sys.__unraisablehook__

Эти объекты содержат исходные значения breakpointhook, displayhook, excepthook и unraisablehook в начале работы программы. Они сохраняются для того, чтобы можно было восстановить значения breakpointhook, displayhook и excepthook, unraisablehook в случае их замены на сломанные или альтернативные объекты.

Added in version 3.7: __breakpointhook__

Added in version 3.8: __unraisablehook__

sys.exception()

Эта функция, вызванная во время выполнения обработчика исключений (например, клаузулы except или except*), возвращает экземпляр исключения, который был пойман этим обработчиком. Когда обработчики исключений вложены друг в друга, доступно только исключение, обработанное самым последним обработчиком.

Если обработчик исключений не выполняется, эта функция возвращает None.

Added in version 3.11.

sys.exc_info()

Эта функция возвращает представление обработанного исключения в старом стиле. Если в данный момент обрабатывается исключение e (поэтому exception() вернет e), exc_info() вернет кортеж (type(e), e, e.__traceback__). То есть кортеж, содержащий тип исключения (подкласс BaseException), само исключение и traceback object, который обычно содержит стек вызовов в точке, где исключение произошло в последний раз.

Если нигде в стеке не обрабатывается исключение, эта функция возвращает кортеж, содержащий три значения None.

Изменено в версии 3.11: Поля type и traceback теперь являются производными от value (экземпляра исключения), поэтому, когда исключение изменяется в процессе обработки, изменения отражаются в результатах последующих обращений к exc_info().

sys.exec_prefix

Строка, указывающая префикс каталога, куда устанавливаются зависящие от платформы файлы Python; по умолчанию это также '/usr/local'. Его можно задать во время сборки с помощью аргумента --exec-prefix в скрипте configure. В частности, все конфигурационные файлы (например, заголовочный файл pyconfig.h) устанавливаются в каталог exec_prefix/lib/pythonX.Y/config, а модули общих библиотек - в exec_prefix/lib/pythonX.Y/lib-dynload, где X.Y - номер версии Python, например 3.2.

Примечание

Если действует значение virtual environment, оно будет изменено в site.py, чтобы указать на виртуальную среду. Значение для установки Python по-прежнему будет доступно через base_exec_prefix.

sys.executable

Строка, указывающая абсолютный путь к исполняемому двоичному файлу для интерпретатора Python в системах, где это имеет смысл. Если Python не может получить реальный путь к исполняемому файлу, sys.executable будет пустой строкой или None.

sys.exit([arg])

Вызывает исключение SystemExit, сигнализирующее о намерении выйти из интерпретатора.

Необязательный аргумент arg может быть целым числом, дающим статус завершения (по умолчанию нулевой), или объектом другого типа. Если это целое число, то ноль считается «успешным завершением», а любое ненулевое значение считается «ненормальным завершением» в оболочках и тому подобных системах. Большинство систем требуют, чтобы оно находилось в диапазоне 0–127, и в противном случае выдают неопределенные результаты. В некоторых системах существует соглашение о присвоении определенных значений кодам выхода, но оно, как правило, недостаточно разработано; программы Unix обычно используют 2 для ошибок синтаксиса командной строки и 1 для всех остальных видов ошибок. Если передается объект другого типа, то None эквивалентен передаче нуля, а любой другой объект выводится в stderr и приводит к коду выхода 1. В частности, sys.exit("some error message") - это быстрый способ выйти из программы при возникновении ошибки.

Поскольку exit() в конечном итоге «только» вызывает исключение, он завершает процесс только при вызове из главного потока, и исключение не перехватывается. Действия по очистке, указанные в формулах finally операторов try, выполняются, и можно перехватить попытку выхода на внешнем уровне.

Изменено в версии 3.6: Если в процессе очистки после того, как интерпретатор Python поймал SystemExit, произошла ошибка (например, ошибка при промывке буферизованных данных в стандартных потоках), статус выхода изменяется на 120.

sys.flags

Функция named tuple flags отображает состояние флагов командной строки. Атрибуты доступны только для чтения.

flags.debug	-d
flags.inspect	-i
flags.interactive	-i
flags.isolated	-I
flags.optimize	-O или -OO
flags.dont_write_bytecode	-B
flags.no_user_site	-s
flags.no_site	-S
flags.ignore_environment	-E
flags.verbose	-v
flags.bytes_warning	-b
flags.quiet	-q
flags.hash_randomization	-R
flags.dev_mode	-X dev (Python Development Mode)
flags.utf8_mode	-X utf8
flags.safe_path	-P
flags.int_max_str_digits	-X int_max_str_digits (integer string conversion length limitation)
flags.warn_default_encoding	-X warn_default_encoding

Изменено в версии 3.2: Добавлен атрибут quiet для нового флага -q.

Added in version 3.2.3: Атрибут hash_randomization.

Изменено в версии 3.3: Удален устаревший атрибут division_warning.

Изменено в версии 3.4: Добавлен атрибут isolated для -I isolated флага.

Изменено в версии 3.7: Добавлен атрибут dev_mode для нового флага Python Development Mode и атрибут utf8_mode для нового флага -X utf8 флага.

Изменено в версии 3.10: Добавлен атрибут warn_default_encoding для -X warn_default_encoding флага.

Изменено в версии 3.11: Добавлен атрибут safe_path для опции -P.

Изменено в версии 3.11: Добавлен атрибут int_max_str_digits.

sys.float_info

Элемент named tuple, содержащий информацию о типе float. Он содержит низкоуровневую информацию о точности и внутреннем представлении. Значения соответствуют различным константам с плавающей точкой, определенным в стандартном заголовочном файле float.h для языка программирования „C“; подробнее см. раздел 5.2.4.2.2 стандарта ISO/IEC C 1999 года [C99], «Характеристики плавающих типов».

Атрибуты float_info named tuple

атрибут	макрос float.h	объяснение
float_info.epsilon	DBL_EPSILON	разница между 1,0 и наименьшим значением, превышающим 1,0, которое можно представить в виде плавающей величины. См. также math.ulp().
float_info.dig	DBL_DIG	Максимальное количество десятичных цифр, которое может быть достоверно представлено в плавающей точке; см. ниже.
float_info.mant_dig	DBL_MANT_DIG	Точность плавающей величины: количество цифр base-radix в значении плавающей величины.
float_info.max	DBL_MAX	Максимально представимое положительное конечное число.
float_info.max_exp	DBL_MAX_EXP	Максимальное целое число e, такое, что radix**(e-1) является представимым конечным числом.
float_info.max_10_exp	DBL_MAX_10_EXP	Максимальное целое число e, такое, что 10**e находится в диапазоне представимых конечных плавающих чисел.
float_info.min	DBL_MIN	Минимально представимое положительное нормализованное число. Используйте math.ulp(0.0), чтобы получить наименьшее положительное денормированное представимое число.
float_info.min_exp	DBL_MIN_EXP	Минимальное целое число e, такое, что radix**(e-1) является нормализованным плавающим числом.
float_info.min_10_exp	DBL_MIN_10_EXP	Минимальное целое число e, такое, что 10**e является нормализованным плавающим числом.
float_info.radix	FLT_RADIX	Радикс представления экспоненты.
float_info.rounds	FLT_ROUNDS	Целое число, представляющее режим округления для арифметики с плавающей точкой. Оно отражает значение системного макроса FLT_ROUNDS во время запуска интерпретатора: -1: неопределимо 0: к нулю 1: до ближайшего 2: к положительной бесконечности 3: к отрицательной бесконечности Все остальные значения для FLT_ROUNDS характеризуют поведение округления, определяемое реализацией.

Атрибут sys.float_info.dig нуждается в дополнительном пояснении. Если s - это любая строка, представляющая десятичное число с не более чем sys.float_info.dig значащими цифрами, то преобразование s в float и обратно восстановит строку, представляющую то же десятичное значение:

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

Но для строк, содержащих более sys.float_info.dig значащих цифр, это не всегда верно:

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

sys.float_repr_style

Строка, указывающая, как ведет себя функция repr() для поплавков. Если строка имеет значение 'short', то для конечного float x, repr(x) стремится выдать короткую строку со свойством float(repr(x)) == x. Это обычное поведение в Python 3.1 и более поздних версиях. В противном случае float_repr_style имеет значение 'legacy', а repr(x) ведет себя так же, как и в версиях Python, предшествующих 3.1.

Added in version 3.1.

sys.getallocatedblocks()

Возвращает количество блоков памяти, выделенных интерпретатором в данный момент, независимо от их размера. Эта функция в основном полезна для отслеживания и отладки утечек памяти. Из-за внутренних кэшей интерпретатора результат может меняться от вызова к вызову; возможно, вам придется вызывать _clear_internal_caches() и gc.collect(), чтобы получить более предсказуемые результаты.

Если сборка или реализация Python не может разумно вычислить эту информацию, то вместо нее разрешается возвращать 0.

Added in version 3.4.

sys.getunicodeinternedsize()

Возвращает количество объектов юникода, которые были интернированы.

Added in version 3.12.

sys.getandroidapilevel()

Возвращает уровень API Android во время сборки в виде целого числа. Это минимальная версия Android, на которой может работать данная сборка Python. Информацию о версии для выполнения смотрите в разделе platform.android_ver().

Availability: Android.

Added in version 3.7.

sys.getdefaultencoding()

Возвращает имя текущей кодировки строк по умолчанию, используемой реализацией Unicode.

sys.getdlopenflags()

Возвращает текущее значение флагов, которые используются при вызовах dlopen(). Символические имена значений флагов можно найти в модуле os (константы RTLD_xxx, например os.RTLD_LAZY).

Availability: Unix.

sys.getfilesystemencoding()

Получите filesystem encoding: кодировку, используемую с filesystem error handler для преобразования имен файлов в Юникод и байтовых имен файлов. Обработчик ошибок файловой системы возвращается из getfilesystemencodeerrors().

Для лучшей совместимости для имен файлов во всех случаях следует использовать str, хотя представление имен файлов в виде байтов также поддерживается. Функции, принимающие или возвращающие имена файлов, должны поддерживать либо str, либо bytes и внутренне преобразовывать их в предпочтительное представление системы.

os.fsencode() и os.fsdecode() должны использоваться для обеспечения правильной кодировки и режима ошибок.

Параметры filesystem encoding and error handler настраиваются при запуске Python функцией PyConfig_Read(): см. члены filesystem_encoding и filesystem_errors в PyConfig.

Изменено в версии 3.2: Результат getfilesystemencoding() больше не может быть None.

Изменено в версии 3.6: Windows больше не гарантирует возврат 'mbcs'. Дополнительные сведения см. в разделах PEP 529 и _enablelegacywindowsfsencoding().

Изменено в версии 3.7: Возвращает 'utf-8', если параметр Python UTF-8 Mode включен.

sys.getfilesystemencodeerrors()

Получите filesystem error handler: обработчик ошибок, используемый с filesystem encoding для преобразования между именами файлов в кодировке Unicode и именами файлов в байтах. Кодировка файловой системы возвращается из getfilesystemencoding().

os.fsencode() и os.fsdecode() должны использоваться для обеспечения правильной кодировки и режима ошибок.

Параметры filesystem encoding and error handler настраиваются при запуске Python функцией PyConfig_Read(): см. члены filesystem_encoding и filesystem_errors в PyConfig.

Added in version 3.6.

sys.get_int_max_str_digits()

Возвращает текущее значение для integer string conversion length limitation. См. также set_int_max_str_digits().

Added in version 3.11.

sys.getrefcount(object)

Возвращает счетчик ссылок на объект. Возвращаемый счетчик обычно на один больше, чем вы ожидаете, потому что он включает (временную) ссылку в качестве аргумента getrefcount().

Обратите внимание, что возвращаемое значение может не отражать реальное количество ссылок на объект. Например, некоторые объекты имеют значение immortal и очень высокое значение refcount, которое не отражает фактического количества ссылок. Следовательно, не стоит полагаться на точное возвращаемое значение, кроме значения 0 или 1.

Изменено в версии 3.12: Бессмертные объекты имеют очень большой счетчик ссылок, который не соответствует реальному количеству ссылок на объект.

sys.getrecursionlimit()

Возвращает текущее значение предела рекурсии, максимальной глубины стека интерпретатора Python. Этот предел не позволяет бесконечной рекурсии привести к переполнению стека C и аварийному завершению работы Python. Он может быть установлен с помощью setrecursionlimit().

sys.getsizeof(object[, default])

Возвращает размер объекта в байтах. Объект может быть любого типа. Все встроенные объекты будут возвращать корректные результаты, но это не обязательно для сторонних расширений, так как это зависит от реализации.

Учитывается только потребление памяти, непосредственно приписываемое объекту, а не потребление памяти объектов, на которые он ссылается.

Если задано, будет возвращено значение default, если объект не предоставляет средств для получения размера. В противном случае будет вызвано сообщение TypeError.

getsizeof() вызывает метод __sizeof__ объекта и добавляет дополнительные накладные расходы на сборщик мусора, если объект управляется сборщиком мусора.

Пример рекурсивного использования getsizeof() для нахождения размера контейнеров и всего их содержимого см. в recursive sizeof recipe.

sys.getswitchinterval()

Возвращает «интервал переключения потоков» интерпретатора; см. setswitchinterval().

Added in version 3.2.

sys._getframe([depth])

Возвращает объект фрейма из стека вызовов. Если указано необязательное целое число depth, возвращается фреймовый объект на столько вызовов ниже вершины стека. Если это глубже стека вызовов, то возвращается ValueError. По умолчанию depth равно нулю, возвращая фрейм в верхней части стека вызовов.

Поднимает auditing event sys._getframe с аргументом frame.

Детали реализации CPython: Эту функцию следует использовать только для внутренних и специализированных целей. Не гарантируется, что она будет существовать во всех реализациях Python.

sys._getframemodulename([depth])

Возвращает имя модуля из стека вызовов. Если указано необязательное целое число depth, возвращается модуль на столько вызовов ниже вершины стека. Если это глубже, чем стек вызовов, или если модуль не идентифицируется, возвращается None. По умолчанию значение depth равно нулю, возвращается модуль, находящийся в верхней части стека вызовов.

Поднимает auditing event sys._getframemodulename с аргументом depth.

Детали реализации CPython: Эту функцию следует использовать только для внутренних и специализированных целей. Не гарантируется, что она будет существовать во всех реализациях Python.

sys.getprofile()

Получение функции профилировщика, заданной setprofile().

sys.gettrace()

Получите функцию трассировки, заданную settrace().

Детали реализации CPython: Функция gettrace() предназначена только для реализации отладчиков, профилировщиков, инструментов покрытия и тому подобного. Ее поведение является частью платформы реализации, а не частью определения языка, и поэтому может быть доступно не во всех реализациях Python.

sys.getwindowsversion()

Возвращает именованный кортеж, описывающий текущую версию Windows. Именованными элементами являются major, minor, build, platform, service_pack, service_pack_minor, service_pack_major, suite_mask, product_type и platform_version. service_pack содержит строку, platform_version - три кортежа, а все остальные значения являются целыми числами. К компонентам также можно обращаться по имени, поэтому sys.getwindowsversion()[0] эквивалентно sys.getwindowsversion().major. Для совместимости с предыдущими версиями только первые 5 элементов могут быть получены с помощью индексации.

платформой будет 2 (VER_PLATFORM_WIN32_NT).

product_type может быть одним из следующих значений:

Постоянно	Значение
1 (VER_NT_WORKSTATION)	Система представляет собой рабочую станцию.
2 (VER_NT_DOMAIN_CONTROLLER)	Система является контроллером домена.
3 (VER_NT_SERVER)	Система является сервером, но не контроллером домена.

Эта функция обертывает функцию Win32 GetVersionEx(); более подробную информацию об этих полях см. в документации Microsoft по OSVERSIONINFOEX().

platform_version возвращает основную версию, минорную версию и номер сборки текущей операционной системы, а не версии, которая эмулируется для данного процесса. Она предназначена для ведения журнала, а не для определения возможностей.

Примечание

platform_version берет версию из kernel32.dll, которая может отличаться от версии ОС. Для получения точной версии ОС используйте модуль platform.

Availability: Windows.

Изменено в версии 3.2: Изменен на именованный кортеж и добавлены service_pack_minor, service_pack_major, suite_mask и product_type.

Изменено в версии 3.6: Добавлена платформа_версии.

sys.get_asyncgen_hooks()

Возвращает объект asyncgen_hooks, который похож на namedtuple вида (firstiter, finalizer), где firstiter и finalizer должны быть либо None, либо функциями, принимающими asynchronous generator iterator в качестве аргумента, и используется для планирования финализации асинхронного генератора циклом событий.

Added in version 3.6: Более подробную информацию см. в разделе PEP 525.

Примечание

Эта функция была добавлена на временной основе (подробности см. в PEP 411).

sys.get_coroutine_origin_tracking_depth()

Получение текущей глубины отслеживания начала корутины, заданной set_coroutine_origin_tracking_depth().

Added in version 3.7.

Примечание

Эта функция была добавлена временно (подробности см. в PEP 411). Используйте ее только для отладки.

sys.hash_info

named tuple, задающий параметры реализации числового хэша. Подробнее о хэшировании числовых типов см. в Хеширование числовых типов.

hash_info.width

Ширина в битах, используемая для хэш-значений

hash_info.modulus

Простой модуль P, используемый в числовой хэш-схеме

hash_info.inf

Хеш-значение, возвращаемое для положительной бесконечности

hash_info.nan

(Этот атрибут больше не используется)

hash_info.imag

Множитель, используемый для мнимой части комплексного числа

hash_info.algorithm

Имя алгоритма для хэширования строк, байтов и просмотра памяти

hash_info.hash_bits

Внутренний размер выхода хэш-алгоритма

hash_info.seed_bits

Размер начального ключа хэш-алгоритма

Added in version 3.2.

Изменено в версии 3.4: Добавлены алгоритм, hash_bits и seed_bits.

sys.hexversion

Номер версии, закодированный в виде одного целого числа. Он гарантированно увеличивается с каждой версией, включая надлежащую поддержку непроизводственных релизов. Например, чтобы проверить, что интерпретатор Python имеет версию не ниже 1.5.2, используйте:

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

Это называется hexversion, так как он действительно выглядит осмысленным, только если рассматривать его как результат передачи встроенной функции hex(). Функции named tuple sys.version_info можно использовать для более удобного для человека кодирования той же информации.

Более подробную информацию о hexversion можно найти в Версионирование API и ABI.

sys.implementation

Объект, содержащий информацию о реализации запущенного в данный момент интерпретатора Python. Следующие атрибуты должны существовать во всех реализациях Python.

name - это идентификатор реализации, например, 'cpython'. Фактическая строка определяется реализацией Python, но она гарантированно должна быть в нижнем регистре.

version - это именованный кортеж в том же формате, что и sys.version_info. Он представляет собой версию реализации Python. Это значение отличается от конкретной версии языка Python, которой соответствует запущенный в данный момент интерпретатор, которую представляет sys.version_info. Например, для PyPy 1.8 sys.implementation.version может быть sys.version_info(1, 8, 0, 'final', 0), тогда как sys.version_info будет sys.version_info(2, 7, 2, 'final', 0). Для CPython это одно и то же значение, поскольку он является эталонной реализацией.

hexversion - это версия реализации в шестнадцатеричном формате, например sys.hexversion.

cache_tag - это тег, используемый механизмом импорта в именах файлов кэшированных модулей. По условию, он должен быть составным из имени реализации и версии, например 'cpython-33'. Однако реализация Python может использовать и другое значение, если это уместно. Если cache_tag имеет значение None, это означает, что кэширование модулей должно быть отключено.

sys.implementation может содержать дополнительные атрибуты, специфичные для реализации Python. Эти нестандартные атрибуты должны начинаться с символа подчеркивания и здесь не описываются. Независимо от своего содержимого, sys.implementation не изменяется ни во время запуска интерпретатора, ни между версиями реализации. (Однако он может меняться между версиями языка Python.) Более подробную информацию см. в разделе PEP 421.

Added in version 3.3.

Примечание

Добавление новых необходимых атрибутов должно проходить через обычный процесс PEP. Дополнительную информацию см. в разделе PEP 421.

sys.int_info

Атрибут named tuple, содержащий информацию о внутреннем представлении целых чисел в Python. Атрибуты доступны только для чтения.

int_info.bits_per_digit

Количество битов, содержащихся в каждом разряде. Целые числа в Python хранятся по основанию 2**int_info.bits_per_digit.

int_info.sizeof_digit

Размер в байтах типа C, используемого для представления цифры.

int_info.default_max_str_digits

Значение по умолчанию для sys.get_int_max_str_digits(), если оно не задано иным явным образом.

int_info.str_digits_check_threshold

Минимальное ненулевое значение для sys.set_int_max_str_digits(), PYTHONINTMAXSTRDIGITS или -X int_max_str_digits.

Added in version 3.1.

Изменено в версии 3.11: Добавлены default_max_str_digits и str_digits_check_threshold.

sys.__interactivehook__

Если этот атрибут существует, его значение автоматически вызывается (без аргументов) при запуске интерпретатора в interactive mode. Это происходит после чтения файла PYTHONSTARTUP, так что вы можете установить этот хук там. Модуль site sets this.

Поднимает auditing event cpython.run_interactivehook с аргументом hook.

Added in version 3.4.

sys.intern(string)

Введите строку в таблицу «интернированных» строк и верните интернированную строку - которая сама является строкой или ее копией. Интернирование строк полезно для повышения производительности поиска по словарю - если ключи в словаре интернированы, а ключ поиска интернирован, то сравнение ключей (после хэширования) может быть выполнено сравнением указателей вместо сравнения строк. Обычно имена, используемые в программах на Python, автоматически интернируются, а словари, используемые для хранения атрибутов модулей, классов или экземпляров, имеют интернированные ключи.

Внутренние строки не являются immortal; чтобы воспользоваться ими, вы должны хранить ссылку на возвращаемое значение intern().

sys._is_gil_enabled()

Возвращает True, если GIL включен, и False, если выключен.

Added in version 3.13.

sys.is_finalizing()

Верните True, если основным интерпретатором Python является shutting down. В противном случае верните False.

См. также исключение PythonFinalizationError.

Added in version 3.5.

sys.last_exc

Эта переменная не всегда определена; она устанавливается в экземпляр исключения, когда исключение не обрабатывается и интерпретатор печатает сообщение об ошибке и трассировку стека. Ее назначение - позволить интерактивному пользователю импортировать модуль отладчика и заняться посмертной отладкой без необходимости повторного выполнения команды, вызвавшей ошибку. (Обычно используется import pdb; pdb.pm() для входа в модуль посмертной отладки; более подробную информацию см. в модуле pdb).

Added in version 3.12.

sys._is_interned(string)

Возвращает True, если данная строка является «интернированной», False в противном случае.

Added in version 3.13.

Детали реализации CPython: Его существование не гарантируется во всех реализациях Python.

sys.last_type

sys.last_value

sys.last_traceback

Эти три переменные устарели; вместо них используйте sys.last_exc. Они содержат унаследованное представление sys.last_exc, возвращаемое из exc_info() выше.

sys.maxsize

Целое число, указывающее максимальное значение, которое может принимать переменная типа Py_ssize_t. Обычно это 2**31 - 1 на 32-битной платформе и 2**63 - 1 на 64-битной.

sys.maxunicode

Целое число, дающее значение самой большой кодовой точки Unicode, т.е. 1114111 (0x10FFFF в шестнадцатеричной системе).

Изменено в версии 3.3: Раньше PEP 393, sys.maxunicode были либо 0xFFFF, либо 0x10FFFF, в зависимости от опции конфигурации, которая указывала, хранятся ли символы Юникода как UCS-2 или UCS-4.

sys.meta_path

Список meta path finder объектов, у которых вызываются их find_spec() методы, чтобы проверить, может ли один из объектов найти импортируемый модуль. По умолчанию он содержит записи, реализующие стандартную семантику импорта Python. Метод find_spec() вызывается как минимум с абсолютным именем импортируемого модуля. Если импортируемый модуль содержится в пакете, то в качестве второго аргумента передается атрибут __path__ родительского пакета. Метод возвращает module spec, или None, если модуль не может быть найден.

См.также

importlib.abc.MetaPathFinder

Абстрактный базовый класс, определяющий интерфейс объектов finder на meta_path.

importlib.machinery.ModuleSpec

Конкретный класс, экземпляры которого должны возвращаться в find_spec().

Изменено в версии 3.4: Module specs были введены в Python 3.4, в PEP 451.

Изменено в версии 3.12: Удален fallback, который искал метод find_module(), если у записи meta_path не было метода find_spec().

sys.modules

Это словарь, который сопоставляет имена модулей с модулями, которые уже были загружены. Этим можно манипулировать для принудительной перезагрузки модулей и других трюков. Однако замена словаря не всегда будет работать так, как ожидается, а удаление важных элементов из словаря может привести к сбою Python. Если вы хотите выполнить итерацию по этому глобальному словарю, всегда используйте sys.modules.copy() или tuple(sys.modules), чтобы избежать исключений, поскольку его размер может измениться во время итерации как побочный эффект кода или активности в других потоках.

sys.orig_argv

Список исходных аргументов командной строки, переданных исполняемому файлу Python.

Элементы sys.orig_argv - это аргументы для интерпретатора Python, а элементы sys.argv - аргументы для пользовательской программы. Аргументы, потребляемые самим интерпретатором, будут присутствовать в sys.orig_argv и отсутствовать в sys.argv.

Added in version 3.10.

sys.path

Список строк, задающих путь поиска модулей. Инициализируется из переменной окружения PYTHONPATH, плюс по умолчанию в зависимости от установки.

По умолчанию, инициализируемый при запуске программы, потенциально опасный путь добавляется к sys.path (перед записями, вставленными в результате выполнения PYTHONPATH):

• python -m module Командная строка: добавление текущего рабочего каталога.

• python script.py командной строки: добавьте каталог скрипта. Если это символическая ссылка, разрешите символические ссылки.

• Командные строки python -c code и python (REPL): добавьте пустую строку, которая означает текущий рабочий каталог.

Чтобы не добавлять этот потенциально опасный путь, используйте параметр командной строки -P или переменную окружения PYTHONSAFEPATH.

Программа может свободно изменять этот список для своих целей. В sys.path следует добавлять только строки; все остальные типы данных при импорте игнорируются.

См.также

• Модуль site Здесь описывается, как использовать .pth-файлы для расширения sys.path.

sys.path_hooks

Список вызываемых файлов, которые, принимая аргумент path, пытаются создать finder для этого пути. Если искатель может быть создан, он должен быть возвращен вызываемой переменной, в противном случае вызовите ImportError.

Первоначально указывается в PEP 302.

sys.path_importer_cache

Словарь, действующий как кэш для объектов finder. Ключами являются пути, которые были переданы в sys.path_hooks, а значениями - найденные искатели. Если путь является правильным путем файловой системы, но ни один искатель не найден в sys.path_hooks, то сохраняется None.

Первоначально указывается в PEP 302.

sys.platform

Строка, содержащая идентификатор платформы. Известные значения:

Система	Значение platform
AIX	'aix'
Android	'android'
Emscripten	'emscripten'
iOS	'ios'
Linux	'linux'
macOS	'darwin'
Windows	'win32'
Windows/Cygwin	'cygwin'
WASI	'wasi'

Для Unix-систем, не указанных в таблице, значением является имя ОС со строчными буквами, возвращаемое командой uname -s, с добавлением первой части версии, возвращаемой командой uname -r, например 'sunos5' или 'freebsd8', на момент сборки Python. Если вы не хотите проверять конкретную версию системы, рекомендуется использовать следующую идиому:

if sys.platform.startswith('freebsd'):
    # FreeBSD-specific code here...

Изменено в версии 3.3: В Linux sys.platform больше не содержит основной версии. Это всегда 'linux', а не 'linux2' или 'linux3'.

Изменено в версии 3.8: В AIX sys.platform больше не содержит основной версии. Это всегда 'aix', а не 'aix5' или 'aix7'.

Изменено в версии 3.13: На Android функция sys.platform теперь возвращает 'android', а не 'linux'.

См.также

os.name имеет более грубую детализацию. os.uname() предоставляет информацию о версии, зависящую от системы.

Модуль platform обеспечивает детальную проверку идентичности системы.

sys.platlibdir

Имя каталога библиотеки для конкретной платформы. Используется для построения пути к стандартной библиотеке и путей к установленным модулям расширения.

На большинстве платформ оно равно "lib". На Fedora и SuSE он равен "lib64" на 64-битных платформах, что дает следующие sys.path пути (где X.Y - версия Python major.minor):

• /usr/lib64/pythonX.Y/: Стандартная библиотека (как os.py модуля os)

• /usr/lib64/pythonX.Y/lib-dynload/: Модули расширения стандартной библиотеки на языке C (как и модуль errno, точное имя файла зависит от платформы)

• /usr/lib/pythonX.Y/site-packages/ (всегда используйте lib, а не sys.platlibdir): Сторонние модули

• /usr/lib64/pythonX.Y/site-packages/: Модули расширения C сторонних пакетов

Added in version 3.9.

sys.prefix

Строка, указывающая префикс каталога, в который устанавливаются независимые от платформы файлы Python; на Unix по умолчанию /usr/local. Его можно задать во время сборки с помощью аргумента --prefix в скрипте configure. Производные пути см. в разделе Пути установки.

Примечание

Если действует значение virtual environment, оно будет изменено в site.py, чтобы указать на виртуальную среду. Значение для установки Python по-прежнему будет доступно через base_prefix.

sys.ps1

sys.ps2

Строки, определяющие основную и дополнительную подсказки интерпретатора. Они задаются только в том случае, если интерпретатор находится в интерактивном режиме. Их начальные значения в этом случае - '>>> ' и '... '. Если переменной присвоен объект, не являющийся строкой, то ее str() переоценивается каждый раз, когда интерпретатор готовится прочитать новую интерактивную команду; это может быть использовано для реализации динамической подсказки.

sys.setdlopenflags(n)

Устанавливает флаги, используемые интерпретатором для вызовов dlopen(), например, когда интерпретатор загружает модули расширения. Помимо прочего, это позволит лениво разрешать символы при импорте модуля, если вызвать его как sys.setdlopenflags(0). Чтобы разделить символы между модулями расширения, вызовите sys.setdlopenflags(os.RTLD_GLOBAL). Символические имена для значений флагов можно найти в модуле os (константы RTLD_xxx, например os.RTLD_LAZY).

Availability: Unix.

sys.set_int_max_str_digits(maxdigits)

Установка integer string conversion length limitation, используемого данным интерпретатором. См. также get_int_max_str_digits().

Added in version 3.11.

sys.setprofile(profilefunc)

Установите функцию профиля системы, которая позволяет реализовать профилировщик исходного кода Python на языке Python. Дополнительную информацию о профилировщике Python см. в главе Профилировщики Python. Функция профиля системы вызывается аналогично функции трассировки системы (см. settrace()), но с разными событиями, например, она не вызывается для каждой выполненной строки кода (только при вызове и возврате, но событие возврата сообщается, даже если было установлено исключение). Функция является потокозависимой, но у профайлера нет возможности узнать о переключении контекста между потоками, поэтому использовать ее при наличии нескольких потоков не имеет смысла. Кроме того, ее возвращаемое значение не используется, поэтому она может просто вернуть None. Ошибка в функции профиля приведет к тому, что она сама себя отменит.

Примечание

Для setprofile() используется тот же механизм трассировки, что и для settrace(). Чтобы отследить вызовы с setprofile() внутри функции трассировки (например, в точке останова отладчика), смотрите call_tracing().

Функции профиля должны иметь три аргумента: frame, event и arg. frame - это текущий фрейм стека. event - это строка: 'call', 'return', 'c_call', 'c_return' или 'c_exception'. arg зависит от типа события.

Эти события имеют следующее значение:

'call'

Вызывается функция (или вводится другой блок кода). Вызывается функция профиля; arg - None.

'return'

Функция (или другой блок кода) вот-вот вернется. Вызывается профильная функция; arg - это значение, которое будет возвращено, или None, если событие вызвано возникновением исключения.

'c_call'

Сейчас будет вызвана функция языка C. Это может быть функция расширения или встроенная функция. arg - это объект функции Си.

'c_return'

Функция C вернулась. arg - это объект функции Си.

'c_exception'

Функция языка Си вызвала исключение. arg - это объект функции Си.

Поднимает auditing event sys.setprofile без аргументов.

sys.setrecursionlimit(limit)

Установите максимальную глубину стека интерпретатора Python равной limit. Это ограничение не позволяет бесконечной рекурсии вызвать переполнение стека C и аварийное завершение работы Python.

Максимально возможный предел зависит от платформы. Пользователю может понадобиться установить более высокий предел, если у него есть программа, требующая глубокой рекурсии, и платформа, поддерживающая более высокий предел. Делать это следует осторожно, поскольку слишком высокий предел может привести к сбою.

Если новый предел слишком мал при текущей глубине рекурсии, будет вызвано исключение RecursionError.

Изменено в версии 3.5.1: Исключение RecursionError теперь вызывается, если новый предел слишком мал при текущей глубине рекурсии.

sys.setswitchinterval(interval)

Установите интервал переключения потоков интерпретатора (в секундах). Это значение с плавающей точкой определяет идеальную продолжительность «таймлайнов», выделяемых для параллельно работающих потоков Python. Обратите внимание, что фактическое значение может быть больше, особенно если используются долго выполняющиеся внутренние функции или методы. Кроме того, решение о том, какой поток станет запланированным в конце интервала, принимает операционная система. Интерпретатор не имеет собственного планировщика.

Added in version 3.2.

sys.settrace(tracefunc)

Устанавливает функцию трассировки системы, которая позволяет реализовать отладчик исходного кода Python на языке Python. Функция зависит от потока; чтобы отладчик поддерживал несколько потоков, он должен зарегистрировать функцию трассировки с помощью settrace() для каждого отлаживаемого потока или использовать threading.settrace().

Функции трассировки должны иметь три аргумента: frame, event и arg. frame - это текущий фрейм стека. event - это строка: 'call', 'line', 'return', 'exception' или 'opcode'. arg зависит от типа события.

Функция трассировки вызывается (с event, установленным в 'call') всякий раз, когда вводится новая локальная область; она должна возвращать ссылку на локальную функцию трассировки, которая будет использоваться для новой области, или None, если область не должна трассироваться.

Локальная функция трассировки должна возвращать ссылку на саму себя или на другую функцию, которая затем будет использоваться в качестве локальной функции трассировки для данной области видимости.

Если в функции трассировки произошла какая-либо ошибка, она будет снята, как и при вызове settrace(None).

Примечание

Трассировка отключается при вызове функции трассировки (например, функции, заданной settrace()). Для рекурсивной трассировки смотрите call_tracing().

Эти события имеют следующее значение:

'call'

Вызывается функция (или вводится другой блок кода). Вызывается глобальная функция трассировки; arg - None; возвращаемое значение задает локальную функцию трассировки.

'line'

Интерпретатор собирается выполнить новую строку кода или повторно выполнить условие цикла. Вызывается локальная функция трассировки; arg - это None; возвращаемое значение задает новую локальную функцию трассировки. Подробное объяснение того, как это работает, см. в Objects/lnotab_notes.txt. События в каждой строке могут быть отключены для кадра путем установки f_trace_lines в False на этом frame.

'return'

Функция (или другой блок кода) вот-вот вернется. Вызывается локальная функция трассировки; arg - значение, которое будет возвращено, или None, если событие вызвано возникновением исключения. Возвращаемое значение функции трассировки игнорируется.

'exception'

Произошло исключение. Вызывается локальная функция трассировки; arg - кортеж (exception, value, traceback); возвращаемое значение задает новую локальную функцию трассировки.

'opcode'

Интерпретатор собирается выполнить новый опкод (подробности об опкоде см. в разделе dis). Вызывается локальная функция трассировки; arg - это None; возвращаемое значение задает новую локальную функцию трассировки. По умолчанию события для каждого опкода не выдаются: их нужно явно запросить, установив f_trace_opcodes в True на frame.

Обратите внимание, что при распространении исключения по цепочке вызывающих команд на каждом уровне генерируется событие 'exception'.

Для более тонкого использования можно установить функцию трассировки, назначив frame.f_trace = tracefunc явно, а не полагаясь на то, что она будет установлена косвенно через возвращаемое значение уже установленной функции трассировки. Это также необходимо для активации функции трассировки на текущем кадре, чего settrace() не делает. Обратите внимание, что для того, чтобы это работало, глобальная функция трассировки должна быть установлена с помощью settrace(), чтобы включить механизм трассировки во время выполнения, но это не обязательно должна быть та же самая функция трассировки (например, это может быть функция трассировки с низкой нагрузкой, которая просто возвращает None, чтобы немедленно отключать себя на каждом кадре).

Дополнительную информацию о коде и фреймовых объектах см. в разделе Стандартная иерархия типов.

Поднимает auditing event sys.settrace без аргументов.

Детали реализации CPython: Функция settrace() предназначена только для реализации отладчиков, профилировщиков, инструментов покрытия и тому подобного. Ее поведение является частью платформы реализации, а не частью определения языка, и поэтому может быть доступно не во всех реализациях Python.

Изменено в версии 3.7: Добавлен тип события 'opcode'; добавлены атрибуты f_trace_lines и f_trace_opcodes для фреймов

sys.set_asyncgen_hooks([firstiter] [, finalizer])

Принимает два необязательных аргумента в виде ключевых слов, которые являются вызываемыми переменными, принимающими в качестве аргумента asynchronous generator iterator. Вызываемая переменная firstiter будет вызвана, когда асинхронный генератор будет итерироваться в первый раз. Вызываемый finalizer будет вызван, когда асинхронный генератор будет собираться в мусор.

Поднимает auditing event sys.set_asyncgen_hooks_firstiter без аргументов.

Поднимает auditing event sys.set_asyncgen_hooks_finalizer без аргументов.

Два события аудита поднимаются, потому что базовый API состоит из двух вызовов, каждый из которых должен поднимать свое собственное событие.

Added in version 3.6: Более подробную информацию см. в PEP 525, а пример метода финализатора - в реализации asyncio.Loop.shutdown_asyncgens в Lib/asyncio/base_events.py.

Примечание

Эта функция была добавлена на временной основе (подробности см. в PEP 411).

sys.set_coroutine_origin_tracking_depth(depth)

Позволяет включить или выключить отслеживание происхождения coroutine. При включении атрибут cr_origin у объектов coroutine будет содержать кортеж (имя файла, номер строки, имя функции), описывающий трассировку, где был создан объект coroutine, причем первым будет самый последний вызов. Если атрибут cr_origin отключен, он будет содержать None.

Чтобы включить, передайте значение depth больше нуля; это задает количество кадров, информация о которых будет захвачена. Чтобы отключить, передайте значение depth равным нулю.

Эта настройка зависит от конкретного потока.

Added in version 3.7.

Примечание

Эта функция была добавлена временно (подробности см. в PEP 411). Используйте ее только для отладки.

sys.activate_stack_trampoline(backend, /)

Активируйте батутный бэкенд стекового профилировщика. Единственным поддерживаемым бэкендом является "perf".

Availability: Linux.

Added in version 3.12.

См.также

• Поддержка Python для профилировщика Linux perf

• https://perf.wiki.kernel.org

sys.deactivate_stack_trampoline()

Деактивируйте текущий бэкэнд батутного профилировщика стека.

Если профилировщик стека не активирован, эта функция не имеет никакого эффекта.

Availability: Linux.

Added in version 3.12.

sys.is_stack_trampoline_active()

Возвращает True, если активен батут профилировщика стека.

Availability: Linux.

Added in version 3.12.

sys._enablelegacywindowsfsencoding()

Заменяет filesystem encoding and error handler на „mbcs“ и „replace“ соответственно, для согласованности с версиями Python до 3.6.

Это эквивалентно определению переменной окружения PYTHONLEGACYWINDOWSFSENCODING перед запуском Python.

См. также sys.getfilesystemencoding() и sys.getfilesystemencodeerrors().

Availability: Windows.

Примечание

Менять кодировку файловой системы после запуска Python рискованно, так как старая кодировка fsencoding или пути, закодированные старой кодировкой fsencoding, могут быть где-то кэшированы. Вместо этого используйте PYTHONLEGACYWINDOWSFSENCODING.

Added in version 3.6: Более подробную информацию см. в разделе PEP 529.

Утратил актуальность с версии 3.13, будет удален в версии 3.16: Вместо этого используйте PYTHONLEGACYWINDOWSFSENCODING.

sys.stdin

sys.stdout

sys.stderr

File objects, используемый интерпретатором для стандартного ввода, вывода и ошибок:

• stdin используется для всего интерактивного ввода (включая вызовы input());

• stdout используется для вывода операторов print() и expression и для подсказок input();

• Собственные подсказки интерпретатора и его сообщения об ошибках отправляются в stderr.

Эти потоки представляют собой обычные text files, подобные тем, которые возвращает функция open(). Их параметры выбираются следующим образом:

• Кодировка и обработка ошибок инициализируются с PyConfig.stdio_encoding и PyConfig.stdio_errors.

  В Windows для консольного устройства используется UTF-8. Для несимвольных устройств, таких как дисковые файлы и трубы, используется кодировка системной локали (т. е. кодовая страница ANSI). Неконсольные символьные устройства, такие как NUL (т. е. где isatty() возвращает True), используют значение кодовых страниц ввода и вывода консоли при запуске, соответственно для stdin и stdout/stderr. По умолчанию используется системное значение locale encoding, если процесс изначально не подключен к консоли.

  Особое поведение консоли можно отменить, установив переменную окружения PYTHONLEGACYWINDOWSSTDIO перед запуском Python. В этом случае кодовые страницы консоли используются так же, как и для любого другого символьного устройства.

  На всех платформах вы можете изменить кодировку символов, установив переменную окружения PYTHONIOENCODING перед запуском Python или используя новую опцию -X utf8 параметра командной строки и переменной окружения PYTHONUTF8. Однако для консоли Windows это применимо только в том случае, если также установлена переменная PYTHONLEGACYWINDOWSSTDIO.

• В интерактивном режиме поток stdout буферизуется строками. В противном случае он буферизуется блоками, как обычные текстовые файлы. Поток stderr в обоих случаях буферизуется строками. Вы можете сделать оба потока небуферизованными, передав параметр командной строки -u или установив переменную окружения PYTHONUNBUFFERED.

Изменено в версии 3.9: Неинтерактивный stderr теперь буферизуется по строкам, а не полностью.

Примечание

Для записи или чтения двоичных данных из/в стандартные потоки используйте базовый двоичный объект buffer. Например, чтобы записать байт в stdout, используйте sys.stdout.buffer.write(b'abc').

Однако если вы пишете библиотеку (и не контролируете, в каком контексте будет выполняться ее код), имейте в виду, что стандартные потоки могут быть заменены файлоподобными объектами типа io.StringIO, которые не поддерживают атрибут buffer.

sys.__stdin__

sys.__stdout__

sys.__stderr__

Эти объекты содержат исходные значения stdin, stderr и stdout в начале работы программы. Они используются во время финализации и могут быть полезны для печати в реальный стандартный поток независимо от того, был ли перенаправлен объект sys.std*.

Его также можно использовать для восстановления фактических файлов в известных рабочих файловых объектах в случае, если они были перезаписаны поврежденным объектом. Однако предпочтительным способом является явное сохранение предыдущего потока перед его заменой и восстановление сохраненного объекта.

Примечание

При некоторых условиях stdin, stdout и stderr, а также исходные значения __stdin__, __stdout__ и __stderr__ могут быть None. Обычно это происходит в приложениях с графическим интерфейсом Windows, не подключенных к консоли, и в приложениях Python, запускаемых с pythonw.

sys.stdlib_module_names

Набор строк, содержащих имена модулей стандартной библиотеки.

Он одинаков для всех платформ. Также перечислены модули, недоступные на некоторых платформах, и модули, отключенные при сборке Python. Перечислены все виды модулей: чистый Python, встроенные, замороженные и модули расширения. Тестовые модули исключены.

Для пакетов указывается только основной пакет: подпакеты и подмодули не указываются. Например, указан пакет email, но не указаны подпакет email.mime и подмодуль email.message.

См. также список sys.builtin_module_names.

Added in version 3.10.

sys.thread_info

Значение named tuple, содержащее информацию о реализации потока.

thread_info.name

Имя реализации потока:

• "nt": Потоки Windows

• "pthread": POSIX-потоки

• "pthread-stubs": заглушка POSIX-потоков (на платформах WebAssembly без поддержки потоков)

• "solaris": Потоки Solaris

thread_info.lock

Имя реализации блокировки:

• "semaphore": блокировка использует семафор

• "mutex+cond": блокировка использует мьютекс и переменную условия

• None, если эта информация неизвестна

thread_info.version

Имя и версия библиотеки потоков. Это строка или None, если эта информация неизвестна.

Added in version 3.3.

sys.tracebacklimit

Когда эта переменная имеет целочисленное значение, она определяет максимальное количество уровней информации о возврате к трассировке, выводимой при возникновении необработанного исключения. По умолчанию установлено значение 1000. Если установлено значение 0 или меньше, вся информация о возврате к трассировке подавляется и выводятся только тип и значение исключения.

sys.unraisablehook(unraisable, /)

Обработка неустранимого исключения.

Вызывается, когда произошло исключение, но у Python нет возможности его обработать. Например, когда деструктор вызывает исключение или во время сборки мусора (gc.collect()).

Аргумент unraisable имеет следующие атрибуты:

• exc_type: Тип исключения.

• exc_value: Значение исключения, может быть None.

• exc_traceback: Отслеживание исключения, может быть None.

• err_msg: Сообщение об ошибке, может быть None.

• object: Объект, вызвавший исключение, может быть None.

По умолчанию хук форматирует err_msg и object как: f'{err_msg}: {object!r}'; используйте сообщение об ошибке «Exception ignored in», если err_msg равно None.

sys.unraisablehook() можно переопределить, чтобы управлять обработкой невычитаемых исключений.

См.также

excepthook(), который обрабатывает не пойманные исключения.

Предупреждение

Хранение exc_value с помощью пользовательского хука может создать цикл ссылок. Его следует явно очистить, чтобы разорвать цикл ссылок, когда исключение больше не нужно.

Хранение object с помощью пользовательского хука может воскресить его, если он установлен на объект, который завершается. Избегайте сохранения object после завершения работы пользовательского хука, чтобы избежать воскрешения объектов.

Поднимает auditing event sys.unraisablehook с аргументами hook, unraisable.

Added in version 3.8.

sys.version

Строка, содержащая номер версии интерпретатора Python, а также дополнительную информацию о номере сборки и используемом компиляторе. Эта строка отображается при запуске интерактивного интерпретатора. Не извлекайте из нее информацию о версии, лучше используйте version_info и функции, предоставляемые модулем platform.

sys.api_version

Версия C API для данного интерпретатора. Программисты могут найти это полезным при отладке конфликтов версий между Python и модулями расширения.

sys.version_info

Кортеж, содержащий пять компонентов номера версии: major, minor, micro, releaselevel и serial. Все значения, кроме releaselevel, являются целыми числами; уровень выпуска - это 'alpha', 'beta', 'candidate' или 'final'. Значение version_info, соответствующее версии Python 2.0, равно (2, 0, 0, 'final', 0). К компонентам также можно обращаться по имени, поэтому sys.version_info[0] эквивалентно sys.version_info.major и так далее.

Изменено в версии 3.1: Добавлены именованные атрибуты компонентов.

sys.warnoptions

Это деталь реализации фреймворка предупреждений; не изменяйте это значение. Дополнительные сведения о системе предупреждений см. в модуле warnings.

sys.winver

Номер версии, используемый для формирования ключей реестра на платформах Windows. Хранится как строковый ресурс 1000 в библиотеке Python DLL. Обычно это значение представляет собой мажорную и минорную версии запущенного интерпретатора Python. Оно предоставляется в модуле sys в информационных целях; изменение этого значения не влияет на ключи реестра, используемые Python.

Availability: Windows.

sys.monitoring

Пространство имен, содержащее функции и константы для регистрации обратных вызовов и управления событиями мониторинга. Подробности см. в разделе sys.monitoring.

sys._xoptions

Словарь различных специфических для реализации флагов, передаваемых через опцию командной строки -X. Имена опций либо сопоставляются с их значениями, если они заданы явно, либо с True. Пример:

$ ./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: Это специфический для CPython способ доступа к опциям, переданным через -X. Другие реализации могут экспортировать их другими способами или вообще не экспортировать.

Added in version 3.2.

Цитаты

[C99]

ISO/IEC 9899:1999. «Языки программирования – C». Публичный проект этого стандарта доступен по адресу https://www.open-std.org/jtc1/sc22/wg14/www/docs/n1256.pdf.