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

Исходный код: Lib/msilib/__init__.py

Модуль msilib поддерживает создание файлов Microsoft Installer (.msi) файлов. Поскольку эти файлы часто содержат встроенный «архив» (.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=None, feature=None, flags=None, keyfile=None, uuid=None)

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

add_file(file, src=None, version=None, language=None)

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

glob(pattern, exclude=None)

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

remove_pyc()

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

8. Компоненты

class msilib.Feature(db, id, title, desc, display, level=1, parent=None, directory=None, attributes=0)

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

set_current()

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

9. Классы GUI

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

class msilib.Control(dlg, name)

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

event(event, argument, condition=1, ordering=None)

Создаёт запись в таблице 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=None)

Добавляет радиокнопку с именем name в группу по координатам x, y, width, height и с меткой text. Если value равно None, оно по умолчанию равно 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 для стандартных действий установщика.