1
:mod:`msilib` --- Read and write Microsoft Installer files
2
==========================================================
6
:synopsis: Creation of Microsoft Installer files, and CAB files.
7
.. moduleauthor:: Martin v. Löwis <martin@v.loewis.de>
8
.. sectionauthor:: Martin v. Löwis <martin@v.loewis.de>
11
.. index:: single: msi
13
The :mod:`msilib` supports the creation of Microsoft Installer (``.msi``) files.
14
Because these files often contain an embedded "cabinet" file (``.cab``), it also
15
exposes an API to create CAB files. Support for reading ``.cab`` files is
16
currently not implemented; read support for the ``.msi`` database is possible.
18
This package aims to provide complete access to all tables in an ``.msi`` file,
19
therefore, it is a fairly low-level API. Two primary applications of this
20
package are the :mod:`distutils` command ``bdist_msi``, and the creation of
21
Python installer package itself (although that currently uses a different
22
version of ``msilib``).
24
The package contents can be roughly split into four parts: low-level CAB
25
routines, low-level MSI routines, higher-level MSI routines, and standard table
29
.. function:: FCICreate(cabname, files)
31
Create a new CAB file named *cabname*. *files* must be a list of tuples, each
32
containing the name of the file on disk, and the name of the file inside the CAB
35
The files are added to the CAB file in the order they appear in the list. All
36
files are added into a single CAB file, using the MSZIP compression algorithm.
38
Callbacks to Python for the various steps of MSI creation are currently not
42
.. function:: UuidCreate()
44
Return the string representation of a new unique identifier. This wraps the
45
Windows API functions :c:func:`UuidCreate` and :c:func:`UuidToString`.
48
.. function:: OpenDatabase(path, persist)
50
Return a new database object by calling MsiOpenDatabase. *path* is the file
51
name of the MSI file; *persist* can be one of the constants
52
``MSIDBOPEN_CREATEDIRECT``, ``MSIDBOPEN_CREATE``, ``MSIDBOPEN_DIRECT``,
53
``MSIDBOPEN_READONLY``, or ``MSIDBOPEN_TRANSACT``, and may include the flag
54
``MSIDBOPEN_PATCHFILE``. See the Microsoft documentation for the meaning of
55
these flags; depending on the flags, an existing database is opened, or a new
59
.. function:: CreateRecord(count)
61
Return a new record object by calling :c:func:`MSICreateRecord`. *count* is the
62
number of fields of the record.
65
.. function:: init_database(name, schema, ProductName, ProductCode, ProductVersion, Manufacturer)
67
Create and return a new database *name*, initialize it with *schema*, and set
68
the properties *ProductName*, *ProductCode*, *ProductVersion*, and
71
*schema* must be a module object containing ``tables`` and
72
``_Validation_records`` attributes; typically, :mod:`msilib.schema` should be
75
The database will contain just the schema and the validation records when this
79
.. function:: add_data(database, table, records)
81
Add all *records* to the table named *table* in *database*.
83
The *table* argument must be one of the predefined tables in the MSI schema,
84
e.g. ``'Feature'``, ``'File'``, ``'Component'``, ``'Dialog'``, ``'Control'``,
87
*records* should be a list of tuples, each one containing all fields of a
88
record according to the schema of the table. For optional fields,
89
``None`` can be passed.
91
Field values can be ints, strings, or instances of the Binary class.
94
.. class:: Binary(filename)
96
Represents entries in the Binary table; inserting such an object using
97
:func:`add_data` reads the file named *filename* into the table.
100
.. function:: add_tables(database, module)
102
Add all table content from *module* to *database*. *module* must contain an
103
attribute *tables* listing all tables for which content should be added, and one
104
attribute per table that has the actual content.
106
This is typically used to install the sequence tables.
109
.. function:: add_stream(database, name, path)
111
Add the file *path* into the ``_Stream`` table of *database*, with the stream
115
.. function:: gen_uuid()
117
Return a new UUID, in the format that MSI typically requires (i.e. in curly
118
braces, and with all hexdigits in upper-case).
123
`FCICreateFile <http://msdn.microsoft.com/library?url=/library/en-us/devnotes/winprog/fcicreate.asp>`_
124
`UuidCreate <http://msdn.microsoft.com/library?url=/library/en-us/rpc/rpc/uuidcreate.asp>`_
125
`UuidToString <http://msdn.microsoft.com/library?url=/library/en-us/rpc/rpc/uuidtostring.asp>`_
127
.. _database-objects:
133
.. method:: Database.OpenView(sql)
135
Return a view object, by calling :c:func:`MSIDatabaseOpenView`. *sql* is the SQL
136
statement to execute.
139
.. method:: Database.Commit()
141
Commit the changes pending in the current transaction, by calling
142
:c:func:`MSIDatabaseCommit`.
145
.. method:: Database.GetSummaryInformation(count)
147
Return a new summary information object, by calling
148
:c:func:`MsiGetSummaryInformation`. *count* is the maximum number of updated
154
`MSIDatabaseOpenView <http://msdn.microsoft.com/library?url=/library/en-us/msi/setup/msidatabaseopenview.asp>`_
155
`MSIDatabaseCommit <http://msdn.microsoft.com/library?url=/library/en-us/msi/setup/msidatabasecommit.asp>`_
156
`MSIGetSummaryInformation <http://msdn.microsoft.com/library?url=/library/en-us/msi/setup/msigetsummaryinformation.asp>`_
164
.. method:: View.Execute(params)
166
Execute the SQL query of the view, through :c:func:`MSIViewExecute`. If
167
*params* is not ``None``, it is a record describing actual values of the
168
parameter tokens in the query.
171
.. method:: View.GetColumnInfo(kind)
173
Return a record describing the columns of the view, through calling
174
:c:func:`MsiViewGetColumnInfo`. *kind* can be either ``MSICOLINFO_NAMES`` or
175
``MSICOLINFO_TYPES``.
178
.. method:: View.Fetch()
180
Return a result record of the query, through calling :c:func:`MsiViewFetch`.
183
.. method:: View.Modify(kind, data)
185
Modify the view, by calling :c:func:`MsiViewModify`. *kind* can be one of
186
``MSIMODIFY_SEEK``, ``MSIMODIFY_REFRESH``, ``MSIMODIFY_INSERT``,
187
``MSIMODIFY_UPDATE``, ``MSIMODIFY_ASSIGN``, ``MSIMODIFY_REPLACE``,
188
``MSIMODIFY_MERGE``, ``MSIMODIFY_DELETE``, ``MSIMODIFY_INSERT_TEMPORARY``,
189
``MSIMODIFY_VALIDATE``, ``MSIMODIFY_VALIDATE_NEW``,
190
``MSIMODIFY_VALIDATE_FIELD``, or ``MSIMODIFY_VALIDATE_DELETE``.
192
*data* must be a record describing the new data.
195
.. method:: View.Close()
197
Close the view, through :c:func:`MsiViewClose`.
202
`MsiViewExecute <http://msdn.microsoft.com/library?url=/library/en-us/msi/setup/msiviewexecute.asp>`_
203
`MSIViewGetColumnInfo <http://msdn.microsoft.com/library?url=/library/en-us/msi/setup/msiviewgetcolumninfo.asp>`_
204
`MsiViewFetch <http://msdn.microsoft.com/library?url=/library/en-us/msi/setup/msiviewfetch.asp>`_
205
`MsiViewModify <http://msdn.microsoft.com/library?url=/library/en-us/msi/setup/msiviewmodify.asp>`_
206
`MsiViewClose <http://msdn.microsoft.com/library?url=/library/en-us/msi/setup/msiviewclose.asp>`_
210
Summary Information Objects
211
---------------------------
214
.. method:: SummaryInformation.GetProperty(field)
216
Return a property of the summary, through :c:func:`MsiSummaryInfoGetProperty`.
217
*field* is the name of the property, and can be one of the constants
218
``PID_CODEPAGE``, ``PID_TITLE``, ``PID_SUBJECT``, ``PID_AUTHOR``,
219
``PID_KEYWORDS``, ``PID_COMMENTS``, ``PID_TEMPLATE``, ``PID_LASTAUTHOR``,
220
``PID_REVNUMBER``, ``PID_LASTPRINTED``, ``PID_CREATE_DTM``,
221
``PID_LASTSAVE_DTM``, ``PID_PAGECOUNT``, ``PID_WORDCOUNT``, ``PID_CHARCOUNT``,
222
``PID_APPNAME``, or ``PID_SECURITY``.
225
.. method:: SummaryInformation.GetPropertyCount()
227
Return the number of summary properties, through
228
:c:func:`MsiSummaryInfoGetPropertyCount`.
231
.. method:: SummaryInformation.SetProperty(field, value)
233
Set a property through :c:func:`MsiSummaryInfoSetProperty`. *field* can have the
234
same values as in :meth:`GetProperty`, *value* is the new value of the property.
235
Possible value types are integer and string.
238
.. method:: SummaryInformation.Persist()
240
Write the modified properties to the summary information stream, using
241
:c:func:`MsiSummaryInfoPersist`.
246
`MsiSummaryInfoGetProperty <http://msdn.microsoft.com/library?url=/library/en-us/msi/setup/msisummaryinfogetproperty.asp>`_
247
`MsiSummaryInfoGetPropertyCount <http://msdn.microsoft.com/library?url=/library/en-us/msi/setup/msisummaryinfogetpropertycount.asp>`_
248
`MsiSummaryInfoSetProperty <http://msdn.microsoft.com/library?url=/library/en-us/msi/setup/msisummaryinfosetproperty.asp>`_
249
`MsiSummaryInfoPersist <http://msdn.microsoft.com/library?url=/library/en-us/msi/setup/msisummaryinfopersist.asp>`_
257
.. method:: Record.GetFieldCount()
259
Return the number of fields of the record, through
260
:c:func:`MsiRecordGetFieldCount`.
263
.. method:: Record.GetInteger(field)
265
Return the value of *field* as an integer where possible. *field* must
269
.. method:: Record.GetString(field)
271
Return the value of *field* as a string where possible. *field* must
275
.. method:: Record.SetString(field, value)
277
Set *field* to *value* through :c:func:`MsiRecordSetString`. *field* must be an
278
integer; *value* a string.
281
.. method:: Record.SetStream(field, value)
283
Set *field* to the contents of the file named *value*, through
284
:c:func:`MsiRecordSetStream`. *field* must be an integer; *value* a string.
287
.. method:: Record.SetInteger(field, value)
289
Set *field* to *value* through :c:func:`MsiRecordSetInteger`. Both *field* and
290
*value* must be an integer.
293
.. method:: Record.ClearData()
295
Set all fields of the record to 0, through :c:func:`MsiRecordClearData`.
300
`MsiRecordGetFieldCount <http://msdn.microsoft.com/library?url=/library/en-us/msi/setup/msirecordgetfieldcount.asp>`_
301
`MsiRecordSetString <http://msdn.microsoft.com/library?url=/library/en-us/msi/setup/msirecordsetstring.asp>`_
302
`MsiRecordSetStream <http://msdn.microsoft.com/library?url=/library/en-us/msi/setup/msirecordsetstream.asp>`_
303
`MsiRecordSetInteger <http://msdn.microsoft.com/library?url=/library/en-us/msi/setup/msirecordsetinteger.asp>`_
304
`MsiRecordClear <http://msdn.microsoft.com/library?url=/library/en-us/msi/setup/msirecordclear.asp>`_
311
All wrappers around MSI functions raise :exc:`MsiError`; the string inside the
312
exception will contain more detail.
323
The class :class:`CAB` represents a CAB file. During MSI construction, files
324
will be added simultaneously to the ``Files`` table, and to a CAB file. Then,
325
when all files have been added, the CAB file can be written, then added to the
328
*name* is the name of the CAB file in the MSI file.
331
.. method:: append(full, file, logical)
333
Add the file with the pathname *full* to the CAB file, under the name
334
*logical*. If there is already a file named *logical*, a new file name is
337
Return the index of the file in the CAB file, and the new name of the file
341
.. method:: commit(database)
343
Generate a CAB file, add it as a stream to the MSI file, put it into the
344
``Media`` table, and remove the generated file from the disk.
353
.. class:: Directory(database, cab, basedir, physical, logical, default, [componentflags])
355
Create a new directory in the Directory table. There is a current component at
356
each point in time for the directory, which is either explicitly created through
357
:meth:`start_component`, or implicitly when files are added for the first time.
358
Files are added into the current component, and into the cab file. To create a
359
directory, a base directory object needs to be specified (can be ``None``), the
360
path to the physical directory, and a logical directory name. *default*
361
specifies the DefaultDir slot in the directory table. *componentflags* specifies
362
the default flags that new components get.
365
.. method:: start_component(component=None, feature=None, flags=None, keyfile=None, uuid=None)
367
Add an entry to the Component table, and make this component the current
368
component for this directory. If no component name is given, the directory
369
name is used. If no *feature* is given, the current feature is used. If no
370
*flags* are given, the directory's default flags are used. If no *keyfile*
371
is given, the KeyPath is left null in the Component table.
374
.. method:: add_file(file, src=None, version=None, language=None)
376
Add a file to the current component of the directory, starting a new one
377
if there is no current component. By default, the file name in the source
378
and the file table will be identical. If the *src* file is specified, it
379
is interpreted relative to the current directory. Optionally, a *version*
380
and a *language* can be specified for the entry in the File table.
383
.. method:: glob(pattern, exclude=None)
385
Add a list of files to the current component as specified in the glob
386
pattern. Individual files can be excluded in the *exclude* list.
389
.. method:: remove_pyc()
391
Remove ``.pyc``/``.pyo`` files on uninstall.
396
`Directory Table <http://msdn.microsoft.com/library?url=/library/en-us/msi/setup/directory_table.asp>`_
397
`File Table <http://msdn.microsoft.com/library?url=/library/en-us/msi/setup/file_table.asp>`_
398
`Component Table <http://msdn.microsoft.com/library?url=/library/en-us/msi/setup/component_table.asp>`_
399
`FeatureComponents Table <http://msdn.microsoft.com/library?url=/library/en-us/msi/setup/featurecomponents_table.asp>`_
407
.. class:: Feature(db, id, title, desc, display, level=1, parent=None, directory=None, attributes=0)
409
Add a new record to the ``Feature`` table, using the values *id*, *parent.id*,
410
*title*, *desc*, *display*, *level*, *directory*, and *attributes*. The
411
resulting feature object can be passed to the :meth:`start_component` method of
415
.. method:: set_current()
417
Make this feature the current feature of :mod:`msilib`. New components are
418
automatically added to the default feature, unless a feature is explicitly
424
`Feature Table <http://msdn.microsoft.com/library?url=/library/en-us/msi/setup/feature_table.asp>`_
431
:mod:`msilib` provides several classes that wrap the GUI tables in an MSI
432
database. However, no standard user interface is provided; use
433
:mod:`~distutils.command.bdist_msi` to create MSI files with a user-interface
434
for installing Python packages.
437
.. class:: Control(dlg, name)
439
Base class of the dialog controls. *dlg* is the dialog object the control
440
belongs to, and *name* is the control's name.
443
.. method:: event(event, argument, condition=1, ordering=None)
445
Make an entry into the ``ControlEvent`` table for this control.
448
.. method:: mapping(event, attribute)
450
Make an entry into the ``EventMapping`` table for this control.
453
.. method:: condition(action, condition)
455
Make an entry into the ``ControlCondition`` table for this control.
458
.. class:: RadioButtonGroup(dlg, name, property)
460
Create a radio button control named *name*. *property* is the installer property
461
that gets set when a radio button is selected.
464
.. method:: add(name, x, y, width, height, text, value=None)
466
Add a radio button named *name* to the group, at the coordinates *x*, *y*,
467
*width*, *height*, and with the label *text*. If *value* is ``None``, it
471
.. class:: Dialog(db, name, x, y, w, h, attr, title, first, default, cancel)
473
Return a new :class:`Dialog` object. An entry in the ``Dialog`` table is made,
474
with the specified coordinates, dialog attributes, title, name of the first,
475
default, and cancel controls.
478
.. method:: control(name, type, x, y, width, height, attributes, property, text, control_next, help)
480
Return a new :class:`Control` object. An entry in the ``Control`` table is
481
made with the specified parameters.
483
This is a generic method; for specific types, specialized methods are
487
.. method:: text(name, x, y, width, height, attributes, text)
489
Add and return a ``Text`` control.
492
.. method:: bitmap(name, x, y, width, height, text)
494
Add and return a ``Bitmap`` control.
497
.. method:: line(name, x, y, width, height)
499
Add and return a ``Line`` control.
502
.. method:: pushbutton(name, x, y, width, height, attributes, text, next_control)
504
Add and return a ``PushButton`` control.
507
.. method:: radiogroup(name, x, y, width, height, attributes, property, text, next_control)
509
Add and return a ``RadioButtonGroup`` control.
512
.. method:: checkbox(name, x, y, width, height, attributes, property, text, next_control)
514
Add and return a ``CheckBox`` control.
519
`Dialog Table <http://msdn.microsoft.com/library?url=/library/en-us/msi/setup/dialog_table.asp>`_
520
`Control Table <http://msdn.microsoft.com/library?url=/library/en-us/msi/setup/control_table.asp>`_
521
`Control Types <http://msdn.microsoft.com/library?url=/library/en-us/msi/setup/controls.asp>`_
522
`ControlCondition Table <http://msdn.microsoft.com/library?url=/library/en-us/msi/setup/controlcondition_table.asp>`_
523
`ControlEvent Table <http://msdn.microsoft.com/library?url=/library/en-us/msi/setup/controlevent_table.asp>`_
524
`EventMapping Table <http://msdn.microsoft.com/library?url=/library/en-us/msi/setup/eventmapping_table.asp>`_
525
`RadioButton Table <http://msdn.microsoft.com/library?url=/library/en-us/msi/setup/radiobutton_table.asp>`_
532
:mod:`msilib` provides a few subpackages that contain only schema and table
533
definitions. Currently, these definitions are based on MSI version 2.0.
538
This is the standard MSI schema for MSI 2.0, with the *tables* variable
539
providing a list of table definitions, and *_Validation_records* providing the
540
data for MSI validation.
545
This module contains table contents for the standard sequence tables:
546
*AdminExecuteSequence*, *AdminUISequence*, *AdvtExecuteSequence*,
547
*InstallExecuteSequence*, and *InstallUISequence*.
552
This module contains definitions for the UIText and ActionText tables, for the
553
standard installer actions.
added
removed
python-3.5.1-docs-html/_sources/library/msilib.txt
