Merged revisions...

Merged revisions 75363,75365,75376,75392,75394,75403,75418,75484,75572,75580,75590,75592,75594-75596,75600,75602-75603,75605-75607,75610-75613,75616-75617,75623,75627,75647 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.
........
  r75365 | georg.brandl | 2009-10-11 22:16:16 +0200 (So, 11 Okt 2009) | 1 line

  Fix broken links found by "make linkcheck".  scipy.org seems to be done right now, so I could not verify links going there.
........
  r75376 | benjamin.peterson | 2009-10-12 03:26:07 +0200 (Mo, 12 Okt 2009) | 1 line

  platform we don't care about
........
  r75392 | andrew.kuchling | 2009-10-13 18:11:49 +0200 (Di, 13 Okt 2009) | 1 line

  Various link, textual, and markup fixes
........
  r75394 | georg.brandl | 2009-10-13 20:10:59 +0200 (Di, 13 Okt 2009) | 1 line

  Fix markup.
........
  r75403 | georg.brandl | 2009-10-14 17:57:46 +0200 (Mi, 14 Okt 2009) | 1 line

  #7126: os.environ changes *do* take effect in subprocesses started with os.system().
........
  r75418 | georg.brandl | 2009-10-14 20:48:32 +0200 (Mi, 14 Okt 2009) | 1 line

  #7116: str.join() takes an iterable.
........
  r75484 | georg.brandl | 2009-10-18 09:58:12 +0200 (So, 18 Okt 2009) | 1 line

  Fix missing word.
........
  r75572 | benjamin.peterson | 2009-10-20 23:55:17 +0200 (Di, 20 Okt 2009) | 1 line

  clarify buffer arg #7178
........
  r75580 | georg.brandl | 2009-10-21 09:15:59 +0200 (Mi, 21 Okt 2009) | 1 line

  #7170: fix explanation about non-weakrefable builtin types.
........
  r75590 | benjamin.peterson | 2009-10-22 04:36:47 +0200 (Do, 22 Okt 2009) | 1 line

  rewrite to be nice to other implementations
........
  r75592 | georg.brandl | 2009-10-22 09:05:48 +0200 (Do, 22 Okt 2009) | 1 line

  Fix punctuation.
........
  r75594 | georg.brandl | 2009-10-22 09:56:02 +0200 (Do, 22 Okt 2009) | 1 line

  Fix markup.
........
  r75595 | georg.brandl | 2009-10-22 09:56:56 +0200 (Do, 22 Okt 2009) | 1 line

  Fix duplicate target.
........
  r75596 | georg.brandl | 2009-10-22 10:05:04 +0200 (Do, 22 Okt 2009) | 1 line

  Add a new directive marking up implementation details and start using it.
........
  r75600 | georg.brandl | 2009-10-22 13:01:46 +0200 (Do, 22 Okt 2009) | 1 line

  Make it more robust.
........
  r75602 | georg.brandl | 2009-10-22 13:28:06 +0200 (Do, 22 Okt 2009) | 1 line

  Document new directive.
........
  r75603 | georg.brandl | 2009-10-22 13:28:23 +0200 (Do, 22 Okt 2009) | 1 line

  Allow short form with text as argument.
........
  r75605 | georg.brandl | 2009-10-22 13:48:10 +0200 (Do, 22 Okt 2009) | 1 line

  Use "impl-detail" directive where applicable.
........
  r75606 | georg.brandl | 2009-10-22 17:00:06 +0200 (Do, 22 Okt 2009) | 1 line

  #6324: membership test tries iteration via __iter__.
........
  r75607 | georg.brandl | 2009-10-22 17:04:09 +0200 (Do, 22 Okt 2009) | 1 line

  #7088: document new functions in signal as Unix-only.
........
  r75610 | georg.brandl | 2009-10-22 17:27:24 +0200 (Do, 22 Okt 2009) | 1 line

  Reorder __slots__ fine print and add a clarification.
........
  r75611 | georg.brandl | 2009-10-22 17:42:32 +0200 (Do, 22 Okt 2009) | 1 line

  #7035: improve docs of the various <method>_errors() functions, and give them docstrings.
........
  r75612 | georg.brandl | 2009-10-22 17:52:15 +0200 (Do, 22 Okt 2009) | 1 line

  #7156: document curses as Unix-only.
........
  r75613 | georg.brandl | 2009-10-22 17:54:35 +0200 (Do, 22 Okt 2009) | 1 line

  #6977: getopt does not support optional option arguments.
........
  r75616 | georg.brandl | 2009-10-22 18:17:05 +0200 (Do, 22 Okt 2009) | 1 line

  Add proper references.
........
  r75617 | georg.brandl | 2009-10-22 18:20:55 +0200 (Do, 22 Okt 2009) | 1 line

  Make printout margin important.
........
  r75623 | georg.brandl | 2009-10-23 10:14:44 +0200 (Fr, 23 Okt 2009) | 1 line

  #7188: fix optionxform() docs.
........
  r75627 | fred.drake | 2009-10-23 15:04:51 +0200 (Fr, 23 Okt 2009) | 2 lines

  add further note about what's passed to optionxform
........
  r75647 | georg.brandl | 2009-10-24 12:04:19 +0200 (Sa, 24 Okt 2009) | 1 line

  Fix markup.
........

Doc/contents.rst

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

Doc/documenting/markup.rst

@@ -626,6 +626,24 @@ units as well as normal text:
 
 --------------
 
+.. describe:: impl-detail
+
+   This directive is used to mark CPython-specific information.  Use either with
+   a block content or a single sentence as an argument, i.e. either ::
+
+      .. impl-detail::
+
+         This describes some implementation detail.
+
+         More explanation.
+
+   or ::
+
+      .. impl-detail:: This shortly mentions an implementation detail.
+
+   "\ **CPython implementation detail:**\ " is automatically prepended to the
+   content.
+
 .. describe:: seealso
 
    Many sections include a list of references to module documentation or

Doc/faq/gui.rst

+: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.
+
+wxWidgets
+'''''''''
+
+wxWidgets is a GUI class library written in C++ that's a portable
+interface to various platform-specific libraries, and that has a
+Python interface called `wxPython <http://www.wxpython.org>`__.
+
+wxWidgets preserves the look and feel of the
+underlying graphics toolkit, and has a large set of widgets and
+collection of GDI classes.  See `the wxWidgets page
+<http://www.wxwidgets.org>`_ for more details.
+
+wxWidgets supports Windows and MacOS; on Unix variants,
+it supports both GTk+ and Motif toolkits.
+
+Qt
+'''
+
+There are bindings available for the Qt toolkit (`PyQt
+<http://www.riverbankcomputing.co.uk/software/pyqt/>`_) and for KDE (`PyKDE <http://www.riverbankcomputing.co.uk/software/pykde/intro>`__).  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 (up to Qt 4.4;
+Qt 4.5 upwards is licensed under the LGPL license) a Qt license from `Trolltech
+<http://www.trolltech.com>`_.
+
+Gtk+
+''''
+
+PyGtk bindings for the `Gtk+ toolkit <http://www.gtk.org>`_ have been
+implemented by James Henstridge; see <http://www.pygtk.org>.
+
+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
+supports 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
+that's written mostly in Python using the MFC classes.
+
+
+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.sourceforge.net/).
+
+Build Tix with SAM enabled, perform the appropriate call to
+:cfunc:`Tclsam_init`, etc. inside Python's
+:file:`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 :cfunc:`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

+###################################
+  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

+=============================================
+"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/howto/unicode.rst

@@ -472,7 +472,7 @@ These are grouped into categories such as "Letter", "Number", "Punctuation", or
 from the above output, ``'Ll'`` means 'Letter, lowercase', ``'No'`` means
 "Number, other", ``'Mn'`` is "Mark, nonspacing", and ``'So'`` is "Symbol,
 other".  See
-<http://www.unicode.org/Public/UNIDATA/UCD.html#General_Category_Values> for a
+<http://unicode.org/Public/5.1.0/ucd/UCD.html#General_Category_Values> for a
 list of category codes.
 
 References

Doc/howto/webservers.rst

@@ -270,8 +270,7 @@ Depending on the web server you need to have a special module.
 * lighttpd ships its own `FastCGI module
   <http://trac.lighttpd.net/trac/wiki/Docs%3AModFastCGI>`_ as well as an `SCGI
   module <http://trac.lighttpd.net/trac/wiki/Docs%3AModSCGI>`_.
-* nginx also supports `FastCGI
-  <http://wiki.codemongers.com/NginxSimplePythonFCGI>`_.
+* nginx also supports `FastCGI <http://wiki.nginx.org/NginxSimplePythonFCGI>`_.
 
 Once you have installed and configured the module, you can test it with the
 following WSGI-application::
@@ -524,7 +523,7 @@ the text of a wiki page.  As always, there are different ways to store
 informations on a web server.
 
 Often relational database engines like `MySQL <http://www.mysql.com/>`_ or
-`PostgreSQL <http://http://www.postgresql.org/>`_ are used due to their good
+`PostgreSQL <http://www.postgresql.org/>`_ are used due to their good
 performance handling very large databases consisting of up to millions of
 entries.  These are *queried* using a language called `SQL
 <http://en.wikipedia.org/wiki/SQL>`_.  Python programmers in general do not like
@@ -628,7 +627,7 @@ which make it possible to write web sites nearly without any Python code.
 It has a big, international community which has created many sites using Django.
 There are also quite a lot of add-on projects which extend Django's normal
 functionality.  This is partly due to Django's well written `online
-documentation <http://doc.djangoproject.com/>`_ and the `Django book
+documentation <http://docs.djangoproject.com/>`_ and the `Django book
 <http://www.djangobook.com/>`_.
 
 

Doc/install/index.rst

@@ -940,7 +940,8 @@ following steps.
 These compilers require some special libraries. This task is more complex than
 for Borland's C++, because there is no program to convert the library.  First
 you have to create a list of symbols which the Python DLL exports. (You can find
-a good program for this task at http://www.emmestech.com/software/cygwin/pexports-0.43/download_pexports.html)
+a good program for this task at
+http://www.emmestech.com/software/pexports-0.43/download_pexports.html).
 
 .. I don't understand what the next line means. --amk
 .. (inclusive the references on data structures.)

Doc/library/__builtin__.rst

@@ -33,9 +33,10 @@ that wants to implement an :func:`open` function that wraps the built-in
 
        # ...
 
-As an implementation detail, most modules have the name ``__builtins__`` (note
-the ``'s'``) made available as part of their globals.  The value of
-``__builtins__`` is normally either this module or the value of this modules's
-:attr:`__dict__` attribute.  Since this is an implementation detail, it may not
-be used by alternate implementations of Python.
+.. impl-detail::
 
+   Most modules have the name ``__builtins__`` (note the ``'s'``) made available
+   as part of their globals.  The value of ``__builtins__`` is normally either
+   this module or the value of this modules's :attr:`__dict__` attribute.  Since
+   this is an implementation detail, it may not be used by alternate
+   implementations of Python.

Doc/library/codecs.rst

@@ -54,7 +54,7 @@ It defines the following functions:
    *incrementalencoder* and *incrementaldecoder*: These have to be factory
    functions providing the following interface:
 
-   ``factory(errors='strict')``
+      ``factory(errors='strict')``
 
    The factory functions must return objects providing the interfaces defined by
    the base classes :class:`IncrementalEncoder` and :class:`IncrementalDecoder`,
@@ -63,20 +63,24 @@ It defines the following functions:
    *streamreader* and *streamwriter*: These have to be factory functions providing
    the following interface:
 
-   ``factory(stream, errors='strict')``
+      ``factory(stream, errors='strict')``
 
    The factory functions must return objects providing the interfaces defined by
    the base classes :class:`StreamWriter` and :class:`StreamReader`, respectively.
    Stream codecs can maintain state.
 
-   Possible values for errors are ``'strict'`` (raise an exception in case of an
-   encoding error), ``'replace'`` (replace malformed data with a suitable
-   replacement marker, such as ``'?'``), ``'ignore'`` (ignore malformed data and
-   continue without further notice), ``'xmlcharrefreplace'`` (replace with the
-   appropriate XML character reference (for encoding only)) and
-   ``'backslashreplace'`` (replace with backslashed escape sequences (for encoding
-   only)) as well as any other error handling name defined via
-   :func:`register_error`.
+   Possible values for errors are
+
+   * ``'strict'``: raise an exception in case of an encoding error
+   * ``'replace'``: replace malformed data with a suitable replacement marker,
+     such as ``'?'`` or ``'\ufffd'``
+   * ``'ignore'``: ignore malformed data and continue without further notice
+   * ``'xmlcharrefreplace'``: replace with the appropriate XML character
+     reference (for encoding only)
+   * ``'backslashreplace'``: replace with backslashed escape sequences (for
+     encoding only
+
+   as well as any other error handling name defined via :func:`register_error`.
 
    In case a search function cannot find a given encoding, it should return
    ``None``.
@@ -177,27 +181,33 @@ functions which use :func:`lookup` for the codec lookup:
 
 .. function:: strict_errors(exception)
 
-   Implements the ``strict`` error handling.
+   Implements the ``strict`` error handling: each encoding or decoding error
+   raises a :exc:`UnicodeError`.
 
 
 .. function:: replace_errors(exception)
 
-   Implements the ``replace`` error handling.
+   Implements the ``replace`` error handling: malformed data is replaced with a
+   suitable replacement character such as ``'?'`` in bytestrings and
+   ``'\ufffd'`` in Unicode strings.
 
 
 .. function:: ignore_errors(exception)
 
-   Implements the ``ignore`` error handling.
+   Implements the ``ignore`` error handling: malformed data is ignored and
+   encoding or decoding is continued without further notice.
 
 
 .. function:: xmlcharrefreplace_errors(exception)
 
-   Implements the ``xmlcharrefreplace`` error handling.
+   Implements the ``xmlcharrefreplace`` error handling (for encoding only): the
+   unencodable character is replaced by an appropriate XML character reference.
 
 
 .. function:: backslashreplace_errors(exception)
 
-   Implements the ``backslashreplace`` error handling.
+   Implements the ``backslashreplace`` error handling (for encoding only): the
+   unencodable character is replaced by a backslashed escape sequence.
 
 To simplify working with encoded files or stream, the module also defines these
 utility functions:

Doc/library/configparser.rst

@@ -317,12 +317,23 @@ RawConfigParser Objects
 
 .. method:: RawConfigParser.optionxform(option)
 
-   Transforms the option name *option* as found in an input file or as passed in by
-   client code to the form that should be used in the internal structures.  The
-   default implementation returns a lower-case version of *option*; subclasses may
-   override this or client code can set an attribute of this name on instances to
-   affect this behavior.  Setting this to :func:`str`, for example, would make
-   option names case sensitive.
+   Transforms the option name *option* as found in an input file or as passed in
+   by client code to the form that should be used in the internal structures.
+   The default implementation returns a lower-case version of *option*;
+   subclasses may override this or client code can set an attribute of this name
+   on instances to affect this behavior.
+
+   You don't necessarily need to subclass a ConfigParser to use this method, you
+   can also re-set it on an instance, to a function that takes a string
+   argument.  Setting it to ``str``, for example, would make option names case
+   sensitive::
+
+      cfgparser = ConfigParser()
+      ...
+      cfgparser.optionxform = str
+
+   Note that when reading configuration files, whitespace around the
+   option names are stripped before :meth:`optionxform` is called.
 
 
 .. _configparser-objects:

Doc/library/curses.rst

-
 :mod:`curses` --- Terminal handling for character-cell displays
 ===============================================================
 
 .. module:: curses
-   :synopsis: An interface to the curses library, providing portable terminal handling.
+   :synopsis: An interface to the curses library, providing portable terminal
+              handling.
+   :platform: Unix
 .. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il>
 .. sectionauthor:: Eric Raymond <esr@thyrsus.com>
 
-
 .. versionchanged:: 1.6
    Added support for the ``ncurses`` library and converted to a package.