diff --git a/pep-0000.txt b/pep-0000.txt index ecf6876b4..f0011c343 100644 --- a/pep-0000.txt +++ b/pep-0000.txt @@ -124,6 +124,7 @@ Index by Category S 335 Overloadable Boolean Operators Ewing S 336 Make None Callable McClelland S 337 Logging Usage in the Standard Library Dubner + S 338 Executing modules inside packages with '-m' Coghlan S 754 IEEE 754 Floating Point Special Values Warnes Finished PEPs (done, implemented in CVS) @@ -370,6 +371,7 @@ Numerical Index S 335 Overloadable Boolean Operators Ewing S 336 Make None Callable McClelland S 337 Logging Usage in the Standard Library Dubner + S 338 Executing modules inside packages with '-m' Coghlan SR 666 Reject Foolish Indentation Creighton S 754 IEEE 754 Floating Point Special Values Warnes I 3000 Python 3.0 Plans Kuchling, Cannon @@ -402,6 +404,7 @@ Owners Cannon, Brett drifty@alum.berkeley.edu Carlson, Josiah jcarlson@uci.edu Carroll, W Isaac icarroll@pobox.com + Coghlan, Nick ncoghlan@email.com Cole, Dave djc@object-craft.com.au Craig, Christopher python-pep@ccraig.org Creighton, Laura lac@strakt.com diff --git a/pep-0338.txt b/pep-0338.txt new file mode 100644 index 000000000..48d56630d --- /dev/null +++ b/pep-0338.txt @@ -0,0 +1,195 @@ +PEP: 338 +Title: Executing modules inside packages with '-m' +Version: $Revision$ +Last-Modified: $Date$ +Author: Nick Coghlan +Status: Draft +Type: Standards Track +Content-Type: text/x-rst +Created: 16-Oct-2004 +Python-Version: 2.5 +Post-History: 8-Nov-2004 + + +Abstract +======== + +This PEP defines semantics for executing modules inside packages as +scripts with the ``-m`` command line switch. + +The proposed semantics are that the containing package be imported +prior to execution of the script. + + +Rationale +========= + +Python 2.4 adds the command line switch ``-m`` to allow modules to be +located using the Python module namespace for execution as scripts. +The motivating examples were standard library modules such as ``pdb`` +and ``profile``. + +A number of users and developers have requested extension of the +feature to also support running modules located inside packages. One +example provided is pychecker's ``pychecker.checker`` module. This +capability was left out of the Python 2.4 implementation because the +appropriate semantics were not entirely clear. + +The opinion on python-dev was that it was better to postpone the +extension to Python 2.5, and go through the PEP process to help make +sure we got it right. + + +Scope of this proposal +========================== + +In Python 2.4, a module located using ``-m`` is executed just as if +its filename had been provided on the command line. The goal of this +PEP is to get as close as possible to making that statement also hold +true for modules inside packages. + +Prior discussions suggest it should be noted that this PEP is **not** +about any of the following: + +- changing the idiom for making Python modules also useful as scripts + (see PEP 299 [1]_). + +- lifting the restriction of ``-m`` to modules of type PY_SOURCE or + PY_COMPILED (i.e. ``.py``, ``.pyc``, ``.pyo``,``.pyw``). + +- addressing the problem of ``-m`` not understanding zip imports or + Python's sys.metapath. + +The issues listed above are considered orthogonal to the specific +feature addressed by this PEP. + + +Current Behaviour +================= + +Before describing the new semantics, it's worth covering the existing +semantics for Python 2.4 (as they are currently defined only by the +source code). + +When ``-m`` is used on the command line, it immediately terminates the +option list (like ``-c``). The argument is interpreted as the name of +a top-level Python module (i.e. one which can be found on +``sys.path``). + +If the module is found, and is of type ``PY_SOURCE`` or +``PY_COMPILED``, then the command line is effectively reinterpreted +from ``python -m `` to ``python + ``. This includes setting ``sys.argv[0]`` correctly +(some scripts rely on this - Python's own ``regrtest.py`` is one +example). + +If the module is not found, or is not of the correct type, an error +is printed. + + +Proposed Semantics +================== + +The semantics proposed are fairly simple: if ``-m`` is used to execute +a module inside a package as a script, then the containing package is +imported before executing the module in accordance with the semantics +for a top-level module. + +This is necessary due to the way Python's import machinery locates +modules inside packages. A package may modify its own __path__ +variable during initialisation. In addition, paths may affected by +``*.pth`` files. Accordingly, the only way for Python to reliably +locate the module is by importing the containing package and +inspecting its __path__ variable. + +Note that the package is *not* imported into the ``__main__`` module's +namespace. The effects of these semantics that will be visible to the +executed module are: + +- the containing package will be in sys.modules + +- any external effects of the package initialisation (e.g. installed + import hooks, loggers, atexit handlers, etc.) + + +Reference Implementation +======================== + +A reference implementation is available on SourceForge [2]_. In this +implementation, if the ``-m`` switch fails to locate the requested +module at the top level, it effectively reinterprets the command from +``python -m