Coverage for nilearn/_utils/__init__.py: 23%
50 statements
« prev ^ index » next coverage.py v7.9.1, created at 2025-06-20 10:58 +0200
« prev ^ index » next coverage.py v7.9.1, created at 2025-06-20 10:58 +0200
1"""The :mod:`nilearn._utils` module provides utilities for developers."""
3import inspect
4import pkgutil
5import warnings
6from importlib import import_module
7from pathlib import Path
9from nilearn._utils.helpers import ( # noqa: F401
10 compare_version,
11 constrained_layout_kwargs,
12 remove_parameters,
13 rename_parameters,
14 stringify_path,
15)
17from .cache_mixin import CacheMixin
18from .docs import fill_doc
19from .logger import compose_err_msg
20from .niimg import load_niimg, repr_niimgs
21from .niimg_conversions import check_niimg, check_niimg_3d, check_niimg_4d
22from .numpy_conversions import as_ndarray
25def all_modules(modules_to_ignore=None, modules_to_consider=None):
26 """Get a list of all modules from nilearn.
28 This function returns a list of all modules from Nilearn.
30 .. note::
32 ``modules_to_ignore`` and ``modules_to_consider``
33 cannot be specified simultaneously.
35 Parameters
36 ----------
37 modules_to_ignore : :obj:`list` or :obj:`set` of :obj:`str` or None,\
38 default=None
39 List of modules to exclude from the listing.
41 .. note::
43 This function will ignore ``tests``, ``externals``, and ``data``
44 by default.
46 modules_to_consider : :obj:`list` or :obj:`set` of :obj:`str` or None,\
47 default=None
48 List of modules to include in the listing.
50 Returns
51 -------
52 all_modules : :obj:`list` of :obj:`str`
53 List of modules.
54 """
55 if modules_to_ignore is not None and modules_to_consider is not None:
56 raise ValueError(
57 "`modules_to_ignore` and `modules_to_consider` "
58 "cannot be both specified."
59 )
60 if modules_to_ignore is None:
61 modules_to_ignore = {"data", "tests", "externals", "conftest"}
62 all_modules = []
63 root = str(Path(__file__).parent.parent)
64 with warnings.catch_warnings():
65 warnings.simplefilter("ignore")
66 for _, modname, _ in pkgutil.walk_packages(
67 path=[root], prefix="nilearn."
68 ):
69 mod_parts = modname.split(".")
70 if modules_to_consider is None:
71 if (
72 all(part not in modules_to_ignore for part in mod_parts)
73 and "._" not in modname
74 ):
75 all_modules.append(modname)
76 elif mod_parts[-2] in modules_to_consider:
77 all_modules.append(modname)
78 return all_modules
81def all_functions(
82 return_private=False, modules_to_ignore=None, modules_to_consider=None
83):
84 """Get a list of all functions from nilearn.
86 This function returns a list of all functions defined in Nilearn.
88 .. note::
90 ``modules_to_ignore`` and ``modules_to_consider`` cannot
91 be specified simultaneously.
93 Parameters
94 ----------
95 return_private : :obj:`bool`
96 Whether to return also private functions or not.
97 Default=False.
99 modules_to_ignore : :obj:`list` or :obj:`set` of :obj:`str` or None,\
100 default=None
101 List of modules to exclude from the listing.
103 .. note::
105 This function will not list functions
106 from ``tests``, ``externals``, and ``data`` by default.
108 modules_to_consider : :obj:`list` or :obj:`set` of :obj:`str` or None,\
109 default=None
110 List of modules to consider for the listing.
113 Returns
114 -------
115 all_functions : List of Tuples (:obj:`str`, callable)
116 List of functions. Each element is a length 2 tuple
117 where the first element is the function name as a string,
118 and the second element is the function itself.
119 """
120 all_functions = []
121 modules = all_modules(
122 modules_to_ignore=modules_to_ignore,
123 modules_to_consider=modules_to_consider,
124 )
125 for modname in modules:
126 module = import_module(modname)
127 functions = [
128 (name, func)
129 for name, func in inspect.getmembers(module, inspect.isfunction)
130 if func.__module__ == module.__name__
131 ]
132 if not return_private:
133 functions = [
134 (name, func)
135 for name, func in functions
136 if not name.startswith("_")
137 ]
138 all_functions.extend(functions)
139 return all_functions
142def all_classes(
143 return_private=False, modules_to_ignore=None, modules_to_consider=None
144):
145 """Get a list of all classes from nilearn.
147 This function returns a list of all classes defined in Nilearn.
149 .. note::
151 ``modules_to_ignore`` and ``modules_to_consider`` cannot
152 be specified simultaneously.
154 Parameters
155 ----------
156 return_private : :obj:`bool`, default=False
157 Whether to return also private classes or not.
159 modules_to_ignore : :obj:`list` or :obj:`set` of :obj:`str` or None,\
160 default=None
161 List of modules to exclude from the listing.
163 .. note::
165 This function will not list classes from
166 ``tests``, ``externals``, and ``data`` by default.
168 modules_to_consider : :obj:`list` or :obj:`set` of :obj:`str` or None,\
169 default=None
170 List of modules to consider for the listing.
172 Returns
173 -------
174 all_classes : List of Tuples (:obj:`str`, callable)
175 List of classes.
176 Each element is a length 2 tuple
177 where the first element is the class name as a string,
178 and the second element is the class itself.
179 """
180 all_classes = []
181 modules = all_modules(
182 modules_to_ignore=modules_to_ignore,
183 modules_to_consider=modules_to_consider,
184 )
185 for modname in modules:
186 module = import_module(modname)
187 classes = [
188 (name, cls)
189 for name, cls in inspect.getmembers(module, inspect.isclass)
190 if cls.__module__ == module.__name__
191 ]
192 if not return_private:
193 classes = [
194 (name, cls)
195 for name, cls in classes
196 if not name.startswith("_")
197 ]
198 all_classes.extend(classes)
199 return all_classes
202__all__ = [
203 "CacheMixin",
204 "all_classes",
205 "all_functions",
206 "as_ndarray",
207 "check_niimg",
208 "check_niimg_3d",
209 "check_niimg_4d",
210 "compare_version",
211 "compose_err_msg",
212 "fill_doc",
213 "load_niimg",
214 "remove_parameters",
215 "rename_parameters",
216 "repr_niimgs",
217 "stringify_path",
218]