Add an option to zipapp to produce a Windows executable

[pfmoore]

BPO	28247
Nosy	@brettcannon, @pfmoore, @tjguk, @zware, @serhiy-storchaka, @eryksun, @zooba, @csabella, @miss-islington
PRs	bpo-28247: Document Windows executable creation in zipapp #6158 [3.7] bpo-28247: Document Windows executable creation in zipapp (GH-6158) #6163 [3.6] bpo-28247: Document Windows executable creation in zipapp (GH-6158) #6164
Files	zipapp-doc.patch

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = 'https://github.com/pfmoore'
closed_at = <Date 2018-03-21.12:43:27.965>
created_at = <Date 2016-09-22.13:55:29.386>
labels = ['3.8', 'type-feature', '3.7', 'docs']
title = 'Add an option to zipapp to produce a Windows executable'
updated_at = <Date 2018-11-24.09:36:10.128>
user = 'https://github.com/pfmoore'

bugs.python.org fields:

activity = <Date 2018-11-24.09:36:10.128>
actor = 'paul.moore'
assignee = 'paul.moore'
closed = True
closed_date = <Date 2018-03-21.12:43:27.965>
closer = 'cheryl.sabella'
components = ['Documentation']
creation = <Date 2016-09-22.13:55:29.386>
creator = 'paul.moore'
dependencies = []
files = ['44863']
hgrepos = []
issue_num = 28247
keywords = ['patch']
message_count = 16.0
messages = ['277224', '277228', '277229', '277231', '277524', '277525', '277606', '277638', '314135', '314137', '314157', '314171', '314172', '314173', '330366', '330374']
nosy_count = 10.0
nosy_names = ['brett.cannon', 'paul.moore', 'tim.golden', 'donmez', 'zach.ware', 'serhiy.storchaka', 'eryksun', 'steve.dower', 'cheryl.sabella', 'miss-islington']
pr_nums = ['6158', '6163', '6164']
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue28247'
versions = ['Python 3.7', 'Python 3.8']

[pfmoore]

The zipapp module allows users to bundle their application as a single file "executable". On Windows, the file is given a ".pyz" extension which is associated with the Python launcher. However, this approach is not always equivalent to a native executable (see http://paul-moores-notes.readthedocs.io/en/latest/wrappers.html for more details).

I suggest adding an option to zipapp that prepends a small executable to the zipapp that uses the Python C API to launch the application. A prototype implementation (zastub) is available at https://github.com/pfmoore/pylaunch.

If this seems reasonable, I'll work up a full patch.

[serhiy-storchaka]

Why not just change the extension to cmd and add the following line at the start?

@python -x "%0" %*

[pfmoore]

(1) It starts an extra process (unless you're running the application from cmd.exe) and (2) in some cases, the system won't recognise a cmd file as an executable. For a simple example,

t.cmd:

@echo Hello from t

example.py:

from subprocess import run
run(["t")]

If you run example.py you get "FileNotFoundError: [WinError 2] The system cannot find the file specified".

[eryksun]

Specifically, while CreateProcess does execute batch scripts via the %ComSpec% interpreter, the only extension it infers is ".exe". To run a ".cmd" or ".bat" file, you have to use the full name with the extension.

[pfmoore]

I'm still unsure whether this would be a good idea. On the plus side, it provides (in conjunction with the "embedded" distribution) a really good way of producing a standalone application on Windows. On the minus side there are some limitations which may trip up naive users:

• You can't put C extensions in a zipapp
• You have to take care with things like multiprocessing if you're using an embedded app.

And the wrapper's basically only 4 lines of code:

wchar_t **myargv = _alloca((__argc + 2) * sizeof(wchar_t*));
myargv[0] = __wargv[0];
memcpy(myargv + 1, __wargv, (__argc + 1) * sizeof(wchar_t *));
return Py_Main(__argc+1, myargv);

so it's not exactly rocket science. (By the way, the arguments to Py_Main are "exactly as those which are passed to a C program’s main" - IIRC, for a C program there's always a NULL pointer at the end of argv, does that rule apply to Py_Main, too? The code doesn't seem to rely on it, so I guess I could save a slot in the array above).

Maybe adding a section to the zipapp docs explaining how to make standalone applications would be a better way of handling this? That would have the advantage of being just as applicable to 3.6 (and 3.5, for that matter) at the cost of making users build their own wrapper (or find a published one).

[brettcannon]

I think documentation is definitely the cheapest option. It's also the most flexible since if we find out there's a lot of usage of the guide then we can add explicit support.

[pfmoore]

OK, here's a first draft documentation patch. As it's purely a documentation change, I guess it should go into the 3.5, 3.6 and trunk branches? For now it's against trunk (it's not like that file has changed recently anyway), and I'll sort out the merge dance once it looks OK.