Pre-PEP: Executing modules inside packages with '-m'

Discussion in 'Python' started by Nick Coghlan, Dec 3, 2004.

  1. Nick Coghlan

    Nick Coghlan Guest

    Anyone playing with the CPython interpreter's new command line switch might have
    noticed that it only works with top-level modules (i.e. scripts that are
    directly on sys.path). If the script is inside a package, the invocation will
    fail with a "Module not found" error.

    This PEP is aimed at fixing that :)


    PEP: XXX
    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


    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.


    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

    - 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 ```` 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, pathing may be 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__

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


    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.


    ... [1] Special __main__() function in modules

    ... [2] Native ``-m`` execmodule support
    ( )

    ... [3] execmodule Python Cookbook Recipe


    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
    Nick Coghlan, Dec 3, 2004
    1. Advertisements

Ask a Question

Want to reply to this thread or ask your own question?

You'll need to choose a username for the site, which only take a couple of moments (here). After that, you can post your question and our members will help you out.