/Doc/library/msilib.rst

http://unladen-swallow.googlecode.com/ · ReStructuredText · 557 lines · 319 code · 238 blank · 0 comment · 0 complexity · b1a498a517c78d1fc142530c15c59249 MD5 · raw file

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