PEP:328
Title:Imports: Multi-Line and Absolute/Relative
Version:1811
Last-Modified:2004-05-02 09:32:32 -0700 (Sun, 02 May 2004)
Author:Aahz <aahz at pythoncraft.com>
Status:Accepted
Type:Standards Track
Python-Version:2.4, 2,5, 2.6
Content-Type:text/x-rst
Created:21-Dec-2003
Post-History:8-Mar-2004

Contents

Abstract

The import statement has two problems:

For the first problem, it is proposed that parentheses be permitted to enclose multiple names, thus allowing Python's standard mechanisms for multi-line values to apply. For the second problem, it is proposed that all import statements be absolute by default (searching sys.path only) with special syntax (leading dots) for accessing package-relative imports.

Timeline

In Python 2.4, you must enable the new absolute import behavior with

from __future__ import absolute_import

You may use relative imports freely. In Python 2.5, any import statement that results in an intra-package import will raise DeprecationWarning (this also applies to from <> import that fails to use the relative import syntax). In Python 2.6, import will always be an absolute import (and the __future__ directive will no longer be needed).

Rationale for Parentheses

Currently, if you want to import a lot of names from a module or package, you have to choose one of several unpalatable options:

(import * is not an option ;-)

Instead, it should be possible to use Python's standard grouping mechanism (parentheses) to write the import statement:

from Tkinter import (Tk, Frame, Button, Entry, Canvas, Text,
    LEFT, DISABLED, NORMAL, RIDGE, END)

This part of the proposal had BDFL approval from the beginning.

Rationale for Absolute Imports

In Python 2.3 and earlier, if you're reading a module located inside a package, it is not clear whether

import foo

refers to a top-level module or to another module inside the package. As Python's library expands, more and more existing package internal modules suddenly shadow standard library modules by accident. It's a particularly difficult problem inside packages because there's no way to specify which module is meant. To resolve the ambiguity, it is proposed that foo will always be a module or package reachable from sys.path. This is called an absolute import.

The python-dev community chose absolute imports as the default because they're the more common use case and because absolute imports can provide all the functionality of relative (intra-package) imports -- albeit at the cost of difficulty when renaming package pieces higher up in the hierarchy or when moving one package inside another.

Because this represents a change in semantics, absolute imports will be optional in Python 2.4 and 2.5 through the use of

from __future__ import absolute_import

This part of the proposal had BDFL approval from the beginning.

Rationale for Relative Imports

With the shift to absolute imports, the question arose whether relative imports should be allowed at all. Several use cases were presented, the most important of which is being able to rearrange the structure of large packages without having to edit sub-packages. In addition, a module inside a package can't easily import itself without relative imports.

Guido approved of the idea of relative imports, but there has been a lot of disagreement on the spelling (syntax). There does seem to be agreement that relative imports will require listing specific names to import (that is, import foo as a bare term will always be an absolute import).

Here are the contenders:

Guido's Decision

Guido has Pronounced [1] that relative imports will use leading dots. A single leading dot indicates a relative import, starting with the current package. Two or more leading dots give a relative import to the parent(s) of the current package, one level per dot after the first. Here's a sample package layout:

package/
    __init__.py
    subpackage1/
        __init__.py
        moduleX.py
        moduleY.py
    subpackage2/
        __init__.py
        moduleZ.py
    moduleA.py

Assuming that the current file is either moduleX.py or subpackage1/__init__.py, following are correct usages of the new syntax:

from .moduleY import spam
from .moduleY import spam as ham
from . import moduleY
from ..subpackage1 import moduleY
from ..subpackage2.moduleZ import eggs
from ..moduleA import foo
from ...package import bar
from ...sys import path

Note that while that last case is legal, it is certainly discouraged ("insane" was the word Guido used).

Relative imports must always use from <> import; import <> is always absolute. Of course, absolute imports can use from <> import by omitting the leading dots. The reason import .foo is prohibited is because after

import XXX.YYY.ZZZ

then

XXX.YYY.ZZZ

is usable in an expression. But

.moduleY

is not usable in an expression.

References

For more background, see the following python-dev threads:

[1]http://mail.python.org/pipermail/python-dev/2004-March/043739.html