This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

classification
Title: Mention "__main__.py" explicitly in command line docs
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.11, Python 3.10
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: cameron, cvrebert, docs@python, eric.araujo, ezio.melotti, iritkatriel, jack__d, lemburg, lukasz.langa, ncoghlan
Priority: normal Keywords: patch

Created on 2013-03-05 19:40 by lemburg, last changed 2022-04-11 14:57 by admin. This issue is now closed.

Pull Requests
URL Status Linked Edit
PR 26883 jack__d, 2021-08-22 19:51
Messages (10)
msg183550 - (view) Author: Marc-Andre Lemburg (lemburg) * (Python committer) Date: 2013-03-05 19:40
The feature to run a ZIP file containing Python modules is not documented.

It was implemented in Python 2.6:

 * http://bugs.python.org/issue1739468

and mentioned in the "What's new":

 * http://docs.python.org/2/whatsnew/2.6.html?highlight=python%20run%20zip%20files#other-language-changes

but searching the documentation for "__main__.py" returns 0 hits in the docs (for Python 2.7 and 3.4).

I guess "python dir" should also be mentioned somewhere...
msg183551 - (view) Author: Eli Bendersky (eli.bendersky) * (Python committer) Date: 2013-03-05 19:48
From http://docs.python.org/3/using/cmdline.html:

  Package names are also permitted. When a package name is supplied instead of a normal module, the interpreter will execute <pkg>.__main__ as the main module. This behaviour is deliberately similar to the handling of directories and zipfiles that are passed to the interpreter as the script argument.

This is for "-m"

Also:

 <script>

    Execute the Python code contained in script, which must be a filesystem path (absolute or relative) referring to either a Python file, a directory containing a __main__.py file, or a zipfile containing a __main__.py file.
msg183821 - (view) Author: Eli Bendersky (eli.bendersky) * (Python committer) Date: 2013-03-09 14:16
Marc-Andre,  Can this issue be closed or are the docs lacking in some way?
msg185764 - (view) Author: Marc-Andre Lemburg (lemburg) * (Python committer) Date: 2013-04-01 20:11
I don't think that's enough documentation for the feature. There's a whole PEP 338 just for the -m option due to the subtle issue associated with the "run a module" logic, so I'd expect somewhat more detail or an update of the PEP with the needed details.

This page would be the appropriate place for a section on the topic, I guess:

http://docs.python.org/3/library/runpy.html

A mention on this page would also be good:

http://docs.python.org/3/tutorial/interpreter.html

Since the feature was added in Python 2.6, the documentation patch should also be backported to the Python 2.6 and 2.7.

PS: I wonder why the documentation search doesn't even return the page you mentioned.
msg185779 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2013-04-01 22:38
The previous title was not accurate, as the directory and zipfile execution feature is documented at http://docs.python.org/2/using/cmdline.html#interface-options

It is also documented in http://docs.python.org/3/library/runpy#runpy.run_path
msg185780 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2013-04-01 22:42
There's also a problem where the CLI docs claim __main__.py support was added in 2.5 - that's not accurate, it was only added in 2.6.
msg185826 - (view) Author: Marc-Andre Lemburg (lemburg) * (Python committer) Date: 2013-04-02 09:21
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/).
msg246798 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2015-07-16 10:11
See also #24632.
msg396155 - (view) Author: Irit Katriel (iritkatriel) * (Python committer) Date: 2021-06-19 23:58
See also Issue39452.
msg400241 - (view) Author: Łukasz Langa (lukasz.langa) * (Python committer) Date: 2021-08-24 20:57
Solved as part of BPO-39452.
History
Date User Action Args
2022-04-11 14:57:42adminsetgithub: 61561
2021-08-24 20:57:22lukasz.langasetstatus: open -> closed

versions: + Python 3.10
nosy: + lukasz.langa

messages: + msg400241
resolution: fixed
stage: patch review -> resolved
2021-08-22 19:51:45jack__dsetkeywords: + patch
nosy: + jack__d

pull_requests: + pull_request26356
stage: patch review
2021-06-21 04:12:55cameronsetnosy: + cameron
2021-06-20 00:00:56iritkatrielsetversions: + Python 3.11, - Python 2.7, Python 3.3, Python 3.4
2021-06-19 23:58:01iritkatrielsetnosy: + iritkatriel
messages: + msg396155
2015-07-16 10:11:38ezio.melottisettype: enhancement

messages: + msg246798
nosy: + ezio.melotti
2013-10-07 02:34:56cvrebertsetnosy: + cvrebert
2013-08-04 00:54:49eli.benderskysetnosy: - eli.bendersky
2013-04-02 09:21:01lemburgsetmessages: + msg185826
2013-04-01 22:42:07ncoghlansetmessages: + msg185780
2013-04-01 22:38:46ncoghlansettitle: Mention "__main__.py" explicit in command line docs -> Mention "__main__.py" explicitly in command line docs
2013-04-01 22:38:35ncoghlansetmessages: + msg185779
title: python modules.zip is not documented -> Mention "__main__.py" explicit in command line docs
2013-04-01 20:18:48eric.araujosetversions: - Python 2.6, Python 3.2
2013-04-01 20:11:44lemburgsetversions: + Python 2.6
2013-04-01 20:11:25lemburgsetmessages: + msg185764
2013-03-11 04:59:25eric.araujosetnosy: + ncoghlan, eric.araujo

versions: + Python 3.2, - Python 3.5
2013-03-09 14:16:50eli.benderskysetmessages: + msg183821
2013-03-05 19:48:45eli.benderskysetnosy: + eli.bendersky
messages: + msg183551
2013-03-05 19:40:25lemburgcreate