Python-Future

1.0.0 · maintenance · verified Sat Mar 28

future is the missing compatibility layer between Python 2 and Python 3. It allows you to use a single, clean Python 3.x-compatible codebase to support both Python 2 and Python 3 with minimal overhead. It provides `future` and `past` packages with backports and forward ports of features from Python 3 and 2, and includes `futurize` and `pasteurize` scripts for automated code conversion. The latest version is 1.0.0, and while feature development is complete, it supports Python 3.12.

Warnings

breaking Python 2 reached its end-of-life in 2020. While `python-future` facilitates compatibility, relying on it for actively maintained Python 2 codebases is increasingly risky due to lack of Python 2 security updates and ecosystem support.
Fix: Prioritize full migration to Python 3. `python-future` should be seen as a stepping stone or a compatibility layer for transitioning legacy code, not a long-term solution for Python 2 development.
gotcha The `python-future` project is declared 'done' and is not recommended for new Python 3 projects. While it receives critical compatibility updates (e.g., Python 3.12 support), its primary purpose as a Python 2/3 compatibility layer means new feature development is complete. It should not be adopted as a dependency for greenfield Python 3 development.
Fix: For new Python 3 projects, write idiomatic Python 3 code directly. If compatibility with multiple Python 3 versions is needed, leverage `__future__` imports (native to Python) and `six` if strictly necessary for very old Python 3 versions, but prefer modern Python features.
gotcha The `install_aliases()` function globally modifies `sys.modules` on Python 2 to map Python 3 standard library names. This can lead to unexpected behavior or conflicts if other libraries or custom import hooks make different assumptions about the module layout.
Fix: Use `install_aliases()` early in your application's startup. Be aware of potential conflicts, especially when mixing with other compatibility layers or dynamically loading modules. Consider explicit `future.moves` imports for specific items to limit global impact if issues arise.
deprecated The `past.translation` module, which offers experimental automatic translation of Python 2 modules to Python 3 upon import, is in 'alpha' status and may be unstable or imperfect. Relying on it for critical functionality is not recommended.
Fix: Prefer using `futurize` (for Py2 to Py2/3) or `pasteurize` (for Py3 to Py2/3) scripts for static code conversion. If `past.translation` is used, ensure thorough testing and be prepared for potential runtime issues.
gotcha HTTPS support with the `http`-based backports within `future` is limited on Python 2.x due to significant changes in SSL support in Python 3.x. Direct `http`-based backports might fail for HTTPS connections.
Fix: For HTTPS support on Python 2, especially within `urllib`, the documentation recommends using `from future.moves.urllib.request import urlopen` or using a dedicated HTTP library like `requests` that handles SSL/TLS more robustly.

Install

pip install future Install stable version
pip install future # Requires Python >=2.6, !=3.0.*, !=3.1.*, !=3.2.* Python compatibility

Imports

Builtins
```
from builtins import (bytes, dict, int, list, object, range, str,
                       ascii, chr, hex, input, next, oct, open, pow,
                       round, super, filter, map, zip)
```
While `future.builtins` exists, the recommended pattern for Python 2/3 compatibility is `from builtins import ...` as it directly maps to Python 3 builtins on Py2 and has no effect on Py3. The wildcard `*` is shown in some examples for brevity but explicit imports are generally preferred.
StandardLibraryAliases
```
from future.standard_library import install_aliases
install_aliases()
```
This function makes Python 3-style standard library imports (e.g., `urllib.parse`, `queue`) available on Python 2 by modifying `sys.modules` and other mechanisms.
__future__ imports
```
from __future__ import (absolute_import, division, print_function, unicode_literals)
```
These are built-in Python future statements crucial for enabling Python 3 behavior in Python 2. `future`'s tools and runtime patches complement these.
past.builtins
```
from past.builtins import basestring, unicode
```
Provides Python 2-specific builtins (like `basestring` or `unicode` type) on Python 3 for modules that explicitly need them, typically during module-by-module migration.

Quickstart

To write new code compatible with both Python 2 (2.6+) and Python 3 (3.3+), start each module with the essential `__future__` imports and `from builtins import *`. Then call `install_aliases()` to ensure standard library modules are correctly mapped. This allows writing predominantly Python 3-style code that runs on both versions.

from __future__ import (absolute_import, division, print_function, unicode_literals)
from builtins import *
from future.standard_library import install_aliases
install_aliases()

# Now write Python 3 code that runs on both Py2 and Py3
print("Hello, world!")

def divide(a, b):
    return a / b # Will use float division even on Python 2

my_dict = {'a': 1, 'b': 2}
print(list(my_dict.keys())) # dict.keys() returns a view (iterable) on Py2 with future installed

# Example of Python 3 library name working on Py2
import urllib.request
print(urllib.request.urlopen('http://example.com').getcode())

view raw JSON →