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. Они не подходят для реализации «песочницы». В частности, вредоносный код может тривиально отключить или обойти хуки, добавленные с помощью этой функции. По меньшей мере, все хуки, связанные с безопасностью, должны быть добавлены с помощью API на C 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().

Аналог этой функции на уровне C — 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' на платформах с big-endian (сначала самый старший байт) и 'little' на платформах с little-endian (сначала младший байт).

sys.builtin_module_names

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

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

END_OF_DOCUMENT_MARKER

sys.call_tracing(func, args)

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

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

sys.copyright: Строка, содержащая копирайт интерпретатора Python.

sys._clear_type_cache()

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

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

sys._current_frames()

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

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

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

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

sys._current_exceptions()

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

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

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

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

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

sys.breakpointhook()

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

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

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

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

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

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

sys._debugmallocstats()

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

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

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

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

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

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

sys.displayhook(value)

Если значение не равно None, эта функция выводит repr(value) в sys.stdout и сохраняет значение в 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: Используйте обработчик ошибок 'backslashreplace' для UnicodeEncodeError.

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

sys._emscripten_info

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

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

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

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

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

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

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

END_OF_DOCUMENT_MARKER

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

Эта функция возвращает представление исключения старого стиля. Если в данный момент обрабатывается исключение (то есть 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.

Примечание

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

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

sys.exit([arg])

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

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

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

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

sys.flags

Кортеж с именованными полями 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() ведёт себя для чисел с плавающей запятой. Если строка имеет значение 'short', то для конечного float x, repr(x) стремится произвести короткую строку с свойством float(repr(x)) == x. Это обычное поведение в Python 3.1 и более поздних версиях. В противном случае, float_repr_style имеет значение 'legacy' и repr(x) ведёт себя так же, как в версиях Python до 3.1.

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

sys.getallocatedblocks()

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

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

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

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

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

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

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

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

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

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

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

END_OF_DOCUMENT_MARKER

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', если включен режим Python UTF-8.

sys.getfilesystemencodeerrors()

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

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

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

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

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

sys.getrefcount(object)

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

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

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

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

sys.getsizeof(object[, default])

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

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

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

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

См. рецепт рекурсивного 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.

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

A именованный кортеж хранящий информацию об внутренней представлении целых чисел в 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)

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

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

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

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

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

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

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

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

sys.maxunicode: Целое число, задающее значение наибольшего кода символа Юникода, т.е. 1114111 (0x10FFFF в шестнадцатеричном формате).

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

sys.meta_path

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

См. также

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

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

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

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

END_OF_DOCUMENT_MARKER

sys.orig_argv

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

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

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

sys.path

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

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

python -m module командная строка: добавляет текущую рабочую директорию.
python script.py командная строка: добавляет директорию скрипта. Если это символическая ссылка, разрешает символические ссылки.
python -c code и python (REPL) командные строки: добавляет пустую строку, что означает текущую рабочую директорию.

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

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

См. также

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

sys.path_hooks

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

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

sys.path_importer_cache

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

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

sys.platform

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

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

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

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

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

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

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

См. также

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() переоценивается каждый раз, когда интерпретатор готовится прочитать новую интерактивную команду; это можно использовать для реализации динамического приглашения.

END_OF_DOCUMENT_MARKER

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.

END_OF_DOCUMENT_MARKER

sys.settrace(tracefunc)

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

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

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

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

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

Примечание

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

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

'call': Вызвана функция (или другой блок кода). Вызывается глобальная функция отслеживания; arg — None; возвращаемое значение определяет локальную функцию отслеживания.
'line': Интерпретатор собирается выполнить новую строку кода или повторно выполнить условие цикла. Вызывается локальная функция отслеживания; arg — None; возвращаемое значение определяет новую локальную функцию отслеживания. См. Objects/lnotab_notes.txt для подробного объяснения работы. События по строкам могут быть отключены для кадра, установив f_trace_lines на False в этом кадре.
'return': Функция (или другой блок кода) собирается вернуть. Вызывается локальная функция отслеживания; arg — значение, которое будет возвращено, или None, если событие вызвано возбуждением исключения. Возвращаемое значение функции отслеживания игнорируется.
'exception': Произошло исключение. Вызывается локальная функция отслеживания; arg — кортеж (exception, value, traceback); возвращаемое значение определяет новую локальную функцию отслеживания.
'opcode': Интерпретатор собирается выполнить новый оператор кода (см. dis для получения подробностей об операторах). Вызывается локальная функция отслеживания; arg — None; возвращаемое значение определяет новую локальную функцию отслеживания. События по операторам кода по умолчанию не генерируются: их необходимо явно запросить, установив f_trace_opcodes на True в кадре.

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

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

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

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

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

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

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

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

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

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

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

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

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

Примечание

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

sys.set_coroutine_origin_tracking_depth(depth)

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

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

Эта настройка специфична для потока.

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

Примечание

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

sys.activate_stack_trampoline(backend, /)

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

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

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

См. также

END_OF_DOCUMENT_MARKER

sys.deactivate_stack_trampoline()

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

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

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

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

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

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

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

sys._enablelegacywindowsfsencoding()

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

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

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

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

Добавлена в версии 3.6: См. PEP 529 для получения дополнительной информации.

sys.stdin

sys.stdout

sys.stderr

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

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

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

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

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

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

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

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

Примечание

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

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

sys.__stdin__

sys.__stdout__

sys.__stderr__

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

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

Примечание

В некоторых условиях stdin, stdout и stderr, а также исходные значения __stdin__, __stdout__ и __stderr__ могут быть None. Это обычно происходит для приложений Windows GUI, которые не подключены к консоли, и приложений 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.

END_OF_DOCUMENT_MARKER

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.

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.