GNU Info

(python2.1-tut.info)Importing * From a Package

---

Next: Intra-package References Prev: Packages Up: Packages

---

Enter node , (file) or (file)node

Importing * From a Package
--------------------------

Now what happens when the user writes `from Sound.Effects import *'?
Ideally, one would hope that this somehow goes out to the filesystem,
finds which submodules are present in the package, and imports them
all.  Unfortunately, this operation does not work very well on Mac and
Windows platforms, where the filesystem does not always have accurate
information about the case of a filename!  On these platforms, there is
no guaranteed way to know whether a file `ECHO.PY' should be imported
as a module `echo', `Echo' or `ECHO'.  (For example, Windows 95 has the
annoying practice of showing all file names with a capitalized first
letter.)  The DOS 8+3 filename restriction adds another interesting
problem for long module names.

The only solution is for the package author to provide an explicit
index of the package.  The import statement uses the following
convention: if a package's `__init__.py' code defines a list named
`__all__', it is taken to be the list of module names that should be
imported when `from PACKAGE import *' is encountered.  It is up to the
package author to keep this list up-to-date when a new version of the
package is released.  Package authors may also decide not to support
it, if they don't see a use for importing * from their package.  For
example, the file `Sounds/Effects/__init__.py' could contain the
following code:

     __all__ = ["echo", "surround", "reverse"]

This would mean that `from Sound.Effects import *' would import the
three named submodules of the `Sound' package.

If `__all__' is not defined, the statement `from Sound.Effects import
*' does _not_ import all submodules from the package `Sound.Effects'
into the current namespace; it only ensures that the package
`Sound.Effects' has been imported (possibly running its initialization
code, `__init__.py') and then imports whatever names are defined in the
package.  This includes any names defined (and submodules explicitly
loaded) by `__init__.py'.  It also includes any submodules of the
package that were explicitly loaded by previous import statements, e.g.

     import Sound.Effects.echo
     import Sound.Effects.surround
     from Sound.Effects import *

In this example, the echo and surround modules are imported in the
current namespace because they are defined in the `Sound.Effects'
package when the `from...import' statement is executed.  (This also
works when `__all__' is defined.)

Note that in general the practicing of importing * from a module or
package is frowned upon, since it often causes poorly readable code.
However, it is okay to use it to save typing in interactive sessions,
and certain modules are designed to export only names that follow
certain patterns.

Remember, there is nothing wrong with using `from Package import
specific_submodule'!  In fact, this is the recommended notation unless
the importing module needs to use submodules with the same name from
different packages.