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