What are good rules of thumb for Python imports?

Question

I am a little confused by the multitude of ways in which you can import modules in Python.

import X import X as Y from A import B 

I have been reading up about scoping and namespaces, but I would like some practical advice on what is the best strategy, under which circumstances and why. Should imports happen at a module level or a method/function level? In the __init__.py or in the module code itself?

My question is not really answered by "Python packages - import by class, not file" although it is obviously related.

Answer 1

In production code in our company, we try to follow the following rules.

We place imports at the beginning of the file, right after the main file's docstring, e.g.:

""" Registry related functionality. """ import wx # ... 

Now, if we import a class that is one of few in the imported module, we import the name directly, so that in the code we only have to use the last part, e.g.:

from RegistryController import RegistryController from ui.windows.lists import ListCtrl, DynamicListCtrl 

There are modules, however, that contain dozens of classes, e.g. list of all possible exceptions. Then we import the module itself and reference to it in the code:

from main.core import Exceptions # ... raise Exceptions.FileNotFound() 

We use the import X as Y as rarely as possible, because it makes searching for usage of a particular module or class difficult. Sometimes, however, you have to use it if you wish to import two classes that have the same name, but exist in different modules, e.g.:

from Queue import Queue from main.core.MessageQueue import Queue as MessageQueue 

As a general rule, we don't do imports inside methods -- they simply make code slower and less readable. Some may find this a good way to easily resolve cyclic imports problem, but a better solution is code reorganization.

Answer 2

Let me just paste a part of conversation on django-dev mailing list started by Guido van Rossum:

[...] For example, it's part of the Google Python style guides[1] that all imports must import a module, not a class or function from that module. There are way more classes and functions than there are modules, so recalling where a particular thing comes from is much easier if it is prefixed with a module name. Often multiple modules happen to define things with the same name -- so a reader of the code doesn't have to go back to the top of the file to see from which module a given name is imported.

Source: http://groups.google.com/group/django-developers/browse_thread/thread/78975372cdfb7d1a

1: http://code.google.com/p/soc/wiki/PythonStyleGuide#Module_and_package_imports