msilib — Read and write Microsoft Installer files

Source code:Lib/msilib/__init__.py

Deprecated since version 3.11:Themsilib module is deprecated(seePEP 594 for details).

Themsilib supports the creation of Microsoft Installer (.msi) files.Because these files often contain an embedded “cabinet” file (.cab), it alsoexposes an API to create CAB files. Support for reading.cab files iscurrently not implemented; read support for the.msi database is possible.

This package aims to provide complete access to all tables in an.msi file,therefore, it is a fairly low-level API. Two primary applications of thispackage are thedistutils commandbdist_msi, and the creation ofPython installer package itself (although that currently uses a differentversion ofmsilib).

The package contents can be roughly split into four parts: low-level CABroutines, low-level MSI routines, higher-level MSI routines, and standard tablestructures.

msilib.FCICreate(cabname,files)

Create a new CAB file namedcabname.files must be a list of tuples, eachcontaining the name of the file on disk, and the name of the file inside the CABfile.

The files are added to the CAB file in the order they appear in the list. Allfiles are added into a single CAB file, using the MSZIP compression algorithm.

Callbacks to Python for the various steps of MSI creation are currently notexposed.

msilib.UuidCreate()

Return the string representation of a new unique identifier. This wraps theWindows API functionsUuidCreate() andUuidToString().

msilib.OpenDatabase(path,persist)

Return a new database object by calling MsiOpenDatabase.path is the filename of the MSI file;persist can be one of the constantsMSIDBOPEN_CREATEDIRECT,MSIDBOPEN_CREATE,MSIDBOPEN_DIRECT,MSIDBOPEN_READONLY, orMSIDBOPEN_TRANSACT, and may include the flagMSIDBOPEN_PATCHFILE. See the Microsoft documentation for the meaning ofthese flags; depending on the flags, an existing database is opened, or a newone created.

msilib.CreateRecord(count)

Return a new record object by callingMSICreateRecord().count is thenumber of fields of the record.

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

Create and return a new databasename, initialize it withschema, and setthe propertiesProductName,ProductCode,ProductVersion, andManufacturer.

schema must be a module object containingtables and_Validation_records attributes; typically,msilib.schema should beused.

The database will contain just the schema and the validation records when thisfunction returns.

msilib.add_data(database,table,records)

Add allrecords to the table namedtable indatabase.

Thetable argument must be one of the predefined tables in the MSI schema,e.g.'Feature','File','Component','Dialog','Control',etc.

records should be a list of tuples, each one containing all fields of arecord according to the schema of the table. For optional fields,None can be passed.

Field values can be ints, strings, or instances of the Binary class.

classmsilib.Binary(filename)

Represents entries in the Binary table; inserting such an object usingadd_data() reads the file namedfilename into the table.

msilib.add_tables(database,module)

Add all table content frommodule todatabase.module must contain anattributetables listing all tables for which content should be added, and oneattribute per table that has the actual content.

This is typically used to install the sequence tables.

msilib.add_stream(database,name,path)

Add the filepath into the_Stream table ofdatabase, with the streamnamename.

msilib.gen_uuid()

Return a new UUID, in the format that MSI typically requires (i.e. in curlybraces, and with all hexdigits in upper-case).

Database Objects

Database.OpenView(sql)

Return a view object, by callingMSIDatabaseOpenView().sql is the SQLstatement to execute.

Database.Commit()

Commit the changes pending in the current transaction, by callingMSIDatabaseCommit().

Database.GetSummaryInformation(count)

Return a new summary information object, by callingMsiGetSummaryInformation().count is the maximum number of updatedvalues.

Database.Close()

Close the database object, throughMsiCloseHandle().

New in version 3.7.

View Objects

View.Execute(params)

Execute the SQL query of the view, throughMSIViewExecute(). Ifparams is notNone, it is a record describing actual values of theparameter tokens in the query.

View.GetColumnInfo(kind)

Return a record describing the columns of the view, through callingMsiViewGetColumnInfo().kind can be eitherMSICOLINFO_NAMES orMSICOLINFO_TYPES.

View.Fetch()

Return a result record of the query, through callingMsiViewFetch().

View.Modify(kind,data)

Modify the view, by callingMsiViewModify().kind can be one ofMSIMODIFY_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, orMSIMODIFY_VALIDATE_DELETE.

data must be a record describing the new data.

View.Close()

Close the view, throughMsiViewClose().

Summary Information Objects

SummaryInformation.GetProperty(field)

Return a property of the summary, throughMsiSummaryInfoGetProperty().field is the name of the property, and can be one of the constantsPID_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, orPID_SECURITY.

SummaryInformation.GetPropertyCount()

Return the number of summary properties, throughMsiSummaryInfoGetPropertyCount().

SummaryInformation.SetProperty(field,value)

Set a property throughMsiSummaryInfoSetProperty().field can have thesame values as inGetProperty(),value is the new value of the property.Possible value types are integer and string.

SummaryInformation.Persist()

Write the modified properties to the summary information stream, usingMsiSummaryInfoPersist().

Record Objects

Record.GetFieldCount()

Return the number of fields of the record, throughMsiRecordGetFieldCount().

Record.GetInteger(field)

Return the value offield as an integer where possible.field mustbe an integer.

Record.GetString(field)

Return the value offield as a string where possible.field mustbe an integer.

Record.SetString(field,value)

Setfield tovalue throughMsiRecordSetString().field must be aninteger;value a string.

Record.SetStream(field,value)

Setfield to the contents of the file namedvalue, throughMsiRecordSetStream().field must be an integer;value a string.

Record.SetInteger(field,value)

Setfield tovalue throughMsiRecordSetInteger(). Bothfield andvalue must be an integer.

Record.ClearData()

Set all fields of the record to 0, throughMsiRecordClearData().

Errors

All wrappers around MSI functions raiseMSIError; the string inside theexception will contain more detail.

CAB Objects

classmsilib.CAB(name)

The classCAB represents a CAB file. During MSI construction, fileswill be added simultaneously to theFiles table, and to a CAB file. Then,when all files have been added, the CAB file can be written, then added to theMSI file.

name is the name of the CAB file in the MSI file.

append(full,file,logical)

Add the file with the pathnamefull to the CAB file, under the namelogical. If there is already a file namedlogical, a new file name iscreated.

Return the index of the file in the CAB file, and the new name of the fileinside the CAB file.

commit(database)

Generate a CAB file, add it as a stream to the MSI file, put it into theMedia table, and remove the generated file from the disk.

Directory Objects

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

Create a new directory in the Directory table. There is a current component ateach point in time for the directory, which is either explicitly created throughstart_component(), or implicitly when files are added for the first time.Files are added into the current component, and into the cab file. To create adirectory, a base directory object needs to be specified (can beNone), thepath to the physical directory, and a logical directory name.defaultspecifies the DefaultDir slot in the directory table.componentflags specifiesthe default flags that new components get.

start_component(component=None,feature=None,flags=None,keyfile=None,uuid=None)

Add an entry to the Component table, and make this component the currentcomponent for this directory. If no component name is given, the directoryname is used. If nofeature is given, the current feature is used. If noflags are given, the directory’s default flags are used. If nokeyfileis given, the KeyPath is left null in the Component table.

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

Add a file to the current component of the directory, starting a new oneif there is no current component. By default, the file name in the sourceand the file table will be identical. If thesrc file is specified, itis interpreted relative to the current directory. Optionally, aversionand alanguage can be specified for the entry in the File table.

glob(pattern,exclude=None)

Add a list of files to the current component as specified in the globpattern. Individual files can be excluded in theexclude list.

remove_pyc()

Remove.pyc files on uninstall.

Features

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

Add a new record to theFeature table, using the valuesid,parent.id,title,desc,display,level,directory, andattributes. Theresulting feature object can be passed to thestart_component() method ofDirectory.

set_current()

Make this feature the current feature ofmsilib. New components areautomatically added to the default feature, unless a feature is explicitlyspecified.

GUI classes

msilib provides several classes that wrap the GUI tables in an MSIdatabase. However, no standard user interface is provided; usebdist_msi to create MSI files with a user-interfacefor installing Python packages.

classmsilib.Control(dlg,name)

Base class of the dialog controls.dlg is the dialog object the controlbelongs to, andname is the control’s name.

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

Make an entry into theControlEvent table for this control.

mapping(event,attribute)

Make an entry into theEventMapping table for this control.

condition(action,condition)

Make an entry into theControlCondition table for this control.

classmsilib.RadioButtonGroup(dlg,name,property)

Create a radio button control namedname.property is the installer propertythat gets set when a radio button is selected.

add(name,x,y,width,height,text,value=None)

Add a radio button namedname to the group, at the coordinatesx,y,width,height, and with the labeltext. Ifvalue isNone, itdefaults toname.

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

Return a newDialog object. An entry in theDialog table is made,with the specified coordinates, dialog attributes, title, name of the first,default, and cancel controls.

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

Return a newControl object. An entry in theControl table ismade with the specified parameters.

This is a generic method; for specific types, specialized methods areprovided.

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

Add and return aText control.

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

Add and return aBitmap control.

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

Add and return aLine control.

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

Add and return aPushButton control.

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

Add and return aRadioButtonGroup control.

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

Add and return aCheckBox control.

Precomputed tables

msilib provides a few subpackages that contain only schema and tabledefinitions. Currently, these definitions are based on MSI version 2.0.

msilib.schema

This is the standard MSI schema for MSI 2.0, with thetables variableproviding a list of table definitions, and_Validation_records providing thedata for MSI validation.

msilib.sequence

This module contains table contents for the standard sequence tables:AdminExecuteSequence,AdminUISequence,AdvtExecuteSequence,InstallExecuteSequence, andInstallUISequence.

msilib.text

This module contains definitions for the UIText and ActionText tables, for thestandard installer actions.