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

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

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

Добавлено в версии 3.2.

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

Доступность: Unix.

sys.addaudithook(hook)

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

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

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

Сам вызов sys.addaudithook() генерирует событие аудита с именем sys.addaudithook без аргументов. Если какие-либо существующие хуки возбуждают исключение, производное от RuntimeError, новый хук не будет добавлен, а исключение будет подавлено. Поэтому вызывающие стороны не могут быть уверены, что их хук был добавлен, если они не контролируют все существующие хуки.

Все события, генерируемые CPython, перечислены в таблице событий аудита. Исходное обсуждение разработки см. в PEP 578.

Добавлено в версии 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, перечислены в таблице событий аудита.

Добавлено в версии 3.8.

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

Добавлено в версии 3.3.

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

Добавлено в версии 3.3.

sys.byteorder: Индикатор порядка байтов в нативном формате. На платформах с порядком байтов от старшего к младшему (сначала старший байт) значение будет 'big', а на платформах с порядком от младшего к старшему (сначала младший байт) — 'little'.

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

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

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

sys._current_frames()

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

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

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

Генерирует событие аудита sys._current_frames без аргументов.

sys._current_exceptions()

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

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

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

Генерирует событие аудита sys._current_exceptions без аргументов.

Изменено в версии 3.12: Теперь каждое значение в словаре — это один экземпляр исключения, а не кортеж из 3 элементов, возвращавшийся функцией 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 не проверяется.

Добавлено в версии 3.7.

sys._debugmallocstats()

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

Если Python собран в режиме отладки (configure --with-pydebug option), функция также выполняет некоторые затратные внутренние проверки целостности.

Добавлено в версии 3.3.

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

sys.dllhandle: Целое число, задающее дескриптор DLL Python.

Доступность: Windows.

sys.displayhook(value)

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

Функция sys.displayhook вызывается для результата вычисления выражения, введённого в интерактивном сеансе 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: Для UnicodeEncodeError используется обработчик ошибок 'backslashreplace'.

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

sys._emscripten_info

Именованный кортеж именованный кортеж, содержащий сведения об окружении на платформе 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 скомпилирован с поддержкой общей памяти.

Доступность: Emscripten.

Добавлено в версии 3.11.

sys.pycache_prefix

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

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

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

Добавлено в версии 3.8.

sys.excepthook(type, value, traceback)

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

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

При возникновении необработанного исключения генерируется событие аудита sys.excepthook с аргументами hook, type, value, traceback. Если хук не задан, hook может быть равен None. Если какой-либо хук возбуждает исключение, производное от RuntimeError, вызов хука будет подавлен. В противном случае исключение хука аудита будет зарегистрировано как невыводимое, после чего будет вызван sys.excepthook.

См. также

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

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

Добавлено в версии 3.7: __breakpointhook__

Добавлено в версии 3.8: __unraisablehook__

sys.exception()

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

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

Добавлено в версии 3.11.

sys.exc_info()

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

Если ни одно исключение в стеке не обрабатывается, эта функция возвращает кортеж, содержащий три значения 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.

Примечание

Если используется виртуальная среда, это значение изменяется в 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

Именованный кортеж 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)
`flags.utf8_mode`	`-X utf8`
`flags.safe_path`	`-P`
`flags.int_max_str_digits`	`-X int_max_str_digits` (ограничение длины преобразования целых чисел в строки)
`flags.warn_default_encoding`	`-X warn_default_encoding`

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

Добавлено в версии 3.2.3: Атрибут hash_randomization.

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

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

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

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

Изменено в версии 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, которое можно представить как float. См. также `math.ulp()`.
`float_info.dig`	`DBL_DIG`	Максимальное количество десятичных цифр, которые можно точно представить в значении float; см. ниже.
`float_info.mant_dig`	`DBL_MANT_DIG`	Точность float: количество цифр в системе счисления с основанием `radix` в мантиссе значения float.
`float_info.max`	`DBL_MAX`	Максимальное представимое положительное конечное значение float.
`float_info.max_exp`	`DBL_MAX_EXP`	Максимальное целое число e, для которого `radix**(e-1)` является представимым конечным значением float.
`float_info.max_10_exp`	`DBL_MAX_10_EXP`	Максимальное целое число e, для которого `10**e` входит в диапазон представимых конечных значений float.
`float_info.min`	`DBL_MIN`	Минимальное представимое положительное нормализованное значение float. Используйте `math.ulp(0.0)`, чтобы получить наименьшее положительное представимое денормализованное значение float.
`float_info.min_exp`	`DBL_MIN_EXP`	Минимальное целое число e, для которого `radix**(e-1)` является нормализованным значением float.
`float_info.min_10_exp`	`DBL_MIN_10_EXP`	Минимальное целое число e, для которого `10**e` является нормализованным значением float.
`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() работает со значениями float. Если строка имеет значение 'short', то для конечного значения float x функция repr(x) пытается сформировать короткую строку, для которой выполняется свойство float(repr(x)) == x. Это обычное поведение в Python 3.1 и более поздних версиях. В противном случае float_repr_style имеет значение 'legacy', а repr(x) работает так же, как и в версиях Python до 3.1.

Добавлено в версии 3.1.

sys.getallocatedblocks()

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

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

Добавлено в версии 3.4.

sys.getunicodeinternedsize(): Возвращает количество интернированных объектов Unicode.

Добавлено в версии 3.12.

sys.getandroidapilevel(): Возвращает целочисленную версию API Android, использованную при сборке.

Доступность: Android.

Добавлено в версии 3.7.

sys.getdefaultencoding(): Возвращает 'utf-8'. Это название кодировки строк по умолчанию, используемой в таких методах, как str.encode().

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

Доступность: Unix.

sys.getfilesystemencoding()

Возвращает кодировку файловой системы: кодировку, используемую вместе с обработчиком ошибок файловой системы для преобразования имён файлов Unicode в байтовые имена и обратно. Обработчик ошибок файловой системы возвращается функцией getfilesystemencodeerrors().

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

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

Кодировка файловой системы и обработчик ошибок настраиваются при запуске Python функцией PyConfig_Read(): см. параметры filesystem_encoding и filesystem_errors структуры PyConfig.

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

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

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

sys.getfilesystemencodeerrors()

Возвращает обработчик ошибок файловой системы: обработчик ошибок, используемый вместе с кодировкой файловой системы для преобразования имён файлов Unicode в байтовые имена и обратно. Кодировка файловой системы возвращается функцией getfilesystemencoding().

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

Добавлено в версии 3.6.

sys.get_int_max_str_digits(): Возвращает текущее значение ограничения длины преобразования целых чисел в строки. См. также set_int_max_str_digits().

Добавлено в версии 3.11.

sys.getrefcount(object)

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

Обратите внимание, что возвращаемое значение может не отражать фактическое количество ссылок на объект. Например, некоторые объекты «бессмертны» и имеют очень высокий счётчик ссылок, не соответствующий реальному количеству ссылок. Поэтому не следует полагаться на точность возвращаемого значения, кроме случаев, когда оно равно 0 или 1.

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

sys.getrecursionlimit(): Возвращает текущее значение ограничения рекурсии — максимальную глубину стека интерпретатора Python. Это ограничение предотвращает переполнение стека C и аварийное завершение Python из-за бесконечной рекурсии. Его можно задать с помощью setrecursionlimit().

sys.getsizeof(object[, default])

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

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

Если указан аргумент default, он будет возвращён, если объект не предоставляет способа получить свой размер. В противном случае возбуждается исключение TypeError.

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

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

sys.getswitchinterval(): Возвращает интервал переключения потоков интерпретатора в секундах; см. setswitchinterval().

Добавлено в версии 3.2.

sys._getframe([depth])

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

Возбуждает событие аудита sys._getframe с аргументом frame.

Особенность реализации CPython: Эту функцию следует использовать только для внутренних и специализированных задач. Её наличие не гарантируется во всех реализациях Python.

sys._getframemodulename([depth])

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

Возбуждает событие аудита sys._getframemodulename с аргументом depth.

sys.getobjects(limit[, type])

Эта функция существует только в том случае, если CPython был собран с использованием специального параметра configure --with-trace-refs. Она предназначена только для отладки проблем со сборкой мусора.

Возвращает список из не более чем limit динамически выделенных объектов Python. Если задан type, включаются только объекты точно этого типа (не его подтипы).

Объекты из списка небезопасно использовать. В частности, результат будет содержать объекты из всех интерпретаторов, которые совместно используют состояние распределителя объектов (то есть созданные с PyInterpreterConfig.use_main_obmalloc, установленным в 1, или с помощью Py_NewInterpreter(), а также из главного интерпретатора). Смешивание объектов из разных интерпретаторов может привести к сбоям или другому неожиданному поведению.

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

Изменено в версии 3.12.8: Результат может содержать объекты из других интерпретаторов.

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 элементов.

platform будет равен 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.

Доступность: Windows.

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

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

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

Добавлено в версии 3.6: Подробнее см. PEP 525.

Примечание

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

sys.get_coroutine_origin_tracking_depth(): Получает текущую глубину отслеживания источника сопрограммы, установленную с помощью set_coroutine_origin_tracking_depth().

Добавлено в версии 3.7.

Примечание

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

sys.hash_info

Именованный кортеж с параметрами реализации числовых хешей. Подробнее о хешировании числовых типов см. в разделе Хеширование числовых типов.

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

hash_info.modulus: Простое число P — модуль, используемый в схеме числового хеширования

hash_info.inf: Значение хеша, возвращаемое для положительной бесконечности

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

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

hash_info.algorithm: Название алгоритма хеширования для типов str, bytes и memoryview

hash_info.hash_bits: Внутренний размер выходных данных алгоритма хеширования

hash_info.seed_bits: Размер ключа-затравки алгоритма хеширования

Добавлено в версии 3.2.

Изменено в версии 3.4: Добавлены algorithm, 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(). Для более удобного для человека представления той же информации можно использовать именованный кортеж 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.

Добавлено в версии 3.3.

Примечание

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

sys.int_info

Именованный кортеж, содержащий сведения о внутреннем представлении целых чисел в 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.

Добавлено в версии 3.1.

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

sys.__interactivehook__

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

При вызове обработчика во время запуска генерируется событие аудита cpython.run_interactivehook, аргументом которого является объект обработчика.

Добавлено в версии 3.4.

sys.intern(string)

Добавляет string в таблицу интернированных строк и возвращает интернированную строку — саму строку string или её копию. Интернирование строк полезно для небольшого ускорения поиска в словарях: если ключи словаря интернированы и ключ поиска также интернирован, сравнение ключей (после хеширования) можно выполнить сравнением указателей, а не строк. Обычно имена, используемые в программах Python, интернируются автоматически, а словари для хранения атрибутов модулей, классов и экземпляров содержат интернированные ключи.

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

sys.is_finalizing(): Возвращает True, если интерпретатор Python завершает работу, и False в противном случае.

Добавлено в версии 3.5.

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

Добавлено в версии 3.12.

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: Целое число, задающее значение наибольшей кодовой точки Юникода, то есть 1114111 (в шестнадцатеричном виде — 0x10FFFF).

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

sys.meta_path

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

См. также

importlib.abc.MetaPathFinder: Абстрактный базовый класс, определяющий интерфейс объектов поиска в meta_path.
importlib.machinery.ModuleSpec: Конкретный класс, экземпляры которого должен возвращать метод find_spec().

Изменено в версии 3.4: Спецификации модулей модулей появились в Python 3.4 благодаря PEP 451.

Изменено в версии 3.12: Удалён резервный механизм поиска метода 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.

Добавлено в версии 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

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

Первоначально определено в PEP 302.

sys.path_importer_cache

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

Первоначально определено в PEP 302.

sys.platform

Эта строка содержит идентификатор платформы, который можно использовать, например, для добавления специфичных для платформы компонентов в sys.path.

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

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

Для других систем используются следующие значения:

Система	значение `platform`
AIX	`'aix'`
Emscripten	`'emscripten'`
Linux	`'linux'`
WASI	`'wasi'`
Windows	`'win32'`
Windows/Cygwin	`'cygwin'`
macOS	`'darwin'`

Изменено в версии 3.3: В Linux sys.platform больше не содержит номер основной версии. Теперь оно всегда равно 'linux', а не 'linux2' или 'linux3'. Поскольку в более старых версиях Python указывается номер версии, рекомендуется всегда использовать приведённый выше идиоматичный способ startswith.

Изменено в версии 3.8: В AIX sys.platform больше не содержит номер основной версии. Теперь оно всегда равно 'aix', а не 'aix5' или 'aix7'. Поскольку в более старых версиях Python указывается номер версии, рекомендуется всегда использовать приведённый выше идиоматичный способ startswith.

См. также

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

Модуль platform позволяет подробно определить систему.

sys.platlibdir

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

На большинстве платформ оно равно "lib". В Fedora и SuSE на 64-разрядных платформах оно равно "lib64", что даёт следующие пути 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 сторонних пакетов

Добавлено в версии 3.9.

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

Примечание

Если используется виртуальное окружение, это значение изменяется в 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).

Доступность: Unix.

sys.set_int_max_str_digits(maxdigits): Задаёт используемое этим интерпретатором ограничение длины строкового представления целого числа. См. также get_int_max_str_digits().

Добавлено в версии 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.
'c_return': Функция C завершила работу. arg — объект функции C.
'c_exception': Функция C вызвала исключение. arg — объект функции C.

Вызывает событие аудита sys.setprofile без аргументов.

sys.setrecursionlimit(limit)

Задаёт максимальную глубину стека интерпретатора Python, равную limit. Это ограничение предотвращает переполнение стека C и аварийное завершение Python из-за бесконечной рекурсии.

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

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

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

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

Добавлено в версии 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 у этого кадра.
'return': Функция (или другой блок кода) собирается завершить работу. Вызывается локальная функция трассировки; arg — возвращаемое значение либо None, если событие вызвано возникновением исключения. Возвращаемое значение функции трассировки игнорируется.
'exception': Произошло исключение. Вызывается локальная функция трассировки; arg — кортеж (exception, value, traceback); возвращаемое значение задаёт новую локальную функцию трассировки.
'opcode': Интерпретатор собирается выполнить новый код операции (подробности о кодах операций см. в dis). Вызывается локальная функция трассировки; arg равно None; возвращаемое значение задаёт новую локальную функцию трассировки. По умолчанию события для каждого кода операции не генерируются: для их включения необходимо явно задать f_trace_opcodes значение True у кадра.

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

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

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

Вызывает событие аудита sys.settrace без аргументов.

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

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

Изменено в версии 3.12: событие 'opcode' будет генерироваться только в том случае, если для f_trace_opcodes хотя бы одного кадра задано значение True до вызова settrace(). В версии 3.13 это поведение будет возвращено к прежнему, чтобы соответствовать предыдущим версиям.

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

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

Вызывает событие аудита sys.set_asyncgen_hooks_firstiter без аргументов.

Вызывает событие аудита sys.set_asyncgen_hooks_finalizer без аргументов.

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

Добавлено в версии 3.6: Дополнительные сведения см. в PEP 525. Пример реализации метода finalizer см. в реализации asyncio.Loop.shutdown_asyncgens в файле Lib/asyncio/base_events.py

Примечание

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

sys.set_coroutine_origin_tracking_depth(depth)

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

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

Эта настройка действует отдельно для каждого потока.

Добавлено в версии 3.7.

Примечание

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

sys.activate_stack_trampoline(backend, /)

Активирует backend трамплина профилировщика стека. Поддерживается только backend "perf".

Доступность: Linux.

Добавлено в версии 3.12.

См. также

sys.deactivate_stack_trampoline()

Деактивирует текущий backend трамплина профилировщика стека.

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

Доступность: Linux.

Добавлено в версии 3.12.

sys.is_stack_trampoline_active(): Возвращает True, если активен трамплин профилировщика стека.

Доступность: Linux.

Добавлено в версии 3.12.

sys._enablelegacywindowsfsencoding()

Изменяет кодировку файловой системы и обработчик ошибок соответственно на ‘mbcs’ и ‘replace’ для обеспечения совместимости с версиями Python до 3.6.

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

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

Доступность: Windows.

Добавлено в версии 3.6: Дополнительные сведения см. в PEP 529.

sys.stdin

sys.stdout

sys.stderr

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

stdin используется для всего интерактивного ввода (включая вызовы input());
stdout используется для вывода print() и операторов выражений, а также для приглашений к вводу функции input();
Собственные приглашения интерпретатора и сообщения об ошибках выводятся в stderr.

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

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

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

Особое поведение консоли можно переопределить, задав переменную окружения 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.

Добавлено в версии 3.10.

sys.thread_info

Именованный кортеж, содержащий информацию о реализации потоков.

thread_info.name

Название реализации потоков:

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

thread_info.lock

Название реализации блокировок:

"semaphore": в блокировке используется семафор
"mutex+cond": в блокировке используются мьютекс и условная переменная
None, если эта информация неизвестна

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

Добавлено в версии 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}'; если err_msg равно None, используется сообщение об ошибке «Exception ignored in».

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

См. также

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

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

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

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

При возникновении исключения, которое невозможно обработать, возбуждается событие аудита sys.unraisablehook с аргументами hook и unraisable. Объект unraisable совпадает с объектом, который будет передан обработчику. Если обработчик не задан, hook может быть None.

Добавлено в версии 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 в DLL Python. Обычно это основные и дополнительные номера версии запущенного интерпретатора Python. Значение предоставляется в модуле sys для справки; его изменение не влияет на используемые Python ключи реестра.

Доступность: 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. Другие реализации могут предоставлять к ним доступ иными способами или не предоставлять его вовсе.

Добавлено в версии 3.2.

Ссылки

[C99]

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