six / documentation / index.rst

Full commit

Six: Python 2 and 3 Compatibility Library

Six provides simple utilities for wrapping over differences between Python 2 and Python 3. It is intended to support codebases that work on both Python 2 and 3 without modification.

Six can be downloaded on PyPi. Its bug tracker and code hosting is on BitBucket.

The name, "six", comes from the fact that 2*3 equals 6. Why not addition? Multiplication is more powerful, and, anyway, "five" has already been snatched away.

Indices and tables

Package contents


Six provides constants that may differ between Python versions. Ones ending _types are mostly useful as the second argument to isinstance or issubclass.

Here's example usage of the module:

import six

def dispatch_types(value):
    if isinstance(value, six.integer_types):
    elif isinstance(value, six.class_types):
    elif isinstance(value, six.string_types):

Object model compatibility

Python 3 renamed the attributes of several intepreter data structures. The following accessors are available. Note that the recommended way to inspect functions and methods is the stdlib :mod:`py3:inspect` module.

A class for making portable iterators. The intention is that it be subclassed and subclasses provide a __next__ method. In Python 2, :class:`Iterator` has one method: next. It simply delegates to __next__. An alternate way to do this would be to simply alias next to __next__. However, this interacts badly with subclasses that override __next__. :class:`Iterator` is empty on Python 3. (In fact, it is just aliased to :class:`py3:object`.)

Syntax compatibility

These functions smooth over operations which have different syntaxes between Python 2 and 3.

Binary and text data

Python 3 enforces the distinction between byte strings and text strings far more rigoriously than Python 2 does; binary data cannot be automatically coerced to or from text data. six provides several functions to assist in classifying string data in all Python versions.


Since all Python versions 2.6 and after support the b prefix, :func:`b`, code without 2.5 support doesn't need :func:`b`.

Renamed modules and attributes compatibility

Python 3 reorganized the standard library and moved several functions to different modules. Six provides a consistent interface to them through the fake :mod:`six.moves` module. For example, to load the module for parsing HTML on Python 2 or 3, write:

from six.moves import html_parser

Similarly, to get the function to reload modules, which was moved from the builtin module to the imp module, use:

from six.moves import reload_module

For the most part, :mod:`six.moves` aliases are the names of the modules in Python 3. When the new Python 3 name is a package, the components of the name are separated by underscores. For example, html.parser becomes html_parser. In some cases where several modules have been combined, the Python 2 name is retained. This is so the appropiate modules can be found when running on Python 2. For example, BaseHTTPServer which is in http.server in Python 3 is aliased as BaseHTTPServer.

Some modules which had two implementations have been merged in Python 3. For example, cPickle no longer exists in Python 3; it was merged with pickle. In these cases, fetching the fast version will load the fast one on Python 2 and the merged module in Python 3.


The :mod:`py2:urllib`, :mod:`py2:urllib2`, and :mod:`py2:urlparse` modules have been combined in the :mod:`py3:urllib` package in Python 3. :mod:`six.moves` doesn't not support their renaming because their members have been mixed across several modules in that package.

Supported renames:

Name Python 2 name Python 3 name
builtins :mod:`py2:__builtin__` :mod:`py3:builtins`
configparser :mod:`py2:ConfigParser` :mod:`py3:configparser`
copyreg :mod:`py2:copy_reg` :mod:`py3:copyreg`
cPickle :mod:`py2:cPickle` :mod:`py3:pickle`
cStringIO :func:`py2:cStringIO.StringIO` :class:`py3:io.StringIO`
filter :func:`py2:itertools.ifilter` :func:`py3:filter`
http_cookiejar :mod:`py2:cookielib` :mod:`py3:http.cookiejar`
http_cookies :mod:`py2:Cookie` :mod:`py3:http.cookies`
html_entities :mod:`py2:htmlentitydefs` :mod:`py3:html.entities`
html_parser :mod:`py2:HTMLParser` :mod:`py3:html.parser`
http_client :mod:`py2:httplib` :mod:`py3:http.client`
BaseHTTPServer :mod:`py2:BaseHTTPServer` :mod:`py3:http.server`
CGIHTTPServer :mod:`py2:CGIHTTPServer` :mod:`py3:http.server`
SimpleHTTPServer :mod:`py2:SimpleHTTPServer` :mod:`py3:http.server`
input :func:`py2:raw_input` :func:`py3:input`
map :func:`py2:itertools.imap` :func:`py3:map`
queue :mod:`py2:Queue` :mod:`py3:queue`
reduce :func:`py2:reduce` :func:`py3:functools.reduce`
reload_module :func:`py2:reload` :func:`py3:imp.reload`
reprlib :mod:`py2:repr` :mod:`py3:reprlib`
socketserver :mod:`py2:SocketServer` :mod:`py3:socketserver`
tkinter :mod:`py2:Tkinter` :mod:`py3:tkinter`
tkinter_dialog :mod:`py2:Dialog` :mod:`py3:tkinter.dialog`
tkinter_filedialog :mod:`py2:FileDialog` :mod:`py3:tkinter.FileDialog`
tkinter_scrolledtext :mod:`py2:ScrolledText` :mod:`py3:tkinter.scolledtext`
tkinter_simpledialog :mod:`py2:SimpleDialog` :mod:`py2:tkinter.simpledialog`
tkinter_tix :mod:`py2:Tix` :mod:`py3:tkinter.tix`
tkinter_constants :mod:`py2:Tkconstants` :mod:`py3:tkinter.constants`
tkinter_dnd :mod:`py2:Tkdnd` :mod:`py3:tkinter.dnd`
tkinter_colorchooser :mod:`py2:tkColorChooser` :mod:`py3:tkinter.colorchooser`
tkinter_commondialog :mod:`py2:tkCommonDialog` :mod:`py3:tkinter.commondialog`
tkinter_tkfiledialog :mod:`py2:tkFileDialog` :mod:`py3:tkinter.filedialog`
tkinter_font :mod:`py2:tkFont` :mod:`py3:tkinter.font`
tkinter_messagebox :mod:`py2:tkMessageBox` :mod:`py3:tkinter.messagebox`
tkinter_tksimpledialog :mod:`py2:tkSimpleDialog` :mod:`py3:tkinter.simpledialog`
urllib_robotparser :mod:`py2:robotparser` :mod:`py3:urllib.robotparser`
winreg :mod:`py2:_winreg` :mod:`py3:winreg`
xrange :func:`py2:xrange` :func:`py3:range`
zip :func:`py2:itertools.izip` :func:`py3:zip`

Advanced - Customizing renames

It is possible to add additional names to the :mod:`six.moves` namespace.

Instances of the following classes can be passed to :func:`add_move`. Neither have any public members.

Create a mapping for :mod:`six.moves` called name that references different modules in Python 2 and 3. old_mod is the name of the Python 2 module. new_mod is the name of the Python 3 module.

Create a mapping for :mod:`six.moves` called name that references different attributes in Python 2 and 3. old_mod is the name of the Python 2 module. new_mod is the name of the Python 3 module. If new_attr is not given, it defaults to old_attr. If neither is given, they both default to name.