196 lines
6.6 KiB
Plaintext
196 lines
6.6 KiB
Plaintext
PEP: 338
|
|
Title: Executing modules inside packages with '-m'
|
|
Version: $Revision$
|
|
Last-Modified: $Date$
|
|
Author: Nick Coghlan <ncoghlan@email.com>
|
|
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 <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
|
|
==========
|
|
|
|
.. [1] Special __main__() function in modules
|
|
(http://www.python.org/peps/pep-0299.html)
|
|
|
|
.. [2] Native ``-m`` execmodule support
|
|
(http://sourceforge.net/tracker/?func=detail&aid=1043356&group_id=5470&atid=305470 )
|
|
|
|
.. [3] execmodule Python Cookbook Recipe
|
|
(http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/307772)
|
|
|
|
|
|
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:
|