File: imports.html

package info (click to toggle)
python-future 0.15.2-4
links: PTS, VCS
area: main
in suites: stretch
size: 8,420 kB
ctags: 6,337
sloc: python: 42,496; makefile: 141; sh: 45
file content (1113 lines) | stat: -rw-r--r-- 88,242 bytes
parent folder | download | duplicates (2)

<!DOCTYPE html>


<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    
    <title>Imports &mdash; Python-Future  documentation</title>
    
    <link rel="stylesheet" href="_static/basic.css" type="text/css" />
    <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
    <link rel="stylesheet" href="_static/my-styles.css" type="text/css" />
    <link rel="stylesheet" href="_static/bootswatch-3.3.4/cerulean/bootstrap.min.css" type="text/css" />
    <link rel="stylesheet" href="_static/bootstrap-sphinx.css" type="text/css" />
    
    <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
        URL_ROOT:    './',
        VERSION:     '',
        COLLAPSE_INDEX: false,
        FILE_SUFFIX: '.html',
        HAS_SOURCE:  true
      };
    </script>
    <script type="text/javascript" src="_static/jquery.js"></script>
    <script type="text/javascript" src="_static/underscore.js"></script>
    <script type="text/javascript" src="_static/doctools.js"></script>
    <script type="text/javascript" src="_static/js/jquery-1.11.0.min.js"></script>
    <script type="text/javascript" src="_static/js/jquery-fix.js"></script>
    <script type="text/javascript" src="_static/bootstrap-3.3.4/js/bootstrap.min.js"></script>
    <script type="text/javascript" src="_static/bootstrap-sphinx.js"></script>
    <link rel="shortcut icon" href="_static/python-future-icon-32.ico"/>
    <link rel="top" title="Python-Future  documentation" href="index.html" />
    <link rel="next" title="What else you need to know" href="what_else.html" />
    <link rel="prev" title="Cheat Sheet: Writing Python 2-3 compatible code" href="compatible_idioms.html" />

<meta charset='utf-8'>
<meta http-equiv='X-UA-Compatible' content='IE=edge,chrome=1'>
<meta name='viewport' content='width=device-width, initial-scale=1.0, maximum-scale=1'>
<meta name="apple-mobile-web-app-capable" content="yes">

<script type="text/javascript">
  var _gaq = _gaq || [];
  _gaq.push(['_setAccount', 'UA-19344199-2']);
  _gaq.push(['_trackPageview']);
</script>

  </head>
  <body role="document">

<a href="https://github.com/PythonCharmers/python-future"><img style="position: absolute; top: 45px; right: 0; border: 0;" src="https://s3.amazonaws.com/github/ribbons/forkme_right_orange_ff7600.png" alt="Fork me on GitHub"></a>
<div id="navbar" class="navbar navbar-inverse navbar-default navbar-fixed-top">

    <div class="container">

      <div class="navbar-header">

        <!-- .btn-navbar is used as the toggle for collapsed navbar content -->
        <button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".nav-collapse">
          <span class="icon-bar"></span>
          <span class="icon-bar"></span>
          <span class="icon-bar"></span>
        </button>

        <a class="logo"> <img height="32" width="32" src="_static/python-future-logo-textless-transparent.png" /></a>
        <a class="navbar-brand" href="index.html">Python-Future</a>
        <span class="navbar-text navbar-version pull-left"><b></b></span>
      </div>
        <div class="collapse navbar-collapse nav-collapse">
          <ul class="nav navbar-nav">
            <li class="divider-vertical"></li>
            
                <li><a href="overview.html">Overview</a></li>
                <li><a href="compatible_idioms.html">Cheat Sheet</a></li>
                <li><a href="faq.html">FAQ</a></li>
            
            
              <li class="dropdown globaltoc-container">
  <a role="button"
     id="dLabelGlobalToc"
     data-toggle="dropdown"
     data-target="#"
     href="index.html">Contents <b class="caret"></b></a>
  <ul class="dropdown-menu globaltoc"
      role="menu"
      aria-labelledby="dLabelGlobalToc"><ul class="current">
<li class="toctree-l1"><a class="reference internal" href="whatsnew.html">What&#8217;s New</a><ul>
<li class="toctree-l2"><a class="reference internal" href="whatsnew.html#what-s-new-in-version-0-15-0-2015-07-25">What&#8217;s new in version 0.15.0 (2015-07-25)</a></li>
<li class="toctree-l2"><a class="reference internal" href="whatsnew.html#what-s-new-in-version-0-14-3-2014-12-15">What&#8217;s new in version 0.14.3 (2014-12-15)</a></li>
<li class="toctree-l2"><a class="reference internal" href="whatsnew.html#what-s-new-in-version-0-14-2-2014-11-21">What&#8217;s new in version 0.14.2 (2014-11-21)</a></li>
<li class="toctree-l2"><a class="reference internal" href="whatsnew.html#what-s-new-in-version-0-14-1-2014-10-02">What&#8217;s new in version 0.14.1 (2014-10-02)</a></li>
<li class="toctree-l2"><a class="reference internal" href="whatsnew.html#what-s-new-in-version-0-14-2014-10-02">What&#8217;s new in version 0.14 (2014-10-02)</a><ul>
<li class="toctree-l3"><a class="reference internal" href="whatsnew.html#bug-fixes">Bug fixes</a></li>
<li class="toctree-l3"><a class="reference internal" href="whatsnew.html#internal-cleanups">Internal cleanups</a></li>
<li class="toctree-l3"><a class="reference internal" href="whatsnew.html#deprecations">Deprecations</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="whatsnew.html#previous-versions">Previous versions</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="overview.html">Overview: Easy, clean, reliable Python 2/3 compatibility</a><ul>
<li class="toctree-l2"><a class="reference internal" href="overview.html#features">Features</a></li>
<li class="toctree-l2"><a class="reference internal" href="overview.html#code-examples">Code examples</a></li>
<li class="toctree-l2"><a class="reference internal" href="overview.html#automatic-conversion-to-py2-3-compatible-code">Automatic conversion to Py2/3-compatible code</a><ul>
<li class="toctree-l3"><a class="reference internal" href="overview.html#futurize-2-to-both">Futurize: 2 to both</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="overview.html#automatic-translation">Automatic translation</a></li>
<li class="toctree-l2"><a class="reference internal" href="overview.html#licensing">Licensing</a></li>
<li class="toctree-l2"><a class="reference internal" href="overview.html#next-steps">Next steps</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="quickstart.html">Quick-start guide</a><ul>
<li class="toctree-l2"><a class="reference internal" href="quickstart.html#installation">Installation</a></li>
<li class="toctree-l2"><a class="reference internal" href="quickstart.html#if-you-are-writing-code-from-scratch">If you are writing code from scratch</a></li>
<li class="toctree-l2"><a class="reference internal" href="quickstart.html#to-convert-existing-python-3-code">To convert existing Python 3 code</a></li>
<li class="toctree-l2"><a class="reference internal" href="quickstart.html#to-convert-existing-python-2-code">To convert existing Python 2 code</a></li>
<li class="toctree-l2"><a class="reference internal" href="quickstart.html#standard-library-reorganization">Standard library reorganization</a></li>
<li class="toctree-l2"><a class="reference internal" href="quickstart.html#python-2-only-dependencies">Python 2-only dependencies</a></li>
<li class="toctree-l2"><a class="reference internal" href="quickstart.html#next-steps">Next steps</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="compatible_idioms.html">Cheat Sheet: Writing Python 2-3 compatible code</a><ul>
<li class="toctree-l2"><a class="reference internal" href="compatible_idioms.html#setup">Setup</a></li>
<li class="toctree-l2"><a class="reference internal" href="compatible_idioms.html#essential-syntax-differences">Essential syntax differences</a><ul>
<li class="toctree-l3"><a class="reference internal" href="compatible_idioms.html#print">print</a></li>
<li class="toctree-l3"><a class="reference internal" href="compatible_idioms.html#raising-exceptions">Raising exceptions</a></li>
<li class="toctree-l3"><a class="reference internal" href="compatible_idioms.html#catching-exceptions">Catching exceptions</a></li>
<li class="toctree-l3"><a class="reference internal" href="compatible_idioms.html#division">Division</a></li>
<li class="toctree-l3"><a class="reference internal" href="compatible_idioms.html#long-integers">Long integers</a></li>
<li class="toctree-l3"><a class="reference internal" href="compatible_idioms.html#octal-constants">Octal constants</a></li>
<li class="toctree-l3"><a class="reference internal" href="compatible_idioms.html#backtick-repr">Backtick repr</a></li>
<li class="toctree-l3"><a class="reference internal" href="compatible_idioms.html#metaclasses">Metaclasses</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="compatible_idioms.html#strings-and-bytes">Strings and bytes</a><ul>
<li class="toctree-l3"><a class="reference internal" href="compatible_idioms.html#unicode-text-string-literals">Unicode (text) string literals</a></li>
<li class="toctree-l3"><a class="reference internal" href="compatible_idioms.html#byte-string-literals">Byte-string literals</a></li>
<li class="toctree-l3"><a class="reference internal" href="compatible_idioms.html#basestring">basestring</a></li>
<li class="toctree-l3"><a class="reference internal" href="compatible_idioms.html#unicode">unicode</a></li>
<li class="toctree-l3"><a class="reference internal" href="compatible_idioms.html#stringio">StringIO</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="compatible_idioms.html#imports-relative-to-a-package">Imports relative to a package</a></li>
<li class="toctree-l2"><a class="reference internal" href="compatible_idioms.html#dictionaries">Dictionaries</a><ul>
<li class="toctree-l3"><a class="reference internal" href="compatible_idioms.html#iterating-through-dict-keys-values-items">Iterating through <code class="docutils literal"><span class="pre">dict</span></code> keys/values/items</a></li>
<li class="toctree-l3"><a class="reference internal" href="compatible_idioms.html#dict-keys-values-items-as-a-list">dict keys/values/items as a list</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="compatible_idioms.html#custom-class-behaviour">Custom class behaviour</a><ul>
<li class="toctree-l3"><a class="reference internal" href="compatible_idioms.html#custom-iterators">Custom iterators</a></li>
<li class="toctree-l3"><a class="reference internal" href="compatible_idioms.html#custom-str-methods">Custom <code class="docutils literal"><span class="pre">__str__</span></code> methods</a></li>
<li class="toctree-l3"><a class="reference internal" href="compatible_idioms.html#custom-nonzero-vs-bool-method">Custom <code class="docutils literal"><span class="pre">__nonzero__</span></code> vs <code class="docutils literal"><span class="pre">__bool__</span></code> method:</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="compatible_idioms.html#lists-versus-iterators">Lists versus iterators</a><ul>
<li class="toctree-l3"><a class="reference internal" href="compatible_idioms.html#xrange">xrange</a></li>
<li class="toctree-l3"><a class="reference internal" href="compatible_idioms.html#range">range</a></li>
<li class="toctree-l3"><a class="reference internal" href="compatible_idioms.html#map">map</a></li>
<li class="toctree-l3"><a class="reference internal" href="compatible_idioms.html#imap">imap</a></li>
<li class="toctree-l3"><a class="reference internal" href="compatible_idioms.html#zip-izip">zip, izip</a></li>
<li class="toctree-l3"><a class="reference internal" href="compatible_idioms.html#filter-ifilter">filter, ifilter</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="compatible_idioms.html#other-builtins">Other builtins</a><ul>
<li class="toctree-l3"><a class="reference internal" href="compatible_idioms.html#file-io-with-open">File IO with open()</a></li>
<li class="toctree-l3"><a class="reference internal" href="compatible_idioms.html#reduce">reduce()</a></li>
<li class="toctree-l3"><a class="reference internal" href="compatible_idioms.html#raw-input">raw_input()</a></li>
<li class="toctree-l3"><a class="reference internal" href="compatible_idioms.html#input">input()</a></li>
<li class="toctree-l3"><a class="reference internal" href="compatible_idioms.html#file">file()</a></li>
<li class="toctree-l3"><a class="reference internal" href="compatible_idioms.html#execfile">execfile()</a></li>
<li class="toctree-l3"><a class="reference internal" href="compatible_idioms.html#unichr">unichr()</a></li>
<li class="toctree-l3"><a class="reference internal" href="compatible_idioms.html#intern">intern()</a></li>
<li class="toctree-l3"><a class="reference internal" href="compatible_idioms.html#apply">apply()</a></li>
<li class="toctree-l3"><a class="reference internal" href="compatible_idioms.html#chr">chr()</a></li>
<li class="toctree-l3"><a class="reference internal" href="compatible_idioms.html#cmp">cmp()</a></li>
<li class="toctree-l3"><a class="reference internal" href="compatible_idioms.html#reload">reload()</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="compatible_idioms.html#standard-library">Standard library</a><ul>
<li class="toctree-l3"><a class="reference internal" href="compatible_idioms.html#dbm-modules">dbm modules</a></li>
<li class="toctree-l3"><a class="reference internal" href="compatible_idioms.html#commands-subprocess-modules">commands / subprocess modules</a></li>
<li class="toctree-l3"><a class="reference internal" href="compatible_idioms.html#subprocess-check-output">subprocess.check_output()</a></li>
<li class="toctree-l3"><a class="reference internal" href="compatible_idioms.html#collections-counter-and-ordereddict">collections: Counter and OrderedDict</a></li>
<li class="toctree-l3"><a class="reference internal" href="compatible_idioms.html#stringio-module">StringIO module</a></li>
<li class="toctree-l3"><a class="reference internal" href="compatible_idioms.html#http-module">http module</a></li>
<li class="toctree-l3"><a class="reference internal" href="compatible_idioms.html#xmlrpc-module">xmlrpc module</a></li>
<li class="toctree-l3"><a class="reference internal" href="compatible_idioms.html#html-escaping-and-entities">html escaping and entities</a></li>
<li class="toctree-l3"><a class="reference internal" href="compatible_idioms.html#html-parsing">html parsing</a></li>
<li class="toctree-l3"><a class="reference internal" href="compatible_idioms.html#urllib-module">urllib module</a></li>
<li class="toctree-l3"><a class="reference internal" href="compatible_idioms.html#tkinter">Tkinter</a></li>
<li class="toctree-l3"><a class="reference internal" href="compatible_idioms.html#socketserver">socketserver</a></li>
<li class="toctree-l3"><a class="reference internal" href="compatible_idioms.html#copy-reg-copyreg">copy_reg, copyreg</a></li>
<li class="toctree-l3"><a class="reference internal" href="compatible_idioms.html#configparser">configparser</a></li>
<li class="toctree-l3"><a class="reference internal" href="compatible_idioms.html#queue">queue</a></li>
<li class="toctree-l3"><a class="reference internal" href="compatible_idioms.html#repr-reprlib">repr, reprlib</a></li>
<li class="toctree-l3"><a class="reference internal" href="compatible_idioms.html#userdict-userlist-userstring">UserDict, UserList, UserString</a></li>
<li class="toctree-l3"><a class="reference internal" href="compatible_idioms.html#itertools-filterfalse-zip-longest">itertools: filterfalse, zip_longest</a></li>
</ul>
</li>
</ul>
</li>
<li class="toctree-l1 current"><a class="current reference internal" href="">Imports</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#future-imports">__future__ imports</a></li>
<li class="toctree-l2"><a class="reference internal" href="#imports-of-builtins">Imports of builtins</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#implicit-imports">Implicit imports</a></li>
<li class="toctree-l3"><a class="reference internal" href="#explicit-imports">Explicit imports</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#standard-library-imports">Standard library imports</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#direct-imports">Direct imports</a></li>
<li class="toctree-l3"><a class="reference internal" href="#aliased-imports">Aliased imports</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#external-standard-library-backports">External standard-library backports</a></li>
<li class="toctree-l2"><a class="reference internal" href="#included-full-backports">Included full backports</a></li>
<li class="toctree-l2"><a class="reference internal" href="#using-python-2-only-dependencies-on-python-3">Using Python 2-only dependencies on Python 3</a></li>
<li class="toctree-l2"><a class="reference internal" href="#should-i-import-unicode-literals">Should I import unicode_literals?</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#benefits">Benefits</a></li>
<li class="toctree-l3"><a class="reference internal" href="#drawbacks">Drawbacks</a></li>
<li class="toctree-l3"><a class="reference internal" href="#others-perspectives">Others&#8217; perspectives</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#next-steps">Next steps</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="what_else.html">What else you need to know</a><ul>
<li class="toctree-l2"><a class="reference internal" href="what_else.html#bytes">bytes</a></li>
<li class="toctree-l2"><a class="reference internal" href="what_else.html#str">str</a></li>
<li class="toctree-l2"><a class="reference internal" href="what_else.html#dict">dict</a><ul>
<li class="toctree-l3"><a class="reference internal" href="what_else.html#memory-efficiency-and-alternatives">Memory-efficiency and alternatives</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="what_else.html#int">int</a></li>
<li class="toctree-l2"><a class="reference internal" href="what_else.html#isinstance">isinstance</a></li>
<li class="toctree-l2"><a class="reference internal" href="what_else.html#passing-data-to-from-python-2-libraries">Passing data to/from Python 2 libraries</a></li>
<li class="toctree-l2"><a class="reference internal" href="what_else.html#native-string-type">Native string type</a></li>
<li class="toctree-l2"><a class="reference internal" href="what_else.html#open">open()</a></li>
<li class="toctree-l2"><a class="reference internal" href="what_else.html#custom-str-methods">Custom __str__ methods</a></li>
<li class="toctree-l2"><a class="reference internal" href="what_else.html#custom-iterators">Custom iterators</a></li>
<li class="toctree-l2"><a class="reference internal" href="what_else.html#binding-a-method-to-a-class">Binding a method to a class</a></li>
<li class="toctree-l2"><a class="reference internal" href="what_else.html#metaclasses">Metaclasses</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="automatic_conversion.html">Automatic conversion to Py2/3</a><ul>
<li class="toctree-l2"><a class="reference internal" href="automatic_conversion.html#futurize-py2-to-py2-3"><code class="docutils literal"><span class="pre">futurize</span></code>: Py2 to Py2/3</a><ul>
<li class="toctree-l3"><a class="reference internal" href="automatic_conversion.html#stage-1-safe-fixes">Stage 1: &#8220;safe&#8221; fixes</a></li>
<li class="toctree-l3"><a class="reference internal" href="automatic_conversion.html#stage-2-py3-style-code-with-wrappers-for-py2">Stage 2: Py3-style code with wrappers for Py2</a></li>
<li class="toctree-l3"><a class="reference internal" href="automatic_conversion.html#separating-text-from-bytes">Separating text from bytes</a></li>
<li class="toctree-l3"><a class="reference internal" href="automatic_conversion.html#post-conversion">Post-conversion</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="automatic_conversion.html#futurize-quick-start-guide"><code class="docutils literal"><span class="pre">futurize</span></code> quick-start guide</a><ul>
<li class="toctree-l3"><a class="reference internal" href="automatic_conversion.html#step-0-setup">Step 0: setup</a></li>
<li class="toctree-l3"><a class="reference internal" href="automatic_conversion.html#step-1-modern-py2-code">Step 1: modern Py2 code</a></li>
<li class="toctree-l3"><a class="reference internal" href="automatic_conversion.html#step-2-working-py3-code-that-still-supports-py2">Step 2: working Py3 code that still supports Py2</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="automatic_conversion.html#pasteurize-py3-to-py2-3"><code class="docutils literal"><span class="pre">pasteurize</span></code>: Py3 to Py2/3</a></li>
<li class="toctree-l2"><a class="reference internal" href="automatic_conversion.html#known-limitations">Known limitations</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="faq.html">Frequently Asked Questions (FAQ)</a><ul>
<li class="toctree-l2"><a class="reference internal" href="faq.html#who-is-this-for">Who is this for?</a></li>
<li class="toctree-l2"><a class="reference internal" href="faq.html#why-upgrade-to-python-3">Why upgrade to Python 3?</a></li>
<li class="toctree-l2"><a class="reference internal" href="faq.html#porting-philosophy">Porting philosophy</a><ul>
<li class="toctree-l3"><a class="reference internal" href="faq.html#why-write-python-3-style-code">Why write Python 3-style code?</a></li>
<li class="toctree-l3"><a class="reference internal" href="faq.html#can-t-i-just-roll-my-own-py2-3-compatibility-layer">Can&#8217;t I just roll my own Py2/3 compatibility layer?</a></li>
<li class="toctree-l3"><a class="reference internal" href="faq.html#what-inspired-this-project">What inspired this project?</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="faq.html#maturity">Maturity</a><ul>
<li class="toctree-l3"><a class="reference internal" href="faq.html#how-well-has-it-been-tested">How well has it been tested?</a></li>
<li class="toctree-l3"><a class="reference internal" href="faq.html#is-the-api-stable">Is the API stable?</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="faq.html#relationship-between-python-future-and-other-compatibility-tools">Relationship between python-future and other compatibility tools</a><ul>
<li class="toctree-l3"><a class="reference internal" href="faq.html#how-does-this-relate-to-2to3">How does this relate to <code class="docutils literal"><span class="pre">2to3</span></code>?</a></li>
<li class="toctree-l3"><a class="reference internal" href="faq.html#can-i-maintain-a-python-2-codebase-and-use-2to3-to-automatically-convert-to-python-3-in-the-setup-script">Can I maintain a Python 2 codebase and use 2to3 to automatically convert to Python 3 in the setup script?</a></li>
<li class="toctree-l3"><a class="reference internal" href="faq.html#what-is-the-relationship-between-future-and-six">What is the relationship between <code class="docutils literal"><span class="pre">future</span></code> and <code class="docutils literal"><span class="pre">six</span></code>?</a></li>
<li class="toctree-l3"><a class="reference internal" href="faq.html#what-is-the-relationship-between-python-future-and-python-modernize">What is the relationship between <code class="docutils literal"><span class="pre">python-future</span></code> and <code class="docutils literal"><span class="pre">python-modernize</span></code>?</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="faq.html#platform-and-version-support">Platform and version support</a><ul>
<li class="toctree-l3"><a class="reference internal" href="faq.html#which-versions-of-python-does-python-future-support">Which versions of Python does <code class="docutils literal"><span class="pre">python-future</span></code> support?</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="faq.html#support">Support</a><ul>
<li class="toctree-l3"><a class="reference internal" href="faq.html#is-there-a-mailing-list">Is there a mailing list?</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="faq.html#contributing">Contributing</a><ul>
<li class="toctree-l3"><a class="reference internal" href="faq.html#can-i-help">Can I help?</a></li>
<li class="toctree-l3"><a class="reference internal" href="faq.html#where-is-the-repo">Where is the repo?</a></li>
</ul>
</li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="stdlib_incompatibilities.html">Standard library incompatibilities</a><ul>
<li class="toctree-l2"><a class="reference internal" href="stdlib_incompatibilities.html#array-array">array.array()</a></li>
<li class="toctree-l2"><a class="reference internal" href="stdlib_incompatibilities.html#array-array-read">array.array.read()</a></li>
<li class="toctree-l2"><a class="reference internal" href="stdlib_incompatibilities.html#base64-decodebytes-and-base64-encodebytes">base64.decodebytes() and base64.encodebytes()</a></li>
<li class="toctree-l2"><a class="reference internal" href="stdlib_incompatibilities.html#re-ascii">re.ASCII</a></li>
<li class="toctree-l2"><a class="reference internal" href="stdlib_incompatibilities.html#struct-pack">struct.pack()</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="older_interfaces.html">Older interfaces</a><ul>
<li class="toctree-l2"><a class="reference internal" href="older_interfaces.html#context-manager-for-import-hooks">Context-manager for import hooks</a></li>
<li class="toctree-l2"><a class="reference internal" href="older_interfaces.html#future-moves-interface"><code class="docutils literal"><span class="pre">future.moves</span></code> interface</a><ul>
<li class="toctree-l3"><a class="reference internal" href="older_interfaces.html#comparing-future-moves-and-six-moves">Comparing future.moves and six.moves</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="older_interfaces.html#import-and-from-import-functions"><code class="docutils literal"><span class="pre">import_</span></code> and <code class="docutils literal"><span class="pre">from_import</span></code> functions</a></li>
<li class="toctree-l2"><a class="reference internal" href="older_interfaces.html#install-hooks-call">install_hooks() call</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="changelog.html">Changes in previous versions</a><ul>
<li class="toctree-l2"><a class="reference internal" href="changelog.html#changes-in-version-0-13-1-2014-09-23">Changes in version 0.13.1 (2014-09-23)</a></li>
<li class="toctree-l2"><a class="reference internal" href="changelog.html#changes-in-version-0-13-2014-08-13">Changes in version 0.13 (2014-08-13)</a><ul>
<li class="toctree-l3"><a class="reference internal" href="changelog.html#deprecations">Deprecations</a></li>
<li class="toctree-l3"><a class="reference internal" href="changelog.html#new-features">New features</a></li>
<li class="toctree-l3"><a class="reference internal" href="changelog.html#bug-fixes">Bug fixes</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="changelog.html#changes-in-version-0-12-4-2014-07-18">Changes in version 0.12.4 (2014-07-18)</a></li>
<li class="toctree-l2"><a class="reference internal" href="changelog.html#changes-in-version-0-12-3-2014-06-19">Changes in version 0.12.3 (2014-06-19)</a></li>
<li class="toctree-l2"><a class="reference internal" href="changelog.html#changes-in-version-0-12-2-2014-05-25">Changes in version 0.12.2 (2014-05-25)</a></li>
<li class="toctree-l2"><a class="reference internal" href="changelog.html#changes-in-version-0-12-1-2014-05-14">Changes in version 0.12.1 (2014-05-14)</a></li>
<li class="toctree-l2"><a class="reference internal" href="changelog.html#changes-in-version-0-12-0-2014-05-06">Changes in version 0.12.0 (2014-05-06)</a><ul>
<li class="toctree-l3"><a class="reference internal" href="changelog.html#more-robust-standard-library-import-hooks">More robust standard-library import hooks</a></li>
<li class="toctree-l3"><a class="reference internal" href="changelog.html#newobject-base-object-defines-fallback-py2-compatible-special-methods"><code class="docutils literal"><span class="pre">newobject</span></code> base object defines fallback Py2-compatible special methods</a></li>
<li class="toctree-l3"><a class="reference internal" href="changelog.html#past-builtins-module-improved"><code class="docutils literal"><span class="pre">past.builtins</span></code> module improved</a></li>
<li class="toctree-l3"><a class="reference internal" href="changelog.html#surrogateescape-error-handler"><code class="docutils literal"><span class="pre">surrogateescape</span></code> error handler</a></li>
<li class="toctree-l3"><a class="reference internal" href="changelog.html#newlist-type"><code class="docutils literal"><span class="pre">newlist</span></code> type</a></li>
<li class="toctree-l3"><a class="reference internal" href="changelog.html#listvalues-and-listitems"><code class="docutils literal"><span class="pre">listvalues</span></code> and <code class="docutils literal"><span class="pre">listitems</span></code></a></li>
<li class="toctree-l3"><a class="reference internal" href="changelog.html#tests">Tests</a></li>
<li class="toctree-l3"><a class="reference internal" href="changelog.html#refactoring-of-future-standard-library-future-backports">Refactoring of <code class="docutils literal"><span class="pre">future.standard_library.*</span></code> -&gt; <code class="docutils literal"><span class="pre">future.backports</span></code></a></li>
<li class="toctree-l3"><a class="reference internal" href="changelog.html#backported-http-server-and-urllib-modules">Backported <code class="docutils literal"><span class="pre">http.server</span></code> and <code class="docutils literal"><span class="pre">urllib</span></code> modules</a></li>
<li class="toctree-l3"><a class="reference internal" href="changelog.html#internal-refactoring">Internal refactoring</a></li>
<li class="toctree-l3"><a class="reference internal" href="changelog.html#id1">Bug fixes</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="changelog.html#changes-in-version-0-11-4-2014-05-25">Changes in version 0.11.4 (2014-05-25)</a></li>
<li class="toctree-l2"><a class="reference internal" href="changelog.html#changes-in-version-0-11-3-2014-02-27">Changes in version 0.11.3 (2014-02-27)</a><ul>
<li class="toctree-l3"><a class="reference internal" href="changelog.html#improved-compatibility-with-requests">Improved compatibility with <code class="docutils literal"><span class="pre">requests</span></code></a></li>
<li class="toctree-l3"><a class="reference internal" href="changelog.html#conversion-scripts-explicitly-install-import-hooks">Conversion scripts explicitly install import hooks</a></li>
<li class="toctree-l3"><a class="reference internal" href="changelog.html#futurize-script-no-longer-adds-unicode-literals-by-default"><code class="docutils literal"><span class="pre">futurize</span></code> script no longer adds <code class="docutils literal"><span class="pre">unicode_literals</span></code> by default</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="changelog.html#changes-in-version-0-11-2014-01-28">Changes in version 0.11 (2014-01-28)</a><ul>
<li class="toctree-l3"><a class="reference internal" href="changelog.html#past-package"><code class="docutils literal"><span class="pre">past</span></code> package</a></li>
<li class="toctree-l3"><a class="reference internal" href="changelog.html#auto-translation-of-python-2-modules-upon-import">Auto-translation of Python 2 modules upon import</a></li>
<li class="toctree-l3"><a class="reference internal" href="changelog.html#separate-pasteurize-script">Separate <code class="docutils literal"><span class="pre">pasteurize</span></code> script</a></li>
<li class="toctree-l3"><a class="reference internal" href="changelog.html#pow">pow()</a></li>
<li class="toctree-l3"><a class="reference internal" href="changelog.html#input-no-longer-disabled-globally-on-py2">input() no longer disabled globally on Py2</a></li>
<li class="toctree-l3"><a class="reference internal" href="changelog.html#deprecated-feature-auto-installation-of-standard-library-import-hooks">Deprecated feature: auto-installation of standard-library import hooks</a></li>
<li class="toctree-l3"><a class="reference internal" href="changelog.html#internal-changes">Internal changes</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="changelog.html#changes-in-version-0-10-2-2014-01-11">Changes in version 0.10.2 (2014-01-11)</a><ul>
<li class="toctree-l3"><a class="reference internal" href="changelog.html#new-context-manager-interface-to-standard-library-hooks">New context-manager interface to standard_library hooks</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="changelog.html#changes-in-version-0-10-0-2013-12-02">Changes in version 0.10.0 (2013-12-02)</a><ul>
<li class="toctree-l3"><a class="reference internal" href="changelog.html#backported-dict-type">Backported <code class="docutils literal"><span class="pre">dict</span></code> type</a></li>
<li class="toctree-l3"><a class="reference internal" href="changelog.html#utility-functions-raise-and-exec">Utility functions <code class="docutils literal"><span class="pre">raise_</span></code> and <code class="docutils literal"><span class="pre">exec_</span></code></a></li>
<li class="toctree-l3"><a class="reference internal" href="changelog.html#bugfixes">Bugfixes</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="changelog.html#changes-in-version-0-9-2013-11-06">Changes in version 0.9 (2013-11-06)</a><ul>
<li class="toctree-l3"><a class="reference internal" href="changelog.html#isinstance-checks-are-supported-natively-with-backported-types"><code class="docutils literal"><span class="pre">isinstance</span></code> checks are supported natively with backported types</a></li>
<li class="toctree-l3"><a class="reference internal" href="changelog.html#futurize-minimal-imports-by-default"><code class="docutils literal"><span class="pre">futurize</span></code>: minimal imports by default</a></li>
<li class="toctree-l3"><a class="reference internal" href="changelog.html#looser-type-checking-for-the-backported-str-object">Looser type-checking for the backported <code class="docutils literal"><span class="pre">str</span></code> object</a></li>
<li class="toctree-l3"><a class="reference internal" href="changelog.html#suspend-hooks-context-manager-added-to-future-standard-library">suspend_hooks() context manager added to <code class="docutils literal"><span class="pre">future.standard_library</span></code></a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="changelog.html#changes-in-version-0-8-2013-10-28">Changes in version 0.8 (2013-10-28)</a><ul>
<li class="toctree-l3"><a class="reference internal" href="changelog.html#python-2-6-support">Python 2.6 support</a></li>
<li class="toctree-l3"><a class="reference internal" href="changelog.html#unused-modules-removed">Unused modules removed</a></li>
<li class="toctree-l3"><a class="reference internal" href="changelog.html#isinstance-added-to-future-builtins-v0-8-2">isinstance() added to <code class="docutils literal"><span class="pre">future.builtins</span></code> (v0.8.2)</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="changelog.html#summary-of-all-changes">Summary of all changes</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="credits.html">Licensing and credits</a><ul>
<li class="toctree-l2"><a class="reference internal" href="credits.html#licence">Licence</a></li>
<li class="toctree-l2"><a class="reference internal" href="credits.html#sponsor">Sponsor</a></li>
<li class="toctree-l2"><a class="reference internal" href="credits.html#authors">Authors</a><ul>
<li class="toctree-l3"><a class="reference internal" href="credits.html#development-lead">Development Lead</a></li>
<li class="toctree-l3"><a class="reference internal" href="credits.html#patches">Patches</a></li>
<li class="toctree-l3"><a class="reference internal" href="credits.html#suggestions-and-feedback">Suggestions and Feedback</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="credits.html#other-credits">Other Credits</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="reference.html">API Reference (in progress)</a><ul>
<li class="toctree-l2"><a class="reference internal" href="reference.html#module-future.builtins">future.builtins Interface</a></li>
<li class="toctree-l2"><a class="reference internal" href="reference.html#module-future.types">Backported types from Python 3</a><ul>
<li class="toctree-l3"><a class="reference internal" href="reference.html#for-more-information">For more information:</a></li>
<li class="toctree-l3"><a class="reference internal" href="reference.html#range">range()</a></li>
<li class="toctree-l3"><a class="reference internal" href="reference.html#super">super()</a></li>
<li class="toctree-l3"><a class="reference internal" href="reference.html#round">round()</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="reference.html#module-future.standard_library">future.standard_library Interface</a><ul>
<li class="toctree-l3"><a class="reference internal" href="reference.html#limitations">Limitations</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="reference.html#module-future.utils">future.utils Interface</a></li>
<li class="toctree-l2"><a class="reference internal" href="reference.html#module-past.builtins">past.builtins Interface</a></li>
<li class="toctree-l2"><a class="reference internal" href="reference.html#module-past.types">Forward-ported types from Python 2</a></li>
</ul>
</li>
</ul>
</ul>
</li>
              
                <li class="dropdown">
  <a role="button"
     id="dLabelLocalToc"
     data-toggle="dropdown"
     data-target="#"
     href="#">Page <b class="caret"></b></a>
  <ul class="dropdown-menu localtoc"
      role="menu"
      aria-labelledby="dLabelLocalToc"><ul>
<li><a class="reference internal" href="#">Imports</a><ul>
<li><a class="reference internal" href="#future-imports">__future__ imports</a></li>
<li><a class="reference internal" href="#imports-of-builtins">Imports of builtins</a><ul>
<li><a class="reference internal" href="#implicit-imports">Implicit imports</a></li>
<li><a class="reference internal" href="#explicit-imports">Explicit imports</a><ul>
<li><a class="reference internal" href="#obsolete-python-2-builtins">Obsolete Python 2 builtins</a></li>
</ul>
</li>
</ul>
</li>
<li><a class="reference internal" href="#standard-library-imports">Standard library imports</a><ul>
<li><a class="reference internal" href="#direct-imports">Direct imports</a></li>
<li><a class="reference internal" href="#aliased-imports">Aliased imports</a></li>
</ul>
</li>
<li><a class="reference internal" href="#external-standard-library-backports">External standard-library backports</a></li>
<li><a class="reference internal" href="#included-full-backports">Included full backports</a></li>
<li><a class="reference internal" href="#using-python-2-only-dependencies-on-python-3">Using Python 2-only dependencies on Python 3</a></li>
<li><a class="reference internal" href="#should-i-import-unicode-literals">Should I import unicode_literals?</a><ul>
<li><a class="reference internal" href="#benefits">Benefits</a></li>
<li><a class="reference internal" href="#drawbacks">Drawbacks</a></li>
<li><a class="reference internal" href="#others-perspectives">Others&#8217; perspectives</a></li>
</ul>
</li>
<li><a class="reference internal" href="#next-steps">Next steps</a></li>
</ul>
</li>
</ul>
</ul>
</li>
              
            
            
            
            
            
          </ul>

          
            
<form class="navbar-form navbar-right" action="search.html" method="get">
 <div class="form-group">
  <input type="text" name="q" class="form-control" placeholder="Search" />
 </div>
  <input type="hidden" name="check_keywords" value="yes" />
  <input type="hidden" name="area" value="default" />
</form>
          

        </div>
    </div>
  </div>

<div class="container">
  <div class="row">
      <div class="col-md-3">
        <div id="sidebar" class="bs-sidenav" role="complementary"><!--<h3>Python-Future</h3>
<p>-->
  <h4>Easy, clean, reliable Python 2/3 compatibility</h4>
  <a href="http://python-future.org">Table of Contents</a>
<!--
</p>
<h3>Other Formats</h3>
<p>
  You can download the documentation in other formats as well:
</p>
<ul>
  <li><a href="http://jinja.pocoo.org/docs/jinja-docs.pdf">as PDF</a>
  <li><a href="http://jinja.pocoo.org/docs/jinja-docs.zip">as zipped HTML</a>
</ul>
-->
<!--<h3>Useful Links</h3>
<ul>
  <li><a href="http://pypi.python.org/pypi/future">on PyPI</a></li>
  <li><a href="https://github.com/PythonCharmers/python-future">on GitHub</a></li>
</ul>
--><ul class="current">
<li class="toctree-l1"><a class="reference internal" href="whatsnew.html">What&#8217;s New</a></li>
<li class="toctree-l1"><a class="reference internal" href="overview.html">Overview: Easy, clean, reliable Python 2/3 compatibility</a></li>
<li class="toctree-l1"><a class="reference internal" href="quickstart.html">Quick-start guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="compatible_idioms.html">Cheat Sheet: Writing Python 2-3 compatible code</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="">Imports</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#future-imports">__future__ imports</a></li>
<li class="toctree-l2"><a class="reference internal" href="#imports-of-builtins">Imports of builtins</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#implicit-imports">Implicit imports</a></li>
<li class="toctree-l3"><a class="reference internal" href="#explicit-imports">Explicit imports</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#standard-library-imports">Standard library imports</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#direct-imports">Direct imports</a></li>
<li class="toctree-l3"><a class="reference internal" href="#aliased-imports">Aliased imports</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#external-standard-library-backports">External standard-library backports</a></li>
<li class="toctree-l2"><a class="reference internal" href="#included-full-backports">Included full backports</a></li>
<li class="toctree-l2"><a class="reference internal" href="#using-python-2-only-dependencies-on-python-3">Using Python 2-only dependencies on Python 3</a></li>
<li class="toctree-l2"><a class="reference internal" href="#should-i-import-unicode-literals">Should I import unicode_literals?</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#benefits">Benefits</a></li>
<li class="toctree-l3"><a class="reference internal" href="#drawbacks">Drawbacks</a></li>
<li class="toctree-l3"><a class="reference internal" href="#others-perspectives">Others&#8217; perspectives</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#next-steps">Next steps</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="what_else.html">What else you need to know</a></li>
<li class="toctree-l1"><a class="reference internal" href="automatic_conversion.html">Automatic conversion to Py2/3</a></li>
<li class="toctree-l1"><a class="reference internal" href="faq.html">Frequently Asked Questions (FAQ)</a></li>
<li class="toctree-l1"><a class="reference internal" href="stdlib_incompatibilities.html">Standard library incompatibilities</a></li>
<li class="toctree-l1"><a class="reference internal" href="older_interfaces.html">Older interfaces</a></li>
<li class="toctree-l1"><a class="reference internal" href="changelog.html">Changes in previous versions</a></li>
<li class="toctree-l1"><a class="reference internal" href="credits.html">Licensing and credits</a></li>
<li class="toctree-l1"><a class="reference internal" href="reference.html">API Reference (in progress)</a></li>
</ul>

        </div>
      </div>
    <div class="col-md-9">
      
  <div class="section" id="imports">
<span id="id1"></span><h1>Imports<a class="headerlink" href="#imports" title="Permalink to this headline">¶</a></h1>
<div class="section" id="future-imports">
<span id="id2"></span><h2>__future__ imports<a class="headerlink" href="#future-imports" title="Permalink to this headline">¶</a></h2>
<p>To write a Python 2/3 compatible codebase, the first step is to add this line
to the top of each module:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">__future__</span> <span class="kn">import</span> <span class="n">absolute_import</span><span class="p">,</span> <span class="n">division</span><span class="p">,</span> <span class="n">print_function</span>
</pre></div>
</div>
<p>For guidelines about whether to import <code class="docutils literal"><span class="pre">unicode_literals</span></code> too, see below
(<a class="reference internal" href="unicode_literals.html#unicode-literals"><span>Should I import unicode_literals?</span></a>).</p>
<p>For more information about the <code class="docutils literal"><span class="pre">__future__</span></code> imports, which are a
standard feature of Python, see the following docs:</p>
<ul class="simple">
<li>absolute_import: <a class="reference external" href="http://www.python.org/dev/peps/pep-0328">PEP 328: Imports: Multi-Line and Absolute/Relative</a></li>
<li>division: <a class="reference external" href="http://www.python.org/dev/peps/pep-0238">PEP 238: Changing the Division Operator</a></li>
<li>print_function: <a class="reference external" href="http://www.python.org/dev/peps/pep-3105">PEP 3105: Make print a function</a></li>
<li>unicode_literals: <a class="reference external" href="http://www.python.org/dev/peps/pep-3112">PEP 3112: Bytes literals in Python 3000</a></li>
</ul>
<p>These are all available in Python 2.6 and up, and enabled by default in Python 3.x.</p>
</div>
<div class="section" id="imports-of-builtins">
<span id="builtins-imports"></span><h2>Imports of builtins<a class="headerlink" href="#imports-of-builtins" title="Permalink to this headline">¶</a></h2>
<div class="section" id="implicit-imports">
<span id="star-imports"></span><h3>Implicit imports<a class="headerlink" href="#implicit-imports" title="Permalink to this headline">¶</a></h3>
<p>If you don&#8217;t mind namespace pollution, the easiest way to provide Py2/3
compatibility for new code using <code class="docutils literal"><span class="pre">future</span></code> is to include the following imports
at the top of every module:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">builtins</span> <span class="kn">import</span> <span class="o">*</span>
</pre></div>
</div>
<p>On Python 3, this has no effect. (It shadows builtins with globals of the same
names.)</p>
<p>On Python 2, this import line shadows 18 builtins (listed below) to
provide their Python 3 semantics.</p>
</div>
<div class="section" id="explicit-imports">
<span id="id3"></span><h3>Explicit imports<a class="headerlink" href="#explicit-imports" title="Permalink to this headline">¶</a></h3>
<p>Explicit forms of the imports are often preferred and are necessary for using
certain automated code-analysis tools.</p>
<p>The complete set of imports of builtins from <code class="docutils literal"><span class="pre">future</span></code> is:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">builtins</span> <span class="kn">import</span> <span class="p">(</span><span class="n">ascii</span><span class="p">,</span> <span class="nb">bytes</span><span class="p">,</span> <span class="nb">chr</span><span class="p">,</span> <span class="nb">dict</span><span class="p">,</span> <span class="nb">filter</span><span class="p">,</span> <span class="nb">hex</span><span class="p">,</span> <span class="nb">input</span><span class="p">,</span>
                      <span class="nb">int</span><span class="p">,</span> <span class="nb">map</span><span class="p">,</span> <span class="nb">next</span><span class="p">,</span> <span class="nb">oct</span><span class="p">,</span> <span class="nb">open</span><span class="p">,</span> <span class="nb">pow</span><span class="p">,</span> <span class="nb">range</span><span class="p">,</span> <span class="nb">round</span><span class="p">,</span>
                      <span class="nb">str</span><span class="p">,</span> <span class="nb">super</span><span class="p">,</span> <span class="nb">zip</span><span class="p">)</span>
</pre></div>
</div>
<p>These are also available under the <code class="docutils literal"><span class="pre">future.builtins</span></code> namespace for backward compatibility.</p>
<p>Importing only some of the builtins is cleaner but increases the risk of
introducing Py2/3 portability bugs as your code evolves over time. For example,
be aware of forgetting to import <code class="docutils literal"><span class="pre">input</span></code>, which could expose a security
vulnerability on Python 2 if Python 3&#8217;s semantics are expected.</p>
<p>The internal API is currently as follows:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">future.types</span> <span class="kn">import</span> <span class="nb">bytes</span><span class="p">,</span> <span class="nb">dict</span><span class="p">,</span> <span class="nb">int</span><span class="p">,</span> <span class="nb">range</span><span class="p">,</span> <span class="nb">str</span>
<span class="kn">from</span> <span class="nn">future.builtins.misc</span> <span class="kn">import</span> <span class="p">(</span><span class="n">ascii</span><span class="p">,</span> <span class="nb">chr</span><span class="p">,</span> <span class="nb">hex</span><span class="p">,</span> <span class="nb">input</span><span class="p">,</span> <span class="nb">next</span><span class="p">,</span>
                                  <span class="nb">oct</span><span class="p">,</span> <span class="nb">open</span><span class="p">,</span> <span class="nb">pow</span><span class="p">,</span> <span class="nb">round</span><span class="p">,</span> <span class="nb">super</span><span class="p">)</span>
<span class="kn">from</span> <span class="nn">future.builtins.iterators</span> <span class="kn">import</span> <span class="nb">filter</span><span class="p">,</span> <span class="nb">map</span><span class="p">,</span> <span class="nb">zip</span>
</pre></div>
</div>
<p>Please note that this internal API is evolving and may not be stable between
different versions of <code class="docutils literal"><span class="pre">future</span></code>. To understand the details of the backported
builtins on Python 2, see the docs for these modules.</p>
<p>For more information on what the backported types provide, see <a class="reference internal" href="what_else.html#what-else"><span>What else you need to know</span></a>.</p>
<div class="section" id="obsolete-python-2-builtins">
<span id="obsolete-builtins"></span><h4>Obsolete Python 2 builtins<a class="headerlink" href="#obsolete-python-2-builtins" title="Permalink to this headline">¶</a></h4>
<p>Twelve Python 2 builtins have been removed from Python 3. To aid with
porting code to Python 3 module by module, you can use the following
import to cause a <code class="docutils literal"><span class="pre">NameError</span></code> exception to be raised on Python 2 when any
of the obsolete builtins is used, just as would occur on Python 3:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">future.builtins.disabled</span> <span class="kn">import</span> <span class="o">*</span>
</pre></div>
</div>
<p>This is equivalent to:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">future.builtins.disabled</span> <span class="kn">import</span> <span class="p">(</span><span class="nb">apply</span><span class="p">,</span> <span class="nb">cmp</span><span class="p">,</span> <span class="nb">coerce</span><span class="p">,</span> <span class="nb">execfile</span><span class="p">,</span>
                             <span class="nb">file</span><span class="p">,</span> <span class="nb">long</span><span class="p">,</span> <span class="nb">raw_input</span><span class="p">,</span> <span class="nb">reduce</span><span class="p">,</span> <span class="nb">reload</span><span class="p">,</span>
                             <span class="nb">unicode</span><span class="p">,</span> <span class="nb">xrange</span><span class="p">,</span> <span class="ne">StandardError</span><span class="p">)</span>
</pre></div>
</div>
<p>Running <code class="docutils literal"><span class="pre">futurize</span></code> over code that uses these Python 2 builtins does not
import the disabled versions; instead, it replaces them with their
equivalent Python 3 forms and then adds <code class="docutils literal"><span class="pre">future</span></code> imports to resurrect
Python 2 support, as described in <a class="reference internal" href="futurize.html#forwards-conversion-stage2"><span>Stage 2: Py3-style code with wrappers for Py2</span></a>.</p>
</div>
</div>
</div>
<div class="section" id="standard-library-imports">
<span id="id4"></span><h2>Standard library imports<a class="headerlink" href="#standard-library-imports" title="Permalink to this headline">¶</a></h2>
<p><code class="xref py py-mod docutils literal"><span class="pre">future</span></code> supports the standard library reorganization (PEP 3108) through
several mechanisms.</p>
<div class="section" id="direct-imports">
<span id="id5"></span><h3>Direct imports<a class="headerlink" href="#direct-imports" title="Permalink to this headline">¶</a></h3>
<p>As of version 0.14, the <code class="docutils literal"><span class="pre">future</span></code> package comes with top-level packages for
Python 2.x that provide access to the reorganized standard library modules
under their Python 3.x names.</p>
<p>Direct imports are the preferred mechanism for accesing the renamed standard
library modules in Python 2/3 compatible code. For example, the following clean
Python 3 code runs unchanged on Python 2 after installing <code class="docutils literal"><span class="pre">future</span></code>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="c"># Alias for future.builtins on Py2:</span>
<span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">builtins</span> <span class="kn">import</span> <span class="nb">str</span><span class="p">,</span> <span class="nb">open</span><span class="p">,</span> <span class="nb">range</span><span class="p">,</span> <span class="nb">dict</span>

<span class="gp">&gt;&gt;&gt; </span><span class="c"># Top-level packages with Py3 names provided on Py2:</span>
<span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">queue</span>
<span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">configparser</span>
<span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">tkinter.dialog</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">etc</span><span class="o">.</span>
</pre></div>
</div>
<p>Notice that this code actually runs on Python 3 without the presence of the
<code class="docutils literal"><span class="pre">future</span></code> package.</p>
<p>Of the 44 modules that were refactored with PEP 3108 (standard library
reorganization), 30 are supported with direct imports in the above manner. The
complete list is here:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="c">### Renamed modules:</span>

<span class="kn">import</span> <span class="nn">builtins</span>

<span class="kn">import</span> <span class="nn">configparser</span>
<span class="kn">import</span> <span class="nn">copyreg</span>

<span class="kn">import</span> <span class="nn">html</span>
<span class="kn">import</span> <span class="nn">html.entities</span>
<span class="kn">import</span> <span class="nn">html.parser</span>

<span class="kn">import</span> <span class="nn">http.client</span>
<span class="kn">import</span> <span class="nn">http.cookies</span>
<span class="kn">import</span> <span class="nn">http.cookiejar</span>
<span class="kn">import</span> <span class="nn">http.server</span>

<span class="kn">import</span> <span class="nn">queue</span>

<span class="kn">import</span> <span class="nn">reprlib</span>

<span class="kn">import</span> <span class="nn">socketserver</span>

<span class="kn">from</span> <span class="nn">tkinter</span> <span class="kn">import</span> <span class="n">colorchooser</span>
<span class="kn">from</span> <span class="nn">tkinter</span> <span class="kn">import</span> <span class="n">commondialog</span>
<span class="kn">from</span> <span class="nn">tkinter</span> <span class="kn">import</span> <span class="n">constants</span>
<span class="kn">from</span> <span class="nn">tkinter</span> <span class="kn">import</span> <span class="n">dialog</span>
<span class="kn">from</span> <span class="nn">tkinter</span> <span class="kn">import</span> <span class="n">dnd</span>
<span class="kn">from</span> <span class="nn">tkinter</span> <span class="kn">import</span> <span class="n">filedialog</span>
<span class="kn">from</span> <span class="nn">tkinter</span> <span class="kn">import</span> <span class="n">font</span>
<span class="kn">from</span> <span class="nn">tkinter</span> <span class="kn">import</span> <span class="n">messagebox</span>
<span class="kn">from</span> <span class="nn">tkinter</span> <span class="kn">import</span> <span class="n">scrolledtext</span>
<span class="kn">from</span> <span class="nn">tkinter</span> <span class="kn">import</span> <span class="n">simpledialog</span>
<span class="kn">from</span> <span class="nn">tkinter</span> <span class="kn">import</span> <span class="n">tix</span>
<span class="kn">from</span> <span class="nn">tkinter</span> <span class="kn">import</span> <span class="n">ttk</span>

<span class="kn">import</span> <span class="nn">winreg</span>                    <span class="c"># Windows only</span>

<span class="kn">import</span> <span class="nn">xmlrpc.client</span>
<span class="kn">import</span> <span class="nn">xmlrpc.server</span>

<span class="kn">import</span> <span class="nn">_dummy_thread</span>
<span class="kn">import</span> <span class="nn">_markupbase</span>
<span class="kn">import</span> <span class="nn">_thread</span>
</pre></div>
</div>
</div>
<div class="section" id="aliased-imports">
<span id="list-standard-library-refactored"></span><h3>Aliased imports<a class="headerlink" href="#aliased-imports" title="Permalink to this headline">¶</a></h3>
<p>The following 14 modules were refactored or extended from Python 2.6/2.7 to 3.x
but were neither renamed in Py3.x nor were the new APIs backported to Py2.x.
This precludes compatibility interfaces that work out-of-the-box. Instead, the
<code class="docutils literal"><span class="pre">future</span></code> package makes the Python 3.x APIs available on Python 2.x as
follows:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">future.standard_library</span> <span class="kn">import</span> <span class="n">install_aliases</span>
<span class="n">install_aliases</span><span class="p">()</span>

<span class="kn">from</span> <span class="nn">collections</span> <span class="kn">import</span> <span class="n">UserDict</span><span class="p">,</span> <span class="n">UserList</span><span class="p">,</span> <span class="n">UserString</span>

<span class="kn">import</span> <span class="nn">urllib.parse</span>
<span class="kn">import</span> <span class="nn">urllib.request</span>
<span class="kn">import</span> <span class="nn">urllib.response</span>
<span class="kn">import</span> <span class="nn">urllib.robotparser</span>
<span class="kn">import</span> <span class="nn">urllib.error</span>

<span class="kn">import</span> <span class="nn">dbm</span>
<span class="kn">import</span> <span class="nn">dbm.dumb</span>
<span class="kn">import</span> <span class="nn">dbm.gnu</span>                <span class="c"># requires Python dbm support</span>
<span class="kn">import</span> <span class="nn">dbm.ndbm</span>               <span class="c"># requires Python dbm support</span>

<span class="kn">from</span> <span class="nn">itertools</span> <span class="kn">import</span> <span class="n">filterfalse</span><span class="p">,</span> <span class="n">zip_longest</span>

<span class="kn">from</span> <span class="nn">subprocess</span> <span class="kn">import</span> <span class="n">getoutput</span><span class="p">,</span> <span class="n">getstatusoutput</span>

<span class="kn">from</span> <span class="nn">sys</span> <span class="kn">import</span> <span class="nb">intern</span>

<span class="kn">import</span> <span class="nn">test.support</span>
</pre></div>
</div>
<p>The newly exposed <code class="docutils literal"><span class="pre">urllib</span></code> submodules are full backports of those from Py3.x.
This means, for example, that <code class="docutils literal"><span class="pre">urllib.parse.unquote()</span></code> now exists and takes
an optional <code class="docutils literal"><span class="pre">encoding</span></code> argument on Py2.x as it does on Py3.x.</p>
<p>Backports also exist of the following features from Python 3.4:</p>
<ul class="simple">
<li><code class="docutils literal"><span class="pre">math.ceil</span></code> returns an int on Py3</li>
<li><code class="docutils literal"><span class="pre">collections.OrderedDict</span></code>  (for Python 2.6)</li>
<li><code class="docutils literal"><span class="pre">collections.Counter</span></code>      (for Python 2.6)</li>
<li><code class="docutils literal"><span class="pre">collections.ChainMap</span></code>     (for all versions prior to Python 3.3)</li>
<li><code class="docutils literal"><span class="pre">itertools.count</span></code>          (for Python 2.6, with step parameter)</li>
<li><code class="docutils literal"><span class="pre">subprocess.check_output</span></code>  (for Python 2.6)</li>
<li><code class="docutils literal"><span class="pre">reprlib.recursive_repr</span></code>   (for Python 2.6 and 2.7)</li>
</ul>
<p>These can then be imported on Python 2.6+ as follows:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">future.standard_library</span> <span class="kn">import</span> <span class="n">install_aliases</span>
<span class="n">install_aliases</span><span class="p">()</span>

<span class="kn">from</span> <span class="nn">math</span> <span class="kn">import</span> <span class="n">ceil</span>      <span class="c"># now returns an int</span>
<span class="kn">from</span> <span class="nn">collections</span> <span class="kn">import</span> <span class="n">Counter</span><span class="p">,</span> <span class="n">OrderedDict</span><span class="p">,</span> <span class="n">ChainMap</span>
<span class="kn">from</span> <span class="nn">itertools</span> <span class="kn">import</span> <span class="n">count</span>
<span class="kn">from</span> <span class="nn">subprocess</span> <span class="kn">import</span> <span class="n">check_output</span>
<span class="kn">from</span> <span class="nn">reprlib</span> <span class="kn">import</span> <span class="n">recursive_repr</span>
</pre></div>
</div>
</div>
</div>
<div class="section" id="external-standard-library-backports">
<h2>External standard-library backports<a class="headerlink" href="#external-standard-library-backports" title="Permalink to this headline">¶</a></h2>
<p>Backports of the following modules from the Python 3.x standard library are
available independently of the python-future project:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">enum</span>                       <span class="c"># pip install enum34</span>
<span class="kn">import</span> <span class="nn">singledispatch</span>             <span class="c"># pip install singledispatch</span>
<span class="kn">import</span> <span class="nn">pathlib</span>                    <span class="c"># pip install pathlib</span>
</pre></div>
</div>
<p>A few modules from Python 3.4 and 3.3 are also available in the <code class="docutils literal"><span class="pre">backports</span></code>
package namespace after <code class="docutils literal"><span class="pre">pip</span> <span class="pre">install</span> <span class="pre">backports.lzma</span></code> etc.:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">backports</span> <span class="kn">import</span> <span class="n">lzma</span>
<span class="kn">from</span> <span class="nn">backports</span> <span class="kn">import</span> <span class="n">functools_lru_cache</span> <span class="k">as</span> <span class="n">lru_cache</span>
</pre></div>
</div>
<p>The following Python 2.6 backports of standard library packages from Python 2.7+
are also available:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">argparse</span>                   <span class="c"># pip install argparse</span>
<span class="kn">import</span> <span class="nn">importlib</span>                  <span class="c"># pip install importlib</span>
<span class="kn">import</span> <span class="nn">unittest2</span> <span class="kn">as</span> <span class="nn">unittest</span>      <span class="c"># pip install unittest2</span>
</pre></div>
</div>
<p>These are included in Python 2.7 and Python 3.x.</p>
</div>
<div class="section" id="included-full-backports">
<h2>Included full backports<a class="headerlink" href="#included-full-backports" title="Permalink to this headline">¶</a></h2>
<p>Alpha-quality full backports of the following modules from Python 3.3&#8217;s
standard library to Python 2.x are also available in <code class="docutils literal"><span class="pre">future.backports</span></code>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">http</span><span class="o">.</span><span class="n">client</span>
<span class="n">http</span><span class="o">.</span><span class="n">server</span>
<span class="n">html</span><span class="o">.</span><span class="n">entities</span>
<span class="n">html</span><span class="o">.</span><span class="n">parser</span>
<span class="n">urllib</span>
<span class="n">xmlrpc</span><span class="o">.</span><span class="n">client</span>
<span class="n">xmlrpc</span><span class="o">.</span><span class="n">server</span>
</pre></div>
</div>
<p>The goal for these modules, unlike the modules in the <code class="docutils literal"><span class="pre">future.moves</span></code> package
or top-level namespace, is to backport new functionality introduced in Python
3.3.</p>
<p>If you need the full backport of one of these packages, please open an issue <a class="reference external" href="https://github.com/PythonCharmers/python-future">here</a>.</p>
</div>
<div class="section" id="using-python-2-only-dependencies-on-python-3">
<span id="translation"></span><h2>Using Python 2-only dependencies on Python 3<a class="headerlink" href="#using-python-2-only-dependencies-on-python-3" title="Permalink to this headline">¶</a></h2>
<p>The <code class="docutils literal"><span class="pre">past</span></code> module provides an experimental <code class="docutils literal"><span class="pre">translation</span></code> package to help
with importing and using old Python 2 modules in a Python 3 environment.</p>
<p>This is implemented using PEP 414 import hooks together with fixers from
<code class="docutils literal"><span class="pre">lib2to3</span></code> and <code class="docutils literal"><span class="pre">libfuturize</span></code> (included with <code class="docutils literal"><span class="pre">python-future</span></code>) that
attempt to automatically translate Python 2 code to Python 3 code with equivalent
semantics upon import.</p>
<p><em>Note</em> This feature is still in alpha and needs further development to support a
full range of real-world Python 2 modules. Also be aware that the API for
this package might change considerably in later versions.</p>
<p>Here is how to use it:</p>
<div class="highlight-python"><div class="highlight"><pre>$ pip3 install plotrique==0.2.5-7 --no-compile   # to ignore SyntaxErrors
$ python3
</pre></div>
</div>
<p>Then pass in a whitelist of module name prefixes to the
<code class="docutils literal"><span class="pre">past.autotranslate()</span></code> function. Example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">past</span> <span class="kn">import</span> <span class="n">autotranslate</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">autotranslate</span><span class="p">([</span><span class="s">&#39;plotrique&#39;</span><span class="p">])</span>
<span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">plotrique</span>
</pre></div>
</div>
<p>Here is another example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">past.translation</span> <span class="kn">import</span> <span class="n">install_hooks</span><span class="p">,</span> <span class="n">remove_hooks</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">install_hooks</span><span class="p">([</span><span class="s">&#39;mypy2module&#39;</span><span class="p">])</span>
<span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">mypy2module</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">remove_hooks</span><span class="p">()</span>
</pre></div>
</div>
<p>This will translate, import and run Python 2 code such as the following:</p>
<div class="highlight-python"><div class="highlight"><pre>### File: mypy2module.py

# Print statements are translated transparently to functions:
print &#39;Hello from a print statement&#39;

# xrange() is translated to Py3&#39;s range():
total = 0
for i in xrange(10):
    total += i
print &#39;Total is: %d&#39; % total

# Dictionary methods like .keys() and .items() are supported and
# return lists as on Python 2:
d = {&#39;a&#39;: 1, &#39;b&#39;: 2}
assert d.keys() == [&#39;a&#39;, &#39;b&#39;]
assert isinstance(d.items(), list)

# Functions like range, reduce, map, filter also return lists:
assert isinstance(range(10), list)

# The exec statement is supported:
exec &#39;total += 1&#39;
print &#39;Total is now: %d&#39; % total

# Long integers are supported:
k = 1234983424324L
print &#39;k + 1 = %d&#39; % k

# Most renamed standard library modules are supported:
import ConfigParser
import HTMLParser
import urllib
</pre></div>
</div>
<p>The attributes of the module are then accessible normally from Python 3.
For example:</p>
<div class="highlight-python"><div class="highlight"><pre># This Python 3 code works
&gt;&gt;&gt; type(mypy2module.d)
builtins.dict
</pre></div>
</div>
<p>This is a standard Python 3 data type, so, when called from Python 3 code,
<code class="docutils literal"><span class="pre">keys()</span></code> returns a view, not a list:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="nb">type</span><span class="p">(</span><span class="n">mypy2module</span><span class="o">.</span><span class="n">d</span><span class="o">.</span><span class="n">keys</span><span class="p">())</span>
<span class="go">builtins.dict_keys</span>
</pre></div>
</div>
<ul class="simple">
<li>It currently requires a newline at the end of the module or it throws a
<code class="docutils literal"><span class="pre">ParseError</span></code>.</li>
<li>This only works with pure-Python modules. C extension modules and Cython code
are not supported.</li>
<li>The biggest hurdle to automatic translation is likely to be ambiguity
about byte-strings and text (unicode strings) in the Python 2 code. If the
<code class="docutils literal"><span class="pre">past.autotranslate</span></code> feature fails because of this, you could try
running <code class="docutils literal"><span class="pre">futurize</span></code> over the code and adding a <code class="docutils literal"><span class="pre">b''</span></code> or <code class="docutils literal"><span class="pre">u''</span></code> prefix to
the relevant string literals. To convert between byte-strings and text (unicode
strings), add an <code class="docutils literal"><span class="pre">.encode</span></code> or <code class="docutils literal"><span class="pre">.decode</span></code> method call. If this succeeds,
please push your patches upstream to the package maintainers.</li>
<li>Otherwise, the source translation feature offered by the <code class="docutils literal"><span class="pre">past.translation</span></code>
package has similar limitations to the <code class="docutils literal"><span class="pre">futurize</span></code> script (see
<a class="reference internal" href="conversion_limitations.html#futurize-limitations"><span>Known limitations</span></a>). Help developing and testing this feature further
would be particularly welcome.</li>
</ul>
<p>Please report any bugs you find on the <code class="docutils literal"><span class="pre">python-future</span></code> <a class="reference external" href="https://github.com/PythonCharmers/python-future/">bug tracker</a>.</p>
</div>
<div class="section" id="should-i-import-unicode-literals">
<span id="unicode-literals"></span><h2>Should I import unicode_literals?<a class="headerlink" href="#should-i-import-unicode-literals" title="Permalink to this headline">¶</a></h2>
<p>The <code class="docutils literal"><span class="pre">future</span></code> package can be used with or without <code class="docutils literal"><span class="pre">unicode_literals</span></code>
imports.</p>
<p>In general, it is more compelling to use <code class="docutils literal"><span class="pre">unicode_literals</span></code> when
back-porting new or existing Python 3 code to Python 2/3 than when porting
existing Python 2 code to 2/3. In the latter case, explicitly marking up all
unicode string literals with <code class="docutils literal"><span class="pre">u''</span></code> prefixes would help to avoid
unintentionally changing the existing Python 2 API. However, if changing the
existing Python 2 API is not a concern, using <code class="docutils literal"><span class="pre">unicode_literals</span></code> may speed up
the porting process.</p>
<p>This section summarizes the benefits and drawbacks of using
<code class="docutils literal"><span class="pre">unicode_literals</span></code>. To avoid confusion, we recommend using
<code class="docutils literal"><span class="pre">unicode_literals</span></code> everywhere across a code-base or not at all, instead of
turning on for only some modules.</p>
<div class="section" id="benefits">
<h3>Benefits<a class="headerlink" href="#benefits" title="Permalink to this headline">¶</a></h3>
<ol class="arabic simple">
<li>String literals are unicode on Python 3. Making them unicode on Python 2
leads to more consistency of your string types across the two
runtimes. This can make it easier to understand and debug your code.</li>
<li>Code without <code class="docutils literal"><span class="pre">u''</span></code> prefixes is cleaner, one of the claimed advantages
of Python 3. Even though some unicode strings would require a function
call to invert them to native strings for some Python 2 APIs (see
<a class="reference internal" href="stdlib_incompatibilities.html#stdlib-incompatibilities"><span>Standard library incompatibilities</span></a>), the incidence of these function calls
would usually be much lower than the incidence of <code class="docutils literal"><span class="pre">u''</span></code> prefixes for text
strings in the absence of <code class="docutils literal"><span class="pre">unicode_literals</span></code>.</li>
<li>The diff when porting to a Python 2/3-compatible codebase may be smaller,
less noisy, and easier to review with <code class="docutils literal"><span class="pre">unicode_literals</span></code> than if an
explicit <code class="docutils literal"><span class="pre">u''</span></code> prefix is added to every unadorned string literal.</li>
<li>If support for Python 3.2 is required (e.g. for Ubuntu 12.04 LTS or
Debian wheezy), <code class="docutils literal"><span class="pre">u''</span></code> prefixes are a <code class="docutils literal"><span class="pre">SyntaxError</span></code>, making
<code class="docutils literal"><span class="pre">unicode_literals</span></code> the only option for a Python 2/3 compatible
codebase. [However, note that <code class="docutils literal"><span class="pre">future</span></code> doesn&#8217;t support Python 3.0-3.2.]</li>
</ol>
</div>
<div class="section" id="drawbacks">
<h3>Drawbacks<a class="headerlink" href="#drawbacks" title="Permalink to this headline">¶</a></h3>
<ol class="arabic simple">
<li>Adding <code class="docutils literal"><span class="pre">unicode_literals</span></code> to a module amounts to a &#8220;global flag day&#8221; for
that module, changing the data types of all strings in the module at once.
Cautious developers may prefer an incremental approach. (See
<a class="reference external" href="http://lwn.net/Articles/165039/">here</a> for an excellent article
describing the superiority of an incremental patch-set in the the case
of the Linux kernel.)</li>
</ol>
<ol class="arabic" start="2">
<li><p class="first">Changing to <code class="docutils literal"><span class="pre">unicode_literals</span></code> will likely introduce regressions on
Python 2 that require an initial investment of time to find and fix. The
APIs may be changed in subtle ways that are not immediately obvious.</p>
<p>An example on Python 2:</p>
<div class="highlight-python"><div class="highlight"><pre>### Module: mypaths.py

...
def unix_style_path(path):
    return path.replace(&#39;\\&#39;, &#39;/&#39;)
...

### User code:

&gt;&gt;&gt; path1 = &#39;\\Users\\Ed&#39;
&gt;&gt;&gt; unix_style_path(path1)
&#39;/Users/ed&#39;
</pre></div>
</div>
<p>On Python 2, adding a <code class="docutils literal"><span class="pre">unicode_literals</span></code> import to <code class="docutils literal"><span class="pre">mypaths.py</span></code> would
change the return type of the <code class="docutils literal"><span class="pre">unix_style_path</span></code> function from <code class="docutils literal"><span class="pre">str</span></code> to
<code class="docutils literal"><span class="pre">unicode</span></code> in the user code, which is difficult to anticipate and probably
unintended.</p>
<p>The counter-argument is that this code is broken, in a portability
sense; we see this from Python 3 raising a <code class="docutils literal"><span class="pre">TypeError</span></code> upon passing the
function a byte-string. The code needs to be changed to make explicit
whether the <code class="docutils literal"><span class="pre">path</span></code> argument is to be a byte string or a unicode string.</p>
</li>
<li><p class="first">With <code class="docutils literal"><span class="pre">unicode_literals</span></code> in effect, there is no way to specify a native
string literal (<code class="docutils literal"><span class="pre">str</span></code> type on both platforms). This can be worked around as follows:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">__future__</span> <span class="kn">import</span> <span class="n">unicode_literals</span>
<span class="gp">&gt;&gt;&gt; </span><span class="o">...</span>
<span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">future.utils</span> <span class="kn">import</span> <span class="n">bytes_to_native_str</span> <span class="k">as</span> <span class="n">n</span>

<span class="gp">&gt;&gt;&gt; </span><span class="n">s</span> <span class="o">=</span> <span class="n">n</span><span class="p">(</span><span class="n">b</span><span class="s">&#39;ABCD&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">s</span>
<span class="go">&#39;ABCD&#39;  # on both Py2 and Py3</span>
</pre></div>
</div>
<p>although this incurs a performance penalty (a function call and, on Py3,
a <code class="docutils literal"><span class="pre">decode</span></code> method call.)</p>
<p>This is a little awkward because various Python library APIs (standard
and non-standard) require a native string to be passed on both Py2
and Py3. (See <a class="reference internal" href="stdlib_incompatibilities.html#stdlib-incompatibilities"><span>Standard library incompatibilities</span></a> for some examples. WSGI
dictionaries are another.)</p>
</li>
</ol>
<ol class="arabic" start="3">
<li><p class="first">If a codebase already explicitly marks up all text with <code class="docutils literal"><span class="pre">u''</span></code> prefixes,
and if support for Python versions 3.0-3.2 can be dropped, then
removing the existing <code class="docutils literal"><span class="pre">u''</span></code> prefixes and replacing these with
<code class="docutils literal"><span class="pre">unicode_literals</span></code> imports (the porting approach Django used) would
introduce more noise into the patch and make it more difficult to review.
However, note that the <code class="docutils literal"><span class="pre">futurize</span></code> script takes advantage of PEP 414 and
does not remove explicit <code class="docutils literal"><span class="pre">u''</span></code> prefixes that already exist.</p>
</li>
<li><p class="first">Turning on <code class="docutils literal"><span class="pre">unicode_literals</span></code> converts even docstrings to unicode, but
Pydoc breaks with unicode docstrings containing non-ASCII characters for
Python versions &lt; 2.7.7. (<a class="reference external" href="http://bugs.python.org/issue1065986#msg207403">Fix
committed</a> in Jan 2014.):</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="k">def</span> <span class="nf">f</span><span class="p">():</span>
<span class="gp">... </span>    <span class="s">u&quot;Author: Martin von Löwis&quot;</span>

<span class="gp">&gt;&gt;&gt; </span><span class="n">help</span><span class="p">(</span><span class="n">f</span><span class="p">)</span>

<span class="go">/Users/schofield/Install/anaconda/python.app/Contents/lib/python2.7/pydoc.pyc in pipepager(text, cmd)</span>
<span class="go">   1376     pipe = os.popen(cmd, &#39;w&#39;)</span>
<span class="go">   1377     try:</span>
<span class="go">-&gt; 1378         pipe.write(text)</span>
<span class="go">   1379         pipe.close()</span>
<span class="go">   1380     except IOError:</span>

<span class="go">UnicodeEncodeError: &#39;ascii&#39; codec can&#39;t encode character u&#39;\xf6&#39; in position 71: ordinal not in range(128)</span>
</pre></div>
</div>
</li>
</ol>
<p>See <a class="reference external" href="http://stackoverflow.com/questions/809796/any-gotchas-using-unicode-literals-in-python-2-6">this Stack Overflow thread</a>
for other gotchas.</p>
</div>
<div class="section" id="others-perspectives">
<h3>Others&#8217; perspectives<a class="headerlink" href="#others-perspectives" title="Permalink to this headline">¶</a></h3>
<p>Django recommends importing <code class="docutils literal"><span class="pre">unicode_literals</span></code> as its top <a class="reference external" href="https://docs.djangoproject.com/en/dev/topics/python3/#unicode-literals">porting tip</a> for
migrating Django extension modules to Python 3.  The following <a class="reference external" href="https://groups.google.com/forum/#!topic/django-developers/2ddIWdicbNY">quote</a> is
from Aymeric Augustin on 23 August 2012 regarding why he chose
<code class="docutils literal"><span class="pre">unicode_literals</span></code> for the port of Django to a Python 2/3-compatible
codebase.:</p>
<blockquote>
<div><p>&#8221;... I&#8217;d like to explain why this PEP [PEP 414, which allows explicit
<code class="docutils literal"><span class="pre">u''</span></code> prefixes for unicode literals on Python 3.3+] is at odds with
the porting philosophy I&#8217;ve applied to Django, and why I would have
vetoed taking advantage of it.</p>
<p>&#8220;I believe that aiming for a Python 2 codebase with Python 3
compatibility hacks is a counter-productive way to port a project. You
end up with all the drawbacks of Python 2 (including the legacy <cite>u</cite>
prefixes) and none of the advantages Python 3 (especially the sane
string handling).</p>
<p>&#8220;Working to write Python 3 code, with legacy compatibility for Python
2, is much more rewarding. Of course it takes more effort, but the
results are much cleaner and much more maintainable. It&#8217;s really about
looking towards the future or towards the past.</p>
<p>&#8220;I understand the reasons why PEP 414 was proposed and why it was
accepted. It makes sense for legacy software that is minimally
maintained. I hope nobody puts Django in this category!&#8221;</p>
</div></blockquote>
<blockquote>
<div><p>&#8220;There are so many subtle problems that <code class="docutils literal"><span class="pre">unicode_literals</span></code> causes.
For instance lots of people accidentally introduce unicode into
filenames and that seems to work, until they are using it on a system
where there are unicode characters in the filesystem path.&#8221;</p>
<p class="attribution">&mdash;Armin Ronacher</p>
</div></blockquote>
<blockquote>
<div><p>&#8220;+1 from me for avoiding the unicode_literals future, as it can have
very strange side effects in Python 2.... This is one of the key
reasons I backed Armin&#8217;s PEP 414.&#8221;</p>
<p class="attribution">&mdash;Nick Coghlan</p>
</div></blockquote>
<blockquote>
<div><p>&#8220;Yeah, one of the nuisances of the WSGI spec is that the header values
IIRC are the str or StringType on both py2 and py3. With
unicode_literals this causes hard-to-spot bugs, as some WSGI servers
might be more tolerant than others, but usually using unicode in python
2 for WSGI headers will cause the response to fail.&#8221;</p>
<p class="attribution">&mdash;Antti Haapala</p>
</div></blockquote>
</div>
</div>
<div class="section" id="next-steps">
<h2>Next steps<a class="headerlink" href="#next-steps" title="Permalink to this headline">¶</a></h2>
<p>See <a class="reference internal" href="what_else.html#what-else"><span>What else you need to know</span></a>.</p>
</div>
</div>


    </div>
      
  </div>
</div>

<footer class="footer">
  <div class="container">
    <p class="pull-right">
      <a href="#">Back to top</a>
      
    </p>
    <p>
        &copy; Copyright 2013-2015, Python Charmers Pty Ltd, Australia.<br/>
    </p>
  </div>
</footer>
<div class="footer">
<script type="text/javascript">
  (function() {
    var ga = document.createElement('script');
    ga.src = ('https:' == document.location.protocol ?
              'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
    ga.setAttribute('async', 'true');
    document.documentElement.firstChild.appendChild(ga);
  })();
</script>
</div>

  </body>
</html>