NOTE: This page is still a work in progress... We need to go through our docstrings and make them sphinx-compliant, and figure out how to improve formatting with the sphinx-bootstrap-theme plugin. Pull requests would be very welcome.
A module that brings in equivalents of the new and modified Python 3 builtins into Py2. Has no effect on Py3.
See the docs here
(docs/what-else.rst
) for more information.
This module contains backports the data types that were significantly changed in the transition from Python 2 to Python 3.
It is used as follows:
from __future__ import division, absolute_import, print_function
from builtins import bytes, dict, int, range, str
to bring in the new semantics for these functions from Python 3. And then, for example:
b = bytes(b'ABCD')
assert list(b) == [65, 66, 67, 68]
assert repr(b) == "b'ABCD'"
assert [65, 66] in b
# These raise TypeErrors:
# b + u'EFGH'
# b.split(u'B')
# bytes(b',').join([u'Fred', u'Bill'])
s = str(u'ABCD')
# These raise TypeErrors:
# s.join([b'Fred', b'Bill'])
# s.startswith(b'A')
# b'B' in s
# s.find(b'A')
# s.replace(u'A', b'a')
# This raises an AttributeError:
# s.decode('utf-8')
assert repr(s) == 'ABCD' # consistent repr with Py3 (no u prefix)
for i in range(10**11)[:10]:
pass
and:
class VerboseList(list):
def append(self, item):
print('Adding an item')
super().append(item) # new simpler super() function
range
is a custom class that backports the slicing behaviour from
Python 3 (based on the xrange
module by Dan Crosta). See the
newrange
module docstring for more details.
super()
is based on Ryan Kelly’s magicsuper
module. See the
newsuper
module docstring for more details.
Python 3 modifies the behaviour of round()
to use “Banker’s Rounding”.
See http://stackoverflow.com/a/10825998. See the newround
module
docstring for more details.
Python 3 reorganized the standard library (PEP 3108). This module exposes several standard library modules to Python 2 under their new Python 3 names.
It is designed to be used as follows:
from future import standard_library
standard_library.install_aliases()
And then these normal Py3 imports work on both Py3 and Py2:
import builtins
import configparser
import copyreg
import queue
import reprlib
import socketserver
import winreg # on Windows only
import test.support
import html, html.parser, html.entites
import http, http.client, http.server
import http.cookies, http.cookiejar
import urllib.parse, urllib.request, urllib.response, urllib.error, urllib.robotparser
import xmlrpc.client, xmlrpc.server
import _thread
import _dummy_thread
import _markupbase
from itertools import filterfalse, zip_longest
from sys import intern
from collections import UserDict, UserList, UserString
from collections import OrderedDict, Counter # even on Py2.6
from subprocess import getoutput, getstatusoutput
from subprocess import check_output # even on Py2.6
(The renamed modules and functions are still available under their old names on Python 2.)
This is a cleaner alternative to this idiom (see http://docs.pythonsprints.com/python3_porting/py-porting.html):
try:
import queue
except ImportError:
import Queue as queue
We don’t currently support these modules, but would like to:
import dbm
import dbm.dumb
import dbm.gnu
import collections.abc # on Py33
import pickle # should (optionally) bring in cPickle on Python 2
future.standard_library.
RenameImport
(old_to_new)[source]¶A class for import hooks mapping Py3 module names etc. to the Py2 equivalents.
future.standard_library.
cache_py2_modules
()[source]¶Currently this function is unneeded, as we are not attempting to provide import hooks for modules with ambiguous names: email, urllib, pickle.
future.standard_library.
detect_hooks
()[source]¶Returns True if the import hooks are installed, False if not.
future.standard_library.
disable_hooks
()[source]¶Deprecated. Use remove_hooks() instead. This will be removed by
future
v1.0.
future.standard_library.
enable_hooks
()[source]¶Deprecated. Use install_hooks() instead. This will be removed by
future
v1.0.
future.standard_library.
exclude_local_folder_imports
(*args)[source]¶A context-manager that prevents standard library modules like configparser from being imported from the local python-future source folder on Py3.
(The presence of a configparser folder would otherwise prevent setuptools from running on Py3.)
future.standard_library.
from_import
(module_name, *symbol_names, **kwargs)[source]¶>>> HTTPConnection = from_import('http.client', 'HTTPConnection')
>>> HTTPServer = from_import('http.server', 'HTTPServer')
>>> urlopen, urlparse = from_import('urllib.request', 'urlopen', 'urlparse')
Equivalent to this on Py3:
>>> from module_name import symbol_names[0], symbol_names[1], ...
and this on Py2:
>>> from future.moves.module_name import symbol_names[0], ...
or:
>>> from future.backports.module_name import symbol_names[0], ...
except that it also handles dotted module names such as http.client
.
future.standard_library.
hooks
[source]¶Acts as a context manager. Saves the state of sys.modules and restores it after the ‘with’ block.
Use like this:
>>> from future import standard_library
>>> with standard_library.hooks():
... import http.client
>>> import requests
For this to work, http.client will be scrubbed from sys.modules after the ‘with’ block. That way the modules imported in the ‘with’ block will continue to be accessible in the current namespace but not from any imported modules (like requests).
future.standard_library.
import_
(module_name, backport=False)[source]¶Pass a (potentially dotted) module name of a Python 3 standard library module. This function imports the module compatibly on Py2 and Py3 and returns the top-level module.
>>> http = import_('http.client')
>>> http = import_('http.server')
>>> urllib = import_('urllib.request')
>>> conn = http.client.HTTPConnection(...)
>>> response = urllib.request.urlopen('http://mywebsite.com')
>>> # etc.
>>> package_name = import_(module_name)
On Py3, equivalent to this:
>>> import module_name
On Py2, equivalent to this if backport=False:
>>> from future.moves import module_name
or to this if backport=True:
>>> from future.backports import module_name
except that it also handles dotted module names such as http.client
The effect then is like this:
>>> from future.backports import module
>>> from future.backports.module import submodule
>>> module.submodule = submodule
Note that this would be a SyntaxError in Python:
>>> from future.backports import http.client
future.standard_library.
install_aliases
()[source]¶Monkey-patches the standard library in Py2.6/7 to provide aliases for better Py3 compatibility.
future.standard_library.
install_hooks
()[source]¶This function installs the future.standard_library import hook into sys.meta_path.
future.standard_library.
is_py2_stdlib_module
(m)[source]¶Tries to infer whether the module m is from the Python 2 standard library. This may not be reliable on all systems.
future.standard_library.
remove_hooks
(scrub_sys_modules=False)[source]¶This function removes the import hook from sys.meta_path.
future.standard_library.
restore_sys_modules
(scrubbed)[source]¶Add any previously scrubbed modules back to the sys.modules cache, but only if it’s safe to do so.
future.standard_library.
scrub_py2_sys_modules
()[source]¶Removes any Python 2 standard library modules from sys.modules
that
would interfere with Py3-style imports using import hooks. Examples are
modules with the same names (like urllib or email).
(Note that currently import hooks are disabled for modules like these with ambiguous names anyway ...)
future.standard_library.
suspend_hooks
[source]¶Acts as a context manager. Use like this:
>>> from future import standard_library
>>> standard_library.install_hooks()
>>> import http.client
>>> # ...
>>> with standard_library.suspend_hooks():
>>> import requests # incompatible with ``future``'s standard library hooks
If the hooks were disabled before the context, they are not installed when the context is left.
A selection of cross-compatible functions for Python 2 and 3.
This module exports useful functions for 2/3 compatible code:
bind_method: binds functions to classes
native_str_to_bytes
andbytes_to_native_str
native_str
: always equal to the native platform string object (because this may be shadowed by imports from future.builtins)lists: lrange(), lmap(), lzip(), lfilter()
- iterable method compatibility:
- iteritems, iterkeys, itervalues
- viewitems, viewkeys, viewvalues
These use the original method if available, otherwise they use items, keys, values.
types:
- text_type: unicode in Python 2, str in Python 3
- binary_type: str in Python 2, bythes in Python 3
- string_types: basestring in Python 2, str in Python 3
- bchr(c):
Take an integer and make a 1-character byte string
- bord(c)
Take the result of indexing on a byte string and make an integer
- tobytes(s)
Take a text string, a byte string, or a sequence of characters taken from a byte string, and make a byte string.
raise_from()
raise_with_traceback()
This module also defines these decorators:
python_2_unicode_compatible
with_metaclass
implements_iterator
Some of the functions in this module come from the following sources:
- Jinja2 (BSD licensed: see https://github.com/mitsuhiko/jinja2/blob/master/LICENSE)
- Pandas compatibility module pandas.compat
- six.py by Benjamin Peterson
- Django
future.utils.
as_native_str
(encoding='utf-8')[source]¶A decorator to turn a function or method call that returns text, i.e. unicode, into one that returns a native platform str.
Use it as a decorator like this:
from __future__ import unicode_literals
class MyClass(object):
@as_native_str(encoding='ascii')
def __repr__(self):
return next(self._iter).upper()
future.utils.
bind_method
(cls, name, func)[source]¶Bind a method to class, python 2 and python 3 compatible.
None
future.utils.
exec_
()¶exec(object[, globals[, locals]])
Read and execute code from an object, which can be a string or a code object. The globals and locals are dictionaries, defaulting to the current globals and locals. If only globals is given, locals defaults to it.
future.utils.
implements_iterator
(cls)[source]¶From jinja2/_compat.py. License: BSD.
Use as a decorator like this:
@implements_iterator
class UppercasingIterator(object):
def __init__(self, iterable):
self._iter = iter(iterable)
def __iter__(self):
return self
def __next__(self):
return next(self._iter).upper()
future.utils.
is_new_style
(cls)[source]¶Python 2.7 has both new-style and old-style classes. Old-style classes can be pesky in some circumstances, such as when using inheritance. Use this function to test for whether a class is new-style. (Python 3 only has new-style classes.)
future.utils.
isbytes
(obj)[source]¶>>> isinstance(obj, bytes)
>>> from future.builtins import bytes
future.utils.
isidentifier
(s, dotted=False)[source]¶A function equivalent to the str.isidentifier method on Py3
future.utils.
isint
(obj)[source]¶Deprecated. Tests whether an object is a Py3 int
or either a Py2 int
or
long
.
Instead of using this function, you can use:
>>> from future.builtins import int
>>> isinstance(obj, int)
The following idiom is equivalent:
>>> from numbers import Integral
>>> isinstance(obj, Integral)
future.utils.
isnewbytes
(obj)[source]¶Equivalent to the result of isinstance(obj, newbytes)
were
__instancecheck__
not overridden on the newbytes subclass. In
other words, it is REALLY a newbytes instance, not a Py2 native str
object?
future.utils.
istext
(obj)[source]¶>>> isinstance(obj, str)
>>> from future.builtins import str
future.utils.
iteritems
(obj, **kwargs)[source]¶Use this only if compatibility with Python versions before 2.7 is required. Otherwise, prefer viewitems().
future.utils.
iterkeys
(obj, **kwargs)[source]¶Use this only if compatibility with Python versions before 2.7 is required. Otherwise, prefer viewkeys().
future.utils.
itervalues
(obj, **kwargs)[source]¶Use this only if compatibility with Python versions before 2.7 is required. Otherwise, prefer viewvalues().
future.utils.
native
(obj)[source]¶On Py3, this is a no-op: native(obj) -> obj
On Py2, returns the corresponding native Py2 types that are superclasses for backported objects from Py3:
>>> from builtins import str, bytes, int
>>> native(str(u'ABC'))
u'ABC'
>>> type(native(str(u'ABC')))
unicode
>>> native(bytes(b'ABC'))
b'ABC'
>>> type(native(bytes(b'ABC')))
bytes
>>> native(int(10**20))
100000000000000000000L
>>> type(native(int(10**20)))
long
Existing native types on Py2 will be returned unchanged:
>>> type(native(u'ABC'))
unicode
future.utils.
native_bytes
¶alias of bytes
future.utils.
native_str_to_bytes
(s, encoding='utf-8')[source]¶On Py3, returns an encoded string.
On Py2, returns a newbytes type, ignoring the encoding
argument.
future.utils.
old_div
(a, b)[source]¶DEPRECATED: import old_div
from past.utils
instead.
Equivalent to a / b
on Python 2 without from __future__ import
division
.
TODO: generalize this to other objects (like arrays etc.)
future.utils.
python_2_unicode_compatible
(cls)[source]¶A decorator that defines __unicode__ and __str__ methods under Python 2. Under Python 3, this decorator is a no-op.
To support Python 2 and 3 with a single code base, define a __str__ method returning unicode text and apply this decorator to the class, like this:
>>> from future.utils import python_2_unicode_compatible
>>> @python_2_unicode_compatible
... class MyClass(object):
... def __str__(self):
... return u'Unicode string: 孔子'
>>> a = MyClass()
Then, after this import:
>>> from future.builtins import str
the following is True
on both Python 3 and 2:
>>> str(a) == a.encode('utf-8').decode('utf-8')
True
and, on a Unicode-enabled terminal with the right fonts, these both print the Chinese characters for Confucius:
>>> print(a)
>>> print(str(a))
The implementation comes from django.utils.encoding.
future.utils.
raise_
(tp, value=None, tb=None)[source]¶A function that matches the Python 2.x raise
statement. This
allows re-raising exceptions with the cls value and traceback on
Python 2 and 3.
future.utils.
raise_with_traceback
(exc, traceback=Ellipsis)[source]¶Raise exception with existing traceback. If traceback is not passed, uses sys.exc_info() to get traceback.
future.utils.
reraise
(tp, value=None, tb=None)¶A function that matches the Python 2.x raise
statement. This
allows re-raising exceptions with the cls value and traceback on
Python 2 and 3.
future.utils.
tobytes
(s)[source]¶Encodes to latin-1 (where the first 256 chars are the same as ASCII.)
future.utils.
viewitems
(obj, **kwargs)[source]¶Function for iterating over dictionary items with the same set-like behaviour on Py2.7 as on Py3.
Passes kwargs to method.
future.utils.
viewkeys
(obj, **kwargs)[source]¶Function for iterating over dictionary keys with the same set-like behaviour on Py2.7 as on Py3.
Passes kwargs to method.
future.utils.
viewvalues
(obj, **kwargs)[source]¶Function for iterating over dictionary values with the same set-like behaviour on Py2.7 as on Py3.
Passes kwargs to method.
future.utils.
with_metaclass
(meta, *bases)[source]¶Function from jinja2/_compat.py. License: BSD.
Use it like this:
class BaseForm(object):
pass
class FormType(type):
pass
class Form(with_metaclass(FormType, BaseForm)):
pass
This requires a bit of explanation: the basic idea is to make a dummy metaclass for one level of class instantiation that replaces itself with the actual metaclass. Because of internal type checks we also need to make sure that we downgrade the custom metaclass for one level to something closer to type (that’s why __call__ and __init__ comes back from type etc.).
This has the advantage over six.with_metaclass of not introducing dummy classes into the final MRO.
A resurrection of some old functions from Python 2 for use in Python 3. These should be used sparingly, to help with porting efforts, since code using them is no longer standard Python 3 code.
This module provides the following:
past.builtins.
filter
(function or None, sequence) → list, tuple, or string¶Return those items of sequence for which function(item) is true. If function is None, return the items that are true. If sequence is a tuple or string, return the same type, else return a list.
past.builtins.
map
(function, sequence[, sequence, ...]) → list¶Return a list of the results of applying the function to the items of the argument sequence(s). If more than one sequence is given, the function is called with an argument list consisting of the corresponding item of each sequence, substituting None for missing values when not all sequences have the same length. If the function is None, return a list of the items of the sequence (or a list of tuples if more than one sequence).
Test cases: >>> oldmap(None, ‘hello world’) [‘h’, ‘e’, ‘l’, ‘l’, ‘o’, ‘ ‘, ‘w’, ‘o’, ‘r’, ‘l’, ‘d’]
>>> oldmap(None, range(4))
[0, 1, 2, 3]
More test cases are in past.tests.test_builtins.
past.builtins.
reduce
(function, sequence[, initial]) → value¶Apply a function of two arguments cumulatively to the items of a sequence, from left to right, so as to reduce the sequence to a single value. For example, reduce(lambda x, y: x+y, [1, 2, 3, 4, 5]) calculates ((((1+2)+3)+4)+5). If initial is present, it is placed before the items of the sequence in the calculation, and serves as a default when the sequence is empty.
past.builtins.
dict
¶alias of olddict
past.builtins.
str
¶alias of oldstr
past.builtins.
execfile
(filename, myglobals=None, mylocals=None)[source]¶Read and execute a Python script from a file in the given namespaces. The globals and locals are dictionaries, defaulting to the current globals and locals. If only globals is given, locals defaults to it.
past.builtins.
intern
(string) → string¶``Intern’’ the given string. This enters the string in the (global) table of interned strings whose purpose is to speed up dictionary lookups. Return the string itself or the previously interned string object with the same value.
past.builtins.
raw_input
()¶input([prompt]) -> string
Read a string from standard input. The trailing newline is stripped. If the user hits EOF (Unix: Ctl-D, Windows: Ctl-Z+Return), raise EOFError. On Unix, GNU readline is used if enabled. The prompt string, if given, is printed without a trailing newline before reading.
past.builtins.
reload
(module)[source]¶DEPRECATED
Reload the module and return it.
The module must have been successfully imported before.
past.builtins.
unichr
(i)¶Return a byte-string of one character with ordinal i; 0 <= i <= 256
past.builtins.
xrange
¶alias of range
Forward-ports of types from Python 2 for use with Python 3:
basestring
: equivalent to (str, bytes)
in isinstance
checksdict
: with list-producing .keys() etc. methodsstr
: bytes-like, but iterating over them doesn’t product integerslong
: alias of Py3 int with L
suffix in the repr
unicode
: alias of Py3 str with u
prefix in the repr
past.types.
olddict
[source]¶A backport of the Python 3 dict object to Py2
iteritems
()¶D.items() -> a set-like object providing a view on D’s items
iterkeys
()¶D.keys() -> a set-like object providing a view on D’s keys
itervalues
()¶D.values() -> an object providing a view on D’s values
viewitems
()¶D.items() -> a set-like object providing a view on D’s items
viewkeys
()¶D.keys() -> a set-like object providing a view on D’s keys
viewvalues
()¶D.values() -> an object providing a view on D’s values