Add clarifying comments for import_modules usage (#23935)

12 files changed, 29 insertions, 19 deletions

diff --git a/var/spack/repos/builtin/packages/py-cartopy/package.py b/var/spack/repos/builtin/packages/py-cartopy/package.py
index 39bbc32415..35f9bf6638 100644
--- a/var/spack/repos/builtin/packages/py-cartopy/package.py
+++ b/var/spack/repos/builtin/packages/py-cartopy/package.py
@@ -14,7 +14,7 @@ class PyCartopy(PythonPackage):
 
     maintainers = ['adamjstewart']
 
-    # Skip test files in cartopy.tests
+    # Tests require extra dependencies, skip them in 'import_modules'
     import_modules = [
         'cartopy', 'cartopy.sphinxext', 'cartopy.io', 'cartopy.geodesic',
         'cartopy.examples', 'cartopy.mpl', 'cartopy.feature'
diff --git a/var/spack/repos/builtin/packages/py-google-api-core/package.py b/var/spack/repos/builtin/packages/py-google-api-core/package.py
index b0fff59ac0..bf0eb23d63 100644
--- a/var/spack/repos/builtin/packages/py-google-api-core/package.py
+++ b/var/spack/repos/builtin/packages/py-google-api-core/package.py
@@ -12,8 +12,8 @@ class PyGoogleApiCore(PythonPackage):
     homepage = "https://github.com/GoogleCloudPlatform/google-cloud-python"
     pypi = "google-api-core/google-api-core-1.14.2.tar.gz"
 
-    # google.api_core.operations_v1 and google.api_core.gapic_v1 require
-    # grpc optional dependency
+    # 'google.api_core.operations_v1' and 'google.api_core.gapic_v1' require 'grpc'.
+    # Leave them out of 'import_modules' to avoid optional dependency.
     import_modules = ['google.api_core', 'google.api_core.future']
 
     version('1.14.2', sha256='2c23fbc81c76b941ffb71301bb975ed66a610e9b03f918feacd1ed59cf43a6ec')
diff --git a/var/spack/repos/builtin/packages/py-ipython/package.py b/var/spack/repos/builtin/packages/py-ipython/package.py
index e889a1ff80..7843ba3559 100644
--- a/var/spack/repos/builtin/packages/py-ipython/package.py
+++ b/var/spack/repos/builtin/packages/py-ipython/package.py
@@ -10,7 +10,8 @@ class PyIpython(PythonPackage):
 
     pypi = "ipython/ipython-7.18.1.tar.gz"
 
-    # IPython.kernel is deprecated and fails to import
+    # 'IPython.kernel' is deprecated and fails to import, leave out of 'import_modules'
+    # to ensure that import tests pass.
     import_modules = [
         'IPython', 'IPython.core', 'IPython.core.tests', 'IPython.core.magics',
         'IPython.sphinxext', 'IPython.terminal',
diff --git a/var/spack/repos/builtin/packages/py-joblib/package.py b/var/spack/repos/builtin/packages/py-joblib/package.py
index c8d4139dfa..bab10e2c88 100644
--- a/var/spack/repos/builtin/packages/py-joblib/package.py
+++ b/var/spack/repos/builtin/packages/py-joblib/package.py
@@ -12,7 +12,8 @@ class PyJoblib(PythonPackage):
     homepage = "https://joblib.readthedocs.io/"
     pypi = "joblib/joblib-0.14.0.tar.gz"
 
-    # 'joblib.test' requires 'pytest'
+    # 'joblib.test' requires 'pytest'. Leave out of 'import_modules' to avoid
+    # unnecessary dependencies.
     import_modules = [
         'joblib', 'joblib.externals', 'joblib.externals.cloudpickle',
         'joblib.externals.loky', 'joblib.externals.loky.backend'
diff --git a/var/spack/repos/builtin/packages/py-sphinxcontrib-applehelp/package.py b/var/spack/repos/builtin/packages/py-sphinxcontrib-applehelp/package.py
index ae12f64e14..0051b2541e 100644
--- a/var/spack/repos/builtin/packages/py-sphinxcontrib-applehelp/package.py
+++ b/var/spack/repos/builtin/packages/py-sphinxcontrib-applehelp/package.py
@@ -13,8 +13,9 @@ class PySphinxcontribApplehelp(PythonPackage):
     homepage = "http://sphinx-doc.org/"
     pypi = "sphinxcontrib-applehelp/sphinxcontrib-applehelp-1.0.1.tar.gz"
 
-    # Sphinx requires sphinxcontrib-applehelp at build-time, but
-    # sphinxcontrib-applehelp requires sphinx at run-time
+    # 'sphinx' requires 'sphinxcontrib-applehelp' at build-time, but
+    # 'sphinxcontrib-applehelp' requires 'sphinx' at run-time. Don't bother trying to
+    # import any modules for this package.
     import_modules = []
 
     version('1.0.1', sha256='edaa0ab2b2bc74403149cb0209d6775c96de797dfd5b5e2a71981309efab3897')
diff --git a/var/spack/repos/builtin/packages/py-sphinxcontrib-devhelp/package.py b/var/spack/repos/builtin/packages/py-sphinxcontrib-devhelp/package.py
index 488dd07c08..0cbe377807 100644
--- a/var/spack/repos/builtin/packages/py-sphinxcontrib-devhelp/package.py
+++ b/var/spack/repos/builtin/packages/py-sphinxcontrib-devhelp/package.py
@@ -13,8 +13,9 @@ class PySphinxcontribDevhelp(PythonPackage):
     homepage = "http://sphinx-doc.org/"
     pypi = "sphinxcontrib-devhelp/sphinxcontrib-devhelp-1.0.1.tar.gz"
 
-    # Sphinx requires sphinxcontrib-devhelp at build-time, but
-    # sphinxcontrib-devhelp requires sphinx at run-time
+    # 'sphinx' requires 'sphinxcontrib-devhelp' at build-time, but
+    # 'sphinxcontrib-devhelp' requires 'sphinx' at run-time. Don't bother trying to
+    # import any modules.
     import_modules = []
 
     version('1.0.1', sha256='6c64b077937330a9128a4da74586e8c2130262f014689b4b89e2d08ee7294a34')
diff --git a/var/spack/repos/builtin/packages/py-sphinxcontrib-htmlhelp/package.py b/var/spack/repos/builtin/packages/py-sphinxcontrib-htmlhelp/package.py
index 1199b88a5a..db7cd3884a 100644
--- a/var/spack/repos/builtin/packages/py-sphinxcontrib-htmlhelp/package.py
+++ b/var/spack/repos/builtin/packages/py-sphinxcontrib-htmlhelp/package.py
@@ -13,8 +13,9 @@ class PySphinxcontribHtmlhelp(PythonPackage):
     homepage = "http://sphinx-doc.org/"
     pypi = "sphinxcontrib-htmlhelp/sphinxcontrib-htmlhelp-1.0.2.tar.gz"
 
-    # Sphinx requires sphinxcontrib-htmlhelp at build-time, but
-    # sphinxcontrib-htmlhelp requires sphinx at run-time
+    # 'sphinx' requires 'sphinxcontrib-htmlhelp' at build-time, but
+    # 'sphinxcontrib-htmlhelp' requires 'sphinx' at run-time. Don't bother trying to
+    # import any modules.
     import_modules = []
 
     version('1.0.2', sha256='4670f99f8951bd78cd4ad2ab962f798f5618b17675c35c5ac3b2132a14ea8422')
diff --git a/var/spack/repos/builtin/packages/py-sphinxcontrib-jsmath/package.py b/var/spack/repos/builtin/packages/py-sphinxcontrib-jsmath/package.py
index 501cd16fae..115a3678b8 100644
--- a/var/spack/repos/builtin/packages/py-sphinxcontrib-jsmath/package.py
+++ b/var/spack/repos/builtin/packages/py-sphinxcontrib-jsmath/package.py
@@ -12,8 +12,9 @@ class PySphinxcontribJsmath(PythonPackage):
     homepage = "http://sphinx-doc.org/"
     pypi = "sphinxcontrib-jsmath/sphinxcontrib-jsmath-1.0.1.tar.gz"
 
-    # Sphinx requires sphinxcontrib-jsmath at build-time, but
-    # sphinxcontrib-jsmath requires sphinx at run-time
+    # 'sphinx' requires 'sphinxcontrib-jsmath' at build-time, but
+    # 'sphinxcontrib-jsmath' requires 'sphinx' at run-time. Don't bother trying to
+    # import any modules.
     import_modules = []
 
     version('1.0.1', sha256='a9925e4a4587247ed2191a22df5f6970656cb8ca2bd6284309578f2153e0c4b8')
diff --git a/var/spack/repos/builtin/packages/py-sphinxcontrib-qthelp/package.py b/var/spack/repos/builtin/packages/py-sphinxcontrib-qthelp/package.py
index 75be7ed6a2..5907734984 100644
--- a/var/spack/repos/builtin/packages/py-sphinxcontrib-qthelp/package.py
+++ b/var/spack/repos/builtin/packages/py-sphinxcontrib-qthelp/package.py
@@ -13,8 +13,9 @@ class PySphinxcontribQthelp(PythonPackage):
     homepage = "http://sphinx-doc.org/"
     pypi = "sphinxcontrib-qthelp/sphinxcontrib-qthelp-1.0.2.tar.gz"
 
-    # Sphinx requires sphinxcontrib-qthelp at build-time, but
-    # sphinxcontrib-qthelp requires sphinx at run-time
+    # 'sphinx' requires 'sphinxcontrib-qthelp' at build-time, but
+    # 'sphinxcontrib-qthelp' requires 'sphinx' at run-time. Don't bother trying to
+    # import any modules.
     import_modules = []
 
     version('1.0.2', sha256='79465ce11ae5694ff165becda529a600c754f4bc459778778c7017374d4d406f')
diff --git a/var/spack/repos/builtin/packages/py-sphinxcontrib-serializinghtml/package.py b/var/spack/repos/builtin/packages/py-sphinxcontrib-serializinghtml/package.py
index 555f05a069..ba89a9b888 100644
--- a/var/spack/repos/builtin/packages/py-sphinxcontrib-serializinghtml/package.py
+++ b/var/spack/repos/builtin/packages/py-sphinxcontrib-serializinghtml/package.py
@@ -13,8 +13,9 @@ class PySphinxcontribSerializinghtml(PythonPackage):
     homepage = "http://sphinx-doc.org/"
     pypi = "sphinxcontrib-serializinghtml/sphinxcontrib-serializinghtml-1.1.3.tar.gz"
 
-    # Sphinx requires sphinxcontrib-serializinghtml at build-time, but
-    # sphinxcontrib-serializinghtml requires sphinx at run-time
+    # 'sphinx' requires 'sphinxcontrib-serializinghtml' at build-time, but
+    # 'sphinxcontrib-serializinghtml' requires 'sphinx' at run-time. Don't bother trying
+    # to import any modules.
     import_modules = []
 
     version('1.1.3', sha256='c0efb33f8052c04fd7a26c0a07f1678e8512e0faec19f4aa8f2473a8b81d5227')
diff --git a/var/spack/repos/builtin/packages/py-torch/package.py b/var/spack/repos/builtin/packages/py-torch/package.py
index cb40d25f0a..4115f4baf3 100644
--- a/var/spack/repos/builtin/packages/py-torch/package.py
+++ b/var/spack/repos/builtin/packages/py-torch/package.py
@@ -16,7 +16,8 @@ class PyTorch(PythonPackage, CudaPackage):
 
     maintainers = ['adamjstewart']
 
-    # Exact set of modules is version- and variant-specific
+    # Exact set of modules is version- and variant-specific, just attempt to import the
+    # core libraries to ensure that the package was successfully installed.
     import_modules = ['torch', 'torch.autograd', 'torch.nn', 'torch.utils']
 
     version('master', branch='master', submodules=True)
diff --git a/var/spack/repos/builtin/packages/py-xarray/package.py b/var/spack/repos/builtin/packages/py-xarray/package.py
index ff2cfe88c0..ba2cef62ab 100644
--- a/var/spack/repos/builtin/packages/py-xarray/package.py
+++ b/var/spack/repos/builtin/packages/py-xarray/package.py
@@ -12,7 +12,8 @@ class PyXarray(PythonPackage):
     homepage = "https://github.com/pydata/xarray"
     pypi = "xarray/xarray-0.9.1.tar.gz"
 
-    # 'xarray.tests' requires pytest
+    # 'xarray.tests' requires 'pytest'. Leave out of 'import_modules' to avoid
+    # unnecessary dependency.
     import_modules = [
         'xarray', 'xarray.core', 'xarray.plot', 'xarray.util',
         'xarray.backends', 'xarray.coding'