Библиотека sys

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

Что такое модуль sys

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

Модуль sys даёт следующую информацию:

• Какая версия Питона запущена.
• Путь к интерпретатору Python, исполняющему текущий скрипт.
• Параметры командной строки, используемые при запуске на выполнение скрипта.
• Флаги, установленные интерпретатором.
• Представление значений с плавающей точкой.
• Многое другое.

Модуль sys часто используют с модулем os. С помощью sys получают нужную информацию об операционной системе, чтобы избежать непредвиденных ошибок, а с помощью os взаимодействуют с ней (работа с файлами, запуск программ на выполнение, обработка путей и так далее).

Как подключить библиотеку

Все библиотеки (модули) в Python 3 подключаются с помощью команды «import имя библиотеки». Существуют разные варианты подключения, используемые при определённых обстоятельствах:

• import sys — Такой способ используется, если в вашем проекте могут использоваться такие же имена переменных или функций, как и в библиотеке. При таком подключении вызов функций или переменных из модуля выполняется так: «sys.имя_функции».
• from sys import * — Способ используется тогда, когда программист уверен, что пересечений имён нет. При вызове методов или функций не нужно ставить префикс «sys.», что уменьшает количество кода. Звёздочку можно заменить на имена конкретных функций, перечисленные через запятую. Это позволяет импортировать не весь модуль, а лишь некоторые его части.
• import sys as s — При такой записи название «sys» заменяется на «s». Способ используют, чтобы заменить длинное название модуля на более короткое и удобное, это позволяет и уменьшить количество кода, и избежать пересечения имён. Правда sys и так достаточно коротко.

Функции и константы модуля sys

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

Информация о системных параметрах

sys.dllhandle

Целое число, которое определяет дескриптор динамически подключаемой библиотеки Python. Работает только в операционной системе Windows.

Дескриптор — это указатель на область памяти. По этому адресу располагается DLL Python. Вот пример использования. Определим указатель и по нему узнаем путь до DLL. Для этого понадобится ещё одна библиотека pywin32, которую установим с помощью  pip install pywin32. Подключается она с помощью import win32api:

import sys
import win32api
print(sys.dllhandle)
print(win32api.GetModuleFileName(sys.dllhandle))

1407778816
C:\Users\all-python\AppData\Local\Programs\Python\Python36-32\python36.dll

sys.exec_prefix

Строка, которая показывает, в какой каталог установлен Python. (обычно это «/usr/local»).

import sys
print(sys.exec_prefix)
print(sys.base_exec_prefix)

d:\python\example\env
C:\Users\all-python\AppData\Local\Programs\Python\Python38-32

sys.executable

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

Если по какой-то причине определить путь к интерпретатору нельзя, sys.executable будет пустой строкой или None.

Вот пример её вывода:

C:\Users\all-python\AppData\Local\Programs\Python\Python38-32\python.exe

sys.getfilesystemencoding()

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

Разные операционные системы используют различные кодировки:

• При режиме UTF-8 кодировка на любой платформе всегда «utf-8».
• В Mac OS X используется кодировка «utf-8».
• В Windows используется «utf-8» или «mbcs», это зависит от настроек системы.

Примечания:

• В Python 3.2 результатом getfilesystemencoding() больше не может быть None.
• С версии Python 3.6 больше не гарантируется, что Windows вернёт кодировку «mbcs».
• В Python 3.7 в режиме UTF-8 кодировка всегда «utf-8».

sys.getwindowsversion()

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

Чтобы получить доступ к определённому компоненту кортежа, достаточно обратиться к нему по индексу «sys.getwindowsversion()[1]» или имени «sys.getwindowsversion().platform». Для сохранения совместимости с предыдущими версиями, только первые пять элементов можно получить по индексу.

Перечислим все 10 вариантов ниаменований: major, minor, build, platform, service_pack, service_pack_minor, service_pack_major, suite_mask, product_type и platform_version.

Некоторые элементы могут выводить несколько значений, например, элемент «platform_version» возвращает основную версию, дополнительную версию и номер сборки ОС.

import sys
print(sys.getwindowsversion())
print(sys.getwindowsversion().platform_version)

sys.getwindowsversion(major=10, minor=0, build=17763, platform=2, 
                      service_pack='')
(10, 0, 17763)

sys.platform

Строка, дающая информацию об используемой операционной системе (идентификатор платформы). Например, «win32».

sys.winver

Содержит номер версии Python, который используется в реестре Windows. Например, «3.8-32».

Используется только в информационных целях, то есть даже если изменить значения «sys.winver», значения в реестре Windows не изменятся.

Информация о параметрах интерпретатора

sys.argv

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

argv[0] — это имя скрипта. Если команда выполнена с опцией «-c», то в argv[0] помещает строка «-c». Если имя скрипта не было передано интерпретатору, то argv[0] будет пустой строкой.

sys.byteorder

Показывает порядок следования байтов. Различные платформы могут использовать как «big-endian» — прямая нумерация байтов, так и «little-endian» — обратная нумерация байтов. Например, при записи целого двухбайтового числа в памяти комрьютера, в случае прямой нумерации вначале идет старший байт, а затем младший. При обратной — наоборот, вначале записывается младший.

sys.builtin_module_names

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

sys.breakpointhook()

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

В обычной реализации функция сначала обращается к локальной переменной среды PYTHONBREAKPOINT. Если у неё значение «0», функция сразу же возвращается, то есть не будет выполнено никаких действий. Если переменная среды не определена, или является пустой строкой, вызывается pdb.set_trace().

sys.copyright

Строка, дающая информацию об авторских правах на интерпретатор Python.

sys._current_frames()

Возвращает словарь, дающий информацию о активных потоках.

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

Пример вывода:

{2788: <frame at 0x03A76418, file 'D:\\python\\test\\loader.py', 
        line 59, code run>,
7796: <frame at 0x03B02190, file 'D:\\python\\test\\output.py', 
        line 27, code out>}

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

sys.flags

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

Вот пример вывода:

sys.flags(debug=0, inspect=0, interactive=0, optimize=0, 
dont_write_bytecode=0, no_user_site=0, no_site=0, ignore_environment=0, 
verbose=0, bytes_warning=0, quiet=0, hash_randomization=1, isolated=0, 
dev_mode=False, utf8_mode=0)

sys.float_info

Именованный кортеж, который содержит информацию о типе «float». Он содержит данные точности и внутреннем представлении чисел этого типа. Значения соответствуют константам с плавающей точкой, определенным в файле float.h для языка программирования C.

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

Пример вывода:

sys.float_info(max=1.7976931348623157e+308, max_exp=1024, max_10_exp=308, 
min=2.2250738585072014e-308, min_exp=-1021, min_10_exp=-307, dig=15, 
mant_dig=53, epsilon=2.220446049250313e-16, radix=2, rounds=1)

sys.float_repr_style

Строка, которая показывает поведение функции repr() для чисел типа «float». Если строка имеет значение «short», то для конечного числа x функция repr(x) пытается создать такую строку, что float(repr(x)) равен x с минимальным количеством десятичных цифр. Если float_repr_style имеет значение «legacy», а repr(x) ведёт себя так же, как до версии Python 3.1 — округлял до 17 десятичных цифр.

sys.getdefaultencoding()

Функция, которая возвращает имя кодировки, используемой по умолчанию, например, «utf-8».

sys.getallocatedblocks()

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

Каждый новый вывод функции может отличаться от предыдущего, это происходит из-за внутреннего кэша интерпретатора. Чтобы получить правильные результаты, нужно использовать функции _clear_type_cache() и gc.collect().

Если по какой-то причине интерпретатор не может вычислить информацию о количестве блоков памяти, функция вернёт ноль.

sys.getandroidapilevel()

Доступно только на платформе Android. Возвращает версию сборки API Android.

sys.getrecursionlimit()

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

Пример использования рекурсии — один из возможных вариантов нахождения чисел Фибоначчи.

sys.getswitchinterval()

Возвращает число, определяющее, частоту переключения потоков. Это вещественное число. Значение в секундах. Например: «0.005».

sys.hexversion

Номер версии интерпретатора Python, закодированный одним числом. Это число увеличивается с каждой версией, включая все виды релизов.

Это число называется «hexversion», потому что оно принимает понятный вид, только если его передать в функцию hex().

Пример версии: 50856176.

sys.hash_info

Кортеж, содержащий информацию о параметрах хеша.

Атрибут	Объяснение
width	Сколько битов используется для значений хеша
modulus	Простой модуль, используемое для числовой схемы хеша
inf	Значение хеша, возвращаемое для +∞
nan	Значение хеша, возвращаемое для типа nan
imag	Множитель, который используется для представления мнимой части комплексного числа
algorithm	Наименование алгоритма, используемого для хеширования строк, байтов и представления памяти
hash_bits	Внутренний размер вывода алгоритма хеширования
seed_bits	Размер начального ключа алгоритма хеширования

Пример вывода:

sys.hash_info(width=32, modulus=2147483647, inf=314159, nan=0, 
imag=1000003, algorithm='siphash24', hash_bits=64, seed_bits=128, 
cutoff=0)

sys.implementation

Объект, дающий информацию о запущенном в данный момент интерпретаторе Python.

Объект должен содержать атрибуты: имя, версия, версия в шестнадцатеричном представлении, дескриптор кэша.

Пример:

namespace(cache_tag='cpython-38', hexversion=50856176, name='cpython', 
version=sys.version_info(major=3, minor=8, micro=0, releaselevel='final', 
serial=0))

sys.int_info

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

Например:

sys.int_info(bits_per_digit=15, sizeof_digit=2)

sys.maxsize

Число, показывающее, какое максимально значение может принять переменная типа Py_ssize_t. Это также максимальный размер списков, словарей, строк и других контейнеров. Пример значения: 2147483647.

sys.maxunicode

Число, показывающее, какое максимальное количество битов может выделяться на представление символа Unicode. Например: 1114111.

sys.modules

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

sys.path

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

Первый элемент списка (path[0]) — это директория, в которой находится скрипт, запускающий интерпретатор Python.

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

sys.dont_write_bytecode

Если sys.dont_write_bytecode принимает значение True, то Python не будет записывать файлы «.pyc» при импорте модулей. Значение устанавливается в зависимости от параметра «-B» командной строки и значения переменной среды PYTHONDONTWRITEBYTECODE, его также можно установить самостоятельно, чтобы управлять созданием файлов байт-кода.

sys.setrecursionlimit(предел)

Функция, позволяющая установить предел глубины рекурсии для интерпретатора Python. Предел предотвращает возможные ошибки, возникающие при переполнении стека в C.

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

sys.setswitchinterval(интервал)

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

sys.version

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

Например:

3.8.0 (tags/v3.8.0:fa919fd, Oct 14 2019, 19:21:23) [MSC v.1916 32 bit 
(Intel)]

sys.api_version

Информацию об используемой интерпретатором версии C API. Применяется при отладке конфликтов, возникающих при взаимодействии Python и дополнительных модулей.

Пример значения: 1013.

Функции для работы с объектами

sys.getrefcount(object)

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

В качестве примера в переменной example сохраним объект класса Example. Потом создадим ссылку на объект. При вызове getrefcount() создастся  ещё одна ссылка на example. В результате получаем 3.

import sys
class Example:
    pass
example = Example()
temp = example
print(sys.getrefcount(example))

3

sys.getsizeof(object[, default])

Показывает, сколько байтов выделяется для хранения объекта любого типа.

Функция вызывает метод __sizeof__() у объекта. К этому значению добавляется размер данных выделенных для сборщика мусора, если объект им управляется.

import sys
class Example:
    pass
example = Example()
print(example.__sizeof__())
print(sys.getsizeof(example))

16
24

sys._getframe([depth])

Возвращает объект кадра из стека вызова. Если передан необязательный аргумент «depth», то функция возвращает объект кадра, который ниже на заданное количество вершины стека.

Если значение «depth» больше, чем стек вызовов, вызывается исключение ValueError.

Значение по умолчанию для «depth» равно нулю, это значит, что функция вернёт самый верхний кадр стека.

Для того, чтобы было проще разобраться приведём пример. Мы вызовим функцию example(), которая в свою очередь вызовит функцию test(). Все эти вызовы будут записаны поочерёдно в стек. С помощью _getframe() получим объекты кадров из стека:

import sys
def test():
    print(sys._getframe(0))
    print(sys._getframe(1))
    print(sys._getframe(2))
    print(sys._getframe(3))
def example():
    test()
example()

Вот что будет возаращено в результате выполнения:

Функции, выполняющие действия и преобразования

sys.call_tracing(функция, аргументы)

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

sys._clear_type_cache()

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

sys.exit([arg])

Выход из Python. Вызывает исключение SystemExit, которое можно перехватить. По желанию можно передать функции аргумент, который может быть целым числом (обычно от 0 до 127).

Если передан ноль, завершение работы происходит в обычном режиме, любое другое значение приводит к «неуспешному завершению». Если аргумент не входит в нужный числовой диапазон, функция может вернуть неопределённые результаты. Некоторые программисты придерживают определённых правил при указании значения аргумента, например, «2» может обозначать выход из-за синтаксической ошибки, а «3» — выход из-за переполнения стека.

sys.exit — это быстрый способ выйти из программы при возникновении ошибки.

sys.stdin

Стандартный поток ввода, который используется для интерактивного ввода, включая вызовы input(). Файло-подобный объект, считывать данные можно с помощью его метода read.

sys.stdout

Стандартный поток вывода, который используется для вывода функции print(), выражений и запросов input(). Файло-подобный объект, записывать данные в него можно с помощью его метода write.

sys._enablelegacywindowsfsencoding()

Изменяет кодировку файловой системы на «mbsc» и режим ошибок на «replace».

Действует также, как и определение переменной среды PYTHONLEGACYWINDOWSFSENCODING перед запуском Python.

Функции для работы с ошибками и исключениями

sys.exc_info()

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

Если исключения не обрабатываются, кортеж состоит из трёх элементов со значением None. В противном случае он имеет значения: тип, значения, трассировка.

Например:

(<class 'ZeroDivisionError'>, ZeroDivisionError('division by zero'), 
<traceback object at 0x02D93EE8>)

sys.last_type, sys.last_value, sys.last_traceback

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

sys.getfilesystemencodeerrors()

Показывает, какой режим обработки неподдерживаемых кодировкой символов при преобразовании имён файлов из Unicode в байтовое представление. В Windows по умолчанию значение «surrogatepass» или «replace». На других операционных системах «surrogateescape».

sys.stderr

Стандартный поток вывода ошибок, в который отправляются все ошибки интерпретатора. Файло-подобный объект, считывать данные можно с помощью его метода read.

sys.settrace(функция трассировки)

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

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

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

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

• «call». Вызывается функция. Также вызывается глобальная функция трассировки; arg имеет значение None; возвращаемое значение ссылается на локальную функцию трассировки.
• «line». Интерпретатор готовится выполнить новую строку кода или повторить условие цикла. Вызывается локальная функция трассировки; arg принимает значение None; возвращаемое значение ссылается на новую локальную функцию трассировки.
• «return». Функция готовится вернуть значение. Вызывается локальная функция трассировки; arg принимает возвращаемое значение или None, если вызывается исключение. Возвращаемое значение функции трассировки игнорируется.
• «exсeption». Было вызвано исключение; вызывается локальная функция трассировки; arg — это кортеж из трех элементов (тип, значение, трассировка); возвращаемое значение ссылается на новую локальную функцию трассировки.
• «opcode». Интерпретатор готовиться выполнить новый код операции. Вызывается локальная функция трассировки; arg принимает значение None; возвращаемое значение ссылается на новую локальную функцию трассировки.

Вот пример: создадим функцию для тарссировки. Она будет просто выводить в консоль аргументы, которые получает. Установим её для трассировки. После этого напишем немного кода: вызовим функцию, которая расчитываем сумму двух чисел. Результат сложения выведем в консоль.

import sys
def trace_func(frame, event, arg):
    print('FRAME: ' + str(frame))
    print('EVENT: ' + str(event))
    print('ARG: ' + str(arg))
sys.settrace(trace_func)
def sum(a, b):
    return a + b
a = sum(4, 7)
print(a)

Результат выполнения программы будет следующий:

Здесь мы видим, что как только вызвалась функция sum, сразуже сработала наша функция трассировки с событием «call».