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

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

  1. Nick Coghlan

    Nick Coghlan Guest

    Python 2.4's -m command line switch only works for modules directly on sys.path.
    Trying to use it with modules inside packages will fail with a "Module not
    found" error. This PEP aims to fix that for Python 2.5.

    Previously, posting of a draft version of the PEP to python-dev and python-list
    didn't actually generate any responses. I'm not sure if that's an indication
    that people don't see the restriction to top-level modules as a problem (and
    hence think the PEP is unecessary), or think the extension to handle packages is
    obvious (and hence see no need to comment).

    Or, it could just be a sign that Python 2.4 hasn't been out long enough for
    anyone to care what I'm yabbering on about :)

    Anyway, all comments are appreciated (even a simple "Sounds good to me").


    PEP: 338
    Title: Executing modules inside packages with '-m'
    Version: $Revision: 1.2 $
    Last-Modified: $Date: 2004/12/11 20:31:10 $
    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 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

    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

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


    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 12, 2004
    1. Advertisements

  2. Nick Coghlan

    alia_khouri Guest

    A useful feature that is a logical extension of current '-m' behaviour.
    (I'm actually surprised it was left out in the first place)

    This will definitely allow me and other python programmers to package
    our scripts better

    Sounds Good to me. (-;

    Thank you for the PEP

    alia_khouri, Dec 12, 2004
    1. Advertisements

  3. Nick Coghlan

    Nick Coghlan Guest

    That seems to be a common reaction :)

    It was dropped for 2.4 because I wasn't sure exactly how it should work, and 2.4
    was already in beta at the time. So I went with the cookbook recipe instead.

    Nick Coghlan, Dec 12, 2004
  4. Nick Coghlan

    richard Guest

    /me too :)

    richard, Dec 12, 2004
  5. puzzling.

    I'd say that for a typical user,

    $ python -m arg

    is a marginal improvement over

    $ python -c "import" arg

    compared to

    $ bar arg

    Fredrik Lundh, Dec 12, 2004
  6. Nick Coghlan

    Nick Coghlan Guest

    This doesn't work. Any code protected by "if __name__ == '__main__':" won't run
    in this context (since '' is being imported as a module, not run as a

    Even 'python -c "from import _main; _main()" arg' isn't quite right,
    since sys.argv[0] will be wrong (it will say '-c', instead of giving the
    module's filename). There's also the problem that there is no standard idiom for
    _main() functions.
    This is true, but it has its own problems, mainly in the area of namespace
    conflicts on the packaging side:

    1. Namespace conflicts between different Python versions
    2. Namespace conflicts between different Python packages
    3. Namespace conflicts between Python packages and other programs
    4. Additional overhead to create an installed module that is usable as a script
    a. Add a shebang line for *nix style systems
    b. Think about how to deal with the previous 3 points
    c. Update the installer to copy the file to the right place with a good name
    d. Realise you're screwed on Windows, since you can't control the file
    associations and the script will always run with the default interpreter.

    An extended -m, on the other hand deals with all those problems automatically:

    python -m arg # Default interpreter, foo's bar
    python -m arg # Default interpreter, bar's bar
    python24 -m arg # Force Python 2.4, foo's bar
    python24 -m arg # Force Python 2.4, bar's bar
    bar arg # Unrelated application called bar

    Points 1, 3 & 4 were the justification for adding the current version of -m to
    Python 2.4 (obviously, point 2 didn't apply, since the current version doesn't
    work for modules insides packages). Specifically, it makes it trivial to get
    hold of the right version of pdb and profile for the interpreter you're working

    For usability, you can hide all of the above behind a menu item or desktop
    shortcut. However, the major target of the feature is Python developers rather
    than the end-users of applications built using Python.

    Nick Coghlan, Dec 13, 2004
  7. I appreciate that you're taking the time to teach me about Python, but I can
    assure you that it's not really needed.

    as for the rest of your arguments, I have to assume that you were joking. (or
    that you have no experience whatsoever of distribution of Python programs in
    Unix and Windows environments).

    Fredrik Lundh, Dec 13, 2004
  8. Nick Coghlan

    Just Guest

    Neither is the sarcasm.
    Whatever. You suggestion does not work in many cases. How about a
    program that starts threads? Can't do that as a side effect of import.

    Just, Dec 14, 2004
  9. Just wrote:

    my suggestion was to make sure that the user can type "bar arg" to start a
    Python program called "bar" with the argument "arg". that's trivial, on all
    major platforms, despite what Nick says -- and yes, you can start threads
    from a program named "bar". try it.

    Fredrik Lundh, Dec 14, 2004
  10. Nick Coghlan

    Just Guest

    This subthread was specifically about your

    python -c "import" arg


    Just, Dec 14, 2004
  11. Nick Coghlan

    Nick Coghlan Guest

    The command line switch came out of a pydev discussion regarding making pdb and
    profile easy to run for developers using multiple versions of Python on the same
    computer (e.g. someone running a Python 2.3 default installation, a Python 2.4
    alpha alternate installation and a Python build from CVS).

    Making a *single* version of an end-user application available on a platform is,
    as you say, quite straightforward. Versioning issues may need to be considered,
    but they're usually limited to making sure you get the 'right' Python out of any
    which are available on the machine.

    And for an application, especially one not aimed at developers, that's almost
    certainly the right road to take. You'll have a name already, and presumably a
    versioning system as well (I believe dist_utils provides something along those

    Making a Python-version specific developer tool easily accessible isn't quite as
    straightforward, since you need to deal with making multiple versions available
    simultaneously, and each version has a different definition of the 'right'
    interpreter. As happened in the standard library with pdb and profile, the
    result is often to just not bother with it - leaving the developer to specify
    the full path to the particular version they want to run. That is, quite
    frankly, a pain - the same info is getting specified twice (once in selecting
    the python version to run, and again in specifying the full path to the
    associated tool)

    One of the options explored in the original pydev discussion that led to '-m'
    was standalone, executable scripts for pdb and profile. The major issue with
    that idea was that it didn't scale very well - to use that solution for any
    other potentially useful scripts in the standard library, we would have had to
    come up with a decent name for each one, and then apply whatever versioning
    mechanism we settled on.

    Using the Python module namespace to find the script means that all the
    versioning issues are already taken care of by the Python interpreters own
    versioning system - whichever version of Python you specify in the command line
    invocation, you get the correct version of the tool for that version of Python.
    It has the added bonus of working not only for pdb and profile, but any other
    scripts which are found to be useful (even those in extension packages, if this
    PEP is accepted by the BDFL).


    P.S. As you might have guessed from the above, it's not the least bit
    coincidental that the example scripts I generally use when discussing '-m' are
    pdb, profile and pychecker.checker. This feature is a convenience for command
    line junkies - which seems to be a fairly common trait amongst the developers I
    know :)
    Nick Coghlan, Dec 14, 2004
  12. in my original post, I said

    I'd say that for a typical user, "A" is a marginal improvement over
    "B", compared to "C".

    which, I thought, tried to say that for a user expecting "C", neither "A" nor "B"
    is good enough.

    Fredrik Lundh, Dec 14, 2004
  13. Nick Coghlan

    Nick Coghlan Guest

    Ah, OK - that makes a lot more sense than the way I read it (it looked to me as
    if you expected option B to do the same thing as option A. It didn't seem likely
    you really believed that, but that was the only interpretation I saw at the time).

    Anyway, as my other rambling message points out (eventually) - this feature is
    intended for developers and Python version specific utility scripts like pdb,
    profile and pychecker.checker, rather than launch scripts for full applications.

    For end users, I agree with you wholeheartedly - applications should behave like
    applications, no matter what language they're written in :)

    Nick Coghlan, Dec 14, 2004
  14. Nick Coghlan

    Martin Bless Guest

    On my Windows machine this command line switch really makes my life so
    much easier. I appreciate -m very much. Going further as proposed in
    PEP 338 sounds good to me.

    One thing I stumbled across with the current implementation:

    Why doesn't "python -m abc" work with


    assuming ./abc/ is directly on the path? In analogy to normal module

    mb - Martin
    Martin Bless, Dec 14, 2004
  15. if you use windows, chances are that what you really want is exemaker...

    Fredrik Lundh, Dec 14, 2004
  16. Nick Coghlan

    Nick Coghlan Guest

    It doesn't work because abc is a package, rather than a module. There are lots
    of things that work as modules for import, but can't be used directly as scripts
    (builtin modules, C extension modules, packages, frozen modules, etc)

    The command line "python ./abc" doesn't work, either - the closest you get is
    "python ./abc/".

    This is one of the things mentioned in the PEP - the restriction to Python
    source code or compiled bytecode is explicit, in order to match the existing
    command line behaviour. Even implementation of the PEP won't allow "python -m
    abc" to work.

    However, with PEP 338, "pep -m abc.__init__" will actually try to run the
    package initialisation code as a script, simply due to the way imp.find_module
    works. Whether that does anything sane is up to the package author. Something to
    realise is that, in this case, actually gets run twice - once for
    the package import, and then again as a script.

    Nick Coghlan, Dec 15, 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.