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 <options> -m <module> <args> to python <options> <filename> <args>. 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 <script> to python -m execmodule <script>. (There is one caveat: when reinterpreted in this way, sys.argv[0] may not actually contain the filename of execmodule. This only affects execmodule itself, not the requested module).

execmodule is a proposed standard library module that contains a single function (also called execmodule). When invoked as a script, this module finds and executes the module supplied as the first argument. It adjusts sys.argv by deleting sys.argv[0] and replacing the new sys.argv[0] with the module's filename instead of its Python name.

The function execmodule is like execfile, but uses the Python module namespace to locate the script instead of the filesystem. It has an additional optional argument set_argv0 which causes the filename of the located module to be written to sys.argv[0] before the module is executed.

A hybrid C/Python implementation is used as the Python module is much more flexible and extensible than the equivalent C code would be. It also allows the execmodule function to be made available. Scripts which execute other scripts (e.g. profile, pdb) have the option to use this function to provide -m style support for identifying the script to be executed.

The Python code for execmodule has also been posted as a cookbook recipe for Python 2.4 [3].

Open Issues

• choosing a name for the standard library module containing execmodule. The reference implementation uses execmodule. An alternative name proposed on python-dev is runpy.

Alternatives

The main alternative implementation considered ignored packages' __path__ variables, and looked only in the main package directory. A Python script with this behaviour can be found in the discussion of the execmodule cookbook recipe [3].

This approach was not used as it does not meet the main goal of the -m switch -- to allow the full Python namespace to be used to locate modules for execution.

References

Copyright

This document has been placed in the public domain.