Doc tweaks

Author: edschofield

docs/int_object.rst

@@ -20,10 +20,10 @@ Python 2::
 
 ``future`` includes a backport of Python 3's ``int`` that
 is a subclass of Python 2's ``long`` with the same representation
-behaviour as Python 3's ``int``. To ensure an integer is long compatibly both
-Py3 and Py2, cast it like this::
+behaviour as Python 3's ``int``. To ensure an integer is long compatibly with
+both Py3 and Py2, cast it like this::
 
-    >>> from future.builtins import *
+    >>> from future.builtins import int
     >>> must_be_a_long_integer = int(1234)
 
 The backported ``int`` object helps with writing doctests and simplifies code

docs/isinstance.rst

@@ -40,7 +40,7 @@ After importing the builtins from ``future``, all these tests pass on
 Python 2 as on Python 3::
 
     >>> from __future__ import unicode_literals
-    >>> from future.builtins import *
+    >>> from future.builtins import bytes, int, str
 
     >>> assert isinstance(10, int)
     >>> assert isinstance(10**100, int)

docs/open_function.rst

@@ -8,19 +8,19 @@ contents as (unicode) strings unless the binary (``b``) flag is passed, as in::
     
     open(filename, 'rb')
 
-in which case it returns a Py3 :class:`bytes` object.
-
-``future.builtins`` provides a compatible ``open`` function on Py2,
-which uses the ``open`` backport available in the standard library :mod:`io`
-module on Py2.6+.
-
-When porting code from Python 2, be aware of the different return types from
-methods such as :func:`read()` from the file object that ``open`` returns.
-
-Note that the output of :func:`read()` etc. is not automatically cast to the
-appropriate ``future.builtins.bytes`` or ``future.builtins.str`` type. If you
-need the stricter type-checking of Py3 on Py2 as well, you can cast it
-explicitly as follows::
+in which case its methods like :func:`read` return Py3 :class:`bytes` objects.
+
+``future.builtins`` provides an ``open`` function on Py2 that is mostly
+compatible with that on Python 3 (e.g. it offers keyword arguments like
+``encoding``). This maps to the ``open`` backport available in the standard
+library :mod:`io` module on Py2.6 and Py2.7.
+
+One difference to be aware of between the Python 3 ``open`` and
+``future.builtins.open`` on Python 2 is that the return types of methods such
+as :func:`read()` from the file object that ``open`` returns are not
+automatically cast to the appropriate ``future.builtins.bytes`` or
+``future.builtins.str`` types. If you need the returned data to behave the same
+way on Py2 as on Py3, you can cast it explicitly as follows::
 
     from __future__ import unicode_literals
     from future.builtins import *

docs/str_object.rst

@@ -44,8 +44,8 @@ Then, for example, the following code has the same effect on Py2 as on Py3::
     TypeError: argument can't be <type 'str'>
 
 Various other operations that mix strings and bytes or other types are
-permitted on Py2 with the :class:`newstr`` class even though they are
-illegal with Python 3. For example::
+permitted on Py2 with the :class:`future.builtins.str` class even though they
+are illegal with Python 3. For example::
 
     >>> s2 = b'/' + str('ABCD')
     >>> s2
@@ -71,8 +71,8 @@ they are unicode. (See ``posixpath.py``.) Another example is the
 .. 
 .. On Py3, these raise TypeErrors.
 
-In most other ways, these :class:`str` objects on Py2 have the same
-behaviours as Python 3's :class:`str`::
+In most other ways, these :class:`future.builtins.str` objects on Py2 have the
+same behaviours as Python 3's :class:`str`::
 
     >>> s = str('ABCD')
     >>> assert repr(s) == 'ABCD'      # consistent repr with Py3 (no u prefix)