/Doc/library/msilib.rst

  1:mod:`msilib` --- Read and write Microsoft Installer files
  2==========================================================
  3
  4.. module:: msilib
  5   :platform: Windows
  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>
  9
 10
 11.. index:: single: msi
 12
 13.. versionadded:: 2.5
 14
 15The :mod:`msilib` supports the creation of Microsoft Installer (``.msi``) files.
 16Because these files often contain an embedded "cabinet" file (``.cab``), it also
 17exposes an API to create CAB files. Support for reading ``.cab`` files is
 18currently not implemented; read support for the ``.msi`` database is possible.
 19
 20This package aims to provide complete access to all tables in an ``.msi`` file,
 21therefore, it is a fairly low-level API. Two primary applications of this
 22package are the :mod:`distutils` command ``bdist_msi``, and the creation of
 23Python installer package itself (although that currently uses a different
 24version of ``msilib``).
 25
 26The package contents can be roughly split into four parts: low-level CAB
 27routines, low-level MSI routines, higher-level MSI routines, and standard table
 28structures.
 29
 30
 31.. function:: FCICreate(cabname, files)
 32
 33   Create a new CAB file named *cabname*. *files* must be a list of tuples, each
 34   containing the name of the file on disk, and the name of the file inside the CAB
 35   file.
 36
 37   The files are added to the CAB file in the order they appear in the list. All
 38   files are added into a single CAB file, using the MSZIP compression algorithm.
 39
 40   Callbacks to Python for the various steps of MSI creation are currently not
 41   exposed.
 42
 43
 44.. function:: UuidCreate()
 45
 46   Return the string representation of a new unique identifier. This wraps the
 47   Windows API functions :cfunc:`UuidCreate` and :cfunc:`UuidToString`.
 48
 49
 50.. function:: OpenDatabase(path, persist)
 51
 52   Return a new database object by calling MsiOpenDatabase.   *path* is the file
 53   name of the MSI file; *persist* can be one of the constants
 54   ``MSIDBOPEN_CREATEDIRECT``, ``MSIDBOPEN_CREATE``, ``MSIDBOPEN_DIRECT``,
 55   ``MSIDBOPEN_READONLY``, or ``MSIDBOPEN_TRANSACT``, and may include the flag
 56   ``MSIDBOPEN_PATCHFILE``. See the Microsoft documentation for the meaning of
 57   these flags; depending on the flags, an existing database is opened, or a new
 58   one created.
 59
 60
 61.. function:: CreateRecord(count)
 62
 63   Return a new record object by calling :cfunc:`MSICreateRecord`. *count* is the
 64   number of fields of the record.
 65
 66
 67.. function:: init_database(name, schema, ProductName, ProductCode, ProductVersion, Manufacturer)
 68
 69   Create and return a new database *name*, initialize it with *schema*, and set
 70   the properties *ProductName*, *ProductCode*, *ProductVersion*, and
 71   *Manufacturer*.
 72
 73   *schema* must be a module object containing ``tables`` and
 74   ``_Validation_records`` attributes; typically, :mod:`msilib.schema` should be
 75   used.
 76
 77   The database will contain just the schema and the validation records when this
 78   function returns.
 79
 80
 81.. function:: add_data(database, table, records)
 82
 83   Add all *records* to the table named *table* in *database*.
 84
 85   The *table* argument must be one of the predefined tables in the MSI schema,
 86   e.g. ``'Feature'``, ``'File'``, ``'Component'``, ``'Dialog'``, ``'Control'``,
 87   etc.
 88
 89   *records* should be a list of tuples, each one containing all fields of a
 90   record according to the schema of the table.  For optional fields,
 91   ``None`` can be passed.
 92
 93   Field values can be int or long numbers, strings, or instances of the Binary
 94   class.
 95
 96
 97.. class:: Binary(filename)
 98
 99   Represents entries in the Binary table; inserting such an object using
100   :func:`add_data` reads the file named *filename* into the table.
101
102
103.. function:: add_tables(database, module)
104
105   Add all table content from *module* to *database*. *module* must contain an
106   attribute *tables* listing all tables for which content should be added, and one
107   attribute per table that has the actual content.
108
109   This is typically used to install the sequence tables.
110
111
112.. function:: add_stream(database, name, path)
113
114   Add the file *path* into the ``_Stream`` table of *database*, with the stream
115   name *name*.
116
117
118.. function:: gen_uuid()
119
120   Return a new UUID, in the format that MSI typically requires (i.e. in curly
121   braces, and with all hexdigits in upper-case).
122
123
124.. seealso::
125
126   `FCICreateFile <http://msdn.microsoft.com/library/default.asp?url=/library/en-us/devnotes/winprog/fcicreate.asp>`_
127   `UuidCreate <http://msdn.microsoft.com/library/default.asp?url=/library/en-us/rpc/rpc/uuidcreate.asp>`_
128   `UuidToString <http://msdn.microsoft.com/library/default.asp?url=/library/en-us/rpc/rpc/uuidtostring.asp>`_
129
130.. _database-objects:
131
132Database Objects
133----------------
134
135
136.. method:: Database.OpenView(sql)
137
138   Return a view object, by calling :cfunc:`MSIDatabaseOpenView`. *sql* is the SQL
139   statement to execute.
140
141
142.. method:: Database.Commit()
143
144   Commit the changes pending in the current transaction, by calling
145   :cfunc:`MSIDatabaseCommit`.
146
147
148.. method:: Database.GetSummaryInformation(count)
149
150   Return a new summary information object, by calling
151   :cfunc:`MsiGetSummaryInformation`.  *count* is the maximum number of updated
152   values.
153
154
155.. seealso::
156
157   `MSIDatabaseOpenView <http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/msidatabaseopenview.asp>`_
158   `MSIDatabaseCommit <http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/msidatabasecommit.asp>`_
159   `MSIGetSummaryInformation <http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/msigetsummaryinformation.asp>`_
160
161.. _view-objects:
162
163View Objects
164------------
165
166
167.. method:: View.Execute(params)
168
169   Execute the SQL query of the view, through :cfunc:`MSIViewExecute`. If
170   *params* is not ``None``, it is a record describing actual values of the
171   parameter tokens in the query.
172
173
174.. method:: View.GetColumnInfo(kind)
175
176   Return a record describing the columns of the view, through calling
177   :cfunc:`MsiViewGetColumnInfo`. *kind* can be either ``MSICOLINFO_NAMES`` or
178   ``MSICOLINFO_TYPES``.
179
180
181.. method:: View.Fetch()
182
183   Return a result record of the query, through calling :cfunc:`MsiViewFetch`.
184
185
186.. method:: View.Modify(kind, data)
187
188   Modify the view, by calling :cfunc:`MsiViewModify`. *kind* can be one of
189   ``MSIMODIFY_SEEK``, ``MSIMODIFY_REFRESH``, ``MSIMODIFY_INSERT``,
190   ``MSIMODIFY_UPDATE``, ``MSIMODIFY_ASSIGN``, ``MSIMODIFY_REPLACE``,
191   ``MSIMODIFY_MERGE``, ``MSIMODIFY_DELETE``, ``MSIMODIFY_INSERT_TEMPORARY``,
192   ``MSIMODIFY_VALIDATE``, ``MSIMODIFY_VALIDATE_NEW``,
193   ``MSIMODIFY_VALIDATE_FIELD``, or ``MSIMODIFY_VALIDATE_DELETE``.
194
195   *data* must be a record describing the new data.
196
197
198.. method:: View.Close()
199
200   Close the view, through :cfunc:`MsiViewClose`.
201
202
203.. seealso::
204
205   `MsiViewExecute <http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/msiviewexecute.asp>`_
206   `MSIViewGetColumnInfo <http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/msiviewgetcolumninfo.asp>`_
207   `MsiViewFetch <http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/msiviewfetch.asp>`_
208   `MsiViewModify <http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/msiviewmodify.asp>`_
209   `MsiViewClose <http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/msiviewclose.asp>`_
210
211.. _summary-objects:
212
213Summary Information Objects
214---------------------------
215
216
217.. method:: SummaryInformation.GetProperty(field)
218
219   Return a property of the summary, through :cfunc:`MsiSummaryInfoGetProperty`.
220   *field* is the name of the property, and can be one of the constants
221   ``PID_CODEPAGE``, ``PID_TITLE``, ``PID_SUBJECT``, ``PID_AUTHOR``,
222   ``PID_KEYWORDS``, ``PID_COMMENTS``, ``PID_TEMPLATE``, ``PID_LASTAUTHOR``,
223   ``PID_REVNUMBER``, ``PID_LASTPRINTED``, ``PID_CREATE_DTM``,
224   ``PID_LASTSAVE_DTM``, ``PID_PAGECOUNT``, ``PID_WORDCOUNT``, ``PID_CHARCOUNT``,
225   ``PID_APPNAME``, or ``PID_SECURITY``.
226
227
228.. method:: SummaryInformation.GetPropertyCount()
229
230   Return the number of summary properties, through
231   :cfunc:`MsiSummaryInfoGetPropertyCount`.
232
233
234.. method:: SummaryInformation.SetProperty(field, value)
235
236   Set a property through :cfunc:`MsiSummaryInfoSetProperty`. *field* can have the
237   same values as in :meth:`GetProperty`, *value* is the new value of the property.
238   Possible value types are integer and string.
239
240
241.. method:: SummaryInformation.Persist()
242
243   Write the modified properties to the summary information stream, using
244   :cfunc:`MsiSummaryInfoPersist`.
245
246
247.. seealso::
248
249   `MsiSummaryInfoGetProperty <http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/msisummaryinfogetproperty.asp>`_
250   `MsiSummaryInfoGetPropertyCount <http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/msisummaryinfogetpropertycount.asp>`_
251   `MsiSummaryInfoSetProperty <http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/msisummaryinfosetproperty.asp>`_
252   `MsiSummaryInfoPersist <http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/msisummaryinfopersist.asp>`_
253
254.. _record-objects:
255
256Record Objects
257--------------
258
259
260.. method:: Record.GetFieldCount()
261
262   Return the number of fields of the record, through
263   :cfunc:`MsiRecordGetFieldCount`.
264
265
266.. method:: Record.GetInteger(field)
267
268   Return the value of *field* as an integer where possible.  *field* must
269   be an integer.
270
271
272.. method:: Record.GetString(field)
273
274   Return the value of *field* as a string where possible.  *field* must
275   be an integer.
276
277
278.. method:: Record.SetString(field, value)
279
280   Set *field* to *value* through :cfunc:`MsiRecordSetString`. *field* must be an
281   integer; *value* a string.
282
283
284.. method:: Record.SetStream(field, value)
285
286   Set *field* to the contents of the file named *value*, through
287   :cfunc:`MsiRecordSetStream`. *field* must be an integer; *value* a string.
288
289
290.. method:: Record.SetInteger(field, value)
291
292   Set *field* to *value* through :cfunc:`MsiRecordSetInteger`. Both *field* and
293   *value* must be an integer.
294
295
296.. method:: Record.ClearData()
297
298   Set all fields of the record to 0, through :cfunc:`MsiRecordClearData`.
299
300
301.. seealso::
302
303   `MsiRecordGetFieldCount <http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/msirecordgetfieldcount.asp>`_
304   `MsiRecordSetString <http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/msirecordsetstring.asp>`_
305   `MsiRecordSetStream <http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/msirecordsetstream.asp>`_
306   `MsiRecordSetInteger <http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/msirecordsetinteger.asp>`_
307   `MsiRecordClear <http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/msirecordclear.asp>`_
308
309.. _msi-errors:
310
311Errors
312------
313
314All wrappers around MSI functions raise :exc:`MsiError`; the string inside the
315exception will contain more detail.
316
317
318.. _cab:
319
320CAB Objects
321-----------
322
323
324.. class:: CAB(name)
325
326   The class :class:`CAB` represents a CAB file. During MSI construction, files
327   will be added simultaneously to the ``Files`` table, and to a CAB file. Then,
328   when all files have been added, the CAB file can be written, then added to the
329   MSI file.
330
331   *name* is the name of the CAB file in the MSI file.
332
333
334   .. method:: append(full, file, logical)
335
336      Add the file with the pathname *full* to the CAB file, under the name
337      *logical*.  If there is already a file named *logical*, a new file name is
338      created.
339
340      Return the index of the file in the CAB file, and the new name of the file
341      inside the CAB file.
342
343
344   .. method:: commit(database)
345
346      Generate a CAB file, add it as a stream to the MSI file, put it into the
347      ``Media`` table, and remove the generated file from the disk.
348
349
350.. _msi-directory:
351
352Directory Objects
353-----------------
354
355
356.. class:: Directory(database, cab, basedir, physical,  logical, default, component, [componentflags])
357
358   Create a new directory in the Directory table. There is a current component at
359   each point in time for the directory, which is either explicitly created through
360   :meth:`start_component`, or implicitly when files are added for the first time.
361   Files are added into the current component, and into the cab file.  To create a
362   directory, a base directory object needs to be specified (can be ``None``), the
363   path to the physical directory, and a logical directory name.  *default*
364   specifies the DefaultDir slot in the directory table. *componentflags* specifies
365   the default flags that new components get.
366
367
368   .. method:: start_component([component[, feature[, flags[, keyfile[, uuid]]]]])
369
370      Add an entry to the Component table, and make this component the current
371      component for this directory. If no component name is given, the directory
372      name is used. If no *feature* is given, the current feature is used. If no
373      *flags* are given, the directory's default flags are used. If no *keyfile*
374      is given, the KeyPath is left null in the Component table.
375
376
377   .. method:: add_file(file[, src[, version[, language]]])
378
379      Add a file to the current component of the directory, starting a new one
380      if there is no current component. By default, the file name in the source
381      and the file table will be identical. If the *src* file is specified, it
382      is interpreted relative to the current directory. Optionally, a *version*
383      and a *language* can be specified for the entry in the File table.
384
385
386   .. method:: glob(pattern[, exclude])
387
388      Add a list of files to the current component as specified in the glob
389      pattern.  Individual files can be excluded in the *exclude* list.
390
391
392   .. method:: remove_pyc()
393
394      Remove ``.pyc``/``.pyo`` files on uninstall.
395
396
397.. seealso::
398
399   `Directory Table <http://msdn.microsoft.com/library/en-us/msi/setup/directory_table.asp>`_
400   `File Table <http://msdn.microsoft.com/library/en-us/msi/setup/file_table.asp>`_
401   `Component Table <http://msdn.microsoft.com/library/en-us/msi/setup/component_table.asp>`_
402   `FeatureComponents Table <http://msdn.microsoft.com/library/en-us/msi/setup/featurecomponents_table.asp>`_
403
404.. _features:
405
406Features
407--------
408
409
410.. class:: Feature(database, id, title, desc, display[, level=1[, parent[, directory[,  attributes=0]]]])
411
412   Add a new record to the ``Feature`` table, using the values *id*, *parent.id*,
413   *title*, *desc*, *display*, *level*, *directory*, and *attributes*. The
414   resulting feature object can be passed to the :meth:`start_component` method of
415   :class:`Directory`.
416
417
418   .. method:: set_current()
419
420      Make this feature the current feature of :mod:`msilib`. New components are
421      automatically added to the default feature, unless a feature is explicitly
422      specified.
423
424
425.. seealso::
426
427   `Feature Table <http://msdn.microsoft.com/library/en-us/msi/setup/feature_table.asp>`_
428
429.. _msi-gui:
430
431GUI classes
432-----------
433
434:mod:`msilib` provides several classes that wrap the GUI tables in an MSI
435database. However, no standard user interface is provided; use :mod:`bdist_msi`
436to create MSI files with a user-interface for installing Python packages.
437
438
439.. class:: Control(dlg, name)
440
441   Base class of the dialog controls. *dlg* is the dialog object the control
442   belongs to, and *name* is the control's name.
443
444
445   .. method:: event(event, argument[,  condition=1[, ordering]])
446
447      Make an entry into the ``ControlEvent`` table for this control.
448
449
450   .. method:: mapping(event, attribute)
451
452      Make an entry into the ``EventMapping`` table for this control.
453
454
455   .. method:: condition(action, condition)
456
457      Make an entry into the ``ControlCondition`` table for this control.
458
459
460.. class:: RadioButtonGroup(dlg, name, property)
461
462   Create a radio button control named *name*. *property* is the installer property
463   that gets set when a radio button is selected.
464
465
466   .. method:: add(name, x, y, width, height, text [, value])
467
468      Add a radio button named *name* to the group, at the coordinates *x*, *y*,
469      *width*, *height*, and with the label *text*. If *value* is omitted, it
470      defaults to *name*.
471
472
473.. class:: Dialog(db, name, x, y, w, h, attr, title, first,  default, cancel)
474
475   Return a new :class:`Dialog` object. An entry in the ``Dialog`` table is made,
476   with the specified coordinates, dialog attributes, title, name of the first,
477   default, and cancel controls.
478
479
480   .. method:: control(name, type, x, y, width, height,  attributes, property, text, control_next, help)
481
482      Return a new :class:`Control` object. An entry in the ``Control`` table is
483      made with the specified parameters.
484
485      This is a generic method; for specific types, specialized methods are
486      provided.
487
488
489   .. method:: text(name, x, y, width, height, attributes, text)
490
491      Add and return a ``Text`` control.
492
493
494   .. method:: bitmap(name, x, y, width, height, text)
495
496      Add and return a ``Bitmap`` control.
497
498
499   .. method:: line(name, x, y, width, height)
500
501      Add and return a ``Line`` control.
502
503
504   .. method:: pushbutton(name, x, y, width, height, attributes,  text, next_control)
505
506      Add and return a ``PushButton`` control.
507
508
509   .. method:: radiogroup(name, x, y, width, height,  attributes, property, text, next_control)
510
511      Add and return a ``RadioButtonGroup`` control.
512
513
514   .. method:: checkbox(name, x, y, width, height,  attributes, property, text, next_control)
515
516      Add and return a ``CheckBox`` control.
517
518
519.. seealso::
520
521   `Dialog Table <http://msdn.microsoft.com/library/en-us/msi/setup/dialog_table.asp>`_
522   `Control Table <http://msdn.microsoft.com/library/en-us/msi/setup/control_table.asp>`_
523   `Control Types <http://msdn.microsoft.com/library/en-us/msi/setup/controls.asp>`_
524   `ControlCondition Table <http://msdn.microsoft.com/library/en-us/msi/setup/controlcondition_table.asp>`_
525   `ControlEvent Table <http://msdn.microsoft.com/library/en-us/msi/setup/controlevent_table.asp>`_
526   `EventMapping Table <http://msdn.microsoft.com/library/en-us/msi/setup/eventmapping_table.asp>`_
527   `RadioButton Table <http://msdn.microsoft.com/library/en-us/msi/setup/radiobutton_table.asp>`_
528
529.. _msi-tables:
530
531Precomputed tables
532------------------
533
534:mod:`msilib` provides a few subpackages that contain only schema and table
535definitions. Currently, these definitions are based on MSI version 2.0.
536
537
538.. data:: schema
539
540   This is the standard MSI schema for MSI 2.0, with the *tables* variable
541   providing a list of table definitions, and *_Validation_records* providing the
542   data for MSI validation.
543
544
545.. data:: sequence
546
547   This module contains table contents for the standard sequence tables:
548   *AdminExecuteSequence*, *AdminUISequence*, *AdvtExecuteSequence*,
549   *InstallExecuteSequence*, and *InstallUISequence*.
550
551
552.. data:: text
553
554   This module contains definitions for the UIText and ActionText tables, for the
555   standard installer actions.
556
557