### Navigation

- index
- modules |
- previous |
- Python-Future documentation »

# API Reference (in progress)

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.

- future.builtins Interface
- Backported types from Python 3
  - For more information:
  - range()
  - super()
  - round()
- future.standard_library Interface
  - Limitations
- future.utils Interface
- past.builtins Interface
- Forward-ported types from Python 2

## future.builtins Interface

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.

`future.builtins.``filter`

  alias of `ifilter`

`future.builtins.``map`

  alias of `imap`

`future.builtins.``zip`

  alias of `izip`

`future.builtins.``ascii`(object) → string

  Return the same as repr(). In Python 3.x, the repr() result will contain printable characters unescaped, while the ascii() result will have such characters backslash-escaped.

`future.builtins.``chr`()

  unichr(i) -> Unicode character

  Return a Unicode string of one character with ordinal i; 0 <= i <= 0x10ffff.

`future.builtins.``hex`(number) → string

  Return the hexadecimal representation of an integer or long integer.

`future.builtins.``input`()

  raw_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.

`future.builtins.``next`(iterator[, default])

  Return the next item from the iterator. If default is given and the iterator is exhausted, it is returned instead of raising StopIteration.

`future.builtins.``oct`(number) → string

  Return the octal representation of an integer or long integer.

`future.builtins.``open`()

  Open file and return a stream. Raise IOError upon failure.

  file is either a text or byte string giving the name (and the path if the file isn’t in the current working directory) of the file to be opened or an integer file descriptor of the file to be wrapped. (If a file descriptor is given, it is closed when the returned I/O object is closed, unless closefd is set to False.)

  mode is an optional string that specifies the mode in which the file is opened. It defaults to ‘r’ which means open for reading in text mode. Other common values are ‘w’ for writing (truncating the file if it already exists), and ‘a’ for appending (which on some Unix systems, means that all writes append to the end of the file regardless of the current seek position). In text mode, if encoding is not specified the encoding used is platform dependent. (For reading and writing raw bytes use binary mode and leave encoding unspecified.) The available modes are:

  Character | Meaning
  ‘r’ | open for reading (default)
  ‘w’ | open for writing, truncating the file first
  ‘a’ | open for writing, appending to the end of the file if it exists
  ‘b’ | binary mode
  ‘t’ | text mode (default)
  ‘+’ | open a disk file for updating (reading and writing)
  ‘U’ | universal newline mode (for backwards compatibility; unneeded for new code)

  The default mode is ‘rt’ (open for reading text). For binary random access, the mode ‘w+b’ opens and truncates the file to 0 bytes, while ‘r+b’ opens the file without truncation.

  Python distinguishes between files opened in binary and text modes, even when the underlying operating system doesn’t. Files opened in binary mode (appending ‘b’ to the mode argument) return contents as bytes objects without any decoding. In text mode (the default, or when ‘t’ is appended to the mode argument), the contents of the file are returned as strings, the bytes having been first decoded using a platform-dependent encoding or using the specified encoding if given.

  buffering is an optional integer used to set the buffering policy. Pass 0 to switch buffering off (only allowed in binary mode), 1 to select line buffering (only usable in text mode), and an integer > 1 to indicate the size of a fixed-size chunk buffer. When no buffering argument is given, the default buffering policy works as follows:

  - Binary files are buffered in fixed-size chunks; the size of the buffer is chosen using a heuristic trying to determine the underlying device’s “block size” and falling back on io.DEFAULT_BUFFER_SIZE. On many systems, the buffer will typically be 4096 or 8192 bytes long.
  - “Interactive” text files (files for which isatty() returns True) use line buffering. Other text files use the policy described above for binary files.

  encoding is the name of the encoding used to decode or encode the file. This should only be used in text mode. The default encoding is platform dependent, but any encoding supported by Python can be passed. See the codecs module for the list of supported encodings.

  errors is an optional string that specifies how encoding errors are to be handled—this argument should not be used in binary mode. Pass ‘strict’ to raise a ValueError exception if there is an encoding error (the default of None has the same effect), or pass ‘ignore’ to ignore errors. (Note that ignoring encoding errors can lead to data loss.) See the documentation for codecs.register for a list of the permitted encoding error strings.

  newline controls how universal newlines works (it only applies to text mode). It can be None, ‘’, ‘n’, ‘r’, and ‘rn’. It works as follows:

  - On input, if newline is None, universal newlines mode is enabled. Lines in the input can end in ‘n’, ‘r’, or ‘rn’, and these are translated into ‘n’ before being returned to the caller. If it is ‘’, universal newline mode is enabled, but line endings are returned to the caller untranslated. If it has any of the other legal values, input lines are only terminated by the given string, and the line ending is returned to the caller untranslated.
  - On output, if newline is None, any ‘n’ characters written are translated to the system default line separator, os.linesep. If newline is ‘’, no translation takes place. If newline is any of the other legal values, any ‘n’ characters written are translated to the given string.

  If closefd is False, the underlying file descriptor will be kept open when the file is closed. This does not work when a file name is given and must be True in that case.

  open() returns a file object whose type depends on the mode, and through which the standard file operations such as reading and writing are performed. When open() is used to open a file in a text mode (‘w’, ‘r’, ‘wt’, ‘rt’, etc.), it returns a TextIOWrapper. When used to open a file in a binary mode, the returned class varies: in read binary mode, it returns a BufferedReader; in write binary and append binary modes, it returns a BufferedWriter, and in read/write mode, it returns a BufferedRandom.

  It is also possible to use a string or bytearray as a file for both reading and writing. For strings StringIO can be used like a file opened in a text mode, and for bytes a BytesIO can be used like a file opened in a binary mode.

`future.builtins.``pow`(x, y[, z]) → number

  With two arguments, equivalent to x**y. With three arguments, equivalent to (x**y) % z, but may be more efficient (e.g. for ints).

`future.builtins.``round`(number, ndigits=None)

  See Python 3 documentation: uses Banker’s Rounding.

  Delegates to the __round__ method if for some reason this exists.

  If not, rounds a number to a given precision in decimal digits (default 0 digits). This returns an int when called with one argument, otherwise the same type as the number. ndigits may be negative.

  See the test_round method in future/tests/test_builtins.py for examples.

`future.builtins.``super`(typ=<object object at 0x7fbd1899d830>, type_or_obj=<object object at 0x7fbd1899d830>, framedepth=1)

  Like builtin super(), but capable of magic.

  This acts just like the builtin super() function, but if called without any arguments it attempts to infer them at runtime.

`future.builtins.``bytes`

  alias of `newbytes`

`future.builtins.``dict`

  alias of `newdict`

`future.builtins.``int`

  alias of `newint`

`future.builtins.``list`

  alias of `newlist`

`future.builtins.``object`

  alias of `newobject`

`future.builtins.``range`

  alias of `newrange`

`future.builtins.``str`

  alias of `newstr`

## Backported types from Python 3

This module contains backports the data types that were significantly changed in the transition from Python 2 to Python 3.

- an implementation of Python 3’s bytes object (pure Python subclass of Python 2’s builtin 8-bit str type)
- an implementation of Python 3’s str object (pure Python subclass of Python 2’s builtin unicode type)
- a backport of the range iterator from Py3 with slicing support

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

### For more information:

- future.types.newbytes
- future.types.newdict
- future.types.newint
- future.types.newobject
- future.types.newrange
- future.types.newstr

#### Notes

### range()

`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()

`super()` is based on Ryan Kelly’s `magicsuper` module. See the `newsuper` module docstring for more details.

### round()

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.

class `future.types.``newbytes`

  A backport of the Python 3 bytes object to Py2

  `decode`(encoding='utf-8', errors='strict')

    Returns a newstr (i.e. unicode subclass)

    Decode B using the codec registered for encoding. Default encoding is ‘utf-8’. errors may be given to set a different error handling scheme. Default is ‘strict’ meaning that encoding errors raise a UnicodeDecodeError. Other possible values are ‘ignore’ and ‘replace’ as well as any other name registered with codecs.register_error that is able to handle UnicodeDecodeErrors.

  `index`(*args, **kwargs)

    Returns index of sub in bytes. Raises ValueError if byte is not in bytes and TypeError if can’t be converted bytes or its length is not 1.

  `lower`() → copy of b

    Return a copy of b with all ASCII characters converted to lowercase.

  classmethod `maketrans`(frm, to) → translation table

    Return a translation table (a bytes object of length 256) suitable for use in the bytes or bytearray translate method where each byte in frm is mapped to the byte at the same position in to. The bytes objects frm and to must be of the same length.

  `rindex`(sub[, start[, end]]) → int

    Like S.rfind() but raise ValueError when the substring is not found.

  `rstrip`(*args, **kwargs)

    Strip trailing bytes contained in the argument. If the argument is omitted, strip trailing ASCII whitespace.

  `splitlines`([keepends]) → list of lines

    Return a list of the lines in B, breaking at line boundaries. Line breaks are not included in the resulting list unless keepends is given and true.

  `strip`(*args, **kwargs)

    Strip leading and trailing bytes contained in the argument. If the argument is omitted, strip trailing ASCII whitespace.

  `upper`() → copy of b

    Return a copy of b with all ASCII characters converted to uppercase.

class `future.types.``newdict`

  A backport of the Python 3 dict object to Py2

  `items`()
    On Python 2.7+:
      D.items() -> a set-like object providing a view on D’s items
    On Python 2.6:
      D.items() -> an iterator over D’s items
  `keys`()
    On Python 2.7+:
      D.keys() -> a set-like object providing a view on D’s keys
    On Python 2.6:
      D.keys() -> an iterator over D’s keys
  `values`()
    On Python 2.7+:
      D.values() -> a set-like object providing a view on D’s values
    On Python 2.6:
      D.values() -> an iterator over D’s values

class `future.types.``newint`

  A backport of the Python 3 int object to Py2

  classmethod `from_bytes`(mybytes, byteorder='big', signed=False)

    Return the integer represented by the given array of bytes.

    The mybytes argument must either support the buffer protocol or be an iterable object producing bytes. Bytes and bytearray are examples of built-in objects that support the buffer protocol.

    The byteorder argument determines the byte order used to represent the integer. If byteorder is ‘big’, the most significant byte is at the beginning of the byte array. If byteorder is ‘little’, the most significant byte is at the end of the byte array. To request the native byte order of the host system, use `sys.byteorder’ as the byte order value.

    The signed keyword-only argument indicates whether two’s complement is used to represent the integer.

  `to_bytes`(length, byteorder='big', signed=False)

    Return an array of bytes representing an integer.

    The integer is represented using length bytes. An OverflowError is raised if the integer is not representable with the given number of bytes.

    The byteorder argument determines the byte order used to represent the integer. If byteorder is ‘big’, the most significant byte is at the beginning of the byte array. If byteorder is ‘little’, the most significant byte is at the end of the byte array. To request the native byte order of the host system, use `sys.byteorder’ as the byte order value.

    The signed keyword-only argument determines whether two’s complement is used to represent the integer. If signed is False and a negative integer is given, an OverflowError is raised.

class `future.types.``newlist`

  A backport of the Python 3 list object to Py2

  `clear`() → None -- remove all items from L
  `copy`() → list -- a shallow copy of L

class `future.types.``newrange`(*args)

  Pure-Python backport of Python 3’s range object. See the CPython documentation for details:

  `count`(value)

    Return the number of ocurrences of integer value in the sequence this range represents.

  `index`(value)

    Return the 0-based position of integer value in the sequence this range represents.

class `future.types.``newstr`

  A backport of the Python 3 str object to Py2

  `encode`(encoding='utf-8', errors='strict')

    Returns bytes

    Encode S using the codec registered for encoding. Default encoding is ‘utf-8’. errors may be given to set a different error handling scheme. Default is ‘strict’ meaning that encoding errors raise a UnicodeEncodeError. Other possible values are ‘ignore’, ‘replace’ and ‘xmlcharrefreplace’ as well as any other name registered with codecs.register_error that can handle UnicodeEncodeErrors.

  `index`(*args, **kwargs)

    Like newstr.find() but raise ValueError when the substring is not found.

  static `maketrans`(x, y=None, z=None)

    Return a translation table usable for str.translate().

    If there is only one argument, it must be a dictionary mapping Unicode ordinals (integers) or characters to Unicode ordinals, strings or None. Character keys will be then converted to ordinals. If there are two arguments, they must be strings of equal length, and in the resulting dictionary, each character in x will be mapped to the character at the same position in y. If there is a third argument, it must be a string, whose characters will be mapped to None in the result.

  `splitlines`(keepends=False) → list of strings

    Return a list of the lines in S, breaking at line boundaries. Line breaks are not included in the resulting list unless keepends is given and true.

  `translate`(table) → str

    Return a copy of the string S, where all characters have been mapped through the given translation table, which must be a mapping of Unicode ordinals to Unicode ordinals, strings, or None. Unmapped characters are left untouched. Characters mapped to None are deleted.

## future.standard_library Interface

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

### Limitations

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

class `future.standard_library.``RenameImport`(old_to_new)

  A class for import hooks mapping Py3 module names etc. to the Py2 equivalents.

`future.standard_library.``cache_py2_modules`()

  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`()

  Returns True if the import hooks are installed, False if not.

`future.standard_library.``disable_hooks`()

  Deprecated. Use remove_hooks() instead. This will be removed by `future` v1.0.

`future.standard_library.``enable_hooks`()

  Deprecated. Use install_hooks() instead. This will be removed by `future` v1.0.

class `future.standard_library.``exclude_local_folder_imports`(*args)

  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)
  Example use:

        >>> 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`.

class `future.standard_library.``hooks`

  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)

  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.

  Example use:

        >>> http = import_('http.client')
        >>> http = import_('http.server')
        >>> urllib = import_('urllib.request')

  Then:

        >>> conn = http.client.HTTPConnection(...)
        >>> response = urllib.request.urlopen('http://mywebsite.com')
        >>> # etc.

  Use as follows:

        >>> 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`()

  Monkey-patches the standard library in Py2.6/7 to provide aliases for better Py3 compatibility.

`future.standard_library.``install_hooks`()

  This function installs the future.standard_library import hook into sys.meta_path.

`future.standard_library.``is_py2_stdlib_module`(m)

  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)

  This function removes the import hook from sys.meta_path.

`future.standard_library.``restore_sys_modules`(scrubbed)

  Add any previously scrubbed modules back to the sys.modules cache, but only if it’s safe to do so.

`future.standard_library.``scrub_future_sys_modules`()

  Deprecated.

`future.standard_library.``scrub_py2_sys_modules`()

  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 ...)

class `future.standard_library.``suspend_hooks`

  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.

## future.utils Interface

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` and `bytes_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')

  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)

  Bind a method to class, python 2 and python 3 compatible.

  cls : type
    class to receive bound method
  name : basestring
    name of method on class instance
  func : function
    function to be bound as method

  None

`future.utils.``exec_`(code, globs=None, locs=None)

  Execute code in a namespace.

`future.utils.``implements_iterator`(cls)

  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)

  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)
  Deprecated. Use::

        >>> isinstance(obj, bytes)

  after this import:

        >>> from future.builtins import bytes

`future.utils.``isidentifier`(s, dotted=False)

  A function equivalent to the str.isidentifier method on Py3

`future.utils.``isint`(obj)

  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)

  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)
  Deprecated. Use::

        >>> isinstance(obj, str)

  after this import:

        >>> from future.builtins import str

`future.utils.``iteritems`(obj, **kwargs)

  Use this only if compatibility with Python versions before 2.7 is required. Otherwise, prefer viewitems().

`future.utils.``iterkeys`(obj, **kwargs)

  Use this only if compatibility with Python versions before 2.7 is required. Otherwise, prefer viewkeys().

`future.utils.``itervalues`(obj, **kwargs)

  Use this only if compatibility with Python versions before 2.7 is required. Otherwise, prefer viewvalues().

`future.utils.``lfilter`()

  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.

`future.utils.``lmap`()

  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).

`future.utils.``lrange`()

  range(stop) -> list of integers range(start, stop[, step]) -> list of integers

  Return a list containing an arithmetic progression of integers. range(i, j) returns [i, i+1, i+2, ..., j-1]; start (!) defaults to 0. When step is given, it specifies the increment (or decrement). For example, range(4) returns [0, 1, 2, 3]. The end point is omitted! These are exactly the valid indices for a list of 4 elements.

`future.utils.``lzip`()

  zip(seq1 [, seq2 [...]]) -> [(seq1[0], seq2[0] ...), (...)]

  Return a list of tuples, where each tuple contains the i-th element from each of the argument sequences. The returned list is truncated in length to the length of the shortest argument sequence.

`future.utils.``native`(obj)

  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 `str`

`future.utils.``native_str`

  alias of `str`

`future.utils.``native_str_to_bytes`(s, encoding=None)

  On Py3, returns an encoded string. On Py2, returns a newbytes type, ignoring the `encoding` argument.

`future.utils.``old_div`(a, b)

  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)

  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: \u5b54\u5b50'

      >>> 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_with_traceback`(exc, traceback=Ellipsis)

  Raise exception with existing traceback. If traceback is not passed, uses sys.exc_info() to get traceback.

`future.utils.``text_to_native_str`(t, encoding='ascii')

  Use this to create a Py2 native string when “from __future__ import unicode_literals” is in effect.

`future.utils.``tobytes`(s)

  Encodes to latin-1 (where the first 256 chars are the same as ASCII.)

`future.utils.``viewitems`(obj, **kwargs)

  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)

  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)

  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)

  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.

## past.builtins Interface

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:

1. Implementations of these builtin functions which have no equivalent on Py3:

- apply
- chr
- cmp
- execfile

2. Aliases:

- intern <- sys.intern
- raw_input <- input
- reduce <- functools.reduce
- reload <- imp.reload
- unichr <- chr
- unicode <- str
- xrange <- range

3. List-producing versions of the corresponding Python 3 iterator-producing functions:

- filter
- map
- range
- zip

4. Forward-ported Py2 types:

- basestring
- dict
- str
- long
- unicode

## Forward-ported types from Python 2

Forward-ports of types from Python 2 for use with Python 3:

- `basestring`: equivalent to `(str, bytes)` in `isinstance` checks
- `dict`: with list-producing .keys() etc. methods
- `str`: bytes-like, but iterating over them doesn’t product integers
- `long`: alias of Py3 int with `L` suffix in the `repr`
- `unicode`: alias of Py3 str with `u` prefix in the `repr`

### Navigation

- index
- modules |
- previous |
- Python-Future documentation »