> The surprising thing is that __main__ works without there being an __init__.

That's also what surprised me, I always thought __main__.py was supposed to be used within a package executed with "python -m pkg", but apparently "regular" dirs and zip files can have one too -- as long as they are executed as "python dir_or_zip".


This should have answered the question I posed in my first message: what is __main__.py and what is its purpose?

As for the others:
Q: when should it be used?
A: whenever you want to make a package/dir/zip executable
Q: what should it contain?
A: usually an import + a function call that launches the app should be enough, but might contain more code if necessary
Q: is it ok to have other __main__.py in the subpackages (e.g. test/__main__.py to run the tests with python -m package.test)?
A: this seems to work and should be OK
Q: how it interacts __init__.py (which one is executed first?)
A: __init__.py seems to be executed first.  I'm not aware of other interactions.

If these are indeed correct, a patch can be made (feel free to do it, since I don't when I'll have time to do it myself).