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

Created on 2012-06-19 08:02 by techtonik, last changed 2012-11-13 07:14 by eric.snow.

Messages (11)
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.
History
Date User Action Args
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