Docs (mostly): Update references to future.builtins -> builtins

Author: edschofield

.gitignore

@@ -22,6 +22,10 @@ develop-eggs
 lib
 lib64
 
+# Backup files
+*.bak
+*.backup
+
 # Installer logs
 pip-log.txt
 

README.rst

@@ -25,15 +25,13 @@ Features
 .. image:: https://travis-ci.org/PythonCharmers/python-future.svg?branch=master
        :target: https://travis-ci.org/PythonCharmers/python-future
 
--   ``future.builtins`` package provides backports and remappings for 20
-    builtins with different semantics on Py3 versus Py2
+-   ``future.builtins`` package (also available as ``builtins`` on Py2) provides
+    backports and remappings for 20 builtins with different semantics on Py3
+    versus Py2
 
 -   ``future.standard_library``, in conjunction with ``future.moves``, provides
     support for importing standard library modules under their Python 3 names
 
--   ``future.backports`` package provides backports from the Py3.3
-    standard library
-
 -   ``past.builtins`` package provides forward-ports of 19 Python 2 types and
     builtin functions. These can aid with per-module code migrations.
 
@@ -65,8 +63,8 @@ these imports as it does on Python 3.3+:
 .. code-block:: python
     
     from __future__ import absolute_import, division, print_function
-    from future.builtins import (bytes, str, open, super, range,
-                                 zip, round, input, int, pow, object)
+    from builtins import (bytes, str, open, super, range,
+                          zip, round, input, int, pow, object)
 
     # Backported Py3 bytes object
     b = bytes(b'ABCD')
@@ -120,7 +118,7 @@ these imports as it does on Python 3.3+:
     assert isinstance('blah', str)       # only if unicode_literals is in effect
 
     # Py3-style iterators written as new-style classes (subclasses of
-    # future.builtins.object) are automatically backward compatible with Py2:
+    # future.types.newobject) are automatically backward compatible with Py2:
     class Upper(object):
         def __init__(self, iterable):
             self._iter = iter(iterable)
@@ -131,19 +129,25 @@ these imports as it does on Python 3.3+:
     assert list(Upper('hello')) == list('HELLO')
 
 
-There is also support for renamed standard library modules in the form of import
-hooks. The context-manager form works like this:
+There is also support for renamed standard library modules. The recommended
+interface works like this:
 
 .. code-block:: python
 
+    # Many Py3 module names are supported directly on both Py2.x and 3.x:
+    from http.client import HttpConnection
+    import html.parser
+    import queue
+    import xmlrpc.client
+
+    # Refactored modules with clashing names on Py2 and Py3 are supported
+    # as follows:
     from future import standard_library
+    standard_library.install_aliases()
 
-    with standard_library.hooks():
-        from http.client import HttpConnection
-        from itertools import filterfalse
-        import html.parser
-        import queue
-        from urllib.request import urlopen
+    # Then, as usual:
+    from itertools import filterfalse
+    from urllib.request import urlopen
 
 
 Automatic conversion to Py2/3-compatible code
@@ -190,9 +194,9 @@ 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()
+    standard_library.install_aliases()
+    from builtins import input
     import queue
     from urllib.request import urlopen
     

docs/bytes_object.rst

@@ -11,10 +11,10 @@ Python 2's :class:`str`, rather than a true implementation of the Python
 
 :mod:`future` contains a backport of the :mod:`bytes` object from Python 3
 which passes most of the Python 3 tests for :mod:`bytes`. (See
-``future/tests/test_bytes.py`` in the source tree.) You can use it as
+``tests/test_future/test_bytes.py`` in the source tree.) You can use it as
 follows::
 
-    >>> from future.builtins import bytes
+    >>> from builtins import bytes
     >>> b = bytes(b'ABCD')
 
 On Py3, this is simply the builtin :class:`bytes` object. On Py2, this
@@ -53,7 +53,7 @@ Currently the easiest way to ensure identical behaviour of byte-strings
 in a Py2/3 codebase is to wrap all byte-string literals ``b'...'`` in a
 :func:`~bytes` call as follows::
     
-    from future.builtins import bytes
+    from builtins import bytes
     
     # ...
 

docs/custom_iterators.rst

@@ -8,12 +8,12 @@ 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`` and define a ``__next__`` method as you normally
+``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
+    from builtins import object
     
     class Upper(object):
         def __init__(self, iterable):
@@ -31,10 +31,10 @@ method that calls your ``__next__``. Use it as follows::
 
 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
+``newobject``.  In that case, you can provide compatibility across
 Python 2 and Python 3 using the ``next`` function from ``future.builtins``::
 
-    from future.builtins import next
+    from builtins import next
 
     from some_module import some_base_class
 

docs/dev_notes.rst

@@ -0,0 +1,23 @@
+Notes
+-----
+This module only supports Python 2.6, Python 2.7, and Python 3.1+.
+
+The following renames are already supported on Python 2.7 without any
+additional work from us::
+
+    reload() -> imp.reload()
+    reduce() -> functools.reduce()
+    StringIO.StringIO -> io.StringIO
+    Bytes.BytesIO -> io.BytesIO
+
+Old things that can one day be fixed automatically by futurize.py::
+
+  string.uppercase -> string.ascii_uppercase   # works on either Py2.7 or Py3+
+  sys.maxint -> sys.maxsize      # but this isn't identical
+
+TODO: Check out these:
+Not available on Py2.6:
+  unittest2 -> unittest?
+  buffer -> memoryview?
+
+

docs/development.rst

@@ -0,0 +1,22 @@
+.. developer-docs
+
+Developer docs
+==============
+
+The easiest way to start developing ``python-future`` is as follows:
+
+1. Install Anaconda Python distribution
+
+2. Run::
+
+    conda install -n future2 python=2.7 pip
+    conda install -n future3 python=3.3 pip
+    
+    git clone https://github.com/PythonCharmers/python-future 
+
+3. If you are using Anaconda Python distribution, this comes without a ``test``
+module on Python 2.x. Copy ``Python-2.7.6/Lib/test`` from the Python source tree
+to ``~/anaconda/envs/yourenvname/lib/python2.7/site-packages/`.
+
+
+

docs/dict_object.rst

@@ -25,14 +25,15 @@ stick with standard Python 3 code in your Py2/3 compatible codebase::
 In this case there will be memory overhead of list creation for each call to
 ``items``, ``values`` or ``keys``.
 
-For improved efficiency, ``future.builtins`` provides a Python 2 ``dict``
-subclass whose :func:`keys`, :func:`values`, and :func:`items` methods return
-iterators on all versions of Python >= 2.6. On Python 2.7, these iterators also
-have the same set-like view behaviour as dictionaries in Python 3. This can
-streamline code that iterates over large dictionaries. For example::
+For improved efficiency, ``future.builtins`` (aliased to ``builtins``) provides
+a Python 2 ``dict`` subclass whose :func:`keys`, :func:`values`, and
+:func:`items` methods return iterators on all versions of Python >= 2.6. On
+Python 2.7, these iterators also have the same set-like view behaviour as
+dictionaries in Python 3. This can streamline code that iterates over large
+dictionaries. For example::
 
     from __future__ import print_function
-    from future.builtins import dict, range
+    from builtins import dict, range
     
     # Memory-efficient construction:
     d = dict((i, i**2) for i in range(10**7))
@@ -46,16 +47,16 @@ streamline code that iterates over large dictionaries. For example::
 On Python 2.6, these methods currently return iterators but do not support the
 new Py3 set-like behaviour.
 
-As usual, on Python 3 ``future.builtins.dict`` is just the built-in ``dict``
-class.
+As usual, on Python 3 ``dict`` imported from either ``builtins`` or
+``future.builtins`` is just the built-in ``dict`` class.
 
 
 Memory-efficiency and alternatives
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 If you already have large native dictionaries, the downside to wrapping them in
-a ``dict`` call is that memory is copied (on both Py3 and with
-``future.builtins.dict``). For example::
+a ``dict`` call is that memory is copied (on both Py3 and on Py2). For
+example::
 
     # This allocates and then frees a large amount of temporary memory:
     d = dict({i: i**2 for i in range(10**7)})
@@ -72,7 +73,7 @@ The memory-efficient (and CPU-efficient) alternatives are:
       d = dict((i, i**2) for i in range(10**7)
 
 - to construct an empty dictionary with a ``dict()`` call using
-  ``future.builtins.dict`` (rather than ``{}``) and then update it;
+  ``builtins.dict`` (rather than ``{}``) and then update it;
 
 - to use the ``viewitems`` etc. functions from :mod:`future.utils`, passing in
   regular dictionaries::

docs/future-builtins.rst

@@ -3,14 +3,16 @@
 ``future.builtins``
 ===================
 
+The ``future.builtins`` module is also accessible as ``builtins`` on Py2.
+
 - ``pow()`` supports fractional exponents of negative numbers like in Py3::
 
-    >>> from future.builtins import pow
+    >>> from builtins import pow
     >>> pow(-1, 0.5)
     (6.123233995736766e-17+1j)
 
 - ``round()`` uses Banker's Rounding as in Py3 to the nearest even last digit::
 
-    >>> from future.builtins import round
+    >>> from builtins import round
     >>> assert round(0.1250, 2) == 0.12
 

docs/futurize.rst

@@ -192,8 +192,8 @@ For example::
 
 would be converted by Stage 2 to this code::
 
-    from future.builtins import input
-    from future.builtins import str
+    from builtins import input
+    from builtins import str
     from future.utils import iteritems, python_2_unicode_compatible
 
     name = input('What is your name?\n')
@@ -290,7 +290,7 @@ that these types behave similarly on Python 2 as on Python 3, also wrap
 byte-strings or text in the ``bytes`` and ``str`` types from ``future``. For
 example::
 
-    from future.builtins import bytes, str
+    from builtins import bytes, str
     b = bytes(b'\x00ABCD')
     s = str(u'This is normal text')
 

docs/futurize_cheatsheet.rst

@@ -88,12 +88,15 @@ changes to all Python source files recursively with::
 To apply the changes, add the ``-w`` argument.
 
 This stage makes further conversions needed to support both Python 2 and 3.
-These will likely require imports from ``future``, such as::
+These will likely require imports from ``future`` on Py2 (and sometimes on Py3),
+such as::
 
     from future import standard_library
-    standard_library.install_hooks()
-    from future.builtins import bytes
-    from future.builtins import open
+    standard_library.install_aliases()
+    # ...
+    from builtins import bytes
+    from builtins import open
+    from future.utils import with_metaclass
 
 Optionally, you can use the ``--unicode-literals`` flag to add this import to
 the top of each module::