diff options
Diffstat (limited to 'Doc/using/cmdline.rst')
| -rw-r--r-- | Doc/using/cmdline.rst | 89 |
1 files 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 <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 @@ 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:: <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. -.. describe:: - + 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. - 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 @@ Generic options Print a short description of all command line options. - .. versionadded:: 2.5 + .. versionchanged:: 2.5 The ``--help`` variant. @@ -138,7 +167,7 @@ Generic options Python 2.5.1 - .. versionadded:: 2.5 + .. versionchanged:: 2.5 The ``--version`` variant. @@ -302,6 +331,7 @@ Miscellaneous options thus equivalent to an omitted line number. .. seealso:: + :mod:`warnings` -- the warnings module :pep:`230` -- Warning framework @@ -358,14 +388,19 @@ These environment variables influence Python's behavior. 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 @@ if Python was configured with the :option:`--with-pydebug` build option. .. 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``. |