29.1. `sys` – Системно-зависимые параметры и функции

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

sys.abiflags¶: В системах POSIX, где Python был собран со стандартным сценарием configure, он содержит флаги ABI, как указано в PEP 3149.

Новое в версии 3.2.

sys.argv¶

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

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

sys.base_exec_prefix¶: Устанавливается во время запуска Python, до выполнения site.py, в такое же значение, как exec_prefix. Если работа происходит не в виртуальном окружении, значения остаются теми же; если site.py обнаруживает, что используется виртуальное окружение, значения prefix и exec_prefix изменяются так, чтобы указывать на виртуальное окружение, тогда как base_prefix и base_exec_prefix продолжают указывать на базовую установку Python (ту, из которой было создано виртуальное окружение).

Новое в версии 3.3.

sys.base_prefix¶: Устанавливается во время запуска Python, до выполнения site.py, в такое же значение, как prefix. Если работа происходит не в виртуальном окружении, значения остаются теми же; если site.py обнаруживает, что используется виртуальное окружение, значения prefix и exec_prefix изменяются так, чтобы указывать на виртуальное окружение, тогда как base_prefix и base_exec_prefix продолжают указывать на базовую установку Python (ту, из которой было создано виртуальное окружение).

Новое в версии 3.3.

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

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

sys.call_tracing(func, args)¶: Вызывает func(*args), пока трассировка включена. Состояние трассировки сохраняется и восстанавливается после завершения. Эта функция предназначена для вызова из отладчика в контрольной точке для рекурсивной отладки другого кода.

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

sys._clear_type_cache()¶

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

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

sys._current_frames()¶

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

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

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

sys._debugmallocstats()¶

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

Если Python сконфигурирован с --with-pydebug, он также выполняет некоторые дорогостоящие проверки внутренней согласованности.

Новое в версии 3.3.

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

sys.dllhandle¶: Целое число, задающее дескриптор DLL Python. Доступность: Windows.

sys.displayhook(значение)¶

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

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

Псевдокод:

python

def displayhook(value):
    if value is None:
        return
    # Установите '_' в None, чтобы избежать рекурсии
    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.excepthook(тип, значение, трассировка)¶

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

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

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

sys.exc_info()¶

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

Если в данный момент в стеке не обрабатывается ни одно исключение, возвращается кортеж из трёх значений None. В противном случае возвращаются значения (type, value, traceback). Их смысл: type содержит тип обрабатываемого исключения (подкласс BaseException); value содержит экземпляр исключения (экземпляр типа исключения); traceback содержит объект traceback (см. Справочное руководство), который инкапсулирует стек вызовов в точке, где изначально возникло исключение.

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.

Примечание

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

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

sys.exit([аргумент])¶

Выход из Python. Это реализовано путём возбуждения SystemExit исключения, поэтому действия по очистке, указанные в предложениях finally операторов try выполняются, и можно перехватить попытку выхода на внешнем уровне.

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

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

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

sys.flags¶

Структурированная последовательность flags предоставляет состояние флагов командной строки. Атрибуты доступны только для чтения.

атрибут	флаг
`debug`	`-d`
`inspect`	`-i`
`interactive`	`-i`
`isolated`	`-I`
`optimize`	`-O` или `-OO`
`dont_write_bytecode`	`-B`
`no_user_site`	`-s`
`no_site`	`-S`
`ignore_environment`	`-E`
`verbose`	`-v`
`bytes_warning`	`-b`
`quiet`	`-q`
`hash_randomization`	`-R`

Изменено в версии 3.2: Добавлен атрибут quiet для нового флага -q.

Новое в версии 3.2.3: Атрибут hash_randomization.

Изменено в версии 3.3: Удалён устаревший атрибут division_warning.

Изменено в версии 3.4: Добавлен атрибут isolated для флага -I isolated.

sys.float_info¶

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

атрибут	макрос float.h	объяснение
`epsilon`	DBL_EPSILON	разница между 1 и наименьшим значением больше 1, которое представимо в виде float
`dig`	DBL_DIG	максимальное количество десятичных цифр, которое может быть точно представлено в float; см. ниже
`mant_dig`	DBL_MANT_DIG	точность float: количество цифр по основанию `radix` в мантиссе числа с плавающей точкой
`max`	DBL_MAX	максимальное представимое конечное значение float
`max_exp`	DBL_MAX_EXP	максимальное целое e, такое что `radix**(e-1)` является представимым конечным значением float
`max_10_exp`	DBL_MAX_10_EXP	максимальное целое e, такое что `10**e` находится в диапазоне представимых конечных чисел с плавающей запятой
`min`	DBL_MIN	минимальное положительное нормализованное значение float
`min_exp`	DBL_MIN_EXP	минимальное целое e, такое что `radix**(e-1)` является нормализованным значением float
`min_10_exp`	DBL_MIN_10_EXP	минимальное целое e, такое что `10**e` является нормализованным значением float
`radix`	FLT_RADIX	основание представления экспоненты
`rounds`	FLT_ROUNDS	Целочисленная константа, представляющая режим округления, используемый для арифметических операций. Она отражает значение макроса FLT_ROUNDS системы на момент запуска интерпретатора. Смотрите раздел 5.2.4.2.2 стандарта C99 для объяснения возможных значений и их смысла.

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

python

>>> import sys
>>> sys.float_info.dig
15
>>> s = '3.14159265358979'    # десятичная строка с 15 значащими цифрами
>>> format(float(s), '.15g')  # преобразовать во float и обратно -> то же значение
'3.14159265358979'

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

python

>>> s = '9876543211234567'    # 16 значащих цифр — слишком много!
>>> format(float(s), '.16g')  # преобразование изменяет значение
'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.getcheckinterval()¶: Возвращает «интервал проверки» интерпретатора; см. setcheckinterval().

Устарело с версии 3.2: Используйте getswitchinterval() вместо.

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

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

sys.getfilesystemencoding()¶

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

Эта кодировка всегда совместима с ASCII.

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

В Mac OS X используется кодировка 'utf-8'.
На Unix кодировкой является локальная кодировка.
На Windows кодировкой может быть 'utf-8' или 'mbcs', в зависимости от конфигурации пользователя.

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

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

sys.getfilesystemencodeerrors()¶

Возвращает название режима обработки ошибок, используемого для преобразования между именами файлов в Unicode и байтовыми именами файлов. Название кодировки возвращается из getfilesystemencoding().

Новое в версии 3.6.

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

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

sys.getsizeof(объект[, по умолчанию])¶

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

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

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

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

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

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

Новое в версии 3.2.

sys._getframe([глубина])¶: Возвращает объект фрейма из стека вызовов. Если задано необязательное целое число depth, возвращается объект фрейма, находящийся на указанное число вызовов ниже вершины стека. Если это глубже, чем стек вызовов, возбуждается ValueError. По умолчанию 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 – 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 возвращает точные номера основной версии, дополнительной версии и сборки текущей операционной системы, а не версию, эмулируемую для процесса. Она предназначена для использования в журналировании, а не для определения возможностей.

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

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

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

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

Новое в версии 3.6: См. PEP 525 для подробностей.

Примечание

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

sys.get_coroutine_wrapper()¶: Возвращает None или обёртку, установленную с помощью set_coroutine_wrapper().

Новое в версии 3.5: Подробнее см. PEP 492.

Примечание

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

sys.hash_info¶

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

атрибут	объяснение
`width`	ширина в битах, используемая для хеш-значений
`modulus`	простой модуль P, используемый в схеме числового хеширования
`inf`	хеш-значение, возвращаемое для положительной бесконечности
`nan`	хэш-значение, возвращаемое для nan
`imag`	множитель для мнимой части комплексного числа
`algorithm`	название алгоритма хеширования для str, bytes и memoryview
`hash_bits`	внутренний размер выходных данных алгоритма хеширования
`seed_bits`	размер начального ключа алгоритма хеширования

Новое в версии 3.2.

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

sys.hexversion¶

Номер версии, закодированный в виде одного целого числа. Гарантированно увеличивается с каждой версией, включая поддержку непроизводственных релизов. Например, чтобы проверить, что интерпретатор Python имеет версию не ниже 1.5.2, используйте:

python

if sys.hexversion >= 0x010502F0:
    # использовать какую-то продвинутую возможность
    ...
else:
    # использовать альтернативную реализацию или предупредить пользователя
    ...

Это называется hexversion, поскольку это действительно имеет смысл только при рассмотрении как результат передачи встроенной функции hex(). Структурированная последовательность sys.version_info может использоваться для более удобочитаемого кодирования той же информации.

Более подробную информацию о hexversion можно найти в API and ABI Versioning.

sys.implementation¶

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

name – это идентификатор реализации, например 'cpython'. Фактическая строка определяется реализацией Python, но гарантированно будет в нижнем регистре.

version – это именованный кортеж в том же формате, что и sys.version_info. Он представляет версию реализации Python. Это отличается от конкретной версии языка Python, которой соответствует текущий интерпретатор, и которую представляет sys.version_info. Например, для PyPy 1.8 sys.implementation.version может быть sys.version_info(1, 8, 0, 'final', 0), тогда как sys.version_info будет sys.version_info(2, 7, 2, 'final', 0). Для CPython они совпадают, поскольку это эталонная реализация.

hexversion – это версия реализации в шестнадцатеричном формате, например sys.hexversion.

cache_tag – это тег, используемый механизмом импорта в именах файлов кэшированных модулей. По соглашению, это составное имя из названия и версии реализации, например 'cpython-33'. Однако реализация Python может использовать другое значение, если это уместно. Если cache_tag установлено в None, это означает, что кэширование модулей должно быть отключено.

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

Новое в версии 3.3.

sys.int_info¶

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

Атрибут	Пояснение
`bits_per_digit`	число бит в каждом разряде. Целые числа Python внутренне хранятся в системе счисления с основанием `2**int_info.bits_per_digit`
`sizeof_digit`	размер в байтах типа C, используемого для представления разряда

Новое в версии 3.1.

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

Новое в версии 3.4.

sys.intern(строка)¶

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

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

sys.is_finalizing()¶: Возвращает True, если интерпретатор Python завершает работу, иначе 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¶: Целое число, задающее значение наибольшей кодовой точки Unicode, т.е. 1114111 (0x10FFFF в шестнадцатеричной записи).

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

sys.meta_path¶

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

Смотрите также

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

Изменено в версии 3.4: Спецификации модулей были введены в Python 3.4, согласно PEP 451. В более ранних версиях Python искали метод с именем find_module(). Этот метод по-прежнему вызывается как запасной вариант, если запись meta_path не имеет метода find_spec().

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

sys.path¶

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

При запуске программы первый элемент этого списка, path[0], содержит каталог со скриптом, который вызвал интерпретатор Python. Если каталог скрипта недоступен (например, при интерактивном запуске или чтении скрипта со стандартного ввода), path[0] является пустой строкой; в этом случае Python сначала ищет модули в текущем каталоге. Обратите внимание, что каталог скрипта вставляется до записей, добавленных через PYTHONPATH

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

Смотрите также

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

sys.path_hooks¶

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

Изначально описано в PEP 302.

sys.path_importer_cache¶

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

Изначально описано в PEP 302.

Изменено в версии 3.3: None сохраняется вместо imp.NullImporter, если не найден finder.

sys.platform¶

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

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

python

if sys.platform.startswith('freebsd'):
    # Код для FreeBSD...
elif sys.platform.startswith('linux'):
    # Код для Linux...

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

Система	`platform` значение
Linux	`'linux'`
Windows	`'win32'`
Windows/Cygwin	`'cygwin'`
Mac OS X	`'darwin'`

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

Смотрите также

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

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

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

Примечание

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

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

sys.setcheckinterval(интервал)¶: Устанавливает «интервал проверки» интерпретатора. Это целочисленное значение определяет, как часто интерпретатор проверяет периодические события, такие как переключения потоков и обработчики сигналов. По умолчанию равно 100, то есть проверка выполняется каждые 100 виртуальных инструкций Python. Установка большего значения может повысить производительность программ, использующих потоки. Установка значения <= 0 означает проверку после каждой виртуальной инструкции, что максимизирует отзывчивость, но также и накладные расходы.

Устарело с версии 3.2: Эта функция больше не действует, так как внутренняя логика переключения потоков и асинхронных задач была переписана. Используйте вместо этого setswitchinterval().

sys.setdlopenflags(n)¶

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

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

sys.setprofile(profilefunc)¶

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

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

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

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

sys.setrecursionlimit(предел)¶

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

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

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

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

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

Новое в версии 3.2.

sys.settrace(tracefunc)¶

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

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

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

Локальная трассировочная функция должна возвращать ссылку на себя (или на другую функцию для дальнейшей трассировки в данной области видимости) либо None, чтобы отключить трассировку в этой области

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

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

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

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

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

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

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

Примечание

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

sys.set_coroutine_wrapper(wrapper)¶

Позволяет перехватывать создание объектов корутина (только тех, которые созданы функцией async def; генераторы, декорированные с помощью types.coroutine() или asyncio.coroutine(), перехватываться не будут).

Аргумент wrapper должен быть одним из следующих:

вызываемый объект, принимающий один аргумент (объект корутины);
None, чтобы сбросить обёртку.

Если вызвать дважды, новая обёртка заменяет предыдущую. Функция привязана к потоку.

Вызываемый объект wrapper не может создавать новые корутины прямо или косвенно:

python

def wrapper(coro):
    async def wrap(coro):
        return await coro
    return wrap(coro)
sys.set_coroutine_wrapper(wrapper)

async def foo():
    pass

# Следующая строка завершится ошибкой RuntimeError, потому что
# ``wrapper`` создает корутину ``wrap(coro)``:
foo()

См. также get_coroutine_wrapper().

Новое в версии 3.5: Подробнее см. PEP 492.

Примечание

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

sys._enablelegacywindowsfsencoding()¶

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

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

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

Новое в версии 3.6: См. PEP 529 для получения дополнительных сведений.

sys.stdin¶

sys.stdout¶

sys.stderr¶

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

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

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

Кодировка символов зависит от платформы. В Windows, если поток является интерактивным (то есть его метод isatty() возвращает True), используется кодовая страница консоли, в противном случае – кодовая страница ANSI. На других платформах используется локальная кодировка (см. locale.getpreferredencoding()).

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

Примечание

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

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

sys.__stdin__¶

sys.__stdout__¶

sys.__stderr__¶

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

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

Примечание

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

sys.thread_info¶

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

Атрибут	Пояснение
`name`	Имя реализации потоков: `'nt'`: потоки Windows `'pthread'`: потоки POSIX `'solaris'`: потоки Solaris
`lock`	Имя реализации блокировки: `'semaphore'`: блокировка использует семафор `'mutex+cond'`: блокировка использует мьютекс и условную переменную `None` если эта информация неизвестна
`version`	Имя и версия библиотеки потоков. Это строка или `None`, если эти сведения неизвестны.

Атрибут

Пояснение

name

Имя реализации потоков:

'nt': потоки Windows

'pthread': потоки POSIX

'solaris': потоки Solaris

lock

Имя реализации блокировки:

'semaphore': блокировка использует семафор

'mutex+cond': блокировка использует мьютекс и условную переменную

None если эта информация неизвестна

version

Имя и версия библиотеки потоков. Это строка или None, если эти сведения неизвестны.

Новое в версии 3.3.

sys.tracebacklimit¶: Когда этой переменной присвоено целое значение, она определяет максимальное количество уровней информации трассировки, выводимой при необработанном исключении. Значение по умолчанию: 1000. Если установлено 0 или меньше, вся информация трассировки подавляется и выводятся только тип и значение исключения.

sys.version¶: Строка, содержащая номер версии интерпретатора Python, а также дополнительную информацию о номере сборки и используемом компиляторе. Эта строка выводится при запуске интерактивного интерпретатора. Не извлекайте из неё информацию о версии, вместо этого используйте version_info и функции, предоставляемые модулем platform.

sys.api_version¶: Версия C API для данного интерпретатора. Программистам это может быть полезно при отладке конфликтов версий между Python и модулями расширения.

sys.version_info¶: Кортеж, содержащий пять компонентов номера версии: major, minor, micro, releaselevel и serial. Все значения, кроме releaselevel, являются целыми числами; уровень выпуска – 'alpha', 'beta', 'candidate' или 'final'. Значение version_info, соответствующее версии Python 2.0, равно (2, 0, 0, 'final', 0). К компонентам также можно обращаться по имени: так sys.version_info[0] эквивалентно sys.version_info.major и так далее.

Изменено в версии 3.1: Добавлены именованные атрибуты компонентов.

sys.warnoptions¶: Это деталь реализации механизма предупреждений; не изменяйте это значение. Обратитесь к модулю warnings за дополнительной информацией о механизме предупреждений.

sys.winver¶: Номер версии, используемый для формирования ключей реестра на платформах Windows. Он хранится как строковый ресурс 1000 в DLL Python. Обычно значение представляет собой первые три символа version. Он предоставляется в модуле sys для информационных целей; изменение этого значения не влияет на ключи реестра, используемые Python. Доступность: Windows.

sys._xoptions¶

Словарь различных флагов, специфичных для реализации, передаваемых через опцию командной строки -X. Имена опций либо сопоставляются со своими значениями, если они заданы явно, либо с True. Пример:

shell-session

$ ./python -Xa=b -Xc
Python 3.2a3+ (py3k, Oct 16 2010, 20:14:50)
[GCC 4.4.3] on linux2
Type "help", "copyright", "credits" or "license" for more information.
>>> import sys
>>> sys._xoptions
{'a': 'b', 'c': True}

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

Новое в версии 3.2.

Цитаты

C99: ISO/IEC 9899:1999. «Языки программирования – C». Общедоступный проект этого стандарта доступен по адресу http://www.open-std.org/jtc1/sc22/wg14/www/docs/n1256.pdf.

29.1. sys – Системно-зависимые параметры и функции​

29.1. `sys` – Системно-зависимые параметры и функции