diff options
| -rw-r--r-- | Doc/library/2to3.rst | 261 | ||||
| -rw-r--r-- | Doc/tools/sphinxext/pyspecific.py | 1 |
2 files changed, 258 insertions, 4 deletions
diff --git a/Doc/library/2to3.rst b/Doc/library/2to3.rst index 24c563c..db60a76 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 @@ -85,6 +87,257 @@ The :option:`-v` option enables output of more information on the translation process. +.. _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 ------------------------------- diff --git a/Doc/tools/sphinxext/pyspecific.py b/Doc/tools/sphinxext/pyspecific.py index be6f78d..05cbe37 100644 --- a/Doc/tools/sphinxext/pyspecific.py +++ b/Doc/tools/sphinxext/pyspecific.py @@ -135,3 +135,4 @@ def setup(app): app.add_builder(suspicious.CheckSuspiciousMarkupBuilder) app.add_description_unit('opcode', 'opcode', '%s (opcode)', parse_opcode_signature) + app.add_description_unit('2to3fixer', '2to3fixer', '%s (2to3 fixer)') |