127 lines
4.2 KiB
ReStructuredText
127 lines
4.2 KiB
ReStructuredText
.. _imports:
|
|
|
|
Imports
|
|
=======
|
|
|
|
.. _-__future__-imports:
|
|
|
|
__future__ imports
|
|
------------------
|
|
|
|
To write a Python 2/3 compatible codebase, the first step is to add this line
|
|
to the top of each module::
|
|
|
|
from __future__ import absolute_import, division, print_function
|
|
|
|
For guidelines about whether to import ``unicode_literals`` too, see below
|
|
(:ref:`unicode-literals`).
|
|
|
|
For more information about the ``__future__`` imports, which are a
|
|
standard feature of Python, see the following docs:
|
|
|
|
- absolute_import: `PEP 328: Imports: Multi-Line and Absolute/Relative <http://www.python.org/dev/peps/pep-0328>`_
|
|
- division: `PEP 238: Changing the Division Operator <http://www.python.org/dev/peps/pep-0238>`_
|
|
- print_function: `PEP 3105: Make print a function <http://www.python.org/dev/peps/pep-3105>`_
|
|
- unicode_literals: `PEP 3112: Bytes literals in Python 3000 <http://www.python.org/dev/peps/pep-3112>`_
|
|
|
|
These are all available in Python 2.7 and up, and enabled by default in Python 3.x.
|
|
|
|
|
|
.. _builtins-imports:
|
|
|
|
Imports of builtins
|
|
-------------------
|
|
|
|
.. _star-imports:
|
|
|
|
Implicit imports
|
|
~~~~~~~~~~~~~~~~
|
|
|
|
If you don't mind namespace pollution, the easiest way to provide Py2/3
|
|
compatibility for new code using ``future`` is to include the following imports
|
|
at the top of every module::
|
|
|
|
from builtins import *
|
|
|
|
On Python 3, this has no effect. (It shadows builtins with globals of the same
|
|
names.)
|
|
|
|
On Python 2, this import line shadows 18 builtins (listed below) to
|
|
provide their Python 3 semantics.
|
|
|
|
|
|
.. _explicit-imports:
|
|
|
|
Explicit imports
|
|
~~~~~~~~~~~~~~~~
|
|
|
|
Explicit forms of the imports are often preferred and are necessary for using
|
|
certain automated code-analysis tools.
|
|
|
|
The complete set of imports of builtins from ``future`` is::
|
|
|
|
from builtins import (ascii, bytes, chr, dict, filter, hex, input,
|
|
int, map, next, oct, open, pow, range, round,
|
|
str, super, zip)
|
|
|
|
These are also available under the ``future.builtins`` namespace for backward compatibility.
|
|
|
|
Importing only some of the builtins is cleaner but increases the risk of
|
|
introducing Py2/3 portability bugs as your code evolves over time. For example,
|
|
be aware of forgetting to import ``input``, which could expose a security
|
|
vulnerability on Python 2 if Python 3's semantics are expected.
|
|
|
|
.. One further technical distinction is that unlike the ``import *`` form above,
|
|
.. these explicit imports do actually modify ``locals()`` on Py3; this is
|
|
.. equivalent to typing ``bytes = bytes; int = int`` etc. for each builtin.
|
|
|
|
The internal API is currently as follows::
|
|
|
|
from future.types import bytes, dict, int, range, str
|
|
from future.builtins.misc import (ascii, chr, hex, input, next,
|
|
oct, open, pow, round, super)
|
|
from future.builtins.iterators import filter, map, zip
|
|
|
|
Please note that this internal API is evolving and may not be stable between
|
|
different versions of ``future``. To understand the details of the backported
|
|
builtins on Python 2, see the docs for these modules.
|
|
|
|
For more information on what the backported types provide, see :ref:`what-else`.
|
|
|
|
.. < Section about past.translation is included here >
|
|
|
|
|
|
.. _obsolete-builtins:
|
|
|
|
Obsolete Python 2 builtins
|
|
__________________________
|
|
|
|
Twelve Python 2 builtins have been removed from Python 3. To aid with
|
|
porting code to Python 3 module by module, you can use the following
|
|
import to cause a ``NameError`` exception to be raised on Python 2 when any
|
|
of the obsolete builtins is used, just as would occur on Python 3::
|
|
|
|
from future.builtins.disabled import *
|
|
|
|
This is equivalent to::
|
|
|
|
from future.builtins.disabled import (apply, cmp, coerce, execfile,
|
|
file, long, raw_input, reduce, reload,
|
|
unicode, xrange, StandardError)
|
|
|
|
Running ``futurize`` over code that uses these Python 2 builtins does not
|
|
import the disabled versions; instead, it replaces them with their
|
|
equivalent Python 3 forms and then adds ``future`` imports to resurrect
|
|
Python 2 support, as described in :ref:`forwards-conversion-stage2`.
|
|
|
|
|
|
.. include:: standard_library_imports.rst
|
|
|
|
.. include:: translation.rst
|
|
|
|
.. include:: unicode_literals.rst
|
|
|
|
Next steps
|
|
----------
|
|
See :ref:`what-else`.
|