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, и сохраняет значение в builtins._. Если repr(value) не может быть закодировано в sys.stdout.encoding с обработчиком ошибок sys.stdout.errors (который, вероятно, 'strict' ), закодировать его в sys.stdout.encoding с обработчиком ошибок 'backslashreplace'.

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

Псевдокод:

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

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

sys.dont_write_bytecode

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

sys.excepthook(type, value, traceback)

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

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

sys.__displayhook__

sys.__excepthook__

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

sys.exc_info()

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

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

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([arg])

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

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

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

sys.flags

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

атрибут	флаг
debug	-d
inspect	-i
interactive	-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.

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 в мантиссе float
max	DBL_MAX	максимальное представимое конечное float
max_exp	DBL_MAX_EXP	максимальное целое e такое, что radix**(e-1) — представимое конечное float
max_10_exp	DBL_MAX_10_EXP	максимальное целое e такое, что 10**e попадает в диапазон представимых конечных float
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 в float и обратно восстановит строку, представляющую то же десятичное значение:

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

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

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

sys.float_repr_style

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

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

sys.getallocatedblocks()

Возвращает количество блоков памяти, в настоящее время выделенных интерпретатором, независимо от их размера. Эта функция в основном полезна для отслеживания и отладки утечек памяти. Из-за внутренних кэшей интерпретатора результат может варьироваться от вызова к вызову; вам может потребоваться вызвать _clear_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-файлов в системные имена файлов. Результат зависит от операционной системы:

• В macOS X кодирование — 'utf-8'.
• В Unix кодирование соответствует пользовательским настройкам в соответствии с результатом nl_langinfo(CODESET).
• В Windows NT+, имена файлов — это Unicode-строки напрямую, поэтому преобразование не выполняется. getfilesystemencoding() всё равно возвращает 'mbcs', так как приложения должны использовать это кодирование, когда явно хотят преобразовать Unicode-строки в байтовые строки, эквивалентные при использовании в качестве имён файлов.
• В Windows 9x кодирование — 'mbcs'.

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

sys.getrefcount(object)

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

sys.getrecursionlimit()

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

sys.getsizeof(object[, default])

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

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

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

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

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

sys.getswitchinterval()

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

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

sys._getframe([depth])

Возвращает объект фрейма из стека вызовов. Если передан необязательный целочисленный параметр depth, возвращает объект фрейма, находящийся на 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. service_pack содержит строку, в то время как все остальные значения — целые числа. К элементам можно также обращаться по имени, поэтому sys.getwindowsversion()[0] эквивалентно sys.getwindowsversion().major. Для совместимости с предыдущими версиями доступны только первые 5 элементов по индексу.

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

Константа	Платформа
0 (VER_PLATFORM_WIN32s)	Win32s в Windows 3.1
1 (VER_PLATFORM_WIN32_WINDOWS)	Windows 95/98/ME
2 (VER_PLATFORM_WIN32_NT)	Windows NT/2000/XP/x64
3 (VER_PLATFORM_WIN32_CE)	Windows CE

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

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

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

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

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

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, используйте:

if sys.hexversion >= 0x010502F0:
    # use some advanced feature
    ...
else:
    # use an alternative implementation or warn the user
    ...

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

Дополнительные сведения о hexversion можно найти в Версионирование API и ABI.

sys.implementation

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

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

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

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

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

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)

Вносит строку в таблицу «интернированных» строк и возвращает интернированную строку — это сама строка или её копия. Интернирование строк полезно для повышения производительности при поиске в словарях — если ключи в словаре интернированы, и ключ поиска интернирован, сравнения ключей (после хеширования) могут выполняться по указателям вместо сравнения строк. Обычно имена, используемые в программах 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

Целое число, указывающее значение наибольшего кода символа Юникода, т. е. 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: Вместо imp.NullImporter теперь сохраняется None, когда находчик не найден.

sys.platform

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

Для систем Unix, за исключением Linux, это строка с именем ОС в нижнем регистре, возвращённая 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...

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

Система	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(interval)

Установите «интервал проверки» интерпретатора. Это целое значение определяет, как часто интерпретатор проверяет периодические события, такие как переключение потоков и обработчики сигналов. По умолчанию значение равно 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. См. главу Профайлеры Python для получения дополнительной информации о профайлере Python. Системная функция профилирования вызывается аналогично системной функции трассировки (см. settrace()), но она не вызывается для каждой выполняемой строки кода (только при вызове и возврате, но событие возврата сообщается даже при установке исключения). Функция зависит от потока, но у профайлера нет возможности узнать о переключениях контекста между потоками, поэтому использовать её в присутствии нескольких потоков не имеет смысла. Кроме того, её возвращаемое значение не используется, поэтому она может просто вернуть None.

sys.setrecursionlimit(limit)

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

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

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

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

sys.setswitchinterval(interval)

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

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

sys.settrace(tracefunc)

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

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

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

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

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

'call'

Вызывается функция (или какая-либо другая область кода). Вызывается глобальная функция трассировки; arg — None; возвращаемое значение определяет локальную функцию трассировки.

'line'

Интерпретатор собирается выполнить новую строку кода или повторно выполнить условие цикла. Вызывается локальная функция трассировки; arg — None; возвращаемое значение определяет новую локальную функцию трассировки. См. Objects/lnotab_notes.txt для подробного объяснения работы.

'return'

Функция (или другая область кода) собирается вернуть. Вызывается локальная функция трассировки; arg — возвращаемое значение или None , если событие вызвано поднятием исключения. Возвращаемое значение функции трассировки игнорируется.

'exception'

Произошло исключение. Вызывается локальная функция трассировки; arg — кортеж (exception, value, traceback); возвращаемое значение определяет новую локальную функцию трассировки.

'c_call'

Собирается вызвать функция C. Это может быть функция расширения или встроенная функция. arg — объект функции C.

'c_return'

Функция C вернула значение. arg — объект функции C.

'c_exception'

Функция C подняла исключение. arg — объект функции C.

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

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

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

sys.settscdump(on_flag)

Активирует дамп измерений VM с использованием счётчика временных меток Pentium, если on_flag истинно. Деактивирует эти дампы, если on_flag ложно. Функция доступна только в том случае, если Python был скомпилирован с --with-tsc. Чтобы понять вывод этого дампа, прочитайте Python/ceval.c в исходных кодах Python.

Примечание реализации CPython: Эта функция тесно связана с деталями реализации CPython и, следовательно, вряд ли будет реализована где-либо ещё.

sys.set_coroutine_wrapper(wrapper)

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

Аргумент wrapper должен быть:

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

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

Вызываемая функция wrapper не может напрямую или косвенно определять новые генераторы:

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

async def foo():
    pass

# The following line will fail with a RuntimeError, because
# ``wrapper`` creates a ``wrap(coro)`` coroutine:
foo()

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

Добавлена в версии 3.5: См. PEP 492 для получения дополнительных сведений.

Примечание

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

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

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

Атрибут	Описание
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. Пример:

$ ./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.

Ссылки