Merged revisions 65209-65216,65225-65226,65233,65239,65246-65247,65255-65256 via svnmerge from

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

........
  r65209 | raymond.hettinger | 2008-07-23 19:08:18 -0500 (Wed, 23 Jul 2008) | 1 line

  Finish-up the partial conversion from int to Py_ssize_t for deque indices and length.
........
  r65210 | raymond.hettinger | 2008-07-23 19:53:49 -0500 (Wed, 23 Jul 2008) | 1 line

  Parse to the correct datatype.
........
  r65211 | benjamin.peterson | 2008-07-23 21:27:46 -0500 (Wed, 23 Jul 2008) | 1 line

  fix spacing
........
  r65212 | benjamin.peterson | 2008-07-23 21:31:28 -0500 (Wed, 23 Jul 2008) | 1 line

  fix markup
........
  r65213 | benjamin.peterson | 2008-07-23 21:45:37 -0500 (Wed, 23 Jul 2008) | 1 line

  add some documentation for 2to3
........
  r65214 | raymond.hettinger | 2008-07-24 00:38:48 -0500 (Thu, 24 Jul 2008) | 1 line

  Finish conversion from int to Py_ssize_t.
........
  r65215 | raymond.hettinger | 2008-07-24 02:04:55 -0500 (Thu, 24 Jul 2008) | 1 line

  Convert from long to Py_ssize_t.
........
  r65216 | georg.brandl | 2008-07-24 02:09:21 -0500 (Thu, 24 Jul 2008) | 2 lines

  Fix indentation.
........
  r65225 | benjamin.peterson | 2008-07-25 11:55:37 -0500 (Fri, 25 Jul 2008) | 1 line

  teach .bzrignore about doc tools
........
  r65226 | benjamin.peterson | 2008-07-25 12:02:11 -0500 (Fri, 25 Jul 2008) | 1 line

  document default value for fillvalue
........
  r65233 | raymond.hettinger | 2008-07-25 13:43:33 -0500 (Fri, 25 Jul 2008) | 1 line

  Issue 1592:  Better error reporting for operations on closed shelves.
........
  r65239 | benjamin.peterson | 2008-07-25 16:59:53 -0500 (Fri, 25 Jul 2008) | 1 line

  fix indentation
........
  r65246 | andrew.kuchling | 2008-07-26 08:08:19 -0500 (Sat, 26 Jul 2008) | 1 line

  This sentence continues to bug me; rewrite it for the second time
........
  r65247 | andrew.kuchling | 2008-07-26 08:09:06 -0500 (Sat, 26 Jul 2008) | 1 line

  Remove extra words
........
  r65255 | skip.montanaro | 2008-07-26 19:49:02 -0500 (Sat, 26 Jul 2008) | 3 lines

  Close issue 3437 - missing state change when Allow lines are processed.
  Adds test cases which use Allow: as well.
........
  r65256 | skip.montanaro | 2008-07-26 19:50:41 -0500 (Sat, 26 Jul 2008) | 2 lines

  note robotparser bug fix.
........

6 files changed, 93 insertions, 6 deletions

diff --git a/Doc/glossary.rst b/Doc/glossary.rst
index ab11a83..41bf081 100644
--- a/Doc/glossary.rst
+++ b/Doc/glossary.rst
@@ -16,6 +16,15 @@ Glossary
       The typical Python prompt of the interactive shell when entering code for
       an indented code block.
 
+   2to3
+      A tool that tries to convert Python 2.x code to Python 3.x code by
+      handling most of the incompatibilites that can be detected by parsing the
+      source and traversing the parse tree.
+
+      2to3 is available in the standard library as :mod:`lib2to3`; a standalone
+      entry point is provided as :file:`Tools/scripts/2to3`.  See
+      :ref:`2to3-reference`.
+
    abstract base class
       Abstract Base Classes (abbreviated ABCs) complement :term:`duck-typing` by
       providing a way to define interfaces when other techniques like :func:`hasattr`
diff --git a/Doc/library/2to3.rst b/Doc/library/2to3.rst
new file mode 100644
index 0000000..4d64af8
--- /dev/null
+++ b/Doc/library/2to3.rst
@@ -0,0 +1,75 @@
+.. _2to3-reference:
+
+2to3 - Automated Python 2 to 3 code translation
+===============================================
+
+.. sectionauthor:: Benjamin Peterson
+
+2to3 is a Python program that reads your Python 2.x source code and applies a
+series of *fixers* to transform it into valid Python 3.x code.
+
+
+Using 2to3
+----------
+
+2to3 can be run with a list of files to transform or a directory to recursively
+traverse looking for files with the ``.py`` extension.
+
+Here is a sample Python 2.x source file, :file:`example.py`::
+
+   def greet(name):
+       print "Hello, {0}!".format(name)
+   print "What's your name?"
+   name = raw_input()
+   greet(name)
+
+It can be converted to Python 3.x code via 2to3 on the command line::
+
+   $ 2to3 example.py
+
+A diff against the original source file will be printed.  2to3 can also write
+the needed modifications right back to the source file.  (A backup of the
+original file will also be made.)  This is done with the :option:`-w` flag::
+
+   $ 2to3 -w example.py
+
+:file:`example.py` will now look like this::
+
+   def greet(name):
+       print("Hello, {0}!".format(name))
+   print("What's your name?")
+   name = input()
+   greet(name)
+
+Comments and and exact indentation will be preserved throughout the translation
+process.
+
+By default, 2to3 will run a set of predefined fixers.  The :option:`-l` flag
+lists all avaible fixers.  An explicit set of fixers to run can be given by use
+of the :option:`-f` flag.  The following example runs only the ``imports`` and
+``has_key`` fixers::
+
+   $ 2to3 -f imports -f has_key example.py
+
+Some fixers are *explicit*, meaning they aren't run be default and must be
+listed on the command line.  Here, in addition to the default fixers, the
+``idioms`` fixer is run::
+
+   $ 2to3 -f all -f idioms example.py
+
+Notice how ``all`` enables all default fixers.
+
+Sometimes 2to3 will find will find a place in your source code that needs to be
+changed, but 2to3 cannot fix automatically.  In this case, 2to3 will print a
+warning beneath the diff for a file.
+
+
+:mod:`lib2to3` - 2to3's library
+-------------------------------
+
+.. module:: lib2to3
+   :synopsis: the 2to3 library
+.. moduleauthor:: Guido van Rossum
+.. moduleauthor:: Collin Winter
+
+.. XXX What is the public interface anyway?
diff --git a/Doc/library/development.rst b/Doc/library/development.rst
index be8c33d..8cd3d0c 100644
--- a/Doc/library/development.rst
+++ b/Doc/library/development.rst
@@ -9,7 +9,8 @@ The modules described in this chapter help you write software.  For example, the
 :mod:`pydoc` module takes a module and generates documentation based on the
 module's contents.  The :mod:`doctest` and :mod:`unittest` modules contains
 frameworks for writing unit tests that automatically exercise code and verify
-that the expected output  is produced.
+that the expected output is produced.  :program:`2to3` can translate Python 2.x
+source code into valid Python 3.x code.
 
 The list of modules described in this chapter is:
 
@@ -19,4 +20,5 @@ The list of modules described in this chapter is:
    pydoc.rst
    doctest.rst
    unittest.rst
+   2to3.rst
    test.rst
diff --git a/Doc/library/email.message.rst b/Doc/library/email.message.rst
index f51230c..bb9c7c7 100644
--- a/Doc/library/email.message.rst
+++ b/Doc/library/email.message.rst
@@ -90,7 +90,7 @@ Here are the methods of the :class:`Message` class:
 
    .. method:: get_payload([i[, decode]])
 
-      Return a reference the current payload, which will be a list of
+      Return the current payload, which will be a list of
       :class:`Message` objects when :meth:`is_multipart` is ``True``, or a
       string when :meth:`is_multipart` is ``False``.  If the payload is a list
       and you mutate the list object, you modify the message's payload in place.
diff --git a/Doc/library/itertools.rst b/Doc/library/itertools.rst
index 3320d99..2d7e756 100644
--- a/Doc/library/itertools.rst
+++ b/Doc/library/itertools.rst
@@ -295,9 +295,10 @@ loops that truncate the stream.
           except IndexError:
               pass
 
-   If one of the iterables is potentially infinite, then the :func:`zip_longest`
-   function should be wrapped with something that limits the number of calls (for
-   example :func:`islice` or :func:`takewhile`).
+   If one of the iterables is potentially infinite, then the
+   :func:`izip_longest` function should be wrapped with something that limits
+   the number of calls (for example :func:`islice` or :func:`takewhile`).  If
+   not specified, *fillvalue* defaults to ``None``.
 
 
 .. function:: permutations(iterable[, r])
diff --git a/Doc/whatsnew/2.6.rst b/Doc/whatsnew/2.6.rst
index 203091f..a8d89cb 100644
--- a/Doc/whatsnew/2.6.rst
+++ b/Doc/whatsnew/2.6.rst
@@ -1144,7 +1144,7 @@ The :meth:`register`  method is useful when you've written a new
 ABC that can describe an existing type or class, or if you want
 to declare that some third-party class implements an ABC.
 For example, if you defined a :class:`PrintableType` ABC,
-it's legal to do:
+it's legal to do::
 
   # Register Python's types
   PrintableType.register(int)