sys
— Параметры и функции, зависящие от конкретной системы¶
Этот модуль предоставляет доступ к некоторым переменным, используемым или поддерживаемым интерпретатором, а также к функциям, которые тесно взаимодействуют с интерпретатором. Он всегда доступен.
- sys.abiflags¶
В системах POSIX, где Python был собран со стандартным скриптом
configure
, он содержит флаги ABI, указанные в PEP 3149.Добавлено в версии 3.2.
Изменено в версии 3.8: Флаги по умолчанию превратились в пустую строку (
m
флаг для pymalloc был удален).
- sys.addaudithook(hook)¶
Добавьте вызываемый hook в список активных перехватчиков аудита для текущего (вспомогательного)интерпретатора.
Когда событие аудита вызывается с помощью функции
sys.audit()
, каждый перехват будет вызываться в том порядке, в котором он был добавлен, с указанием имени события и набора аргументов. Сначала вызываются собственные перехватчики, добавленные с помощьюPySys_AddAuditHook()
, за которыми следуют перехватчики, добавленные в текущем (вспомогательном) интерпретаторе. Затем перехватчики могут регистрировать событие, вызывать исключение для прерывания операции или полностью завершать процесс.Обратите внимание, что перехватчики аудита предназначены в первую очередь для сбора информации о внутренних или других ненаблюдаемых действиях, будь то с помощью Python или библиотек, написанных на Python. Они не подходят для реализации «изолированной среды». В частности, вредоносный код может просто отключить или обойти перехватчики, добавленные с помощью этой функции. Как минимум, все уязвимые для безопасности перехватчики должны быть добавлены с использованием C API
PySys_AddAuditHook()
перед инициализацией среды выполнения, а любые модули, допускающие произвольное изменение памяти (например,ctypes
), должны быть полностью удалены или тщательно отслеживаться.Выдает auditing event
sys.addaudithook
без каких-либо аргументов.Смотрите audit events table для всех событий, вызванных CPython, и PEP 578 для обсуждения исходного дизайна.
Добавлено в версии 3.8.
Изменено в версии 3.8.1: Исключения, полученные из
Exception
, но не изRuntimeError
, больше не подавляются.Детали реализации CPython: Когда трассировка включена (см.
settrace()
), перехватчики Python отслеживаются только в том случае, если вызываемый объект имеет элемент__cantrace__
, для которого установлено значение true. В противном случае функции трассировки будут пропускать перехватчик.
- sys.argv¶
Список аргументов командной строки, передаваемых скрипту на Python.
argv[0]
- это имя скрипта (зависит от операционной системы, является ли это полным путем или нет). Если команда была выполнена с использованием параметра командной строки-c
для интерпретатора,argv[0]
устанавливается в строку'-c'
. Если интерпретатору Python не было передано имя скрипта, тоargv[0]
будет пустой строкой.Чтобы просмотреть стандартный ввод или список файлов, указанный в командной строке, обратитесь к модулю
fileinput
.Смотрите также
sys.orig_argv
.Примечание
В Unix аргументы командной строки передаются в байтах из операционной системы. Python расшифровывает их с помощью кодировки файловой системы и обработчика ошибок «surrogateescape». Если вам нужны исходные байты, вы можете получить их с помощью
[os.fsencode(arg) for arg in sys.argv]
.
- sys.audit(event, *args)¶
Инициируйте событие аудита и активируйте все активные перехватчики аудита. event - это строка, идентифицирующая событие, а args может содержать необязательные аргументы с дополнительной информацией о событии. Количество и типы аргументов для данного события считаются общедоступным и стабильным API и не должны изменяться между выпусками.
Например, одно событие аудита называется
os.chdir
. У этого события есть один аргумент с именем path, который будет содержать запрошенный новый рабочий каталог.sys.audit()
вызовет существующие перехватчики аудита, передав имя события и аргументы, и повторно вызовет первое исключение из любого перехватчика. В общем, если возникает исключение, его не следует обрабатывать, а процесс следует завершить как можно быстрее. Это позволяет реализациям перехватчиков решать, как реагировать на конкретные события: они могут просто зарегистрировать событие или прервать операцию, вызвав исключение.Перехватчики добавляются с помощью функций
sys.addaudithook()
илиPySys_AddAuditHook()
.Встроенным эквивалентом этой функции является : c:func:PySys_Audit. По возможности предпочтительнее использовать встроенную функцию.
Смотрите audit events table для всех событий, вызываемых Python.
Добавлено в версии 3.8.
- sys.base_exec_prefix¶
Установите во время запуска Python, перед запуском
site.py
, то же значение, что иexec_prefix
. Если не выполняется в virtual environment, значения останутся прежними; еслиsite.py
обнаружит, что используется виртуальная среда, значенияprefix
иexec_prefix
будут изменены на значения к виртуальной среде, тогда какbase_prefix
иbase_exec_prefix
будут по-прежнему указывать на базовую установку Python (ту, на основе которой была создана виртуальная среда).Добавлено в версии 3.3.
- sys.base_prefix¶
Установите во время запуска Python, перед запуском
site.py
, то же значение, что иprefix
. Если не выполняется в virtual environment, значения останутся прежними; еслиsite.py
обнаружит, что используется виртуальная среда, значенияprefix
иexec_prefix
будут изменены на значения к виртуальной среде, тогда какbase_prefix
иbase_exec_prefix
будут по-прежнему указывать на базовую установку Python (ту, на основе которой была создана виртуальная среда).Добавлено в версии 3.3.
- sys.byteorder¶
Индикатор исходного порядка байтов. Это значение будет
'big'
на платформах с большим порядком байтов (первый байт по старшинству) и'little'
на платформах с меньшим порядком байтов (первый байт по старшинству).
- sys.builtin_module_names¶
Набор строк, содержащих имена всех модулей, которые скомпилированы в этот интерпретатор Python. (Эта информация недоступна никаким другим способом —
modules.keys()
только список импортированных модулей.)Смотрите также список
sys.stdlib_module_names
.
- sys.call_tracing(func, args)¶
Вызовите
func(*args)
, когда включена трассировка. Состояние трассировки сохраняется и впоследствии восстанавливается. Это предназначено для вызова из отладчика из контрольной точки для рекурсивной отладки или профилирования какого-либо другого кода.Трассировка приостанавливается при вызове функции трассировки, заданной параметрами
settrace()
илиsetprofile()
, чтобы избежать бесконечной рекурсии.call_tracing()
включает явную рекурсию функции трассировки.
- sys.copyright¶
Строка, содержащая авторские права, относящиеся к интерпретатору Python.
- sys._clear_type_cache()¶
Очистите внутренний кэш типов. Кэш типов используется для ускорения поиска атрибутов и методов. Используйте функцию только для удаления ненужных ссылок во время отладки утечки ссылок.
Эта функция должна использоваться только для внутренних и специализированных целей.
- sys._current_frames()¶
Возвращает словарь, сопоставляющий идентификатор каждого потока с самым верхним фреймом стека, который в данный момент активен в этом потоке на момент вызова функции. Обратите внимание, что функции в модуле
traceback
могут создавать стек вызовов с учетом такого фрейма.Это наиболее полезно для отладки взаимоблокировки: эта функция не требует взаимодействия заблокированных потоков, и стеки вызовов таких потоков замораживаются до тех пор, пока они остаются заблокированными. Кадр, возвращаемый для потока, не находящегося в тупиковой ситуации, может не иметь никакого отношения к текущей активности этого потока к моменту проверки кадра вызывающим кодом.
Эта функция должна использоваться только для внутренних и специализированных целей.
Выдает auditing event
sys._current_frames
без каких-либо аргументов.
- sys._current_exceptions()¶
Возвращает словарь, сопоставляющий идентификатор каждого потока с самым верхним исключением, активным в данный момент в этом потоке на момент вызова функции. Если поток в данный момент не обрабатывает исключение, оно не включается в результирующий словарь.
Это наиболее полезно для статистического профилирования.
Эта функция должна использоваться только для внутренних и специализированных целей.
Выдает auditing event
sys._current_exceptions
без каких-либо аргументов.
- sys.breakpointhook()¶
Эта функция перехвата вызывается встроенным
breakpoint()
. По умолчанию она переводит вас в отладчикpdb
, но ее можно настроить на любую другую функцию, чтобы вы могли выбрать, какой отладчик использовать.Сигнатура этой функции зависит от того, что она вызывает. Например, привязка по умолчанию (например,
pdb.set_trace()
) не ожидает аргументов, но вы можете привязать ее к функции, которая ожидает дополнительных аргументов (позиционных и/или ключевых слов). Встроенная функцияbreakpoint()
передает свои*args
и**kws
напрямую. Все, что возвращаетbreakpointhooks()
, возвращается изbreakpoint()
.Реализация по умолчанию сначала обращается к переменной окружения
PYTHONBREAKPOINT
. Если для нее задано значение"0"
, то эта функция немедленно возвращается; т.е. она не работает. Если переменная окружения не задана или имеет значение пустой строки, вызываетсяpdb.set_trace()
. В противном случае этой переменной следует присвоить имя выполняемой функции, используя терминологию точечного импорта в Python, напримерpackage.subpackage.module.function
. В этом случае будет импортированpackage.subpackage.module
, и результирующий модуль должен иметь вызываемый элемент с именемfunction()
. Это выполняется с передачей*args
и**kws
, и все, что возвращаетfunction()
,sys.breakpointhook()
возвращается к встроенной функцииbreakpoint()
.Обратите внимание, что если что-то пойдет не так при импорте вызываемого объекта с именем
PYTHONBREAKPOINT
, будет сообщено оRuntimeWarning
и точка останова будет проигнорирована.Также обратите внимание, что если
sys.breakpointhook()
переопределяется программно, тоPYTHONBREAKPOINT
не используется.Добавлено в версии 3.7.
- sys._debugmallocstats()¶
Выведите в stderr низкоуровневую информацию о состоянии распределителя памяти CPython.
Если Python built in debug mode (
configure --with-pydebug option
),, он также выполняет некоторые дорогостоящие проверки внутренней согласованности.Добавлено в версии 3.3.
Детали реализации CPython: Эта функция специфична для CPython. Точный формат вывода здесь не определен и может измениться.
- sys.dllhandle¶
Целое число, указывающее дескриптор библиотеки DLL на Python.
Availability: Окна.
- 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 скомпилирован с поддержкой Emscripten pthreads.
True
если Python скомпилирован с поддержкой общей памяти.
Availability: Emscripten.
Добавлено в версии 3.11.
- sys.pycache_prefix¶
Если это значение задано (а не
None
), Python будет записывать файлы с байт-кодом-кэшем.pyc
в параллельное дерево каталогов с корнем в этом каталоге (и считывать их из него), а не из__pycache__
каталогов в исходном коде дерево. Любые каталоги__pycache__
в дереве исходного кода будут проигнорированы, а новые файлы.pyc
будут записаны с префиксом pycache. Таким образом, если вы используетеcompileall
в качестве шага предварительной сборки, вы должны убедиться, что запускаете его с тем же префиксом pycache (если таковой имеется), который вы будете использовать во время выполнения.Относительный путь интерпретируется относительно текущего рабочего каталога.
Это значение изначально устанавливается на основе значения параметра командной строки
-X
pycache_prefix=PATH
или переменной окруженияPYTHONPYCACHEPREFIX
(приоритет отдается командной строке). Если ни один из них не задан, то этоNone
.Добавлено в версии 3.8.
- sys.excepthook(type, value, traceback)¶
Эта функция выводит заданную обратную трассировку и исключение на
sys.stderr
.Когда возникает и не обрабатывается исключение, отличное от
SystemExit
, интерпретатор вызываетsys.excepthook
с тремя аргументами: классом исключения, экземпляром исключения и объектом обратной трассировки. В интерактивном сеансе это происходит непосредственно перед возвращением управления в командную строку; в программе на Python это происходит непосредственно перед завершением работы программы. Обработку таких исключений верхнего уровня можно настроить, назначив другую функцию с тремя аргументами дляsys.excepthook
.Создает 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
можно было восстановить в случае, если они будут заменены сломанными или альтернативными объектами.Добавлено в версии 3.7: __breakpointhook__
Добавлено в версии 3.8: __unraisablehook__
- sys.exception()¶
Эта функция, вызываемая во время выполнения обработчика исключений (например, предложения
except
илиexcept*
), возвращает экземпляр исключения, который был перехвачен этим обработчиком. Когда обработчики исключений вложены друг в друга, доступно только исключение, обрабатываемое самым внутренним обработчиком.Если обработчик исключений не выполняется, эта функция возвращает
None
.Добавлено в версии 3.11.
- sys.exc_info()¶
Эта функция возвращает представление обработанного исключения в старом стиле. Если в данный момент обрабатывается исключение
e
, то будет возвращено значениеexception()
e
),exc_info()
возвращает кортеж(type(e), e, e.__traceback__)
. То есть кортеж, содержащий тип исключения (подклассBaseException
), само исключение и traceback object, который обычно инкапсулирует стек вызовов в точке, где в последний раз возникало исключение.Если нигде в стеке не обрабатывается исключение, эта функция возвращает кортеж, содержащий три значения
None
.Изменено в версии 3.11: Поля
type
иtraceback
теперь являются производными отvalue
(экземпляра exception), поэтому, когда исключение изменяется во время его обработки, изменения отражаются в результатах последующих вызовов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()
в конечном счете «only» вызывает исключение, оно завершает процесс только при вызове из основного потока, и исключение не перехватывается. Действия по очистке, указанные в предложениях finally инструкцииtry
, выполняются, и можно перехватить попытку выхода на внешнем уровне.Изменено в версии 3.6: Если при очистке возникает ошибка после того, как интерпретатор Python поймал
SystemExit
(например, ошибка очистки буферизованных данных в стандартных потоках), статус завершения изменяется на 120.
- sys.flags¶
Флаги named tuple * отображают статус флагов командной строки. Атрибуты доступны только для чтения.
- 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
.Добавлено в версии 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¶
A named tuple содержит информацию о типе float. Он содержит информацию низкого уровня о точности и внутреннем представлении. Значения соответствуют различным константам с плавающей запятой, определенным в стандартном заголовочном файле
float.h
для языка программирования «C»; подробности см. в разделе 5.2.4.2.2 стандарта ISO/IEC 1999 года [C99] «Характеристики плавающих типов».Атрибуты системы float_info
named tuple¶атрибут
макрос 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
Точность с плавающей точкой: количество базовых цифр``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
Целое число, представляющее режим округления для арифметики с плавающей запятой. Это отражает значение макроса system
FLT_ROUNDS
во время запуска интерпретатора:-1
: не поддается определению0
: приближается к нулю1
: до ближайшего2
: к положительной бесконечности3
: к отрицательной бесконечности
Все остальные значения для
FLT_ROUNDS
характеризуют поведение округления, определяемое реализацией.Атрибут
sys.float_info.dig
нуждается в дополнительном объяснении. Еслиs
- это любая строка, представляющая десятичное число, содержащее не болееsys.float_info.dig
значащих цифр, то преобразованиеs
в число с плавающей точкой и обратно восстановит строку, представляющую то же десятичное значение:>>> import sys >>> sys.float_info.dig 15 >>> s = '3.14159265358979' # decimal string with 15 significant digits >>> format(float(s), '.15g') # convert to float and back -> same value '3.14159265358979'
Но для строк, содержащих более
sys.float_info.dig
значащих цифр, это не всегда верно:>>> s = '9876543211234567' # 16 significant digits is too many! >>> format(float(s), '.16g') # conversion changes value '9876543211234568'
- sys.float_repr_style¶
Строка, указывающая, как ведет себя функция
repr()
для чисел с плавающей запятой. Если строка имеет значение'short'
, то для конечного числа с плавающей точкойx
,repr(x)
необходимо создать короткую строку со свойствомfloat(repr(x)) == x
. Это обычное поведение в Python 3.1 и более поздних версиях. В противном случаеfloat_repr_style
имеет значение'legacy'
иrepr(x)
ведет себя так же, как и в версиях Python до 3.1.Добавлено в версии 3.1.
- sys.getallocatedblocks()¶
Возвращает количество блоков памяти, выделенных интерпретатором в данный момент, независимо от их размера. Эта функция в основном полезна для отслеживания и отладки утечек памяти. Из-за внутренних кэшей интерпретатора результат может варьироваться от вызова к вызову; возможно, вам придется вызывать
_clear_type_cache()
иgc.collect()
, чтобы получить более предсказуемые результаты.Если сборка или реализация на Python не могут разумно вычислить эту информацию, вместо
getallocatedblocks()
разрешается возвращать 0.Добавлено в версии 3.4.
- sys.getandroidapilevel()¶
Возвращает версию API времени сборки Android в виде целого числа.
Availability: Android.
Добавлено в версии 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, либо байты и внутренне преобразовываться в предпочтительное представление системы.
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 для преобразования имен файлов в Юникоде в байты. Кодировка файловой системы возвращается из
getfilesystemencoding()
.os.fsencode()
иos.fsdecode()
следует использовать для обеспечения правильной кодировки и режима ошибок.Параметры filesystem encoding and error handler настраиваются при запуске Python с помощью функции
PyConfig_Read()
: смотритеfilesystem_encoding
иfilesystem_errors
, входящие в составPyConfig
.Добавлено в версии 3.6.
- sys.get_int_max_str_digits()¶
Возвращает текущее значение для integer string conversion length limitation. Смотрите также
set_int_max_str_digits()
.Добавлено в версии 3.11.
- sys.getrefcount(object)¶
Возвращает количество ссылок на объект. Возвращаемое значение обычно на единицу больше, чем вы могли бы ожидать, поскольку оно включает (временную) ссылку в качестве аргумента
getrefcount()
.Обратите внимание, что возвращаемое значение может не отражать фактического количества ссылок на объект. Следовательно, не полагайтесь на точность возвращаемого значения, за исключением значений 0 или 1.
- sys.getrecursionlimit()¶
Возвращает текущее значение предела рекурсии, максимальной глубины стека интерпретатора Python. Это ограничение предотвращает переполнение стека C при бесконечной рекурсии и сбой Python. Его можно задать с помощью
setrecursionlimit()
.
- sys.getsizeof(object[, default])¶
Возвращает размер объекта в байтах. Объект может быть любого типа. Все встроенные объекты будут возвращать корректные результаты, но это не обязательно должно выполняться для сторонних расширений, поскольку это зависит от конкретной реализации.
Учитывается только потребление памяти, непосредственно связанное с объектом, а не потребление памяти объектами, на которые он ссылается.
Если задано значение, то будет возвращено значение по умолчанию, если объект не предоставляет средства для получения размера. В противном случае будет поднято значение
TypeError
.getsizeof()
вызывает метод объекта__sizeof__
и добавляет дополнительные накладные расходы на сборщик мусора, если объект управляется сборщиком мусора.Смотрите recursive sizeof recipe для примера рекурсивного использования
getsizeof()
для определения размера контейнеров и всего их содержимого.
- sys.getswitchinterval()¶
Возвращает значение интерпретатора «интервал переключения потоков»; смотрите
setswitchinterval()
.Добавлено в версии 3.2.
- sys._getframe([depth])¶
Возвращает объект frame из стека вызовов. Если задано необязательное целое число depth, возвращает объект frame, который многими вызовами находится ниже вершины стека. Если он находится глубже, чем стек вызовов, вызывается значение
ValueError
. Значение по умолчанию для depth равно нулю, что возвращает кадр в верхней части стека вызовов.Создает auditing event
sys._getframe
с аргументомframe
.Детали реализации CPython: Эту функцию следует использовать только для внутренних и специализированных целей. Не гарантируется, что она существует во всех реализациях Python.
- sys.getprofile()¶
Получите функцию профилировщика, заданную параметром
setprofile()
.
- sys.gettrace()¶
Получите функцию трассировки, заданную параметром
settrace()
.Детали реализации CPython: Функция
gettrace()
предназначена только для реализации отладчиков, профилировщиков, инструментов покрытия и т.п. Ее поведение является частью платформы реализации, а не частью определения языка, и, следовательно, может быть доступно не во всех реализациях Python.
- sys.getwindowsversion()¶
Возвращает именованный кортеж, описывающий текущую версию Windows. Названными элементами являются major, minor, build, platform, service_pack, service_pack_minor, service_pack_major, suite_mask, product_type и platform_version. service_pack содержит строку, platform_version - кортеж из 3 элементов, а все остальные значения являются целыми числами. К компонентам также можно обращаться по имени, поэтому
sys.getwindowsversion()[0]
эквивалентноsys.getwindowsversion().major
. Для обеспечения совместимости с предыдущими версиями с помощью индексации можно извлечь только первые 5 элементов.платформа будет
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: Окна.
Изменено в версии 3.2: Изменен на именованный кортеж и добавлены service_pack_minor, service_pack_major, suite_mask и product_type.
Изменено в версии 3.6: Добавлена версия платформы_version
- sys.get_asyncgen_hooks()¶
Возвращает объект asyncgen_hooks, который похож на
namedtuple
вида(firstiter, finalizer)
, где firstiter и finalizer должны быть либоNone
, либо функциями, которые принимают asynchronous generator iterator в качестве аргумента и используются для планирования завершения работы асинхронного генератора с помощью цикла обработки событий.Добавлено в версии 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 named tuple, содержащий параметры реализации числового хэширования. Более подробную информацию о хэшировании числовых типов смотрите в разделе Хэширование числовых типов.
- hash_info.width¶
Ширина в битах, используемая для хэш-значений
- hash_info.modulus¶
Простой модуль P, используемый для числовой хэш-схемы
- hash_info.inf¶
Хэш-значение, возвращаемое для положительной бесконечности
- hash_info.nan¶
(Этот атрибут больше не используется)
- hash_info.imag¶
Множитель, используемый для обозначения мнимой части комплексного числа
- hash_info.algorithm¶
Название алгоритма для хэширования str, байтов и memoryview
- hash_info.hash_bits¶
Внутренний размер выходных данных хэш-алгоритма
- hash_info.seed_bits¶
Размер начального ключа хэш-алгоритма
Добавлено в версии 3.2.
Изменено в версии 3.4: Добавлены алгоритм, хэш-биты и начальные биты
- 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 - это namedtuple в том же формате, что и
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.Добавлено в версии 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
.
Добавлено в версии 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
.Добавлено в версии 3.4.
- sys.intern(string)¶
Введите string в таблицу «интернированных» строк и верните интернированную строку, которая является самой string или ее копией. Интернирование строк полезно для повышения производительности поиска по словарю - если ключи в словаре интернированы, а ключ поиска интернирован, сравнение ключей (после хэширования) может выполняться с помощью сравнения указателей вместо сравнения строк. Обычно имена, используемые в программах на Python, автоматически интернируются, а словари, используемые для хранения атрибутов модуля, класса или экземпляра, содержат интернированные ключи.
Интернированные строки не бессмертны; вы должны сохранять ссылку на возвращаемое значение
intern()
, чтобы извлечь из этого пользу.
- sys.is_finalizing()¶
Возвращает
True
, если интерпретатор Python shutting down,False
в противном случае.Добавлено в версии 3.5.
- sys.last_type¶
- sys.last_value¶
- sys.last_traceback¶
Эти три переменные определены не всегда; они устанавливаются, когда исключение не обрабатывается и интерпретатор выводит сообщение об ошибке и обратную трассировку стека. Их назначение состоит в том, чтобы позволить интерактивному пользователю импортировать модуль отладчика и приступить к посмертной отладке без необходимости повторного выполнения команды, вызвавшей ошибку. (Обычно используется
import pdb; pdb.pm()
для входа в посмертный отладчик; дополнительную информацию смотрите в модулеpdb
.)Значение переменных такое же, как и у возвращаемых значений из
exc_info()
, приведенных выше.
- sys.maxsize¶
Целое число, задающее максимальное значение, которое может принимать переменная типа
Py_ssize_t
. Обычно это2**31 - 1
на 32-разрядной платформе и2**63 - 1
на 64-разрядной платформе.
- sys.maxunicode¶
Целое число, задающее значение наибольшей кодовой точки в Юникоде, т.е.
1114111
(0x10FFFF
в шестнадцатеричном формате).Изменено в версии 3.3: Раньше PEP 393,
sys.maxunicode
было либо0xFFFF
, либо0x10FFFF
, в зависимости от параметра конфигурации, который указывал, будут ли символы Unicode храниться как 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. В более ранних версиях Python использовался метод с именем
find_module()
. Это по-прежнему вызывается в качестве запасного варианта, если записьmeta_path
не содержит методаfind_spec()
.
- sys.modules¶
Это словарь, который сопоставляет названия модулей с уже загруженными модулями. Этим можно манипулировать для принудительной перезагрузки модулей и других трюков. Однако замена словаря не обязательно будет работать должным образом, а удаление важных элементов из словаря может привести к сбою Python. Если вы хотите выполнить итерацию по этому глобальному словарю, всегда используйте
sys.modules.copy()
илиtuple(sys.modules)
, чтобы избежать исключений, поскольку его размер может изменяться во время итерации как побочный эффект кода или активности в других потоках.
- sys.orig_argv¶
Список исходных аргументов командной строки, переданных в исполняемый файл Python.
Элементы
sys.orig_argv
являются аргументами интерпретатора Python, в то время как элементыsys.argv
являются аргументами пользовательской программы. Аргументы, используемые самим интерпретатором, будут присутствовать вsys.orig_argv
и отсутствовать вsys.argv
.Добавлено в версии 3.10.
- sys.path¶
Список строк, указывающих путь поиска модулей. Инициализируется из переменной среды
PYTHONPATH
, а также зависит от установки по умолчанию.По умолчанию, при инициализации при запуске программы, потенциально небезопасный путь добавляется к
sys.path
(перед записями, вставленными в результатеPYTHONPATH
).:python -m module
командная строка: добавьте в начало текущий рабочий каталог.python script.py
командная строка: добавьте в начало каталог скрипта. Если это символьная ссылка, разрешите символьные ссылки.python -c code
иpython
(REPL) командные строки: добавьте пустую строку, которая означает текущий рабочий каталог.
Чтобы не указывать этот потенциально небезопасный путь в начале, используйте параметр командной строки
-P
или переменную средыPYTHONSAFEPATH
.Программа может свободно изменять этот список для своих собственных целей. В
sys.path
следует добавлять только строки; все остальные типы данных игнорируются при импорте.
- sys.path_hooks¶
Список вызываемых объектов, которые принимают аргумент path, чтобы попытаться создать finder для пути. Если finder может быть создан, он должен быть возвращен вызываемым объектом, в противном случае вызывается
ImportError
.Первоначально указанный в PEP 302.
- sys.path_importer_cache¶
Словарь, действующий как кэш для объектов finder. Ключи - это пути, которые были переданы в
sys.path_hooks
, а значения - это найденные средства поиска. Если путь является допустимым путем к файловой системе, но finder не найден наsys.path_hooks
, то сохраняетсяNone
.Первоначально указанный в PEP 302.
Изменено в версии 3.3:
None
сохраняется вместоimp.NullImporter
, если программа поиска не найдена.
- sys.platform¶
Эта строка содержит идентификатор платформы, который можно использовать, например, для добавления компонентов, зависящих от платформы, к
sys.path
.Для Unix-систем, за исключением Linux и AIX, это название ОС в нижнем регистре, возвращаемое с помощью
uname -s
, с добавлением первой части версии, возвращаемой с помощьюuname -r
, например,'sunos5'
или'freebsd8'
, в то время, когда был создан Python. Поэтому, если вы не хотите протестировать конкретную версию системы, рекомендуется использовать следующую идиому:if sys.platform.startswith('freebsd'): # FreeBSD-specific code here... elif sys.platform.startswith('linux'): # Linux-specific code here... elif sys.platform.startswith('aix'): # AIX-specific code here...
Для других систем эти значения следующие:
Система
platform
значениеAIX
'aix'
Эмскриптен
'emscripten'
Линукс
'linux'
БЫЛ
'wasi'
Окна
'win32'
Windows/Cygwin
'cygwin'
macOS (макОС)
'darwin'
Изменено в версии 3.3: В Linux
sys.platform
больше не содержит основной версии. Это всегда'linux'
, вместо'linux2'
или'linux3'
. Поскольку более старые версии Python содержат номер версии, рекомендуется всегда использовать идиомуstartswith
, представленную выше.Изменено в версии 3.8: В AIX
sys.platform
больше не содержит основной версии. Это всегда'aix'
, вместо'aix5'
или'aix7'
. Поскольку более старые версии Python содержат номер версии, рекомендуется всегда использовать идиомуstartswith
, представленную выше.См.также
os.name
имеет более высокую степень детализации.os.uname()
содержит информацию о версии, зависящей от системы.Модуль
platform
обеспечивает детальную проверку подлинности системы.
- sys.platlibdir¶
Имя каталога библиотеки, зависящей от платформы. Используется для построения пути к стандартной библиотеке и путей к установленным модулям расширения.
На большинстве платформ оно равно
"lib"
. В Fedora и SuSE оно равно"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 для сторонних пакетов
Добавлено в версии 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()
.Добавлено в версии 3.11.
- sys.setprofile(profilefunc)¶
Установите системную функцию profile, которая позволяет вам реализовать профилировщик исходного кода Python на Python. Смотрите главу Профилировщики Python для получения дополнительной информации о профилировщике Python. Системная функция profile вызывается аналогично системной функции trace (см.
settrace()
), но она вызывается с разными событиями, например, она вызывается не для каждой выполняемой строки кода (только при вызове и возврате, но о событии возврата сообщается даже тогда, когда было установлено исключение). Функция зависит от конкретного потока, но профилировщик не может узнать о переключении контекста между потоками, поэтому нет смысла использовать ее при наличии нескольких потоков. Кроме того, его возвращаемое значение не используется, поэтому оно может просто вернутьNone
. Ошибка в функции profile приведет к тому, что она сама не будет установлена.Примечание
Для
setprofile()
используется тот же механизм трассировки, что и дляsettrace()
. Чтобы отслеживать вызовы с помощьюsetprofile()
внутри функции трассировки (например, в точке останова отладчика), смотритеcall_tracing()
.Функции профиля должны иметь три аргумента: frame, event и arg. frame - это текущий кадр стека. событие - это строка:
'call'
,'return'
,'c_call'
,'c_return'
, или'c_exception'
. аргумент зависит от типа события.Эти события имеют следующее значение:
'call'
Вызывается функция (или вводится какой-либо другой блок кода). Вызывается функция профиля; аргумент равен
None
.'return'
Функция (или другой блок кода) вот-вот вернется. Вызывается функция profile; arg - это значение, которое будет возвращено, или
None
, если событие вызвано возникновением исключения.'c_call'
Вот-вот будет вызвана функция языка Си. Это может быть функция расширения или встроенная функция. arg - объект функции языка Си.
'c_return'
Была возвращена функция языка Си. arg - это объект функции языка Си.
'c_exception'
Функция языка Си вызвала исключение. arg - это объект функции языка Си.
Выдает auditing event
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 - это текущий кадр стека. событие - это строка:
'call'
,'line'
,'return'
,'exception'
или'opcode'
. аргумент зависит от типа события.След функция вызывается (в случае значение
'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 будет вызван при первом запуске асинхронного генератора. Финализатор будет вызван, когда асинхронный генератор будет готов к сборке мусора.
Выдает auditing event
sys.set_asyncgen_hooks_firstiter
без каких-либо аргументов.Выдает auditing event
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.Чтобы включить, укажите значение глубины, большее нуля; это задаст количество кадров, информация о которых будет записана. Чтобы отключить, установите значение глубины равным нулю.
Этот параметр зависит от конкретного потока.
Добавлено в версии 3.7.
Примечание
Эта функция была добавлена на временной основе (подробности см. в разделе PEP 411). Используйте ее только в целях отладки.
- sys._enablelegacywindowsfsencoding()¶
Изменяет filesystem encoding and error handler на «mbc» и «replace» соответственно для соответствия версиям Python до версии 3.6.
Это эквивалентно определению переменной окружения
PYTHONLEGACYWINDOWSFSENCODING
перед запуском Python.Смотрите также
sys.getfilesystemencoding()
иsys.getfilesystemencodeerrors()
.Availability: Окна.
Добавлено в версии 3.6: Смотрите PEP 529 для получения более подробной информации.
- sys.stdin¶
- sys.stdout¶
- sys.stderr¶
File objects используется интерпретатором для стандартного ввода, вывода и устранения ошибок:
stdin
используется для любого интерактивного ввода (включая вызовыinput()
).;stdout
используется для вывода инструкцийprint()
и expression, а также для подсказокinput()
;Собственные подсказки интерпретатора и его сообщения об ошибках отображаются в виде
stderr
.
Эти потоки являются обычными text files, как и те, которые возвращает функция
open()
. Их параметры выбираются следующим образом:Кодирование и обработка ошибок инициализируются с помощью:c:member:PyConfig.stdio_encoding и
PyConfig.stdio_errors
.В Windows для обозначения консольного устройства используется кодировка UTF-8. Несимвольные устройства, такие как файлы на диске и каналы передачи данных, используют системную языковую кодировку (т.е. кодовую страницу ANSI). Неконсольные символьные устройства, такие как NULL (т.е. где
isatty()
возвращаетTrue
), используют значения кодовых страниц ввода и вывода консоли при запуске, соответственно для stdin и stdout/stderr. По умолчанию используется значение system 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
.Добавлено в версии 3.10.
- sys.thread_info¶
A 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
, если эта информация неизвестна.
Добавлено в версии 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
после завершения пользовательского перехватчика, чтобы избежать повторного создания объектов.Создает auditing event
sys.unraisablehook
с аргументамиhook
,unraisable
.Добавлено в версии 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; не изменяйте это значение. Обратитесь к модулю
warnings
для получения дополнительной информации о платформе warnings.
- sys.winver¶
Номер версии, используемый для формирования разделов реестра на платформах Windows. Он хранится в виде строки resource 1000 в библиотеке DLL Python. Обычно это значение соответствует основной и вспомогательной версиям запущенного интерпретатора Python. Оно предоставляется в модуле
sys
в информационных целях; изменение этого значения не влияет на разделы реестра, используемые Python.Availability: Окна.
- 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.
Цитаты
ISO/IEC 9899:1999. «Языки программирования - C». Общедоступный проект этого стандарта доступен по адресу https://www.open-std.org/jtc1/sc22/wg14/www/docs/n1256.pdf.