5.3 Creating Windows Installers

Executable installers are the natural format for binary distributions
on Windows. They display a nice graphical user interface, display
some information about the module distribution to be installed taken
from the metadata in the setup script, let the user select a few
options, and start or cancel the installation.

Since the metadata is taken from the setup script, creating Windows
installers is usually as easy as running:

python setup.py bdist_wininst

or the bdist command with the --formats option:

python setup.py bdist --formats=wininst

If you have a pure module distribution (only containing pure Python
modules and packages), the resulting installer will be version
independent and have a name like foo-1.0.win32.exe. These
installers can even be created on Unix or Mac OS platforms.

If you have a non-pure distribution, the extensions can only be
created on a Windows platform, and will be Python version dependent.
The installer filename will reflect this and now has the form
foo-1.0.win32-py2.0.exe. You have to create a separate installer
for every Python version you want to support.

The installer will try to compile pure modules into bytecode after
installation on the target system in normal and optimizing mode. If
you don't want this to happen for some reason, you can run the
bdist_wininst command with the
--no-target-compile and/or the
--no-target-optimize option.

By default the installer will display the cool ``Python Powered'' logo
when it is run, but you can also supply your own bitmap which must be
a Windows .bmp file with the --bitmap option.

The installer will also display a large title on the desktop
background window when it is run, which is constructed from the name
of your distribution and the version number. This can be changed to
another text by using the --title option.

The installer file will be written to the ``distribution directory''
-- normally dist/, but customizable with the
--dist-dir option.

5.3.1 The Postinstallation script

Starting with Python 2.3, a postinstallation script can be specified
which the --install-script option. The basename of the
script must be specified, and the script filename must also be listed
in the scripts argument to the setup function.

This script will be run at installation time on the target system
after all the files have been copied, with argv[1] set to
-install, and again at uninstallation time before the
files are removed with argv[1] set to -remove.

The installation script runs embedded in the windows installer, every
output (sys.stdout, sys.stderr) is redirected into a
buffer and will be displayed in the GUI after the script has finished.

Some functions especially useful in this context are available as
additional built-in functions in the installation script.

directory_created(

path)

file_created(

path)

These functions should be called when a directory or file is created
by the postinstall script at installation time. It will register
path with the uninstaller, so that it will be removed when the
distribution is uninstalled. To be safe, directories are only removed
if they are empty.

get_special_folder_path(

csidl_string)

This function can be used to retrieve special folder locations on
Windows like the Start Menu or the Desktop. It returns the full
path to the folder. csidl_string must be one of the following
strings:

This function creates a shortcut.
target is the path to the program to be started by the shortcut.
description is the description of the shortcut.
filename is the title of the shortcut that the user will see.
arguments specifies the command line arguments, if any.
workdir is the working directory for the program.
iconpath is the file containing the icon for the shortcut,
and iconindex is the index of the icon in the file
iconpath. Again, for details consult the Microsoft
documentation for the IShellLink interface.