Merge branch 'v0.12.x' of https://github.com/PythonCharmers/python-future into v0.12.x

Author: edschofield

README.rst

@@ -25,11 +25,11 @@ Features
 -   ``future.builtins`` package provides backports and remappings for 19
     builtins with different semantics on Py3 versus Py2
 
--   ``future.standard_library`` package provides backports from the Py3.3
-    standard library
+-   ``future.standard_library``, in conjunction with ``future.moves``, provides
+    support for importing standard library modules under their Python 3 names
 
--   ``future.moves`` package provides support for reorganized standard library
-    modules (renames from native packages)
+-   ``future.backports`` package provides backports from the Py3.3
+    standard library
 
 -   ``past.builtins`` package provides forward-ports of Python 2 types and
     resurrects some Python 2 builtins (to aid with per-module code migrations)
@@ -108,16 +108,16 @@ these imports as it does on Python 3.3+:
     name = input('What is your name? ')
     print('Hello ' + name)
 
+    # pow() supports fractional exponents of negative numbers like in Py3:
+    z = pow(-1, 0.5)
+
     # Compatible output from isinstance() across Py2/3:
     assert isinstance(2**64, int)        # long integers
     assert isinstance(u'blah', str)
     assert isinstance('blah', str)       # only if unicode_literals is in effect
 
-    # pow() supports fractional exponents of negative numbers like in Py3:
-    z = pow(-1, 0.5)
-
     # Py3-style iterators written as new-style classes (subclasses of
-    # future.builtins.object) are backward compatibile with Py2:
+    # future.builtins.object) are automatically backward compatible with Py2:
     class Upper(object):
         def __init__(self, iterable):
             self._iter = iter(iterable)
@@ -172,24 +172,38 @@ For example, running ``futurize -w mymodule.py`` turns this Python 2 code:
 
 .. code-block:: python
     
-    import ConfigParser
+    import Queue
+    from urllib2 import urlopen
 
-    class Blah(object):
-        pass
-    print 'Hello',
+
+    def greet(name):
+        print 'Hello',
+        print name
+
+    print 'What's your name?',
+    name = raw_input()
+    greet(name)
 
 into this code which runs on both Py2 and Py3:
 
 .. code-block:: python
     
     from __future__ import print_function
+    from future.builtins import input
     from future import standard_library
+    standard_library.install_hooks()
+    import queue
+    from urllib.request import urlopen
     
-    import configparser
 
-    class Blah(object):
-        pass
-    print('Hello', end=' ')
+    def greet(name):
+        print('Hello', end=' ')
+        print(name)
+
+    print('What's your name?', end=' ')
+    name = input()
+    greet(name)
+
 
 For complex projects, it may be better to divide the porting into two stages.
 ``futurize`` supports a ``--stage1`` flag for safe changes that modernize the

docs/custom_iterators.rst

@@ -3,13 +3,15 @@
 Custom iterators
 ----------------
 
-If you define your own iterators, there is an incompatibility in the special method name
-across Py3 and Py2. On Python 3 it is ``__next__``, whereas on Python 2 it is
-``next``.
+If you define your own iterators, there is an incompatibility in the method name
+to retrieve the next item across Py3 and Py2. On Python 3 it is ``__next__``,
+whereas on Python 2 it is ``next``.
 
 The most elegant solution to this is to derive your custom iterator class from
-``future.builtins.object``. This provides a special fallback ``next`` method
-that maps to ``__next__``. Use it as follows::
+``future.builtins.object`` and define a ``__next__`` method as you normally
+would on Python 3. On Python 2, ``object`` then refers to the
+``future.types.newobject`` base class, which provides a fallback ``next``
+method that calls your ``__next__``. Use it as follows::
 
     from future.builtins import object
     
@@ -27,11 +29,12 @@ that maps to ``__next__``. Use it as follows::
     assert list(itr) == list('LLO')
 
 
-This works unless you are defining a subclass of a base class defined elsewhere
-that does not derive from ``future.builtins.object``.
+You can use this approach unless you are defining a custom iterator as a
+subclass of a base class defined elsewhere that does not derive from
+``future.builtins.object``.  In that case, you can provide compatibility across
+Python 2 and Python 3 using the ``next`` function from ``future.builtins``::
 
-In this case, you can provide compatibility across Python 2 and Python 3 using the ``next``
-function in ``future.builtins``::
+    from future.builtins import next
 
     from some_module import some_base_class
 
@@ -43,8 +46,6 @@ function in ``future.builtins``::
         def __iter__(self):
             return self
 
-    from future.builtins import next
-
     itr2 = Upper2('hello')
     assert next(itr2) == 'H'
     assert next(itr2) == 'E'
@@ -55,17 +56,17 @@ function in ``future.builtins``::
     assert 'next' in dir(itr3)
     assert next(itr3) == 'one'
 
-This works whenever your code calls the ``next()`` function explicitly. If you
-consume the iterator implicitly in a ``for`` loop or ``list()`` call or by some
-other method, the ``future.builtins.next`` function will not help; the third
-assertion below would fail on Python 2::
+This approach is feasible whenever your code calls the ``next()`` function
+explicitly. If you consume the iterator implicitly in a ``for`` loop or
+``list()`` call or by some other means, the ``future.builtins.next`` function
+will not help; the third assertion below would fail on Python 2::
 
     itr2 = Upper2('hello')
 
     assert next(itr2) == 'H'
     assert next(itr2) == 'E'
     assert list(itr2) == list('LLO')      # fails because Py2 implicitly looks
-                                          # for a ``__next__`` method.
+                                          # for a ``next`` method.
 
 Instead, you can use a decorator called ``implements_iterator`` from
 ``future.utils`` to allow Py3-style iterators to work identically on Py2, even

docs/quickstart.rst

@@ -65,7 +65,7 @@ See :ref:`backwards-conversion` for more details.
 To convert existing Python 2 code
 ---------------------------------
 
-Start with the :ref:`automatic-conversion` page.
+Start with this page: :ref:`automatic-conversion`.
 
 .. If you already know Python 3, start with the :ref:`automatic-conversion` page.
 .. If you don't know Python 3 yet, start with :ref:`python3-essentials`.
@@ -77,7 +77,7 @@ Standard library reorganization
 -------------------------------
 
 :mod:`future` supports the standard library reorganization (PEP 3108)
-via import hooks, allowing almost all moved standard library modules to
+via import hooks, allowing most moved standard library modules to
 be accessed under their Python 3 names and locations in Python 2::
     
     from future import standard_library
@@ -107,28 +107,6 @@ be accessed under their Python 3 names and locations in Python 2::
         import xmlrpc.client
         import xmlrpc.server
 
-.. ``urllib`` currently requires an explicit import because the name clashes with
-.. that on Python 2 and because Python's syntax does not allow imports of this
-.. form with a dotted module name after ``as``::
-..
-..     import future.moves.urllib.parse as urllib.parse
-..
-.. For submodules of ``urllib`` and other packages (like ``http``), this
-.. alternative form is available::
-..
-..     from future.standard_library import import_
-..
-..     urllib = import_('urllib')
-..     import_('urllib.parse')
-..     import_('urllib.request')
-..     import_('urllib.error')
-..
-..     response = urllib.request.urlopen('http://mywebsite.com')
-..     # etc.
-..
-.. For an explanation of these and other forms of imports from the standard
-.. library, see :ref:`standard-library-imports`.
-
 
 .. _py2-dependencies:
 

docs/whatsnew.rst

@@ -10,8 +10,8 @@ The major new feature in this version is improvements in the support for the
 reorganized standard library (PEP 3108) and compatibility of the import
 mechanism with 3rd-party modules.
 
-Standard-library import hooks now require explicit installation
----------------------------------------------------------------
+More robust standard-library import hooks
+-----------------------------------------
 
 **Note: backwards-incompatible change:** As previously announced (see
 :ref:`deprecated-auto-import-hooks`), the import hooks must now be enabled
@@ -40,7 +40,7 @@ backwards compatibility::
     ...
     standard_library.remove_hooks()
 
-Requiring explicit installation of import hooks allows finer-grained control
+Explicit installation of import hooks allows finer-grained control
 over whether they are enabled for other imported modules that provide their own
 Python 2/3 compatibility layer. This also improves compatibility of ``future``
 with tools like ``py2exe``.
@@ -49,11 +49,12 @@ with tools like ``py2exe``.
 ``newobject`` base object defines fallback Py2-compatible special methods
 -------------------------------------------------------------------------
 
-There is a new ``future.builtins.object`` base class that can streamline Py3/2
-compatible code by providing fallback Py2-compatible special methods for its
-subclasses. It currently provides ``next()`` and ``__nonzero__()`` as fallback
-methods on Py2 when its subclasses define the corresponding Py3-style
-``__next__()`` and ``__bool__()`` methods.
+There is a new ``future.types.newobject`` base class (available as
+``future.builtins.object``) that can streamline Py3/2 compatible code by
+providing fallback Py2-compatible special methods for its subclasses. It
+currently provides ``next()`` and ``__nonzero__()`` as fallback methods on Py2
+when its subclasses define the corresponding Py3-style ``__next__()`` and
+``__bool__()`` methods.
 
 This obviates the need to add certain compatibility hacks or decorators to the
 code such as the ``@implements_iterator`` decorator for classes that define a
@@ -75,15 +76,15 @@ to ``__next__``::
 
     assert list(Upper('hello')) == list('HELLO')
 
-``future.builtins.object`` defines other Py2-compatible special methods similarly:
+``newobject`` defines other Py2-compatible special methods similarly:
 currently these include ``__nonzero__`` (mapped to ``__bool__``) and
 ``__long__`` (mapped to ``__int__``).
 
 Inheriting from ``newobject`` on Python 2 is safe even if your class defines
 its own Python 2-style ``__nonzero__`` and ``next`` and ``__long__`` methods.
 Your custom methods will simply override those on the base class.
 
-On Python 3, as usual, ``object`` simply refers to ``builtins.object``.
+On Python 3, as usual, ``future.builtins.object`` simply refers to ``builtins.object``.
 
 
 ``past.builtins`` module improved