1.. _imports: 2 3Imports 4======= 5 6.. _-__future__-imports: 7 8__future__ imports 9------------------ 10 11To write a Python 2/3 compatible codebase, the first step is to add this line 12to the top of each module:: 13 14 from __future__ import absolute_import, division, print_function 15 16For guidelines about whether to import ``unicode_literals`` too, see below 17(:ref:`unicode-literals`). 18 19For more information about the ``__future__`` imports, which are a 20standard feature of Python, see the following docs: 21 22- absolute_import: `PEP 328: Imports: Multi-Line and Absolute/Relative <http://www.python.org/dev/peps/pep-0328>`_ 23- division: `PEP 238: Changing the Division Operator <http://www.python.org/dev/peps/pep-0238>`_ 24- print_function: `PEP 3105: Make print a function <http://www.python.org/dev/peps/pep-3105>`_ 25- unicode_literals: `PEP 3112: Bytes literals in Python 3000 <http://www.python.org/dev/peps/pep-3112>`_ 26 27These are all available in Python 2.7 and up, and enabled by default in Python 3.x. 28 29 30.. _builtins-imports: 31 32Imports of builtins 33------------------- 34 35.. _star-imports: 36 37Implicit imports 38~~~~~~~~~~~~~~~~ 39 40If you don't mind namespace pollution, the easiest way to provide Py2/3 41compatibility for new code using ``future`` is to include the following imports 42at the top of every module:: 43 44 from builtins import * 45 46On Python 3, this has no effect. (It shadows builtins with globals of the same 47names.) 48 49On Python 2, this import line shadows 18 builtins (listed below) to 50provide their Python 3 semantics. 51 52 53.. _explicit-imports: 54 55Explicit imports 56~~~~~~~~~~~~~~~~ 57 58Explicit forms of the imports are often preferred and are necessary for using 59certain automated code-analysis tools. 60 61The complete set of imports of builtins from ``future`` is:: 62 63 from builtins import (ascii, bytes, chr, dict, filter, hex, input, 64 int, map, next, oct, open, pow, range, round, 65 str, super, zip) 66 67These are also available under the ``future.builtins`` namespace for backward compatibility. 68 69Importing only some of the builtins is cleaner but increases the risk of 70introducing Py2/3 portability bugs as your code evolves over time. For example, 71be aware of forgetting to import ``input``, which could expose a security 72vulnerability on Python 2 if Python 3's semantics are expected. 73 74.. One further technical distinction is that unlike the ``import *`` form above, 75.. these explicit imports do actually modify ``locals()`` on Py3; this is 76.. equivalent to typing ``bytes = bytes; int = int`` etc. for each builtin. 77 78The internal API is currently as follows:: 79 80 from future.types import bytes, dict, int, range, str 81 from future.builtins.misc import (ascii, chr, hex, input, next, 82 oct, open, pow, round, super) 83 from future.builtins.iterators import filter, map, zip 84 85Please note that this internal API is evolving and may not be stable between 86different versions of ``future``. To understand the details of the backported 87builtins on Python 2, see the docs for these modules. 88 89For more information on what the backported types provide, see :ref:`what-else`. 90 91.. < Section about past.translation is included here > 92 93 94.. _obsolete-builtins: 95 96Obsolete Python 2 builtins 97__________________________ 98 99Twelve Python 2 builtins have been removed from Python 3. To aid with 100porting code to Python 3 module by module, you can use the following 101import to cause a ``NameError`` exception to be raised on Python 2 when any 102of the obsolete builtins is used, just as would occur on Python 3:: 103 104 from future.builtins.disabled import * 105 106This is equivalent to:: 107 108 from future.builtins.disabled import (apply, cmp, coerce, execfile, 109 file, long, raw_input, reduce, reload, 110 unicode, xrange, StandardError) 111 112Running ``futurize`` over code that uses these Python 2 builtins does not 113import the disabled versions; instead, it replaces them with their 114equivalent Python 3 forms and then adds ``future`` imports to resurrect 115Python 2 support, as described in :ref:`forwards-conversion-stage2`. 116 117 118.. include:: standard_library_imports.rst 119 120.. include:: translation.rst 121 122.. include:: unicode_literals.rst 123 124Next steps 125---------- 126See :ref:`what-else`. 127