File: what_else.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 (1177 lines) | stat: -rw-r--r-- 113,025 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>What else you need to know &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="Automatic conversion to Py2/3" href="automatic_conversion.html" />
    <link rel="prev" title="Imports" href="imports.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"><a class="reference internal" href="imports.html">Imports</a><ul>
<li class="toctree-l2"><a class="reference internal" href="imports.html#future-imports">__future__ imports</a></li>
<li class="toctree-l2"><a class="reference internal" href="imports.html#imports-of-builtins">Imports of builtins</a><ul>
<li class="toctree-l3"><a class="reference internal" href="imports.html#implicit-imports">Implicit imports</a></li>
<li class="toctree-l3"><a class="reference internal" href="imports.html#explicit-imports">Explicit imports</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="imports.html#standard-library-imports">Standard library imports</a><ul>
<li class="toctree-l3"><a class="reference internal" href="imports.html#direct-imports">Direct imports</a></li>
<li class="toctree-l3"><a class="reference internal" href="imports.html#aliased-imports">Aliased imports</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="imports.html#external-standard-library-backports">External standard-library backports</a></li>
<li class="toctree-l2"><a class="reference internal" href="imports.html#included-full-backports">Included full backports</a></li>
<li class="toctree-l2"><a class="reference internal" href="imports.html#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="imports.html#should-i-import-unicode-literals">Should I import unicode_literals?</a><ul>
<li class="toctree-l3"><a class="reference internal" href="imports.html#benefits">Benefits</a></li>
<li class="toctree-l3"><a class="reference internal" href="imports.html#drawbacks">Drawbacks</a></li>
<li class="toctree-l3"><a class="reference internal" href="imports.html#others-perspectives">Others&#8217; perspectives</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="imports.html#next-steps">Next steps</a></li>
</ul>
</li>
<li class="toctree-l1 current"><a class="current reference internal" href="">What else you need to know</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#bytes">bytes</a></li>
<li class="toctree-l2"><a class="reference internal" href="#str">str</a></li>
<li class="toctree-l2"><a class="reference internal" href="#dict">dict</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#memory-efficiency-and-alternatives">Memory-efficiency and alternatives</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#int">int</a></li>
<li class="toctree-l2"><a class="reference internal" href="#isinstance">isinstance</a></li>
<li class="toctree-l2"><a class="reference internal" href="#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="#native-string-type">Native string type</a></li>
<li class="toctree-l2"><a class="reference internal" href="#open">open()</a></li>
<li class="toctree-l2"><a class="reference internal" href="#custom-str-methods">Custom __str__ methods</a></li>
<li class="toctree-l2"><a class="reference internal" href="#custom-iterators">Custom iterators</a></li>
<li class="toctree-l2"><a class="reference internal" href="#binding-a-method-to-a-class">Binding a method to a class</a></li>
<li class="toctree-l2"><a class="reference internal" href="#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="#">What else you need to know</a><ul>
<li><a class="reference internal" href="#bytes">bytes</a></li>
<li><a class="reference internal" href="#str">str</a></li>
<li><a class="reference internal" href="#dict">dict</a><ul>
<li><a class="reference internal" href="#memory-efficiency-and-alternatives">Memory-efficiency and alternatives</a></li>
</ul>
</li>
<li><a class="reference internal" href="#int">int</a></li>
<li><a class="reference internal" href="#isinstance">isinstance</a></li>
<li><a class="reference internal" href="#passing-data-to-from-python-2-libraries">Passing data to/from Python 2 libraries</a></li>
<li><a class="reference internal" href="#native-string-type">Native string type</a></li>
<li><a class="reference internal" href="#open">open()</a></li>
<li><a class="reference internal" href="#custom-str-methods">Custom __str__ methods</a></li>
<li><a class="reference internal" href="#custom-iterators">Custom iterators</a></li>
<li><a class="reference internal" href="#binding-a-method-to-a-class">Binding a method to a class</a></li>
<li><a class="reference internal" href="#metaclasses">Metaclasses</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"><a class="reference internal" href="imports.html">Imports</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="">What else you need to know</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#bytes">bytes</a></li>
<li class="toctree-l2"><a class="reference internal" href="#str">str</a></li>
<li class="toctree-l2"><a class="reference internal" href="#dict">dict</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#memory-efficiency-and-alternatives">Memory-efficiency and alternatives</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#int">int</a></li>
<li class="toctree-l2"><a class="reference internal" href="#isinstance">isinstance</a></li>
<li class="toctree-l2"><a class="reference internal" href="#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="#native-string-type">Native string type</a></li>
<li class="toctree-l2"><a class="reference internal" href="#open">open()</a></li>
<li class="toctree-l2"><a class="reference internal" href="#custom-str-methods">Custom __str__ methods</a></li>
<li class="toctree-l2"><a class="reference internal" href="#custom-iterators">Custom iterators</a></li>
<li class="toctree-l2"><a class="reference internal" href="#binding-a-method-to-a-class">Binding a method to a class</a></li>
<li class="toctree-l2"><a class="reference internal" href="#metaclasses">Metaclasses</a></li>
</ul>
</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="what-else-you-need-to-know">
<span id="what-else"></span><h1>What else you need to know<a class="headerlink" href="#what-else-you-need-to-know" title="Permalink to this headline">¶</a></h1>
<p>The following points are important to know about when writing Python 2/3
compatible code.</p>
<div class="section" id="bytes">
<span id="bytes-object"></span><span id="what-else-essentials"></span><h2>bytes<a class="headerlink" href="#bytes" title="Permalink to this headline">¶</a></h2>
<p>Handling <code class="docutils literal"><span class="pre">bytes</span></code> consistently and correctly has traditionally been one
of the most difficult tasks in writing a Py2/3 compatible codebase. This
is because the Python 2 <code class="xref py py-class docutils literal"><span class="pre">bytes</span></code> object is simply an alias for
Python 2&#8217;s <a class="reference external" href="http://docs.python.org/library/functions.html#str" title="(in Python v2.7)"><code class="xref py py-class docutils literal"><span class="pre">str</span></code></a>, rather than a true implementation of the Python
3 <code class="xref py py-class docutils literal"><span class="pre">bytes</span></code> object, which is substantially different.</p>
<p><code class="xref py py-mod docutils literal"><span class="pre">future</span></code> contains a backport of the <code class="xref py py-mod docutils literal"><span class="pre">bytes</span></code> object from Python 3
which passes most of the Python 3 tests for <code class="xref py py-mod docutils literal"><span class="pre">bytes</span></code>. (See
<code class="docutils literal"><span class="pre">tests/test_future/test_bytes.py</span></code> in the source tree.) You can use it 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">builtins</span> <span class="kn">import</span> <span class="nb">bytes</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">b</span> <span class="o">=</span> <span class="nb">bytes</span><span class="p">(</span><span class="n">b</span><span class="s">&#39;ABCD&#39;</span><span class="p">)</span>
</pre></div>
</div>
<p>On Py3, this is simply the builtin <code class="xref py py-class docutils literal"><span class="pre">bytes</span></code> object. On Py2, this
object is a subclass of Python 2&#8217;s <a class="reference external" href="http://docs.python.org/library/functions.html#str" title="(in Python v2.7)"><code class="xref py py-class docutils literal"><span class="pre">str</span></code></a> that enforces the same
strict separation of unicode strings and byte strings as Python 3&#8217;s
<code class="xref py py-class docutils literal"><span class="pre">bytes</span></code> object:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">b</span> <span class="o">+</span> <span class="s">u&#39;EFGH&#39;</span>      <span class="c"># TypeError</span>
<span class="gt">Traceback (most recent call last):</span>
  File <span class="nb">&quot;&lt;stdin&gt;&quot;</span>, line <span class="m">1</span>, in <span class="n">&lt;module&gt;</span>
<span class="gr">TypeError</span>: <span class="n">argument can&#39;t be unicode string</span>

<span class="gp">&gt;&gt;&gt; </span><span class="nb">bytes</span><span class="p">(</span><span class="n">b</span><span class="s">&#39;,&#39;</span><span class="p">)</span><span class="o">.</span><span class="n">join</span><span class="p">([</span><span class="s">u&#39;Fred&#39;</span><span class="p">,</span> <span class="s">u&#39;Bill&#39;</span><span class="p">])</span>
<span class="gt">Traceback (most recent call last):</span>
  File <span class="nb">&quot;&lt;stdin&gt;&quot;</span>, line <span class="m">1</span>, in <span class="n">&lt;module&gt;</span>
<span class="gr">TypeError</span>: <span class="n">sequence item 0: expected bytes, found unicode string</span>

<span class="gp">&gt;&gt;&gt; </span><span class="n">b</span> <span class="o">==</span> <span class="s">u&#39;ABCD&#39;</span>
<span class="go">False</span>

<span class="gp">&gt;&gt;&gt; </span><span class="n">b</span> <span class="o">&lt;</span> <span class="s">u&#39;abc&#39;</span>
<span class="gt">Traceback (most recent call last):</span>
  File <span class="nb">&quot;&lt;stdin&gt;&quot;</span>, line <span class="m">1</span>, in <span class="n">&lt;module&gt;</span>
<span class="gr">TypeError</span>: <span class="n">unorderable types: bytes() and &lt;type &#39;unicode&#39;&gt;</span>
</pre></div>
</div>
<p>In most other ways, these <code class="xref py py-class docutils literal"><span class="pre">bytes</span></code> objects have identical
behaviours to Python 3&#8217;s <code class="xref py py-class docutils literal"><span class="pre">bytes</span></code>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">b</span> <span class="o">=</span> <span class="nb">bytes</span><span class="p">(</span><span class="n">b</span><span class="s">&#39;ABCD&#39;</span><span class="p">)</span>
<span class="k">assert</span> <span class="nb">list</span><span class="p">(</span><span class="n">b</span><span class="p">)</span> <span class="o">==</span> <span class="p">[</span><span class="mi">65</span><span class="p">,</span> <span class="mi">66</span><span class="p">,</span> <span class="mi">67</span><span class="p">,</span> <span class="mi">68</span><span class="p">]</span>
<span class="k">assert</span> <span class="nb">repr</span><span class="p">(</span><span class="n">b</span><span class="p">)</span> <span class="o">==</span> <span class="s">&quot;b&#39;ABCD&#39;&quot;</span>
<span class="k">assert</span> <span class="n">b</span><span class="o">.</span><span class="n">split</span><span class="p">(</span><span class="n">b</span><span class="s">&#39;B&#39;</span><span class="p">)</span> <span class="o">==</span> <span class="p">[</span><span class="n">b</span><span class="s">&#39;A&#39;</span><span class="p">,</span> <span class="n">b</span><span class="s">&#39;CD&#39;</span><span class="p">]</span>
</pre></div>
</div>
<p>Currently the easiest way to ensure identical behaviour of byte-strings
in a Py2/3 codebase is to wrap all byte-string literals <code class="docutils literal"><span class="pre">b'...'</span></code> in a
<code class="xref py py-func docutils literal"><span class="pre">bytes()</span></code> call as follows:</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="nb">bytes</span>

<span class="c"># ...</span>

<span class="n">b</span> <span class="o">=</span> <span class="nb">bytes</span><span class="p">(</span><span class="n">b</span><span class="s">&#39;This is my bytestring&#39;</span><span class="p">)</span>

<span class="c"># ...</span>
</pre></div>
</div>
<p>This is not perfect, but it is superior to manually debugging and fixing
code incompatibilities caused by the many differences between Py3 bytes
and Py2 strings.</p>
<p>The <code class="xref py py-class docutils literal"><span class="pre">bytes</span></code> type from <code class="xref py py-mod docutils literal"><span class="pre">builtins</span></code> also provides support for the
<code class="docutils literal"><span class="pre">surrogateescape</span></code> error handler on Python 2.x. Here is an example that works
identically on Python 2.x and 3.x:</p>
<div class="highlight-python"><div class="highlight"><pre><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">bytes</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">b</span> <span class="o">=</span> <span class="nb">bytes</span><span class="p">(</span><span class="n">b</span><span class="s">&#39;</span><span class="se">\xff</span><span class="s">&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">b</span><span class="o">.</span><span class="n">decode</span><span class="p">(</span><span class="s">&#39;utf-8&#39;</span><span class="p">,</span> <span class="s">&#39;surrogateescape&#39;</span><span class="p">)</span>
<span class="go">&#39;\udcc3&#39;</span>
</pre></div>
</div>
<p>This feature is in alpha. Please leave feedback <a class="reference external" href="https://github.com/PythonCharmers/python-future/issues">here</a> about whether this
works for you.</p>
</div>
<div class="section" id="str">
<span id="str-object"></span><h2>str<a class="headerlink" href="#str" title="Permalink to this headline">¶</a></h2>
<p>The <a class="reference external" href="http://docs.python.org/library/functions.html#str" title="(in Python v2.7)"><code class="xref py py-class docutils literal"><span class="pre">str</span></code></a> object in Python 3 is quite similar but not identical to the
Python 2 <code class="xref py py-class docutils literal"><span class="pre">unicode</span></code> object.</p>
<p>The major difference is the stricter type-checking of Py3&#8217;s <code class="docutils literal"><span class="pre">str</span></code> that
enforces a distinction between unicode strings and byte-strings, such as when
comparing, concatenating, joining, or replacing parts of strings.</p>
<p>There are also other differences, such as the <code class="docutils literal"><span class="pre">repr</span></code> of unicode strings in
Py2 having a <code class="docutils literal"><span class="pre">u'...'</span></code> prefix, versus simply <code class="docutils literal"><span class="pre">'...'</span></code>, and the removal of
the <code class="xref py py-func docutils literal"><span class="pre">str.decode()</span></code> method in Py3.</p>
<p><code class="xref py py-mod docutils literal"><span class="pre">future</span></code> contains a <code class="xref py py-class docutils literal"><span class="pre">newstr`</span></code> type that is a backport of the
<code class="xref py py-mod docutils literal"><span class="pre">str</span></code> object from Python 3. This inherits from the Python 2
<code class="xref py py-class docutils literal"><span class="pre">unicode</span></code> class but has customizations to improve compatibility with
Python 3&#8217;s <a class="reference external" href="http://docs.python.org/library/functions.html#str" title="(in Python v2.7)"><code class="xref py py-class docutils literal"><span class="pre">str</span></code></a> object. You can use it 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="kn">from</span> <span class="nn">builtins</span> <span class="kn">import</span> <span class="nb">str</span>
</pre></div>
</div>
<p>On Py2, this gives us:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="nb">str</span>
<span class="go">future.types.newstr.newstr</span>
</pre></div>
</div>
<p>(On Py3, it is simply the usual builtin <a class="reference external" href="http://docs.python.org/library/functions.html#str" title="(in Python v2.7)"><code class="xref py py-class docutils literal"><span class="pre">str</span></code></a> object.)</p>
<p>Then, for example, the following code has the same effect on Py2 as on Py3:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">s</span> <span class="o">=</span> <span class="nb">str</span><span class="p">(</span><span class="s">u&#39;ABCD&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">assert</span> <span class="n">s</span> <span class="o">!=</span> <span class="n">b</span><span class="s">&#39;ABCD&#39;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">assert</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">s</span><span class="o">.</span><span class="n">encode</span><span class="p">(</span><span class="s">&#39;utf-8&#39;</span><span class="p">),</span> <span class="nb">bytes</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">assert</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">b</span><span class="o">.</span><span class="n">decode</span><span class="p">(</span><span class="s">&#39;utf-8&#39;</span><span class="p">),</span> <span class="nb">str</span><span class="p">)</span>

<span class="go">These raise TypeErrors:</span>

<span class="gp">&gt;&gt;&gt; </span><span class="nb">bytes</span><span class="p">(</span><span class="n">b</span><span class="s">&#39;B&#39;</span><span class="p">)</span> <span class="ow">in</span> <span class="n">s</span>
<span class="gt">Traceback (most recent call last):</span>
  File <span class="nb">&quot;&lt;stdin&gt;&quot;</span>, line <span class="m">1</span>, in <span class="n">&lt;module&gt;</span>
<span class="gr">TypeError</span>: <span class="n">&#39;in &lt;string&gt;&#39; requires string as left operand, not &lt;type &#39;str&#39;&gt;</span>

<span class="gp">&gt;&gt;&gt; </span><span class="n">s</span><span class="o">.</span><span class="n">find</span><span class="p">(</span><span class="nb">bytes</span><span class="p">(</span><span class="n">b</span><span class="s">&#39;A&#39;</span><span class="p">))</span>
<span class="gt">Traceback (most recent call last):</span>
  File <span class="nb">&quot;&lt;stdin&gt;&quot;</span>, line <span class="m">1</span>, in <span class="n">&lt;module&gt;</span>
<span class="gr">TypeError</span>: <span class="n">argument can&#39;t be &lt;type &#39;str&#39;&gt;</span>
</pre></div>
</div>
<p>Various other operations that mix strings and bytes or other types are
permitted on Py2 with the <code class="xref py py-class docutils literal"><span class="pre">newstr</span></code> class even though they
are illegal with Python 3. For example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">s2</span> <span class="o">=</span> <span class="n">b</span><span class="s">&#39;/&#39;</span> <span class="o">+</span> <span class="nb">str</span><span class="p">(</span><span class="s">&#39;ABCD&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">s2</span>
<span class="go">&#39;/ABCD&#39;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="nb">type</span><span class="p">(</span><span class="n">s2</span><span class="p">)</span>
<span class="go">future.types.newstr.newstr</span>
</pre></div>
</div>
<p>This is allowed for compatibility with parts of the Python 2 standard
library and various third-party libraries that mix byte-strings and unicode
strings loosely. One example is <code class="docutils literal"><span class="pre">os.path.join</span></code> on Python 2, which
attempts to add the byte-string <code class="docutils literal"><span class="pre">b'/'</span></code> to its arguments, whether or not
they are unicode. (See <code class="docutils literal"><span class="pre">posixpath.py</span></code>.) Another example is the
<code class="xref py py-func docutils literal"><span class="pre">escape()</span></code> function in Django 1.4&#8217;s <code class="xref py py-mod docutils literal"><span class="pre">django.utils.html</span></code>.</p>
<p>In most other ways, these <code class="xref py py-class docutils literal"><span class="pre">builtins.str</span></code> objects on Py2 have the
same behaviours as Python 3&#8217;s <a class="reference external" href="http://docs.python.org/library/functions.html#str" title="(in Python v2.7)"><code class="xref py py-class docutils literal"><span class="pre">str</span></code></a>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">s</span> <span class="o">=</span> <span class="nb">str</span><span class="p">(</span><span class="s">&#39;ABCD&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">assert</span> <span class="nb">repr</span><span class="p">(</span><span class="n">s</span><span class="p">)</span> <span class="o">==</span> <span class="s">&#39;ABCD&#39;</span>      <span class="c"># consistent repr with Py3 (no u prefix)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">assert</span> <span class="nb">list</span><span class="p">(</span><span class="n">s</span><span class="p">)</span> <span class="o">==</span> <span class="p">[</span><span class="s">&#39;A&#39;</span><span class="p">,</span> <span class="s">&#39;B&#39;</span><span class="p">,</span> <span class="s">&#39;C&#39;</span><span class="p">,</span> <span class="s">&#39;D&#39;</span><span class="p">]</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">assert</span> <span class="n">s</span><span class="o">.</span><span class="n">split</span><span class="p">(</span><span class="s">&#39;B&#39;</span><span class="p">)</span> <span class="o">==</span> <span class="p">[</span><span class="s">&#39;A&#39;</span><span class="p">,</span> <span class="s">&#39;CD&#39;</span><span class="p">]</span>
</pre></div>
</div>
<p>The <a class="reference external" href="http://docs.python.org/library/functions.html#str" title="(in Python v2.7)"><code class="xref py py-class docutils literal"><span class="pre">str</span></code></a> type from <code class="xref py py-mod docutils literal"><span class="pre">builtins</span></code> also provides support for the
<code class="docutils literal"><span class="pre">surrogateescape</span></code> error handler on Python 2.x. Here is an example that works
identically on Python 2.x and 3.x:</p>
<div class="highlight-python"><div class="highlight"><pre><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="gp">&gt;&gt;&gt; </span><span class="n">s</span> <span class="o">=</span> <span class="nb">str</span><span class="p">(</span><span class="s">u&#39;</span><span class="se">\udcff</span><span class="s">&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">s</span><span class="o">.</span><span class="n">encode</span><span class="p">(</span><span class="s">&#39;utf-8&#39;</span><span class="p">,</span> <span class="s">&#39;surrogateescape&#39;</span><span class="p">)</span>
<span class="go">b&#39;\xff&#39;</span>
</pre></div>
</div>
<p>This feature is in alpha. Please leave feedback <a class="reference external" href="https://github.com/PythonCharmers/python-future/issues">here</a> about whether this
works for you.</p>
</div>
<div class="section" id="dict">
<span id="dict-object"></span><h2>dict<a class="headerlink" href="#dict" title="Permalink to this headline">¶</a></h2>
<p>Python 3 dictionaries have <code class="docutils literal"><span class="pre">.keys()</span></code>, <code class="docutils literal"><span class="pre">.values()</span></code>, and <code class="docutils literal"><span class="pre">.items()</span></code>
methods which return memory-efficient set-like iterator objects, not lists.
(See <a class="reference external" href="http://www.python.org/dev/peps/pep-3106/">PEP 3106</a>.)</p>
<p>If your dictionaries are small, performance is not critical, and you don&#8217;t need
the set-like behaviour of iterator objects from Python 3, you can of course
stick with standard Python 3 code in your Py2/3 compatible codebase:</p>
<div class="highlight-python"><div class="highlight"><pre># Assuming d is a native dict ...

for key in d:
    # code here

for item in d.items():
    # code here

for value in d.values():
    # code here
</pre></div>
</div>
<p>In this case there will be memory overhead of list creation on Py2 for each
call to <code class="docutils literal"><span class="pre">items</span></code>, <code class="docutils literal"><span class="pre">values</span></code> or <code class="docutils literal"><span class="pre">keys</span></code>.</p>
<p>For improved efficiency, <code class="docutils literal"><span class="pre">future.builtins</span></code> (aliased to <code class="docutils literal"><span class="pre">builtins</span></code>) provides
a Python 2 <code class="docutils literal"><span class="pre">dict</span></code> subclass whose <code class="xref py py-func docutils literal"><span class="pre">keys()</span></code>, <code class="xref py py-func docutils literal"><span class="pre">values()</span></code>, and
<code class="xref py py-func docutils literal"><span class="pre">items()</span></code> methods return iterators on all versions of Python &gt;= 2.6. On
Python 2.7, these iterators also have the same set-like view behaviour as
dictionaries in Python 3. This can streamline code that iterates over large
dictionaries. For example:</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">print_function</span>
<span class="kn">from</span> <span class="nn">builtins</span> <span class="kn">import</span> <span class="nb">dict</span><span class="p">,</span> <span class="nb">range</span>

<span class="c"># Memory-efficient construction:</span>
<span class="n">d</span> <span class="o">=</span> <span class="nb">dict</span><span class="p">((</span><span class="n">i</span><span class="p">,</span> <span class="n">i</span><span class="o">**</span><span class="mi">2</span><span class="p">)</span> <span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="mi">10</span><span class="o">**</span><span class="mi">7</span><span class="p">))</span>

<span class="k">assert</span> <span class="ow">not</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">d</span><span class="o">.</span><span class="n">items</span><span class="p">(),</span> <span class="nb">list</span><span class="p">)</span>

<span class="c"># Because items() is memory-efficient, so is this:</span>
<span class="n">d2</span> <span class="o">=</span> <span class="nb">dict</span><span class="p">((</span><span class="n">v</span><span class="p">,</span> <span class="n">k</span><span class="p">)</span> <span class="k">for</span> <span class="p">(</span><span class="n">k</span><span class="p">,</span> <span class="n">v</span><span class="p">)</span> <span class="ow">in</span> <span class="n">d</span><span class="o">.</span><span class="n">items</span><span class="p">())</span>
</pre></div>
</div>
<p>On Python 2.6, these methods currently return iterators but do not support the
new Py3 set-like behaviour.</p>
<p>As usual, on Python 3 <code class="docutils literal"><span class="pre">dict</span></code> imported from either <code class="docutils literal"><span class="pre">builtins</span></code> or
<code class="docutils literal"><span class="pre">future.builtins</span></code> is just the built-in <code class="docutils literal"><span class="pre">dict</span></code> class.</p>
<div class="section" id="memory-efficiency-and-alternatives">
<h3>Memory-efficiency and alternatives<a class="headerlink" href="#memory-efficiency-and-alternatives" title="Permalink to this headline">¶</a></h3>
<p>If you already have large native dictionaries, the downside to wrapping them in
a <code class="docutils literal"><span class="pre">dict</span></code> call is that memory is copied (on both Py3 and on Py2). For
example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="c"># This allocates and then frees a large amount of temporary memory:</span>
<span class="n">d</span> <span class="o">=</span> <span class="nb">dict</span><span class="p">({</span><span class="n">i</span><span class="p">:</span> <span class="n">i</span><span class="o">**</span><span class="mi">2</span> <span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="mi">10</span><span class="o">**</span><span class="mi">7</span><span class="p">)})</span>
</pre></div>
</div>
<p>If dictionary methods like <code class="docutils literal"><span class="pre">values</span></code> and <code class="docutils literal"><span class="pre">items</span></code> are called only once, this
obviously negates the memory benefits offered by the overridden methods through
not creating temporary lists.</p>
<p>The memory-efficient (and CPU-efficient) alternatives are:</p>
<ul>
<li><p class="first">to construct a dictionary from an iterator. The above line could use a
generator like this:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">d</span> <span class="o">=</span> <span class="nb">dict</span><span class="p">((</span><span class="n">i</span><span class="p">,</span> <span class="n">i</span><span class="o">**</span><span class="mi">2</span><span class="p">)</span> <span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="mi">10</span><span class="o">**</span><span class="mi">7</span><span class="p">))</span>
</pre></div>
</div>
</li>
<li><p class="first">to construct an empty dictionary with a <code class="docutils literal"><span class="pre">dict()</span></code> call using
<code class="docutils literal"><span class="pre">builtins.dict</span></code> (rather than <code class="docutils literal"><span class="pre">{}</span></code>) and then update it;</p>
</li>
<li><p class="first">to use the <code class="docutils literal"><span class="pre">viewitems</span></code> etc. functions from <a class="reference internal" href="reference.html#module-future.utils" title="future.utils"><code class="xref py py-mod docutils literal"><span class="pre">future.utils</span></code></a>, passing in
regular dictionaries:</p>
<div class="highlight-python"><div class="highlight"><pre>from future.utils import viewkeys, viewvalues, viewitems

for (key, value) in viewitems(hugedictionary):
    # some code here

# Set intersection:
d = {i**2: i for i in range(1000)}
both = viewkeys(d) &amp; set(range(0, 1000, 7))

# Set union:
both = viewvalues(d1) | viewvalues(d2)
</pre></div>
</div>
</li>
</ul>
<p>For Python 2.6 compatibility, the functions <code class="docutils literal"><span class="pre">iteritems</span></code> etc. are also
available in <a class="reference internal" href="reference.html#module-future.utils" title="future.utils"><code class="xref py py-mod docutils literal"><span class="pre">future.utils</span></code></a>. These are equivalent to the functions of the
same names in <code class="docutils literal"><span class="pre">six</span></code>, which is equivalent to calling the <code class="docutils literal"><span class="pre">iteritems</span></code> etc.
methods on Python 2, or to calling <code class="docutils literal"><span class="pre">items</span></code> etc. on Python 3.</p>
</div>
</div>
<div class="section" id="int">
<span id="int-object"></span><h2>int<a class="headerlink" href="#int" title="Permalink to this headline">¶</a></h2>
<p>Python 3&#8217;s <code class="docutils literal"><span class="pre">int</span></code> type is very similar to Python 2&#8217;s <code class="docutils literal"><span class="pre">long</span></code>, except
for the representation (which omits the <code class="docutils literal"><span class="pre">L</span></code> suffix in Python 2). Python
2&#8217;s usual (short) integers have been removed from Python 3, as has the
<code class="docutils literal"><span class="pre">long</span></code> builtin name.</p>
<p>Python 3:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="mi">2</span><span class="o">**</span><span class="mi">64</span>
<span class="go">18446744073709551616</span>
</pre></div>
</div>
<p>Python 2:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="mi">2</span><span class="o">**</span><span class="mi">64</span>
<span class="go">18446744073709551616L</span>
</pre></div>
</div>
<p><code class="docutils literal"><span class="pre">future</span></code> includes a backport of Python 3&#8217;s <code class="docutils literal"><span class="pre">int</span></code> that
is a subclass of Python 2&#8217;s <code class="docutils literal"><span class="pre">long</span></code> with the same representation
behaviour as Python 3&#8217;s <code class="docutils literal"><span class="pre">int</span></code>. To ensure an integer is long compatibly with
both Py3 and Py2, cast it like this:</p>
<div class="highlight-python"><div class="highlight"><pre><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">int</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">must_be_a_long_integer</span> <span class="o">=</span> <span class="nb">int</span><span class="p">(</span><span class="mi">1234</span><span class="p">)</span>
</pre></div>
</div>
<p>The backported <code class="docutils literal"><span class="pre">int</span></code> object helps with writing doctests and simplifies code
that deals with <code class="docutils literal"><span class="pre">long</span></code> and <code class="docutils literal"><span class="pre">int</span></code> as special cases on Py2. An example is the
following code from <code class="docutils literal"><span class="pre">xlwt-future</span></code> (called by the <code class="docutils literal"><span class="pre">xlwt.antlr.BitSet</span></code> class)
for writing out Excel <code class="docutils literal"><span class="pre">.xls</span></code> spreadsheets. With <code class="docutils literal"><span class="pre">future</span></code>, the 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="nb">int</span>

<span class="k">def</span> <span class="nf">longify</span><span class="p">(</span><span class="n">data</span><span class="p">):</span>
    <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">    Turns data (an int or long, or a list of ints or longs) into a</span>
<span class="sd">    list of longs.</span>
<span class="sd">    &quot;&quot;&quot;</span>
    <span class="k">if</span> <span class="ow">not</span> <span class="n">data</span><span class="p">:</span>
        <span class="k">return</span> <span class="p">[</span><span class="nb">int</span><span class="p">(</span><span class="mi">0</span><span class="p">)]</span>
    <span class="k">if</span> <span class="ow">not</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">data</span><span class="p">,</span> <span class="nb">list</span><span class="p">):</span>
        <span class="k">return</span> <span class="p">[</span><span class="nb">int</span><span class="p">(</span><span class="n">data</span><span class="p">)]</span>
    <span class="k">return</span> <span class="nb">list</span><span class="p">(</span><span class="nb">map</span><span class="p">(</span><span class="nb">int</span><span class="p">,</span> <span class="n">data</span><span class="p">))</span>
</pre></div>
</div>
<p>Without <code class="docutils literal"><span class="pre">future</span></code> (or with <code class="docutils literal"><span class="pre">future</span></code> &lt; 0.7), this might be:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">def</span> <span class="nf">longify</span><span class="p">(</span><span class="n">data</span><span class="p">):</span>
    <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">    Turns data (an int or long, or a list of ints or longs) into a</span>
<span class="sd">    list of longs.</span>
<span class="sd">    &quot;&quot;&quot;</span>
    <span class="k">if</span> <span class="ow">not</span> <span class="n">data</span><span class="p">:</span>
        <span class="k">if</span> <span class="n">PY3</span><span class="p">:</span>
            <span class="k">return</span> <span class="p">[</span><span class="mi">0</span><span class="p">]</span>
        <span class="k">else</span><span class="p">:</span>
            <span class="k">return</span> <span class="p">[</span><span class="nb">long</span><span class="p">(</span><span class="mi">0</span><span class="p">)]</span>
    <span class="k">if</span> <span class="ow">not</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">data</span><span class="p">,</span><span class="nb">list</span><span class="p">):</span>
        <span class="k">if</span> <span class="n">PY3</span><span class="p">:</span>
            <span class="k">return</span> <span class="p">[</span><span class="nb">int</span><span class="p">(</span><span class="n">data</span><span class="p">)]</span>
        <span class="k">else</span><span class="p">:</span>
            <span class="k">return</span> <span class="p">[</span><span class="nb">long</span><span class="p">(</span><span class="n">data</span><span class="p">)]</span>
    <span class="k">if</span> <span class="n">PY3</span><span class="p">:</span>
        <span class="k">return</span> <span class="nb">list</span><span class="p">(</span><span class="nb">map</span><span class="p">(</span><span class="nb">int</span><span class="p">,</span> <span class="n">data</span><span class="p">))</span>   <span class="c"># same as returning data, but with up-front typechecking</span>
    <span class="k">else</span><span class="p">:</span>
        <span class="k">return</span> <span class="nb">list</span><span class="p">(</span><span class="nb">map</span><span class="p">(</span><span class="nb">long</span><span class="p">,</span> <span class="n">data</span><span class="p">))</span>
</pre></div>
</div>
</div>
<div class="section" id="isinstance">
<span id="isinstance-calls"></span><h2>isinstance<a class="headerlink" href="#isinstance" title="Permalink to this headline">¶</a></h2>
<p>The following tests all pass on Python 3:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="k">assert</span> <span class="nb">isinstance</span><span class="p">(</span><span class="mi">2</span><span class="o">**</span><span class="mi">62</span><span class="p">,</span> <span class="nb">int</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">assert</span> <span class="nb">isinstance</span><span class="p">(</span><span class="mi">2</span><span class="o">**</span><span class="mi">63</span><span class="p">,</span> <span class="nb">int</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">assert</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">b</span><span class="s">&#39;my byte-string&#39;</span><span class="p">,</span> <span class="nb">bytes</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">assert</span> <span class="nb">isinstance</span><span class="p">(</span><span class="s">u&#39;unicode string 1&#39;</span><span class="p">,</span> <span class="nb">str</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">assert</span> <span class="nb">isinstance</span><span class="p">(</span><span class="s">&#39;unicode string 2&#39;</span><span class="p">,</span> <span class="nb">str</span><span class="p">)</span>
</pre></div>
</div>
<p>However, two of these normally fail on Python 2:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="k">assert</span> <span class="nb">isinstance</span><span class="p">(</span><span class="mi">2</span><span class="o">**</span><span class="mi">63</span><span class="p">,</span> <span class="nb">int</span><span class="p">)</span>
<span class="gt">Traceback (most recent call last):</span>
  File <span class="nb">&quot;&lt;stdin&gt;&quot;</span>, line <span class="m">1</span>, in <span class="n">&lt;module&gt;</span>
<span class="gr">AssertionError</span>

<span class="gp">&gt;&gt;&gt; </span><span class="k">assert</span> <span class="nb">isinstance</span><span class="p">(</span><span class="s">u&#39;my unicode string&#39;</span><span class="p">,</span> <span class="nb">str</span><span class="p">)</span>
<span class="gt">Traceback (most recent call last):</span>
  File <span class="nb">&quot;&lt;stdin&gt;&quot;</span>, line <span class="m">1</span>, in <span class="n">&lt;module&gt;</span>
<span class="gr">AssertionError</span>
</pre></div>
</div>
<p>And if this import is in effect on Python 2:</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>
</pre></div>
</div>
<p>then the fifth test fails too:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="k">assert</span> <span class="nb">isinstance</span><span class="p">(</span><span class="s">&#39;unicode string 2&#39;</span><span class="p">,</span> <span class="nb">str</span><span class="p">)</span>
<span class="gt">Traceback (most recent call last):</span>
  File <span class="nb">&quot;&lt;stdin&gt;&quot;</span>, line <span class="m">1</span>, in <span class="n">&lt;module&gt;</span>
<span class="gr">AssertionError</span>
</pre></div>
</div>
<p>After importing the builtins from <code class="docutils literal"><span class="pre">future</span></code>, all these tests pass on
Python 2 as on Python 3:</p>
<div class="highlight-python"><div class="highlight"><pre><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">bytes</span><span class="p">,</span> <span class="nb">int</span><span class="p">,</span> <span class="nb">str</span>

<span class="gp">&gt;&gt;&gt; </span><span class="k">assert</span> <span class="nb">isinstance</span><span class="p">(</span><span class="mi">10</span><span class="p">,</span> <span class="nb">int</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">assert</span> <span class="nb">isinstance</span><span class="p">(</span><span class="mi">10</span><span class="o">**</span><span class="mi">100</span><span class="p">,</span> <span class="nb">int</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">assert</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">b</span><span class="s">&#39;my byte-string&#39;</span><span class="p">,</span> <span class="nb">bytes</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">assert</span> <span class="nb">isinstance</span><span class="p">(</span><span class="s">u&#39;unicode string 1&#39;</span><span class="p">,</span> <span class="nb">str</span><span class="p">)</span>
</pre></div>
</div>
<p>However, note that the last test requires that <code class="docutils literal"><span class="pre">unicode_literals</span></code> be imported to succeed.:</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="k">assert</span> <span class="nb">isinstance</span><span class="p">(</span><span class="s">&#39;unicode string 2&#39;</span><span class="p">,</span> <span class="nb">str</span><span class="p">)</span>
</pre></div>
</div>
<p>This works because the backported types <code class="docutils literal"><span class="pre">int</span></code>, <code class="docutils literal"><span class="pre">bytes</span></code> and <code class="docutils literal"><span class="pre">str</span></code>
(and others) have metaclasses that override <code class="docutils literal"><span class="pre">__instancecheck__</span></code>. See <a class="reference external" href="http://www.python.org/dev/peps/pep-3119/#overloading-isinstance-and-issubclass">PEP 3119</a>
for details.</p>
</div>
<div class="section" id="passing-data-to-from-python-2-libraries">
<h2>Passing data to/from Python 2 libraries<a class="headerlink" href="#passing-data-to-from-python-2-libraries" title="Permalink to this headline">¶</a></h2>
<p>If you are passing any of the backported types (<code class="docutils literal"><span class="pre">bytes</span></code>, <code class="docutils literal"><span class="pre">int</span></code>, <code class="docutils literal"><span class="pre">dict,</span>
<span class="pre">``str</span></code>) into brittle library code that performs type-checks using <code class="docutils literal"><span class="pre">type()</span></code>,
rather than <code class="docutils literal"><span class="pre">isinstance()</span></code>, or requires that you pass Python 2&#8217;s native types
(rather than subclasses) for some other reason, it may be necessary to upcast
the types from <code class="docutils literal"><span class="pre">future</span></code> to their native superclasses on Py2.</p>
<p>The <code class="docutils literal"><span class="pre">native</span></code> function in <code class="docutils literal"><span class="pre">future.utils</span></code> is provided for this. Here is how
to use it. (The output showing is from Py2):</p>
<div class="highlight-python"><div class="highlight"><pre><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">int</span><span class="p">,</span> <span class="nb">bytes</span><span class="p">,</span> <span class="nb">str</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">native</span>

<span class="gp">&gt;&gt;&gt; </span><span class="n">a</span> <span class="o">=</span> <span class="nb">int</span><span class="p">(</span><span class="mi">10</span><span class="o">**</span><span class="mi">20</span><span class="p">)</span>     <span class="c"># Py3-like long int</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">a</span>
<span class="go">100000000000000000000</span>
<span class="gp">&gt;&gt;&gt; </span><span class="nb">type</span><span class="p">(</span><span class="n">a</span><span class="p">)</span>
<span class="go">future.types.newint.newint</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">native</span><span class="p">(</span><span class="n">a</span><span class="p">)</span>
<span class="go">100000000000000000000L</span>
<span class="gp">&gt;&gt;&gt; </span><span class="nb">type</span><span class="p">(</span><span class="n">native</span><span class="p">(</span><span class="n">a</span><span class="p">))</span>
<span class="go">long</span>

<span class="gp">&gt;&gt;&gt; </span><span class="n">b</span> <span class="o">=</span> <span class="nb">bytes</span><span class="p">(</span><span class="n">b</span><span class="s">&#39;ABC&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="nb">type</span><span class="p">(</span><span class="n">b</span><span class="p">)</span>
<span class="go">future.types.newbytes.newbytes</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">native</span><span class="p">(</span><span class="n">b</span><span class="p">)</span>
<span class="go">&#39;ABC&#39;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="nb">type</span><span class="p">(</span><span class="n">native</span><span class="p">(</span><span class="n">b</span><span class="p">))</span>
<span class="go">str</span>

<span class="gp">&gt;&gt;&gt; </span><span class="n">s</span> <span class="o">=</span> <span class="nb">str</span><span class="p">(</span><span class="s">u&#39;ABC&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="nb">type</span><span class="p">(</span><span class="n">s</span><span class="p">)</span>
<span class="go">future.types.newstr.newstr</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">native</span><span class="p">(</span><span class="n">s</span><span class="p">)</span>
<span class="go">u&#39;ABC&#39;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="nb">type</span><span class="p">(</span><span class="n">native</span><span class="p">(</span><span class="n">s</span><span class="p">))</span>
<span class="go">unicode</span>
</pre></div>
</div>
<p>On Py3, the <code class="xref py py-func docutils literal"><span class="pre">native()</span></code> function is a no-op.</p>
</div>
<div class="section" id="native-string-type">
<h2>Native string type<a class="headerlink" href="#native-string-type" title="Permalink to this headline">¶</a></h2>
<p>Some library code, include standard library code like the <code class="docutils literal"><span class="pre">array.array()</span></code>
constructor, require native strings on Python 2 and Python 3. This means that
there is no simple way to pass the appropriate string type when the
<code class="docutils literal"><span class="pre">unicode_literals</span></code> import from <code class="docutils literal"><span class="pre">__future__</span></code> is in effect.</p>
<p>The objects <code class="docutils literal"><span class="pre">native_str</span></code> and <code class="docutils literal"><span class="pre">native_bytes</span></code> are available in
<code class="docutils literal"><span class="pre">future.utils</span></code> for this case. These are equivalent to the <code class="docutils literal"><span class="pre">str</span></code> and
<code class="docutils literal"><span class="pre">bytes</span></code> objects in <code class="docutils literal"><span class="pre">__builtin__</span></code> on Python 2 or in <code class="docutils literal"><span class="pre">builtins</span></code> on Python 3.</p>
<p>The functions <code class="docutils literal"><span class="pre">native_str_to_bytes</span></code> and <code class="docutils literal"><span class="pre">bytes_to_native_str</span></code> are also
available for more explicit conversions.</p>
</div>
<div class="section" id="open">
<span id="open-function"></span><h2>open()<a class="headerlink" href="#open" title="Permalink to this headline">¶</a></h2>
<p>The Python 3 builtin <a class="reference external" href="http://docs.python.org/library/functions.html#open" title="(in Python v2.7)"><code class="xref py py-func docutils literal"><span class="pre">open()</span></code></a> function for opening files returns file
contents as (unicode) strings unless the binary (<code class="docutils literal"><span class="pre">b</span></code>) flag is passed, as in:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="nb">open</span><span class="p">(</span><span class="n">filename</span><span class="p">,</span> <span class="s">&#39;rb&#39;</span><span class="p">)</span>
</pre></div>
</div>
<p>in which case its methods like <code class="xref py py-func docutils literal"><span class="pre">read()</span></code> return Py3 <code class="xref py py-class docutils literal"><span class="pre">bytes</span></code> objects.</p>
<p>On Py2 with <code class="docutils literal"><span class="pre">future</span></code> installed, the <code class="xref py py-mod docutils literal"><span class="pre">builtins</span></code> module provides an
<code class="docutils literal"><span class="pre">open</span></code> function that is mostly compatible with that on Python 3 (e.g. it
offers keyword arguments like <code class="docutils literal"><span class="pre">encoding</span></code>). This maps to the <code class="docutils literal"><span class="pre">open</span></code> backport
available in the standard library <a class="reference external" href="http://docs.python.org/library/io.html#module-io" title="(in Python v2.7)"><code class="xref py py-mod docutils literal"><span class="pre">io</span></code></a> module on Py2.6 and Py2.7.</p>
<p>One difference to be aware of between the Python 3 <code class="docutils literal"><span class="pre">open</span></code> and
<code class="docutils literal"><span class="pre">future.builtins.open</span></code> on Python 2 is that the return types of methods such
as <code class="xref py py-func docutils literal"><span class="pre">read()</span></code> from the file object that <code class="docutils literal"><span class="pre">open</span></code> returns are not
automatically cast from native bytes or unicode strings on Python 2 to the
corresponding <code class="docutils literal"><span class="pre">future.builtins.bytes</span></code> or <code class="docutils literal"><span class="pre">future.builtins.str</span></code> types. If you
need the returned data to behave the exactly same way on Py2 as on Py3, you can
cast it explicitly as follows:</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">unicode_literals</span>
<span class="kn">from</span> <span class="nn">builtins</span> <span class="kn">import</span> <span class="nb">open</span><span class="p">,</span> <span class="nb">bytes</span>

<span class="n">data</span> <span class="o">=</span> <span class="nb">open</span><span class="p">(</span><span class="s">&#39;image.png&#39;</span><span class="p">,</span> <span class="s">&#39;rb&#39;</span><span class="p">)</span><span class="o">.</span><span class="n">read</span><span class="p">()</span>
<span class="c"># On Py2, data is a standard 8-bit str with loose Unicode coercion.</span>
<span class="c"># data + u&#39;&#39; would likely raise a UnicodeDecodeError</span>

<span class="n">data</span> <span class="o">=</span> <span class="nb">bytes</span><span class="p">(</span><span class="n">data</span><span class="p">)</span>
<span class="c"># Now it behaves like a Py3 bytes object...</span>

<span class="k">assert</span> <span class="n">data</span><span class="p">[:</span><span class="mi">4</span><span class="p">]</span> <span class="o">==</span> <span class="n">b</span><span class="s">&#39;</span><span class="se">\x89</span><span class="s">PNG&#39;</span>
<span class="k">assert</span> <span class="n">data</span><span class="p">[</span><span class="mi">4</span><span class="p">]</span> <span class="o">==</span> <span class="mi">13</span>     <span class="c"># integer</span>
<span class="c"># Raises TypeError:</span>
<span class="c"># data + u&#39;&#39;</span>
</pre></div>
</div>
</div>
<div class="section" id="custom-str-methods">
<span id="id2"></span><h2>Custom __str__ methods<a class="headerlink" href="#custom-str-methods" title="Permalink to this headline">¶</a></h2>
<p>If you define a custom <code class="docutils literal"><span class="pre">__str__</span></code> method for any of your classes,
functions like <code class="docutils literal"><span class="pre">print()</span></code> expect <code class="docutils literal"><span class="pre">__str__</span></code> on Py2 to return a byte
string, whereas on Py3 they expect a (unicode) string.</p>
<p>Use the following decorator to map the <code class="docutils literal"><span class="pre">__str__</span></code> to <code class="docutils literal"><span class="pre">__unicode__</span></code> on
Py2 and define <code class="docutils literal"><span class="pre">__str__</span></code> to encode it as utf-8:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">future.utils</span> <span class="kn">import</span> <span class="n">python_2_unicode_compatible</span>

<span class="nd">@python_2_unicode_compatible</span>
<span class="k">class</span> <span class="nc">MyClass</span><span class="p">(</span><span class="nb">object</span><span class="p">):</span>
    <span class="k">def</span> <span class="nf">__str__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
        <span class="k">return</span> <span class="s">u&#39;Unicode string: </span><span class="se">\u5b54\u5b50</span><span class="s">&#39;</span>
<span class="n">a</span> <span class="o">=</span> <span class="n">MyClass</span><span class="p">()</span>

<span class="c"># This then prints the name of a Chinese philosopher:</span>
<span class="k">print</span><span class="p">(</span><span class="n">a</span><span class="p">)</span>
</pre></div>
</div>
<p>This decorator is identical to the decorator of the same name in
<code class="xref py py-mod docutils literal"><span class="pre">django.utils.encoding</span></code>.</p>
<p>This decorator is a no-op on Python 3.</p>
</div>
<div class="section" id="custom-iterators">
<span id="id3"></span><h2>Custom iterators<a class="headerlink" href="#custom-iterators" title="Permalink to this headline">¶</a></h2>
<p>If you define your own iterators, there is an incompatibility in the method name
to retrieve the next item across Py3 and Py2. On Python 3 it is <code class="docutils literal"><span class="pre">__next__</span></code>,
whereas on Python 2 it is <code class="docutils literal"><span class="pre">next</span></code>.</p>
<p>The most elegant solution to this is to derive your custom iterator class from
<code class="docutils literal"><span class="pre">builtins.object</span></code> and define a <code class="docutils literal"><span class="pre">__next__</span></code> method as you normally
would on Python 3. On Python 2, <code class="docutils literal"><span class="pre">object</span></code> then refers to the
<code class="docutils literal"><span class="pre">future.types.newobject</span></code> base class, which provides a fallback <code class="docutils literal"><span class="pre">next</span></code>
method that calls your <code class="docutils literal"><span class="pre">__next__</span></code>. Use it as follows:</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="nb">object</span>

<span class="k">class</span> <span class="nc">Upper</span><span class="p">(</span><span class="nb">object</span><span class="p">):</span>
    <span class="k">def</span> <span class="nf">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">iterable</span><span class="p">):</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">_iter</span> <span class="o">=</span> <span class="nb">iter</span><span class="p">(</span><span class="n">iterable</span><span class="p">)</span>
    <span class="k">def</span> <span class="nf">__next__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>                 <span class="c"># Py3-style iterator interface</span>
        <span class="k">return</span> <span class="nb">next</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">_iter</span><span class="p">)</span><span class="o">.</span><span class="n">upper</span><span class="p">()</span>
    <span class="k">def</span> <span class="nf">__iter__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
        <span class="k">return</span> <span class="bp">self</span>

<span class="n">itr</span> <span class="o">=</span> <span class="n">Upper</span><span class="p">(</span><span class="s">&#39;hello&#39;</span><span class="p">)</span>
<span class="k">assert</span> <span class="nb">next</span><span class="p">(</span><span class="n">itr</span><span class="p">)</span> <span class="o">==</span> <span class="s">&#39;H&#39;</span>
<span class="k">assert</span> <span class="nb">next</span><span class="p">(</span><span class="n">itr</span><span class="p">)</span> <span class="o">==</span> <span class="s">&#39;E&#39;</span>
<span class="k">assert</span> <span class="nb">list</span><span class="p">(</span><span class="n">itr</span><span class="p">)</span> <span class="o">==</span> <span class="nb">list</span><span class="p">(</span><span class="s">&#39;LLO&#39;</span><span class="p">)</span>
</pre></div>
</div>
<p>You can use this approach unless you are defining a custom iterator as a
subclass of a base class defined elsewhere that does not derive from
<code class="docutils literal"><span class="pre">newobject</span></code>.  In that case, you can provide compatibility across
Python 2 and Python 3 using the <code class="docutils literal"><span class="pre">next</span></code> function from <code class="docutils literal"><span class="pre">future.builtins</span></code>:</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="nb">next</span>

<span class="kn">from</span> <span class="nn">some_module</span> <span class="kn">import</span> <span class="n">some_base_class</span>

<span class="k">class</span> <span class="nc">Upper2</span><span class="p">(</span><span class="n">some_base_class</span><span class="p">):</span>
    <span class="k">def</span> <span class="nf">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">iterable</span><span class="p">):</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">_iter</span> <span class="o">=</span> <span class="nb">iter</span><span class="p">(</span><span class="n">iterable</span><span class="p">)</span>
    <span class="k">def</span> <span class="nf">__next__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>                 <span class="c"># Py3-style iterator interface</span>
        <span class="k">return</span> <span class="nb">next</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">_iter</span><span class="p">)</span><span class="o">.</span><span class="n">upper</span><span class="p">()</span>
    <span class="k">def</span> <span class="nf">__iter__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
        <span class="k">return</span> <span class="bp">self</span>

<span class="n">itr2</span> <span class="o">=</span> <span class="n">Upper2</span><span class="p">(</span><span class="s">&#39;hello&#39;</span><span class="p">)</span>
<span class="k">assert</span> <span class="nb">next</span><span class="p">(</span><span class="n">itr2</span><span class="p">)</span> <span class="o">==</span> <span class="s">&#39;H&#39;</span>
<span class="k">assert</span> <span class="nb">next</span><span class="p">(</span><span class="n">itr2</span><span class="p">)</span> <span class="o">==</span> <span class="s">&#39;E&#39;</span>
</pre></div>
</div>
<p><code class="docutils literal"><span class="pre">next()</span></code> also works with regular Python 2 iterators with a <code class="docutils literal"><span class="pre">.next</span></code> method:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">itr3</span> <span class="o">=</span> <span class="nb">iter</span><span class="p">([</span><span class="s">&#39;one&#39;</span><span class="p">,</span> <span class="s">&#39;three&#39;</span><span class="p">,</span> <span class="s">&#39;five&#39;</span><span class="p">])</span>
<span class="k">assert</span> <span class="s">&#39;next&#39;</span> <span class="ow">in</span> <span class="nb">dir</span><span class="p">(</span><span class="n">itr3</span><span class="p">)</span>
<span class="k">assert</span> <span class="nb">next</span><span class="p">(</span><span class="n">itr3</span><span class="p">)</span> <span class="o">==</span> <span class="s">&#39;one&#39;</span>
</pre></div>
</div>
<p>This approach is feasible whenever your code calls the <code class="docutils literal"><span class="pre">next()</span></code> function
explicitly. If you consume the iterator implicitly in a <code class="docutils literal"><span class="pre">for</span></code> loop or
<code class="docutils literal"><span class="pre">list()</span></code> call or by some other means, the <code class="docutils literal"><span class="pre">future.builtins.next</span></code> function
will not help; the third assertion below would fail on Python 2:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">itr2</span> <span class="o">=</span> <span class="n">Upper2</span><span class="p">(</span><span class="s">&#39;hello&#39;</span><span class="p">)</span>

<span class="k">assert</span> <span class="nb">next</span><span class="p">(</span><span class="n">itr2</span><span class="p">)</span> <span class="o">==</span> <span class="s">&#39;H&#39;</span>
<span class="k">assert</span> <span class="nb">next</span><span class="p">(</span><span class="n">itr2</span><span class="p">)</span> <span class="o">==</span> <span class="s">&#39;E&#39;</span>
<span class="k">assert</span> <span class="nb">list</span><span class="p">(</span><span class="n">itr2</span><span class="p">)</span> <span class="o">==</span> <span class="nb">list</span><span class="p">(</span><span class="s">&#39;LLO&#39;</span><span class="p">)</span>      <span class="c"># fails because Py2 implicitly looks</span>
                                      <span class="c"># for a ``next`` method.</span>
</pre></div>
</div>
<p>Instead, you can use a decorator called <code class="docutils literal"><span class="pre">implements_iterator</span></code> from
<code class="docutils literal"><span class="pre">future.utils</span></code> to allow Py3-style iterators to work identically on Py2, even
if they don&#8217;t inherit from <code class="docutils literal"><span class="pre">future.builtins.object</span></code>. Use it as follows:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">future.utils</span> <span class="kn">import</span> <span class="n">implements_iterator</span>

<span class="n">Upper2</span> <span class="o">=</span> <span class="n">implements_iterator</span><span class="p">(</span><span class="n">Upper2</span><span class="p">)</span>

<span class="k">print</span><span class="p">(</span><span class="nb">list</span><span class="p">(</span><span class="n">Upper2</span><span class="p">(</span><span class="s">&#39;hello&#39;</span><span class="p">)))</span>
<span class="c"># prints [&#39;H&#39;, &#39;E&#39;, &#39;L&#39;, &#39;L&#39;, &#39;O&#39;]</span>
</pre></div>
</div>
<p>This can of course also be used with the <code class="docutils literal"><span class="pre">&#64;</span></code> decorator syntax when defining
the iterator as follows:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="nd">@implements_iterator</span>
<span class="k">class</span> <span class="nc">Upper2</span><span class="p">(</span><span class="n">some_base_class</span><span class="p">):</span>
    <span class="k">def</span> <span class="nf">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">iterable</span><span class="p">):</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">_iter</span> <span class="o">=</span> <span class="nb">iter</span><span class="p">(</span><span class="n">iterable</span><span class="p">)</span>
    <span class="k">def</span> <span class="nf">__next__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>                 <span class="c"># note the Py3 interface</span>
        <span class="k">return</span> <span class="nb">next</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">_iter</span><span class="p">)</span><span class="o">.</span><span class="n">upper</span><span class="p">()</span>
    <span class="k">def</span> <span class="nf">__iter__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
        <span class="k">return</span> <span class="bp">self</span>
</pre></div>
</div>
<p>On Python 3, as usual, this decorator does nothing.</p>
</div>
<div class="section" id="binding-a-method-to-a-class">
<span id="bind-method"></span><span id="what-else-advanced"></span><h2>Binding a method to a class<a class="headerlink" href="#binding-a-method-to-a-class" title="Permalink to this headline">¶</a></h2>
<p>Python 2 draws a distinction between bound and unbound methods, whereas
in Python 3 this distinction is gone: unbound methods have been removed
from the language. To bind a method to a class compatibly across Python
3 and Python 2, you can use the <code class="xref py py-func docutils literal"><span class="pre">bind_method()</span></code> helper function:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">future.utils</span> <span class="kn">import</span> <span class="n">bind_method</span>

<span class="k">class</span> <span class="nc">Greeter</span><span class="p">(</span><span class="nb">object</span><span class="p">):</span>
    <span class="k">pass</span>

<span class="k">def</span> <span class="nf">greet</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">message</span><span class="p">):</span>
    <span class="k">print</span><span class="p">(</span><span class="n">message</span><span class="p">)</span>

<span class="n">bind_method</span><span class="p">(</span><span class="n">Greeter</span><span class="p">,</span> <span class="s">&#39;greet&#39;</span><span class="p">,</span> <span class="n">greet</span><span class="p">)</span>

<span class="n">g</span> <span class="o">=</span> <span class="n">Greeter</span><span class="p">()</span>
<span class="n">g</span><span class="o">.</span><span class="n">greet</span><span class="p">(</span><span class="s">&#39;Hi!&#39;</span><span class="p">)</span>
</pre></div>
</div>
<p>On Python 3, calling <code class="docutils literal"><span class="pre">bind_method(cls,</span> <span class="pre">name,</span> <span class="pre">func)</span></code> is equivalent to
calling <code class="docutils literal"><span class="pre">setattr(cls,</span> <span class="pre">name,</span> <span class="pre">func)</span></code>. On Python 2 it is equivalent to:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">types</span>
<span class="nb">setattr</span><span class="p">(</span><span class="n">cls</span><span class="p">,</span> <span class="n">name</span><span class="p">,</span> <span class="n">types</span><span class="o">.</span><span class="n">MethodType</span><span class="p">(</span><span class="n">func</span><span class="p">,</span> <span class="bp">None</span><span class="p">,</span> <span class="n">cls</span><span class="p">))</span>
</pre></div>
</div>
</div>
<div class="section" id="metaclasses">
<h2>Metaclasses<a class="headerlink" href="#metaclasses" title="Permalink to this headline">¶</a></h2>
<p>Python 3 and Python 2 syntax for metaclasses are incompatible.
<code class="docutils literal"><span class="pre">future</span></code> provides a function (from <code class="docutils literal"><span class="pre">jinja2/_compat.py</span></code>) called
<code class="xref py py-func docutils literal"><span class="pre">with_metaclass()</span></code> that can assist with specifying metaclasses
portably across Py3 and Py2. Use it like this:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">future.utils</span> <span class="kn">import</span> <span class="n">with_metaclass</span>

<span class="k">class</span> <span class="nc">BaseForm</span><span class="p">(</span><span class="nb">object</span><span class="p">):</span>
    <span class="k">pass</span>

<span class="k">class</span> <span class="nc">FormType</span><span class="p">(</span><span class="nb">type</span><span class="p">):</span>
    <span class="k">pass</span>

<span class="k">class</span> <span class="nc">Form</span><span class="p">(</span><span class="n">with_metaclass</span><span class="p">(</span><span class="n">FormType</span><span class="p">,</span> <span class="n">BaseForm</span><span class="p">)):</span>
    <span class="k">pass</span>
</pre></div>
</div>
</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>