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.