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.

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

    @python -x "%0" %*

(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".

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.

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).

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.

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.

Only backport if you want; it's not a bug fix so technically it doesn't need to be backported.

Hi Paul,

Were you interested in moving forward with this doc change?

Hi Cheryl,
Looks like I dropped the ball on this one :-( I think it just needs to be applied to the main branch (3.7/3.8) - I don't think it's worth backporting.

I'll try to get to it when I can, but it may not be for a few weeks, as I have other stuff on my plate at the moment. I've not done anything under the new github workflow, so I don't want to rush it and risk making mistakes. I'm happy if someone else wants to merge it in the meantime.

Hi Paul,

Thanks for your response.  I've made the pull request from your patch, so it would great if you could review it.  Thanks!

New changeset 4be79f29463f632cd8b48486feadc2ed308fb520 by Paul Moore (Cheryl Sabella) in branch 'master':
bpo-28247: Document Windows executable creation in zipapp (GH-6158)
https://github.com/python/cpython/commit/4be79f29463f632cd8b48486feadc2ed308fb520

New changeset a70b8f593657f563116001f654587620271eb9ae by Miss Islington (bot) in branch '3.7':
bpo-28247: Document Windows executable creation in zipapp (GH-6158)
https://github.com/python/cpython/commit/a70b8f593657f563116001f654587620271eb9ae

New changeset 47a0e64ccf711e8d6d0c497d565ca7e2e82de7d4 by Miss Islington (bot) in branch '3.6':
bpo-28247: Document Windows executable creation in zipapp (GH-6158)
https://github.com/python/cpython/commit/47a0e64ccf711e8d6d0c497d565ca7e2e82de7d4

The documentation helped a lot, so thanks for that! But it misses the final crucial step:

copy /b zastub.exe+app.pyz app.exe

The documentation talks about prepending the zastub.exe to the zip file but never mentions how, which is very confusing.

While I can see your point, I'm a little skeptical that anyone who's able to write C source code and compile it can't work out how to combine two binary files... :-)