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