From 1255af25a07587bae29ab1144be9c45aafba42cc Mon Sep 17 00:00:00 2001 From: Matthias Bussonnier Date: Wed, 6 Jul 2016 19:37:27 -0700 Subject: [PATCH] Convert PEP 299 to rst. (#47) --- pep-0299.txt | 134 +++++++++++++++++++++++++++------------------------ 1 file changed, 71 insertions(+), 63 deletions(-) diff --git a/pep-0299.txt b/pep-0299.txt index d9054dcf7..a855c58e5 100644 --- a/pep-0299.txt +++ b/pep-0299.txt @@ -5,116 +5,124 @@ Last-Modified: $Date$ Author: Jeff Epler 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: