From 31f631539e87d95337ee383604f4f666aa2000d6 Mon Sep 17 00:00:00 2001 From: Nick Coghlan Date: Wed, 30 Apr 2008 14:23:36 +0000 Subject: Update command line usage documentation to reflect 2.6 changes (also includes some minor cleanups). Addresses TODO list issue 2258 --- Doc/using/cmdline.rst | 89 +++++++++++++++++++++++++++++++++++---------------- 1 file changed, 62 insertions(+), 27 deletions(-) diff --git a/Doc/using/cmdline.rst b/Doc/using/cmdline.rst index 36a8dd1..355e9ed 100644 --- a/Doc/using/cmdline.rst +++ b/Doc/using/cmdline.rst @@ -28,20 +28,25 @@ The most common use case is, of course, a simple invocation of a script:: python myscript.py +.. _using-on-interface-options: + Interface options ~~~~~~~~~~~~~~~~~ -The interpreter interface resembles that of the UNIX shell: +The interpreter interface resembles that of the UNIX shell, but provides some +additional methods of invocation: * When called with standard input connected to a tty device, it prompts for commands and executes them until an EOF (an end-of-file character, you can produce that with *Ctrl-D* on UNIX or *Ctrl-Z, Enter* on Windows) is read. * When called with a file name argument or with a file as standard input, it reads and executes a script from that file. +* When called with a directory name argument, it reads and executes an + appropriately named script from that directory. * When called with ``-c command``, it executes the Python statement(s) given as *command*. Here *command* may contain multiple statements separated by newlines. Leading whitespace is significant in Python statements! -* When called with ``-m module-name``, the given module is searched on the +* When called with ``-m module-name``, the given module is located on the Python module path and executed as a script. In non-interactive mode, the entire input is parsed before it is executed. @@ -58,25 +63,31 @@ source. normal module code. If this option is given, the first element of :data:`sys.argv` will be - ``"-c"``. + ``"-c"`` and the current directory will be added to the start of + :data:`sys.path` (allowing modules in that directory to be imported as top + level modules). .. cmdoption:: -m - Search :data:`sys.path` for the named module and run the corresponding module - file as if it were executed with ``python modulefile.py`` as a script. + Search :data:`sys.path` for the named module and execute its contents as + the :mod:`__main__` module. Since the argument is a *module* name, you must not give a file extension - (``.py``). However, the ``module-name`` does not have to be a valid Python - identifer (e.g. you can use a file name including a hyphen). + (``.py``). The ``module-name`` should be a valid Python module name, but + the implementation may not always enforce this (e.g. it may allow you to + use a name that includes a hyphen). .. note:: This option cannot be used with builtin modules and extension modules - written in C, since they do not have Python module files. + written in C, since they do not have Python module files. However, it + can still be used for precompiled modules, even if the original source + file is not available. If this option is given, the first element of :data:`sys.argv` will be the - full path to the module file. + full path to the module file. As with the :option:`-c` option, the current + directory will be added to the start of :data:`sys.path`. Many standard library modules contain code that is invoked on their execution as a script. An example is the :mod:`timeit` module:: @@ -90,34 +101,52 @@ source. :pep:`338` -- Executing modules as scripts + .. versionadded:: 2.4 + .. versionchanged:: 2.5 - The module name can now include packages. + The named module can now be located inside a package. + + +.. describe:: - + + Read commands from standard input (:data:`sys.stdin`). If standard input is + a terminal, :option:`-i` is implied. + + If this option is given, the first element of :data:`sys.argv` will be + ``"-"`` and the current directory will be added to the start of + :data:`sys.path`. .. describe::