What are the “best practices” for using import in a module?
PythonLevel: Intermediate
What are the “best practices” for using import in a module?
Hints
- Identify object types, mutability and execution order.
- Trace a minimal example: which values and references change?
Answer
In general, don’t use from modulename import *. Doing so clutters the
importer’s namespace, and makes it much harder for linters to detect undefined
names.
Import modules at the top of a file. Doing so makes it clear what other modules your code requires and avoids questions of whether the module name is in scope. Using one import per line makes it easy to add and delete module imports, but using multiple imports per line uses less screen space.
It’s good practice if you import modules in the following order:
-
third-party library modules (anything installed in Python’s site-packages directory) – e.g.
dateutil,requests,PIL.Image -
locally developed modules
It is sometimes necessary to move imports to a function or class to avoid problems with circular imports. Gordon McMillan says:
Circular imports are fine where both modules use the “import ” form of import. They fail when the 2nd module wants to grab a name out of the first (“from module import name”) and the import is at the top level. That’s because names in the 1st are not yet available, because the first module is busy importing the 2nd.
In this case, if the second module is only used in one function, then the import can easily be moved into that function. By the time the import is called, the first module will have finished initializing, and the second module can do its import.
It may also be necessary to move imports out of the top level of code if some of the modules are platform-specific. In that case, it may not even be possible to import all of the modules at the top of the file. In this case, importing the correct modules in the corresponding platform-specific code is a good option.
Only move imports into a local scope, such as inside a function definition, if
it’s necessary to solve a problem such as avoiding a circular import or are
trying to reduce the initialization time of a module. This technique is
especially helpful if many of the imports are unnecessary depending on how the
program executes. You may also want to move imports into a function if the
modules are only ever used in that function. Note that loading a module the
first time may be expensive because of the one time initialization of the
module, but loading a module multiple times is virtually free, costing only a
couple of dictionary lookups. Even if the module name has gone out of scope,
the module is probably available in sys.modules.
Source and licence: Python 3.14.0 Programming FAQ — Python Software Foundation · PSF-2.0