diff --git a/pep-0299.txt b/pep-0299.txt new file mode 100644 index 000000000..68b6f0e1a --- /dev/null +++ b/pep-0299.txt @@ -0,0 +1,106 @@ +PEP: 299 +Title: Special __main__() function in modules +Version: $Revision$ +Last-Modified: $Date$ +Author: Jeff Epler +Status: Draft +Type: Standards Track +Created: 12-Aug-2002 +Python-version: 2.3 +Post-History: + + +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. + + The semi-standard idiom + + 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 + + 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) + + +Proposal + + The standard name of the 'main function' should be '__main__'. + When a module is invoked on the command line, such as + + 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): + + if globals().has_key("__main__"): + import sys as __sys + __sys.exit(__main__(__sys.argv)) + + Other modules may execute + + 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) + + +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. + + +Open Issues + + - 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(). + + - 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. + + +Copyright + + 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: