8000 More doc updates · shawnp/python-future@c7694cd · GitHub
[go: up one dir, main page]
Skip to content 8000

Commit c7694cd

Browse files
edschofieldedschofield
committed
More doc updates
1 parent 4d7862e commit c7694cd

File tree

8 files changed

+38
-37
lines changed

8 files changed

+38
-37
lines changed

‎docs/source/bytes_object.rst

Lines changed: 6 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -14,14 +14,14 @@ which passes most of the Python 3 tests for :mod:`bytes`. (See
1414
``future/tests/test_bytes.py`` in the source tree.) You can use it as
1515
follows::
1616

17-
from future.builtins import bytes
17+
>>> from future.builtins import bytes
1818
19-
b = bytes(b'ABCD')
19+
>>> b = bytes(b'ABCD')
2020

2121
On Py3, this is simply the builtin :class:`bytes` object. On Py2, this
22-
object inherits from Python 2's :class:`str`, but it enforces the same
23-
strict strict separation of unicode strings and byte strings as Python
24-
3's :class:`bytes` object::
22+
object is a subclass of Python 2's :class:`str` that enforces the same
23+
strict separation of unicode strings and byte strings as Python 3's
24+
:class:`bytes` object::
2525

2626
>>> b + u'EFGH' # TypeError
2727
Traceback (most recent call last):
@@ -45,9 +45,6 @@ Py2::
4545

4646
On Py3, these raise TypeErrors.
4747

48-
In most other ways, these :class:`str` objects on Py2 have the same
49-
behaviours as Python 3's :class:`str`::
50-
5148
In most other ways, these :class:`bytes` objects have identical
5249
behaviours to Python 3's :class:`bytes`::
5350

@@ -56,7 +53,7 @@ behaviours to Python 3's :class:`bytes`::
5653
assert repr(b) == "b'ABCD'"
5754
assert b.split(b'b') == [b'A', b'CD']
5855

59-
Currently the easiest way to ensure identical use of byte-strings
56+
Currently the easiest way to ensure identical behaviour of byte-strings
6057
in a Py3/2 codebase is to wrap all byte-string literals ``b'...'`` in a
6158
:func:`~bytes` call, as follows::
6259

‎docs/source/dict_methods.rst

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,3 +35,5 @@ etc. functions from :mod:`future.utils`::
3535
# Set union:
3636
both = viewvalues(d1) | viewvalues(d2)
3737

38+
For Python 2.6 compatibility, the functions ``iteritems`` etc. are also
39+
available in :mod:`future.utils`.

‎docs/source/imports.rst

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -50,9 +50,10 @@ If you prefer explicit imports, the explicit equivalent of the ``from
5050
future.builtins import *`` line is::
5151

5252
from future.builtins import (filter, map, zip,
53-
ascii, chr, hex, input, oct, open,
53+
ascii, chr, hex, input, isinstance, oct, open,
5454
bytes, int, range, round, str, super)
5555

56+
5657
However, we discourage importing only some of these builtins because this
5758
increases the risk of introducing Py2/3 portability bugs into your code.
5859

@@ -66,12 +67,13 @@ To understand what each of these does, see the docs for these modules:
6667
The internal API is currently as follows::
6768

6869
from future.builtins.iterators import filter, map, zip
69-
from future.builtins.misc import ascii, chr, hex, input, oct, open
70+
from future.builtins.misc import ascii, chr, hex, input, isinstance, oct, open
7071
from future.builtins.backports import bytes, int, range, round, str, super
7172

7273
But please note that this internal API is evolving and may not be stable
7374
between different versions of ``future``.
7475

76+
7577
.. _obsolete-builtins:
7678

7779
Obsolete Python 2 builtins

‎docs/source/int_object.rst

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -5,8 +5,8 @@ int
55

66
Python 3's ``int`` type is very similar to Python 2's ``long``, except
77
for the representation (which omits the ``L`` suffix in Python 2). Python
8-
2's normal (short) integers have been removed from Python 3, as has the
9-
``long`` builtin.
8+
2's usual (short) integers have been removed from Python 3, as has the
9+
``long`` builtin name.
1010

1111
Python 3::
1212

@@ -18,7 +18,7 @@ Python 2::
1818
>>> 2**64
1919
18446744073709551616L
2020

21-
``future`` includes a backport of Python 3's ``int`` since v0.7.0, which
21+
``future`` includes a backport of Python 3's ``int`` that
2222
is a subclass of Python 2's ``long`` with the same representation
2323
behaviour as Python 3's ``int``. To ensure an integer is long compatibly both
2424
Py3 and Py2, cast it like this::
@@ -31,7 +31,7 @@ that deals with ``long`` and ``int`` as special cases on Py2. An example is the
3131
following code from ``xlwt-future`` (called by the ``xlwt.antlr.BitSet`` class)
3232
for writing out Excel ``.xls`` spreadsheets.
3333

34-
With ``future`` v0.7.0+, the code is::
34+
With ``future``, the code is::
3535

3636
def longify(data):
3737
"""

‎docs/source/isinstance.rst

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ The following tests all pass on Python 3::
1212
>>> assert isinstance('unicode string 2', str)
1313

1414

15-
However, two normally fail on Python 2::
15+
However, two of these normally fail on Python 2::
1616

1717
>>> assert isinstance(2**63, int)
1818
Traceback (most recent call last):
@@ -58,10 +58,10 @@ If you are passing any of the backported types (``bytes``, ``str``,
5858
``int``) into brittle library code that performs type-checks using ``type()``,
5959
rather than ``isinstance()``, or requires that you pass Python 2's native types
6060
(rather than subclasses) for some other reason, it may be necessary to upcast
61-
the types from ``future`` to their native superclasses on Py2. A function
62-
``future.utils.native`` is provided for this.
61+
the types from ``future`` to their native superclasses on Py2.
6362

64-
Here is how to use it. (The output showing is from Py2)::
63+
The ``native`` function in ``future.utils`` is provided for this. Here is how
64+
to use it. (The output showing is from Py2)::
6565

6666
>>> from future.builtins import *
6767
>>> from future.utils import native
@@ -103,12 +103,12 @@ constructor, require native strings on Python 2 and Python 3. This means that
103103
there is no simple way to pass the appropriate string type when the
104104
``unicode_literals`` import from ``__future__`` is in effect.
105105

106-
The objects ``native_str`` and ``native_bytes`` are available in
107-
``future.utils`` for this case. These are equivalent to ``__builtin__.str`` on
108-
Python 2 or ``builtins.str`` on Python 3.
106+
The objects ``native_str`` and ``native_bytes`` are available in
107+
``future.utils`` for this case. These are equivalent to the ``str`` and
108+
``bytes`` objects in ``__builtin__`` on Python 2 or in ``builtins`` on Python 3.
109109

110-
Alternatively, the functions ``native_str_to_bytes`` and
111-
``bytes_to_native_str`` are also available for conversions.
110+
The functions ``native_str_to_bytes`` and ``bytes_to_native_str`` are also
111+
available for more explicit conversions.
112112

113113

114114
.. ``isinstance`` checks are sometimes fragile and generally discouraged in

‎docs/source/quickstart.rst

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ Quick-start guide
44
=================
55

66
The ``future`` module helps run Python 3.x-compatible code under Python
7-
2 with minimal code cruft.
7+
2.6 and 2.7 with minimal code cruft.
88

99
You can use it to help to port your code from Python 2 to Python 3 today
1010
-- and still have it run on Python 2.
@@ -33,17 +33,17 @@ Start each module with these lines::
3333
from future.builtins import *
3434

3535
Then write standard Python 3 code. The :mod:`future` package will
36-
provide support for running your code on Python 2.7 mostly unchanged.
36+
provide support for running your code on Python 2.6 and 2.7 mostly unchanged.
3737

3838
See :ref:`what-else` for more details.
3939

4040

4141
To convert existing Python 3 code
4242
---------------------------------
4343

44-
To offer backward compatibility with Python 2, you can use the ``futurize`` script with a ``--from3`` parameter. This adds
45-
46-
these lines at the top of your Python 3 modules::
44+
To offer backward compatibility with Python 2, you can use the ``futurize``
45+
script with the ``--from3`` parameter. This adds these lines at the top of each
46+
module::
4747

4848
from __future__ import (absolute_import, division,
4949
print_function, unicode_literals)

‎docs/source/str_object.rst

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -6,12 +6,12 @@ str
66
The :class:`str` object in Python 3 is quite similar but not identical to the
77
Python 2 :class:`unicode` object.
88

9-
The major difference is the stricter type-checking with Py3 ``str`` to enforce
10-
the distinction between unicode strings and byte-strings, such as when
9+
The major difference is the stricter type-checking of Py3's ``str`` that
10+
enforces a distinction between unicode strings and byte-strings, such as when
1111
comparing, concatenating, joining, or replacing parts of strings.
1212

13-
There are also minor differences, such as the ``repr`` of unicode strings in
14-
Py2 having a ``"u'...'"`` prefix, versus simply ``"'...'"``, and the removal of
13+
There are also other differences, such as the ``repr`` of unicode strings in
14+
Py2 having a ``u'...'`` prefix, versus simply ``'...'``, and the removal of
1515
the :func:`str.decode` method in Py3.
1616

1717
``future`` contains a backport of the :mod:`str` object from Python 3 which
@@ -63,9 +63,9 @@ behaviours as Python 3's :class:`str`::
6363
>>> assert list(s) == ['A', 'B', 'C', 'D']
6464
>>> assert s.split('B') == ['A', 'CD']
6565

66-
Currently the easiest way to ensure identical use of (unicode) strings across
67-
Py3 and Py2 in a single-source codebase is to wrap string literals in a
68-
:func:`~str` call, as follows::
66+
If you must ensure identical use of (unicode) strings across Py3 and Py2 in a
67+
single-source codebase, you can wrap string literals in a :func:`~str` call, as
68+
follows::
6969
7070
from __future__ import unicode_literals
7171
from future.builtins import *

‎docs/source/what_else.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ What else you need to know
44
**************************
55

66
``future`` cannot completely close the gap between Python 3 and Python 2
7-
with just the right :ref:`imports`. The following require some
7+
with just the right :ref:`imports`. The following points require some
88
additional work.
99

1010
.. _what-else-essentials:

0 commit comments

Comments
 (0)
0