[Python-checkins] r62593 - python/trunk/Doc/using/cmdline.rst

Wed Apr 30 16:23:36 CEST 2008

Author: nick.coghlan
Date: Wed Apr 30 16:23:36 2008
New Revision: 62593
Log:
Update command line usage documentation to reflect 2.6 changes (also includes some minor cleanups). Addresses TODO list issue 2258
Modified:
 python/trunk/Doc/using/cmdline.rst
Modified: python/trunk/Doc/using/cmdline.rst
==============================================================================

--- python/trunk/Doc/using/cmdline.rst	(original)
+++ python/trunk/Doc/using/cmdline.rst	Wed Apr 30 16:23:36 2008
@@ -28,20 +28,25 @@
 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 @@
 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 <module-name>
 
- 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 @@
 
 :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:: <script>
 
- Execute the Python code contained in *script*, which must be an (absolute or
- relative) file name.
+ Execute the Python code contained in *script*, which must be a filesystem
+ path (absolute or relative) referring to either a Python file, a directory
+ containing a ``__main__.py`` file, or a zipfile containing a
+ ``__main__.py`` file.
 
 If this option is given, the first element of :data:`sys.argv` will be the
- script file name as given on the command line.
+ script name as given on the command line.
 
+ If the script name refers directly to a Python file, the directory
+ containing that file is added to the start of :data:`sys.path`, and the
+ file is executed as the :mod:`__main__` module.
+
+ If the script name refers to a directory or zipfile, the script name is
+ added to the start of :data:`sys.path` and the ``__main__.py`` file in
+ that location is executed as the :mod:`__main__` module.
 
-.. describe:: -
-
- Read commands from standard input (:data:`sys.stdin`). If standard input is
- a terminal, :option:`-i` is implied.
+ .. versionchanged:: 2.5
+ Directories and zipfiles containing a ``__main__.py`` file at the top
+ level are now considered valid Python scripts.
 
- If this option is given, the first element of :data:`sys.argv` will be
- ``"-"``.
+If no interface option is given, :option:`-i` is implied, ``sys.argv[0]`` is
+an empty string (``""``) and the current directory will be added to the
+start of :data:`sys.path`.
 
 .. seealso:: 
 :ref:`tut-invoking`
 
 
-If no script name is given, ``sys.argv[0]`` is an empty string (``""``).
-
-
 Generic options
 ~~~~~~~~~~~~~~~
 
@@ -127,7 +156,7 @@
 
 Print a short description of all command line options.
 
- .. versionadded:: 2.5
+ .. versionchanged:: 2.5
 The ``--help`` variant.
 
 
@@ -138,7 +167,7 @@
 
 Python 2.5.1
 
- .. versionadded:: 2.5
+ .. versionchanged:: 2.5
 The ``--version`` variant.
 
 
@@ -302,6 +331,7 @@
 thus equivalent to an omitted line number.
 
 .. seealso::
+ :mod:`warnings` -- the warnings module
 
 :pep:`230` -- Warning framework
 
@@ -358,14 +388,19 @@
 the shell's :envvar:`PATH`: one or more directory pathnames separated by
 :data:`os.pathsep` (e.g. colons on Unix or semicolons on Windows).
 Non-existent directories are silently ignored.
+
+ In addition to normal directories, individual :envvar:`PYTHONPATH` entries
+ may refer to zipfiles containing pure Python modules (in either source or
+ compiled form). Extension modules cannot be imported from zipfiles.
 
 The default search path is installation dependent, but generally begins with
 :file:`{prefix}/lib/python{version}`` (see :envvar:`PYTHONHOME` above). It
 is *always* appended to :envvar:`PYTHONPATH`.
 
- If a script argument is given, the directory containing the script is
- inserted in the path in front of :envvar:`PYTHONPATH`. The search path can
- be manipulated from within a Python program as the variable :data:`sys.path`.
+ An additional directory will be inserted in the search path in front of
+ :envvar:`PYTHONPATH` as described above under
+ :ref:`using-on-interface-options`. The search path can be manipulated from
+ within a Python program as the variable :data:`sys.path`.
 
 
 .. envvar:: PYTHONSTARTUP
@@ -451,7 +486,7 @@
 
 .. envvar:: PYTHONTHREADDEBUG
 
- If set, Python will print debug threading debug info.
+ If set, Python will print threading debug info.
 
 .. versionchanged:: 2.6
 Previously, this variable was called ``THREADDEBUG``.
