Convert PEP 299 to rst. (#47)
This commit is contained in:
Matthias Bussonnier
Berker Peksag
parent
2e6c3886d1
commit
1255af25a0
134
pep-0299.txt
134
pep-0299.txt
|
|
@ -5,116 +5,124 @@ Last-Modified: $Date$
|
|||
Author: Jeff Epler <jepler@unpythonic.net>
|
||||
Status: Rejected
|
||||
Type: Standards Track
|
||||
Content-Type: text/x-rst
|
||||
Created: 12-Aug-2002
|
||||
Python-Version: 2.3
|
||||
Post-History: 29-Mar-2006
|
||||
|
||||
|
||||
Abstract
|
||||
|
||||
Many Python modules are also intended to be callable as standalone
|
||||
scripts. This PEP proposes that a special function called
|
||||
__main__() should serve this purpose.
|
||||
Abstract
|
||||
========
|
||||
|
||||
Many Python modules are also intended to be callable as standalone
|
||||
scripts. This PEP proposes that a special function called ``__main__()``
|
||||
should serve this purpose.
|
||||
|
||||
|
||||
Motivation
|
||||
==========
|
||||
|
||||
There should be one simple and universal idiom for invoking a
|
||||
module as a standalone script.
|
||||
There should be one simple and universal idiom for invoking a module
|
||||
as a standalone script.
|
||||
|
||||
The semi-standard idiom
|
||||
The semi-standard idiom::
|
||||
|
||||
if __name__ == '__main__':
|
||||
perform "standalone" functionality
|
||||
if __name__ == '__main__':
|
||||
perform "standalone" functionality
|
||||
|
||||
is unclear to programmers of languages like C and C++. It also
|
||||
does not permit invocation of the standalone function when the
|
||||
module is imported. The variant
|
||||
is unclear to programmers of languages like C and C++. It also does
|
||||
not permit invocation of the standalone function when the module is
|
||||
imported. The variant::
|
||||
|
||||
if __name__ == '__main__':
|
||||
main_function()
|
||||
if __name__ == '__main__':
|
||||
main_function()
|
||||
|
||||
is sometimes seen, but there exists no standard name for the
|
||||
function, and because arguments are taken from sys.argv it is not
|
||||
possible to pass specific arguments without changing the argument
|
||||
list seen by all other modules. (Imagine a threaded Python
|
||||
program, with two threads wishing to invoke the standalone
|
||||
functionality of different modules with different argument lists)
|
||||
is sometimes seen, but there exists no standard name for the function,
|
||||
and because arguments are taken from sys.argv it is not possible to
|
||||
pass specific arguments without changing the argument list seen by all
|
||||
other modules. (Imagine a threaded Python program, with two threads
|
||||
wishing to invoke the standalone functionality of different modules
|
||||
with different argument lists)
|
||||
|
||||
|
||||
Proposal
|
||||
========
|
||||
|
||||
The standard name of the 'main function' should be '__main__'.
|
||||
When a module is invoked on the command line, such as
|
||||
The standard name of the 'main function' should be ``__main__``. When a
|
||||
module is invoked on the command line, such as::
|
||||
|
||||
python mymodule.py
|
||||
python mymodule.py
|
||||
|
||||
then the module behaves as though the following lines existed at
|
||||
the end of the module (except that the attribute __sys may not be
|
||||
used or assumed to exist elsewhere in the script):
|
||||
then the module behaves as though the following lines existed at the
|
||||
end of the module (except that the attribute __sys may not be used or
|
||||
assumed to exist elsewhere in the script)::
|
||||
|
||||
if globals().has_key("__main__"):
|
||||
import sys as __sys
|
||||
__sys.exit(__main__(__sys.argv))
|
||||
if globals().has_key("__main__"):
|
||||
import sys as __sys
|
||||
__sys.exit(__main__(__sys.argv))
|
||||
|
||||
Other modules may execute
|
||||
Other modules may execute::
|
||||
|
||||
import mymodule
|
||||
mymodule.__main__(['mymodule', ...])
|
||||
import mymodule mymodule.__main__(['mymodule', ...])
|
||||
|
||||
It is up to mymodule to document thread-safety issues or other
|
||||
issues which might restrict use of __main__. (Other issues might
|
||||
include use of mutually exclusive GUI modules, non-sharable
|
||||
resources like hardware devices, reassignment of sys.stdin/stdout,
|
||||
etc)
|
||||
It is up to ``mymodule`` to document thread-safety issues or other
|
||||
issues which might restrict use of ``__main__``. (Other issues might
|
||||
include use of mutually exclusive GUI modules, non-sharable resources
|
||||
like hardware devices, reassignment of ``sys.stdin``/``stdout``, etc)
|
||||
|
||||
|
||||
Implementation
|
||||
==============
|
||||
|
||||
In modules/main.c, the block near line 385 (after the
|
||||
PyRun_AnyFileExFlags call) will be changed so that the above code
|
||||
(or its C equivalent) is executed.
|
||||
In ``modules/main.c``, the block near line 385 (after the
|
||||
``PyRun_AnyFileExFlags`` call) will be changed so that the above code
|
||||
(or its C equivalent) is executed.
|
||||
|
||||
|
||||
Open Issues
|
||||
===========
|
||||
|
||||
- Should the return value from __main__ be treated as the exit value?
|
||||
* Should the return value from ``__main__`` be treated as the exit value?
|
||||
|
||||
Yes. Many __main__ will naturally return None, which sys.exit
|
||||
translates into a "success" return code. In those that return a
|
||||
numeric result, it behaves just like the argument to sys.exit()
|
||||
or the return value from C's main().
|
||||
Yes. Many ``__main__`` will naturally return ``None``, which
|
||||
``sys.exit`` translates into a "success" return code. In those that
|
||||
return a numeric result, it behaves just like the argument to
|
||||
``sys.exit()`` or the return value from C's main().
|
||||
|
||||
- Should the argument list to __main__ include argv[0], or just the
|
||||
"real" arguments argv[1:]?
|
||||
* Should the argument list to ``__main__`` include ``argv[0]``, or just the
|
||||
"real" arguments ``argv[1:]``?
|
||||
|
||||
argv[0] is included for symmetry with sys.argv and easy
|
||||
transition to the new standard idiom.
|
||||
``argv[0]`` is included for symmetry with ``sys.argv`` and easy
|
||||
transition to the new standard idiom.
|
||||
|
||||
|
||||
Rejection
|
||||
=========
|
||||
|
||||
In a short discussion on python-dev [1], two major backwards
|
||||
compatibility problems were brought up and Guido pronounced that he
|
||||
doesn't like the idea anyway as it's "not worth the change (in docs,
|
||||
user habits, etc.) and there's nothing particularly broken."
|
||||
In a short discussion on python-dev [1], two major backwards
|
||||
compatibility problems were brought up and Guido pronounced that he
|
||||
doesn't like the idea anyway as it's "not worth the change (in docs,
|
||||
user habits, etc.) and there's nothing particularly broken."
|
||||
|
||||
|
||||
References
|
||||
==========
|
||||
|
||||
[1] Georg Brandl, "What about PEP 299",
|
||||
http://mail.python.org/pipermail/python-dev/2006-March/062951.html
|
||||
.. [1] Georg Brandl, "What about PEP 299",
|
||||
http://mail.python.org/pipermail/python-dev/2006-March/062951.html
|
||||
|
||||
|
||||
Copyright
|
||||
=========
|
||||
|
||||
This document has been placed in the public domain.
|
||||
|
||||
This document has been placed in the public domain.
|
||||
|
||||
|
||||
Local Variables:
|
||||
mode: indented-text
|
||||
indent-tabs-mode: nil
|
||||
sentence-end-double-space: t
|
||||
fill-column: 70
|
||||
End:
|
||||
..
|
||||
Local Variables:
|
||||
mode: indented-text
|
||||
indent-tabs-mode: nil
|
||||
sentence-end-double-space: t
|
||||
fill-column: 70
|
||||
End:
|
||||
|
|
|
|||
Loading…
Reference in New Issue