Skip to content

Commit 63df7dc

Browse files
edschofieldedschofield
committed
Update docs to reflect new with standard_library.enable_hooks() regime ...
1 parent 50ccc80 commit 63df7dc

6 files changed

Lines changed: 159 additions & 107 deletions

File tree

‎docs/changelog.rst‎

Lines changed: 14 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,18 @@ As usual, this has no effect on Python 3.
3636

3737
*Note*: this is a backward-incompatible change.
3838

39+
Simpler imports
40+
---------------
41+
42+
It is now possible to import builtins directly from the ``future``
43+
namespace as follows::
44+
45+
>>> from future import *
46+
47+
or just those you need::
48+
49+
>>> from future import open, str
50+
3951

4052
.. whats-new-0.10:
4153
@@ -48,8 +60,8 @@ Backported ``dict`` type
4860
``future.builtins`` now provides a Python 2 ``dict`` subclass whose
4961
:func:`keys`, :func:`values`, and :func:`items` methods produce
5062
memory-efficient iterators. On Python 2.7, these also have the same set-like
51-
view behaviour as on Python 3. This can streamline code needing to iterate over
52-
large dictionaries. For example::
63+
view behaviour as on Python 3. This can streamline code needing to iterate
64+
over large dictionaries. For example::
5365

5466
from __future__ import print_function
5567
from future.builtins import dict, range

‎docs/imports.rst‎

Lines changed: 55 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -6,60 +6,65 @@ Imports
66
future imports
77
~~~~~~~~~~~~~~
88

9-
The imports to include at the top of every Py2/3-compatible module using
10-
``future`` are::
9+
The easiest way to provide Py2/3 compatibility using ``future`` is to
10+
include the following imports at the top of every module::
1111

1212
from __future__ import (absolute_import, division,
1313
print_function, unicode_literals)
14-
from future import standard_library
15-
from future.builtins import *
14+
from future import *
1615

17-
On Python 3, these import lines have zero effect and zero namespace
18-
pollution.
16+
On Python 3, ``from future import *`` imports only two symbols: the modules
17+
``standard_library`` and ``utils``. No builtin functions are affected.
1918

20-
On Python 2, ``from future import standard_library`` installs
21-
import hooks to allow renamed and moved standard library modules to be
22-
imported from their new Py3 locations. See :ref:`standard-library` for more
23-
information.
19+
On Python 2, this import line also shadows 17 builtins (listed below) to
20+
provide their Python 3 semantics.
2421

25-
On Python 2, the ``from future.builtins import *`` line shadows builtins
26-
to provide their Python 3 semantics. (See :ref:`explicit-imports` for the
27-
explicit form.)
2822

23+
More explicit imports
24+
~~~~~~~~~~~~~~~~~~~~~
2925

30-
__future__ imports
31-
~~~~~~~~~~~~~~~~~~
26+
If you wish to be avoid namespace pollution on Python 3, an alternative set
27+
of imports is::
3228

33-
For more information about the ``__future__`` imports, which are a
34-
standard feature of Python, see the following docs:
29+
from __future__ import (absolute_import, division,
30+
print_function, unicode_literals)
31+
from future.builtins import *
3532

36-
- absolute_import: `PEP 328: Imports: Multi-Line and Absolute/Relative <http://www.python.org/dev/peps/pep-0328>`_
37-
- division: `PEP 238: Changing the Division Operator <http://www.python.org/dev/peps/pep-0238>`_
38-
- print_function: `PEP 3105: Make print a function <http://www.python.org/dev/peps/pep-3105>`_
39-
- unicode_literals: `PEP 3112: Bytes literals in Python 3000 <http://www.python.org/dev/peps/pep-3112>`_
33+
together with these module imports when necessary::
34+
35+
from future import standard_library, utils
4036

41-
These are all available in Python 2.6 and up, and enabled by default in Python 3.x.
37+
The advantage of this form is that on Python 3, the ``from future.builtins
38+
import *`` line has zero effect and zero namespace pollution.
39+
40+
On Python 2, ``from future.builtins import *`` shadows the same 17 builtins
41+
(see below) as with ``from future import *``.
4242

4343

4444
.. _explicit-imports:
4545

4646
Explicit imports
4747
~~~~~~~~~~~~~~~~
4848

49-
If you prefer explicit imports, the explicit equivalent of the ``from
50-
future.builtins import *`` line is::
51-
49+
If you prefer fully explicit imports, the most common set is::
50+
51+
from future import standard_library, utils
5252
from future.builtins import (filter, map, zip,
5353
ascii, chr, hex, input, oct, open,
5454
bytes, int, range, round, str, super)
5555

56+
(All the replaced builtins are also available in the ``future`` namespace.)
5657

57-
The disadvantage of importing only some of these builtins is that it
58+
The disadvantage of importing only some of the builtins is that it
5859
increases the risk of introducing Py2/3 portability bugs as your code
5960
evolves over time.
6061

61-
To understand the details of these functions on Python 2, see the docs
62-
for these modules:
62+
Also, a technical distinction is that unlike the ``import *`` forms above,
63+
these explicit imports do actually change ``locals()``; this is equivalent
64+
to typing ``filter = filter; map = map`` etc. for each builtin.
65+
66+
To understand the details of the backported builtins on Python 2, see the
67+
docs for these modules:
6368

6469
- future.builtins
6570
- future.builtins.iterators
@@ -83,8 +88,8 @@ Obsolete Python 2 builtins
8388

8489
Twelve Python 2 builtins have been removed from Python 3. To aid with
8590
porting code to Python 3 module by module, you can use the following
86-
import to cause a ``NameError`` exception to be raised on Python 2 as
87-
on Python 3 when any of the obsolete builtins is used::
91+
import to cause a ``NameError`` exception to be raised on Python 2 when any
92+
of the obsolete builtins is used, just as would occur on Python 3::
8893

8994
from future.builtins.disabled import *
9095

@@ -94,7 +99,24 @@ This is equivalent to::
9499
file, long, raw_input, reduce, reload,
95100
unicode, xrange, StandardError)
96101

97-
Running ``futurize`` over code that uses these Python 2 builtins replaces
98-
them with their Python 3 equivalents (which work on Py2 as well using
99-
``future`` imports.)
102+
Running ``futurize`` over code that uses these Python 2 builtins does not
103+
import the disabled versions; instead, it replaces them with their
104+
equivalent Python 3 forms and then adds ``future`` imports to resurrect
105+
Python 2 support.
106+
107+
108+
__future__ imports
109+
~~~~~~~~~~~~~~~~~~
110+
111+
For more information about the ``__future__`` imports, which are a
112+
standard feature of Python, see the following docs:
113+
114+
- absolute_import: `PEP 328: Imports: Multi-Line and Absolute/Relative <http://www.python.org/dev/peps/pep-0328>`_
115+
- division: `PEP 238: Changing the Division Operator <http://www.python.org/dev/peps/pep-0238>`_
116+
- print_function: `PEP 3105: Make print a function <http://www.python.org/dev/peps/pep-3105>`_
117+
- unicode_literals: `PEP 3112: Bytes literals in Python 3000 <http://www.python.org/dev/peps/pep-3112>`_
118+
119+
These are all available in Python 2.6 and up, and enabled by default in Python 3.x.
120+
121+
100122

‎docs/overview.rst‎

Lines changed: 14 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ to supporting both Python 2 and 3 in a single codebase, module by module.
1616
Features
1717
--------
1818

19-
- provides backports and remappings for 15 builtins with different
19+
- provides backports and remappings for 17 builtins with different
2020
semantics on Py3 versus Py2
2121
- provides backports and remappings from the Py3 standard library
2222
- 300+ unit tests
@@ -38,21 +38,15 @@ together with Python's built-in ``__future__`` module like this::
3838

3939
from __future__ import (absolute_import, division,
4040
print_function, unicode_literals)
41-
from future import standard_library
4241
from future.builtins import *
4342
44-
followed by standard Python 3 code. The imports have no effect on Python
45-
3 but allow the code to run mostly unchanged on Python 3 and Python 2.6/2.7.
43+
followed by mostly standard Python 3 code. The imports have no effect on
44+
Python 3 but allow the code to run mostly unchanged on Python 3 and Python
45+
2.6/2.7.
4646

4747
For example, this code behaves the same way on Python 2.6/2.7 after these
4848
imports as it normally does on Python 3::
4949
50-
# Support for renamed standard library modules via import hooks
51-
from http.client import HttpConnection
52-
from itertools import filterfalse
53-
import html.parser
54-
import queue
55-
5650
# Backported Py3 bytes object
5751
b = bytes(b'ABCD')
5852
assert list(b) == [65, 66, 67, 68]
@@ -102,6 +96,16 @@ imports as it normally does on Python 3::
10296
assert isinstance('blah', str) # with unicode_literals in effect
10397
assert isinstance(b'bytestring', bytes)
10498

99+
There is also support for renamed standard library modules in the form of a context manager that provides import hooks:
100+
101+
from future import standard_library
102+
103+
with standard_library.enable_hooks():
104+
from http.client import HttpConnection
105+
from itertools import filterfalse
106+
import html.parser
107+
import queue
108+
105109

106110
Next steps
107111
----------

‎docs/quickstart.rst‎

Lines changed: 25 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,6 @@ Start each module with these lines::
2626

2727
from __future__ import (absolute_import, division,
2828
print_function, unicode_literals)
29-
from future import standard_library
3029
from future.builtins import *
3130

3231
Then write standard Python 3 code. The :mod:`future` package will
@@ -44,19 +43,12 @@ module::
4443

4544
from __future__ import (absolute_import, division,
4645
print_function, unicode_literals)
47-
from future import standard_library
4846
from future.builtins import *
4947
5048
and converts a few Python 3-only constructs to a form compatible with
5149
both Py3 and Py2. Most remaining Python 3 code should simply work on
5250
Python 2.
5351

54-
For a realistic example, you can see the included `backported
55-
http.client module
56-
<https://github.com/PythonCharmers/python-future/blob/master/future/standard_library/http/client.py>`_,
57-
and look at the diff between this and the Python 3.3 module (e.g.
58-
``/usr/lib/python3.3/http/client.py``).
59-
6052
See :ref:`backwards-conversion` for more details.
6153

6254

@@ -80,37 +72,40 @@ be accessed under their Python 3 names and locations in Python 2::
8072
8173
from future import standard_library
8274
83-
import socketserver
84-
import queue
85-
import configparser
86-
import test.support
87-
import html.parser
88-
from collections import UserList
89-
from itertools import filterfalse, zip_longest
90-
from http.client import HttpConnection
91-
# and other moved modules and definitions
75+
with standard_library.enable_hooks():
76+
import socketserver
77+
import queue
78+
import configparser
79+
import test.support
80+
import html.parser
81+
from collections import UserList
82+
from itertools import filterfalse, zip_longest
83+
from http.client import HttpConnection
84+
# and other moved modules and definitions
9285

9386
:mod:`future` also includes backports for these stdlib modules from Py3
9487
that were heavily refactored versus Py2::
9588
96-
import html
97-
import html.entities
98-
import html.parser
89+
with standard_library.enable_hooks():
90+
import html
91+
import html.entities
92+
import html.parser
9993

100-
import http
101-
import http.client
102-
import http.server
94+
import http
95+
import http.client
96+
import http.server
10397

10498
These modules are currently not supported, but we aim to support them in
10599
the future::
106100
107-
import http.cookies
108-
import http.cookiejar
109-
110-
import urllib
111-
import urllib.parse
112-
import urllib.request
113-
import urllib.error
101+
with standard_library.enable_hooks():
102+
import http.cookies
103+
import http.cookiejar
104+
105+
import urllib
106+
import urllib.parse
107+
import urllib.request
108+
import urllib.error
114109

115110
If you need one of these, please open an issue `here
116111
<https://github.com/PythonCharmers/python-future>`_.

‎future/__init__.py‎

Lines changed: 35 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -1,32 +1,50 @@
11
"""
2-
future: Easy, safe support for Python 2/3 compatibility
2+
future: Easy, safe support for Python 3/2 compatibility
33
=======================================================
44
5-
``future`` is the missing compatibility layer between Python 2 and Python 3. It allows you to use a single, clean Python 3.x-compatible codebase to support both Python 2 and Python 3 with minimal overhead.
5+
``future`` is the missing compatibility layer between Python 3 and Python
6+
2. It allows you to use a single, clean Python 3.x-compatible codebase to
7+
support both Python 3 and Python 2 with minimal overhead.
68
79
Notable projects that use ``future`` for Python 2/3 compatibility are `Mezzanine <http://mezzanine.jupo.org/>`_ and `xlwt-future <https://pypi.python.org/pypi/xlwt-future>`_.
810
911
It is designed to be used as follows::
1012
1113
from __future__ import (absolute_import, division,
1214
print_function, unicode_literals)
13-
from future import standard_library
14-
from future.builtins import * # or explicit imports: str, int, bytes,
15-
# open, super, range, zip, input, etc.
16-
17-
followed by predominantly standard, idiomatic Python 3 code that then runs similarly on Python 2.6/2.7 and Python 3.3+.
15+
from future import *
1816
19-
On Python 3, the import lines have zero effect (and zero namespace
20-
pollution).
17+
or with explicit imports::
2118
22-
On Python 2, ``from future import standard_library`` installs
23-
import hooks to allow renamed and moved standard library modules to be
24-
imported from their new Py3 locations. On Python 2, the ``from future.builtins import *`` line shadows all builtins with different behaviour in Python 3 versus 2 to provide their Python 3 semantics.
19+
from future.builtins import (filter, map, zip,
20+
ascii, chr, hex, input, oct, open,
21+
bytes, int, range, round, str, super)
22+
23+
followed by predominantly standard, idiomatic Python 3 code that then runs
24+
similarly on Python 2.6/2.7 and Python 3.3+.
25+
26+
On Python 3, the import lines have zero effect.
27+
28+
On Python 2, the import lines shadow all the builtins with different
29+
behaviour in Python 3 versus 2 to provide their Python 3 semantics.
30+
31+
32+
Standard library reorganization
33+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
34+
35+
``from future import standard_library`` provides a context-manager called
36+
``enable_hooks`` that installs import hooks (PEP 3108) to allow renamed and
37+
moved standard library modules to be imported from their new Py3 locations.
2538
2639
2740
Automatic conversion
2841
--------------------
29-
An included script called `futurize <http://python-future.org/automatic_conversion.html>`_ aids in converting code (from either Python 2 or Python 3) to code compatible with both platforms. It is similar to ``python-modernize`` but goes further in providing Python 3 compatibility through the use of the backported types and builtin functions in ``future``.
42+
An included script called `futurize
43+
<http://python-future.org/automatic_conversion.html>`_ aids in converting
44+
code (from either Python 2 or Python 3) to code compatible with both
45+
platforms. It is similar to ``python-modernize`` but goes further in
46+
providing Python 3 compatibility through the use of the backported types
47+
and builtin functions in ``future``.
3048
3149
3250
Documentation
@@ -66,12 +84,12 @@
6684
6785
"""
6886

69-
# No namespace pollution
70-
__all__ = []
87+
from future import standard_library, utils
88+
from future.builtins import *
7189

7290
__ver_major__ = 0
73-
__ver_minor__ = 10
74-
__ver_patch__ = 1
91+
__ver_minor__ = 11
92+
__ver_patch__ = 0
7593
__ver_sub__ = ''
7694
__version__ = "%d.%d.%d%s" % (__ver_major__, __ver_minor__,
7795
__ver_patch__, __ver_sub__)

0 commit comments

Comments
 (0)