title: What does from __future__ import absolute_import actually do?
body: <p>I have <a href="https://stackoverflow.com/a/22679558/2588818">answered</a> a question regarding absolute imports in Python, which I thought I understood based on reading <a href="https://docs.python.org/2.5/whatsnew/pep-328.html" rel="noreferrer">the Python 2.5 changelog</a> and accompanying <a href="https://www.python.org/dev/peps/pep-0328/" rel="noreferrer">PEP</a>. However, upon installing Python 2.5 and attempting to craft an example of properly using <code>from __future__ import absolute_import</code>, I realize things are not so clear.</p>
  
  <p>Straight from the changelog linked above, this statement accurately summarized my understanding of the absolute import change:</p>
  
  <blockquote>
    <p>Let's say you have a package directory like this:</p>
  
  <pre><code>pkg/
  pkg/__init__.py
  pkg/main.py
  pkg/string.py
  </code></pre>
    
    <p>This defines a package named <code>pkg</code> containing the <code>pkg.main</code> and <code>pkg.string</code> submodules.</p>
    
    <p>Consider the code in the main.py module. What happens if it executes the statement <code>import string</code>? In Python 2.4 and earlier, it will first look in the package's directory to perform a relative import, finds pkg/string.py, imports the contents of that file as the <code>pkg.string</code> module, and that module is bound to the name <code>"string"</code> in the <code>pkg.main</code> module's namespace.</p>
  </blockquote>
  
  <p>So I created this exact directory structure:</p>
  
  <pre><code>$ ls -R
  .:
  pkg/
  
  ./pkg:
  __init__.py  main.py  string.py
  </code></pre>
  
  <p><code>__init__.py</code> and <code>string.py</code> are empty. <code>main.py</code> contains the following code:</p>
  
  <pre><code>import string
  print string.ascii_uppercase
  </code></pre>
  
  <p>As expected, running this with Python 2.5 fails with an <code>AttributeError</code>:</p>
  
  <pre><code>$ python2.5 pkg/main.py
  Traceback (most recent call last):
    File "pkg/main.py", line 2, in &lt;module&gt;
      print string.ascii_uppercase
  AttributeError: 'module' object has no attribute 'ascii_uppercase'
  </code></pre>
  
  <p>However, further along in the 2.5 changelog, we find this (emphasis added):</p>
  
  <blockquote>
    <p>In Python 2.5, you can switch <code>import</code>'s behaviour to absolute imports using a <code>from __future__ import absolute_import</code> directive. This absolute-import behaviour will become the default in a future version (probably Python 2.7). <strong>Once absolute imports are the default, <code>import string</code> will always find the standard library's version.</strong></p>
  </blockquote>
  
  <p>I thus created <code>pkg/main2.py</code>, identical to <code>main.py</code> but with the additional future import directive. It now looks like this:</p>
  
  <pre><code>from __future__ import absolute_import
  import string
  print string.ascii_uppercase
  </code></pre>
  
  <p>Running this with Python 2.5, however... fails with an <code>AttributeError</code>:</p>
  
  <pre><code>$ python2.5 pkg/main2.py
  Traceback (most recent call last):
    File "pkg/main2.py", line 3, in &lt;module&gt;
      print string.ascii_uppercase
  AttributeError: 'module' object has no attribute 'ascii_uppercase'
  </code></pre>
  
  <p>This pretty flatly contradicts the statement that <code>import string</code> will <strong>always</strong> find the std-lib version with absolute imports enabled. What's more, despite the warning that absolute imports are scheduled to become the "new default" behavior, I hit this same problem using both Python 2.7, with or without the <code>__future__</code> directive:</p>
  
  <pre><code>$ python2.7 pkg/main.py
  Traceback (most recent call last):
    File "pkg/main.py", line 2, in &lt;module&gt;
      print string.ascii_uppercase
  AttributeError: 'module' object has no attribute 'ascii_uppercase'
  
  $ python2.7 pkg/main2.py
  Traceback (most recent call last):
    File "pkg/main2.py", line 3, in &lt;module&gt;
      print string.ascii_uppercase
  AttributeError: 'module' object has no attribute 'ascii_uppercase'
  </code></pre>
  
  <p>as well as Python 3.5, with or without (assuming the <code>print</code> statement is changed in both files):</p>
  
  <pre><code>$ python3.5 pkg/main.py
  Traceback (most recent call last):
    File "pkg/main.py", line 2, in &lt;module&gt;
      print(string.ascii_uppercase)
  AttributeError: module 'string' has no attribute 'ascii_uppercase'
  
  $ python3.5 pkg/main2.py
  Traceback (most recent call last):
    File "pkg/main2.py", line 3, in &lt;module&gt;
      print(string.ascii_uppercase)
  AttributeError: module 'string' has no attribute 'ascii_uppercase'
  </code></pre>
  
  <hr>
  
  <p>I have tested other variations of this. Instead of <code>string.py</code>, I have created an empty module -- a directory named <code>string</code> containing only an empty <code>__init__.py</code> -- and instead of issuing imports from <code>main.py</code>, I have <code>cd</code>'d to <code>pkg</code> and run imports directly from the REPL. Neither of these variations (nor a combination of them) changed the results above. I cannot reconcile this with what I have read about the <code>__future__</code> directive and absolute imports.</p>
  
  <p>It seems to me that this is easily explicable by <a href="https://docs.python.org/2/library/sys.html#sys.path" rel="noreferrer">the following</a> (this is from the Python 2 docs but this statement remains unchanged in the same docs for Python 3):</p>
  
  <blockquote>
    <h3>sys.path</h3>
    
    <p>(...)</p>
    
    <p>As initialized upon program startup, the first item of this list, <code>path[0]</code>, is the directory containing the script that was used to invoke the Python interpreter. If the script directory is not available (e.g. if the interpreter is invoked interactively or if the script is read from standard input), <code>path[0]</code> is the empty string, <strong>which directs Python to search modules in the current directory first.</strong></p>
  </blockquote>
  
  <p>So what am I missing? Why does the <code>__future__</code> statement seemingly not do what it says, and what is the resolution of this contradiction between these two sections of documentation, as well as between described and actual behavior?</p>