Doc/library/msilib.rst

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