New submission from Ezio Melotti:
__main__.py seems to only be mentioned briefly in a couple of places in the
official docs:
1) https://docs.python.org/3/library/__main__.html
2) https://docs.python.org/3/using/cmdline.html#cmdoption-m
The first link only says:
"""For a package, the same effect can be achieved by including a __main__.py
module, the contents of which will be executed when the module is run with
-m."""
("-m" should actually use :option:`-m` to automatically link to the second URL.)
The second link mentions __main__.py in two sentences:
"""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."""
"""If the script name refers to a directory or zipfile, the script name is
added to the start of sys.path and the __main__.py file in that location is
executed as the __main__ module."""
I think it would be better to expand the first link to state clearly what is
__main__.py and what is its purpose. In addition, the section should clarify a
few more things, e.g. when it should be used, what it should contain, if it's
ok to have other __main__.py in the subpackages (e.g. test/__main__.py to run
the tests with python -m package.test), how it interacts __init__.py (which one
is executed first?).
Perhaps it should also get a glossary entry and/or a short mention in the
tutorial together with zip imports.
In addition to the two links above, a Google search returns the stackoverflow
question "What is __main__.py?" as first result, and a couple more related
questions that could/should be answered by our docs.
----------
assignee: docs@python
components: Documentation
messages: 246719
nosy: docs@python, ethan.furman, ezio.melotti, nedbat
priority: normal
severity: normal
stage: needs patch
status: open
title: Improve documentation about __main__.py
type: enhancement
versions: Python 2.7, Python 3.4, Python 3.5
_______________________________________
Python tracker <[email protected]>
<http://bugs.python.org/issue24632>
_______________________________________
_______________________________________________
Python-bugs-list mailing list
Unsubscribe:
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
