Add note discouraging selective imports from future.builtins

edschofield · edschofield · commit 0193ca5a4837 · 2013-10-02T11:34:13.000+10:00
diff --git a/docs/source/imports.rst b/docs/source/imports.rst
@@ -45,6 +45,7 @@ These are all available in Python 2.6 and up, and mandatory in Python 3+.
 
 Explicit imports
 ~~~~~~~~~~~~~~~~
+
 If you prefer explicit imports, the explicit equivalent of the ``from
 future.builtins import *`` line is::
 
@@ -53,7 +54,10 @@ future.builtins import *`` line is::
                                  str, bytes, range, round, super,
                                  apply, cmp, coerce, execfile, file, long,
                                  raw_input, reduce, reload, unicode, xrange,
-                                 str, StandardError)
+                                 StandardError)
+
+However, we discourage importing only some of these builtins because this
+increases the risk of introducing Py2/3 portability bugs into your code.
 
 To understand what each of these does, see the docs for these modules:
 
@@ -65,13 +69,13 @@ To understand what each of these does, see the docs for these modules:
 
 The internal API is currently as follows::
 
-    from future.builtins.iterators import zip, map, filter
-    from future.builtins.misc import ascii, oct, hex, chr, int, input, open
-    from future.builtins.backports import str, bytes, range, round, super
+    from future.builtins.iterators import filter, map, zip
+    from future.builtins.misc import ascii, chr, hex, input, int, oct, open
+    from future.builtins.backports import bytes, range, round, str, super
     from future.builtins.disabled import (apply, cmp, coerce,
             execfile, file, long, raw_input, reduce, reload, unicode,
             xrange, StandardError)
 
-But please note that this internal API may not be stable between
-different versions of ``future``.
+But please note that this internal API is evolving and may not be stable
+between different versions of ``future``.
 
