README.rst 9.7 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287
  1. .. _overview:
  2. Overview: Easy, clean, reliable Python 2/3 compatibility
  3. ========================================================
  4. ``python-future`` is the missing compatibility layer between Python 2 and
  5. Python 3. It allows you to use a single, clean Python 3.x-compatible
  6. codebase to support both Python 2 and Python 3 with minimal overhead.
  7. It provides ``future`` and ``past`` packages with backports and forward
  8. ports of features from Python 3 and 2. It also comes with ``futurize`` and
  9. ``pasteurize``, customized 2to3-based scripts that helps you to convert
  10. either Py2 or Py3 code easily to support both Python 2 and 3 in a single
  11. clean Py3-style codebase, module by module.
  12. Notable projects that use ``python-future`` for Python 2/3 compatibility
  13. are `Mezzanine <http://mezzanine.jupo.org/>`_ and `ObsPy
  14. <http://obspy.org>`_.
  15. .. _features:
  16. Features
  17. --------
  18. .. image:: https://travis-ci.org/PythonCharmers/python-future.svg?branch=master
  19. :target: https://travis-ci.org/PythonCharmers/python-future
  20. - ``future.builtins`` package (also available as ``builtins`` on Py2) provides
  21. backports and remappings for 20 builtins with different semantics on Py3
  22. versus Py2
  23. - support for directly importing 30 standard library modules under
  24. their Python 3 names on Py2
  25. - support for importing the other 14 refactored standard library modules
  26. under their Py3 names relatively cleanly via
  27. ``future.standard_library`` and ``future.moves``
  28. - ``past.builtins`` package provides forward-ports of 19 Python 2 types and
  29. builtin functions. These can aid with per-module code migrations.
  30. - ``past.translation`` package supports transparent translation of Python 2
  31. modules to Python 3 upon import. [This feature is currently in alpha.]
  32. - 1000+ unit tests, including many from the Py3.3 source tree.
  33. - ``futurize`` and ``pasteurize`` scripts based on ``2to3`` and parts of
  34. ``3to2`` and ``python-modernize``, for automatic conversion from either Py2
  35. or Py3 to a clean single-source codebase compatible with Python 2.6+ and
  36. Python 3.3+.
  37. - a curated set of utility functions and decorators in ``future.utils`` and
  38. ``past.utils`` selected from Py2/3 compatibility interfaces from projects
  39. like ``six``, ``IPython``, ``Jinja2``, ``Django``, and ``Pandas``.
  40. - support for the ``surrogateescape`` error handler when encoding and
  41. decoding the backported ``str`` and ``bytes`` objects. [This feature is
  42. currently in alpha.]
  43. .. _code-examples:
  44. Code examples
  45. -------------
  46. Replacements for Py2's built-in functions and types are designed to be imported
  47. at the top of each Python module together with Python's built-in ``__future__``
  48. statements. For example, this code behaves identically on Python 2.6/2.7 after
  49. these imports as it does on Python 3.3+:
  50. .. code-block:: python
  51. from __future__ import absolute_import, division, print_function
  52. from builtins import (bytes, str, open, super, range,
  53. zip, round, input, int, pow, object)
  54. # Backported Py3 bytes object
  55. b = bytes(b'ABCD')
  56. assert list(b) == [65, 66, 67, 68]
  57. assert repr(b) == "b'ABCD'"
  58. # These raise TypeErrors:
  59. # b + u'EFGH'
  60. # bytes(b',').join([u'Fred', u'Bill'])
  61. # Backported Py3 str object
  62. s = str(u'ABCD')
  63. assert s != bytes(b'ABCD')
  64. assert isinstance(s.encode('utf-8'), bytes)
  65. assert isinstance(b.decode('utf-8'), str)
  66. assert repr(s) == "'ABCD'" # consistent repr with Py3 (no u prefix)
  67. # These raise TypeErrors:
  68. # bytes(b'B') in s
  69. # s.find(bytes(b'A'))
  70. # Extra arguments for the open() function
  71. f = open('japanese.txt', encoding='utf-8', errors='replace')
  72. # New zero-argument super() function:
  73. class VerboseList(list):
  74. def append(self, item):
  75. print('Adding an item')
  76. super().append(item)
  77. # New iterable range object with slicing support
  78. for i in range(10**15)[:10]:
  79. pass
  80. # Other iterators: map, zip, filter
  81. my_iter = zip(range(3), ['a', 'b', 'c'])
  82. assert my_iter != list(my_iter)
  83. # The round() function behaves as it does in Python 3, using
  84. # "Banker's Rounding" to the nearest even last digit:
  85. assert round(0.1250, 2) == 0.12
  86. # input() replaces Py2's raw_input() (with no eval()):
  87. name = input('What is your name? ')
  88. print('Hello ' + name)
  89. # pow() supports fractional exponents of negative numbers like in Py3:
  90. z = pow(-1, 0.5)
  91. # Compatible output from isinstance() across Py2/3:
  92. assert isinstance(2**64, int) # long integers
  93. assert isinstance(u'blah', str)
  94. assert isinstance('blah', str) # only if unicode_literals is in effect
  95. # Py3-style iterators written as new-style classes (subclasses of
  96. # future.types.newobject) are automatically backward compatible with Py2:
  97. class Upper(object):
  98. def __init__(self, iterable):
  99. self._iter = iter(iterable)
  100. def __next__(self): # note the Py3 interface
  101. return next(self._iter).upper()
  102. def __iter__(self):
  103. return self
  104. assert list(Upper('hello')) == list('HELLO')
  105. There is also support for renamed standard library modules. The recommended
  106. interface works like this:
  107. .. code-block:: python
  108. # Many Py3 module names are supported directly on both Py2.x and 3.x:
  109. from http.client import HttpConnection
  110. import html.parser
  111. import queue
  112. import xmlrpc.client
  113. # Refactored modules with clashing names on Py2 and Py3 are supported
  114. # as follows:
  115. from future import standard_library
  116. standard_library.install_aliases()
  117. # Then, for example:
  118. from itertools import filterfalse, zip_longest
  119. from urllib.request import urlopen
  120. from collections import ChainMap
  121. from collections import UserDict, UserList, UserString
  122. from subprocess import getoutput, getstatusoutput
  123. from collections import Counter, OrderedDict # backported to Py2.6
  124. Automatic conversion to Py2/3-compatible code
  125. ---------------------------------------------
  126. ``python-future`` comes with two scripts called ``futurize`` and
  127. ``pasteurize`` to aid in making Python 2 code or Python 3 code compatible with
  128. both platforms (Py2/3). It is based on 2to3 and uses fixers from ``lib2to3``,
  129. ``lib3to2``, and ``python-modernize``, as well as custom fixers.
  130. ``futurize`` passes Python 2 code through all the appropriate fixers to turn it
  131. into valid Python 3 code, and then adds ``__future__`` and ``future`` package
  132. imports so that it also runs under Python 2.
  133. For conversions from Python 3 code to Py2/3, use the ``pasteurize`` script
  134. instead. This converts Py3-only constructs (e.g. new metaclass syntax) to
  135. Py2/3 compatible constructs and adds ``__future__`` and ``future`` imports to
  136. the top of each module.
  137. In both cases, the result should be relatively clean Py3-style code that runs
  138. mostly unchanged on both Python 2 and Python 3.
  139. Futurize: 2 to both
  140. ~~~~~~~~~~~~~~~~~~~
  141. For example, running ``futurize -w mymodule.py`` turns this Python 2 code:
  142. .. code-block:: python
  143. import Queue
  144. from urllib2 import urlopen
  145. def greet(name):
  146. print 'Hello',
  147. print name
  148. print "What's your name?",
  149. name = raw_input()
  150. greet(name)
  151. into this code which runs on both Py2 and Py3:
  152. .. code-block:: python
  153. from __future__ import print_function
  154. from future import standard_library
  155. standard_library.install_aliases()
  156. from builtins import input
  157. import queue
  158. from urllib.request import urlopen
  159. def greet(name):
  160. print('Hello', end=' ')
  161. print(name)
  162. print("What's your name?", end=' ')
  163. name = input()
  164. greet(name)
  165. See :ref:`forwards-conversion` and :ref:`backwards-conversion` for more details.
  166. Automatic translation
  167. ---------------------
  168. The ``past`` package can automatically translate some simple Python 2
  169. modules to Python 3 upon import. The goal is to support the "long tail" of
  170. real-world Python 2 modules (e.g. on PyPI) that have not been ported yet. For
  171. example, here is how to use a Python 2-only package called ``plotrique`` on
  172. Python 3. First install it:
  173. .. code-block:: bash
  174. $ pip3 install plotrique==0.2.5-7 --no-compile # to ignore SyntaxErrors
  175. (or use ``pip`` if this points to your Py3 environment.)
  176. Then pass a whitelist of module name prefixes to the ``autotranslate()`` function.
  177. Example:
  178. .. code-block:: bash
  179. $ python3
  180. >>> from past import autotranslate
  181. >>> autotranslate(['plotrique'])
  182. >>> import plotrique
  183. This transparently translates and runs the ``plotrique`` module and any
  184. submodules in the ``plotrique`` package that ``plotrique`` imports.
  185. This is intended to help you migrate to Python 3 without the need for all
  186. your code's dependencies to support Python 3 yet. It should be used as a
  187. last resort; ideally Python 2-only dependencies should be ported
  188. properly to a Python 2/3 compatible codebase using a tool like
  189. ``futurize`` and the changes should be pushed to the upstream project.
  190. Note: the auto-translation feature is still in alpha; it needs more testing and
  191. development, and will likely never be perfect.
  192. For more info, see :ref:`translation`.
  193. Licensing
  194. ---------
  195. :Author: Ed Schofield
  196. :Copyright: 2013-2016 Python Charmers Pty Ltd, Australia.
  197. :Sponsor: Python Charmers Pty Ltd, Australia, and Python Charmers Pte
  198. Ltd, Singapore. http://pythoncharmers.com
  199. :Licence: MIT. See ``LICENSE.txt`` or `here <http://python-future.org/credits.html>`_.
  200. :Other credits: See `here <http://python-future.org/credits.html>`_.
  201. Next steps
  202. ----------
  203. If you are new to Python-Future, check out the `Quickstart Guide
  204. <http://python-future.org/quickstart.html>`_.
  205. For an update on changes in the latest version, see the `What's New
  206. <http://python-future.org/whatsnew.html>`_ page.