Merged revisions 75363 via svnmerge from

svn+ssh://pythondev@svn.python.org/python/trunk

........
  r75363 | georg.brandl | 2009-10-11 20:31:23 +0200 (So, 11 Okt 2009) | 1 line

  Add the Python FAQ lists to the documentation.  Copied from sandbox/faq.  Many thanks to AMK for the preparation work.
........

Doc/contents.rst

@@ -15,6 +15,7 @@
    install/index.rst
    documenting/index.rst
    howto/index.rst
+   faq/index.rst
    glossary.rst
 
    about.rst

Doc/faq/extending.rst

@@ -0,0 +1,481 @@
+=======================
+Extending/Embedding FAQ
+=======================
+
+.. contents::
+
+.. highlight:: c
+
+
+Can I create my own functions in C?
+-----------------------------------
+
+Yes, you can create built-in modules containing functions, variables, exceptions
+and even new types in C.  This is explained in the document
+:ref:`extending-index`.
+
+Most intermediate or advanced Python books will also cover this topic.
+
+
+Can I create my own functions in C++?
+-------------------------------------
+
+Yes, using the C compatibility features found in C++.  Place ``extern "C" {
+... }`` around the Python include files and put ``extern "C"`` before each
+function that is going to be called by the Python interpreter.  Global or static
+C++ objects with constructors are probably not a good idea.
+
+
+Writing C is hard; are there any alternatives?
+----------------------------------------------
+
+There are a number of alternatives to writing your own C extensions, depending
+on what you're trying to do.
+
+.. XXX make sure these all work; mention Cython
+
+If you need more speed, `Psyco <http://psyco.sourceforge.net/>`_ generates x86
+assembly code from Python bytecode.  You can use Psyco to compile the most
+time-critical functions in your code, and gain a significant improvement with
+very little effort, as long as you're running on a machine with an
+x86-compatible processor.
+
+`Pyrex <http://www.cosc.canterbury.ac.nz/~greg/python/Pyrex/>`_ is a compiler
+that accepts a slightly modified form of Python and generates the corresponding
+C code.  Pyrex makes it possible to write an extension without having to learn
+Python's C API.
+
+If you need to interface to some C or C++ library for which no Python extension
+currently exists, you can try wrapping the library's data types and functions
+with a tool such as `SWIG <http://www.swig.org>`_.  `SIP
+<http://www.riverbankcomputing.co.uk/sip/>`_, `CXX
+<http://cxx.sourceforge.net/>`_ `Boost
+<http://www.boost.org/libs/python/doc/index.html>`_, or `Weave
+<http://www.scipy.org/site_content/weave>`_ are also alternatives for wrapping
+C++ libraries.
+
+
+How can I execute arbitrary Python statements from C?
+-----------------------------------------------------
+
+The highest-level function to do this is :cfunc:`PyRun_SimpleString` which takes
+a single string argument to be executed in the context of the module
+``__main__`` and returns 0 for success and -1 when an exception occurred
+(including ``SyntaxError``).  If you want more control, use
+:cfunc:`PyRun_String`; see the source for :cfunc:`PyRun_SimpleString` in
+``Python/pythonrun.c``.
+
+
+How can I evaluate an arbitrary Python expression from C?
+---------------------------------------------------------
+
+Call the function :cfunc:`PyRun_String` from the previous question with the
+start symbol :cdata:`Py_eval_input`; it parses an expression, evaluates it and
+returns its value.
+
+
+How do I extract C values from a Python object?
+-----------------------------------------------
+
+That depends on the object's type.  If it's a tuple, :cfunc:`PyTuple_Size`
+returns its length and :cfunc:`PyTuple_GetItem` returns the item at a specified
+index.  Lists have similar functions, :cfunc:`PyListSize` and
+:cfunc:`PyList_GetItem`.
+
+For strings, :cfunc:`PyString_Size` returns its length and
+:cfunc:`PyString_AsString` a pointer to its value.  Note that Python strings may
+contain null bytes so C's :cfunc:`strlen` should not be used.
+
+To test the type of an object, first make sure it isn't *NULL*, and then use
+:cfunc:`PyString_Check`, :cfunc:`PyTuple_Check`, :cfunc:`PyList_Check`, etc.
+
+There is also a high-level API to Python objects which is provided by the
+so-called 'abstract' interface -- read ``Include/abstract.h`` for further
+details.  It allows interfacing with any kind of Python sequence using calls
+like :cfunc:`PySequence_Length`, :cfunc:`PySequence_GetItem`, etc.)  as well as
+many other useful protocols.
+
+
+How do I use Py_BuildValue() to create a tuple of arbitrary length?
+-------------------------------------------------------------------
+
+You can't.  Use ``t = PyTuple_New(n)`` instead, and fill it with objects using
+``PyTuple_SetItem(t, i, o)`` -- note that this "eats" a reference count of
+``o``, so you have to :cfunc:`Py_INCREF` it.  Lists have similar functions
+``PyList_New(n)`` and ``PyList_SetItem(l, i, o)``.  Note that you *must* set all
+the tuple items to some value before you pass the tuple to Python code --
+``PyTuple_New(n)`` initializes them to NULL, which isn't a valid Python value.
+
+
+How do I call an object's method from C?
+----------------------------------------
+
+The :cfunc:`PyObject_CallMethod` function can be used to call an arbitrary
+method of an object.  The parameters are the object, the name of the method to
+call, a format string like that used with :cfunc:`Py_BuildValue`, and the
+argument values::
+
+   PyObject *
+   PyObject_CallMethod(PyObject *object, char *method_name,
+                       char *arg_format, ...);
+
+This works for any object that has methods -- whether built-in or user-defined.
+You are responsible for eventually :cfunc:`Py_DECREF`\ 'ing the return value.
+
+To call, e.g., a file object's "seek" method with arguments 10, 0 (assuming the
+file object pointer is "f")::
+
+   res = PyObject_CallMethod(f, "seek", "(ii)", 10, 0);
+   if (res == NULL) {
+           ... an exception occurred ...
+   }
+   else {
+           Py_DECREF(res);
+   }
+
+Note that since :cfunc:`PyObject_CallObject` *always* wants a tuple for the
+argument list, to call a function without arguments, pass "()" for the format,
+and to call a function with one argument, surround the argument in parentheses,
+e.g. "(i)".
+
+
+How do I catch the output from PyErr_Print() (or anything that prints to stdout/stderr)?
+----------------------------------------------------------------------------------------
+
+In Python code, define an object that supports the ``write()`` method.  Assign
+this object to :data:`sys.stdout` and :data:`sys.stderr`.  Call print_error, or
+just allow the standard traceback mechanism to work. Then, the output will go
+wherever your ``write()`` method sends it.
+
+The easiest way to do this is to use the StringIO class in the standard library.
+
+Sample code and use for catching stdout:
+
+   >>> class StdoutCatcher:
+   ...     def __init__(self):
+   ...         self.data = ''
+   ...     def write(self, stuff):
+   ...         self.data = self.data + stuff
+   ...
+   >>> import sys
+   >>> sys.stdout = StdoutCatcher()
+   >>> print 'foo'
+   >>> print 'hello world!'
+   >>> sys.stderr.write(sys.stdout.data)
+   foo
+   hello world!
+
+
+How do I access a module written in Python from C?
+--------------------------------------------------
+
+You can get a pointer to the module object as follows::
+
+   module = PyImport_ImportModule("<modulename>");
+
+If the module hasn't been imported yet (i.e. it is not yet present in
+:data:`sys.modules`), this initializes the module; otherwise it simply returns
+the value of ``sys.modules["<modulename>"]``.  Note that it doesn't enter the
+module into any namespace -- it only ensures it has been initialized and is
+stored in :data:`sys.modules`.
+
+You can then access the module's attributes (i.e. any name defined in the
+module) as follows::
+
+   attr = PyObject_GetAttrString(module, "<attrname>");
+
+Calling :cfunc:`PyObject_SetAttrString` to assign to variables in the module
+also works.
+
+
+How do I interface to C++ objects from Python?
+----------------------------------------------
+
+Depending on your requirements, there are many approaches.  To do this manually,
+begin by reading :ref:`the "Extending and Embedding" document
+<extending-index>`.  Realize that for the Python run-time system, there isn't a
+whole lot of difference between C and C++ -- so the strategy of building a new
+Python type around a C structure (pointer) type will also work for C++ objects.
+
+For C++ libraries, you can look at `SIP
+<http://www.riverbankcomputing.co.uk/sip/>`_, `CXX
+<http://cxx.sourceforge.net/>`_, `Boost
+<http://www.boost.org/libs/python/doc/index.html>`_, `Weave
+<http://www.scipy.org/site_content/weave>`_ or `SWIG <http://www.swig.org>`_
+
+
+I added a module using the Setup file and the make fails; why?
+--------------------------------------------------------------
+
+Setup must end in a newline, if there is no newline there, the build process
+fails.  (Fixing this requires some ugly shell script hackery, and this bug is so
+minor that it doesn't seem worth the effort.)
+
+
+How do I debug an extension?
+----------------------------
+
+When using GDB with dynamically loaded extensions, you can't set a breakpoint in
+your extension until your extension is loaded.
+
+In your ``.gdbinit`` file (or interactively), add the command::
+
+   br _PyImport_LoadDynamicModule
+
+Then, when you run GDB::
+
+   $ gdb /local/bin/python
+   gdb) run myscript.py
+   gdb) continue # repeat until your extension is loaded
+   gdb) finish   # so that your extension is loaded
+   gdb) br myfunction.c:50
+   gdb) continue
+
+I want to compile a Python module on my Linux system, but some files are missing. Why?
+--------------------------------------------------------------------------------------
+
+Most packaged versions of Python don't include the
+:file:`/usr/lib/python2.{x}/config/` directory, which contains various files
+required for compiling Python extensions.
+
+For Red Hat, install the python-devel RPM to get the necessary files.
+
+For Debian, run ``apt-get install python-dev``.
+
+
+What does "SystemError: _PyImport_FixupExtension: module yourmodule not loaded" mean?
+-------------------------------------------------------------------------------------
+
+This means that you have created an extension module named "yourmodule", but
+your module init function does not initialize with that name.
+
+Every module init function will have a line similar to::
+
+   module = Py_InitModule("yourmodule", yourmodule_functions);
+
+If the string passed to this function is not the same name as your extension
+module, the :exc:`SystemError` exception will be raised.
+
+
+How do I tell "incomplete input" from "invalid input"?
+------------------------------------------------------
+
+Sometimes you want to emulate the Python interactive interpreter's behavior,
+where it gives you a continuation prompt when the input is incomplete (e.g. you
+typed the start of an "if" statement or you didn't close your parentheses or
+triple string quotes), but it gives you a syntax error message immediately when
+the input is invalid.
+
+In Python you can use the :mod:`codeop` module, which approximates the parser's
+behavior sufficiently.  IDLE uses this, for example.
+
+The easiest way to do it in C is to call :cfunc:`PyRun_InteractiveLoop` (perhaps
+in a separate thread) and let the Python interpreter handle the input for
+you. You can also set the :cfunc:`PyOS_ReadlineFunctionPointer` to point at your
+custom input function. See ``Modules/readline.c`` and ``Parser/myreadline.c``
+for more hints.
+
+However sometimes you have to run the embedded Python interpreter in the same
+thread as your rest application and you can't allow the
+:cfunc:`PyRun_InteractiveLoop` to stop while waiting for user input.  The one
+solution then is to call :cfunc:`PyParser_ParseString` and test for ``e.error``
+equal to ``E_EOF``, which means the input is incomplete).  Here's a sample code
+fragment, untested, inspired by code from Alex Farber::
+
+   #include <Python.h>
+   #include <node.h>
+   #include <errcode.h>
+   #include <grammar.h>
+   #include <parsetok.h>
+   #include <compile.h>
+
+   int testcomplete(char *code)
+     /* code should end in \n */
+     /* return -1 for error, 0 for incomplete, 1 for complete */
+   {
+     node *n;
+     perrdetail e;
+
+     n = PyParser_ParseString(code, &_PyParser_Grammar,
+                              Py_file_input, &e);
+     if (n == NULL) {
+       if (e.error == E_EOF)
+         return 0;
+       return -1;
+     }
+
+     PyNode_Free(n);
+     return 1;
+   }
+
+Another solution is trying to compile the received string with
+:cfunc:`Py_CompileString`. If it compiles without errors, try to execute the
+returned code object by calling :cfunc:`PyEval_EvalCode`. Otherwise save the
+input for later. If the compilation fails, find out if it's an error or just
+more input is required - by extracting the message string from the exception
+tuple and comparing it to the string "unexpected EOF while parsing".  Here is a
+complete example using the GNU readline library (you may want to ignore
+**SIGINT** while calling readline())::
+
+   #include <stdio.h>
+   #include <readline.h>
+
+   #include <Python.h>
+   #include <object.h>
+   #include <compile.h>
+   #include <eval.h>
+
+   int main (int argc, char* argv[])
+   {
+     int i, j, done = 0;                          /* lengths of line, code */
+     char ps1[] = ">>> ";
+     char ps2[] = "... ";
+     char *prompt = ps1;
+     char *msg, *line, *code = NULL;
+     PyObject *src, *glb, *loc;
+     PyObject *exc, *val, *trb, *obj, *dum;
+
+     Py_Initialize ();
+     loc = PyDict_New ();
+     glb = PyDict_New ();
+     PyDict_SetItemString (glb, "__builtins__", PyEval_GetBuiltins ());
+
+     while (!done)
+     {
+       line = readline (prompt);
+
+       if (NULL == line)                          /* CTRL-D pressed */
+       {
+         done = 1;
+       }
+       else
+       {
+         i = strlen (line);
+
+         if (i > 0)
+           add_history (line);                    /* save non-empty lines */
+
+         if (NULL == code)                        /* nothing in code yet */
+           j = 0;
+         else
+           j = strlen (code);
+
+         code = realloc (code, i + j + 2);
+         if (NULL == code)                        /* out of memory */
+           exit (1);
+
+         if (0 == j)                              /* code was empty, so */
+           code[0] = '\0';                        /* keep strncat happy */
+
+         strncat (code, line, i);                 /* append line to code */
+         code[i + j] = '\n';                      /* append '\n' to code */
+         code[i + j + 1] = '\0';
+
+         src = Py_CompileString (code, "<stdin>", Py_single_input);
+
+         if (NULL != src)                         /* compiled just fine - */
+         {
+           if (ps1  == prompt ||                  /* ">>> " or */
+               '\n' == code[i + j - 1])           /* "... " and double '\n' */
+           {                                               /* so execute it */
+             dum = PyEval_EvalCode ((PyCodeObject *)src, glb, loc);
+             Py_XDECREF (dum);
+             Py_XDECREF (src);
+             free (code);
+             code = NULL;
+             if (PyErr_Occurred ())
+               PyErr_Print ();
+             prompt = ps1;
+           }
+         }                                        /* syntax error or E_EOF? */
+         else if (PyErr_ExceptionMatches (PyExc_SyntaxError))
+         {
+           PyErr_Fetch (&exc, &val, &trb);        /* clears exception! */
+
+           if (PyArg_ParseTuple (val, "sO", &msg, &obj) &&
+               !strcmp (msg, "unexpected EOF while parsing")) /* E_EOF */
+           {
+             Py_XDECREF (exc);
+             Py_XDECREF (val);
+             Py_XDECREF (trb);
+             prompt = ps2;
+           }
+           else                                   /* some other syntax error */
+           {
+             PyErr_Restore (exc, val, trb);
+             PyErr_Print ();
+             free (code);
+             code = NULL;
+             prompt = ps1;
+           }
+         }
+         else                                     /* some non-syntax error */
+         {
+           PyErr_Print ();
+           free (code);
+           code = NULL;
+           prompt = ps1;
+         }
+
+         free (line);
+       }
+     }
+
+     Py_XDECREF(glb);
+     Py_XDECREF(loc);
+     Py_Finalize();
+     exit(0);
+   }
+
+
+How do I find undefined g++ symbols __builtin_new or __pure_virtual?
+--------------------------------------------------------------------
+
+To dynamically load g++ extension modules, you must recompile Python, relink it
+using g++ (change LINKCC in the python Modules Makefile), and link your
+extension module using g++ (e.g., ``g++ -shared -o mymodule.so mymodule.o``).
+
+
+Can I create an object class with some methods implemented in C and others in Python (e.g. through inheritance)?
+----------------------------------------------------------------------------------------------------------------
+
+In Python 2.2, you can inherit from builtin classes such as :class:`int`,
+:class:`list`, :class:`dict`, etc.
+
+The Boost Python Library (BPL, http://www.boost.org/libs/python/doc/index.html)
+provides a way of doing this from C++ (i.e. you can inherit from an extension
+class written in C++ using the BPL).
+
+
+When importing module X, why do I get "undefined symbol: PyUnicodeUCS2*"?
+-------------------------------------------------------------------------
+
+You are using a version of Python that uses a 4-byte representation for Unicode
+characters, but some C extension module you are importing was compiled using a
+Python that uses a 2-byte representation for Unicode characters (the default).
+
+If instead the name of the undefined symbol starts with ``PyUnicodeUCS4``, the
+problem is the reverse: Python was built using 2-byte Unicode characters, and
+the extension module was compiled using a Python with 4-byte Unicode characters.
+
+This can easily occur when using pre-built extension packages.  RedHat Linux
+7.x, in particular, provided a "python2" binary that is compiled with 4-byte
+Unicode.  This only causes the link failure if the extension uses any of the
+``PyUnicode_*()`` functions.  It is also a problem if an extension uses any of
+the Unicode-related format specifiers for :cfunc:`Py_BuildValue` (or similar) or
+parameter specifications for :cfunc:`PyArg_ParseTuple`.
+
+You can check the size of the Unicode character a Python interpreter is using by
+checking the value of sys.maxunicode:
+
+   >>> import sys
+   >>> if sys.maxunicode > 65535:
+   ...     print 'UCS4 build'
+   ... else:
+   ...     print 'UCS2 build'
+
+The only way to solve this problem is to use extension modules compiled with a
+Python binary built using the same size for Unicode characters.
+
+
+

Doc/faq/gui.rst

@@ -0,0 +1,160 @@
+:tocdepth: 2
+
+==========================
+Graphic User Interface FAQ
+==========================
+
+.. contents::
+
+General GUI Questions
+=====================
+
+What platform-independent GUI toolkits exist for Python?
+--------------------------------------------------------
+
+Depending on what platform(s) you are aiming at, there are several.
+
+.. XXX check links
+
+Tkinter
+'''''''
+
+Standard builds of Python include an object-oriented interface to the Tcl/Tk
+widget set, called Tkinter.  This is probably the easiest to install and use.
+For more info about Tk, including pointers to the source, see the Tcl/Tk home
+page at http://www.tcl.tk.  Tcl/Tk is fully portable to the MacOS, Windows, and
+Unix platforms.
+
+wxWindows
+'''''''''
+
+wxWindows is a portable GUI class library written in C++ that's a portable
+interface to various platform-specific libraries; wxWidgets is a Python
+interface to wxWindows.  wxWindows supports Windows and MacOS; on Unix variants,
+it supports both GTk+ and Motif toolkits.  wxWindows preserves the look and feel
+of the underlying graphics toolkit, and there is quite a rich widget set and
+collection of GDI classes.  See `the wxWindows page <http://www.wxwindows.org>`_
+for more details.
+
+`wxWidgets <http://wxwidgets.org>`_ is an extension module that wraps many of
+the wxWindows C++ classes, and is quickly gaining popularity amongst Python
+developers.  You can get wxWidgets as part of the source or CVS distribution of
+wxWindows, or directly from its home page.
+
+Qt
+'''
+
+There are bindings available for the Qt toolkit (`PyQt
+<http://www.riverbankcomputing.co.uk/pyqt/>`_) and for KDE (PyKDE).  If you're
+writing open source software, you don't need to pay for PyQt, but if you want to
+write proprietary applications, you must buy a PyQt license from `Riverbank
+Computing <http://www.riverbankcomputing.co.uk>`_ and a Qt license from
+`Trolltech <http://www.trolltech.com>`_.
+
+Gtk+
+''''
+
+PyGtk bindings for the `Gtk+ toolkit <http://www.gtk.org>`_ have been
+implemented by by James Henstridge; see ftp://ftp.gtk.org/pub/gtk/python/.
+
+FLTK
+''''
+
+Python bindings for `the FLTK toolkit <http://www.fltk.org>`_, a simple yet
+powerful and mature cross-platform windowing system, are available from `the
+PyFLTK project <http://pyfltk.sourceforge.net>`_.
+
+
+FOX
+'''
+
+A wrapper for `the FOX toolkit <http://www.fox-toolkit.org/>`_ called `FXpy
+<http://fxpy.sourceforge.net/>`_ is available.  FOX supports both Unix variants
+and Windows.
+
+
+OpenGL
+''''''
+
+For OpenGL bindings, see `PyOpenGL <http://pyopengl.sourceforge.net>`_.
+
+
+What platform-specific GUI toolkits exist for Python?
+-----------------------------------------------------
+
+`The Mac port <http://python.org/download/mac>`_ by Jack Jansen has a rich and
+ever-growing set of modules that support the native Mac toolbox calls.  The port
+includes support for MacOS9 and MacOS X's Carbon libraries.  By installing the
+`PyObjc Objective-C bridge <http://pyobjc.sourceforge.net>`_, Python programs
+can use MacOS X's Cocoa libraries. See the documentation that comes with the Mac
+port.
+
+:ref:`Pythonwin <windows-faq>` by Mark Hammond includes an interface to the
+Microsoft Foundation Classes and a Python programming environment using it
+that's written mostly in Python.
+
+
+Tkinter questions
+=================
+
+How do I freeze Tkinter applications?
+-------------------------------------
+
+Freeze is a tool to create stand-alone applications.  When freezing Tkinter
+applications, the applications will not be truly stand-alone, as the application
+will still need the Tcl and Tk libraries.
+
+One solution is to ship the application with the tcl and tk libraries, and point
+to them at run-time using the :envvar:`TCL_LIBRARY` and :envvar:`TK_LIBRARY`
+environment variables.
+
+To get truly stand-alone applications, the Tcl scripts that form the library
+have to be integrated into the application as well. One tool supporting that is
+SAM (stand-alone modules), which is part of the Tix distribution
+(http://tix.mne.com).  Build Tix with SAM enabled, perform the appropriate call
+to Tclsam_init etc inside Python's Modules/tkappinit.c, and link with libtclsam
+and libtksam (you might include the Tix libraries as well).
+
+
+Can I have Tk events handled while waiting for I/O?
+---------------------------------------------------
+
+Yes, and you don't even need threads!  But you'll have to restructure your I/O
+code a bit.  Tk has the equivalent of Xt's XtAddInput() call, which allows you
+to register a callback function which will be called from the Tk mainloop when
+I/O is possible on a file descriptor.  Here's what you need::
+
+   from Tkinter import tkinter
+   tkinter.createfilehandler(file, mask, callback)
+
+The file may be a Python file or socket object (actually, anything with a
+fileno() method), or an integer file descriptor.  The mask is one of the
+constants tkinter.READABLE or tkinter.WRITABLE.  The callback is called as
+follows::
+
+   callback(file, mask)
+
+You must unregister the callback when you're done, using ::
+
+   tkinter.deletefilehandler(file)
+
+Note: since you don't know *how many bytes* are available for reading, you can't
+use the Python file object's read or readline methods, since these will insist
+on reading a predefined number of bytes.  For sockets, the :meth:`recv` or
+:meth:`recvfrom` methods will work fine; for other files, use
+``os.read(file.fileno(), maxbytecount)``.
+
+
+I can't get key bindings to work in Tkinter: why?
+-------------------------------------------------
+
+An often-heard complaint is that event handlers bound to events with the
+:meth:`bind` method don't get handled even when the appropriate key is pressed.
+
+The most common cause is that the widget to which the binding applies doesn't
+have "keyboard focus".  Check out the Tk documentation for the focus command.
+Usually a widget is given the keyboard focus by clicking in it (but not for
+labels; see the takefocus option).
+
+
+

Doc/faq/index.rst

@@ -0,0 +1,18 @@
+###################################
+  Python Frequently Asked Questions
+###################################
+
+:Release: |version|
+:Date: |today|
+
+.. toctree::
+   :maxdepth: 1
+
+   general.rst
+   programming.rst
+   design.rst
+   library.rst
+   extending.rst
+   windows.rst
+   gui.rst
+   installed.rst

Doc/faq/installed.rst

@@ -0,0 +1,53 @@
+=============================================
+"Why is Python Installed on my Computer?" FAQ
+=============================================
+
+What is Python?
+---------------
+
+Python is a programming language.  It's used for many different applications.
+It's used in some high schools and colleges as an introductory programming
+language because Python is easy to learn, but it's also used by professional
+software developers at places such as Google, NASA, and Lucasfilm Ltd.
+
+If you wish to learn more about Python, start with the `Beginner's Guide to
+Python <http://wiki.python.org/moin/BeginnersGuide>`_.
+
+
+Why is Python installed on my machine?
+--------------------------------------
+
+If you find Python installed on your system but don't remember installing it,
+there are several possible ways it could have gotten there.
+
+* Perhaps another user on the computer wanted to learn programming and installed
+  it; you'll have to figure out who's been using the machine and might have
+  installed it.
+* A third-party application installed on the machine might have been written in
+  Python and included a Python installation.  For a home computer, the most
+  common such application is `PySol <http://pysolfc.sourceforge.net/>`_, a
+  solitaire game that includes over 1000 different games and variations.
+* Some Windows machines also have Python installed.  At this writing we're aware
+  of computers from Hewlett-Packard and Compaq that include Python.  Apparently
+  some of HP/Compaq's administrative tools are written in Python.
+* All Apple computers running Mac OS X have Python installed; it's included in
+  the base installation.
+
+
+Can I delete Python?
+--------------------
+
+That depends on where Python came from.
+
+If someone installed it deliberately, you can remove it without hurting
+anything.  On Windows, use the Add/Remove Programs icon in the Control Panel.
+
+If Python was installed by a third-party application, you can also remove it,
+but that application will no longer work.  You should use that application's
+uninstaller rather than removing Python directly.
+
+If Python came with your operating system, removing it is not recommended.  If
+you remove it, whatever tools were written in Python will no longer run, and
+some of them might be important to you.  Reinstalling the whole system would
+then be required to fix things again.
+

Doc/tools/sphinxext/indexcontent.html

@@ -26,6 +26,8 @@
          <span class="linkdescr">sharing modules with others</span></p>
       <p class="biglink"><a class="biglink" href="{{ pathto("documenting/index") }}">Documenting Python</a><br/>
          <span class="linkdescr">guide for documentation authors</span></p>
+      <p class="biglink"><a class="biglink" href="{{ pathto("faq/index") }}">FAQs</a><br/>
+         <span class="linkdescr">frequently asked questions (with answers!)</span></p>
     </td></tr>
   </table>