[r680]: trunk / py2exe / docs / py2exe.txt  Maximize  Restore  History

Download this file

459 lines (317 with data), 17.4 kB

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
.. image:: py2exe.jpg
:align: center
.. _license: LICENSE.txt
.. _distutils: http://www.python.org/doc/current/dist/
.. _setup-script: http://www.python.org/doc/current/dist/setup-script.html
.. _py2exe-0.6.9.win32-py2.3.exe: http://prdownloads.sourceforge.net/py2exe/py2exe-0.6.9.win32-py2.3.exe?download
.. _py2exe-0.6.9.win32-py2.4.exe: http://prdownloads.sourceforge.net/py2exe/py2exe-0.6.9.win32-py2.4.exe?download
.. _py2exe-0.6.9.win32-py2.5.exe: http://prdownloads.sourceforge.net/py2exe/py2exe-0.6.9.win32-py2.5.exe?download
.. _py2exe-0.6.9.win64-py2.5.amd64.msi: http://prdownloads.sourceforge.net/py2exe/py2exe-0.6.9.win64-py2.5.amd64.msi?download
.. _py2exe-0.6.9.win32-py2.6.exe: http://prdownloads.sourceforge.net/py2exe/py2exe-0.6.9.win32-py2.6.exe?download
.. _py2exe-0.6.9.win64-py2.6.amd64.exe: http://prdownloads.sourceforge.net/py2exe/py2exe-0.6.9.win64-py2.6.amd64.exe?download
.. _py2exe-0.6.9.win32-py2.7.exe: http://prdownloads.sourceforge.net/py2exe/py2exe-0.6.9.win32-py2.7.exe?download
.. _py2exe-0.6.9.win64-py2.7.amd64.exe: http://prdownloads.sourceforge.net/py2exe/py2exe-0.6.9.win64-py2.7.amd64.exe?download
.. _WIKI: http://www.py2exe.org/
.. _SourceForge: http://sourceforge.net/projects/py2exe/
.. _announcement: http://py2exe.svn.sourceforge.net/viewvc/*checkout*/py2exe/trunk/py2exe/ANNOUNCE
.. _ChangeLog: http://py2exe.svn.sourceforge.net/viewvc/*checkout*/py2exe/trunk/py2exe/ChangeLog
.. _`py2exe mailing list`: https://lists.sourceforge.net/lists/listinfo/py2exe-users
.. _gmane: http://www.gmane.org/
.. _http: http://news.gmane.org/gmane.comp.python.py2exe/
.. _nntp: nntp://news.gmane.org/gmane.comp.python.py2exe
.. _sample_xref: http://www.py2exe.org/sample_xref.html
.. _MPL: http://www.opensource.org/licenses/mozilla1.1.php
.. _Mozilla Public License Version 1.1: http://www.mozilla.org/MPL/MPL-1.1.html
py2exe - convert python scripts into standalone windows programs
================================================================
Copyright (c) 2001-2008 Thomas Heller, Mark Hammond, Joachim Bauch,
Jimmy Retzlaff, and contributors.
Abstract
--------
**py2exe** is a Python distutils_ extension which converts python
scripts into executable windows programs, able to run without
requiring a python installation.
It has been used to create wxPython, Tkinter, Pmw, PyGTK, pygame,
win32com client and server modules and other standalone programs.
**py2exe** is distributed under an open-source license_. It contains
code originally written by Joachim Bauch, released under the `Mozilla
Public License Version 1.1`_
News
----
**py2exe 0.6.9 released (2008/11/15)**
Binaries for Python 2.6 and Python 2.7.
Fixed a modulefinder crash on certain relative imports.
Changed the py2exe\samples\singlefile\gui\test_wx.py sample to use the wx package instead of the old wxPython package.
Copy the manifest, if any, from the 'template' into the targets to ensure embedded assembly references, as required for python 2.6 based apps, are copied.
Allow each target to specify Vista User Access Control flags. For example, specifying 'uac_execution_info="requireAdministrator"' would force elevation for the final executable.
**py2exe 0.6.8 released (2008/06/15)**
Support for relative imports.
Fix MemoryLoadLibrary to handle loading function addresses by ordinal numbers. Patch and test by Matthias Miller.
Using the options compressed=1, bundle_files=3, and zipfile=None at the same time now works; patch from Alexey Borzenkov.
Allow renaming of single-executable files; patch from Alexey Borzenkov.
Embedding icon resources into the image now works correctly even for ico files containing multiple images.
pyd files from different packages with the same filename no longer conflict. Patch from Grant Edwards.
There are new samples for the 'typelibs' support, including the new option of pre-generating a typelib and specifying the file as an input to py2exe.
The test suite is now included in the source distribution.
**py2exe 0.6.6 released (2006/12/30)**
Better support for Python 2.5.
Experimental support for 64-bit builds of Python on win64.
Better ISAPI support.
New samples for ISAPI and COM servers.
Support for new "command-line styles" when building Windows services.
**py2exe 0.6.5 released (2006/03/20)**
Fixed modulefinder / mf related bugs introduced in 0.6.4. This
will be most evident when working with things like
win32com.shell and xml.xpath.
Files no longer keep read-only attributes when they are copied
as this was causing problems with the copying of some MS DLLs.
**py2exe 0.6.4 released (2006/02/13)**
New skip-archive option which copies the Python bytecode files
directly into the dist directory and subdirectories - no
archive is used.
An experimental new custom-boot-script option which allows a boot
script to be specified (e.g., --custom-boot-script=cbs.py) which can
do things like installing a customized stdout blackhole. See
py2exe's boot_common.py for examples of what can be done. The custom
boot script is executed during startup of the executable immediately
after boot_common.py is executed.
Thomas Heller's performance improvements for finding needed
modules.
Mark Hammond's fix for thread-state errors when a py2exe
created executable tries to use a py2exe created COM DLL.
**py2exe 0.6.3 released (2005/10/06)**
dll-excludes is now available on the command line and can be used to
exclude msvcr71.dll and w9xpopen.exe.
A bug that caused py2exe to crash when copying extension modules in
packages was fixed.
**py2exe 0.6.2 released (2005/09/07)**
Several important bugfixes.
For Python 2.4, MSVCR71.dll is now copied into the dist directory.
This dll cannot be bundled into the executable, sorry.
**py2exe 0.6.1 released (2005/09/05)**
Can now create single file executables.
Documentation
-------------
You are reading it ;-). A lot of other, user supplied documentation
is in the WIKI_.
Please don't mail me directly about py2exe, please use the `py2exe
mailing list`_, which is also available on gmane_, via http_ and nntp_.
What's new in py2exe 0.6
------------------------
- The new ``--bundle <level>`` or ``-b <level>`` command line switch
instructs py2exe to bundle needed dlls and pyds into the library file
or the executable itself, instead of simply collecting them in the
dist directory. Not only does this create less files you have to
distribute, it also allows Python inprocess COM servers to run
completely isolated from other Python interpreters in the same
process. See below for more details.
- To prevent unicode encoding error, py2exe now by default includes the
``codecs`` module and the ``encodings`` package. If you are sure your
program never implicitely or explicitely has to convert between
unicode and ascii strings this can be prevented by the ``--ascii`` or
``-a`` command line switch.
- It is no longer required to clean the build directory from time to
time to prevent some strange errors.
- Several patches have been integrated (if you miss a patch you sent me,
please send it again. It can be that I missed some mails).
The announcement_, and the ChangeLog_.
Some comments about py2exe 0.5, still valid for 0.6
---------------------------------------------------
The documentation is still to be written, but there is quite some info
available in the included samples, and in the WIKI_ pages. Thanks to
everyone who contributed.
Python 2.3 or 2.4 is required, because the new zipimport feature is
used. The zipimport mechanism is able to handle the early imports of
the warnings and also the encodings module which is done by Python.
Using py2exe
------------
Assuming you have written a python script ``myscript.py`` which you
want to convert into an executable windows program, able to run on
systems without a python installation. If you don't already have
written a *distutils* setup-script_, write one, and insert the
statement ``import py2exe`` before the call to the setup function::
# setup.py
from distutils.core import setup
import py2exe
setup(console=["myscript.py"])
Running ::
python setup.py py2exe --help
will display all available command-line flags to the **py2exe**
command.
Now you can call the setup script like in this way::
python setup.py py2exe
and a subdirectory ``dist`` will be created, containing the files
``myscript.exe``, ``python23.dll``, and ``library.zip``. If your script
uses compiled C extension modules, they will be copied here as well,
also all dlls needed at runtime (except the system dlls).
These files include everything that is needed for your program, and
you should distribute the whole directory contents.
The above setup script creates a console program, if you want a GUI
program without the console window, simply replace
``console=["myscript.py"]`` with ``windows=["myscript.py"]``.
**py2exe** can create more than one exe file in one run, this is
useful if you have a couple of related scripts. Pass a list of all
scripts in the ``console`` and/or ``windows`` keyword argument.
Specifying additional files
---------------------------
Some applications need additional files at runtime, like configuration
files, fonts, or bitmaps.
**py2exe** can copy these files into subdirectories of ``dist`` if they
are specified in the setup script with the ``data_files``
option. ``data_files`` should contain a sequence of ``(target-dir,
files)`` tuples, where files is a sequence of files to be copied.
Here's an example::
# setup.py
from distutils.core import setup
import glob
import py2exe
setup(console=["myscript.py"],
data_files=[("bitmaps",
["bm/large.gif", "bm/small.gif"]),
("fonts",
glob.glob("fonts\\*.fnt"))],
)
This would create a subdirectory ``dist\bitmaps``, containing the two
``.gif`` files, and a subdirectory ``dist\fonts``, containing all the
``.fnt`` files.
Windows NT services
-------------------
You can build Windows NT services by passing a ``service`` keyword
argument to the ``setup`` function, the value must be a list of Python
module names containing a service class (identified by the ``_svc_name_``
attribute)::
# setup.py
from distutils.core import setup
import py2exe
setup(service=["MyService"])
Optionally, you can specify a 'cmdline-style' attribute to py2exe, with
valid values being 'py2exe' (the default), 'pywin32' or 'custom'. 'py2exe'
specifies the traditional command-line always supported by py2exe. 'pywin32'
supports the exact same command-line arguments as pywin32 supports (ie, the
same arguments supported when running the service from the .py file.)
'custom' means that your module is expected to provide a 'HandleCommandLine'
function which is responsible for all command-line handling.
The built service executables are able to install and remove
themselves by calling them with certain command line flags, run the
exe with the ``-help`` argument to find out more.
COM servers
-----------
COM servers are built by passing a ``com_server`` keyword argument to
the setup function, again the value must be a list of Python module
names containing one or more COM server classes (identified by their
``_reg_progid_`` attribute)::
# setup.py
from distutils.core import setup
import py2exe
setup(com_server=["win32com.server.interp"])
By default both DLL and EXE servers are built, you should simply
delete those you don't need.
The bundle option
-----------------
By default py2exe creates these files in the ``dist`` directory which
you must deploy:
1. One (or more) .exe files
2. The python##.dll
3. A couple of .pyd files which are the compiled extensions that the
exe files need, plus any other .dll files that the extensions need.
4. A ``library.zip`` file which contains the compiled pure python
modules as .pyc or .pyo files (if you have specified 'zipfile=None'
in the setup script this file is append to the .exe files and not
present in the dist-directory).
The ``--bundle <level>`` or ``-b <level>`` command line switch will
create less files because binary extensions, runtime dlls, and even
the Python-dll itself is bundled into the executable itself, or inside
the library-archive if you prefer that.
The bundled pyds and dlls are *never* unpacked to the file system,
instead they are transparently loaded at runtime from the bundle. The
resulting executable *appears* to be statically linked.
Specifying a level of ``2`` includes the .pyd and .dll files into the
zip-archive or the executable. Thus, the dist directory will contain
your exe file(s), the library.zip file (if you haven't specified
'zipfile=None'), and the python dll. The advantage of this scheme is
that the application can still load extension modules from the file
system if you extend ``sys.path`` at runtime.
Using a level of ``1`` includes the .pyd and .dll files into the
zip-archive or the executable itself, and does the same for
pythonXY.dll. The advantage is that you only need to distribute one
file per exe, which will however be quite large. Another advantage is
that inproc COM servers will run completely isolated from other Python
interpreters in the same exe. The disadvantage of this scheme is that
it is impossible to load other extensions from the file system, the
application will crash with a fatal Python error if you try this. I
have still to find a way to prevent this and raise an ImportError
instead - any suggestions how this can be implemented would be very
welcome.
The bundle-option has been tested with some popular extensions, but of
course there's no guarantee that any extension will work in bundled
form - be sure to test the executable (which you should do anyway).
The bundle option achieves its magic by code which emulates the
Windows LoadLibrary api, it is compiled into the exe-stubs that py2exe
uses. For experimentation, it is also installed as a normal Python
extension ``_memimporter.pyd`` in the ``lib\site-packages`` directory.
The Python module ``zipextimported.py`` in the same directory
demonstrates how it can be used to load binary extensions from
zip-files.
Samples
-------
The ``py2exe``-installer installs some examples into the
``lib\site-packages\py2exe\samples`` directory, demonstrating several
simple and advances features.
The ``singlefile`` subdirectory contains two samples which are built
as single-file executables: a trivial wxPython gui program, and a
pywin32 dll COM server module.
How does it work?
-----------------
**py2exe** uses python's ``modulefinder`` to examine your script and
find all python and extension modules needed to run it. Pure python
modules are compiled into ``.pyc`` or ``.pyo`` files in a temporary
directory. Compiled extension modules (``.pyd``) are also found and
parsed for binary dependencies.
A zip-compatible archive is built, containing all python files from
this directory. Your main script is inserted as a resource into a
custom embedded python interpreter supplied with py2exe, and the
zip-archive is installed as the only item on ``sys.path``.
In simple cases, only ``pythonxx.dll`` is needed in addition to
``myscript.exe``. If, however, your script needs extension modules,
unfortunately those cannot be included or imported from the
zip-archive, so they are needed as separate files (and are copied into
the ``dist`` directory).
*Attention*: **py2exe** tries to track down all binary dependencies
for all pyds and dlls copied to the dist directory recursively, and
copies all these dependend files into the dist directory. **py2exe**
has a builtin list of some system dlls which are not copied, but this
list can never be complete.
Installing py2exe
-----------------
Download and run the installer py2exe-0.6.9.win32-py2.3.exe_ (for
Python 2.3), py2exe-0.6.9.win32-py2.4.exe_ (for
Python 2.4), py2exe-0.6.9.win32-py2.5.exe_ (for Python 2.5),
py2exe-0.6.9.win64-py2.5.amd64.msi_ (for 64-bit Python 2.5),
py2exe-0.6.9.win32-py2.6.exe_ (for Python 2.6),
py2exe-0.6.9.win64-py2.6.amd64.exe_ (for 64-bit Python 2.6),
py2exe-0.6.9.win32-py2.7.exe_ (for Python 2.7), or
py2exe-0.6.9.win64-py2.7.amd64.exe_ (for 64-bit Python 2.7).
This installs **py2exe** together with some samples, the samples are in
the ``lib\site-packages\py2exe\samples`` subdirectory.
For **Windows 95/98/Me**, you need the *Microsoft Layer for Unicode on
Windows 95/98/ME Systems (MSLU)* dll from here_ (Internet Explorer is
required to download it: Scroll down to the Win95/98/Me section).
Download and run the self-extracting ``unicows.exe`` file, and copy
the unpacked ``unicows.dll`` file in the directory which contains your
``python.exe``. Note that this is only needed on the machine where
you want to build executables with **py2exe**, it is not required on
the machine where you want to run the created programs.
If you use ``py2exe`` to build COM clients or servers, win32all build
163 (or later) is strongly recommened - it contains much better support
for frozen executables.
.. _here: http://www.microsoft.com/msdownload/platformsdk/sdkupdate/psdkredist.htm
Project information
-------------------
The project is hosted at |SourceForge|_.
.. |SourceForge| image::
http://sourceforge.net/sflogo.php?group_id=15583&;type=1
:alt: SourceForge Logo
:align: middle
:class: borderless
:width: 88
:height: 31