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

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

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

Устарело с версии 3.13: Вместо неё используйте более универсальную функцию _clear_internal_caches().

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

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

sys._current_frames()

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

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

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

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

sys._current_exceptions()

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

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

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

Вызывает событие аудита 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 не проверяется.

Добавлено в версии 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: Если это значение истинно, 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 скомпилирован с поддержкой потоков 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 для флага -I isolated.

Изменено в версии 3.7: Добавлен атрибут dev_mode для нового режима разработки Python и атрибут 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

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

Атрибуты именованного кортежа `float_info`
атрибут	макрос 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_internal_caches() и gc.collect().

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

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

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

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

sys.getandroidapilevel(): Возвращает целое число, обозначающее уровень API Android на момент сборки. Оно представляет минимальную версию Android, на которой может работать эта сборка Python. Сведения о версии во время выполнения см. в разделе platform.android_ver().

Доступность: 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().

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

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.

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

sys.getobjects(limit[, type])

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

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

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

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

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

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 — кортеж из 3 элементов, а все остальные значения являются целыми числами. К компонентам также можно обращаться по имени, поэтому 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: Название алгоритма хеширования строк, байтов и объектов 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_gil_enabled(): Возвращает True, если GIL включена, и False, если она отключена.

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

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

sys.is_finalizing()

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

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

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

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

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

sys._is_interned(string): Возвращает True, если заданная строка интернирована, и False в противном случае.

Добавлено в версии 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 в зависимости от параметра конфигурации, определявшего, хранятся ли символы Unicode в формате 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

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

Система	Значение `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 на 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

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.

Примечание

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

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

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

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.