PEP: 299
Title: Special __main__() function in modules
Version: $Revision: 1357 $
Last-Modified: $Date: 2002-08-26 11:11:49 -0700 (Mon, 26 Aug 2002) $
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: