Merged revisions 69364-69365,69409-69410,69413,69417,69435,69442,69447,69495,69519-69521 via svnmerge from

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

........
  r69364 | kristjan.jonsson | 2009-02-06 04:17:34 -0600 (Fri, 06 Feb 2009) | 1 line

  Fix a number of Win32ErrorTests error cases.  chmod wasn't being tested.  'access' never raises an error.
........
  r69365 | armin.rigo | 2009-02-06 05:46:26 -0600 (Fri, 06 Feb 2009) | 2 lines

  Ivan on IRC in #twisted reported this crasher.
........
  r69409 | georg.brandl | 2009-02-07 06:21:17 -0600 (Sat, 07 Feb 2009) | 1 line

  #5174: fix wrong file closing in example.
........
  r69410 | neil.schemenauer | 2009-02-07 08:53:31 -0600 (Sat, 07 Feb 2009) | 4 lines

  Fix broken test in test_hotshot.  Treating the current directory as an
  empty file is sloppy and non-portable.  Use NamedTemporaryFile to make
  an empty file.
........
  r69413 | neil.schemenauer | 2009-02-07 12:35:16 -0600 (Sat, 07 Feb 2009) | 2 lines

  Add test for issue #999042, explict global statement works.
........
  r69417 | benjamin.peterson | 2009-02-07 17:01:19 -0600 (Sat, 07 Feb 2009) | 1 line

  document individual 2to3 fixers
........
  r69435 | benjamin.peterson | 2009-02-08 08:38:13 -0600 (Sun, 08 Feb 2009) | 1 line

  document numliterals fixer
........
  r69442 | benjamin.peterson | 2009-02-08 09:14:57 -0600 (Sun, 08 Feb 2009) | 1 line

  a few edits and typos
........
  r69447 | vinay.sajip | 2009-02-08 13:06:08 -0600 (Sun, 08 Feb 2009) | 2 lines

  Issue #5170: Fixed Unicode output bug in logging and added test case. This is a regression which did not occur in 2.5.
........
  r69495 | kristjan.jonsson | 2009-02-10 07:32:24 -0600 (Tue, 10 Feb 2009) | 1 line

  Issue 4804.  Add a function to test the validity of file descriptors on Windows, and stop using global runtime settings to silence the warnings / assertions.
........
  r69519 | gregory.p.smith | 2009-02-11 17:45:25 -0600 (Wed, 11 Feb 2009) | 3 lines

  Issue #1008086: Fixes socket.inet_aton() to always return 4 bytes even
  on LP64 platforms (most 64-bit Linux, bsd, unix systems).
........
  r69520 | benjamin.peterson | 2009-02-11 21:50:00 -0600 (Wed, 11 Feb 2009) | 1 line

  os.fsync() should be used to ensure that data is written to disk
........
  r69521 | benjamin.peterson | 2009-02-11 22:17:04 -0600 (Wed, 11 Feb 2009) | 1 line

  no need for this __bases__ trick anymore
........

1 files changed, 263 insertions, 10 deletions

diff --git a/Doc/library/2to3.rst b/Doc/library/2to3.rst
index 375bd10..7ab34da 100644
--- a/Doc/library/2to3.rst
+++ b/Doc/library/2to3.rst
@@ -14,6 +14,8 @@ adapted to custom applications in which Python code needs to be edited
 automatically.
 
 
+.. _2to3-using:
+
 Using 2to3
 ----------
 
@@ -52,10 +54,10 @@ After transformation, :file:`example.py` looks like this::
 
 Comments and exact indentation are preserved throughout the translation process.
 
-By default, 2to3 runs a set of predefined fixers.  The :option:`-l` flag lists
-all available fixers.  An explicit set of fixers to run can be given with
-:option:`-f`.  Likewise the :option:`-x` explicitly disables a fixer.  The
-following example runs only the ``imports`` and ``has_key`` fixers::
+By default, 2to3 runs a set of :ref:`predefined fixers <2to3-fixers>`.  The
+:option:`-l` flag lists all available fixers.  An explicit set of fixers to run
+can be given with :option:`-f`.  Likewise the :option:`-x` explicitly disables a
+fixer.  The following example runs only the ``imports`` and ``has_key`` fixers::
 
    $ 2to3 -f imports -f has_key example.py
 
@@ -84,12 +86,263 @@ document could also be refactored with this option.
 The :option:`-v` option enables output of more information on the translation
 process.
 
-When the :option:`-p` is passed, 2to3 treats ``print`` as a function instead of
-a statement.  This is useful when ``from __future__ import print_function`` is
-being used.  If this option is not given, the print fixer will surround print
-calls in an extra set of parentheses because it cannot differentiate between the
-print statement with parentheses (such as ``print ("a" + "b" + "c")``) and a
-true function call.
+When the :option:`-p` is passed, the :2to3fixer:`print` fixer ``print`` as a
+function instead of a statement.  This is useful when ``from __future__ import
+print_function`` is being used.  If this option is not given, the print fixer
+will surround print calls in an extra set of parentheses because it cannot
+differentiate between the print statement with parentheses (such as ``print
+("a" + "b" + "c")``) and a true function call.
+
+
+.. _2to3-fixers:
+
+Fixers
+------
+
+Each step of tranforming code is encapsulated in a fixer.  The command ``2to3
+-l`` lists them.  As :ref:`documented above <2to3-using>`, each can be turned on
+and off individually.  They are described here in more detail.
+
+
+.. 2to3fixer:: apply
+
+   Removes usage of :func:`apply`.  For example ``apply(function, *args,
+   **kwargs)`` is converted to ``function(*args, **kwargs)``.
+
+.. 2to3fixer:: basestring
+
+   Converts :class:`basestring` to :class:`str`.
+
+.. 2to3fixer:: buffer
+
+   Converts :class:`buffer` to :class:`memoryview`.  This fixer is optional
+   because the :class:`memoryview` API is similar but not exactly the same as
+   that of :class:`buffer`.
+
+.. 2to3fixer:: callable
+
+   Converts ``callable(x)`` to ``hasattr(x, "__call_")``.
+
+.. 2to3fixer:: dict
+
+   Fixes dictionary iteration methods.  :meth:`dict.iteritems` is converted to
+   :meth:`dict.items`, :meth:`dict.iterkeys` to :meth:`dict.keys`, and
+   :meth:`dict.itervalues` to :meth:`dict.values`.  It also wraps existing
+   usages of :meth:`dict.items`, :meth:`dict.keys`, and :meth:`dict.values` in a
+   call to :class:`list`.
+
+.. 2to3fixer:: except
+
+   Converts ``except X, T`` to ``except X as T``.
+
+.. 2to3fixer:: exec
+
+   Converts the :keyword:`exec` statement to the :func:`exec` function.
+
+.. 2to3fixer:: execfile
+
+   Removes usage of :func:`execfile`.  The argument to :func:`execfile` is
+   wrapped in calls to :func:`open`, :func:`compile`, and :func:`exec`.
+
+.. 2to3fixer:: filter
+
+   Wraps :func:`filter` usage in a :class:`list` call.
+
+.. 2to3fixer:: funcattrs
+
+   Fixes function attributes that have been renamed.  For example,
+   ``my_function.func_closure`` is converted to ``my_function.__closure__``.
+
+.. 2to3fixer:: future
+
+   Removes ``from __future__ import new_feature`` statements.
+
+.. 2to3fixer:: getcwdu
+
+   Renames :func:`os.getcwdu` to :func:`os.getcwd`.
+
+.. 2to3fixer:: has_key
+
+   Changes ``dict.has_key(key)`` to ``key in dict``.
+
+.. 2to3fixer:: idioms
+
+   This optional fixer preforms several transformations that make Python code
+   more idiomatic.  Type comparisions like ``type(x) is SomeClass`` and
+   ``type(x) == SomeClass`` are converted to ``isinstance(x, SomeClass)``.
+   ``while 1`` becomes ``while True``.  This fixer also tries to make use of
+   :func:`sorted` in appropiate places.  For example, this block ::
+
+       L = list(some_iterable)
+       L.sort()
+
+   is changed to ::
+
+      L = sorted(some_iterable)
+
+.. 2to3fixer:: import
+
+   Detects sibling imports and converts them to relative imports.
+
+.. 2to3fixer:: imports
+
+   Handles module renames in the standard library.
+
+.. 2to3fixer:: imports2
+
+   Handles other modules renames in the standard library.  It is separate from
+   the :2to3fixer:`imports` fixer only because of technical limitations.
+
+.. 2to3fixer:: input
+
+   Converts ``input(prompt)`` to ``eval(input(prompt))``
+
+.. 2to3fixer:: intern
+
+   Converts :func:`intern` to :func:`sys.intern`.
+
+.. 2to3fixer:: isinstance
+
+   Fixes duplicate types in the second argument of :func:`isinstance`.  For
+   example, ``isinstance(x, (int, int))`` is converted to ``isinstance(x,
+   (int))``.
+
+.. 2to3fixer:: itertools_imports
+
+   Removes imports of :func:`itertools.ifilter`, :func:`itertools.izip`, and
+   :func:`itertools.imap`.  Imports of :func:`itertools.ifilterfalse` are also
+   changed to :func:`itertools.filterfalse`.
+
+.. 2to3fixer:: itertools
+
+   Changes usage of :func:`itertools.ifilter`, :func:`itertools.izip`, and
+   :func:`itertools.imap` to their builtin equivalents.
+   :func:`itertools.ifilterfalse` is changed to :func:`itertools.filterfalse`.
+
+.. 2to3fixer:: long
+
+   Strips the ``L`` prefix on long literals and renames :class:`long` to
+   :class:`int`.
+
+.. 2to3fixer:: map
+
+   Wraps :func:`map` in a :class:`list` call.  It also changes ``map(None, x)``
+   to ``list(x)``.  Using ``from future_builtins import map`` disables this
+   fixer.
+
+.. 2to3fixer:: metaclass
+
+   Converts the old metaclass syntax (``__metaclass__ = Meta`` in the class
+   body) to the new (``class X(metaclass=Meta)``).
+
+.. 2to3fixer:: methodattrs
+
+   Fixes old method attribute names.  For example, ``meth.im_func`` is converted
+   to ``meth.__func__``.
+
+.. 2to3fixer:: ne
+
+   Converts the old not-equal syntax, ``<>``, to ``!=``.
+
+.. 2to3fixer:: next
+
+   Converts the use of iterator's :meth:`next` methods to the :func:`next`
+   function.  It also renames :meth:`next` methods to :meth:`~object.__next__`.
+
+.. 2to3fixer:: nonzero
+
+   Renames :meth:`~object.__nonzero__` to :meth:`~object.__bool__`.
+
+.. 2to3fixer:: numliterals
+
+   Converts octal literals into the new syntax.
+
+.. 2to3fixer:: paren
+
+   Add extra parenthesis where they are required in list comprehensions.  For
+   example, ``[x for x in 1, 2]`` becomes ``[x for x in (1, 2)]``.
+
+.. 2to3fixer:: print
+
+   Converts the :keyword:`print` statement to the :func:`print` function.
+
+.. 2to3fixer:: raises
+
+   Converts ``raise E, V`` to ``raise E(V)``, and ``raise E, V, T`` to ``raise
+   E(V).with_traceback(T)``.  If ``E`` is a tuple, the translation will be
+   incorrect because substituting tuples for exceptions has been removed in 3.0.
+
+.. 2to3fixer:: raw_input
+
+   Converts :func:`raw_input` to :func:`input`.
+
+.. 2to3fixer:: reduce
+
+   Handles the move of :func:`reduce` to :func:`functools.reduce`.
+
+.. 2to3fixer:: renames
+
+   Changes :data:`sys.maxint` to :data:`sys.maxsize`.
+
+.. 2to3fixer:: repr
+
+   Replaces backtick repr with the :func:`repr` function.
+
+.. 2to3fixer:: set_literal
+
+   Replaces use of the :class:`set` constructor with set literals.  This fixer
+   is optional.
+
+.. 2to3fixer:: standard_error
+
+   Renames :exc:`StandardError` to :exc:`Exception`.
+
+.. 2to3fixer:: sys_exc
+
+   Changes the deprecated :data:`sys.exc_value`, :data:`sys.exc_type`,
+   :data:`sys.exc_traceback` to use :func:`sys.exc_info`.
+
+.. 2to3fixer:: throw
+
+   Fixes the API change in generator's :meth:`throw` method.
+
+.. 2to3fixer:: tuple_params
+
+   Removes implicit tuple parameter unpacking.  This fixer inserts temporary
+   variables.
+
+.. 2to3fixer:: types
+
+   Fixes code broken from the removal of some members in the :mod:`types`
+   module.
+
+.. 2to3fixer:: unicode
+
+   Renames :class:`unicode` to :class:`str`.
+
+.. 2to3fixer:: urllib
+
+   Handles the rename of :mod:`urllib` and :mod:`urllib2` to the :mod:`urllib`
+   package.
+
+.. 2to3fixer:: ws_comma
+
+   Removes excess whitespace from comma separated items.  This fixer is
+   optional.
+
+.. 2to3fixer:: xrange
+
+   Renames :func:`xrange` to :func:`range` and wraps existing :func:`range`
+   calls with :class:`list`.
+
+.. 2to3fixer:: xreadlines
+
+   Changes ``for x in file.xreadlines()`` to ``for x in file``.
+
+.. 2to3fixer:: zip
+
+   Wraps :func:`zip` usage in a :class:`list` call.  This is disabled when
+   ``from future_builtins import zip`` appears.
 
 
 :mod:`lib2to3` - 2to3's library