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 MDAnalysis.analysis

  1. In MDAnalysis.analysis, all imports must be at the top level (as in the General Rule) — see Issue 666 for more information.

  2. Optional modules can be imported

  3. No analysis module is imported automatically at the 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 General rules for importing, but import MDAnalysis modules before 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 MDAnalysis module from the __init__.py of MDAnalysisTests or from any of its plugins (it’s ok to import from test files). Importing 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:

  • six

  • numpy

  • biopython

  • gridDataFormats

  • mmtf-python

  • scipy

  • 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 MDAnalysis.analysis or MDAnalysis.visualization. Only packages in the List of core module dependencies can be imported.

Optional modules in MDAnalysis.analysis and MDAnalysis.visualization

Modules under 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 try/except

  • print and log a warning

  • only raise an ImportError in the specific function or method that would depend on the missing module.