added PEP 338, , by
This commit is contained in:
David Goodger
parent
9844a8b7c7
commit
5514470bdf
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -0,0 +1,195 @@
|
|||
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:
|
||||
Loading…
Reference in New Issue