[Python-checkins] r45839 - python/trunk/Doc/lib/lib.tex python/trunk/Doc/lib/libmsilib.tex
martin.v.loewis
python-checkins at python.org
Mon May 1 18:12:45 CEST 2006
Author: martin.v.loewis
Date: Mon May 1 18:12:44 2006
New Revision: 45839
Added:
python/trunk/Doc/lib/libmsilib.tex (contents, props changed)
Modified:
python/trunk/Doc/lib/lib.tex
Log:
Add msilib documentation.
Modified: python/trunk/Doc/lib/lib.tex
==============================================================================
--- python/trunk/Doc/lib/lib.tex (original)
+++ python/trunk/Doc/lib/lib.tex Mon May 1 18:12:44 2006
@@ -446,6 +446,7 @@
\input{libsunaudio}
\input{windows} % MS Windows ONLY
+\input{libmsilib}
\input{libmsvcrt}
\input{libwinreg}
\input{libwinsound}
Added: python/trunk/Doc/lib/libmsilib.tex
==============================================================================
--- (empty file)
+++ python/trunk/Doc/lib/libmsilib.tex Mon May 1 18:12:44 2006
@@ -0,0 +1,485 @@
+\section{\module{msilib} ---
+ Read and write Microsoft Installer files}
+
+\declaremodule{standard}{msilib}
+ \platform{Windows}
+\modulesynopsis{Creation of Microsoft Installer files, and CAB files.}
+\moduleauthor{Martin v. L\"owis}{martin at v.loewis.de}
+\sectionauthor{Martin v. L\"owis}{martin at v.loewis.de}
+
+\index{msi}
+
+\versionadded{2.5}
+
+The \module{msilib} supports the creation of Microsoft Installer
+(\code{.msi}) files. Because these files often contain an embedded
+``cabinet'' file (\code{.cab}), it also exposes an API to create
+CAB files. Support for reading \code{.cab} files is currently not
+implemented; read support for the \code{.msi} database is possible.
+
+This package aims to provide complete access to all tables in an
+\code{.msi} file, therefore, it is a fairly low-level API. Two
+primary applications of this package are the \module{distutils}
+command \code{bdist_msi}, and the creation of Python installer
+package itself (although that currently uses a different version
+of \code{msilib}).
+
+The package contents can be roughly split into four parts:
+low-level CAB routines, low-level MSI routines, higher-level
+MSI routines, and standard table structures.
+
+\begin{funcdesc}{FCICreate}{cabname, files}
+ Create a new CAB file named \var{cabname}. \var{files} must
+ be a list of tuples, each containing the name of the file on
+ disk, and the name of the file inside the CAB file.
+
+ The files are added to the CAB file in the order they have
+ in the list. All files are added into a single CAB file,
+ using the MSZIP compression algorithm.
+
+ Callbacks to Python for the various steps of MSI creation
+ are currently not exposed.
+\end{funcdesc}
+
+\begin{funcdesc}{UUIDCreate}{}
+ Return the string representation of a new unique identifier.
+ This wraps the Windows API functions \code{UuidCreate} and
+ \code{UuidToString}.
+\end{funcdesc}
+
+\begin{funcdesc}{OpenDatabase}{path, persist}
+ Return a new database object by calling MsiOpenDatabase.
+ \var{path} is the file name of the
+ MSI file; persist can be one of the constants
+ \code{MSIDBOPEN_CREATEDIRECT}, \code{MSIDBOPEN_CREATE},
+ \code{MSIDBOPEN_DIRECT}, \code{MSIDBOPEN_READONLY}, or
+ \code{MSIDBOPEN_TRANSACT}, and may include the flag
+ \code{MSIDBOPEN_PATCHFILE}. See the Microsoft documentation for
+ the meaning of these flags; depending on the flags,
+ an existing database is opened, or a new one created.
+\end{funcdesc}
+
+\begin{funcdesc}{CreateRecord}{count}
+ Return a new record object by calling MSICreateRecord.
+ \var{count} is the number of fields of the record.
+\end{funcdesc}
+
+\begin{funcdesc}{init_database}{name, schema, ProductName, ProductCode, ProductVersion, Manufacturer}
+ Create and return a new database \var{name}, initialize it
+ with \var{schema}, and set the properties \var{ProductName},
+ \var{ProductCode}, \var{ProductVersion}, and \var{Manufacturer}.
+
+ \var{schema} must be a module object containing \code{tables} and
+ \code{_Validation_records} attributes; typically,
+ \module{msilib.schema} should be used.
+
+ The database will contain just the schema and the validation
+ records when this function returns.
+\end{funcdesc}
+
+\begin{funcdesc}{add_data}{database, records}
+ Add all \var{records} to \var{database}. \var{records} should
+ be a list of tuples, each one containing all fields of a record
+ according to the schema of the table. For optional fields,
+ \code{None} can be passed.
+
+ Field values can be int or long numbers, strings, or instances
+ of the Binary class.
+\end{funcdesc}
+
+\begin{classdesc}{Binary}{filename}
+ Represents entries into the Binary table; inserting such
+ an object using \function{add_data} reads the file named
+ \var{filename} into the table.
+\end{classdesc}
+
+\begin{funcdesc}{add_tables}{database, module}
+ Add all table content from \var{module} to \var{database}.
+ \var{module} must contain an attribute \var{tables}
+ listing all tables for which content should be added,
+ and one attribute per table that has the actual content.
+
+ This is typically used to install the sequence
+\end{funcdesc}
+
+\begin{funcdesc}{add_stream}{database, name, path}
+ Add the file \var{path} into the \code{_Stream} table
+ of \var{database}, with the stream name \var{name}.
+\end{funcdesc}
+
+\begin{funcdesc}{gen_uuid}{}
+ Return a new UUID, in the format that MSI typically
+ requires (i.e. in curly braces, and with all hexdigits
+ in upper-case).
+\end{funcdesc}
+
+\begin{seealso}
+ \seetitle[http://msdn.microsoft.com/library/default.asp?url=/library/en-us/devnotes/winprog/fcicreate.asp]{FCICreateFile}{}
+ \seetitle[http://msdn.microsoft.com/library/default.asp?url=/library/en-us/rpc/rpc/uuidcreate.asp]{UuidCreate}{}
+ \seetitle[http://msdn.microsoft.com/library/default.asp?url=/library/en-us/rpc/rpc/uuidtostring.asp]{UuidToString}{}
+\end{seealso}
+
+\subsection{Database Objects\label{database-objects}}
+
+\begin{methoddesc}{OpenView}{sql}
+ Return a view object, by calling MSIDatabaseOpenView.
+ \var{sql} is the SQL statement to execute.
+\end{methoddesc}
+
+\begin{methoddesc}{Commit}{}
+ Commit the changes pending in the current transaction,
+ by calling MSIDatabaseCommit.
+\end{methoddesc}
+
+\begin{methoddesc}{GetSummaryInformation}{count}
+ Return a new summary information object, by calling
+ MsiGetSummaryInformation. \var{count} is the maximum number of
+ updated values.
+\end{methoddesc}
+
+\begin{seealso}
+ \seetitle[http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/msiopenview.asp]{MSIOpenView}{}
+ \seetitle[http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/msidatabasecommit.asp]{MSIDatabaseCommit}{}
+ \seetitle[http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/msigetsummaryinformation.asp]{MSIGetSummaryInformation}{}
+\end{seealso}
+
+\subsection{View Objects\label{view-objects}}
+
+\begin{methoddesc}{Execute}{\optional{params=None}}
+ Execute the SQL query of the view, through MSIViewExecute.
+ \var{params} is an optional record describing actual values
+ of the parameter tokens in the query.
+\end{methoddesc}
+
+\begin{methoddesc}{GetColumnInfo}{kind}
+ Return a record describing the columns of the view, through
+ calling MsiViewGetColumnInfo. \var{kind} can be either
+ \code{MSICOLINFO_NAMES} or \code{MSICOLINFO_TYPES}
+\end{methoddesc}
+
+\begin{methoddesc}{Fetch}{}
+ Return a result record of the query, through calling
+ MsiViewFetch.
+\end{methoddesc}
+
+\begin{methoddesc}{Modify}{kind, data}
+ Modify the view, by calling MsiViewModify. \var{kind}
+ can be one of \code{MSIMODIFY_SEEK}, \code{MSIMODIFY_REFRESH},
+ \code{MSIMODIFY_INSERT}, \code{MSIMODIFY_UPDATE}, \code{MSIMODIFY_ASSIGN},
+ \code{MSIMODIFY_REPLACE}, \code{MSIMODIFY_MERGE}, \code{MSIMODIFY_DELETE},
+ \code{MSIMODIFY_INSERT_TEMPORARY}, \code{MSIMODIFY_VALIDATE},
+ \code{MSIMODIFY_VALIDATE_NEW}, \code{MSIMODIFY_VALIDATE_FIELD}, or
+ \code{MSIMODIFY_VALIDATE_DELETE}.
+
+ \var{data} must be a record describing the new data.
+\end{methoddesc}
+
+\begin{methoddesc}{Close}{}
+ Close the view, through MsiViewClose.
+\end{methoddesc}
+
+\begin{seealso}
+ \seetitle[http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/msiviewexecute.asp]{MsiViewExecute}{}
+ \seetitle[http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/msiviewgetcolumninfo.asp]{MSIViewGetColumnInfo}{}
+ \seetitle[http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/msiviewfetch.asp]{MsiViewFetch}{}
+ \seetitle[http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/msiviewmodify.asp]{MsiViewModify}{}
+ \seetitle[http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/msiviewclose.asp]{MsiViewClose}{}
+\end{seealso}
+
+\subsection{Summary Information Objects\label{summary-objects}}
+
+\begin{methoddesc}{GetProperty}{field}
+ Return a property of the summary, through MsiSummaryInfoGetProperty.
+ \var{field} is the name of the property, and can be one of the
+ constants
+ \code{PID_CODEPAGE}, \code{PID_TITLE}, \code{PID_SUBJECT},
+ \code{PID_AUTHOR}, \code{PID_KEYWORDS}, \code{PID_COMMENTS},
+ \code{PID_TEMPLATE}, \code{PID_LASTAUTHOR}, \code{PID_REVNUMBER},
+ \code{PID_LASTPRINTED}, \code{PID_CREATE_DTM}, \code{PID_LASTSAVE_DTM},
+ \code{PID_PAGECOUNT}, \code{PID_WORDCOUNT}, \code{PID_CHARCOUNT},
+ \code{PID_APPNAME}, or \code{PID_SECURITY}.
+\end{methoddesc}
+
+\begin{methoddesc}{GetPropertyCount}{}
+ Return the number of summary properties, through
+ MsiSummaryInfoGetPropertyCount.
+\end{methoddesc}
+
+\begin{methoddesc}{SetProperty}{field, value}
+ Set a property through MsiSummaryInfoSetProperty. \var{field}
+ can have the same values as in \method{GetProperty}, \var{value}
+ is the new value of the property. Possible value types are integer
+ and string.
+\end{methoddesc}
+
+\begin{methoddesc}{Persist}{}
+ Write the modified properties to the summary information stream,
+ using MsiSummaryInfoPersist.
+\end{methoddesc}
+
+\begin{seealso}
+ \seetitle[http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/msisummaryinfogetproperty.asp]{MsiSummaryInfoGetProperty}{}
+ \seetitle[http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/msisummaryinfogetpropertycount.asp]{MsiSummaryInfoGetPropertyCount}{}
+ \seetitle[http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/msisummaryinfosetproperty.asp]{MsiSummaryInfoSetProperty}{}
+ \seetitle[http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/msisummaryinfopersist.asp]{MsiSummaryInfoPersist}{}
+\end{seealso}
+
+\subsection{Record Objects\label{record-objects}}
+
+\begin{methoddesc}{GetFieldCount}{}
+ Return the number of fields of the record, through MsiRecordGetFieldCount.
+\end{methoddesc}
+
+\begin{methoddesc}{SetString}{field, value}
+ Set \var{field} to \var{value} through MsiRecordSetString.
+ \var{field} must be an integer; \var{value} a string.
+\end{methoddesc}
+
+\begin{methoddesc}{SetStream}{field, value}
+ Set \var{field} to the contents of the file named \var{value},
+ through MsiRecordSetStream.
+ \var{field} must be an integer; \var{value} a string.
+\end{methoddesc}
+
+\begin{methoddesc}{SetInteger}{field, value}
+ Set \var{field} to \var{value} through MsiRecordSetInteger.
+ Both \var{field} and \var{value} must be an integers.
+\end{methoddesc}
+
+\begin{methoddesc}{ClearData}{}
+ Set all fields of the record to 0, through MsiRecordClearData.
+\end{methoddesc}
+
+\begin{seealso}
+ \seetitle[http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/msirecordgetfieldcount.asp]{MsiRecordGetFieldCount}{}
+ \seetitle[http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/msirecordsetstring.asp]{MsiRecordSetString}{}
+ \seetitle[http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/msirecordsetstream.asp]{MsiRecordSetStream}{}
+ \seetitle[http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/msirecordsetinteger.asp]{MsiRecordSetInteger}{}
+ \seetitle[http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/msirecordclear.asp]{MsiRecordClear}{}
+\end{seealso}
+
+\subsection{Errors\label{msi-errors}}
+
+All wrappers around MSI functions raise \exception{MsiError};
+the string inside the exception will contain more detail.
+
+\subsection{CAB Objects\label{cab}}
+
+\begin{classdesc}{CAB}{name}
+ The class \class{CAB} represents a CAB file. During MSI construction,
+ files will be added simultaneously to the \code{Files} table, and
+ to a CAB file. Then, when all files have been added, the CAB file
+ can be written, then added to the MSI file.
+
+ \var{name} is the name of the CAB file in the MSI file.
+\end{classdesc}
+
+\begin{methoddesc}[CAB]{append}{full, logical}
+ Add the file with the pathname \var{full} to the CAB file,
+ under the name \var{logical}. If there is already a file
+ named \var{logical}, a new file name is created.
+
+ Return the index of the file in the CAB file, and the
+ new name of the file inside the CAB file.
+\end{methoddesc}
+
+\begin{methoddesc}[CAB]{append}{database}
+ Generate a CAB file, add it as a stream to the MSI file,
+ put it into the \code{Media} table, and remove the generated
+ file from the disk.
+\end{methoddesc}
+
+\subsection{Directory Objects\label{msi-directory}}
+
+\begin{classdesc}{Directory}{database, cab, basedir, physical,
+ logical, default, component, \optional{flags}}
+ Create a new directory in the Directory table. There is a current
+ component at each point in time for the directory, which is either
+ explicitly created through start_component, or implicitly when files
+ are added for the first time. Files are added into the current
+ component, and into the cab file. To create a directory, a base
+ directory object needs to be specified (can be None), the path to
+ the physical directory, and a logical directory name. Default
+ specifies the DefaultDir slot in the directory table. componentflags
+ specifies the default flags that new components get.
+\end{classdesc}
+
+\begin{methoddesc}[Directory]{start_component}{\optional{component\optional{,
+ feature\optional{, flags\optional{, keyfile\optional{, uuid}}}}}}
+ Add an entry to the Component table, and make this component the
+ current for this directory. If no component name is given, the
+ directory name is used. If no feature is given, the current feature
+ is used. If no flags are given, the directory's default flags are
+ used. If no keyfile is given, the KeyPath is left null in the
+ Component table.
+\end{methoddesc}
+
+\begin{methoddesc}[Directory]{add_file}{file\optional{, src\optional{,
+ version\optional{, language}}}}
+ Add a file to the current component of the directory, starting a new
+ one one if there is no current component. By default, the file name
+ in the source and the file table will be identical. If the src file
+ is specified, it is interpreted relative to the current
+ directory. Optionally, a version and a language can be specified for
+ the entry in the File table.
+\end{methoddesc}
+
+\begin{methoddesc}[Directory]{glob}{pattern\optional{, exclude}}
+ Add a list of files to the current component as specified in the glob
+ pattern. Individual files can be excluded in the exclude list.
+\end{methoddesc}
+
+\begin{methoddesc}[Directory]{remove_pyc}{}
+ Remove .pyc/.pyo files on uninstall
+\end{methoddesc}
+
+\begin{seealso}
+ \seetitle[http://msdn.microsoft.com/library/en-us/msi/setup/directory_table.asp]{Directory Table}{}
+ \seetitle[http://msdn.microsoft.com/library/en-us/msi/setup/file_table.asp]{File Table}{}
+ \seetitle[http://msdn.microsoft.com/library/en-us/msi/setup/component_table.asp]{Component Table}{}
+ \seetitle[http://msdn.microsoft.com/library/en-us/msi/setup/featurecomponents_table.asp]{FeatureComponents Table}{}
+\end{seealso}
+
+
+\subsection{Features\label{features}}
+
+\begin{classdesc}{Feature}{database, id, title, desc, display\optional{,
+ level=1\optional{, parent\optional\{, directory\optional{,
+ attributes=0}}}}
+
+ Add a new record to the \code{Feature} table, using the values
+ \var{id}, \var{parent.id}, \var{title}, \var{desc}, \var{display},
+ \var{level}, \var{directory}, and \var{attributes}. The resulting
+ feature object can be passed to the \method{start_component} method
+ of \class{Directory}.
+\end{classdesc}
+
+\begin{methoddesc}[Feature]{set_current}{}
+ Make this feature the current feature of \module{msilib}.
+ New components are automatically added to the default feature,
+ unless a feature is explicitly specified.
+\end{methoddesc}
+
+\begin{seealso}
+ \seetitle[http://msdn.microsoft.com/library/en-us/msi/setup/feature_table.asp]{Feature Table}{}
+\end{seealso}
+
+\subsection{GUI classes\label{msi-gui}}
+
+\module{msilib} provides several classes that wrap the GUI tables in
+an MSI database. However, no standard user interface is provided; use
+\module{bdist_msi} to create MSI files with a user-interface for
+installing Python packages.
+
+\begin{classdesc}{Control}{dlg, name}
+ Base class of the dialog controls. \var{dlg} is the dialog object
+ the control belongs to, and \var{name} is the control's name.
+\end{classdesc}
+
+\begin{methoddesc}[Control]{event}{event, argument\optional{,
+ condition = ``1''\optional{, ordering}}}
+
+ Make an entry into the \code{ControlEvent} table for this control.
+\end{methoddesc}
+
+\begin{methoddesc}[Control]{mapping}{event, attribute}
+ Make an entry into the \code{EventMapping} table for this control.
+\end{methoddesc}
+
+\begin{methoddesc}[Control]{condition}{action, condition}
+ Make an entry into the \code{ControlCondition} table for this control.
+\end{methoddesc}
+
+
+\begin{classdesc}{RadioButtonGroup}{dlg, name, property}
+ Create a radio button control named \var{name}. \var{property}
+ is the installer property that gets set when a radio button
+ is selected.
+\end{classdesc}
+
+\begin{methoddesc}[RadioButtonGroup]{add}{name, x, y, width, height, text
+ \optional{, value}}
+ Add a radio button named \var{name} to the group, at the
+ coordinates \var{x}, \var{y}, \var{width}, \var{height}, and
+ with the label \var{text}. If \var{value} is omitted, it
+ defaults to \var{name}.
+\end{methoddesc}
+
+\begin{classdesc}{Dialog}{db, name, x, y, w, h, attr, title, first,
+ default, cancel}
+ Return a new Dialog object. An entry in the \code{Dialog} table
+ is made, with the specified coordinates, dialog attributes, title,
+ name of the first, default, and cancel controls.
+\end{classdesc}
+
+\begin{methoddesc}[Dialog]{control}{name, type, x, y, width, height,
+ attributes, property, text, control_next, help}
+ Return a new Control object. An entry in the \code{Control} table
+ is made with the specified parameters.
+
+ This is a generic method; for specific types, specialized methods
+ are provided.
+\end{methoddesc}
+
+
+\begin{methoddesc}[Dialog]{text}{name, x, y, width, height, attributes, text}
+ Add and return a \code{Text} control.
+\end{methoddesc}
+
+\begin{methoddesc}[Dialog]{bitmap}{name, x, y, width, height, text}
+ Add and return a \code{Bitmap} control.
+\end{methoddesc}
+
+\begin{methoddesc}[Dialog]{line}{name, x, y, width, height}
+ Add and return a \code{Line} control.
+\end{methoddesc}
+
+\begin{methoddesc}[Dialog]{pushbutton}{name, x, y, width, height, attributes,
+ text, next_control}
+ Add and return a \code{PushButton} control.
+\end{methoddesc}
+
+\begin{methoddesc}[Dialog]{radiogroup}{name, x, y, width, height,
+ attributes, property, text, next_control}
+ Add and return a \code{RadioButtonGroup} control.
+\end{methoddesc}
+
+\begin{methoddesc}[Dialog]{checkbox}{name, x, y, width, height,
+ attributes, property, text, next_control}
+ Add and return a \code{CheckBox} control.
+\end{methoddesc}
+
+\begin{seealso}
+ \seetitle[http://msdn.microsoft.com/library/en-us/msi/setup/dialog_table.asp]{Dialog Table}{}
+ \seetitle[http://msdn.microsoft.com/library/en-us/msi/setup/control_table.asp]{Control Table}{}
+ \seetitle[http://msdn.microsoft.com/library/en-us/msi/setup/controls.asp]{Control Types}{}
+ \seetitle[http://msdn.microsoft.com/library/en-us/msi/setup/controlcondition_table.asp]{ControlCondition Table}{}
+ \seetitle[http://msdn.microsoft.com/library/en-us/msi/setup/controlevent_table.asp]{ControlEvent Table}{}
+ \seetitle[http://msdn.microsoft.com/library/en-us/msi/setup/eventmapping_table.asp]{EventMapping Table}{}
+ \seetitle[http://msdn.microsoft.com/library/en-us/msi/setup/radiobutton_table.asp]{RadioButton Table}{}
+\end{seealso}
+
+\subsection{Precomputed tables\label{msi-tables}}
+
+\module{msilib} provides a few subpackages that contain
+only schema and table definitions. Currently, these definitions
+are based on MSI version 2.0.
+
+\begin{datadesc}{schema}
+ This is the standard MSI schema for MSI 2.0, with the
+ \var{tables} variable providing a list of table definitions,
+ and \var{_Validation_records} providing the data for
+ MSI validation.
+\end{datadesc}
+
+\begin{datadesc}{sequence}
+ This module contains table contents for the standard sequence
+ tables: \var{AdminExecuteSequence}, \var{AdminUISequence},
+ \var{AdvtExecuteSequence}, \var{InstallExecuteSequence}, and
+ \var{InstallUISequence}.
+\end{datadesc}
+
+\begin{datadesc}{text}
+ This module contains definitions for the UIText and ActionText
+ tables, for the standard installer actions.
+\end{datadesc}
\ No newline at end of file
More information about the Python-checkins
mailing list