Section 12.4. Importing Modules

12.4. Importing Modules

12.4.1. The import Statement

Importing a module requires the use of the import statement, whose syntax is:

import module1  import module2[     : import moduleN

It is also possible to import multiple modules on the same line like this ...

import module1[, module2[,... moduleN]]

... but the resulting code is not as readable as having multiple import statements. Also, there is no performance hit and no change in the way that the Python bytecode is generated, so by all means, use the first form, which is the preferred form.

Core Style: Module ordering for import statements

It is recommended that all module imports happen at the top of Python modules. Furthermore, imports should follow this ordering:

• Python Standard Library modules

• Python third party modules

• Application-specific modules

Separate these groups with an empty line between the imports of these three types of modules. This helps ensure that modules are imported in a consistent manner and helps minimize the number of import statements required in each of the modules. You can read more about this and other import tips in Python's Style Guide, written up as PEP 8.

When this statement is encountered by the interpreter, the module is imported if found in the search path. Scoping rules apply, so if imported from the top level of a module, it has global scope; if imported from a function, it has local scope.

When a module is imported the first time, it is loaded and executed.

12.4.2. The from-import Statement

It is possible to import specific module elements into your own module. By this, we really mean importing specific names from the module into the current namespace. For this purpose, we can use the from-import statement, whose syntax is:

from module import name1[, name2[,... nameN]]

12.4.3. Multi-Line Import

The multi-line import feature was added in Python 2.4 specifically for long from-import statements. When importing many attributes from the same module, import lines of code tend to get long and wrap, requiring a NEWLINE-escaping backslash. Here is the example imported (pun intended) directly from PEP 328:

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

Your other option is to have multiple from-import statements:

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

We are also trying to stem usage on the unfavored from Tkinter import * (see the Core Style sidebar in Section 12.5.3). Instead, programmers should be free to use Python's standard grouping mechanism (parentheses) to create a more reasonable multi-line import statement:

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

You can find out more about multi-line imports in the documentation or in PEP 328.

12.4.4. Extended Import Statement (as)

There are times when you are importing either a module or module attribute with a name that you are already using in your application, or perhaps it is a name that you do not want to use. Maybe the name is too long to type everywhere, or more subjectively, perhaps it is a name that you just plain do not like.

This had been a fairly common request from Python programmers: the ability to import modules and module attributes into a program using names other than their original given names. One common workaround is to assign the module name to a variable:

>>> import longmodulename >>> short = longmodulename >>> del longmodulename

In the example above, rather than using longmodulename.attribute, you would use the short.attribute to access the same object. (A similar analogy can be made with importing module attributes using from-import, see below.) However, to do this over and over again and in multiple modules can be annoying and seem wasteful. Using extended import, you can change the locally bound name for what you are importing. Statements like ...

      import Tkinter     from cgi import FieldStorage . . . can be replaced by . . .     import Tkinter as tk     from cgi import FieldStorage as form

This feature was added in Python 2.0. At that time, "as" was not implemented as a keyword; it finally became one in Python 2.6. For more information on extended import, see the Python Language Reference Manual and PEP 221.