I still don't think that the available documentation is detailed enough. It leaves too many unanswered question, e.g.

* What happens if you have both __init__.py and __main__.py in a directory or a ZIP file ?

* What does "the script name is added to the start of sys.path" mean when using a ZIP file ?

* What are the implications of "Directories and zipfiles containing a __main__.py file at the top level are now considered valid Python scripts." and where does this scope end ? The wording suggests that you can also import such directories or ZIP files.

* How are sys.path, __name__ and possibly __path__ setup when using this approach of running a dir/package/ZIP file ?

and probably a few more. The above can all be answered using trial-and-error, but it would be better to actually document the intended behavior.

Some quirks I found (dir is a directory with both __init__.py and __main__.py):

* "python2.6 dir" runs the __main__.py file, while "python2.6 -m dir" does not. Both work in the same way in Python 2.7.

* In Python 2.7, the two approaches differ in the way sys.path[0] is setup: "python2.7 dir" causes this to be set to "dir", while "python2.7 -m dir" results in "".

Background: The reason why I'm interested in this is that we are trying to mimic the Python command line interface with pyrun (http://www.egenix.com/products/python/PyRun/).