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
........
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 @@
automatically.
+.. _2to3-using:
+
Using 2to3
----------
@@ -52,10 +54,10 @@
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 @@
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