Changeset 391 for python/trunk/Doc/library/2to3.rst

Timestamp:

Mar 19, 2014, 11:31:01 PM (11 years ago)

Author:

dmik

Message:

python: Merge vendor 2.7.6 to trunk.

Location:

python/trunk

Files:

• . (modified) (1 prop)
• Doc/library/2to3.rst (modified) (10 diffs)

python/trunk/Doc/library/2to3.rst

@@ -24 +24 @@
 
 2to3's basic arguments are a list of files or directories to transform.  The
-directories are to recursively traversed for Python sources.
+directories are recursively traversed for Python sources.
 
 Here is a sample Python 2.x source file, :file:`example.py`::
@@ -87 +87 @@
 process.
 
+Since some print statements can be parsed as function calls or statements, 2to3
+cannot always read files containing the print function.  When 2to3 detects the
+presence of the ``from __future__ import print_function`` compiler directive, it
+modifies its internal grammar to interpret :func:`print` as a function.  This
+change can also be enabled manually with the :option:`-p` flag.  Use
+:option:`-p` to run fixers on code that already has had its print statements
+converted.
+
+The :option:`-o` or :option:`--output-dir` option allows specification of an
+alternate directory for processed output files to be written to.  The
+:option:`-n` flag is required when using this as backup files do not make sense
+when not overwriting the input files.
+
+.. versionadded:: 2.7.3
+   The :option:`-o` option was added.
+
+The :option:`-W` or :option:`--write-unchanged-files` flag tells 2to3 to always
+write output files even if no changes were required to the file.  This is most
+useful with :option:`-o` so that an entire Python source tree is copied with
+translation from one directory to another.
+This option implies the :option:`-w` flag as it would not make sense otherwise.
+
+.. versionadded:: 2.7.3
+   The :option:`-W` flag was added.
+
+The :option:`--add-suffix` option specifies a string to append to all output
+filenames.  The :option:`-n` flag is required when specifying this as backups
+are not necessary when writing to different filenames.  Example::
+
+   $ 2to3 -n -W --add-suffix=3 example.py
+
+Will cause a converted file named ``example.py3`` to be written.
+
+.. versionadded:: 2.7.3
+   The :option:`--add-suffix` option was added.
+
+To translate an entire project from one directory tree to another use::
+
+   $ 2to3 --output-dir=python3-version/mycode -W -n python2-version/mycode
+
 
 .. _2to3-fixers:
@@ -93 +133 @@
 ------
 
-Each step of tranforming code is encapsulated in a fixer.  The command ``2to3
+Each step of transforming 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.
@@ -115 +155 @@
 .. 2to3fixer:: callable
 
-   Converts ``callable(x)`` to ``hasattr(x, "__call_")``.
+   Converts ``callable(x)`` to ``isinstance(x, collections.Callable)``, adding
+   an import to :mod:`collections` if needed. Note ``callable(x)`` has returned
+   in Python 3.2, so if you do not intend to support Python 3.1, you can disable
+   this fixer.
 
 .. 2to3fixer:: dict
@@ -121 +164 @@
    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`.
+   :meth:`dict.itervalues` to :meth:`dict.values`.  Similarly,
+   :meth:`dict.viewitems`, :meth:`dict.viewkeys` and :meth:`dict.viewvalues` are
+   converted respectively to :meth:`dict.items`, :meth:`dict.keys` and
+   :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
@@ -138 +183 @@
    wrapped in calls to :func:`open`, :func:`compile`, and :func:`exec`.
 
+.. 2to3fixer:: exitfunc
+
+   Changes assignment of :attr:`sys.exitfunc` to use of the :mod:`atexit`
+   module.
+
 .. 2to3fixer:: filter
 
@@ -161 +211 @@
 .. 2to3fixer:: idioms
 
-   This optional fixer preforms several transformations that make Python code
-   more idiomatic.  Type comparisions like ``type(x) is SomeClass`` and
+   This optional fixer performs several transformations that make Python code
+   more idiomatic.  Type comparisons 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 ::
+   :func:`sorted` in appropriate places.  For example, this block ::
 
        L = list(some_iterable)
@@ -215 +265 @@
 .. 2to3fixer:: long
 
-   Strips the ``L`` prefix on long literals and renames :class:`long` to
-   :class:`int`.
+   Renames :class:`long` to :class:`int`.
 
 .. 2to3fixer:: map
@@ -242 +291 @@
    Converts the use of iterator's :meth:`~iterator.next` methods to the
    :func:`next` function.  It also renames :meth:`next` methods to
-   :meth:`~object.__next__`.
+   :meth:`~iterator.__next__`.
 
 .. 2to3fixer:: nonzero
 
-   Renames :meth:`~object.__nonzero__` to :meth:`~object.__bool__`.
+   Renames :meth:`__nonzero__` to :meth:`~object.__bool__`.
 
 .. 2to3fixer:: numliterals
@@ -261 +310 @@
    Converts the :keyword:`print` statement to the :func:`print` function.
 
-.. 2to3fixer:: raises
+.. 2to3fixer:: raise
 
    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.
+   incorrect because substituting tuples for exceptions has been removed in Python 3.
 
 .. 2to3fixer:: raw_input