sys
— Параметры и функции, специфичные для системы¶
Этот модуль предоставляет доступ к некоторым переменным, используемым или поддерживаемым интерпретатором, а также к функциям, которые активно взаимодействуют с интерпретатором. Он всегда доступен.
- sys.abiflags¶
На POSIX-системах, где Python был собран с помощью стандартного скрипта
configure
, он содержит флаги ABI, указанные в PEP 3149.Added in version 3.2.
Изменено в версии 3.8: Флаги по умолчанию стали пустой строкой (флаг``m`` для pymalloc был удален).
Availability: Unix.
- sys.addaudithook(hook)¶
Добавляет вызываемый hook в список активных крючков аудита для текущего (под)интерпретатора.
Когда событие аудита поднимается с помощью функции
sys.audit()
, каждый крючок будет вызван в том порядке, в котором он был добавлен, с именем события и кортежем аргументов. Сначала вызываются нативные хуки, добавленные с помощьюPySys_AddAuditHook()
, затем хуки, добавленные в текущем (под)интерпретаторе. Хуки могут регистрировать событие, вызывать исключение для прерывания операции или полностью завершать процесс.Обратите внимание, что крючки аудита предназначены в первую очередь для сбора информации о внутренних или иных ненаблюдаемых действиях, как Python, так и библиотек, написанных на Python. Они не подходят для реализации «песочницы». В частности, вредоносный код может тривиально отключить или обойти крючки, добавленные с помощью этой функции. Как минимум, все чувствительные к безопасности крючки должны быть добавлены с помощью C API
PySys_AddAuditHook()
перед инициализацией среды выполнения, а любые модули, позволяющие произвольно модифицировать память (например,ctypes
), должны быть полностью удалены или тщательно контролироваться.Поднимает auditing event
sys.addaudithook
без аргументов.Смотрите audit events table для всех событий, вызванных CPython, и PEP 578 для обсуждения оригинального дизайна.
Added in version 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, см. в разделе audit events table.
Added in version 3.8.
- sys.base_exec_prefix¶
Устанавливается во время запуска Python, перед запуском
site.py
, в то же значение, что иexec_prefix
. Если virtual environment не запущен, значения останутся прежними; еслиsite.py
обнаружит, что используется виртуальная среда, значенияprefix
иexec_prefix
будут изменены, чтобы указывать на виртуальную среду, тогда какbase_prefix
иbase_exec_prefix
останутся указывать на базовую установку Python (ту, из которой была создана виртуальная среда).Added in version 3.3.
- sys.base_prefix¶
Устанавливается во время запуска Python, перед запуском
site.py
, в то же значение, что иprefix
. Если virtual environment не запущен, значения останутся прежними; еслиsite.py
обнаружит, что используется виртуальная среда, значенияprefix
иexec_prefix
будут изменены, чтобы указывать на виртуальную среду, тогда какbase_prefix
иbase_exec_prefix
останутся указывать на базовую установку Python (ту, из которой была создана виртуальная среда).Added in version 3.3.
- sys.byteorder¶
Индикатор собственного порядка байтов. Имеет значение
'big'
на платформах с big-endian (старший байт первый) и'little'
на платформах с little-endian (младший байт первый).
- 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()¶
Очистите все внутренние кэши, связанные с производительностью. Используйте эту функцию только для освобождения ненужных ссылок и блоков памяти при поиске утечек.
Added in version 3.13.
- sys._current_frames()¶
Возвращает словарь, отображающий идентификатор каждого потока на самый верхний кадр стека, активный в этом потоке на момент вызова функции. Обратите внимание, что функции в модуле
traceback
могут построить стек вызовов с учетом такого фрейма.Это наиболее полезно для отладки тупиковых ситуаций: функция не требует сотрудничества тупиковых потоков, и стеки вызовов таких потоков замораживаются до тех пор, пока они остаются в тупике. Кадр, возвращаемый для не заблокированного потока, может не иметь никакого отношения к текущей активности этого потока к тому моменту, когда вызывающий код изучит этот кадр.
Эта функция должна использоваться только для внутренних и специализированных целей.
Поднимает auditing event
sys._current_frames
без аргументов.
- sys._current_exceptions()¶
Возвращает словарь, отображающий идентификатор каждого потока на самое верхнее исключение, активное в этом потоке на момент вызова функции. Если поток в данный момент не обрабатывает исключение, он не включается в словарь результатов.
Это наиболее полезно для статистического профилирования.
Эта функция должна использоваться только для внутренних и специализированных целей.
Поднимает auditing event
sys._current_exceptions
без аргументов.Изменено в версии 3.12: Каждое значение в словаре теперь представляет собой один экземпляр исключения, а не три кортежа, как в случае с
sys.exc_info()
.
- sys.breakpointhook()¶
Эта функция-хук вызывается встроенным
breakpoint()
. По умолчанию она перебрасывает вас в отладчикpdb
, но ее можно установить на любую другую функцию, чтобы вы могли выбирать, какой отладчик будет использоваться.Сигнатура этой функции зависит от того, что она вызывает. Например, привязка по умолчанию (например,
pdb.set_trace()
) не ожидает никаких аргументов, но вы можете привязать ее к функции, которая ожидает дополнительных аргументов (позиционных и/или ключевых). Встроенная функцияbreakpoint()
передает свои*args
и**kws
напрямую. Все, что возвращаетbreakpointhooks()
, возвращается изbreakpoint()
.Реализация по умолчанию сначала обращается к переменной окружения
PYTHONBREAKPOINT
. Если она установлена в значение"0"
, то функция возвращается немедленно, то есть не работает. Если переменная окружения не установлена или установлена в пустую строку, вызываетсяpdb.set_trace()
. В противном случае эта переменная должна называть функцию для запуска, используя номенклатуру Python с точечным импортом, напримерpackage.subpackage.module.function
. В этом случае будет импортированаpackage.subpackage.module
, а результирующий модуль должен содержать вызываемую функцию с именемfunction()
. Он запускается, передавая*args
и**kws
, и все, что возвращаетfunction()
,sys.breakpointhook()
возвращает встроенной функцииbreakpoint()
.Обратите внимание, что если при импорте вызываемой переменной с именем
PYTHONBREAKPOINT
что-то пойдет не так, то будет выдано сообщениеRuntimeWarning
и точка останова будет проигнорирована.Также обратите внимание, что если
sys.breakpointhook()
переопределяется программно, тоPYTHONBREAKPOINT
не обращается.Added in version 3.7.
- sys._debugmallocstats()¶
Выведите на stderr низкоуровневую информацию о состоянии аллокатора памяти CPython.
Если Python имеет значение built in debug mode (
configure --with-pydebug option
), он также выполняет несколько дорогостоящих проверок внутренней согласованности.Added in version 3.3.
Детали реализации CPython: Эта функция специфична для CPython. Точный формат вывода здесь не определен и может измениться.
- sys.dllhandle¶
Целое число, указывающее дескриптор библиотеки Python DLL.
Availability: 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
вызывается по результату оценки expression, введенной в интерактивной сессии 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¶
Кортеж named tuple, содержащий информацию об окружении на платформе wasm32-emscripten. Именованный кортеж является предварительным и может измениться в будущем.
- _emscripten_info.emscripten_version¶
Версия Emscripten в виде кортежа интов (мажор, минор, микро), например
(3, 1, 8)
.
- _emscripten_info.runtime¶
Строка времени выполнения, например, агент пользователя браузера,
'Node.js v14.18.2'
или'UNKNOWN'
.
- _emscripten_info.pthreads¶
True
, если Python скомпилирован с поддержкой pthreads в Emscripten.
True
, если Python скомпилирован с поддержкой общей памяти.
Availability: Emscripten.
Added in version 3.11.
- sys.pycache_prefix¶
Если это значение установлено (не
None
), Python будет записывать файлы.pyc
байткод-кеша в (и читать их из) параллельное дерево каталогов, корнем которого является этот каталог, а не из__pycache__
каталогов в дереве исходного кода. Любые__pycache__
каталоги в дереве исходного кода будут проигнорированы, а новые.pyc
файлы будут записаны в префикс pycache. Таким образом, если вы используетеcompileall
в качестве шага предварительной сборки, вы должны убедиться, что вы запускаете его с тем же префиксом pycache (если таковой имеется), который вы будете использовать во время выполнения.Относительный путь интерпретируется относительно текущего рабочего каталога.
Изначально это значение устанавливается на основе значения параметра
-X
pycache_prefix=PATH
параметра командной строки или переменной окруженияPYTHONPYCACHEPREFIX
(приоритет имеет командная строка). Если ни то, ни другое не установлено, значение будетNone
.Added in version 3.8.
- sys.excepthook(type, value, traceback)¶
Эта функция выводит заданный откат трассы и исключение в
sys.stderr
.Когда возникает исключение, отличное от
SystemExit
, и оно не поймано, интерпретатор вызываетsys.excepthook
с тремя аргументами: класс исключения, экземпляр исключения и объект traceback. В интерактивном сеансе это происходит непосредственно перед возвратом управления в подсказку; в программе на Python это происходит непосредственно перед выходом из программы. Обработку таких исключений верхнего уровня можно настроить, назначивsys.excepthook
другую функцию с тремя аргументами.Поднимает auditing event
sys.excepthook
с аргументамиhook
,type
,value
,traceback
.См.также
Функция
sys.unraisablehook()
обрабатывает неустранимые исключения, а функцияthreading.excepthook()
- исключения, вызванныеthreading.Thread.run()
.
- sys.__breakpointhook__¶
- sys.__displayhook__¶
- sys.__excepthook__¶
- sys.__unraisablehook__¶
Эти объекты содержат исходные значения
breakpointhook
,displayhook
,excepthook
иunraisablehook
в начале работы программы. Они сохраняются для того, чтобы можно было восстановить значенияbreakpointhook
,displayhook
иexcepthook
,unraisablehook
в случае их замены на сломанные или альтернативные объекты.Added in version 3.7: __breakpointhook__
Added in version 3.8: __unraisablehook__
- sys.exception()¶
Эта функция, вызванная во время выполнения обработчика исключений (например, клаузулы
except
илиexcept*
), возвращает экземпляр исключения, который был пойман этим обработчиком. Когда обработчики исключений вложены друг в друга, доступно только исключение, обработанное самым последним обработчиком.Если обработчик исключений не выполняется, эта функция возвращает
None
.Added in version 3.11.
- sys.exc_info()¶
Эта функция возвращает представление обработанного исключения в старом стиле. Если в данный момент обрабатывается исключение
e
(поэтомуexception()
вернетe
),exc_info()
вернет кортеж(type(e), e, e.__traceback__)
. То есть кортеж, содержащий тип исключения (подклассBaseException
), само исключение и traceback object, который обычно содержит стек вызовов в точке, где исключение произошло в последний раз.Если нигде в стеке не обрабатывается исключение, эта функция возвращает кортеж, содержащий три значения
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¶
Функция named tuple flags отображает состояние флагов командной строки. Атрибуты доступны только для чтения.
- flags.debug¶
- flags.inspect¶
- flags.interactive¶
- flags.isolated¶
- flags.optimize¶
- flags.dont_write_bytecode¶
- flags.no_user_site¶
- flags.no_site¶
- flags.ignore_environment¶
- flags.verbose¶
- flags.bytes_warning¶
- flags.quiet¶
- flags.hash_randomization¶
- flags.dev_mode¶
- flags.utf8_mode¶
- flags.safe_path¶
- flags.int_max_str_digits¶
-X int_max_str_digits
(integer string conversion length limitation)- flags.warn_default_encoding¶
Изменено в версии 3.2: Добавлен атрибут
quiet
для нового флага-q
.Added in version 3.2.3: Атрибут
hash_randomization
.Изменено в версии 3.3: Удален устаревший атрибут
division_warning
.Изменено в версии 3.4: Добавлен атрибут
isolated
для-I
isolated
флага.Изменено в версии 3.7: Добавлен атрибут
dev_mode
для нового флага Python Development Mode и атрибут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¶
Элемент named tuple, содержащий информацию о типе float. Он содержит низкоуровневую информацию о точности и внутреннем представлении. Значения соответствуют различным константам с плавающей точкой, определенным в стандартном заголовочном файле
float.h
для языка программирования „C“; подробнее см. раздел 5.2.4.2.2 стандарта ISO/IEC C 1999 года [C99], «Характеристики плавающих типов».¶ атрибут
макрос float.h
объяснение
- float_info.epsilon¶
DBL_EPSILON
разница между 1,0 и наименьшим значением, превышающим 1,0, которое можно представить в виде плавающей величины.
См. также
math.ulp()
.- float_info.dig¶
DBL_DIG
Максимальное количество десятичных цифр, которое может быть достоверно представлено в плавающей точке; см. ниже.
- float_info.mant_dig¶
DBL_MANT_DIG
Точность плавающей величины: количество цифр base-
radix
в значении плавающей величины.- float_info.max¶
DBL_MAX
Максимально представимое положительное конечное число.
- float_info.max_exp¶
DBL_MAX_EXP
Максимальное целое число e, такое, что
radix**(e-1)
является представимым конечным числом.- float_info.max_10_exp¶
DBL_MAX_10_EXP
Максимальное целое число e, такое, что
10**e
находится в диапазоне представимых конечных плавающих чисел.- float_info.min¶
DBL_MIN
Минимально представимое положительное нормализованное число.
Используйте
math.ulp(0.0)
, чтобы получить наименьшее положительное денормированное представимое число.- float_info.min_exp¶
DBL_MIN_EXP
Минимальное целое число e, такое, что
radix**(e-1)
является нормализованным плавающим числом.- float_info.min_10_exp¶
DBL_MIN_10_EXP
Минимальное целое число e, такое, что
10**e
является нормализованным плавающим числом.- 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'
, то для конечного floatx
,repr(x)
стремится выдать короткую строку со свойствомfloat(repr(x)) == x
. Это обычное поведение в Python 3.1 и более поздних версиях. В противном случаеfloat_repr_style
имеет значение'legacy'
, аrepr(x)
ведет себя так же, как и в версиях Python, предшествующих 3.1.Added in version 3.1.
- sys.getallocatedblocks()¶
Возвращает количество блоков памяти, выделенных интерпретатором в данный момент, независимо от их размера. Эта функция в основном полезна для отслеживания и отладки утечек памяти. Из-за внутренних кэшей интерпретатора результат может меняться от вызова к вызову; возможно, вам придется вызывать
_clear_internal_caches()
иgc.collect()
, чтобы получить более предсказуемые результаты.Если сборка или реализация Python не может разумно вычислить эту информацию, то вместо нее разрешается возвращать 0.
Added in version 3.4.
- sys.getunicodeinternedsize()¶
Возвращает количество объектов юникода, которые были интернированы.
Added in version 3.12.
- sys.getandroidapilevel()¶
Возвращает уровень API Android во время сборки в виде целого числа. Это минимальная версия Android, на которой может работать данная сборка Python. Информацию о версии для выполнения смотрите в разделе
platform.android_ver()
.Availability: Android.
Added in version 3.7.
- sys.getdefaultencoding()¶
Возвращает имя текущей кодировки строк по умолчанию, используемой реализацией Unicode.
- sys.getdlopenflags()¶
Возвращает текущее значение флагов, которые используются при вызовах
dlopen()
. Символические имена значений флагов можно найти в модулеos
(константыRTLD_xxx
, напримерos.RTLD_LAZY
).Availability: Unix.
- sys.getfilesystemencoding()¶
Получите filesystem encoding: кодировку, используемую с filesystem error handler для преобразования имен файлов в Юникод и байтовых имен файлов. Обработчик ошибок файловой системы возвращается из
getfilesystemencodeerrors()
.Для лучшей совместимости для имен файлов во всех случаях следует использовать str, хотя представление имен файлов в виде байтов также поддерживается. Функции, принимающие или возвращающие имена файлов, должны поддерживать либо str, либо bytes и внутренне преобразовывать их в предпочтительное представление системы.
os.fsencode()
иos.fsdecode()
должны использоваться для обеспечения правильной кодировки и режима ошибок.Параметры filesystem encoding and error handler настраиваются при запуске 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 Mode включен.
- sys.getfilesystemencodeerrors()¶
Получите filesystem error handler: обработчик ошибок, используемый с filesystem encoding для преобразования между именами файлов в кодировке Unicode и именами файлов в байтах. Кодировка файловой системы возвращается из
getfilesystemencoding()
.os.fsencode()
иos.fsdecode()
должны использоваться для обеспечения правильной кодировки и режима ошибок.Параметры filesystem encoding and error handler настраиваются при запуске Python функцией
PyConfig_Read()
: см. членыfilesystem_encoding
иfilesystem_errors
вPyConfig
.Added in version 3.6.
- sys.get_int_max_str_digits()¶
Возвращает текущее значение для integer string conversion length limitation. См. также
set_int_max_str_digits()
.Added in version 3.11.
- sys.getrefcount(object)¶
Возвращает счетчик ссылок на объект. Возвращаемый счетчик обычно на один больше, чем вы ожидаете, потому что он включает (временную) ссылку в качестве аргумента
getrefcount()
.Обратите внимание, что возвращаемое значение может не отражать реальное количество ссылок на объект. Например, некоторые объекты имеют значение immortal и очень высокое значение refcount, которое не отражает фактического количества ссылок. Следовательно, не стоит полагаться на точное возвращаемое значение, кроме значения 0 или 1.
Изменено в версии 3.12: Бессмертные объекты имеют очень большой счетчик ссылок, который не соответствует реальному количеству ссылок на объект.
- sys.getrecursionlimit()¶
Возвращает текущее значение предела рекурсии, максимальной глубины стека интерпретатора Python. Этот предел не позволяет бесконечной рекурсии привести к переполнению стека C и аварийному завершению работы Python. Он может быть установлен с помощью
setrecursionlimit()
.
- sys.getsizeof(object[, default])¶
Возвращает размер объекта в байтах. Объект может быть любого типа. Все встроенные объекты будут возвращать корректные результаты, но это не обязательно для сторонних расширений, так как это зависит от реализации.
Учитывается только потребление памяти, непосредственно приписываемое объекту, а не потребление памяти объектов, на которые он ссылается.
Если задано, будет возвращено значение default, если объект не предоставляет средств для получения размера. В противном случае будет вызвано сообщение
TypeError
.getsizeof()
вызывает метод__sizeof__
объекта и добавляет дополнительные накладные расходы на сборщик мусора, если объект управляется сборщиком мусора.Пример рекурсивного использования
getsizeof()
для нахождения размера контейнеров и всего их содержимого см. в recursive sizeof recipe.
- sys.getswitchinterval()¶
Возвращает «интервал переключения потоков» интерпретатора; см.
setswitchinterval()
.Added in version 3.2.
- sys._getframe([depth])¶
Возвращает объект фрейма из стека вызовов. Если указано необязательное целое число depth, возвращается фреймовый объект на столько вызовов ниже вершины стека. Если это глубже стека вызовов, то возвращается
ValueError
. По умолчанию depth равно нулю, возвращая фрейм в верхней части стека вызовов.Поднимает auditing event
sys._getframe
с аргументомframe
.Детали реализации CPython: Эту функцию следует использовать только для внутренних и специализированных целей. Не гарантируется, что она будет существовать во всех реализациях Python.
- sys._getframemodulename([depth])¶
Возвращает имя модуля из стека вызовов. Если указано необязательное целое число depth, возвращается модуль на столько вызовов ниже вершины стека. Если это глубже, чем стек вызовов, или если модуль не идентифицируется, возвращается
None
. По умолчанию значение depth равно нулю, возвращается модуль, находящийся в верхней части стека вызовов.Поднимает auditing event
sys._getframemodulename
с аргументомdepth
.Детали реализации CPython: Эту функцию следует использовать только для внутренних и специализированных целей. Не гарантируется, что она будет существовать во всех реализациях Python.
- sys.getprofile()¶
Получение функции профилировщика, заданной
setprofile()
.
- sys.gettrace()¶
Получите функцию трассировки, заданную
settrace()
.Детали реализации CPython: Функция
gettrace()
предназначена только для реализации отладчиков, профилировщиков, инструментов покрытия и тому подобного. Ее поведение является частью платформы реализации, а не частью определения языка, и поэтому может быть доступно не во всех реализациях Python.
- sys.getwindowsversion()¶
Возвращает именованный кортеж, описывающий текущую версию Windows. Именованными элементами являются major, minor, build, platform, service_pack, service_pack_minor, service_pack_major, suite_mask, product_type и platform_version. service_pack содержит строку, platform_version - три кортежа, а все остальные значения являются целыми числами. К компонентам также можно обращаться по имени, поэтому
sys.getwindowsversion()[0]
эквивалентноsys.getwindowsversion().major
. Для совместимости с предыдущими версиями только первые 5 элементов могут быть получены с помощью индексации.платформой будет
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
.Availability: Windows.
Изменено в версии 3.2: Изменен на именованный кортеж и добавлены service_pack_minor, service_pack_major, suite_mask и product_type.
Изменено в версии 3.6: Добавлена платформа_версии.
- sys.get_asyncgen_hooks()¶
Возвращает объект asyncgen_hooks, который похож на
namedtuple
вида(firstiter, finalizer)
, где firstiter и finalizer должны быть либоNone
, либо функциями, принимающими asynchronous generator iterator в качестве аргумента, и используется для планирования финализации асинхронного генератора циклом событий.Added in version 3.6: Более подробную информацию см. в разделе PEP 525.
Примечание
Эта функция была добавлена на временной основе (подробности см. в PEP 411).
- sys.get_coroutine_origin_tracking_depth()¶
Получение текущей глубины отслеживания начала корутины, заданной
set_coroutine_origin_tracking_depth()
.Added in version 3.7.
Примечание
Эта функция была добавлена временно (подробности см. в PEP 411). Используйте ее только для отладки.
- sys.hash_info¶
named tuple, задающий параметры реализации числового хэша. Подробнее о хэшировании числовых типов см. в Хеширование числовых типов.
- hash_info.width¶
Ширина в битах, используемая для хэш-значений
- hash_info.modulus¶
Простой модуль P, используемый в числовой хэш-схеме
- hash_info.inf¶
Хеш-значение, возвращаемое для положительной бесконечности
- hash_info.nan¶
(Этот атрибут больше не используется)
- hash_info.imag¶
Множитель, используемый для мнимой части комплексного числа
- hash_info.algorithm¶
Имя алгоритма для хэширования строк, байтов и просмотра памяти
- hash_info.hash_bits¶
Внутренний размер выхода хэш-алгоритма
- hash_info.seed_bits¶
Размер начального ключа хэш-алгоритма
Added in version 3.2.
Изменено в версии 3.4: Добавлены алгоритм, 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()
. Функции named tuplesys.version_info
можно использовать для более удобного для человека кодирования той же информации.Более подробную информацию о
hexversion
можно найти в Версионирование API и ABI.
- sys.implementation¶
Объект, содержащий информацию о реализации запущенного в данный момент интерпретатора Python. Следующие атрибуты должны существовать во всех реализациях Python.
name - это идентификатор реализации, например,
'cpython'
. Фактическая строка определяется реализацией Python, но она гарантированно должна быть в нижнем регистре.version - это именованный кортеж в том же формате, что и
sys.version_info
. Он представляет собой версию реализации Python. Это значение отличается от конкретной версии языка Python, которой соответствует запущенный в данный момент интерпретатор, которую представляетsys.version_info
. Например, для PyPy 1.8sys.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.Added in version 3.3.
Примечание
Добавление новых необходимых атрибутов должно проходить через обычный процесс PEP. Дополнительную информацию см. в разделе PEP 421.
- sys.int_info¶
Атрибут named tuple, содержащий информацию о внутреннем представлении целых чисел в 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
.
Added in version 3.1.
Изменено в версии 3.11: Добавлены
default_max_str_digits
иstr_digits_check_threshold
.
- sys.__interactivehook__¶
Если этот атрибут существует, его значение автоматически вызывается (без аргументов) при запуске интерпретатора в interactive mode. Это происходит после чтения файла
PYTHONSTARTUP
, так что вы можете установить этот хук там. Модульsite
sets this.Поднимает auditing event
cpython.run_interactivehook
с аргументомhook
.Added in version 3.4.
- sys.intern(string)¶
Введите строку в таблицу «интернированных» строк и верните интернированную строку - которая сама является строкой или ее копией. Интернирование строк полезно для повышения производительности поиска по словарю - если ключи в словаре интернированы, а ключ поиска интернирован, то сравнение ключей (после хэширования) может быть выполнено сравнением указателей вместо сравнения строк. Обычно имена, используемые в программах на Python, автоматически интернируются, а словари, используемые для хранения атрибутов модулей, классов или экземпляров, имеют интернированные ключи.
Внутренние строки не являются immortal; чтобы воспользоваться ими, вы должны хранить ссылку на возвращаемое значение
intern()
.
- sys._is_gil_enabled()¶
Возвращает
True
, если GIL включен, иFalse
, если выключен.Added in version 3.13.
- sys.is_finalizing()¶
Верните
True
, если основным интерпретатором Python является shutting down. В противном случае вернитеFalse
.См. также исключение
PythonFinalizationError
.Added in version 3.5.
- sys.last_exc¶
Эта переменная не всегда определена; она устанавливается в экземпляр исключения, когда исключение не обрабатывается и интерпретатор печатает сообщение об ошибке и трассировку стека. Ее назначение - позволить интерактивному пользователю импортировать модуль отладчика и заняться посмертной отладкой без необходимости повторного выполнения команды, вызвавшей ошибку. (Обычно используется
import pdb; pdb.pm()
для входа в модуль посмертной отладки; более подробную информацию см. в модулеpdb
).Added in version 3.12.
- sys._is_interned(string)¶
Возвращает
True
, если данная строка является «интернированной»,False
в противном случае.Added in version 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
, в зависимости от опции конфигурации, которая указывала, хранятся ли символы Юникода как UCS-2 или UCS-4.
- sys.meta_path¶
Список meta path finder объектов, у которых вызываются их
find_spec()
методы, чтобы проверить, может ли один из объектов найти импортируемый модуль. По умолчанию он содержит записи, реализующие стандартную семантику импорта Python. Методfind_spec()
вызывается как минимум с абсолютным именем импортируемого модуля. Если импортируемый модуль содержится в пакете, то в качестве второго аргумента передается атрибут__path__
родительского пакета. Метод возвращает module spec, илиNone
, если модуль не может быть найден.См.также
importlib.abc.MetaPathFinder
Абстрактный базовый класс, определяющий интерфейс объектов finder на
meta_path
.importlib.machinery.ModuleSpec
Конкретный класс, экземпляры которого должны возвращаться в
find_spec()
.
Изменено в версии 3.4: Module specs были введены в Python 3.4, в PEP 451.
Изменено в версии 3.12: Удален fallback, который искал метод
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
.Added in version 3.10.
- sys.path¶
Список строк, задающих путь поиска модулей. Инициализируется из переменной окружения
PYTHONPATH
, плюс по умолчанию в зависимости от установки.По умолчанию, инициализируемый при запуске программы, потенциально опасный путь добавляется к
sys.path
(перед записями, вставленными в результате выполненияPYTHONPATH
):python -m module
Командная строка: добавление текущего рабочего каталога.python script.py
командной строки: добавьте каталог скрипта. Если это символическая ссылка, разрешите символические ссылки.Командные строки
python -c code
иpython
(REPL): добавьте пустую строку, которая означает текущий рабочий каталог.
Чтобы не добавлять этот потенциально опасный путь, используйте параметр командной строки
-P
или переменную окруженияPYTHONSAFEPATH
.Программа может свободно изменять этот список для своих целей. В
sys.path
следует добавлять только строки; все остальные типы данных при импорте игнорируются.
- sys.path_hooks¶
Список вызываемых файлов, которые, принимая аргумент path, пытаются создать finder для этого пути. Если искатель может быть создан, он должен быть возвращен вызываемой переменной, в противном случае вызовите
ImportError
.Первоначально указывается в PEP 302.
- sys.path_importer_cache¶
Словарь, действующий как кэш для объектов finder. Ключами являются пути, которые были переданы в
sys.path_hooks
, а значениями - найденные искатели. Если путь является правильным путем файловой системы, но ни один искатель не найден вsys.path_hooks
, то сохраняетсяNone
.Первоначально указывается в PEP 302.
- sys.platform¶
Строка, содержащая идентификатор платформы. Известные значения:
Система
Значение
platform
AIX
'aix'
Android
'android'
Emscripten
'emscripten'
iOS
'ios'
Linux
'linux'
macOS
'darwin'
Windows
'win32'
Windows/Cygwin
'cygwin'
WASI
'wasi'
Для Unix-систем, не указанных в таблице, значением является имя ОС со строчными буквами, возвращаемое командой
uname -s
, с добавлением первой части версии, возвращаемой командойuname -r
, например'sunos5'
или'freebsd8'
, на момент сборки Python. Если вы не хотите проверять конкретную версию системы, рекомендуется использовать следующую идиому:if sys.platform.startswith('freebsd'): # FreeBSD-specific code here...
Изменено в версии 3.3: В Linux
sys.platform
больше не содержит основной версии. Это всегда'linux'
, а не'linux2'
или'linux3'
.Изменено в версии 3.8: В AIX
sys.platform
больше не содержит основной версии. Это всегда'aix'
, а не'aix5'
или'aix7'
.Изменено в версии 3.13: На Android функция
sys.platform
теперь возвращает'android'
, а не'linux'
.См.также
os.name
имеет более грубую детализацию.os.uname()
предоставляет информацию о версии, зависящую от системы.Модуль
platform
обеспечивает детальную проверку идентичности системы.
- sys.platlibdir¶
Имя каталога библиотеки для конкретной платформы. Используется для построения пути к стандартной библиотеке и путей к установленным модулям расширения.
На большинстве платформ оно равно
"lib"
. На Fedora и SuSE он равен"lib64"
на 64-битных платформах, что дает следующиеsys.path
пути (гдеX.Y
- версия Pythonmajor.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 сторонних пакетов
Added in version 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
).Availability: Unix.
- sys.set_int_max_str_digits(maxdigits)¶
Установка integer string conversion length limitation, используемого данным интерпретатором. См. также
get_int_max_str_digits()
.Added in version 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_return'
Функция C вернулась. arg - это объект функции Си.
'c_exception'
Функция языка Си вызвала исключение. arg - это объект функции Си.
Поднимает auditing event
sys.setprofile
без аргументов.
- sys.setrecursionlimit(limit)¶
Установите максимальную глубину стека интерпретатора Python равной limit. Это ограничение не позволяет бесконечной рекурсии вызвать переполнение стека C и аварийное завершение работы Python.
Максимально возможный предел зависит от платформы. Пользователю может понадобиться установить более высокий предел, если у него есть программа, требующая глубокой рекурсии, и платформа, поддерживающая более высокий предел. Делать это следует осторожно, поскольку слишком высокий предел может привести к сбою.
Если новый предел слишком мал при текущей глубине рекурсии, будет вызвано исключение
RecursionError
.Изменено в версии 3.5.1: Исключение
RecursionError
теперь вызывается, если новый предел слишком мал при текущей глубине рекурсии.
- sys.setswitchinterval(interval)¶
Установите интервал переключения потоков интерпретатора (в секундах). Это значение с плавающей точкой определяет идеальную продолжительность «таймлайнов», выделяемых для параллельно работающих потоков Python. Обратите внимание, что фактическое значение может быть больше, особенно если используются долго выполняющиеся внутренние функции или методы. Кроме того, решение о том, какой поток станет запланированным в конце интервала, принимает операционная система. Интерпретатор не имеет собственного планировщика.
Added in version 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
на этом frame.'return'
Функция (или другой блок кода) вот-вот вернется. Вызывается локальная функция трассировки; arg - значение, которое будет возвращено, или
None
, если событие вызвано возникновением исключения. Возвращаемое значение функции трассировки игнорируется.'exception'
Произошло исключение. Вызывается локальная функция трассировки; arg - кортеж
(exception, value, traceback)
; возвращаемое значение задает новую локальную функцию трассировки.'opcode'
Интерпретатор собирается выполнить новый опкод (подробности об опкоде см. в разделе
dis
). Вызывается локальная функция трассировки; arg - этоNone
; возвращаемое значение задает новую локальную функцию трассировки. По умолчанию события для каждого опкода не выдаются: их нужно явно запросить, установивf_trace_opcodes
вTrue
на frame.
Обратите внимание, что при распространении исключения по цепочке вызывающих команд на каждом уровне генерируется событие
'exception'
.Для более тонкого использования можно установить функцию трассировки, назначив
frame.f_trace = tracefunc
явно, а не полагаясь на то, что она будет установлена косвенно через возвращаемое значение уже установленной функции трассировки. Это также необходимо для активации функции трассировки на текущем кадре, чегоsettrace()
не делает. Обратите внимание, что для того, чтобы это работало, глобальная функция трассировки должна быть установлена с помощьюsettrace()
, чтобы включить механизм трассировки во время выполнения, но это не обязательно должна быть та же самая функция трассировки (например, это может быть функция трассировки с низкой нагрузкой, которая просто возвращаетNone
, чтобы немедленно отключать себя на каждом кадре).Дополнительную информацию о коде и фреймовых объектах см. в разделе Стандартная иерархия типов.
Поднимает auditing event
sys.settrace
без аргументов.Детали реализации CPython: Функция
settrace()
предназначена только для реализации отладчиков, профилировщиков, инструментов покрытия и тому подобного. Ее поведение является частью платформы реализации, а не частью определения языка, и поэтому может быть доступно не во всех реализациях Python.Изменено в версии 3.7: Добавлен тип события
'opcode'
; добавлены атрибутыf_trace_lines
иf_trace_opcodes
для фреймов
- sys.set_asyncgen_hooks([firstiter] [, finalizer])¶
Принимает два необязательных аргумента в виде ключевых слов, которые являются вызываемыми переменными, принимающими в качестве аргумента asynchronous generator iterator. Вызываемая переменная firstiter будет вызвана, когда асинхронный генератор будет итерироваться в первый раз. Вызываемый finalizer будет вызван, когда асинхронный генератор будет собираться в мусор.
Поднимает auditing event
sys.set_asyncgen_hooks_firstiter
без аргументов.Поднимает auditing event
sys.set_asyncgen_hooks_finalizer
без аргументов.Два события аудита поднимаются, потому что базовый API состоит из двух вызовов, каждый из которых должен поднимать свое собственное событие.
Added in version 3.6: Более подробную информацию см. в PEP 525, а пример метода финализатора - в реализации
asyncio.Loop.shutdown_asyncgens
в Lib/asyncio/base_events.py.Примечание
Эта функция была добавлена на временной основе (подробности см. в PEP 411).
- sys.set_coroutine_origin_tracking_depth(depth)¶
Позволяет включить или выключить отслеживание происхождения coroutine. При включении атрибут
cr_origin
у объектов coroutine будет содержать кортеж (имя файла, номер строки, имя функции), описывающий трассировку, где был создан объект coroutine, причем первым будет самый последний вызов. Если атрибутcr_origin
отключен, он будет содержатьNone
.Чтобы включить, передайте значение depth больше нуля; это задает количество кадров, информация о которых будет захвачена. Чтобы отключить, передайте значение depth равным нулю.
Эта настройка зависит от конкретного потока.
Added in version 3.7.
Примечание
Эта функция была добавлена временно (подробности см. в PEP 411). Используйте ее только для отладки.
- sys.activate_stack_trampoline(backend, /)¶
Активируйте батутный бэкенд стекового профилировщика. Единственным поддерживаемым бэкендом является
"perf"
.Availability: Linux.
Added in version 3.12.
- sys.deactivate_stack_trampoline()¶
Деактивируйте текущий бэкэнд батутного профилировщика стека.
Если профилировщик стека не активирован, эта функция не имеет никакого эффекта.
Availability: Linux.
Added in version 3.12.
- sys.is_stack_trampoline_active()¶
Возвращает
True
, если активен батут профилировщика стека.Availability: Linux.
Added in version 3.12.
- sys._enablelegacywindowsfsencoding()¶
Заменяет filesystem encoding and error handler на „mbcs“ и „replace“ соответственно, для согласованности с версиями Python до 3.6.
Это эквивалентно определению переменной окружения
PYTHONLEGACYWINDOWSFSENCODING
перед запуском Python.См. также
sys.getfilesystemencoding()
иsys.getfilesystemencodeerrors()
.Availability: Windows.
Примечание
Менять кодировку файловой системы после запуска Python рискованно, так как старая кодировка fsencoding или пути, закодированные старой кодировкой fsencoding, могут быть где-то кэшированы. Вместо этого используйте
PYTHONLEGACYWINDOWSFSENCODING
.Added in version 3.6: Более подробную информацию см. в разделе PEP 529.
Утратил актуальность с версии 3.13, будет удален в версии 3.16: Вместо этого используйте
PYTHONLEGACYWINDOWSFSENCODING
.
- sys.stdin¶
- sys.stdout¶
- sys.stderr¶
File objects, используемый интерпретатором для стандартного ввода, вывода и ошибок:
stdin
используется для всего интерактивного ввода (включая вызовыinput()
);stdout
используется для вывода операторовprint()
и expression и для подсказокinput()
;Собственные подсказки интерпретатора и его сообщения об ошибках отправляются в
stderr
.
Эти потоки представляют собой обычные text files, подобные тем, которые возвращает функция
open()
. Их параметры выбираются следующим образом:Кодировка и обработка ошибок инициализируются с
PyConfig.stdio_encoding
иPyConfig.stdio_errors
.В Windows для консольного устройства используется UTF-8. Для несимвольных устройств, таких как дисковые файлы и трубы, используется кодировка системной локали (т. е. кодовая страница ANSI). Неконсольные символьные устройства, такие как NUL (т. е. где
isatty()
возвращаетTrue
), используют значение кодовых страниц ввода и вывода консоли при запуске, соответственно для stdin и stdout/stderr. По умолчанию используется системное значение locale encoding, если процесс изначально не подключен к консоли.Особое поведение консоли можно отменить, установив переменную окружения PYTHONLEGACYWINDOWSSTDIO перед запуском Python. В этом случае кодовые страницы консоли используются так же, как и для любого другого символьного устройства.
На всех платформах вы можете изменить кодировку символов, установив переменную окружения
PYTHONIOENCODING
перед запуском Python или используя новую опцию-X
utf8
параметра командной строки и переменной окруженияPYTHONUTF8
. Однако для консоли Windows это применимо только в том случае, если также установлена переменнаяPYTHONLEGACYWINDOWSSTDIO
.В интерактивном режиме поток
stdout
буферизуется строками. В противном случае он буферизуется блоками, как обычные текстовые файлы. Потокstderr
в обоих случаях буферизуется строками. Вы можете сделать оба потока небуферизованными, передав параметр командной строки-u
или установив переменную окруженияPYTHONUNBUFFERED
.
Изменено в версии 3.9: Неинтерактивный
stderr
теперь буферизуется по строкам, а не полностью.Примечание
Для записи или чтения двоичных данных из/в стандартные потоки используйте базовый двоичный объект
buffer
. Например, чтобы записать байт вstdout
, используйтеsys.stdout.buffer.write(b'abc')
.Однако если вы пишете библиотеку (и не контролируете, в каком контексте будет выполняться ее код), имейте в виду, что стандартные потоки могут быть заменены файлоподобными объектами типа
io.StringIO
, которые не поддерживают атрибутbuffer
.
- sys.__stdin__¶
- sys.__stdout__¶
- sys.__stderr__¶
Эти объекты содержат исходные значения
stdin
,stderr
иstdout
в начале работы программы. Они используются во время финализации и могут быть полезны для печати в реальный стандартный поток независимо от того, был ли перенаправлен объектsys.std*
.Его также можно использовать для восстановления фактических файлов в известных рабочих файловых объектах в случае, если они были перезаписаны поврежденным объектом. Однако предпочтительным способом является явное сохранение предыдущего потока перед его заменой и восстановление сохраненного объекта.
Примечание
При некоторых условиях
stdin
,stdout
иstderr
, а также исходные значения__stdin__
,__stdout__
и__stderr__
могут бытьNone
. Обычно это происходит в приложениях с графическим интерфейсом Windows, не подключенных к консоли, и в приложениях Python, запускаемых с pythonw.
- sys.stdlib_module_names¶
Набор строк, содержащих имена модулей стандартной библиотеки.
Он одинаков для всех платформ. Также перечислены модули, недоступные на некоторых платформах, и модули, отключенные при сборке Python. Перечислены все виды модулей: чистый Python, встроенные, замороженные и модули расширения. Тестовые модули исключены.
Для пакетов указывается только основной пакет: подпакеты и подмодули не указываются. Например, указан пакет
email
, но не указаны подпакетemail.mime
и подмодульemail.message
.См. также список
sys.builtin_module_names
.Added in version 3.10.
- sys.thread_info¶
Значение named tuple, содержащее информацию о реализации потока.
- thread_info.name¶
Имя реализации потока:
"nt"
: Потоки Windows"pthread"
: POSIX-потоки"pthread-stubs"
: заглушка POSIX-потоков (на платформах WebAssembly без поддержки потоков)"solaris"
: Потоки Solaris
- thread_info.lock¶
Имя реализации блокировки:
"semaphore"
: блокировка использует семафор"mutex+cond"
: блокировка использует мьютекс и переменную условияNone
, если эта информация неизвестна
- thread_info.version¶
Имя и версия библиотеки потоков. Это строка или
None
, если эта информация неизвестна.
Added in version 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}'
; используйте сообщение об ошибке «Exception ignored in», еслиerr_msg
равноNone
.sys.unraisablehook()
можно переопределить, чтобы управлять обработкой невычитаемых исключений.См.также
excepthook()
, который обрабатывает не пойманные исключения.Предупреждение
Хранение
exc_value
с помощью пользовательского хука может создать цикл ссылок. Его следует явно очистить, чтобы разорвать цикл ссылок, когда исключение больше не нужно.Хранение
object
с помощью пользовательского хука может воскресить его, если он установлен на объект, который завершается. Избегайте сохраненияobject
после завершения работы пользовательского хука, чтобы избежать воскрешения объектов.Поднимает auditing event
sys.unraisablehook
с аргументамиhook
,unraisable
.Added in version 3.8.
- sys.version¶
Строка, содержащая номер версии интерпретатора Python, а также дополнительную информацию о номере сборки и используемом компиляторе. Эта строка отображается при запуске интерактивного интерпретатора. Не извлекайте из нее информацию о версии, лучше используйте
version_info
и функции, предоставляемые модулемplatform
.
- sys.api_version¶
Версия C API для данного интерпретатора. Программисты могут найти это полезным при отладке конфликтов версий между Python и модулями расширения.
- sys.version_info¶
Кортеж, содержащий пять компонентов номера версии: major, minor, micro, releaselevel и serial. Все значения, кроме releaselevel, являются целыми числами; уровень выпуска - это
'alpha'
,'beta'
,'candidate'
или'final'
. Значениеversion_info
, соответствующее версии Python 2.0, равно(2, 0, 0, 'final', 0)
. К компонентам также можно обращаться по имени, поэтомуsys.version_info[0]
эквивалентноsys.version_info.major
и так далее.Изменено в версии 3.1: Добавлены именованные атрибуты компонентов.
- sys.warnoptions¶
Это деталь реализации фреймворка предупреждений; не изменяйте это значение. Дополнительные сведения о системе предупреждений см. в модуле
warnings
.
- sys.winver¶
Номер версии, используемый для формирования ключей реестра на платформах Windows. Хранится как строковый ресурс 1000 в библиотеке Python DLL. Обычно это значение представляет собой мажорную и минорную версии запущенного интерпретатора Python. Оно предоставляется в модуле
sys
в информационных целях; изменение этого значения не влияет на ключи реестра, используемые Python.Availability: 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
. Другие реализации могут экспортировать их другими способами или вообще не экспортировать.Added in version 3.2.
Цитаты
ISO/IEC 9899:1999. «Языки программирования – C». Публичный проект этого стандарта доступен по адресу https://www.open-std.org/jtc1/sc22/wg14/www/docs/n1256.pdf.