[docs] [issue24632] Improve documentation about __main__.py

[Ezio Melotti]

Ezio Melotti added the comment:

Another thing that should be clarified, is the difference between __main__.py inside a package, and __main__.py inside a zip file.

For packages, as far as I understand, __main__.py should be inside the package (i.e. pkg/__main__.py, in the same dir of pkg/__init__.py).
This allows the package to be "executed" by doing "python3 -m pkg".

For zip files, the __main__.py should be right inside the zip (i.e. file.zip/__main__.py).
This allows the zip file to be "executed" by doing "python3 file.zip" (note that no -m is used here, and that "python3 -m file.zip" fails).

While zipping a package that already contains a __main__.py, the right way to do it seems to be the following:
1) add the package to a zip file (i.e. file.zip/pkg/)
2) add another __main__.py to the zip (i.e. file.zip/__main__.py)
3) add 'import pkg.__main__' to file.zip/__main__.py
now if you do "python3 file.zip", file.zip/__main__.py will be executed, and in turn it will import file.zip/pkg/__main__.py, obtaining a result equivalent to "python -m pkg".

(I still haven't figured out if the __main__.py is necessary while /importing/ a package/module from a zip file, after having added the zip file to sys.path.)

So, to summarize, it seems to me that:
1) pkg/__main__.py is necessary to run "python3 -m pkg" (with -m);
2) file.zip/__main__.py is necessary to run "python3 file.zip" (without -m);
3) due to 1) and 2) creating an executable zipped package requires 2 __main__.py;
4) "python3 pkg" and "python3 -m file.zip" are not supposed to work even if the __main__.py files are in the right place.

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue24632>
_______________________________________