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

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

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

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

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

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__ со значением, которое считается истинным. В противном случае функции трассировки пропускают хук.

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 без аргументов.

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

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

_emscripten_info.emscripten_version: Версия Emscripten в виде кортежа целых чисел (основная, дополнительная и исправительная версии), например (3, 1, 8).

_emscripten_info.runtime: Строка среды выполнения, например строка user agent браузера, '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 для флага 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

Именованный кортеж, содержащий сведения о типе 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() работает с числами с плавающей точкой. Если строка имеет значение 'short', то для конечного числа с плавающей точкой 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.getandroidapilevel(): Возвращает целым числом версию API Android, использованную при сборке.

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

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

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

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

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

sys.getfilesystemencoding()

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

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

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.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: Название алгоритма хеширования 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_type

sys.last_value

sys.last_traceback

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

Значение переменных совпадает со значениями, возвращаемыми описанной выше функцией 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. В более ранних версиях Python выполнялся поиск метода с именем 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.

Изменено в версии 3.3: Если объект поиска не найден, сохраняется None вместо imp.NullImporter.

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

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

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

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.