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

[Ezio Melotti]

Ezio Melotti added the comment:

After further tests, I think I figured out how things works.
There are three separate things that interact with each other:
  * packages (dirs with an __init__.py) and "regular" dirs (with no __init__.py) or zip files;
  * how python is executed (with or without -m);
  * if the pkg/dir/zip is executed or imported.

__main__.py makes a pkg/dir/zip "executable", but:
  * if it's a package, "python -m pkg" should be used;
  * if it's a dir or zip, "python dir_or_zip" should be used instead.

There seem to be no differences between "regular" dirs and zip files:
  * both can become executable with a __main__.py;
  * both should be executed with "python dir_or_zip" (no -m);
  * both can not be imported (if we ignore namespace packages);
  * both can be added to sys.path, and the modules they contain imported, without needing any __main__.py.

This also means that __main__.py is used only while doing "python -m pkg" or "python dir_or_zip", and not while doing "import pkg" or while importing a module inside a dir/zip.

----------

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