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
  15 The :mod:`msilib` supports the creation of Microsoft Installer (``.msi``) files.
  16 Because these files often contain an embedded "cabinet" file (``.cab``), it also
  17 exposes an API to create CAB files. Support for reading ``.cab`` files is
  18 currently not implemented; read support for the ``.msi`` database is possible.
  19
  20 This package aims to provide complete access to all tables in an ``.msi`` file,
  21 therefore, it is a fairly low-level API. Two primary applications of this
  22 package are the :mod:`distutils` command ``bdist_msi``, and the creation of
  23 Python installer package itself (although that currently uses a different
  24 version of ``msilib``).
  25
  26 The package contents can be roughly split into four parts: low-level CAB
  27 routines, low-level MSI routines, higher-level MSI routines, and standard table
  28 structures.
  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
 132 Database 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
 163 View 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
 213 Summary 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
 256 Record 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
 311 Errors
 312 ------
 313
 314 All wrappers around MSI functions raise :exc:`MsiError`; the string inside the
 315 exception will contain more detail.
 316
 317
 318 .. _cab:
 319
 320 CAB 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
 352 Directory 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
 406 Features
 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
 431 GUI classes
 432 -----------
 433
 434 :mod:`msilib` provides several classes that wrap the GUI tables in an MSI
 435 database. However, no standard user interface is provided; use :mod:`bdist_msi`
 436 to 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
 531 Precomputed tables
 532 ------------------
 533
 534 :mod:`msilib` provides a few subpackages that contain only schema and table
 535 definitions. 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