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' на платформах с большим порядком байтов (старший байт вначале), и 'little' на платформах с малым порядком байтов (младший байт вначале).

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

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

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

Устарело начиная с версии 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)

Если значение не является 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: Строка runtime, например, пользовательский агент браузера, 'Node.js v14.18.2' или 'UNKNOWN'.

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

_emscripten_info.shared_memory: True, если Python скомпилирован с поддержкой shared memory.

Доступность: 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', то для конечного числа с плавающей точкой 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(): Возвращает имя текущего кодирования по умолчанию для строк, используемое реализацией Unicode.

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

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

sys.getfilesystemencoding()

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

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

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

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

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

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

Изменено в версии 3.7: Возвращает 'utf-8', если включён режим 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__ объекта и добавляет дополнительную нагрузку сборщика мусора, если объект управляется сборщиком мусора.

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

END_OF_DOCUMENT_MARKER

sys.getobjects(limit[, type])

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

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

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

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

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

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

sys.gettrace(): Получить функцию отслеживания, установленную с помощью settrace().

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

sys.getwindowsversion()

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

platform будет 2 (VER_PLATFORM_WIN32_NT).

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

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

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

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

Примечание

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

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

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

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

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

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

Примечание

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

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

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

Примечание

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

sys.hash_info

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

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 версия.

END_OF_DOCUMENT_MARKER

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_gil_enabled(): Возвращает True, если GIL включен, и False, если он отключен.

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

sys.is_finalizing()

Возвращает True, если главная интерпретация Python выключается. В противном случае возвращает False.

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

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

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

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

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

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

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

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

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

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

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

sys.meta_path

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

См. также

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

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

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

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

sys.orig_argv

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

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

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

sys.path

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

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

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

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

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

См. также

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

sys.path_hooks

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

Первоначально указано в PEP 302.

sys.path_importer_cache

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

Первоначально указано в PEP 302.

END_OF_DOCUMENT_MARKER

sys.platform

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

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

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

if sys.platform.startswith('freebsd'):
    # FreeBSD-specific code here...

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

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

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

См. также

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

Модуль platform предоставляет подробные проверки идентификации системы.

sys.platlibdir

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

На большинстве платформ оно равно "lib". На Fedora и SuSE для 64-битных платформ оно равно "lib64", что даёт следующие sys.path пути (где X.Y — версия Python major.minor):

/usr/lib64/pythonX.Y/: Стандартная библиотека (например, os.py модуля os)
/usr/lib64/pythonX.Y/lib-dynload/: Модули расширения C стандартной библиотеки (например, модуль errno, точное имя файла зависит от платформы)
/usr/lib/pythonX.Y/site-packages/ (всегда используйте lib, а не sys.platlibdir): Модули сторонних разработчиков
/usr/lib64/pythonX.Y/site-packages/: Модули расширения C сторонних пакетов

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

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

Примечание

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

sys.ps1
sys.ps2: Строки, задающие первичный и вторичный приглашающий символ интерпретатора. Определяются только если интерпретатор находится в интерактивном режиме. Их начальные значения в этом случае — '>>> ' и '... '. Если в одну из переменных присвоено нестроковое значение, его str() переоценивается каждый раз, когда интерпретатор готовится прочитать новую интерактивную команду; это позволяет реализовывать динамический приглашающий символ.

sys.setdlopenflags(n): Устанавливает флаги, используемые интерпретатором для dlopen() вызовов, таких как при загрузке модулей расширения. Среди прочего, это позволит обеспечить отложенное разрешение символов при импорте модуля, если вызвать как sys.setdlopenflags(0). Для совместного использования символов между модулями расширения, вызов как sys.setdlopenflags(os.RTLD_GLOBAL). Символьные имена значений флагов можно найти в модуле os (постоянные RTLD_xxx, например, os.RTLD_LAZY).

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

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

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

sys.setprofile(profilefunc)

Устанавливает системную функцию профилирования, которая позволяет реализовать в Python профайлер кода Python. См. главу Профайлеры Python для получения дополнительной информации о профайлере Python. Системная функция профилирования вызывается аналогично системной функции отслеживания (см. settrace()), но вызывается с разными событиями, например, она не вызывается для каждой выполняемой строки кода (только при вызове и возврате, но событие возврата сообщается даже при возникновении исключения). Функция специфична для потока, но для профайлера нет способа узнать о переключениях контекста между потоками, поэтому использовать её в многопоточном окружении не имеет смысла. Кроме того, её возвращаемое значение не используется, поэтому оно может просто вернуть None. Ошибка в функции профилирования приведёт к её удалению.

Примечание

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

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

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

'call': Функция вызывается (или вводится другой блок кода). Функция профилирования вызывается; arg — None.
'return': Функция (или другой блок кода) возвращает значение. Функция профилирования вызывается; arg — возвращаемое значение или None, если событие вызвано поднятием исключения.
'c_call': Называется функция C. Это может быть функция расширения или встроенная функция. arg — объект функции C.
'c_return': Функция C возвратила значение. arg — объект функции C.
'c_exception': Функция C подняла исключение. arg — объект функции C.

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

sys.setrecursionlimit(limit)

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

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

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

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

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

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

sys.settrace(tracefunc)

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

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

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

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

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

Примечание

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

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

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

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

Для более тонкой настройки можно установить функцию отслеживания, явно присвоив frame.f_trace = tracefunc, а не полагаясь на то, что она установлена косвенно через возвращаемое значение уже установленной функции отслеживания. Это также необходимо для активации функции отслеживания в текущем кадре, чего settrace() не делает. Обратите внимание, что для работы глобальная функция отслеживания должна быть установлена с помощью settrace(), чтобы включить механизм runtime-отслеживания, но она не обязательно должна быть той же функцией отслеживания (например, это может быть функция отслеживания с низкой нагрузкой, которая просто возвращает 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. Поддерживается только "perf".

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

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

См. также

sys.deactivate_stack_trampoline()

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

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

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

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

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

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

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

sys._enablelegacywindowsfsencoding()

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

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

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

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

Примечание

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

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

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

sys.stdin

sys.stdout

sys.stderr

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

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

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

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

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

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

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

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

Примечание

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

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

sys.__stdin__

sys.__stdout__

sys.__stderr__

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

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

Примечание

В некоторых условиях stdin, stdout и stderr, а также исходные значения __stdin__, __stdout__ и __stderr__ могут быть None. Это обычно происходит для приложений Windows GUI, не подключенных к консоли, и приложений Python, запущенных с помощью pythonw.

sys.stdlib_module_names

Неизменяемое множество строк, содержащих имена модулей стандартной библиотеки.

Оно одинаково на всех платформах. Также включены модули, недоступные на некоторых платформах, и модули, отключенные при сборке Python. Все типы модулей: чисто Python, встроенные, замороженные и модули расширений. Тестовые модули исключены.

Для пакетов указан только основной пакет: подпакеты и подмодули не указаны. Например, пакет email указан, но подпакет email.mime и подмодуль email.message не указаны.

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

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

END_OF_DOCUMENT_MARKER

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.

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: Версия API C для этой интерпретации. Программистам это может пригодиться при отладке конфликтов версий между 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.