module_imports.rst

Module imports in MDAnalysis

We are striving to keep module dependencies small and lightweight (i.e., easily installable with pip).

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:

  • future (from __future__ import absolute_import, print_function, division)
  • Compatibility imports (e.g. six)
  • global imports (installed packages)
  • local imports (MDAnalysis modules)

• use absolute imports in the library (i.e. relative imports must be explicitly indicated)

For example:

from __future__ import absolute_import
from six.moves import range

import numpy as np

import .core
import ..units

Module imports in :mod:`MDAnalysis.analysis`

1. In :mod:`MDAnalysis.analysis`, all imports must be at the top level (as in the General Rule) — see Issue 666 for more information.
2. :ref:`Optional modules <optional-modules>` can be imported
3. No analysis module is imported automatically at the :mod:`MDAnalysis.analysis` level to avoid breaking the installation when optional dependencies are missing.

Module imports in the test suite

• Use the module import order in :ref:`general-rules-for-importing`, but import :mod:`MDAnalysis` modules before :mod:`MDAnalysisTests` imports
• 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 :mod:`MDAnalysis` module from the __init__.py of :mod:`MDAnalysisTests` or from any of its plugins (it's ok to import from test files). Importing :mod:`MDAnalysis` from 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:

• :mod:`six`
• :mod:`numpy`
• :mod:`biopython`
• :mod:`gridDataFormats`
• :mod:`mmtf-python`
• :mod:`scipy`
• :mod:`matplotlib`

because these packages are always installed.

If you must depend on a new external package, first discuss its use on GitHub Discussions (Development) or as part of the issue/pull request.

Modules in the "core"

The core of MDAnalysis contains all packages that are not in :mod:`MDAnalysis.analysis` or :mod:`MDAnalysis.visualization`. Only packages in the :ref:`core-module-dependencies` can be imported.

Optional modules in :mod:`MDAnalysis.analysis` and :mod:`MDAnalysis.visualization`

Modules under :mod:`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 :ref:`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 try/except
• print and log a warning
• only raise an ImportError in the specific function or method that would depend on the missing module.