sys — Системные параметры и функции

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

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

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

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

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

sys.addaudithook(hook)

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

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

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

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

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

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

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

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

sys.argv

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

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

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

Примечание

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

sys.audit(event, *args)

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

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

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

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

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

См. таблицу событий аудита, содержащую все события, вызываемые CPython.

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

sys.base_exec_prefix

Эквивалентно exec_prefix, но относится к базовой установке Python.

При работе в виртуальном окружении значение exec_prefix переопределяется префиксом виртуального окружения. base_exec_prefix, напротив, не меняется и всегда указывает на базовую установку Python. Дополнительные сведения см. в разделе Виртуальные окружения.

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

sys.base_prefix

Эквивалентно prefix, но относится к базовой установке Python.

При работе в виртуальном окружении значение prefix переопределяется префиксом виртуального окружения. base_prefix, напротив, не меняется и всегда указывает на базовую установку Python. Дополнительные сведения см. в разделе Виртуальные окружения.

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

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

sys.builtin_module_names

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

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

sys.call_tracing(func, args)

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

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

sys.copyright: Строка с информацией об авторских правах на интерпретатор Python.

sys._clear_type_cache()

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

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

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

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

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

sys._current_frames()

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

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

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

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

sys._current_exceptions()

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

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

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

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

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

sys.breakpointhook()

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

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

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

Обратите внимание: если при импорте вызываемого объекта, указанного в PYTHONBREAKPOINT, возникнет ошибка, будет выдано предупреждение RuntimeWarning, а точка останова будет проигнорирована.

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

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

sys._debugmallocstats()

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

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

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

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

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

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

sys.displayhook(value)

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

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

Псевдокод:

def displayhook(value):
    if value is None:
        return
    # Set '_' to None to avoid recursion
    builtins._ = None
    text = repr(value)
    try:
        sys.stdout.write(text)
    except UnicodeEncodeError:
        bytes = text.encode(sys.stdout.encoding, 'backslashreplace')
        if hasattr(sys.stdout, 'buffer'):
            sys.stdout.buffer.write(bytes)
        else:
            text = bytes.decode(sys.stdout.encoding, 'strict')
            sys.stdout.write(text)
    sys.stdout.write("\n")
    builtins._ = value

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

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

sys._emscripten_info

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

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

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

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

sys.pycache_prefix

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

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

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

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

sys.excepthook(type, value, traceback)

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

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

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

См. также

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

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

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

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

sys.exception()

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

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

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

sys.exc_info()

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

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

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

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

Примечание

Если используется виртуальное окружение, это значение exec_prefix будет указывать на виртуальное окружение. Значение для установки Python по-прежнему будет доступно через base_exec_prefix. Дополнительные сведения см. в разделе Виртуальные окружения.

Изменено в версии 3.14: При работе в виртуальном окружении значения prefix и exec_prefix теперь устанавливаются в префикс виртуального окружения при инициализации путей, а не модулем site. Это означает, что prefix и exec_prefix всегда указывают на виртуальное окружение, даже если site отключён (-S).

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

sys.exit([arg])

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

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

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

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

sys.flags

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

`flags.debug`	`-d`
`flags.inspect`	`-i`
`flags.interactive`	`-i`
`flags.isolated`	`-I`
`flags.optimize`	`-O` или `-OO`
`flags.dont_write_bytecode`	`-B`
`flags.no_user_site`	`-s`
`flags.no_site`	`-S`
`flags.ignore_environment`	`-E`
`flags.verbose`	`-v`
`flags.bytes_warning`	`-b`
`flags.quiet`	`-q`
`flags.hash_randomization`	`-R`
`flags.dev_mode`	`-X dev` (режим разработки Python)
`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`
`flags.gil`	`-X gil` и `PYTHON_GIL`
`flags.thread_inherit_context`	`-X thread_inherit_context` и `PYTHON_THREAD_INHERIT_CONTEXT`
`flags.context_aware_warnings`	`-X context_aware_warnings` и `PYTHON_CONTEXT_AWARE_WARNINGS`

Изменено в версии 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.

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

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

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

sys.float_info

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

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

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

>>> import sys
>>> sys.float_info.dig
15
>>> s = '3.14159265358979'    # decimal string with 15 significant digits
>>> format(float(s), '.15g')  # convert to float and back -> same value
'3.14159265358979'

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

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

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

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

sys.getallocatedblocks()

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

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

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

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

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

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

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

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

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

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

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

sys.getfilesystemencoding()

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

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

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

Особенность реализации CPython: бессмертные объекты Immortal с большим счётчиком ссылок можно распознать с помощью _is_immortal().

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

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

sys.getsizeof(object[, default])

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

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

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

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

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

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

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

sys._getframe([depth])

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

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

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

sys._getframemodulename([depth])

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

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

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

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

sys.getobjects(limit[, type])

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

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

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

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

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

sys.getprofile(): Возвращает функцию профилирования, заданную с помощью setprofile().

sys.gettrace(): Возвращает функцию трассировки, заданную с помощью settrace().

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

sys.getwindowsversion()

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

platform будет равно 2 (VER_PLATFORM_WIN32_NT).

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

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

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

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

Примечание

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

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

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

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

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

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

Примечание

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

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

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

Примечание

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

sys.hash_info

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

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

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

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

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

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

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

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

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

hash_info.cutoff: Пороговое значение для оптимизации DJBX33A коротких строк в диапазоне [1, cutoff).

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

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

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, это означает, что кэширование модулей следует отключить.

supports_isolated_interpreters — логическое значение, указывающее, поддерживает ли эта реализация несколько изолированных интерпретаторов. Для CPython на большинстве платформ оно равно True. На платформах с такой поддержкой реализован низкоуровневый модуль _interpreters.

См. также

PEP 684, PEP 734 и concurrent.interpreters.

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

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

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

Примечание

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

sys.int_info

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

int_info.bits_per_digit: Количество битов в каждой цифре. Целые числа Python хранятся внутри в системе счисления с основанием 2**int_info.bits_per_digit.

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

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

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

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

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

sys.__interactivehook__

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

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

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

sys.intern(string)

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

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

sys._is_gil_enabled(): Возвращает True, если GIL включена, и False, если она отключена.

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

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

sys.is_finalizing()

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

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

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

sys._jit

Средства для наблюдения за компиляцией «на лету».

Особенность реализации CPython: JIT-компиляция — это экспериментальная особенность реализации CPython. Наличие sys._jit и его одинаковое поведение во всех реализациях Python, версиях и конфигурациях сборки не гарантируются.

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

_jit.is_available(): Возвращает True, если текущий исполняемый файл Python поддерживает JIT-компиляцию, и False в противном случае. Это можно настроить, собрав CPython с параметром --experimental-jit в Windows и с параметром --enable-experimental-jit на всех остальных платформах.

_jit.is_enabled(): Возвращает True, если JIT-компиляция включена для текущего процесса Python (что подразумевает sys._jit.is_available()), и False в противном случае. Если JIT-компиляция доступна, ее можно включить или отключить при запуске интерпретатора, задав переменной окружения PYTHON_JIT значение 0 (отключено) или 1 (включено).

_jit.is_active()

Возвращает True, если верхний кадр Python в данный момент выполняет JIT-код (что подразумевает sys._jit.is_enabled()), и False в противном случае.

Примечание

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

Примечание

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

>>> for warmup in range(BIG_NUMBER):
...     # This line is "hot", and is eventually JIT-compiled:
...     if sys._jit.is_active():
...         # This line is "cold", and is run in the interpreter:
...         assert sys._jit.is_active()
...
Traceback (most recent call last):
  File "<stdin>", line 5, in <module>
    assert sys._jit.is_active()
           ~~~~~~~~~~~~~~~~~~^^
AssertionError

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

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

sys._is_immortal(op): Возвращает True, если указанный объект является бессмертным, и False в противном случае.

Примечание

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

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

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

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

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

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

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

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

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

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

sys.meta_path

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

См. также

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

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

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

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

sys.orig_argv

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

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

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

sys.path

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

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

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

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

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

См. также

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

sys.path_hooks

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

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

sys.path_importer_cache

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

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

sys.platform

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

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

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

if sys.platform.startswith('sunos'):
    # SunOS-specific code here...

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

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

Изменено в версии 3.13: В Android sys.platform теперь возвращает 'android', а не 'linux'.

Изменено в версии 3.14: В FreeBSD sys.platform больше не содержит основную версию. Теперь это всегда 'freebsd', а не 'freebsd13' или 'freebsd14'.

См. также

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. Производные пути см. в разделе Пути установки.

Примечание

Если используется виртуальное окружение, этот prefix будет указывать на виртуальное окружение. Значение для установки Python по-прежнему доступно через base_prefix. Дополнительные сведения см. в разделе Виртуальные окружения.

Изменено в версии 3.14: При работе в виртуальном окружении значения prefix и exec_prefix теперь устанавливаются в префикс виртуального окружения при инициализации путей, а не в site. Это означает, что prefix и exec_prefix всегда указывают на виртуальное окружение, даже если site отключён (-S).

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

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

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

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

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

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

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

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

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

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

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

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

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

Примечание

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

sys.set_coroutine_origin_tracking_depth(depth)

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

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

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

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

Примечание

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

sys.activate_stack_trampoline(backend, /)

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

Трамплины стека нельзя активировать, если активен JIT.

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

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

См. также

sys.deactivate_stack_trampoline()

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

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

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

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

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

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

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

sys.remote_exec(pid, script)

Выполняет script — файл с кодом Python в удалённом процессе с указанным pid.

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

В удалённом процессе должен работать интерпретатор CPython той же основной и дополнительной версии, что и в локальном процессе. Если локальный или удалённый интерпретатор является предварительной версией (альфа-, бета-версией или кандидатом на выпуск), локальный и удалённый интерпретаторы должны иметь абсолютно одинаковую версию.

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

При выполнении кода в удалённом процессе возникает событие аудита sys.remote_exec с аргументами pid и путём к файлу скрипта. Это событие возникает в процессе, вызвавшем sys.remote_exec().

При выполнении скрипта в удалённом процессе возникает событие аудита cpython.remote_debugger_script с путём в удалённом процессе. Это событие возникает в удалённом процессе, а не в процессе, вызвавшем sys.remote_exec().

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

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

sys._enablelegacywindowsfsencoding()

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

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

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

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

Примечание

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

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

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

sys.stdin

sys.stdout

sys.stderr

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

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

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

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

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

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

На любой платформе можно переопределить кодировку символов, задав перед запуском Python переменную окружения PYTHONIOENCODING или используя новый параметр командной строки -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, эквивалентная макросу C PYTHON_API_VERSION. Определена для обратной совместимости.

В настоящее время эта константа не обновляется в новых версиях 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.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.