classification
Title: Unclear language in __main__ description
Type: behavior Stage: needs patch
Components: Documentation Versions: Python 2.7
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: eric.araujo Nosy List: docs@python, eric.araujo, eric.snow, ezio.melotti, loewis, mansam, mikehoy, python-dev, r.david.murray, techtonik, terry.reedy
Priority: normal Keywords: easy, patch

Created on 2012-06-19 08:02 by techtonik, last changed 2014-05-02 08:23 by eric.araujo.

Files
File name Uploaded Description Edit
clarify-__main__-documentation.patch mansam, 2014-04-14 15:46 review
clarify-__main__-documentation.patch mansam, 2014-04-14 16:10 review
clarify-__main__-documentation-backticks.patch mansam, 2014-04-14 18:12 review
Messages (19)
msg163140 - (view) Author: anatoly techtonik (techtonik) Date: 2012-06-19 08:02
http://docs.python.org/library/__main__.html

"It is this environment in which the idiomatic “conditional script” stanza causes a script to run"

?!?
msg163141 - (view) Author: Hynek Schlawack (hynek) * (Python committer) Date: 2012-06-19 08:07
I’m no native speaker but I fail to see anything abusive here.
msg163142 - (view) Author: anatoly techtonik (techtonik) Date: 2012-06-19 08:10
It is abusive for those who don't get the meaning. Can you translate it to simple english?
msg163143 - (view) Author: anatoly techtonik (techtonik) Date: 2012-06-19 08:13
Maybe "abusive language" is not the right translation from Russian. It could be "coarse language" or "foul language".
msg163144 - (view) Author: Martin v. Löwis (loewis) * (Python committer) Date: 2012-06-19 08:23
Which specific word do you consider "грубый" or "сквернословие"? This is all polite, courteous wording, in my understanding of English. But maybe a native speaker should really comment here.
msg163145 - (view) Author: anatoly techtonik (techtonik) Date: 2012-06-19 08:50
Ok, the "language is not clear enough" is the queasily polite, serious and corteous substitution for "abusive language" in the title of this issue.

Can you translate it to simple english?
msg163146 - (view) Author: Martin v. Löwis (loewis) * (Python committer) Date: 2012-06-19 08:55
"The following fragment can be used to make a Python file both a library and a script".
msg163148 - (view) Author: Martin v. Löwis (loewis) * (Python committer) Date: 2012-06-19 08:57
Or, actually 

"When the script executes as this (i.e. "__main__") module, the following conditional statement, which is in wide use and well-known, will cause the script to run".
msg163149 - (view) Author: anatoly techtonik (techtonik) Date: 2012-06-19 09:10
Now I get it. That's much better. Thanks. =)

After rereading the description with this new info I spot that __main__ is called a module, which is not true, because it is only a module name. It makes sense to enclose it in quotes in title as well.

I'd reword this:
{{{
This module represents the (otherwise anonymous) scope in which the interpreter’s main program executes — commands read either from standard input, from a script file, or from an interactive prompt. It is this environment in which the idiomatic “conditional script” stanza causes a script to run:
}}}

to this:
{{{
This __name__ value represents (otherwise anonymous) scope of the program’s main module in the interpreter. __name__ becomes equal to '__main__' when commands read either from standard input, from a script file, or from an interactive prompt. For example, a common way to add code to module that will only be executable when run as a script is to place it into the following if block:
}}}

Not academic, but practical.
msg163157 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2012-06-19 12:48
Hmm.  I think that chapter could use a more extensive rewrite with some additional information provided.  For example, you actually can have a __main__ module in a package, and anything inside it will execute when the package is run via -m.

The "otherwise anonymous" is a bit misleading, I think.  The real distinction is that when a module is run as a script, __name__ is set to __main__, whereas when it is imported, __name__ is the module name.  This distinction allows a module to easily detect when it is being run as a script rather than imported, and the "idiomatic 'conditional script' stanza" is how to implement the behavior of a module conditionally acting as a script depending on how it is accessed.
msg163535 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2012-06-23 06:48
As a native speaker, I agree that the sentence, in isolation, is hardly comprehensible. The previous one is also a bit flakey.

The situation is that top-level code executes in a module named __main__, which has one joint global/local namespace that is the global namespace for all subsidiary contexts. '__main__':<__main__ module> is added to sys.modules before user code is executed. The name __main__ is not normally in the __main__ (global) namespace, hence the comment about 'anonymous' in the first sentence. (It is not anonymous in sys.modules.) However (1) __main__ or any other module/namespace can 'import __main__' and get the reference to __main__ from sys.modules and (2) __main__ does have name __name__ bound to the *string* '__main__'. Hence a module can discover whether or not it *is* the __main__ module.

Part of the quoting confusion is that unquoted names in code become strings in namespace dicts, and hence quoted literals when referring to them as keys. What I did not realize until just now is that the __name__ attribute of a module *is* its name (key) in the module namespace (sys.modules dict). For instance, after 'import x.y' or 'from x import y', x.y.__name__ or y.__name is 'x.y' and that is its name (key) in sys.modules. So it appears that the __name__ of a package (sub)module is never just the filename (which I expected), and "__name__ is the module name" only if one considers the package name as part of the module name (which I did not).

The only non-capi reference to module.__name__ in the index is

3.2. The standard type hierarchy
Modules
"__name__ is the module’s name"

But what is the modules name? Its name in sys.modules, which is either __main__ or the full dotted name for modules in packages (as I just learned). Perhaps this could be explained better here.
msg216102 - (view) Author: Sam Lucidi (mansam) * Date: 2014-04-14 15:46
I've attempted to synthesize the ideas in this thread into a clearer explanation of __main__. What I've written doesn't attempt to explain anything else about module naming, but it does try to address the common package and module uses of __main__.
msg216103 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2014-04-14 16:01
I've made some review comments.
msg216107 - (view) Author: Sam Lucidi (mansam) * Date: 2014-04-14 16:10
Thanks, I've revised the change based on your comments.
msg216175 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2014-04-14 19:06
New changeset 4f23648b7c97 by R David Murray in branch '3.4':
#15104: improve the discussion of __main__.
http://hg.python.org/cpython/rev/4f23648b7c97

New changeset 94ac365bf1b7 by R David Murray in branch 'default':
Merge: #15104: improve the discussion of __main__.
http://hg.python.org/cpython/rev/94ac365bf1b7
msg216176 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2014-04-14 19:07
Thanks, Sam.  I did not apply this to 2.7 because I'm not sure if the __main__.py is supported there.  Can someone check?
msg216218 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2014-04-14 21:05
I am a bit puzzled. According to
https://docs.python.org/2.7/using/cmdline.html#interface-options __main__.py (not indexed) has been supported since 2.5. On the other hand, recursively grepping Lib for 'e' in __main__.py files hits about 20 files in 3.4 but only 2 in 2.7. Moreover, those two files fail for trying to do relative imports: "from .main import main, TestProgram, USAGE_AS_MAIN".
msg216248 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2014-04-14 22:54
New changeset 008486e18e90 by R David Murray in branch '3.4':
#15104: add backtick code markup.
http://hg.python.org/cpython/rev/008486e18e90

New changeset 14e874736d3a by R David Murray in branch 'default':
Merge: #15104: add backtick code markup.
http://hg.python.org/cpython/rev/14e874736d3a
msg217747 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2014-05-02 08:23
Docs and indexing/cross-links in 2.7 should indeed be improved.  I had forgotten which of 2.6 or 2.7 added support for executing packages thanks to __main__.py files and the docs don't contain an answer that's comprehensive and easy to find.
History
Date User Action Args
2014-05-02 08:23:25eric.araujosetnosy: + eric.araujo
messages: + msg217747

assignee: docs@python -> eric.araujo
stage: patch review -> needs patch
2014-04-14 22:54:42python-devsetmessages: + msg216248
2014-04-14 21:05:31terry.reedysetmessages: + msg216218
2014-04-14 19:07:55r.david.murraysetmessages: - msg216177
2014-04-14 19:07:35r.david.murraysetmessages: + msg216177
2014-04-14 19:07:33r.david.murraysettype: enhancement -> behavior
messages: + msg216176
versions: - Python 3.4, Python 3.5
2014-04-14 19:06:17python-devsetnosy: + python-dev
messages: + msg216175
2014-04-14 18:12:52mansamsetfiles: + clarify-__main__-documentation-backticks.patch
2014-04-14 16:10:55mansamsetfiles: + clarify-__main__-documentation.patch

messages: + msg216107
2014-04-14 16:01:54r.david.murraysetstage: needs patch -> patch review
versions: + Python 3.5, - Python 3.2, Python 3.3
2014-04-14 16:01:34r.david.murraysetmessages: + msg216103
2014-04-14 15:46:08mansamsetfiles: + clarify-__main__-documentation.patch

nosy: + mansam
messages: + msg216102

keywords: + patch
2012-11-13 07:14:37eric.snowsetnosy: + eric.snow
2012-11-02 07:26:29hyneksetnosy: - hynek
2012-10-03 15:02:26mikehoysetnosy: + mikehoy
2012-10-02 05:44:33ezio.melottisetkeywords: + easy
versions: + Python 3.4
2012-06-23 06:48:08terry.reedysetnosy: + terry.reedy
messages: + msg163535
2012-06-19 16:17:23ezio.melottisetnosy: + ezio.melotti
type: enhancement
2012-06-19 12:48:15r.david.murraysetnosy: + r.david.murray
title: abusive language in __name__ description -> Unclear language in __main__ description
messages: + msg163157

versions: + Python 2.7, Python 3.2, Python 3.3
stage: needs patch
2012-06-19 09:10:36techtoniksetmessages: + msg163149
2012-06-19 08:57:37loewissetmessages: + msg163148
2012-06-19 08:55:01loewissetmessages: + msg163146
2012-06-19 08:50:26techtoniksetmessages: + msg163145
2012-06-19 08:23:38loewissetnosy: + loewis
messages: + msg163144
2012-06-19 08:13:34techtoniksetmessages: + msg163143
2012-06-19 08:10:01techtoniksetmessages: + msg163142
2012-06-19 08:07:38hyneksetnosy: + hynek
messages: + msg163141
2012-06-19 08:02:44techtonikcreate