Move the 3k reST doc tree in place.
diff --git a/Doc/library/sys.rst b/Doc/library/sys.rst
new file mode 100644
index 0000000..5184c25
--- /dev/null
+++ b/Doc/library/sys.rst
@@ -0,0 +1,606 @@
+
+:mod:`sys` --- System-specific parameters and functions
+=======================================================
+
+.. module:: sys
+ :synopsis: Access system-specific parameters and functions.
+
+
+This module provides access to some variables used or maintained by the
+interpreter and to functions that interact strongly with the interpreter. It is
+always available.
+
+
+.. data:: argv
+
+ The list of command line arguments passed to a Python script. ``argv[0]`` is the
+ script name (it is operating system dependent whether this is a full pathname or
+ not). If the command was executed using the :option:`-c` command line option to
+ the interpreter, ``argv[0]`` is set to the string ``'-c'``. If no script name
+ was passed to the Python interpreter, ``argv[0]`` is the empty string.
+
+ To loop over the standard input, or the list of files given on the
+ command line, see the :mod:`fileinput` module.
+
+
+.. data:: byteorder
+
+ An indicator of the native byte order. This will have the value ``'big'`` on
+ big-endian (most-significant byte first) platforms, and ``'little'`` on
+ little-endian (least-significant byte first) platforms.
+
+ .. versionadded:: 2.0
+
+
+.. data:: subversion
+
+ A triple (repo, branch, version) representing the Subversion information of the
+ Python interpreter. *repo* is the name of the repository, ``'CPython'``.
+ *branch* is a string of one of the forms ``'trunk'``, ``'branches/name'`` or
+ ``'tags/name'``. *version* is the output of ``svnversion``, if the interpreter
+ was built from a Subversion checkout; it contains the revision number (range)
+ and possibly a trailing 'M' if there were local modifications. If the tree was
+ exported (or svnversion was not available), it is the revision of
+ ``Include/patchlevel.h`` if the branch is a tag. Otherwise, it is ``None``.
+
+ .. versionadded:: 2.5
+
+
+.. data:: builtin_module_names
+
+ A tuple of strings giving the names of all modules that are compiled into this
+ Python interpreter. (This information is not available in any other way ---
+ ``modules.keys()`` only lists the imported modules.)
+
+
+.. data:: copyright
+
+ A string containing the copyright pertaining to the Python interpreter.
+
+
+.. function:: _current_frames()
+
+ Return a dictionary mapping each thread's identifier to the topmost stack frame
+ currently active in that thread at the time the function is called. Note that
+ functions in the :mod:`traceback` module can build the call stack given such a
+ frame.
+
+ This is most useful for debugging deadlock: this function does not require the
+ deadlocked threads' cooperation, and such threads' call stacks are frozen for as
+ long as they remain deadlocked. The frame returned for a non-deadlocked thread
+ may bear no relationship to that thread's current activity by the time calling
+ code examines the frame.
+
+ This function should be used for internal and specialized purposes only.
+
+ .. versionadded:: 2.5
+
+
+.. data:: dllhandle
+
+ Integer specifying the handle of the Python DLL. Availability: Windows.
+
+
+.. function:: displayhook(value)
+
+ If *value* is not ``None``, this function prints it to ``sys.stdout``, and saves
+ it in ``__builtin__._``.
+
+ ``sys.displayhook`` is called on the result of evaluating an expression entered
+ in an interactive Python session. The display of these values can be customized
+ by assigning another one-argument function to ``sys.displayhook``.
+
+
+.. function:: excepthook(type, value, traceback)
+
+ This function prints out a given traceback and exception to ``sys.stderr``.
+
+ When an exception is raised and uncaught, the interpreter calls
+ ``sys.excepthook`` with three arguments, the exception class, exception
+ instance, and a traceback object. In an interactive session this happens just
+ before control is returned to the prompt; in a Python program this happens just
+ before the program exits. The handling of such top-level exceptions can be
+ customized by assigning another three-argument function to ``sys.excepthook``.
+
+
+.. data:: __displayhook__
+ __excepthook__
+
+ These objects contain the original values of ``displayhook`` and ``excepthook``
+ at the start of the program. They are saved so that ``displayhook`` and
+ ``excepthook`` can be restored in case they happen to get replaced with broken
+ objects.
+
+
+.. function:: exc_info()
+
+ This function returns a tuple of three values that give information about the
+ exception that is currently being handled. The information returned is specific
+ both to the current thread and to the current stack frame. If the current stack
+ frame is not handling an exception, the information is taken from the calling
+ stack frame, or its caller, and so on until a stack frame is found that is
+ handling an exception. Here, "handling an exception" is defined as "executing
+ or having executed an except clause." For any stack frame, only information
+ about the most recently handled exception is accessible.
+
+ .. index:: object: traceback
+
+ If no exception is being handled anywhere on the stack, a tuple containing three
+ ``None`` values is returned. Otherwise, the values returned are ``(type, value,
+ traceback)``. Their meaning is: *type* gets the exception type of the exception
+ being handled (a class object); *value* gets the exception parameter (its
+ :dfn:`associated value` or the second argument to :keyword:`raise`, which is
+ always a class instance if the exception type is a class object); *traceback*
+ gets a traceback object (see the Reference Manual) which encapsulates the call
+ stack at the point where the exception originally occurred.
+
+ .. warning::
+
+ Assigning the *traceback* return value to a local variable in a function that is
+ handling an exception will cause a circular reference. This will prevent
+ anything referenced by a local variable in the same function or by the traceback
+ from being garbage collected. Since most functions don't need access to the
+ traceback, the best solution is to use something like ``exctype, value =
+ sys.exc_info()[:2]`` to extract only the exception type and value. If you do
+ need the traceback, make sure to delete it after use (best done with a
+ :keyword:`try` ... :keyword:`finally` statement) or to call :func:`exc_info` in
+ a function that does not itself handle an exception.
+
+ .. note::
+
+ Beginning with Python 2.2, such cycles are automatically reclaimed when garbage
+ collection is enabled and they become unreachable, but it remains more efficient
+ to avoid creating cycles.
+
+
+.. data:: exec_prefix
+
+ A string giving the site-specific directory prefix where the platform-dependent
+ Python files are installed; by default, this is also ``'/usr/local'``. This can
+ be set at build time with the :option:`--exec-prefix` argument to the
+ :program:`configure` script. Specifically, all configuration files (e.g. the
+ :file:`pyconfig.h` header file) are installed in the directory ``exec_prefix +
+ '/lib/pythonversion/config'``, and shared library modules are installed in
+ ``exec_prefix + '/lib/pythonversion/lib-dynload'``, where *version* is equal to
+ ``version[:3]``.
+
+
+.. data:: executable
+
+ A string giving the name of the executable binary for the Python interpreter, on
+ systems where this makes sense.
+
+
+.. function:: exit([arg])
+
+ Exit from Python. This is implemented by raising the :exc:`SystemExit`
+ exception, so cleanup actions specified by finally clauses of :keyword:`try`
+ statements are honored, and it is possible to intercept the exit attempt at an
+ outer level. The optional argument *arg* can be an integer giving the exit
+ status (defaulting to zero), or another type of object. If it is an integer,
+ zero is considered "successful termination" and any nonzero value is considered
+ "abnormal termination" by shells and the like. Most systems require it to be in
+ the range 0-127, and produce undefined results otherwise. Some systems have a
+ convention for assigning specific meanings to specific exit codes, but these are
+ generally underdeveloped; Unix programs generally use 2 for command line syntax
+ errors and 1 for all other kind of errors. If another type of object is passed,
+ ``None`` is equivalent to passing zero, and any other object is printed to
+ ``sys.stderr`` and results in an exit code of 1. In particular,
+ ``sys.exit("some error message")`` is a quick way to exit a program when an
+ error occurs.
+
+
+.. function:: getcheckinterval()
+
+ Return the interpreter's "check interval"; see :func:`setcheckinterval`.
+
+ .. versionadded:: 2.3
+
+
+.. function:: getdefaultencoding()
+
+ Return the name of the current default string encoding used by the Unicode
+ implementation.
+
+ .. versionadded:: 2.0
+
+
+.. function:: getdlopenflags()
+
+ Return the current value of the flags that are used for :cfunc:`dlopen` calls.
+ The flag constants are defined in the :mod:`dl` and :mod:`DLFCN` modules.
+ Availability: Unix.
+
+ .. versionadded:: 2.2
+
+
+.. function:: getfilesystemencoding()
+
+ Return the name of the encoding used to convert Unicode filenames into system
+ file names, or ``None`` if the system default encoding is used. The result value
+ depends on the operating system:
+
+ * On Windows 9x, the encoding is "mbcs".
+
+ * On Mac OS X, the encoding is "utf-8".
+
+ * On Unix, the encoding is the user's preference according to the result of
+ nl_langinfo(CODESET), or :const:`None` if the ``nl_langinfo(CODESET)`` failed.
+
+ * On Windows NT+, file names are Unicode natively, so no conversion is
+ performed. :func:`getfilesystemencoding` still returns ``'mbcs'``, as this is
+ the encoding that applications should use when they explicitly want to convert
+ Unicode strings to byte strings that are equivalent when used as file names.
+
+ .. versionadded:: 2.3
+
+
+.. function:: getrefcount(object)
+
+ Return the reference count of the *object*. The count returned is generally one
+ higher than you might expect, because it includes the (temporary) reference as
+ an argument to :func:`getrefcount`.
+
+
+.. function:: getrecursionlimit()
+
+ Return the current value of the recursion limit, the maximum depth of the Python
+ interpreter stack. This limit prevents infinite recursion from causing an
+ overflow of the C stack and crashing Python. It can be set by
+ :func:`setrecursionlimit`.
+
+
+.. function:: _getframe([depth])
+
+ Return a frame object from the call stack. If optional integer *depth* is
+ given, return the frame object that many calls below the top of the stack. If
+ that is deeper than the call stack, :exc:`ValueError` is raised. The default
+ for *depth* is zero, returning the frame at the top of the call stack.
+
+ This function should be used for internal and specialized purposes only.
+
+
+.. function:: getwindowsversion()
+
+ Return a tuple containing five components, describing the Windows version
+ currently running. The elements are *major*, *minor*, *build*, *platform*, and
+ *text*. *text* contains a string while all other values are integers.
+
+ *platform* may be one of the following values:
+
+ +-----------------------------------------+-----------------------+
+ | Constant | Platform |
+ +=========================================+=======================+
+ | :const:`0 (VER_PLATFORM_WIN32s)` | Win32s on Windows 3.1 |
+ +-----------------------------------------+-----------------------+
+ | :const:`1 (VER_PLATFORM_WIN32_WINDOWS)` | Windows 95/98/ME |
+ +-----------------------------------------+-----------------------+
+ | :const:`2 (VER_PLATFORM_WIN32_NT)` | Windows NT/2000/XP |
+ +-----------------------------------------+-----------------------+
+ | :const:`3 (VER_PLATFORM_WIN32_CE)` | Windows CE |
+ +-----------------------------------------+-----------------------+
+
+ This function wraps the Win32 :cfunc:`GetVersionEx` function; see the Microsoft
+ documentation for more information about these fields.
+
+ Availability: Windows.
+
+ .. versionadded:: 2.3
+
+
+.. data:: hexversion
+
+ The version number encoded as a single integer. This is guaranteed to increase
+ with each version, including proper support for non-production releases. For
+ example, to test that the Python interpreter is at least version 1.5.2, use::
+
+ if sys.hexversion >= 0x010502F0:
+ # use some advanced feature
+ ...
+ else:
+ # use an alternative implementation or warn the user
+ ...
+
+ This is called ``hexversion`` since it only really looks meaningful when viewed
+ as the result of passing it to the built-in :func:`hex` function. The
+ ``version_info`` value may be used for a more human-friendly encoding of the
+ same information.
+
+ .. versionadded:: 1.5.2
+
+
+.. function:: intern(string)
+
+ Enter *string* in the table of "interned" strings and return the interned string
+ -- which is *string* itself or a copy. Interning strings is useful to gain a
+ little performance on dictionary lookup -- if the keys in a dictionary are
+ interned, and the lookup key is interned, the key comparisons (after hashing)
+ can be done by a pointer compare instead of a string compare. Normally, the
+ names used in Python programs are automatically interned, and the dictionaries
+ used to hold module, class or instance attributes have interned keys.
+
+ .. versionchanged:: 2.3
+ Interned strings are not immortal (like they used to be in Python 2.2 and
+ before); you must keep a reference to the return value of :func:`intern` around
+ to benefit from it.
+
+
+.. data:: last_type
+ last_value
+ last_traceback
+
+ These three variables are not always defined; they are set when an exception is
+ not handled and the interpreter prints an error message and a stack traceback.
+ Their intended use is to allow an interactive user to import a debugger module
+ and engage in post-mortem debugging without having to re-execute the command
+ that caused the error. (Typical use is ``import pdb; pdb.pm()`` to enter the
+ post-mortem debugger; see chapter :ref:`debugger` for
+ more information.)
+
+ The meaning of the variables is the same as that of the return values from
+ :func:`exc_info` above. (Since there is only one interactive thread,
+ thread-safety is not a concern for these variables, unlike for ``exc_type``
+ etc.)
+
+
+.. data:: maxint
+
+ The largest positive integer supported by Python's regular integer type. This
+ is at least 2\*\*31-1. The largest negative integer is ``-maxint-1`` --- the
+ asymmetry results from the use of 2's complement binary arithmetic.
+
+
+.. data:: maxunicode
+
+ An integer giving the largest supported code point for a Unicode character. The
+ value of this depends on the configuration option that specifies whether Unicode
+ characters are stored as UCS-2 or UCS-4.
+
+
+.. data:: modules
+
+ This is a dictionary that maps module names to modules which have already been
+ loaded. This can be manipulated to force reloading of modules and other tricks.
+
+
+.. data:: path
+
+ .. index:: triple: module; search; path
+
+ A list of strings that specifies the search path for modules. Initialized from
+ the environment variable :envvar:`PYTHONPATH`, plus an installation-dependent
+ default.
+
+ As initialized upon program startup, the first item of this list, ``path[0]``,
+ is the directory containing the script that was used to invoke the Python
+ interpreter. If the script directory is not available (e.g. if the interpreter
+ is invoked interactively or if the script is read from standard input),
+ ``path[0]`` is the empty string, which directs Python to search modules in the
+ current directory first. Notice that the script directory is inserted *before*
+ the entries inserted as a result of :envvar:`PYTHONPATH`.
+
+ A program is free to modify this list for its own purposes.
+
+ .. versionchanged:: 2.3
+ Unicode strings are no longer ignored.
+
+
+.. data:: platform
+
+ This string contains a platform identifier, e.g. ``'sunos5'`` or ``'linux1'``.
+ This can be used to append platform-specific components to ``path``, for
+ instance.
+
+
+.. data:: prefix
+
+ A string giving the site-specific directory prefix where the platform
+ independent Python files are installed; by default, this is the string
+ ``'/usr/local'``. This can be set at build time with the :option:`--prefix`
+ argument to the :program:`configure` script. The main collection of Python
+ library modules is installed in the directory ``prefix + '/lib/pythonversion'``
+ while the platform independent header files (all except :file:`pyconfig.h`) are
+ stored in ``prefix + '/include/pythonversion'``, where *version* is equal to
+ ``version[:3]``.
+
+
+.. data:: ps1
+ ps2
+
+ .. index::
+ single: interpreter prompts
+ single: prompts, interpreter
+
+ Strings specifying the primary and secondary prompt of the interpreter. These
+ are only defined if the interpreter is in interactive mode. Their initial
+ values in this case are ``'>>> '`` and ``'... '``. If a non-string object is
+ assigned to either variable, its :func:`str` is re-evaluated each time the
+ interpreter prepares to read a new interactive command; this can be used to
+ implement a dynamic prompt.
+
+
+.. function:: setcheckinterval(interval)
+
+ Set the interpreter's "check interval". This integer value determines how often
+ the interpreter checks for periodic things such as thread switches and signal
+ handlers. The default is ``100``, meaning the check is performed every 100
+ Python virtual instructions. Setting it to a larger value may increase
+ performance for programs using threads. Setting it to a value ``<=`` 0 checks
+ every virtual instruction, maximizing responsiveness as well as overhead.
+
+
+.. function:: setdefaultencoding(name)
+
+ Set the current default string encoding used by the Unicode implementation. If
+ *name* does not match any available encoding, :exc:`LookupError` is raised.
+ This function is only intended to be used by the :mod:`site` module
+ implementation and, where needed, by :mod:`sitecustomize`. Once used by the
+ :mod:`site` module, it is removed from the :mod:`sys` module's namespace.
+
+ .. % Note that \refmodule{site} is not imported if
+ .. % the \programopt{-S} option is passed to the interpreter, in which
+ .. % case this function will remain available.
+
+ .. versionadded:: 2.0
+
+
+.. function:: setdlopenflags(n)
+
+ Set the flags used by the interpreter for :cfunc:`dlopen` calls, such as when
+ the interpreter loads extension modules. Among other things, this will enable a
+ lazy resolving of symbols when importing a module, if called as
+ ``sys.setdlopenflags(0)``. To share symbols across extension modules, call as
+ ``sys.setdlopenflags(dl.RTLD_NOW | dl.RTLD_GLOBAL)``. Symbolic names for the
+ flag modules can be either found in the :mod:`dl` module, or in the :mod:`DLFCN`
+ module. If :mod:`DLFCN` is not available, it can be generated from
+ :file:`/usr/include/dlfcn.h` using the :program:`h2py` script. Availability:
+ Unix.
+
+ .. versionadded:: 2.2
+
+
+.. function:: setprofile(profilefunc)
+
+ .. index::
+ single: profile function
+ single: profiler
+
+ Set the system's profile function, which allows you to implement a Python source
+ code profiler in Python. See chapter :ref:`profile` for more information on the
+ Python profiler. The system's profile function is called similarly to the
+ system's trace function (see :func:`settrace`), but it isn't called for each
+ executed line of code (only on call and return, but the return event is reported
+ even when an exception has been set). The function is thread-specific, but
+ there is no way for the profiler to know about context switches between threads,
+ so it does not make sense to use this in the presence of multiple threads. Also,
+ its return value is not used, so it can simply return ``None``.
+
+
+.. function:: setrecursionlimit(limit)
+
+ Set the maximum depth of the Python interpreter stack to *limit*. This limit
+ prevents infinite recursion from causing an overflow of the C stack and crashing
+ Python.
+
+ The highest possible limit is platform-dependent. A user may need to set the
+ limit higher when she has a program that requires deep recursion and a platform
+ that supports a higher limit. This should be done with care, because a too-high
+ limit can lead to a crash.
+
+
+.. function:: settrace(tracefunc)
+
+ .. index::
+ single: trace function
+ single: debugger
+
+ Set the system's trace function, which allows you to implement a Python
+ source code debugger in Python. See section :ref:`debugger-hooks` in the
+ chapter on the Python debugger. The function is thread-specific; for a
+ debugger to support multiple threads, it must be registered using
+ :func:`settrace` for each thread being debugged.
+
+ .. note::
+
+ The :func:`settrace` function is intended only for implementing debuggers,
+ profilers, coverage tools and the like. Its behavior is part of the
+ implementation platform, rather than part of the language definition, and thus
+ may not be available in all Python implementations.
+
+
+.. function:: settscdump(on_flag)
+
+ Activate dumping of VM measurements using the Pentium timestamp counter, if
+ *on_flag* is true. Deactivate these dumps if *on_flag* is off. The function is
+ available only if Python was compiled with :option:`--with-tsc`. To understand
+ the output of this dump, read :file:`Python/ceval.c` in the Python sources.
+
+ .. versionadded:: 2.4
+
+
+.. data:: stdin
+ stdout
+ stderr
+
+ File objects corresponding to the interpreter's standard input, output and error
+ streams. ``stdin`` is used for all interpreter input except for scripts.
+ ``stdout`` is used for the output of :keyword:`print` and expression statements.
+ The interpreter's own prompts and (almost all of) its error messages go to
+ ``stderr``. ``stdout`` and ``stderr`` needn't be built-in file objects: any
+ object is acceptable as long as it has a :meth:`write` method that takes a
+ string argument. (Changing these objects doesn't affect the standard I/O
+ streams of processes executed by :func:`os.popen`, :func:`os.system` or the
+ :func:`exec\*` family of functions in the :mod:`os` module.)
+
+
+.. data:: __stdin__
+ __stdout__
+ __stderr__
+
+ These objects contain the original values of ``stdin``, ``stderr`` and
+ ``stdout`` at the start of the program. They are used during finalization, and
+ could be useful to restore the actual files to known working file objects in
+ case they have been overwritten with a broken object.
+
+
+.. data:: tracebacklimit
+
+ When this variable is set to an integer value, it determines the maximum number
+ of levels of traceback information printed when an unhandled exception occurs.
+ The default is ``1000``. When set to ``0`` or less, all traceback information
+ is suppressed and only the exception type and value are printed.
+
+
+.. data:: version
+
+ A string containing the version number of the Python interpreter plus additional
+ information on the build number and compiler used. It has a value of the form
+ ``'version (#build_number, build_date, build_time) [compiler]'``. The first
+ three characters are used to identify the version in the installation
+ directories (where appropriate on each platform). An example::
+
+ >>> import sys
+ >>> sys.version
+ '1.5.2 (#0 Apr 13 1999, 10:51:12) [MSC 32 bit (Intel)]'
+
+
+.. data:: api_version
+
+ The C API version for this interpreter. Programmers may find this useful when
+ debugging version conflicts between Python and extension modules.
+
+ .. versionadded:: 2.3
+
+
+.. data:: version_info
+
+ A tuple containing the five components of the version number: *major*, *minor*,
+ *micro*, *releaselevel*, and *serial*. All values except *releaselevel* are
+ integers; the release level is ``'alpha'``, ``'beta'``, ``'candidate'``, or
+ ``'final'``. The ``version_info`` value corresponding to the Python version 2.0
+ is ``(2, 0, 0, 'final', 0)``.
+
+ .. versionadded:: 2.0
+
+
+.. data:: warnoptions
+
+ This is an implementation detail of the warnings framework; do not modify this
+ value. Refer to the :mod:`warnings` module for more information on the warnings
+ framework.
+
+
+.. data:: winver
+
+ The version number used to form registry keys on Windows platforms. This is
+ stored as string resource 1000 in the Python DLL. The value is normally the
+ first three characters of :const:`version`. It is provided in the :mod:`sys`
+ module for informational purposes; modifying this value has no effect on the
+ registry keys used by Python. Availability: Windows.
+
+
+.. seealso::
+
+ Module :mod:`site`
+ This describes how to use .pth files to extend ``sys.path``.
+