Benjamin Peterson | d631371 | 2008-07-31 16:23:04 +0000 | [diff] [blame] | 1 | .. _2to3-reference: |
| 2 | |
| 3 | 2to3 - Automated Python 2 to 3 code translation |
| 4 | =============================================== |
| 5 | |
Benjamin Peterson | 058e31e | 2009-01-16 03:54:08 +0000 | [diff] [blame] | 6 | .. sectionauthor:: Benjamin Peterson <benjamin@python.org> |
Benjamin Peterson | d631371 | 2008-07-31 16:23:04 +0000 | [diff] [blame] | 7 | |
Benjamin Peterson | 8951b61 | 2008-09-03 02:27:16 +0000 | [diff] [blame] | 8 | 2to3 is a Python program that reads Python 2.x source code and applies a series |
| 9 | of *fixers* to transform it into valid Python 3.x code. The standard library |
Benjamin Peterson | ae5360b | 2008-09-08 23:05:23 +0000 | [diff] [blame] | 10 | contains a rich set of fixers that will handle almost all code. 2to3 supporting |
| 11 | library :mod:`lib2to3` is, however, a flexible and generic library, so it is |
| 12 | possible to write your own fixers for 2to3. :mod:`lib2to3` could also be |
| 13 | adapted to custom applications in which Python code needs to be edited |
| 14 | automatically. |
Benjamin Peterson | d631371 | 2008-07-31 16:23:04 +0000 | [diff] [blame] | 15 | |
| 16 | |
Benjamin Peterson | f91df04 | 2009-02-13 02:50:59 +0000 | [diff] [blame] | 17 | .. _2to3-using: |
| 18 | |
Benjamin Peterson | d631371 | 2008-07-31 16:23:04 +0000 | [diff] [blame] | 19 | Using 2to3 |
| 20 | ---------- |
| 21 | |
Benjamin Peterson | ae5360b | 2008-09-08 23:05:23 +0000 | [diff] [blame] | 22 | 2to3 will usually be installed with the Python interpreter as a script. It is |
| 23 | also located in the :file:`Tools/scripts` directory of the Python root. |
| 24 | |
| 25 | 2to3's basic arguments are a list of files or directories to transform. The |
Chris Jerdonek | 4639749 | 2012-10-11 15:59:32 -0700 | [diff] [blame] | 26 | directories are recursively traversed for Python sources. |
Benjamin Peterson | d631371 | 2008-07-31 16:23:04 +0000 | [diff] [blame] | 27 | |
| 28 | Here is a sample Python 2.x source file, :file:`example.py`:: |
| 29 | |
| 30 | def greet(name): |
| 31 | print "Hello, {0}!".format(name) |
| 32 | print "What's your name?" |
| 33 | name = raw_input() |
| 34 | greet(name) |
| 35 | |
Martin Panter | 1050d2d | 2016-07-26 11:18:21 +0200 | [diff] [blame] | 36 | It can be converted to Python 3.x code via 2to3 on the command line: |
| 37 | |
| 38 | .. code-block:: shell-session |
Benjamin Peterson | d631371 | 2008-07-31 16:23:04 +0000 | [diff] [blame] | 39 | |
| 40 | $ 2to3 example.py |
| 41 | |
Benjamin Peterson | ae5360b | 2008-09-08 23:05:23 +0000 | [diff] [blame] | 42 | A diff against the original source file is printed. 2to3 can also write the |
Benjamin Peterson | ad3d5c2 | 2009-02-26 03:38:59 +0000 | [diff] [blame] | 43 | needed modifications right back to the source file. (A backup of the original |
Martin Panter | 5c67933 | 2016-10-30 04:20:17 +0000 | [diff] [blame] | 44 | file is made unless :option:`!-n` is also given.) Writing the changes back is |
| 45 | enabled with the :option:`!-w` flag: |
Martin Panter | 1050d2d | 2016-07-26 11:18:21 +0200 | [diff] [blame] | 46 | |
| 47 | .. code-block:: shell-session |
Benjamin Peterson | d631371 | 2008-07-31 16:23:04 +0000 | [diff] [blame] | 48 | |
| 49 | $ 2to3 -w example.py |
| 50 | |
Benjamin Peterson | ae5360b | 2008-09-08 23:05:23 +0000 | [diff] [blame] | 51 | After transformation, :file:`example.py` looks like this:: |
Benjamin Peterson | d631371 | 2008-07-31 16:23:04 +0000 | [diff] [blame] | 52 | |
| 53 | def greet(name): |
| 54 | print("Hello, {0}!".format(name)) |
| 55 | print("What's your name?") |
| 56 | name = input() |
| 57 | greet(name) |
| 58 | |
Benjamin Peterson | 1a6e0d0 | 2008-10-25 15:49:17 +0000 | [diff] [blame] | 59 | Comments and exact indentation are preserved throughout the translation process. |
Benjamin Peterson | d631371 | 2008-07-31 16:23:04 +0000 | [diff] [blame] | 60 | |
Benjamin Peterson | f91df04 | 2009-02-13 02:50:59 +0000 | [diff] [blame] | 61 | By default, 2to3 runs a set of :ref:`predefined fixers <2to3-fixers>`. The |
Martin Panter | 254da19 | 2016-07-26 06:46:06 +0000 | [diff] [blame] | 62 | :option:`!-l` flag lists all available fixers. An explicit set of fixers to run |
Martin Panter | 5c67933 | 2016-10-30 04:20:17 +0000 | [diff] [blame] | 63 | can be given with :option:`!-f`. Likewise the :option:`!-x` explicitly disables a |
Martin Panter | 1050d2d | 2016-07-26 11:18:21 +0200 | [diff] [blame] | 64 | fixer. The following example runs only the ``imports`` and ``has_key`` fixers: |
| 65 | |
| 66 | .. code-block:: shell-session |
Benjamin Peterson | d631371 | 2008-07-31 16:23:04 +0000 | [diff] [blame] | 67 | |
| 68 | $ 2to3 -f imports -f has_key example.py |
| 69 | |
Martin Panter | 1050d2d | 2016-07-26 11:18:21 +0200 | [diff] [blame] | 70 | This command runs every fixer except the ``apply`` fixer: |
| 71 | |
| 72 | .. code-block:: shell-session |
Benjamin Peterson | 206e307 | 2008-10-19 14:07:49 +0000 | [diff] [blame] | 73 | |
| 74 | $ 2to3 -x apply example.py |
| 75 | |
Benjamin Peterson | 1a6e0d0 | 2008-10-25 15:49:17 +0000 | [diff] [blame] | 76 | Some fixers are *explicit*, meaning they aren't run by default and must be |
Benjamin Peterson | ae5360b | 2008-09-08 23:05:23 +0000 | [diff] [blame] | 77 | listed on the command line to be run. Here, in addition to the default fixers, |
Martin Panter | 1050d2d | 2016-07-26 11:18:21 +0200 | [diff] [blame] | 78 | the ``idioms`` fixer is run: |
| 79 | |
| 80 | .. code-block:: shell-session |
Benjamin Peterson | d631371 | 2008-07-31 16:23:04 +0000 | [diff] [blame] | 81 | |
| 82 | $ 2to3 -f all -f idioms example.py |
| 83 | |
Benjamin Peterson | ae5360b | 2008-09-08 23:05:23 +0000 | [diff] [blame] | 84 | Notice how passing ``all`` enables all default fixers. |
Benjamin Peterson | d631371 | 2008-07-31 16:23:04 +0000 | [diff] [blame] | 85 | |
Benjamin Peterson | 1a6e0d0 | 2008-10-25 15:49:17 +0000 | [diff] [blame] | 86 | Sometimes 2to3 will find a place in your source code that needs to be changed, |
| 87 | but 2to3 cannot fix automatically. In this case, 2to3 will print a warning |
| 88 | beneath the diff for a file. You should address the warning in order to have |
| 89 | compliant 3.x code. |
Benjamin Peterson | ae5360b | 2008-09-08 23:05:23 +0000 | [diff] [blame] | 90 | |
Martin Panter | 00ccacc | 2016-04-16 04:59:38 +0000 | [diff] [blame] | 91 | 2to3 can also refactor doctests. To enable this mode, use the :option:`!-d` |
Benjamin Peterson | e9bbc8b | 2008-09-28 02:06:32 +0000 | [diff] [blame] | 92 | flag. Note that *only* doctests will be refactored. This also doesn't require |
| 93 | the module to be valid Python. For example, doctest like examples in a reST |
| 94 | document could also be refactored with this option. |
Benjamin Peterson | ae5360b | 2008-09-08 23:05:23 +0000 | [diff] [blame] | 95 | |
Martin Panter | 00ccacc | 2016-04-16 04:59:38 +0000 | [diff] [blame] | 96 | The :option:`!-v` option enables output of more information on the translation |
Benjamin Peterson | 206e307 | 2008-10-19 14:07:49 +0000 | [diff] [blame] | 97 | process. |
Benjamin Peterson | ae5360b | 2008-09-08 23:05:23 +0000 | [diff] [blame] | 98 | |
Benjamin Peterson | a0dfa82 | 2009-11-13 02:25:08 +0000 | [diff] [blame] | 99 | Since some print statements can be parsed as function calls or statements, 2to3 |
| 100 | cannot always read files containing the print function. When 2to3 detects the |
| 101 | presence of the ``from __future__ import print_function`` compiler directive, it |
Georg Brandl | 6faee4e | 2010-09-21 14:48:28 +0000 | [diff] [blame] | 102 | modifies its internal grammar to interpret :func:`print` as a function. This |
Martin Panter | 5c67933 | 2016-10-30 04:20:17 +0000 | [diff] [blame] | 103 | change can also be enabled manually with the :option:`!-p` flag. Use |
| 104 | :option:`!-p` to run fixers on code that already has had its print statements |
Benjamin Peterson | a0dfa82 | 2009-11-13 02:25:08 +0000 | [diff] [blame] | 105 | converted. |
| 106 | |
Martin Panter | 5c67933 | 2016-10-30 04:20:17 +0000 | [diff] [blame] | 107 | The :option:`!-o` or :option:`!--output-dir` option allows specification of an |
Gregory P. Smith | 58f23ff | 2012-02-12 15:50:21 -0800 | [diff] [blame] | 108 | alternate directory for processed output files to be written to. The |
Martin Panter | 5c67933 | 2016-10-30 04:20:17 +0000 | [diff] [blame] | 109 | :option:`!-n` flag is required when using this as backup files do not make sense |
Gregory P. Smith | 58f23ff | 2012-02-12 15:50:21 -0800 | [diff] [blame] | 110 | when not overwriting the input files. |
| 111 | |
| 112 | .. versionadded:: 3.2.3 |
Martin Panter | 5c67933 | 2016-10-30 04:20:17 +0000 | [diff] [blame] | 113 | The :option:`!-o` option was added. |
Gregory P. Smith | 58f23ff | 2012-02-12 15:50:21 -0800 | [diff] [blame] | 114 | |
Martin Panter | 5c67933 | 2016-10-30 04:20:17 +0000 | [diff] [blame] | 115 | The :option:`!-W` or :option:`!--write-unchanged-files` flag tells 2to3 to always |
Gregory P. Smith | 58f23ff | 2012-02-12 15:50:21 -0800 | [diff] [blame] | 116 | write output files even if no changes were required to the file. This is most |
Martin Panter | 5c67933 | 2016-10-30 04:20:17 +0000 | [diff] [blame] | 117 | useful with :option:`!-o` so that an entire Python source tree is copied with |
Gregory P. Smith | 58f23ff | 2012-02-12 15:50:21 -0800 | [diff] [blame] | 118 | translation from one directory to another. |
Martin Panter | 5c67933 | 2016-10-30 04:20:17 +0000 | [diff] [blame] | 119 | This option implies the :option:`!-w` flag as it would not make sense otherwise. |
Gregory P. Smith | 58f23ff | 2012-02-12 15:50:21 -0800 | [diff] [blame] | 120 | |
| 121 | .. versionadded:: 3.2.3 |
Martin Panter | 00ccacc | 2016-04-16 04:59:38 +0000 | [diff] [blame] | 122 | The :option:`!-W` flag was added. |
Gregory P. Smith | 58f23ff | 2012-02-12 15:50:21 -0800 | [diff] [blame] | 123 | |
Martin Panter | 5c67933 | 2016-10-30 04:20:17 +0000 | [diff] [blame] | 124 | The :option:`!--add-suffix` option specifies a string to append to all output |
| 125 | filenames. The :option:`!-n` flag is required when specifying this as backups |
Martin Panter | 1050d2d | 2016-07-26 11:18:21 +0200 | [diff] [blame] | 126 | are not necessary when writing to different filenames. Example: |
| 127 | |
| 128 | .. code-block:: shell-session |
Gregory P. Smith | 58f23ff | 2012-02-12 15:50:21 -0800 | [diff] [blame] | 129 | |
| 130 | $ 2to3 -n -W --add-suffix=3 example.py |
| 131 | |
| 132 | Will cause a converted file named ``example.py3`` to be written. |
| 133 | |
| 134 | .. versionadded:: 3.2.3 |
Martin Panter | 5c67933 | 2016-10-30 04:20:17 +0000 | [diff] [blame] | 135 | The :option:`!--add-suffix` option was added. |
Gregory P. Smith | 58f23ff | 2012-02-12 15:50:21 -0800 | [diff] [blame] | 136 | |
Martin Panter | 1050d2d | 2016-07-26 11:18:21 +0200 | [diff] [blame] | 137 | To translate an entire project from one directory tree to another use: |
| 138 | |
| 139 | .. code-block:: shell-session |
Gregory P. Smith | 58f23ff | 2012-02-12 15:50:21 -0800 | [diff] [blame] | 140 | |
| 141 | $ 2to3 --output-dir=python3-version/mycode -W -n python2-version/mycode |
| 142 | |
Benjamin Peterson | f91df04 | 2009-02-13 02:50:59 +0000 | [diff] [blame] | 143 | |
| 144 | .. _2to3-fixers: |
| 145 | |
| 146 | Fixers |
| 147 | ------ |
| 148 | |
Georg Brandl | ae2dbe2 | 2009-03-13 19:04:40 +0000 | [diff] [blame] | 149 | Each step of transforming code is encapsulated in a fixer. The command ``2to3 |
Benjamin Peterson | f91df04 | 2009-02-13 02:50:59 +0000 | [diff] [blame] | 150 | -l`` lists them. As :ref:`documented above <2to3-using>`, each can be turned on |
| 151 | and off individually. They are described here in more detail. |
| 152 | |
| 153 | |
| 154 | .. 2to3fixer:: apply |
| 155 | |
| 156 | Removes usage of :func:`apply`. For example ``apply(function, *args, |
| 157 | **kwargs)`` is converted to ``function(*args, **kwargs)``. |
| 158 | |
Ezio Melotti | 6bdd986 | 2013-11-23 21:14:42 +0200 | [diff] [blame] | 159 | .. 2to3fixer:: asserts |
| 160 | |
| 161 | Replaces deprecated :mod:`unittest` method names with the correct ones. |
| 162 | |
| 163 | ================================ ========================================== |
| 164 | From To |
| 165 | ================================ ========================================== |
| 166 | ``failUnlessEqual(a, b)`` :meth:`assertEqual(a, b) |
| 167 | <unittest.TestCase.assertEqual>` |
| 168 | ``assertEquals(a, b)`` :meth:`assertEqual(a, b) |
| 169 | <unittest.TestCase.assertEqual>` |
| 170 | ``failIfEqual(a, b)`` :meth:`assertNotEqual(a, b) |
| 171 | <unittest.TestCase.assertNotEqual>` |
| 172 | ``assertNotEquals(a, b)`` :meth:`assertNotEqual(a, b) |
| 173 | <unittest.TestCase.assertNotEqual>` |
| 174 | ``failUnless(a)`` :meth:`assertTrue(a) |
| 175 | <unittest.TestCase.assertTrue>` |
| 176 | ``assert_(a)`` :meth:`assertTrue(a) |
| 177 | <unittest.TestCase.assertTrue>` |
| 178 | ``failIf(a)`` :meth:`assertFalse(a) |
| 179 | <unittest.TestCase.assertFalse>` |
| 180 | ``failUnlessRaises(exc, cal)`` :meth:`assertRaises(exc, cal) |
| 181 | <unittest.TestCase.assertRaises>` |
| 182 | ``failUnlessAlmostEqual(a, b)`` :meth:`assertAlmostEqual(a, b) |
| 183 | <unittest.TestCase.assertAlmostEqual>` |
| 184 | ``assertAlmostEquals(a, b)`` :meth:`assertAlmostEqual(a, b) |
| 185 | <unittest.TestCase.assertAlmostEqual>` |
| 186 | ``failIfAlmostEqual(a, b)`` :meth:`assertNotAlmostEqual(a, b) |
| 187 | <unittest.TestCase.assertNotAlmostEqual>` |
| 188 | ``assertNotAlmostEquals(a, b)`` :meth:`assertNotAlmostEqual(a, b) |
| 189 | <unittest.TestCase.assertNotAlmostEqual>` |
| 190 | ================================ ========================================== |
| 191 | |
Benjamin Peterson | f91df04 | 2009-02-13 02:50:59 +0000 | [diff] [blame] | 192 | .. 2to3fixer:: basestring |
| 193 | |
| 194 | Converts :class:`basestring` to :class:`str`. |
| 195 | |
| 196 | .. 2to3fixer:: buffer |
| 197 | |
| 198 | Converts :class:`buffer` to :class:`memoryview`. This fixer is optional |
| 199 | because the :class:`memoryview` API is similar but not exactly the same as |
| 200 | that of :class:`buffer`. |
| 201 | |
Benjamin Peterson | f91df04 | 2009-02-13 02:50:59 +0000 | [diff] [blame] | 202 | .. 2to3fixer:: dict |
| 203 | |
| 204 | Fixes dictionary iteration methods. :meth:`dict.iteritems` is converted to |
| 205 | :meth:`dict.items`, :meth:`dict.iterkeys` to :meth:`dict.keys`, and |
Alexandre Vassalotti | a515bab | 2010-01-12 18:38:14 +0000 | [diff] [blame] | 206 | :meth:`dict.itervalues` to :meth:`dict.values`. Similarly, |
Benjamin Peterson | e90f54e | 2010-03-21 23:17:57 +0000 | [diff] [blame] | 207 | :meth:`dict.viewitems`, :meth:`dict.viewkeys` and :meth:`dict.viewvalues` are |
| 208 | converted respectively to :meth:`dict.items`, :meth:`dict.keys` and |
Alexandre Vassalotti | a515bab | 2010-01-12 18:38:14 +0000 | [diff] [blame] | 209 | :meth:`dict.values`. It also wraps existing usages of :meth:`dict.items`, |
| 210 | :meth:`dict.keys`, and :meth:`dict.values` in a call to :class:`list`. |
Benjamin Peterson | f91df04 | 2009-02-13 02:50:59 +0000 | [diff] [blame] | 211 | |
| 212 | .. 2to3fixer:: except |
| 213 | |
| 214 | Converts ``except X, T`` to ``except X as T``. |
| 215 | |
| 216 | .. 2to3fixer:: exec |
| 217 | |
Georg Brandl | 375aec2 | 2011-01-15 17:03:02 +0000 | [diff] [blame] | 218 | Converts the ``exec`` statement to the :func:`exec` function. |
Benjamin Peterson | f91df04 | 2009-02-13 02:50:59 +0000 | [diff] [blame] | 219 | |
| 220 | .. 2to3fixer:: execfile |
| 221 | |
| 222 | Removes usage of :func:`execfile`. The argument to :func:`execfile` is |
| 223 | wrapped in calls to :func:`open`, :func:`compile`, and :func:`exec`. |
| 224 | |
Benjamin Peterson | e90f54e | 2010-03-21 23:17:57 +0000 | [diff] [blame] | 225 | .. 2to3fixer:: exitfunc |
| 226 | |
| 227 | Changes assignment of :attr:`sys.exitfunc` to use of the :mod:`atexit` |
| 228 | module. |
| 229 | |
Benjamin Peterson | f91df04 | 2009-02-13 02:50:59 +0000 | [diff] [blame] | 230 | .. 2to3fixer:: filter |
| 231 | |
| 232 | Wraps :func:`filter` usage in a :class:`list` call. |
| 233 | |
| 234 | .. 2to3fixer:: funcattrs |
| 235 | |
| 236 | Fixes function attributes that have been renamed. For example, |
| 237 | ``my_function.func_closure`` is converted to ``my_function.__closure__``. |
| 238 | |
| 239 | .. 2to3fixer:: future |
| 240 | |
| 241 | Removes ``from __future__ import new_feature`` statements. |
| 242 | |
| 243 | .. 2to3fixer:: getcwdu |
| 244 | |
| 245 | Renames :func:`os.getcwdu` to :func:`os.getcwd`. |
| 246 | |
| 247 | .. 2to3fixer:: has_key |
| 248 | |
| 249 | Changes ``dict.has_key(key)`` to ``key in dict``. |
| 250 | |
| 251 | .. 2to3fixer:: idioms |
| 252 | |
Georg Brandl | ae2dbe2 | 2009-03-13 19:04:40 +0000 | [diff] [blame] | 253 | This optional fixer performs several transformations that make Python code |
| 254 | more idiomatic. Type comparisons like ``type(x) is SomeClass`` and |
Benjamin Peterson | f91df04 | 2009-02-13 02:50:59 +0000 | [diff] [blame] | 255 | ``type(x) == SomeClass`` are converted to ``isinstance(x, SomeClass)``. |
| 256 | ``while 1`` becomes ``while True``. This fixer also tries to make use of |
Georg Brandl | ae2dbe2 | 2009-03-13 19:04:40 +0000 | [diff] [blame] | 257 | :func:`sorted` in appropriate places. For example, this block :: |
Benjamin Peterson | f91df04 | 2009-02-13 02:50:59 +0000 | [diff] [blame] | 258 | |
| 259 | L = list(some_iterable) |
| 260 | L.sort() |
| 261 | |
| 262 | is changed to :: |
| 263 | |
| 264 | L = sorted(some_iterable) |
| 265 | |
| 266 | .. 2to3fixer:: import |
| 267 | |
| 268 | Detects sibling imports and converts them to relative imports. |
| 269 | |
| 270 | .. 2to3fixer:: imports |
| 271 | |
| 272 | Handles module renames in the standard library. |
| 273 | |
| 274 | .. 2to3fixer:: imports2 |
| 275 | |
| 276 | Handles other modules renames in the standard library. It is separate from |
| 277 | the :2to3fixer:`imports` fixer only because of technical limitations. |
| 278 | |
| 279 | .. 2to3fixer:: input |
| 280 | |
Martin Panter | d21e0b5 | 2015-10-10 10:36:22 +0000 | [diff] [blame] | 281 | Converts ``input(prompt)`` to ``eval(input(prompt))``. |
Benjamin Peterson | f91df04 | 2009-02-13 02:50:59 +0000 | [diff] [blame] | 282 | |
| 283 | .. 2to3fixer:: intern |
| 284 | |
| 285 | Converts :func:`intern` to :func:`sys.intern`. |
| 286 | |
| 287 | .. 2to3fixer:: isinstance |
| 288 | |
| 289 | Fixes duplicate types in the second argument of :func:`isinstance`. For |
| 290 | example, ``isinstance(x, (int, int))`` is converted to ``isinstance(x, |
Eli Boyarski | 26248ef | 2017-07-24 03:39:07 +0300 | [diff] [blame] | 291 | int)`` and ``isinstance(x, (int, float, int))`` is converted to |
| 292 | ``isinstance(x, (int, float))``. |
Benjamin Peterson | f91df04 | 2009-02-13 02:50:59 +0000 | [diff] [blame] | 293 | |
| 294 | .. 2to3fixer:: itertools_imports |
| 295 | |
| 296 | Removes imports of :func:`itertools.ifilter`, :func:`itertools.izip`, and |
| 297 | :func:`itertools.imap`. Imports of :func:`itertools.ifilterfalse` are also |
| 298 | changed to :func:`itertools.filterfalse`. |
| 299 | |
| 300 | .. 2to3fixer:: itertools |
| 301 | |
| 302 | Changes usage of :func:`itertools.ifilter`, :func:`itertools.izip`, and |
Georg Brandl | 22b3431 | 2009-07-26 14:54:51 +0000 | [diff] [blame] | 303 | :func:`itertools.imap` to their built-in equivalents. |
Benjamin Peterson | f91df04 | 2009-02-13 02:50:59 +0000 | [diff] [blame] | 304 | :func:`itertools.ifilterfalse` is changed to :func:`itertools.filterfalse`. |
| 305 | |
| 306 | .. 2to3fixer:: long |
| 307 | |
Benjamin Peterson | 4dafd40 | 2013-01-28 18:28:38 -0500 | [diff] [blame] | 308 | Renames :class:`long` to :class:`int`. |
Benjamin Peterson | f91df04 | 2009-02-13 02:50:59 +0000 | [diff] [blame] | 309 | |
| 310 | .. 2to3fixer:: map |
| 311 | |
| 312 | Wraps :func:`map` in a :class:`list` call. It also changes ``map(None, x)`` |
| 313 | to ``list(x)``. Using ``from future_builtins import map`` disables this |
| 314 | fixer. |
| 315 | |
| 316 | .. 2to3fixer:: metaclass |
| 317 | |
| 318 | Converts the old metaclass syntax (``__metaclass__ = Meta`` in the class |
| 319 | body) to the new (``class X(metaclass=Meta)``). |
| 320 | |
| 321 | .. 2to3fixer:: methodattrs |
| 322 | |
| 323 | Fixes old method attribute names. For example, ``meth.im_func`` is converted |
| 324 | to ``meth.__func__``. |
| 325 | |
| 326 | .. 2to3fixer:: ne |
| 327 | |
| 328 | Converts the old not-equal syntax, ``<>``, to ``!=``. |
| 329 | |
| 330 | .. 2to3fixer:: next |
| 331 | |
Georg Brandl | 502d9a5 | 2009-07-26 15:02:41 +0000 | [diff] [blame] | 332 | Converts the use of iterator's :meth:`~iterator.next` methods to the |
| 333 | :func:`next` function. It also renames :meth:`next` methods to |
Serhiy Storchaka | bfdcd43 | 2013-10-13 23:09:14 +0300 | [diff] [blame] | 334 | :meth:`~iterator.__next__`. |
Benjamin Peterson | f91df04 | 2009-02-13 02:50:59 +0000 | [diff] [blame] | 335 | |
| 336 | .. 2to3fixer:: nonzero |
| 337 | |
Serhiy Storchaka | bfdcd43 | 2013-10-13 23:09:14 +0300 | [diff] [blame] | 338 | Renames :meth:`__nonzero__` to :meth:`~object.__bool__`. |
Benjamin Peterson | f91df04 | 2009-02-13 02:50:59 +0000 | [diff] [blame] | 339 | |
| 340 | .. 2to3fixer:: numliterals |
| 341 | |
| 342 | Converts octal literals into the new syntax. |
| 343 | |
Alexandre Vassalotti | ae78018 | 2010-08-05 07:12:18 +0000 | [diff] [blame] | 344 | .. 2to3fixer:: operator |
| 345 | |
| 346 | Converts calls to various functions in the :mod:`operator` module to other, |
| 347 | but equivalent, function calls. When needed, the appropriate ``import`` |
Serhiy Storchaka | 0a2abdf | 2017-11-16 09:16:24 +0200 | [diff] [blame] | 348 | statements are added, e.g. ``import collections.abc``. The following mapping |
Alexandre Vassalotti | ae78018 | 2010-08-05 07:12:18 +0000 | [diff] [blame] | 349 | are made: |
| 350 | |
Serhiy Storchaka | 0a2abdf | 2017-11-16 09:16:24 +0200 | [diff] [blame] | 351 | ================================== ============================================= |
Alexandre Vassalotti | ae78018 | 2010-08-05 07:12:18 +0000 | [diff] [blame] | 352 | From To |
Serhiy Storchaka | 0a2abdf | 2017-11-16 09:16:24 +0200 | [diff] [blame] | 353 | ================================== ============================================= |
Dong-hee Na | a489599 | 2017-11-29 01:26:56 +0900 | [diff] [blame^] | 354 | ``operator.isCallable(obj)`` ``callable(obj)`` |
Alexandre Vassalotti | ae78018 | 2010-08-05 07:12:18 +0000 | [diff] [blame] | 355 | ``operator.sequenceIncludes(obj)`` ``operator.contains(obj)`` |
Serhiy Storchaka | 0a2abdf | 2017-11-16 09:16:24 +0200 | [diff] [blame] | 356 | ``operator.isSequenceType(obj)`` ``isinstance(obj, collections.abc.Sequence)`` |
| 357 | ``operator.isMappingType(obj)`` ``isinstance(obj, collections.abc.Mapping)`` |
Alexandre Vassalotti | ae78018 | 2010-08-05 07:12:18 +0000 | [diff] [blame] | 358 | ``operator.isNumberType(obj)`` ``isinstance(obj, numbers.Number)`` |
| 359 | ``operator.repeat(obj, n)`` ``operator.mul(obj, n)`` |
| 360 | ``operator.irepeat(obj, n)`` ``operator.imul(obj, n)`` |
Serhiy Storchaka | 0a2abdf | 2017-11-16 09:16:24 +0200 | [diff] [blame] | 361 | ================================== ============================================= |
Alexandre Vassalotti | ae78018 | 2010-08-05 07:12:18 +0000 | [diff] [blame] | 362 | |
Benjamin Peterson | f91df04 | 2009-02-13 02:50:59 +0000 | [diff] [blame] | 363 | .. 2to3fixer:: paren |
| 364 | |
| 365 | Add extra parenthesis where they are required in list comprehensions. For |
| 366 | example, ``[x for x in 1, 2]`` becomes ``[x for x in (1, 2)]``. |
| 367 | |
| 368 | .. 2to3fixer:: print |
| 369 | |
Georg Brandl | 375aec2 | 2011-01-15 17:03:02 +0000 | [diff] [blame] | 370 | Converts the ``print`` statement to the :func:`print` function. |
Benjamin Peterson | f91df04 | 2009-02-13 02:50:59 +0000 | [diff] [blame] | 371 | |
Benjamin Peterson | b51b5c4 | 2010-07-01 17:49:01 +0000 | [diff] [blame] | 372 | .. 2to3fixer:: raise |
Benjamin Peterson | f91df04 | 2009-02-13 02:50:59 +0000 | [diff] [blame] | 373 | |
| 374 | Converts ``raise E, V`` to ``raise E(V)``, and ``raise E, V, T`` to ``raise |
| 375 | E(V).with_traceback(T)``. If ``E`` is a tuple, the translation will be |
| 376 | incorrect because substituting tuples for exceptions has been removed in 3.0. |
| 377 | |
| 378 | .. 2to3fixer:: raw_input |
| 379 | |
| 380 | Converts :func:`raw_input` to :func:`input`. |
| 381 | |
| 382 | .. 2to3fixer:: reduce |
| 383 | |
| 384 | Handles the move of :func:`reduce` to :func:`functools.reduce`. |
| 385 | |
Benjamin Peterson | 448e81b | 2012-12-07 22:44:10 -0500 | [diff] [blame] | 386 | .. 2to3fixer:: reload |
| 387 | |
| 388 | Converts :func:`reload` to :func:`imp.reload`. |
| 389 | |
Benjamin Peterson | f91df04 | 2009-02-13 02:50:59 +0000 | [diff] [blame] | 390 | .. 2to3fixer:: renames |
| 391 | |
| 392 | Changes :data:`sys.maxint` to :data:`sys.maxsize`. |
| 393 | |
| 394 | .. 2to3fixer:: repr |
| 395 | |
| 396 | Replaces backtick repr with the :func:`repr` function. |
| 397 | |
| 398 | .. 2to3fixer:: set_literal |
| 399 | |
| 400 | Replaces use of the :class:`set` constructor with set literals. This fixer |
| 401 | is optional. |
| 402 | |
Benjamin Peterson | a819577 | 2014-05-31 13:16:49 -0700 | [diff] [blame] | 403 | .. 2to3fixer:: standarderror |
Benjamin Peterson | f91df04 | 2009-02-13 02:50:59 +0000 | [diff] [blame] | 404 | |
| 405 | Renames :exc:`StandardError` to :exc:`Exception`. |
| 406 | |
| 407 | .. 2to3fixer:: sys_exc |
| 408 | |
| 409 | Changes the deprecated :data:`sys.exc_value`, :data:`sys.exc_type`, |
| 410 | :data:`sys.exc_traceback` to use :func:`sys.exc_info`. |
| 411 | |
| 412 | .. 2to3fixer:: throw |
| 413 | |
| 414 | Fixes the API change in generator's :meth:`throw` method. |
| 415 | |
| 416 | .. 2to3fixer:: tuple_params |
| 417 | |
| 418 | Removes implicit tuple parameter unpacking. This fixer inserts temporary |
| 419 | variables. |
| 420 | |
| 421 | .. 2to3fixer:: types |
| 422 | |
| 423 | Fixes code broken from the removal of some members in the :mod:`types` |
| 424 | module. |
| 425 | |
| 426 | .. 2to3fixer:: unicode |
| 427 | |
| 428 | Renames :class:`unicode` to :class:`str`. |
| 429 | |
| 430 | .. 2to3fixer:: urllib |
| 431 | |
| 432 | Handles the rename of :mod:`urllib` and :mod:`urllib2` to the :mod:`urllib` |
| 433 | package. |
| 434 | |
| 435 | .. 2to3fixer:: ws_comma |
| 436 | |
| 437 | Removes excess whitespace from comma separated items. This fixer is |
| 438 | optional. |
| 439 | |
| 440 | .. 2to3fixer:: xrange |
| 441 | |
| 442 | Renames :func:`xrange` to :func:`range` and wraps existing :func:`range` |
| 443 | calls with :class:`list`. |
| 444 | |
| 445 | .. 2to3fixer:: xreadlines |
| 446 | |
| 447 | Changes ``for x in file.xreadlines()`` to ``for x in file``. |
| 448 | |
| 449 | .. 2to3fixer:: zip |
| 450 | |
| 451 | Wraps :func:`zip` usage in a :class:`list` call. This is disabled when |
| 452 | ``from future_builtins import zip`` appears. |
Benjamin Peterson | d631371 | 2008-07-31 16:23:04 +0000 | [diff] [blame] | 453 | |
| 454 | |
| 455 | :mod:`lib2to3` - 2to3's library |
| 456 | ------------------------------- |
| 457 | |
| 458 | .. module:: lib2to3 |
| 459 | :synopsis: the 2to3 library |
Terry Jan Reedy | fa089b9 | 2016-06-11 15:02:54 -0400 | [diff] [blame] | 460 | |
Benjamin Peterson | d631371 | 2008-07-31 16:23:04 +0000 | [diff] [blame] | 461 | .. moduleauthor:: Guido van Rossum |
| 462 | .. moduleauthor:: Collin Winter |
Benjamin Peterson | 25c95f1 | 2009-05-08 20:42:26 +0000 | [diff] [blame] | 463 | .. moduleauthor:: Benjamin Peterson <benjamin@python.org> |
Benjamin Peterson | d631371 | 2008-07-31 16:23:04 +0000 | [diff] [blame] | 464 | |
Terry Jan Reedy | fa089b9 | 2016-06-11 15:02:54 -0400 | [diff] [blame] | 465 | **Source code:** :source:`Lib/lib2to3/` |
| 466 | |
| 467 | -------------- |
Benjamin Peterson | e9bbc8b | 2008-09-28 02:06:32 +0000 | [diff] [blame] | 468 | |
Georg Brandl | e720c0a | 2009-04-27 16:20:50 +0000 | [diff] [blame] | 469 | .. note:: |
Benjamin Peterson | e9bbc8b | 2008-09-28 02:06:32 +0000 | [diff] [blame] | 470 | |
| 471 | The :mod:`lib2to3` API should be considered unstable and may change |
| 472 | drastically in the future. |
| 473 | |
Benjamin Peterson | d631371 | 2008-07-31 16:23:04 +0000 | [diff] [blame] | 474 | .. XXX What is the public interface anyway? |