Docs: improve organization

Consolidate several smaller sections into larger ones

Author: edschofield

docs/automatic_conversion.rst

@@ -22,6 +22,8 @@ mostly unchanged on both Python 2 and Python 3.
 
 .. include:: futurize.rst
 
+.. include:: futurize_cheatsheet.rst
+
 .. include:: pasteurize.rst
 
 .. include:: conversion_limitations.rst

docs/contents.rst.inc

@@ -9,13 +9,11 @@ Contents:
    quickstart
    compatible_idioms
    imports
-   standard_library_imports
    what_else
    automatic_conversion
-   futurize_cheatsheet
-   translation
-   stdlib_incompatibilities
    faq
+   stdlib_incompatibilities
+   older_interfaces
    changelog
    credits
    reference

docs/conversion_limitations.rst

@@ -1,26 +1,19 @@
-How well do ``futurize`` and ``pasteurize`` work?
--------------------------------------------------
+.. _futurize-limitations:
 
-They are still incomplete and make some mistakes, like 2to3, on which they are
-based.
+Known limitations
+-----------------
 
-Nevertheless, ``futurize`` and ``pasteurize`` are useful to automate much of the
+``futurize`` and ``pasteurize`` are useful to automate much of the
 work of porting, particularly the boring repetitive text substitutions. They also
 help to flag which parts of the code require attention.
 
-Please report bugs on `GitHub
-<https://github.com/PythonCharmers/python-future/>`_.
-
-Contributions to the ``lib2to3``-based fixers for ``futurize`` and
-``pasteurize`` are particularly welcome! Please see :ref:`contributing`.
-
-
-.. _futurize-limitations:
-
-Known limitations
------------------
+Nevertheless, ``futurize`` and ``pasteurize`` are still incomplete and make
+some mistakes, like 2to3, on which they are based. Please report bugs on
+`GitHub <https://github.com/PythonCharmers/python-future/>`_. Contributions to
+the ``lib2to3``-based fixers for ``futurize`` and ``pasteurize`` are
+particularly welcome! Please see :ref:`contributing`.
 
-``futurize`` doesn't currently make this change automatically:
+``futurize`` doesn't currently make the following change automatically:
 
 1. Strings containing ``\U`` produce a ``SyntaxError`` on Python 3. An example is::
 

docs/futurize_cheatsheet.rst

@@ -1,15 +1,14 @@
 .. _futurize_cheatsheet:
 
-``futurize`` quick-start: automatic conversion from Py2 to Py2/3
-================================================================
+``futurize`` quick-start guide
+------------------------------
 
-Instructions and notes on converting code from supporting only Python 2 to
-supporting both Python 3 and 2 with a single codebase using ``futurize``:
+How to convert Py2 code to Py2/3 code using ``futurize``:
 
 .. _porting-setup:
 
 Step 0: setup
--------------
+~~~~~~~~~~~~~
 
 Step 0 goal: set up and see the tests passing on Python 2 and failing on Python 3.
 
@@ -23,7 +22,7 @@ d. Install Python 3.3 with e.g. ``sudo apt-get install python3``. On other platf
 .. _porting-step1:
 
 Step 1: modern Py2 code
------------------------
+~~~~~~~~~~~~~~~~~~~~~~~
 
 The goal for this step is to modernize the Python 2 code without introducing any dependencies (on ``future`` or e.g. ``six``) at this stage.
 
@@ -45,7 +44,7 @@ See :ref:`forwards-conversion-stage1` for more info.
 
 
 Example error
-~~~~~~~~~~~~~
+*************
 
 One relatively common error after conversion is::
 
@@ -71,7 +70,7 @@ imports.)
 .. _porting-step2:
 
 Step 2: working Py3 code that still supports Py2
-------------------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The goal for this step is to get the tests passing first on Py3 and then on Py2
 again with the help of the ``future`` package.

docs/imports.rst

@@ -60,17 +60,12 @@ certain automated code-analysis tools.
 
 The complete set of imports of builtins from ``future`` is::
     
-    from future.builtins import (ascii, bytes, chr, dict, filter, hex, input,
-                                 int, map, next, oct, open, pow, range, round,
-                                 str, super, zip)
-
-The contents of the ``future.builtins`` module are also accessible under the
-``builtins`` namespace as follows::
-
     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
@@ -84,12 +79,12 @@ 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, round, super)
+                                      oct, open, pow, round, super)
     from future.builtins.iterators import filter, map, zip
 
-To understand the details of the backported builtins on Python 2, see the
-docs for these modules. Please note that this internal API is evolving and may
-not be stable between different versions of ``future``.
+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`.
 
@@ -99,7 +94,7 @@ For more information on what the backported types provide, see :ref:`what-else`.
 .. _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
@@ -120,5 +115,12 @@ 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`.

docs/older_interfaces.rst

@@ -0,0 +1,141 @@
+.. _older-standard-library-interfaces:
+
+Older interfaces
+~~~~~~~~~~~~~~~~
+
+In addition to the direct and ``install_aliases()`` interfaces (described in
+:ref:`standard-library-imports`), ``future`` supports four other interfaces to
+the reorganized standard library. This is largely for historical reasons (for
+versions prior to 0.14).
+
+
+Context-manager for import hooks
+________________________________
+
+The context-manager interface is via a context-manager called ``hooks``::
+
+    from future.standard_library import hooks
+    with hooks():
+        import socketserver
+        import queue
+        import configparser
+        import test.support
+        import html.parser
+        from collections import UserList
+        from itertools import filterfalse, zip_longest
+        from http.client import HttpConnection
+        import urllib.request
+        # and other moved modules and definitions
+
+This interface is straightforward and effective, using PEP 302 import
+hooks.
+
+
+``future.moves`` interface
+__________________________
+
+The ``future.moves`` interface avoids import hooks. It may therefore be more
+robust, at the cost of less idiomatic code. Use it as follows::
+
+    from future.moves import queue
+    from future.moves import socketserver
+    from future.moves.http.client import HTTPConnection
+    # etc.
+
+If you wish to achieve the effect of a two-level import such as this::
+
+    import http.client 
+
+portably on both Python 2 and Python 3, note that Python currently does not
+support syntax like this::
+
+    from future.moves import http.client
+
+One workaround is to replace the dot with an underscore::
+
+    import future.moves.http.client as http_client
+
+
+Comparing future.moves and six.moves
+++++++++++++++++++++++++++++++++++++
+
+``future.moves`` and ``six.moves`` provide a similar Python 3-style
+interface to the native standard library module definitions.
+
+The major difference is that the ``future.moves`` package is a real Python package
+(``future/moves/__init__.py``) with real modules provided as ``.py`` files, whereas
+``six.moves`` constructs fake ``_LazyModule`` module objects within the Python
+code and injects them into the ``sys.modules`` cache.
+
+The advantage of ``six.moves`` is that the code fits in a single module that can be
+copied into a project that seeks to eliminate external dependencies.
+
+The advantage of ``future.moves`` is that it is likely to be more robust in the
+face of magic like Django's auto-reloader and tools like ``py2exe`` and
+``cx_freeze``. See issues #51, #53, #56, and #63 in the ``six`` project for
+more detail of bugs related to the ``six.moves`` approach.
+
+
+``import_`` and ``from_import`` functions
+_________________________________________
+
+The functional interface is to use the ``import_`` and ``from_import``
+functions from ``future.standard_library`` as follows::
+
+    from future.standard_library import import_, from_import
+    
+    http = import_('http.client')
+    urllib = import_('urllib.request')
+
+    urlopen, urlsplit = from_import('urllib.request', 'urlopen', 'urlsplit')
+
+This interface also works with two-level imports.
+
+
+install_hooks() call
+____________________
+
+The last interface to the reorganized standard library is via a call to
+``install_hooks()``::
+
+    from future import standard_library
+    standard_library.install_hooks()
+
+    import urllib
+    f = urllib.request.urlopen('http://www.python.org/')
+
+    standard_library.remove_hooks()
+
+If you use this interface, it is recommended to disable the import hooks again
+after use by calling ``remove_hooks()``, in order to prevent the futurized
+modules from being invoked inadvertently by other modules. (Python does not
+automatically disable import hooks at the end of a module, but keeps them
+active for the life of a process unless removed.)
+
+.. 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.moves`` or ``future.backports`` modules unintentionally.
+.. Code such as this will then fall through to using the Py2 standard library
+.. modules on Py2::
+.. 
+..     try:
+..         from http.client import HTTPConnection
+..     except ImportError:
+..         from httplib import HTTPConnection
+.. 
+.. **Requests**: The above snippet is from the `requests
+.. <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
+.. ``http_client`` in your code, an alternative is this::
+.. 
+..     from future.standard_library import http
+..     from future.standard_library.http import client as _client
+..     http.client = client
+
+.. but it has the advantage that it can be used by automatic translation scripts such as ``futurize`` and ``pasteurize``.
+
+

docs/quickstart.rst

@@ -123,7 +123,7 @@ to be accessed under their Python 3 names and locations in Python 2::
     import xmlrpc.client
     import xmlrpc.server
 
-and others. For a complete list, see :ref:`list-standard-library-renamed`.
+and others. For a complete list, see :ref:`direct-imports`.
 
 .. _py2-dependencies: