[issue15104] abusive language in __name__ description

New submission from anatoly techtonik <techtonik@gmail.com>: http://docs.python.org/library/__main__.html "It is this environment in which the idiomatic “conditional script” stanza causes a script to run" ?!? ---------- assignee: docs@python components: Documentation messages: 163140 nosy: docs@python, techtonik priority: normal severity: normal status: open title: abusive language in __name__ description _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15104> _______________________________________

Hynek Schlawack <hs@ox.cx> added the comment: I’m no native speaker but I fail to see anything abusive here. ---------- nosy: +hynek _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15104> _______________________________________

anatoly techtonik <techtonik@gmail.com> added the comment: It is abusive for those who don't get the meaning. Can you translate it to simple english? ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15104> _______________________________________

anatoly techtonik <techtonik@gmail.com> added the comment: Maybe "abusive language" is not the right translation from Russian. It could be "coarse language" or "foul language". ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15104> _______________________________________

Martin v. Löwis <martin@v.loewis.de> added the comment: 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. ---------- nosy: +loewis _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15104> _______________________________________

anatoly techtonik <techtonik@gmail.com> added the comment: 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? ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15104> _______________________________________

Martin v. Löwis <martin@v.loewis.de> added the comment: "The following fragment can be used to make a Python file both a library and a script". ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15104> _______________________________________

Martin v. Löwis <martin@v.loewis.de> added the comment: 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". ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15104> _______________________________________

anatoly techtonik <techtonik@gmail.com> added the comment: 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. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15104> _______________________________________

R. David Murray <rdmurray@bitdance.com> added the comment: 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. ---------- nosy: +r.david.murray stage: -> needs patch title: abusive language in __name__ description -> Unclear language in __main__ description versions: +Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15104> _______________________________________

Changes by Ezio Melotti <ezio.melotti@gmail.com>: ---------- nosy: +ezio.melotti type: -> enhancement _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15104> _______________________________________

Terry J. Reedy <tjreedy@udel.edu> added the comment: 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. ---------- nosy: +terry.reedy _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15104> _______________________________________

Changes by Ezio Melotti <ezio.melotti@gmail.com>: ---------- keywords: +easy versions: +Python 3.4 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15104> _______________________________________

Changes by Mike Hoy <mhoy09@gmail.com>: ---------- nosy: +mikehoy _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15104> _______________________________________

Changes by Hynek Schlawack <hs@ox.cx>: ---------- nosy: -hynek _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15104> _______________________________________

Changes by Eric Snow <ericsnowcurrently@gmail.com>: ---------- nosy: +eric.snow _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15104> _______________________________________

Sam Lucidi added the comment: 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__. ---------- keywords: +patch nosy: +mansam Added file: http://bugs.python.org/file34820/clarify-__main__-documentation.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15104> _______________________________________

R. David Murray added the comment: I've made some review comments. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15104> _______________________________________

Changes by R. David Murray <rdmurray@bitdance.com>: ---------- stage: needs patch -> patch review versions: +Python 3.5 -Python 3.2, Python 3.3 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15104> _______________________________________

Sam Lucidi added the comment: Thanks, I've revised the change based on your comments. ---------- Added file: http://bugs.python.org/file34822/clarify-__main__-documentation.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15104> _______________________________________

Changes by Sam Lucidi <mansam@csh.rit.edu>: Added file: http://bugs.python.org/file34831/clarify-__main__-documentation-backticks.pa... _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15104> _______________________________________

Roundup Robot added the comment: 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 ---------- nosy: +python-dev _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15104> _______________________________________

R. David Murray added the comment: 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? ---------- type: enhancement -> behavior versions: -Python 3.4, Python 3.5 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15104> _______________________________________

R. David Murray added the comment: 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? ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15104> _______________________________________

Changes by R. David Murray <rdmurray@bitdance.com>: ---------- Removed message: http://bugs.python.org/msg216177 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15104> _______________________________________

Terry J. Reedy added the comment: 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". ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15104> _______________________________________

Roundup Robot added the comment: 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 ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15104> _______________________________________

Éric Araujo added the comment: 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. ---------- assignee: docs@python -> eric.araujo nosy: +eric.araujo stage: patch review -> needs patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15104> _______________________________________

Irit Katriel <iritkatriel@yahoo.com> added the comment: Fixed for Python 3, too late for Python 2. ---------- nosy: +iritkatriel resolution: -> fixed stage: needs patch -> resolved status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue15104> _______________________________________
participants (12)
-
anatoly techtonik
-
Eric Snow
-
Ezio Melotti
-
Hynek Schlawack
-
Irit Katriel
-
Martin v. Löwis
-
Mike Hoy
-
R. David Murray
-
Roundup Robot
-
Sam Lucidi
-
Terry J. Reedy
-
Éric Araujo