Frequently Asked Questions (FAQ)
********************************

Who is this for?
================

1. People with existing or new Python 3 codebases who wish to provide
ongoing Python 2.7 support easily and with little maintenance burden.

2. People who wish to ease and accelerate migration of their Python 2 codebases
to Python 3.4+, module by module, without giving up Python 2 compatibility.


Why upgrade to Python 3?
========================

.. epigraph::

   "Python 2 is the next COBOL."

   -- Alex Gaynor, at PyCon AU 2013

Python 2.7 is the end of the Python 2 line. (See `PEP 404
<http://www.python.org/peps/pep-0404/>`_.) The language and standard
libraries are improving only in Python 3.x.

Python 3.x is a better language and better set of standard libraries than
Python 2.x in many ways. Python 3.x is cleaner, less warty, and easier to
learn than Python 2. It has better memory efficiency, easier Unicode handling,
and powerful new features like the `asyncio
<https://docs.python.org/3/library/asyncio.html>`_ module.

.. Unicode handling is also much easier. For example, see `this page
.. <http://pythonhosted.org/kitchen/unicode-frustrations.html>`_
.. describing some of the problems with handling Unicode on Python 2 that
.. Python 3 mostly solves.


Porting philosophy
==================

Why write Python 3-style code?
------------------------------

Here are some quotes:

- "Django's developers have found that attempting to write Python 3 code
  that's compatible with Python 2 is much more rewarding than the
  opposite." from the `Django docs
  <https://docs.djangoproject.com/en/dev/topics/python3/>`_.

- "Thanks to Python 3 being more strict about things than Python 2 (e.g.,
  bytes vs. strings), the source translation [from Python 3 to 2] can be
  easier and more straightforward than from Python 2 to 3. Plus it gives
  you more direct experience developing in Python 3 which, since it is
  the future of Python, is a good thing long-term." from the official
  guide `"Porting Python 2 Code to Python 3"
  <http://docs.python.org/2/howto/pyporting.html>`_ by Brett Cannon.

- "Developer energy should be reserved for addressing real technical
  difficulties associated with the Python 3 transition (like
  distinguishing their 8-bit text strings from their binary data). They
  shouldn't be punished with additional code changes ..." from `PEP 414
  <http://www.python.org/dev/peps/pep-0414/>`_ by Armin Ronacher and Nick
  Coghlan.


Can't I just roll my own Py2/3 compatibility layer?
---------------------------------------------------

Yes, but using ``python-future`` will probably be easier and lead to cleaner
code with fewer bugs.

Consider this quote:

.. epigraph::

   "Duplication of effort is wasteful, and replacing the various
   home-grown approaches with a standard feature usually ends up making
   things more readable, and interoperable as well."

   -- Guido van Rossum (`blog post <http://www.artima.com/weblogs/viewpost.jsp?thread=86641>`_)


``future`` also includes various Py2/3 compatibility tools in
:mod:`future.utils` picked from large projects (including IPython,
Django, Jinja2, Pandas), which should reduce the burden on every project to
roll its own py3k compatibility wrapper module.


What inspired this project?
---------------------------

In our Python training courses, we at `Python Charmers
<http://pythoncharmers.com>`_ faced a dilemma: teach people Python 3, which was
future-proof but not as useful to them today because of weaker 3rd-party
package support, or teach people Python 2, which was more useful today but
would require them to change their code and unlearn various habits soon. We
searched for ways to avoid polluting the world with more deprecated code, but
didn't find a good way.

Also, in attempting to help with porting packages such as `scikit-learn
<http://scikit-learn.org>`_ to Python 3, I (Ed) was dissatisfied with how much
code cruft was necessary to introduce to support Python 2 and 3 from a single
codebase (the preferred porting option). Since backward-compatibility with
Python 2 may be necessary for at least the next 5 years, one of the promised
benefits of Python 3 -- cleaner code with fewer of Python 2's warts -- was
difficult to realize before in practice in a single codebase that supported
both platforms.

The goal is to accelerate the uptake of Python 3 and help the strong Python
community to remain united around a single version of the language.


Maturity
========

How well has it been tested?
----------------------------

``future`` is used by several major projects, including `mezzanine
<http://mezzanine.jupo.org>`_ and `ObsPy <http://www.obspy.org>`_. It is also
currently being used to help with porting 800,000 lines of Python 2 code in
`Sage <http://sagemath.org>`_ to Python 2/3.

Currently ``python-future`` has over 1000 unit tests. Many of these are straight
from the Python 3.3 and 3.4 test suites.

In general, the ``future`` package itself is in good shape, whereas the
``futurize`` script for automatic porting is imperfect; chances are it will
require some manual cleanup afterwards. The ``past`` package also needs to be
expanded.


Is the API stable?
------------------

Not yet; ``future`` is still in beta. Where possible, we will try not to break
anything which was documented and used to work.  After version 1.0 is released,
the API will not change in backward-incompatible ways until a hypothetical
version 2.0.

..
    Are there any example of Python 2 packages ported to Python 3 using ``future`` and ``futurize``?
    ------------------------------------------------------------------------------------------------

    Yes, an example is the port of ``xlwt``, available `here
    <https://github.com/python-excel/xlwt/pull/32>`_.

    The code also contains backports for several Py3 standard library
    modules under ``future/standard_library/``.


Relationship between python-future and other compatibility tools
================================================================

How does this relate to ``2to3``?
---------------------------------

``2to3`` is a powerful and flexible tool that can produce different
styles of Python 3 code. It is, however, primarily designed for one-way
porting efforts, for projects that can leave behind Python 2 support.

The example at the top of the `2to3 docs
<http://docs.python.org/2/library/2to3.html>`_ demonstrates this.  After
transformation by ``2to3``, ``example.py`` looks like this::

    def greet(name):
        print("Hello, {0}!".format(name))
    print("What's your name?")
    name = input()
    greet(name)

This is Python 3 code that, although syntactically valid on Python 2,
is semantically incorrect. On Python 2, it raises an exception for
most inputs; worse, it allows arbitrary code execution by the user
for specially crafted inputs because of the ``eval()`` executed by Python
2's ``input()`` function.

This is not an isolated example; almost every output of ``2to3`` will need
modification to provide backward compatibility with Python 2. As an
alternative, the ``python-future`` project provides a script called
``futurize`` that is based on ``lib2to3`` but will produce code that is
compatible with both platforms (Py2 and Py3).


Can I maintain a Python 2 codebase and use 2to3 to automatically convert to Python 3 in the setup script?
---------------------------------------------------------------------------------------------------------

This was originally the approach recommended by Python's core developers,
but it has some large drawbacks:

1. First, your actual working codebase will be stuck with Python 2's
warts and smaller feature set for as long as you need to retain Python 2
compatibility. This may be at least 5 years for many projects, possibly
much longer.

2. Second, this approach carries the significant disadvantage that you
cannot apply patches submitted by Python 3 users against the
auto-generated Python 3 code. (See `this talk
<http://www.youtube.com/watch?v=xNZ4OVO2Z_E>`_ by Jacob Kaplan-Moss.)


What is the relationship between ``future`` and ``six``?
--------------------------------------------------------

``python-future`` is a higher-level compatibility layer than ``six`` that
includes more backported functionality from Python 3, more forward-ported
functionality from Python 2, and supports cleaner code, but requires more
modern Python versions to run.

``python-future`` and ``six`` share the same goal of making it possible to write
a single-source codebase that works on both Python 2 and Python 3.
``python-future`` has the further goal of allowing standard Py3 code to run with
almost no modification on both Py3 and Py2. ``future`` provides a more
complete set of support for Python 3's features, including backports of
Python 3 builtins such as the ``bytes`` object (which is very different
to Python 2's ``str`` object) and several standard library modules.

``python-future`` supports only Python 2.7+ and Python 3.4+, whereas ``six``
supports all versions of Python from 2.4 onwards. (See
:ref:`supported-versions`.) If you must support older Python versions,
``six`` will be essential for you. However, beware that maintaining
single-source compatibility with older Python versions is ugly and `not
fun <http://lucumr.pocoo.org/2013/5/21/porting-to-python-3-redux/>`_.

If you can drop support for older Python versions, ``python-future`` leverages
some important features introduced into Python 2.7, such as
import hooks, and a comprehensive and well-tested set of backported
functionality, to allow you to write more idiomatic, maintainable code with
fewer compatibility hacks.


What is the relationship between ``python-future`` and ``python-modernize``?
----------------------------------------------------------------------------

``python-future`` contains, in addition to the ``future`` compatibility
package, a ``futurize`` script that is similar to ``python-modernize.py``
in intent and design. Both are based heavily on ``2to3``.

Whereas ``python-modernize`` converts Py2 code into a common subset of
Python 2 and 3, with ``six`` as a run-time dependency, ``futurize``
converts either Py2 or Py3 code into (almost) standard Python 3 code,
with ``future`` as a run-time dependency.

Because ``future`` provides more backported Py3 behaviours from ``six``,
the code resulting from ``futurize`` is more likely to work
identically on both Py3 and Py2 with less additional manual porting
effort.


Platform and version support
============================

.. _supported-versions:

Which versions of Python does ``python-future`` support?
--------------------------------------------------------

Python 2.7, and 3.4+ only.

Python 2.7 introduced many important forward-compatibility
features (such as import hooks, ``b'...'`` literals and ``__future__``
definitions) that greatly reduce the maintenance burden for single-source
Py2/3 compatible code. ``future`` leverages these features and aims to
close the remaining gap between Python 3 and 2.7.


Do you support Pypy?
~~~~~~~~~~~~~~~~~~~~

Yes, except for the standard library import hooks (currently). Feedback
and pull requests are welcome!


Do you support IronPython and/or Jython?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Not sure. This would be nice...


.. _support:

Support
=======

Is there a mailing list?
------------------------

Yes, please ask any questions on the `python-porting
<https://mail.python.org/mailman/listinfo/python-porting>`_ mailing list.


.. _contributing:

Contributing
============

Can I help?
-----------

Yes please :) We welcome bug reports, additional tests, pull requests,
and stories of either success or failure with using it. Help with the fixers
for the ``futurize`` script is particularly welcome.


Where is the repo?
------------------

`<https://github.com/PythonCharmers/python-future>`_.