faq.rst 12 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317
  1. Frequently Asked Questions (FAQ)
  2. ********************************
  3. Who is this for?
  4. ================
  5. 1. People with existing or new Python 3 codebases who wish to provide
  6. ongoing Python 2.6 / 2.7 support easily and with little maintenance burden.
  7. 2. People who wish to ease and accelerate migration of their Python 2 codebases
  8. to Python 3.3+, module by module, without giving up Python 2 compatibility.
  9. Why upgrade to Python 3?
  10. ========================
  11. .. epigraph::
  12. "Python 2 is the next COBOL."
  13. -- Alex Gaynor, at PyCon AU 2013
  14. Python 2.7 is the end of the Python 2 line. (See `PEP 404
  15. <http://www.python.org/peps/pep-0404/>`_.) The language and standard
  16. libraries are improving only in Python 3.x.
  17. Python 3.x is a better language and better set of standard libraries than
  18. Python 2.x in many ways. Python 3.x is cleaner, less warty, and easier to
  19. learn than Python 2. It has better memory efficiency, easier Unicode handling,
  20. and powerful new features like the `asyncio
  21. <https://docs.python.org/3/library/asyncio.html>`_ module.
  22. .. Unicode handling is also much easier. For example, see `this page
  23. .. <http://pythonhosted.org/kitchen/unicode-frustrations.html>`_
  24. .. describing some of the problems with handling Unicode on Python 2 that
  25. .. Python 3 mostly solves.
  26. Porting philosophy
  27. ==================
  28. Why write Python 3-style code?
  29. ------------------------------
  30. Here are some quotes:
  31. - "Django's developers have found that attempting to write Python 3 code
  32. that's compatible with Python 2 is much more rewarding than the
  33. opposite." from the `Django docs
  34. <https://docs.djangoproject.com/en/dev/topics/python3/>`_.
  35. - "Thanks to Python 3 being more strict about things than Python 2 (e.g.,
  36. bytes vs. strings), the source translation [from Python 3 to 2] can be
  37. easier and more straightforward than from Python 2 to 3. Plus it gives
  38. you more direct experience developing in Python 3 which, since it is
  39. the future of Python, is a good thing long-term." from the official
  40. guide `"Porting Python 2 Code to Python 3"
  41. <http://docs.python.org/2/howto/pyporting.html>`_ by Brett Cannon.
  42. - "Developer energy should be reserved for addressing real technical
  43. difficulties associated with the Python 3 transition (like
  44. distinguishing their 8-bit text strings from their binary data). They
  45. shouldn't be punished with additional code changes ..." from `PEP 414
  46. <http://www.python.org/dev/peps/pep-0414/>`_ by Armin Ronacher and Nick
  47. Coghlan.
  48. Can't I just roll my own Py2/3 compatibility layer?
  49. ---------------------------------------------------
  50. Yes, but using ``python-future`` will probably be easier and lead to cleaner
  51. code with fewer bugs.
  52. Consider this quote:
  53. .. epigraph::
  54. "Duplication of effort is wasteful, and replacing the various
  55. home-grown approaches with a standard feature usually ends up making
  56. things more readable, and interoperable as well."
  57. -- Guido van Rossum (`blog post <http://www.artima.com/weblogs/viewpost.jsp?thread=86641>`_)
  58. ``future`` also includes various Py2/3 compatibility tools in
  59. :mod:`future.utils` picked from large projects (including IPython,
  60. Django, Jinja2, Pandas), which should reduce the burden on every project to
  61. roll its own py3k compatibility wrapper module.
  62. What inspired this project?
  63. ---------------------------
  64. In our Python training courses, we at `Python Charmers
  65. <http://pythoncharmers.com>`_ faced a dilemma: teach people Python 3, which was
  66. future-proof but not as useful to them today because of weaker 3rd-party
  67. package support, or teach people Python 2, which was more useful today but
  68. would require them to change their code and unlearn various habits soon. We
  69. searched for ways to avoid polluting the world with more deprecated code, but
  70. didn't find a good way.
  71. Also, in attempting to help with porting packages such as `scikit-learn
  72. <http://scikit-learn.org>`_ to Python 3, I (Ed) was dissatisfied with how much
  73. code cruft was necessary to introduce to support Python 2 and 3 from a single
  74. codebase (the preferred porting option). Since backward-compatibility with
  75. Python 2 may be necessary for at least the next 5 years, one of the promised
  76. benefits of Python 3 -- cleaner code with fewer of Python 2's warts -- was
  77. difficult to realize before in practice in a single codebase that supported
  78. both platforms.
  79. The goal is to accelerate the uptake of Python 3 and help the strong Python
  80. community to remain united around a single version of the language.
  81. Maturity
  82. ========
  83. How well has it been tested?
  84. ----------------------------
  85. ``future`` is used by several major projects, including `mezzanine
  86. <http://mezzanine.jupo.org>`_ and `ObsPy <http://www.obspy.org>`_. It is also
  87. currently being used to help with porting 800,000 lines of Python 2 code in
  88. `Sage <http://sagemath.org>`_ to Python 2/3.
  89. Currently ``python-future`` has over 1000 unit tests. Many of these are straight
  90. from the Python 3.3 and 3.4 test suites.
  91. In general, the ``future`` package itself is in good shape, whereas the
  92. ``futurize`` script for automatic porting is imperfect; chances are it will
  93. require some manual cleanup afterwards. The ``past`` package also needs to be
  94. expanded.
  95. Is the API stable?
  96. ------------------
  97. Not yet; ``future`` is still in beta. Where possible, we will try not to break
  98. anything which was documented and used to work. After version 1.0 is released,
  99. the API will not change in backward-incompatible ways until a hypothetical
  100. version 2.0.
  101. ..
  102. Are there any example of Python 2 packages ported to Python 3 using ``future`` and ``futurize``?
  103. ------------------------------------------------------------------------------------------------
  104. Yes, an example is the port of ``xlwt``, available `here
  105. <https://github.com/python-excel/xlwt/pull/32>`_.
  106. The code also contains backports for several Py3 standard library
  107. modules under ``future/standard_library/``.
  108. Relationship between python-future and other compatibility tools
  109. ================================================================
  110. How does this relate to ``2to3``?
  111. ---------------------------------
  112. ``2to3`` is a powerful and flexible tool that can produce different
  113. styles of Python 3 code. It is, however, primarily designed for one-way
  114. porting efforts, for projects that can leave behind Python 2 support.
  115. The example at the top of the `2to3 docs
  116. <http://docs.python.org/2/library/2to3.html>`_ demonstrates this. After
  117. transformation by ``2to3``, ``example.py`` looks like this::
  118. def greet(name):
  119. print("Hello, {0}!".format(name))
  120. print("What's your name?")
  121. name = input()
  122. greet(name)
  123. This is Python 3 code that, although syntactically valid on Python 2,
  124. is semantically incorrect. On Python 2, it raises an exception for
  125. most inputs; worse, it allows arbitrary code execution by the user
  126. for specially crafted inputs because of the ``eval()`` executed by Python
  127. 2's ``input()`` function.
  128. This is not an isolated example; almost every output of ``2to3`` will need
  129. modification to provide backward compatibility with Python 2. As an
  130. alternative, the ``python-future`` project provides a script called
  131. ``futurize`` that is based on ``lib2to3`` but will produce code that is
  132. compatible with both platforms (Py2 and Py3).
  133. Can I maintain a Python 2 codebase and use 2to3 to automatically convert to Python 3 in the setup script?
  134. ---------------------------------------------------------------------------------------------------------
  135. This was originally the approach recommended by Python's core developers,
  136. but it has some large drawbacks:
  137. 1. First, your actual working codebase will be stuck with Python 2's
  138. warts and smaller feature set for as long as you need to retain Python 2
  139. compatibility. This may be at least 5 years for many projects, possibly
  140. much longer.
  141. 2. Second, this approach carries the significant disadvantage that you
  142. cannot apply patches submitted by Python 3 users against the
  143. auto-generated Python 3 code. (See `this talk
  144. <http://www.youtube.com/watch?v=xNZ4OVO2Z_E>`_ by Jacob Kaplan-Moss.)
  145. What is the relationship between ``future`` and ``six``?
  146. --------------------------------------------------------
  147. ``python-future`` is a higher-level compatibility layer than ``six`` that
  148. includes more backported functionality from Python 3, more forward-ported
  149. functionality from Python 2, and supports cleaner code, but requires more
  150. modern Python versions to run.
  151. ``python-future`` and ``six`` share the same goal of making it possible to write
  152. a single-source codebase that works on both Python 2 and Python 3.
  153. ``python-future`` has the further goal of allowing standard Py3 code to run with
  154. almost no modification on both Py3 and Py2. ``future`` provides a more
  155. complete set of support for Python 3's features, including backports of
  156. Python 3 builtins such as the ``bytes`` object (which is very different
  157. to Python 2's ``str`` object) and several standard library modules.
  158. ``python-future`` supports only Python 2.6+ and Python 3.3+, whereas ``six``
  159. supports all versions of Python from 2.4 onwards. (See
  160. :ref:`supported-versions`.) If you must support older Python versions,
  161. ``six`` will be esssential for you. However, beware that maintaining
  162. single-source compatibility with older Python versions is ugly and `not
  163. fun <http://lucumr.pocoo.org/2013/5/21/porting-to-python-3-redux/>`_.
  164. If you can drop support for older Python versions, ``python-future`` leverages
  165. some important features introduced into Python 2.6 and 2.7, such as
  166. import hooks, and a comprehensive and well-tested set of backported
  167. functionality, to allow you to write more idiomatic, maintainable code with
  168. fewer compatibility hacks.
  169. What is the relationship between ``python-future`` and ``python-modernize``?
  170. ----------------------------------------------------------------------------
  171. ``python-future`` contains, in addition to the ``future`` compatibility
  172. package, a ``futurize`` script that is similar to ``python-modernize.py``
  173. in intent and design. Both are based heavily on ``2to3``.
  174. Whereas ``python-modernize`` converts Py2 code into a common subset of
  175. Python 2 and 3, with ``six`` as a run-time dependency, ``futurize``
  176. converts either Py2 or Py3 code into (almost) standard Python 3 code,
  177. with ``future`` as a run-time dependency.
  178. Because ``future`` provides more backported Py3 behaviours from ``six``,
  179. the code resulting from ``futurize`` is more likely to work
  180. identically on both Py3 and Py2 with less additional manual porting
  181. effort.
  182. Platform and version support
  183. ============================
  184. .. _supported-versions:
  185. Which versions of Python does ``python-future`` support?
  186. --------------------------------------------------------
  187. Python 2.6, 2.7, and 3.3+ only.
  188. Python 2.6 and 2.7 introduced many important forward-compatibility
  189. features (such as import hooks, ``b'...'`` literals and ``__future__``
  190. definitions) that greatly reduce the maintenance burden for single-source
  191. Py2/3 compatible code. ``future`` leverages these features and aims to
  192. close the remaining gap between Python 3 and 2.6 / 2.7.
  193. Python 3.2 could perhaps be supported too, although the illegal unicode
  194. literal ``u'...'`` syntax may be inconvenient to work around. The Py3.2
  195. userbase is very small, however. Please let us know via GitHub `issue #29
  196. <https://github.com/PythonCharmers/python-future/issues/29>`_ if you
  197. would like to see Py3.2 support.
  198. Do you support Pypy?
  199. ~~~~~~~~~~~~~~~~~~~~
  200. Yes, except for the standard library import hooks (currently). Feedback
  201. and pull requests are welcome!
  202. Do you support IronPython and/or Jython?
  203. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  204. Not sure. This would be nice...
  205. .. _support:
  206. Support
  207. =======
  208. Is there a mailing list?
  209. ------------------------
  210. Yes, please ask any questions on the `python-porting
  211. <https://mail.python.org/mailman/listinfo/python-porting>`_ mailing list.
  212. .. _contributing:
  213. Contributing
  214. ============
  215. Can I help?
  216. -----------
  217. Yes please :) We welcome bug reports, additional tests, pull requests,
  218. and stories of either success or failure with using it. Help with the fixers
  219. for the ``futurize`` script is particularly welcome.
  220. Where is the repo?
  221. ------------------
  222. `<https://github.com/PythonCharmers/python-future>`_.