Module imports in MDAnalysis¶
We are striving to keep module dependencies small and lightweight (i.e., easily installable with
General rules for importing¶
Imports should all happen at the start of a module (not inside classes or functions).
Modules must be imported in the following order:
from __future__ import absolute_import, print_function, division)
Compatibility imports (e.g.
global imports (installed packages)
local imports (MDAnalysis modules)
use absolute imports in the library (i.e. relative imports must be explicitly indicated)
from __future__ import absolute_import from six.moves import range import numpy as np import .core import ..units
Module imports in
MDAnalysis.analysis, all imports must be at the top level (as in the General Rule) — see Issue 666 for more information.
Optional modules can be imported
No analysis module is imported automatically at the
MDAnalysis.analysislevel to avoid breaking the installation when optional dependencies are missing.
Module imports in the test suite¶
Use the module import order in General rules for importing, but import
Do not use relative imports (e.g.
import .datafiles) in the test suite. This breaks running the tests from inside the test directory (see Issue 189 for more information)
Never import the
MDAnalysismodule from the
MDAnalysisTestsor from any of its plugins (it’s ok to import from test files). Importing
MDAnalysisfrom the test setup code will cause severe coverage underestimation.
Module dependencies in the code¶
List of core module dependencies¶
Any module from the standard library can be used, as well as the following nonstandard libraries:
because these packages are always installed.
If you must depend on a new external package, first discuss its use on the developer mailing list or as part of the issue/pull request.
Modules in the “core”¶
The core of MDAnalysis contains all packages that are not in
MDAnalysis.visualization. Only packages in the List of core module dependencies can be imported.
Optional modules in
MDAnalysis.analysis are considered independent from the core package. Each analysis module can have its own set of dependencies. We strive to keep them small, but module authors are, in principle, free to import what they need. When analysis modules import packages outside of List of core module dependencies, the dependencies are considered optional (and should be listed in
setup.py under analysis). (See also Issue 1159 for more discussion.)
A user who does not have a specific optional package installed must still be able to import everything else in MDAnalysis. An analysis module may simply raise an
ImportError if a package is missing. However, it is recommended that the module should print and log an error message notifying the user that a specific additional package needs to be installed to use it.
If a large portion of the code in the module does not depend on a specific optional module then you should:
guard the import at the top level with a
print and log a warning
only raise an
ImportErrorin the specific function or method that would depend on the missing module.