peps/pep-0299.txt at main · python/peps

Cannot retrieve contributors at this time

128 lines (87 sloc) 3.42 KB

	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
	==========

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


	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:

python / peps Public

peps/pep-0299.txt