Permalink
Browse files

Docs (mostly): Update references to future.builtins -> builtins

  • Loading branch information...
1 parent fdf1ea3 commit 4002f59843ea6555ad93f13471864d252e825184 @edschofield edschofield committed Oct 1, 2014
Showing with 429 additions and 779 deletions.
  1. +4 −0 .gitignore
  2. +22 −18 README.rst
  3. +3 −3 docs/bytes_object.rst
  4. +4 −4 docs/custom_iterators.rst
  5. +23 −0 docs/dev_notes.rst
  6. +22 −0 docs/development.rst
  7. +12 −11 docs/dict_object.rst
  8. +4 −2 docs/future-builtins.rst
  9. +3 −3 docs/futurize.rst
  10. +7 −4 docs/futurize_cheatsheet.rst
  11. +55 −0 docs/futurize_overview.rst
  12. +18 −11 docs/imports.rst
  13. +2 −2 docs/int_object.rst
  14. +2 −2 docs/isinstance.rst
  15. +2 −2 docs/notebooks/bytes object.ipynb
  16. +3 −3 docs/notebooks/object special methods (next, bool, ...).ipynb
  17. +5 −5 docs/open_function.rst
  18. +35 −33 docs/quickstart.rst
  19. +1 −1 docs/roadmap.rst
  20. +71 −43 docs/standard_library_imports.rst
  21. +13 −8 docs/str_object.rst
  22. +13 −0 docs/upgrading.rst
  23. +11 −6 docs/whatsnew.rst
  24. +0 −577 src/future/backports/http/cookies.py.bak
  25. +1 −5 src/future/standard_library/__init__.py
  26. +7 −2 src/future/tests/base.py
  27. +1 −1 src/future/types/__init__.py
  28. +1 −1 src/future/types/newdict.py
  29. +1 −1 src/future/types/newlist.py
  30. +27 −0 src/future/types/newmemoryview.py
  31. +2 −2 src/future/types/newobject.py
  32. +1 −1 src/future/types/newstr.py
  33. +1 −1 src/future/utils/__init__.py
  34. +5 −5 src/libfuturize/fixer_util.py
  35. +3 −4 src/libfuturize/fixes/fix_future_builtins.py
  36. +1 −1 src/libfuturize/fixes/fix_future_standard_library.py
  37. +2 −2 src/libfuturize/fixes/fix_object.py
  38. +27 −0 src/libfuturize/fixes/fix_remove_old__future__imports.py
  39. +2 −2 src/libfuturize/fixes/fix_xrange_with_import.py
  40. +1 −1 src/libfuturize/main.py
  41. +5 −5 src/libpasteurize/fixes/fix_add_all_future_builtins.py
  42. +3 −4 src/libpasteurize/fixes/fix_future_builtins.py
  43. +1 −1 src/libpasteurize/fixes/fix_newstyle.py
  44. +2 −2 src/libpasteurize/main.py
View
@@ -22,6 +22,10 @@ develop-eggs
lib
lib64
+# Backup files
+*.bak
+*.backup
+
# Installer logs
pip-log.txt
View
@@ -25,15 +25,13 @@ Features
.. image:: https://travis-ci.org/PythonCharmers/python-future.svg?branch=master
:target: https://travis-ci.org/PythonCharmers/python-future
-- ``future.builtins`` package provides backports and remappings for 20
- builtins with different semantics on Py3 versus Py2
+- ``future.builtins`` package (also available as ``builtins`` on Py2) provides
+ backports and remappings for 20 builtins with different semantics on Py3
+ versus Py2
- ``future.standard_library``, in conjunction with ``future.moves``, provides
support for importing standard library modules under their Python 3 names
-- ``future.backports`` package provides backports from the Py3.3
- standard library
-
- ``past.builtins`` package provides forward-ports of 19 Python 2 types and
builtin functions. These can aid with per-module code migrations.
@@ -65,8 +63,8 @@ these imports as it does on Python 3.3+:
.. code-block:: python
from __future__ import absolute_import, division, print_function
- from future.builtins import (bytes, str, open, super, range,
- zip, round, input, int, pow, object)
+ from builtins import (bytes, str, open, super, range,
+ zip, round, input, int, pow, object)
# Backported Py3 bytes object
b = bytes(b'ABCD')
@@ -120,7 +118,7 @@ these imports as it does on Python 3.3+:
assert isinstance('blah', str) # only if unicode_literals is in effect
# Py3-style iterators written as new-style classes (subclasses of
- # future.builtins.object) are automatically backward compatible with Py2:
+ # future.types.newobject) are automatically backward compatible with Py2:
class Upper(object):
def __init__(self, iterable):
self._iter = iter(iterable)
@@ -131,19 +129,25 @@ these imports as it does on Python 3.3+:
assert list(Upper('hello')) == list('HELLO')
-There is also support for renamed standard library modules in the form of import
-hooks. The context-manager form works like this:
+There is also support for renamed standard library modules. The recommended
+interface works like this:
.. code-block:: python
+ # Many Py3 module names are supported directly on both Py2.x and 3.x:
+ from http.client import HttpConnection
+ import html.parser
+ import queue
+ import xmlrpc.client
+
+ # Refactored modules with clashing names on Py2 and Py3 are supported
+ # as follows:
from future import standard_library
+ standard_library.install_aliases()
- with standard_library.hooks():
- from http.client import HttpConnection
- from itertools import filterfalse
- import html.parser
- import queue
- from urllib.request import urlopen
+ # Then, as usual:
+ from itertools import filterfalse
+ from urllib.request import urlopen
Automatic conversion to Py2/3-compatible code
@@ -190,9 +194,9 @@ into this code which runs on both Py2 and Py3:
.. code-block:: python
from __future__ import print_function
- from future.builtins import input
from future import standard_library
- standard_library.install_hooks()
+ standard_library.install_aliases()
+ from builtins import input
import queue
from urllib.request import urlopen
@@ -11,10 +11,10 @@ Python 2's :class:`str`, rather than a true implementation of the Python
:mod:`future` contains a backport of the :mod:`bytes` object from Python 3
which passes most of the Python 3 tests for :mod:`bytes`. (See
-``future/tests/test_bytes.py`` in the source tree.) You can use it as
+``tests/test_future/test_bytes.py`` in the source tree.) You can use it as
follows::
- >>> from future.builtins import bytes
+ >>> from builtins import bytes
>>> b = bytes(b'ABCD')
On Py3, this is simply the builtin :class:`bytes` object. On Py2, this
@@ -53,7 +53,7 @@ Currently the easiest way to ensure identical behaviour of byte-strings
in a Py2/3 codebase is to wrap all byte-string literals ``b'...'`` in a
:func:`~bytes` call as follows::
- from future.builtins import bytes
+ from builtins import bytes
# ...
@@ -8,12 +8,12 @@ to retrieve the next item across Py3 and Py2. On Python 3 it is ``__next__``,
whereas on Python 2 it is ``next``.
The most elegant solution to this is to derive your custom iterator class from
-``future.builtins.object`` and define a ``__next__`` method as you normally
+``builtins.object`` and define a ``__next__`` method as you normally
would on Python 3. On Python 2, ``object`` then refers to the
``future.types.newobject`` base class, which provides a fallback ``next``
method that calls your ``__next__``. Use it as follows::
- from future.builtins import object
+ from builtins import object
class Upper(object):
def __init__(self, iterable):
@@ -31,10 +31,10 @@ method that calls your ``__next__``. Use it as follows::
You can use this approach unless you are defining a custom iterator as a
subclass of a base class defined elsewhere that does not derive from
-``future.builtins.object``. In that case, you can provide compatibility across
+``newobject``. In that case, you can provide compatibility across
Python 2 and Python 3 using the ``next`` function from ``future.builtins``::
- from future.builtins import next
+ from builtins import next
from some_module import some_base_class
View
@@ -0,0 +1,23 @@
+Notes
+-----
+This module only supports Python 2.6, Python 2.7, and Python 3.1+.
+
+The following renames are already supported on Python 2.7 without any
+additional work from us::
+
+ reload() -> imp.reload()
+ reduce() -> functools.reduce()
+ StringIO.StringIO -> io.StringIO
+ Bytes.BytesIO -> io.BytesIO
+
+Old things that can one day be fixed automatically by futurize.py::
+
+ string.uppercase -> string.ascii_uppercase # works on either Py2.7 or Py3+
+ sys.maxint -> sys.maxsize # but this isn't identical
+
+TODO: Check out these:
+Not available on Py2.6:
+ unittest2 -> unittest?
+ buffer -> memoryview?
+
+
View
@@ -0,0 +1,22 @@
+.. developer-docs
+
+Developer docs
+==============
+
+The easiest way to start developing ``python-future`` is as follows:
+
+1. Install Anaconda Python distribution
+
+2. Run::
+
+ conda install -n future2 python=2.7 pip
+ conda install -n future3 python=3.3 pip
+
+ git clone https://github.com/PythonCharmers/python-future
+
+3. If you are using Anaconda Python distribution, this comes without a ``test``
+module on Python 2.x. Copy ``Python-2.7.6/Lib/test`` from the Python source tree
+to ``~/anaconda/envs/yourenvname/lib/python2.7/site-packages/`.
+
+
+
View
@@ -25,14 +25,15 @@ stick with standard Python 3 code in your Py2/3 compatible codebase::
In this case there will be memory overhead of list creation for each call to
``items``, ``values`` or ``keys``.
-For improved efficiency, ``future.builtins`` provides a Python 2 ``dict``
-subclass whose :func:`keys`, :func:`values`, and :func:`items` methods return
-iterators on all versions of Python >= 2.6. On Python 2.7, these iterators also
-have the same set-like view behaviour as dictionaries in Python 3. This can
-streamline code that iterates over large dictionaries. For example::
+For improved efficiency, ``future.builtins`` (aliased to ``builtins``) provides
+a Python 2 ``dict`` subclass whose :func:`keys`, :func:`values`, and
+:func:`items` methods return iterators on all versions of Python >= 2.6. On
+Python 2.7, these iterators also have the same set-like view behaviour as
+dictionaries in Python 3. This can streamline code that iterates over large
+dictionaries. For example::
from __future__ import print_function
- from future.builtins import dict, range
+ from builtins import dict, range
# Memory-efficient construction:
d = dict((i, i**2) for i in range(10**7))
@@ -46,16 +47,16 @@ streamline code that iterates over large dictionaries. For example::
On Python 2.6, these methods currently return iterators but do not support the
new Py3 set-like behaviour.
-As usual, on Python 3 ``future.builtins.dict`` is just the built-in ``dict``
-class.
+As usual, on Python 3 ``dict`` imported from either ``builtins`` or
+``future.builtins`` is just the built-in ``dict`` class.
Memory-efficiency and alternatives
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If you already have large native dictionaries, the downside to wrapping them in
-a ``dict`` call is that memory is copied (on both Py3 and with
-``future.builtins.dict``). For example::
+a ``dict`` call is that memory is copied (on both Py3 and on Py2). For
+example::
# This allocates and then frees a large amount of temporary memory:
d = dict({i: i**2 for i in range(10**7)})
@@ -72,7 +73,7 @@ The memory-efficient (and CPU-efficient) alternatives are:
d = dict((i, i**2) for i in range(10**7)
- to construct an empty dictionary with a ``dict()`` call using
- ``future.builtins.dict`` (rather than ``{}``) and then update it;
+ ``builtins.dict`` (rather than ``{}``) and then update it;
- to use the ``viewitems`` etc. functions from :mod:`future.utils`, passing in
regular dictionaries::
@@ -3,14 +3,16 @@
``future.builtins``
===================
+The ``future.builtins`` module is also accessible as ``builtins`` on Py2.
+
- ``pow()`` supports fractional exponents of negative numbers like in Py3::
- >>> from future.builtins import pow
+ >>> from builtins import pow
>>> pow(-1, 0.5)
(6.123233995736766e-17+1j)
- ``round()`` uses Banker's Rounding as in Py3 to the nearest even last digit::
- >>> from future.builtins import round
+ >>> from builtins import round
>>> assert round(0.1250, 2) == 0.12
View
@@ -192,8 +192,8 @@ For example::
would be converted by Stage 2 to this code::
- from future.builtins import input
- from future.builtins import str
+ from builtins import input
+ from builtins import str
from future.utils import iteritems, python_2_unicode_compatible
name = input('What is your name?\n')
@@ -290,7 +290,7 @@ that these types behave similarly on Python 2 as on Python 3, also wrap
byte-strings or text in the ``bytes`` and ``str`` types from ``future``. For
example::
- from future.builtins import bytes, str
+ from builtins import bytes, str
b = bytes(b'\x00ABCD')
s = str(u'This is normal text')
@@ -88,12 +88,15 @@ changes to all Python source files recursively with::
To apply the changes, add the ``-w`` argument.
This stage makes further conversions needed to support both Python 2 and 3.
-These will likely require imports from ``future``, such as::
+These will likely require imports from ``future`` on Py2 (and sometimes on Py3),
+such as::
from future import standard_library
- standard_library.install_hooks()
- from future.builtins import bytes
- from future.builtins import open
+ standard_library.install_aliases()
+ # ...
+ from builtins import bytes
+ from builtins import open
+ from future.utils import with_metaclass
Optionally, you can use the ``--unicode-literals`` flag to add this import to
the top of each module::
@@ -0,0 +1,55 @@
+The ``futurize`` script passes Python 2 code through all the appropriate fixers
+to turn it into valid Python 3 code, and then adds ``__future__`` and
+``future`` package imports to re-enable compatibility with Python 2.
+
+For example, running ``futurize`` turns this Python 2 code:
+
+.. code-block:: python
+
+ import ConfigParser # Py2 module name
+
+ class Upper(object):
+ def __init__(self, iterable):
+ self._iter = iter(iterable)
+ def next(self): # Py2-style iterator interface
+ return next(self._iter).upper()
+ def __iter__(self):
+ return self
+
+ itr = Upper('hello')
+ print next(itr),
+ for letter in itr:
+ print letter, # Py2-style print statement
+
+into this code which runs on both Py2 and Py3:
+
+.. code-block:: python
+
+ from __future__ import print_function
+ from future import standard_library
+ standard_library.install_hooks()
+ from future.builtins import next
+ from future.builtins import object
+ import configparser # Py3-style import
+
+ class Upper(object):
+ def __init__(self, iterable):
+ self._iter = iter(iterable)
+ def __next__(self): # Py3-style iterator interface
+ return next(self._iter).upper()
+ def __iter__(self):
+ return self
+
+ itr = Upper('hello')
+ print(next(itr), end=' ') # Py3-style print function
+ for letter in itr:
+ print(letter, end=' ')
+
+
+To write out all the changes to your Python files that ``futurize`` suggests,
+use the ``-w`` flag.
+
+For complex projects, it is probably best to divide the porting into two stages.
+Stage 1 is for "safe" changes that modernize the code but do not break Python
+2.6 compatibility or introduce a depdendency on the ``future`` package. Stage 2
+is to complete the process.
Oops, something went wrong.

0 comments on commit 4002f59

Please sign in to comment.