Doc updates and tweaks

Author: edschofield

docs/faq.rst

@@ -118,22 +118,27 @@ Maturity
 Is it tested?
 -------------
 
-``future`` is used by ``mezzanine`` and ``ObsPy``. It has also been used to
-help with the port of 800,000 lines of Python 2 code in Sage to Python 2/3
-(currently underway).
+``future`` is used by several major projects, including `mezzanine
+<http://mezzanine.jupo.org>`_ and `ObsPy <http://www.obspy.org>`_. It is also
+currently being used to help with porting 800,000 lines of Python 2 code in
+`Sage <http://sagemath.org>`_ to Python 2/3.
 
 Currently ``future`` has 800+ unit tests. Many of these are straight from the
-Python 3.3 test suite. In general, the ``future`` package itself is in good
-shape, whereas the ``futurize`` script for automatic porting is incomplete and
-imperfect.  (Chances are it will require some manual cleanup afterwards.) The
-``past`` package also needs further work.
-    
+Python 3.3 test suite.
+
+In general, the ``future`` package itself is in good shape, whereas the
+``futurize`` script for automatic porting is incomplete and imperfect.
+(Chances are it will require some manual cleanup afterwards.) The ``past``
+package also needs further work.
+
+
 Is the API stable?
 ------------------
 
-Not yet; ``future`` is still in beta. We will try not to break anything which
-was documented and used to work.  After version 1.0 is released, the API will
-not change in backward-incompatible ways until a hypothetical version 2.0.
+Not yet; ``future`` is still in beta. Where possible, we will try not to break
+anything which was documented and used to work.  After version 1.0 is released,
+the API will not change in backward-incompatible ways until a hypothetical
+version 2.0.
 
 ..
     Are there any example of Python 2 packages ported to Python 3 using ``future`` and ``futurize``?

docs/standard_library_imports.rst

@@ -6,7 +6,7 @@ Standard library imports
 :mod:`future` supports the standard library reorganization (PEP 3108). Under
 the standard Python 3 names and locations, it provides access to either the
 corresponding native standard library modules (``future.moves``) or to backported
-modules from Python 3.3 (``future.standard_library``).
+modules from Python 3.3 (``future.backports``).
 
 There are currently four interfaces to the reorganized standard library.
 
@@ -70,7 +70,7 @@ follows::
 install_hooks() call
 ------------------------
 
-The fourth (deprecated) interface to the reorganized standard library is via an
+The fourth interface to the reorganized standard library is via an
 explicit call to ``install_hooks``::
 
     from future import standard_library
@@ -91,8 +91,8 @@ active indefinitely.)
 The call to ``scrub_future_sys_modules()`` removes any modules from the
 ``sys.modules`` cache (on Py2 only) that have Py3-style names, like ``http.client``.
 This can prevent libraries that have their own Py2/3 compatibility code from
-importing the ``future.standard_library`` modules unintentionally. Code such as
-this will then fall through to using the Py2 standard library
+importing the ``future.moves`` or ``future.backports`` modules unintentionally.
+Code such as this will then fall through to using the Py2 standard library
 modules on Py2::
 
     try:
@@ -101,12 +101,8 @@ modules on Py2::
         from httplib import HTTPConnection
 
 **Requests**: The above snippet is from the `requests
-<http://docs.python-requests.org>`_ library. Note that ``requests``  is
-currently incompatible with the import hooks in ``future.standard_library``. To
-use both of these together, you must call ``remove_hooks()`` and
-``scrub_future_sys_modules()`` as above before you (or users of your library)
-import ``requests``. The easiest way to do this is with the ``hooks`` context
-manager or one of the other import mechanisms (see above).
+<http://docs.python-requests.org>`_ library. As of v0.12, the
+``future.standard_library`` import hooks are compatible with Requests.
 
 
 .. If you wish to avoid changing every reference of ``http.client`` to
@@ -154,9 +150,11 @@ Backports
 ---------
 
 Backports of the following modules from Python 3.3's standard library to Python 2.x are also
-available in ``future.standard_library``::
+available in ``future.backports``::
 
+    http.client
     http.server
+    html.server
     urllib
     xmlrpc.client
     xmlrpc.server

docs/whatsnew.rst

@@ -14,7 +14,7 @@ mechanism with 3rd-party modules.
 Standard-library import hooks now require explicit installation
 ---------------------------------------------------------------
 
-*Note: backwards-incompatible change:* As previously announced (see
+**Note: backwards-incompatible change:** As previously announced (see
 :ref:`deprecated-auto-import-hooks`), the import hooks must now be enabled
 explicitly, as follows::
 
@@ -26,10 +26,12 @@ explicitly, as follows::
 
 This now causes these modules to be imported from ``future.moves``, a new
 package that provides wrappers over the native Python 2 standard library with
-the new Python 3 organization.
+the new Python 3 organization. As a consequence, the import hooks provided in
+``future.standard_library`` are now fully compatible with the `Requests library
+<http://python-requests.org>`_.
 
-The functional interface is now deprecated but still supported for backwards
-compatibility::
+The functional interface with ``install_hooks()`` is still supported for
+backwards compatibility::
 
     from future import standard_library
     standard_library.install_hooks():
@@ -39,49 +41,10 @@ compatibility::
     ...
     standard_library.remove_hooks()
 
-This allows finer-grained control over whether import hooks are enabled for
-other imported modules, such as ``requests``, which provide their own Python
-2/3 compatibility code. This also improves compatibility of ``future`` with
-tools like ``py2exe``.
-
-
-.. Versioned standard library imports
-.. ----------------------------------
-.. 
-.. ``future`` now offers a choice of either backported versions of the standard library modules from Python 3.3 or renamed Python 2.7 versions. Use it as follows::
-.. 
-..     from future import standard_library
-..     standard_library.install_hooks(version='3.3')
-..     import html.parser
-..     ...
-..     standard_library.remove_hooks()
-.. 
-.. or as follows::
-..     
-..     from future import standard_library
-..     with standard_library.hooks(version='2.7'):
-..         import html.parser
-..         ...
-.. 
-.. If ``version='2.7'`` is selected, on Python 2.7 the import hooks provide an interface to the
-.. Python 2.7 standard library modules remapped to their equivalent Python 3.x names. For example, the above code is equivalent to this on Python 2.7 (more or less)::
-.. 
-..     import htmllib
-..     module = type(htmllib)
-..     html = module('html')
-..     html.parser = module('html.parser')
-..     html.parser.HTMLParser = htmllib.HTMLParser
-..     html.parser.HTMLParseError = htmllib.htmlParseError
-.. 
-.. but the dozen or so other functions in Python 3.3's ``html.parser`` module are not available on Python 2.7.
-.. 
-.. 
-.. If ``version=='3.3'`` is selected, 
-.. 
-.. These are not (yet) full backports of
-.. the Python 3.3
-.. modules but remappings to the corresponding
-.. functionality in the Python 2.x standard library.
+Requiring 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``.
 
 
 ``newobject`` base object defines fallback Py2-compatible special methods
@@ -134,7 +97,7 @@ functions like ``map()`` and ``filter()`` now behave as they do on Py2 with with
 
 The ``past.builtins`` module has also been extended to add Py3 support for
 additional Py2 constructs that are not adequately handled by ``lib2to3`` (see
-issue #37). This includes custom ``execfile()`` and ``cmp()`` functions.
+issue #37). This includes new ``execfile()`` and ``cmp()`` functions.
 ``futurize`` now invokes imports of these functions from ``past.builtins``.
 
 
@@ -454,21 +417,18 @@ Please remember to import ``input`` from ``future.builtins`` if you use
 ``input()`` in a Python 2/3 compatible codebase.
 
 
-.. deprecated-auto-import-hooks
+.. deprecated-auto-import-hooks:
 
 Deprecated feature: auto-installation of standard-library import hooks
 ----------------------------------------------------------------------
 
 Previous versions of ``python-future`` installed import hooks automatically upon
-``from future import standard_library``. This has been deprecated in order to
-improve robustness and compatibility with modules like ``requests`` that already
-perform their own single-source Python 2/3 compatibility.
+importing the ``standard_library`` module from ``future``. This has been
+deprecated in order to improve robustness and compatibility with modules like
+``requests`` that already perform their own single-source Python 2/3
+compatibility.
 
-.. (Previously, the import hooks were
-.. bleeding into surrounding code, causing incompatibilities with modules like
-.. ``requests`` (issue #19). 
-
-In the next version of ``python-future``, importing ``future.standard_library``
+As of v0.12 of ``python-future``, importing ``future.standard_library``
 will no longer install import hooks by default. Instead, please install the
 import hooks explicitly as follows::
     
@@ -479,16 +439,8 @@ and uninstall them after your import statements using::
 
     standard_library.remove_hooks()
 
-..  For more fine-grained use of import hooks, the names can be passed explicitly as
-..  follows::
-.. 
-..      from future import standard_library
-..      standard_library.install_hooks()
-
-
 *Note*: this will be a backward-incompatible change.
 
-.. This feature may be resurrected in a later version if a safe implementation can be found.
 
 
 Internal changes