Yeah, I never found a good place to document this, hence the relatively sparse references in the "using" docs.

The most complete official docs for these features are actually in runpy:

* https://docs.python.org/3/library/runpy.html#runpy.run_module
* https://docs.python.org/3/library/runpy.html#runpy.run_path

run_module is a thin wrapper around the same core code that actually implements the -m switch

run_path is a Python level reimplementation of the __main__ execution logic

There's also http://www.curiousefficiency.org/posts/2011/03/what-is-python-script.html on my blog and the explanation of the options that need to be supported in PEP 432: https://www.python.org/dev/peps/pep-0432/#preparing-the-main-module

A lot of the confusion stems from the fact that directory & zipfile execution was added without a PEP back in 2.6 (it was just a normal tracker issue) and we forgot to add it to the What's New document. We hoped the inclusion of the zipapp module in Python 3.5 via PEP 441 might help resolve that lack of awareness, but it doesn't seem to have had much impact.