Move the 3k reST doc tree in place.

1 files changed, 248 insertions, 0 deletions

diff --git a/Doc/tutorial/interpreter.rst b/Doc/tutorial/interpreter.rst
new file mode 100644
index 0000000..8b42090
--- /dev/null
+++ b/Doc/tutorial/interpreter.rst
@@ -0,0 +1,248 @@
+.. _tut-using:
+
+****************************
+Using the Python Interpreter
+****************************
+
+
+.. _tut-invoking:
+
+Invoking the Interpreter
+========================
+
+The Python interpreter is usually installed as :file:`/usr/local/bin/python` on
+those machines where it is available; putting :file:`/usr/local/bin` in your
+Unix shell's search path makes it possible to start it by typing the command ::
+
+   python
+
+to the shell.  Since the choice of the directory where the interpreter lives is
+an installation option, other places are possible; check with your local Python
+guru or system administrator.  (E.g., :file:`/usr/local/python` is a popular
+alternative location.)
+
+On Windows machines, the Python installation is usually placed in
+:file:`C:\Python30`, though you can change this when you're running the
+installer.  To add this directory to your path,  you can type the following
+command into the command prompt in a DOS box::
+
+   set path=%path%;C:\python30
+
+Typing an end-of-file character (:kbd:`Control-D` on Unix, :kbd:`Control-Z` on
+Windows) at the primary prompt causes the interpreter to exit with a zero exit
+status.  If that doesn't work, you can exit the interpreter by typing the
+following commands: ``import sys; sys.exit()``.
+
+The interpreter's line-editing features usually aren't very sophisticated.  On
+Unix, whoever installed the interpreter may have enabled support for the GNU
+readline library, which adds more elaborate interactive editing and history
+features. Perhaps the quickest check to see whether command line editing is
+supported is typing Control-P to the first Python prompt you get.  If it beeps,
+you have command line editing; see Appendix :ref:`tut-interacting` for an
+introduction to the keys.  If nothing appears to happen, or if ``^P`` is echoed,
+command line editing isn't available; you'll only be able to use backspace to
+remove characters from the current line.
+
+The interpreter operates somewhat like the Unix shell: when called with standard
+input connected to a tty device, it reads and executes commands interactively;
+when called with a file name argument or with a file as standard input, it reads
+and executes a *script* from that file.
+
+A second way of starting the interpreter is ``python -c command [arg] ...``,
+which executes the statement(s) in *command*, analogous to the shell's
+:option:`-c` option.  Since Python statements often contain spaces or other
+characters that are special to the shell, it is best to quote  *command* in its
+entirety with double quotes.
+
+Some Python modules are also useful as scripts.  These can be invoked using
+``python -m module [arg] ...``, which executes the source file for *module* as
+if you had spelled out its full name on the command line.
+
+Note that there is a difference between ``python file`` and ``python <file``.
+In the latter case, input requests from the program, such as calling
+``sys.stdin.read()``, are satisfied from *file*.  Since this file has already
+been read until the end by the parser before the program starts executing, the
+program will encounter end-of-file immediately.  In the former case (which is
+usually what you want) they are satisfied from whatever file or device is
+connected to standard input of the Python interpreter.
+
+When a script file is used, it is sometimes useful to be able to run the script
+and enter interactive mode afterwards.  This can be done by passing :option:`-i`
+before the script.  (This does not work if the script is read from standard
+input, for the same reason as explained in the previous paragraph.)
+
+
+.. _tut-argpassing:
+
+Argument Passing
+----------------
+
+When known to the interpreter, the script name and additional arguments
+thereafter are passed to the script in the variable ``sys.argv``, which is a
+list of strings.  Its length is at least one; when no script and no arguments
+are given, ``sys.argv[0]`` is an empty string.  When the script name is given as
+``'-'`` (meaning  standard input), ``sys.argv[0]`` is set to ``'-'``.  When
+:option:`-c` *command* is used, ``sys.argv[0]`` is set to ``'-c'``.  When
+:option:`-m` *module* is used, ``sys.argv[0]``  is set to the full name of the
+located module.  Options found after  :option:`-c` *command* or :option:`-m`
+*module* are not consumed  by the Python interpreter's option processing but
+left in ``sys.argv`` for  the command or module to handle.
+
+
+.. _tut-interactive:
+
+Interactive Mode
+----------------
+
+When commands are read from a tty, the interpreter is said to be in *interactive
+mode*.  In this mode it prompts for the next command with the *primary prompt*,
+usually three greater-than signs (``>>>``); for continuation lines it prompts
+with the *secondary prompt*, by default three dots (``...``). The interpreter
+prints a welcome message stating its version number and a copyright notice
+before printing the first prompt::
+
+   python
+   Python 1.5.2b2 (#1, Feb 28 1999, 00:02:06)  [GCC 2.8.1] on sunos5
+   Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam
+   >>>
+
+Continuation lines are needed when entering a multi-line construct. As an
+example, take a look at this :keyword:`if` statement::
+
+   >>> the_world_is_flat = 1
+   >>> if the_world_is_flat:
+   ...     print "Be careful not to fall off!"
+   ... 
+   Be careful not to fall off!
+
+
+.. _tut-interp:
+
+The Interpreter and Its Environment
+===================================
+
+
+.. _tut-error:
+
+Error Handling
+--------------
+
+When an error occurs, the interpreter prints an error message and a stack trace.
+In interactive mode, it then returns to the primary prompt; when input came from
+a file, it exits with a nonzero exit status after printing the stack trace.
+(Exceptions handled by an :keyword:`except` clause in a :keyword:`try` statement
+are not errors in this context.)  Some errors are unconditionally fatal and
+cause an exit with a nonzero exit; this applies to internal inconsistencies and
+some cases of running out of memory.  All error messages are written to the
+standard error stream; normal output from executed commands is written to
+standard output.
+
+Typing the interrupt character (usually Control-C or DEL) to the primary or
+secondary prompt cancels the input and returns to the primary prompt. [#]_
+Typing an interrupt while a command is executing raises the
+:exc:`KeyboardInterrupt` exception, which may be handled by a :keyword:`try`
+statement.
+
+
+.. _tut-scripts:
+
+Executable Python Scripts
+-------------------------
+
+On BSD'ish Unix systems, Python scripts can be made directly executable, like
+shell scripts, by putting the line ::
+
+   #! /usr/bin/env python
+
+(assuming that the interpreter is on the user's :envvar:`PATH`) at the beginning
+of the script and giving the file an executable mode.  The ``#!`` must be the
+first two characters of the file.  On some platforms, this first line must end
+with a Unix-style line ending (``'\n'``), not a Mac OS (``'\r'``) or Windows
+(``'\r\n'``) line ending.  Note that the hash, or pound, character, ``'#'``, is
+used to start a comment in Python.
+
+The script can be given an executable mode, or permission, using the
+:program:`chmod` command::
+
+   $ chmod +x myscript.py
+
+
+Source Code Encoding
+--------------------
+
+It is possible to use encodings different than ASCII in Python source files. The
+best way to do it is to put one more special comment line right after the ``#!``
+line to define the source file encoding::
+
+   # -*- coding: encoding -*- 
+
+
+With that declaration, all characters in the source file will be treated as
+having the encoding *encoding*, and it will be possible to directly write
+Unicode string literals in the selected encoding.  The list of possible
+encodings can be found in the Python Library Reference, in the section on
+:mod:`codecs`.
+
+For example, to write Unicode literals including the Euro currency symbol, the
+ISO-8859-15 encoding can be used, with the Euro symbol having the ordinal value
+164.  This script will print the value 8364 (the Unicode codepoint corresponding
+to the Euro symbol) and then exit::
+
+   # -*- coding: iso-8859-15 -*-
+
+   currency = u"€"
+   print ord(currency)
+
+If your editor supports saving files as ``UTF-8`` with a UTF-8 *byte order mark*
+(aka BOM), you can use that instead of an encoding declaration. IDLE supports
+this capability if ``Options/General/Default Source Encoding/UTF-8`` is set.
+Notice that this signature is not understood in older Python releases (2.2 and
+earlier), and also not understood by the operating system for script files with
+``#!`` lines (only used on Unix systems).
+
+By using UTF-8 (either through the signature or an encoding declaration),
+characters of most languages in the world can be used simultaneously in string
+literals and comments.  Using non-ASCII characters in identifiers is not
+supported. To display all these characters properly, your editor must recognize
+that the file is UTF-8, and it must use a font that supports all the characters
+in the file.
+
+
+.. _tut-startup:
+
+The Interactive Startup File
+----------------------------
+
+When you use Python interactively, it is frequently handy to have some standard
+commands executed every time the interpreter is started.  You can do this by
+setting an environment variable named :envvar:`PYTHONSTARTUP` to the name of a
+file containing your start-up commands.  This is similar to the :file:`.profile`
+feature of the Unix shells.
+
+.. % XXX This should probably be dumped in an appendix, since most people
+.. % don't use Python interactively in non-trivial ways.
+
+This file is only read in interactive sessions, not when Python reads commands
+from a script, and not when :file:`/dev/tty` is given as the explicit source of
+commands (which otherwise behaves like an interactive session).  It is executed
+in the same namespace where interactive commands are executed, so that objects
+that it defines or imports can be used without qualification in the interactive
+session. You can also change the prompts ``sys.ps1`` and ``sys.ps2`` in this
+file.
+
+If you want to read an additional start-up file from the current directory, you
+can program this in the global start-up file using code like ``if
+os.path.isfile('.pythonrc.py'): exec(open('.pythonrc.py').read())``.
+If you want to use the startup file in a script, you must do this explicitly
+in the script::
+
+   import os
+   filename = os.environ.get('PYTHONSTARTUP')
+   if filename and os.path.isfile(filename):
+       exec(open(filename).read())
+
+
+.. rubric:: Footnotes
+
+.. [#] A problem with the GNU Readline package may prevent this.
+