[Python-Dev] Draft: PEP for imports

[Aahz]

Here's the draft PEP for imports.  I'll wait a few days for comments
before sending to the PEPmeister.

PEP: XXX
Title: Imports: multi-line and absolute/relative
Version: 
Last-Modified: 
Author: Aahz <aahz at pythoncraft.com
Status: Draft
Type: Standards Track
Python-Version: 2.4
Content-Type: text/x-rst
Created: 21-Dec-2003
Post-History: 


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
surround 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 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.

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

and

::

    from ...foo import

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 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.

*   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).


Open Issues
===========

The BDFL needs to decide which of the various options for relative
imports works best.  Additional proposals are still welcome.  As usual,
Guido prefers reasons to histrionics.



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>`_


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: