[Python-Dev] Pre-PEP: Executing modules inside packages with '-m'

Nick Coghlan ncoghlan at iinet.net.au
Mon Nov 8 13:40:53 CET 2004 

A little later than planned, but I have a draft of the PEP to extend the 
-m switch to cover modules inside packages.

I will note that the SF reference implementation linked to by the PEP is 
marginally out of date - under certain circumstances (e.g. "python 
-mpychecker.checker") the current patch on SF can overwrite the C-level 
argv[0] which I've realised may not be a great idea given the existence 
of the Py_GetArgcArgv API (the PEP text describes the planned workaround).

Regards,
Nick.

-- 
Nick Coghlan               |     Brisbane, Australia
Email: ncoghlan at email.com  | Mobile: +61 409 573 268
-------------- next part --------------
PEP: XXX
Title: Executing modules inside packages with '-m'
Version: $Revision: 1.4 $
Last-Modified: $Date: 2003/09/22 04:51:50 $
Author: Nick Coghlan <ncoghlan at email.com>,
Status: Draft
Type: Standards Track
Content-Type: text/x-rst
Created: 16-Oct-2004
Python-Version: 2.5
Post-History: 16-Oct-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 are 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.

- 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.  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)


Reference Implementation
========================

A reference implementation is available on SourceForge [1]_.  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.

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


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.
However, this approach did 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] Native ``-m`` execmodule support
   (http://www.python.org/peps/pep-0009.html)

.. [2] execmodule Python Cookbook Recipe
   (http://www.python.org/peps/pep-0001.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:

More information about the Python-Dev mailing list