<commit_before>future: clean single-source support for Python 3 and 2
======================================================

The ``future`` module helps run Python 3.x-compatible code under Python 2
with minimal code cruft.

The goal is to allow you to write clean, modern, forward-compatible
Python 3 code today and to run it with minimal effort under Python 2
alongside a Python 2 stack that may contain dependencies that have not
yet been ported to Python 3.

It is designed to be used as follows::

    from __future__ import (division, absolute_import, print_function,
                            unicode_literals)
    from future import *
    
followed by clean Python 3 code (with a few restrictions) that can run
unchanged on Python 2.7.

On Python 3, the ``from future import *`` line has no effect (i.e. no
namespace pollution.) On Python 2 it shadows builtins to provide the
Python 3 semantics. (See below for the explicit import form.)

After the imports, this code runs identically on Python 3 and 2::
    
    # New iterable range object with slicing support
    for i in range(10**11)[:10]:
        pass
    
    # Other common iterators: map, reduce, zip
    my_iter = zip(range(3), ['a', 'b', 'c'])
    assert my_iter != list(my_iter)
    
    # New simpler super() function:
    class VerboseList(list):
        def append(self, item):
            print('Adding an item')
            super().append(item)
    
    # These raise NameErrors:
    # apply(), cmp(), coerce(), reduce(), xrange(), etc.
    
    # This identity is restored. This is normally valid on Py3 and Py2, but
    # 'from __future__ import unicode_literals' breaks it on Py2:
    assert isinstance('happy', str)
    
    # The round() function behaves as it does in Python 3, using "Banker's
    # Rounding" to the nearest even last digit:
    assert round(0.1250, 2) == 0.12
    
    # input() is now safe (no eval()):
    name = input('What is your name? ')
    print('Hello ' + name)


``future`` also supports the standard library reorganization (PEP 3108)
via import hooks, allowing standard library modules to be accessed under
their Python 3 names and locations::
    
    from future import standard_library_renames
    
    import socketserver
    import queue
    import configparser
    # and other moved modules


If you prefer explicit imports, the explicit equivalent of the ``from
future import *`` line above is::
    
    from future.common_iterators import zip, map, filter
    from future.builtins import ascii, oct, hex, chr, int
    from future.modified_builtins import (range, super, round, input)
    from future.disable_obsolete_builtins import (apply, cmp, coerce,
            execfile, file, long, raw_input, reduce, reload, unicode,
            xrange, StandardError)
    from future.str_is_unicode import str

But please note that the API is still evolving rapidly.

See the docstrings for each of these modules for more info::

- future.standard_library_renames
- future.common_iterators
- future.builtins
- future.modified_builtins
- future.disable_obsolete_builtins
- future.str_as_unicode


Credits
-------
:Author:  <NAME>
:Sponsor: Python Charmers Pty Ltd, Australia, and Python Charmers Pte
          Ltd, Singapore. http://pythoncharmers.com
:Others:  The ``super()`` and ``range()`` functions are derived from Ryan
          Kelly's ``magicsuper`` module and <NAME>'s ``xrange``
          module. The ``python_2_unicode_compatible`` decorator is from
          ``django.utils.encoding``. The fix_metaclass 2to3 fixer (from
          Armin Ronacher's python-modernize) was authored by <NAME> and <NAME>.


FAQ
===


:Q: Why use this approach?

:A: Here are some quotes:
<commit_msg>Describe ``futurize`` and limitations in README<commit_after>future: clean single-source support for Python 3 and 2
======================================================

The ``future`` module helps run Python 3.x-compatible code under Python 2
with minimal code cruft.

The goal is to allow you to write clean, modern, forward-compatible
Python 3 code today and to run it with minimal effort under Python 2
alongside a Python 2 stack that may contain dependencies that have not
yet been ported to Python 3.

It is designed to be used as follows::

    from __future__ import (division, absolute_import, print_function,
                            unicode_literals)
    from future import *
    
followed by clean Python 3 code (with a few restrictions) that can run
unchanged on Python 2.7.

On Python 3, the ``from future import *`` line has no effect (i.e. no
namespace pollution.) On Python 2 it shadows builtins to provide the
Python 3 semantics. (See below for the explicit import form.)

After the imports, this code runs identically on Python 3 and 2::
    
    # New iterable range object with slicing support
    for i in range(10**11)[:10]:
        pass
    
    # Other common iterators: map, reduce, zip
    my_iter = zip(range(3), ['a', 'b', 'c'])
    assert my_iter != list(my_iter)
    
    # New simpler super() function:
    class VerboseList(list):
        def append(self, item):
            print('Adding an item')
            super().append(item)
    
    # These raise NameErrors:
    # apply(), cmp(), coerce(), reduce(), xrange(), etc.
    
    # This identity is restored. This is normally valid on Py3 and Py2, but
    # 'from __future__ import unicode_literals' breaks it on Py2:
    assert isinstance('happy', str)
    
    # The round() function behaves as it does in Python 3, using "Banker's
    # Rounding" to the nearest even last digit:
    assert round(0.1250, 2) == 0.12
    
    # input() is now safe (no eval()):
    name = input('What is your name? ')
    print('Hello ' + name)


``future`` also supports the standard library reorganization (PEP 3108)
via import hooks, allowing standard library modules to be accessed under
their Python 3 names and locations::
    
    from future import standard_library_renames
    
    import socketserver
    import queue
    import configparser
    # and other moved modules


If you prefer explicit imports, the explicit equivalent of the ``from
future import *`` line above is::
    
    from future.common_iterators import zip, map, filter
    from future.builtins import ascii, oct, hex, chr, int
    from future.modified_builtins import (range, super, round, input)
    from future.disable_obsolete_builtins import (apply, cmp, coerce,
            execfile, file, long, raw_input, reduce, reload, unicode,
            xrange, StandardError)
    from future.str_is_unicode import str

But please note that the API is still evolving rapidly.

See the docstrings for each of these modules for more info::

- future.standard_library_renames
- future.common_iterators
- future.builtins
- future.modified_builtins
- future.disable_obsolete_builtins
- future.str_as_unicode


Automatic conversion
====================

There is a script included called ``futurize.py`` to aid in making either
Python 2 code or Python 3 code compatible with both platforms using the
``future`` module. It is based on 2to3 and inspired by <NAME>'s
``modernize.py``.

For Python 2 code (the default), it runs the code through all the
appropriate 2to3 fixers to turn it into valid Python 3 code, and then
adds ``__future__`` and ``future`` package imports so that (hopefully)
the resulting code runs on Python 3 as well.

For Python 3 code (with ``--from3``), it merely adds ``__future__`` and
``future`` imports to the top of each module so that (with luck) the code
will run automatically on Python 2 as well.


Limitations
-----------
Python 3 code that causes SyntaxErrors on Python 2 is not handled by the
``futurize`` script (except for ``print_function``). This includes:

- Function arguments in Py3.3 like this: 
    def f(a, b, *, c='blah', d='blah'):
        ...

- ``yield ... from`` syntax for generators in Py3.3

- ``raise ... from`` syntax for exceptions. (This is simple to fix
  manually by creating a temporary variable.)

- And any code that requires standard library features from Python 3 that
  are not available in the modules of the same names in Python 2.
  A couple of significantly refactored modules have been backported,
  however, since this was an easier process using ``future`` than
  handling the complexity of the renames. These modules are:
  ``urllib``, ``html``, ``http``.


Credits
-------
:Author:  <NAME>
:Sponsor: Python Charmers Pty Ltd, Australia, and Python Charmers Pte
          Ltd, Singapore. http://pythoncharmers.com
:Others:  The ``super()`` and ``range()`` functions are derived from Ryan
          Kelly's ``magicsuper`` module and <NAME>'s ``xrange``
          module. The ``python_2_unicode_compatible`` decorator is from
          ``django.utils.encoding``. The fix_metaclass 2to3 fixer (from
          Ar<NAME>'s python-modernize) was authored by <NAME> and <NAME>.


FAQ
===


:Q: Why use this approach?

:A: Here are some quotes:

{'fraction_non_alphanumeric': 0.09882747068676717, 'fraction_numerical': 0.012060301507537688, 'mean_word_length': 3.3709126403123473, 'pattern_counts': {'":': 0, '<': 13, '<?xml version=': 0, '>': 13, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1002208', 'n_tokens_mistral': 2591, 'n_tokens_neox': 2432, 'n_words': 1118}