PEP 299, Special __main__() function in modules, Jeff Epler

pep-0299.txt

@@ -0,0 +1,106 @@
+PEP: 299
+Title: Special __main__() function in modules
+Version: $Revision$
+Last-Modified: $Date$
+Author: Jeff Epler <jepler@unpythonic.net>
+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: