python-peps/pep-0328.txt

PEP: 328
Title: Imports: Multi-Line and Absolute/Relative
Version: $Revision$
Last-Modified: $Date$
Author: Aahz <aahz@pythoncraft.com>
Status: Accepted
Type: Standards Track
Python-Version: 2.4
Content-Type: text/x-rst
Created: 21-Dec-2003
Post-History: 8-Mar-2004


Abstract
========

The ``import`` statement has two problems:

* Long ``import`` statements can be difficult to write, requiring
  various contortions to fit Pythonic style guidelines.

* Imports can be ambiguous in the face of packages; within a package,
  it's not clear whether ``import foo`` refers to a module within the
  package or some module outside the package.

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 (more precisely,
relative to ``sys.path``) with special syntax for accessing
package-relative imports.


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:

* Write a long line with backslash continuations::

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

* Write multiple ``import`` statements::

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

(``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 already has BDFL approval.


Rationale for Absolute Imports
==============================

In current Python, 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.
To resolve the ambiguity, it is proposed that ``foo`` will always be a
module or package reachable from ``sys.path``.

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

    from __future__ import absolute_import

This PEP will be updated when it is decided to make absolute imports
the default, probably Python 2.5 or 2.6.

This part of the proposal already has BDFL approval.


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:

* One from Guido::

      from .foo import bar

  and ::

      from ...foo import bar

  These two forms have a couple of different suggested semantics.  One
  semantic is to make each dot represent one level.  There have been
  many complaints about the difficulty of counting dots.  Another
  option is to only allow one level of relative import.  That misses a
  lot of functionality, and people still complained about missing the
  dot in the one-dot form.  The final option is to define an algorithm
  for finding relative modules and packages; the objection here is
  "Explicit is better than implicit".  (The algorithm proposed is
  "search up from current package directory until the ultimate package
  parent gets hit".)

  Some people have suggested other punctuation as the separator, such
  as "-" or "^".

  Some people have suggested using "*"::

      from *.foo import bar

* The next set of options is conflated from several posters::

      from __pkg__.__pkg__ import

  and ::

      from .__parent__.__parent__ import

  Many people (Guido included) think these look ugly, but they *are*
  clear and explicit.  Overall, more people prefer ``__pkg__`` as the
  shorter option.

* One suggestion was to allow only sibling references.  In other words,
  you would not be able to use relative imports to refer to modules
  higher in the package tree.  You would then be able to do either ::

      from .spam import eggs

  or ::

      import .spam.eggs

* Some people favor allowing indexed parents::

      from -2.spam import eggs

  In this scenario, importing from the current directory would be a
  simple ::

      from .spam import eggs


* Finally, some people dislike the way you have to change ``import``
  to ``from ... import`` when you want to dig inside a package.  They
  suggest completely rewriting the ``import`` syntax::

      from MODULE import NAMES as RENAME searching HOW

  or ::

      import NAMES as RENAME from MODULE searching HOW
          [from NAMES] [in WHERE] import ...

  However, this most likely could not be implemented for Python 2.4
  (too big a change), and allowing relative imports is sufficiently
  critical that we need something now (given that the standard
  ``import`` will change to absolute import).  More than that, this
  proposed syntax has several open questions:

  - What is the precise proposed syntax?  (Which clauses are optional
    under which circumstances?)

  - How strongly does the ``searching`` clause bind?  In other words,
    do you write::

        import foo as bar searching XXX, spam as ham searching XXX

    or::

        import foo as bar, spam as ham searching XXX


Guido's Decision
================

Guido has Pronounced [1]_ that relative imports will use leading dots,
one per level of parent.


References
==========

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

- `Re: Christmas Wishlist
  <http://mail.python.org/pipermail/python-dev/2003-December/040973.html>`__

- `Re: Python-Dev Digest, Vol 5, Issue 57
  <http://mail.python.org/pipermail/python-dev/2003-December/041078.html>`__

- `Relative import
  <http://mail.python.org/pipermail/python-dev/2003-December/041065.html>`__

- `Another Strategy for Relative Import
  <http://mail.python.org/pipermail/python-dev/2003-December/041418.html>`__

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


Copyright
=========

This document has been placed in the public domain.


..
   Local Variables:
   mode: indented-text
   indent-tabs-mode: nil
   sentence-end-double-space: t
   fill-column: 70
   End: