msilib — Чтение и запись файлов Microsoft Installer

Модуль msilib поддерживает создание файлов Microsoft Installer (.msi) . Поскольку эти файлы часто содержат вложенный файл «cabinet» (.cab), он также предоставляет API для создания файлов CAB. Поддержка чтения файлов .cab в настоящее время не реализована; поддержка чтения базы данных .msi возможна.

Этот пакет призван предоставить полный доступ ко всем таблицам в файле .msi, поэтому это API довольно низкого уровня. Два основных применения этого пакета — команда distutils bdist_msi, и создание собственного пакета установщика Python (хотя в настоящее время используется другая версия msilib).

Содержимое пакета можно условно разделить на четыре части: процедуры CAB низкого уровня, процедуры MSI низкого уровня, процедуры MSI более высокого уровня и стандартные структуры таблиц.

msilib.FCICreate(cabname, files)

Создаёт новый файл CAB с именем cabname. files должен быть списком кортежей, каждый из которых содержит имя файла на диске и имя файла внутри файла CAB.

Файлы добавляются в файл CAB в порядке их появления в списке. Все файлы добавляются в один файл CAB с использованием алгоритма сжатия MSZIP.

Обратные вызовы в Python для различных этапов создания MSI в настоящее время не доступны.

msilib.UuidCreate()

Возвращает строковое представление нового уникального идентификатора. Это оболочка функций Windows API UuidCreate() и UuidToString().

msilib.OpenDatabase(path, persist)

Возвращает новый объект базы данных, вызывая MsiOpenDatabase. path — имя файла MSI; persist может быть одним из констант MSIDBOPEN_CREATEDIRECT, MSIDBOPEN_CREATE, MSIDBOPEN_DIRECT, MSIDBOPEN_READONLY, или MSIDBOPEN_TRANSACT, и может включать флаг MSIDBOPEN_PATCHFILE. См. документацию Microsoft для понимания значения этих флагов; в зависимости от флагов, открывается существующая база данных или создаётся новая.

msilib.CreateRecord(count)

Возвращает новый объект записи, вызывая MSICreateRecord(). count — количество полей записи.

msilib.init_database(name, schema, ProductName, ProductCode, ProductVersion, Manufacturer)

Создаёт и возвращает новую базу данных name, инициализирует её с помощью schema и задаёт свойства ProductName, ProductCode, ProductVersion и Manufacturer.

schema должен быть объектом модуля, содержащим атрибуты tables и _Validation_records; обычно используется msilib.schema.

База данных будет содержать только схему и записи проверки, когда эта функция вернётся.

msilib.add_data(database, table, records)

Добавляет все records в таблицу с именем table в database.

Аргумент table должен быть одной из предопределённых таблиц в схеме MSI, например, 'Feature', 'File', 'Component', 'Dialog', 'Control', и т. д.

records должен быть списком кортежей, каждый из которых содержит все поля записи в соответствии со схемой таблицы. Для необязательных полей можно передать None.

Значения полей могут быть целыми или длинными числами, строками или экземплярами класса Binary.

class msilib.Binary(filename)

Представляет записи в таблице Binary; вставка такого объекта с помощью add_data() считывает файл с именем filename в таблицу.

msilib.add_tables(database, module)

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

Это обычно используется для установки последовательностей таблиц.

msilib.add_stream(database, name, path)

Добавляет файл path в таблицу _Stream базы данных database с именем потока name.

msilib.gen_uuid()

Возвращает новый UUID в формате, обычно требуемом MSI (т. е. в фигурных скобках и с использованием всех шестнадцатеричных цифр в верхнем регистре).

1. Объекты базы данных

Database.OpenView(sql)

Возвращает объект представления, вызывая MSIDatabaseOpenView(). sql — SQL-запрос для выполнения.

Database.Commit()

Подтверждает изменения, ожидающие обработки в текущей транзакции, вызывая MSIDatabaseCommit().

Database.GetSummaryInformation(count)

Возвращает новый объект сводной информации, вызывая MsiGetSummaryInformation(). count — максимальное количество обновлённых значений.

2. Объекты представления

View.Execute(params)

Выполняет SQL-запрос представления через MSIViewExecute(). Если params не None, это запись, описывающая фактические значения маркеров параметров в запросе.

View.GetColumnInfo(kind)

Возвращает запись, описывающую столбцы представления, вызывая MsiViewGetColumnInfo(). kind может быть либо MSICOLINFO_NAMES или MSICOLINFO_TYPES.

View.Fetch()

Возвращает запись результата запроса, вызывая MsiViewFetch().

View.Modify(kind, data)

Изменяет представление, вызывая MsiViewModify(). kind может быть одним из MSIMODIFY_SEEK, MSIMODIFY_REFRESH, MSIMODIFY_INSERT, MSIMODIFY_UPDATE, MSIMODIFY_ASSIGN, MSIMODIFY_REPLACE, MSIMODIFY_MERGE, MSIMODIFY_DELETE, MSIMODIFY_INSERT_TEMPORARY, MSIMODIFY_VALIDATE, MSIMODIFY_VALIDATE_NEW, MSIMODIFY_VALIDATE_FIELD, или MSIMODIFY_VALIDATE_DELETE.

data должна быть записью, описывающей новые данные.

View.Close()

Закрывает представление через MsiViewClose().

3. Объекты сводной информации

SummaryInformation.GetProperty(field)

Возвращает свойство сводки через MsiSummaryInfoGetProperty(). field — имя свойства, и может быть одним из констант PID_CODEPAGE, PID_TITLE, PID_SUBJECT, PID_AUTHOR, PID_KEYWORDS, PID_COMMENTS, PID_TEMPLATE, PID_LASTAUTHOR, PID_REVNUMBER, PID_LASTPRINTED, PID_CREATE_DTM, PID_LASTSAVE_DTM, PID_PAGECOUNT, PID_WORDCOUNT, PID_CHARCOUNT, PID_APPNAME, или PID_SECURITY.

SummaryInformation.GetPropertyCount()

Возвращает количество свойств сводки, через MsiSummaryInfoGetPropertyCount().

SummaryInformation.SetProperty(field, value)

Устанавливает свойство через MsiSummaryInfoSetProperty(). field может иметь те же значения, что и в GetProperty(), value — новое значение свойства. Возможные типы значений — целое число и строка.

SummaryInformation.Persist()

Записывает изменённые свойства в поток сводной информации, используя MsiSummaryInfoPersist().

4. Объекты записей

Record.GetFieldCount()

Возвращает количество полей записи, через MsiRecordGetFieldCount().

Record.GetInteger(field)

Возвращает значение поля field в виде целого числа, если это возможно. field должно быть целым числом.

Record.GetString(field)

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

Record.SetString(field, value)

Устанавливает значение поля field в value через MsiRecordSetString(). field должно быть целым числом; value — строкой.

Record.SetStream(field, value)

Устанавливает значение поля field в содержимое файла с именем value через MsiRecordSetStream(). field должно быть целым числом; value — строкой.

Record.SetInteger(field, value)

Устанавливает значение поля field в value через MsiRecordSetInteger(). И field, и value должны быть целыми числами.

Record.ClearData()

Устанавливает все поля записи в 0 через MsiRecordClearData().

5. Ошибки

Все обёртки вокруг функций MSI поднимают MSIError; строка внутри исключения будет содержать больше деталей.

6. Объекты CAB

class msilib.CAB(name)

Класс CAB представляет файл CAB. Во время создания MSI файлы будут одновременно добавляться в таблицу Files и в файл CAB. Затем, когда все файлы будут добавлены, файл CAB можно записать и добавить в файл MSI.

name — имя файла CAB в файле MSI.

append(full, file, logical)

Добавляет файл с полным путем full в файл CAB под именем logical. Если файл с именем logical уже существует, создаётся новое имя файла.

Возвращает индекс файла в файле CAB и новое имя файла внутри файла CAB.

commit(database)

Генерирует файл CAB, добавляет его как поток в файл MSI, помещает его в таблицу Media и удаляет сгенерированный файл с диска.

7. Объекты каталогов

class msilib.Directory(database, cab, basedir, physical, logical, default[, componentflags])

Создаёт новый каталог в таблице Каталог. В каждый момент времени для каталога существует текущий компонент, который создаётся явно через start_component() или неявно при первом добавлении файлов. Файлы добавляются в текущий компонент и в файл CAB. Для создания каталога необходимо указать базовый объект каталога (может быть None), путь к физическому каталогу и имя логического каталога. default указывает слот DefaultDir в таблице каталогов. componentflags указывает флаги по умолчанию, которые получают новые компоненты.

start_component([component[, feature[, flags[, keyfile[, uuid]]]]])

Добавляет запись в таблицу Компонент и делает этот компонент текущим компонентом для данного каталога. Если имя компонента не указано, используется имя каталога. Если feature не указан, используется текущее свойство. Если flags не указаны, используются флаги по умолчанию каталога. Если keyfile не указан, KeyPath остаётся пустым в таблице Компонент.

add_file(file[, src[, version[, language]]])

Добавляет файл в текущий компонент каталога, создавая новый, если текущего компонента нет. По умолчанию имя файла в источнике и таблице файлов будет идентичным. Если файл src указан, он интерпретируется относительно текущего каталога. Необязательно можно указать version и language для записи в таблице Файлов.

glob(pattern[, exclude])

Добавляет список файлов в текущий компонент, как указано в шаблоне glob. Отдельные файлы могут быть исключены в списке exclude.

remove_pyc()

Удалить файлы .pyc/.pyo при удалении.

8. Свойства

class msilib.Feature(database, id, title, desc, display[, level=1[, parent[, directory[, attributes=0]]]])

Добавляет новую запись в таблицу Feature, используя значения id, parent.id, title, desc, display, level, directory и attributes. Полученный объект свойства можно передать методу start_component() объекта Directory.

set_current()

Делает это свойство текущим свойством msilib. Новые компоненты автоматически добавляются в свойство по умолчанию, если не указано явно.

9. Классы графического интерфейса

msilib предоставляет несколько классов, которые оборачивают таблицы графического интерфейса в базе данных MSI. Однако стандартный пользовательский интерфейс не предоставляется; используйте bdist_msi для создания файлов MSI с пользовательским интерфейсом для установки пакетов Python.

class msilib.Control(dlg, name)

Базовый класс элементов управления диалоговым окном. dlg — это объект диалогового окна, к которому принадлежит элемент управления, а name — имя элемента управления.

event(event, argument[, condition=1[, ordering]])

Создаёт запись в таблице ControlEvent для этого элемента управления.

mapping(event, attribute)

Создаёт запись в таблице EventMapping для этого элемента управления.

condition(action, condition)

Создаёт запись в таблице ControlCondition для этого элемента управления.

class msilib.RadioButtonGroup(dlg, name, property)

Создаёт элемент управления радиокнопкой с именем name. property — свойство установщика, которое устанавливается при выборе радиокнопки.

add(name, x, y, width, height, text[, value])

Добавляет радиокнопку с именем name в группу по координатам x, y, width, height с меткой text. Если value опущен, он по умолчанию равен name.

class msilib.Dialog(db, name, x, y, w, h, attr, title, first, default, cancel)

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

control(name, type, x, y, width, height, attributes, property, text, control_next, help)

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

Этот метод является общим; для конкретных типов предоставляются специализированные методы.

text(name, x, y, width, height, attributes, text)

Добавляет и возвращает элемент управления Text.

bitmap(name, x, y, width, height, text)

Добавляет и возвращает элемент управления Bitmap.

line(name, x, y, width, height)

Добавляет и возвращает элемент управления Line.

pushbutton(name, x, y, width, height, attributes, text, next_control)

Добавляет и возвращает элемент управления PushButton.

radiogroup(name, x, y, width, height, attributes, property, text, next_control)

Добавляет и возвращает элемент управления RadioButtonGroup.

checkbox(name, x, y, width, height, attributes, property, text, next_control)

Добавляет и возвращает элемент управления CheckBox.

10. Предварительно вычисленные таблицы

msilib предоставляет несколько подпакетов, содержащих только определения схем и таблиц. В настоящее время эти определения основаны на версии MSI 2.0.

msilib.schema

Это стандартная схема MSI для MSI 2.0, где переменная tables содержит список определений таблиц, а _Validation_records — данные для проверки MSI.

msilib.sequence

Этот модуль содержит содержимое таблиц стандартной последовательности: AdminExecuteSequence, AdminUISequence, AdvtExecuteSequence, InstallExecuteSequence и InstallUISequence.

msilib.text

Этот модуль содержит определения таблиц UIText и ActionText для стандартных действий установщика.