PEP: 299 Title: Special __main__() function in modules Version:
$Revision$ 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.

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.

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."

References

Copyright

This document has been placed in the public domain.

[1] Georg Brandl, "What about PEP 299",
https://mail.python.org/pipermail/python-dev/2006-March/062951.html