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

1"""The :mod:`nilearn._utils` module provides utilities for developers.""" 

2 

3import inspect 

4import pkgutil 

5import warnings 

6from importlib import import_module 

7from pathlib import Path 

8 

9from nilearn._utils.helpers import ( # noqa: F401 

10 compare_version, 

11 constrained_layout_kwargs, 

12 remove_parameters, 

13 rename_parameters, 

14 stringify_path, 

15) 

16 

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 

23 

24 

25def all_modules(modules_to_ignore=None, modules_to_consider=None): 

26 """Get a list of all modules from nilearn. 

27 

28 This function returns a list of all modules from Nilearn. 

29 

30 .. note:: 

31 

32 ``modules_to_ignore`` and ``modules_to_consider`` 

33 cannot be specified simultaneously. 

34 

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. 

40 

41 .. note:: 

42 

43 This function will ignore ``tests``, ``externals``, and ``data`` 

44 by default. 

45 

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. 

49 

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 

79 

80 

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. 

85 

86 This function returns a list of all functions defined in Nilearn. 

87 

88 .. note:: 

89 

90 ``modules_to_ignore`` and ``modules_to_consider`` cannot 

91 be specified simultaneously. 

92 

93 Parameters 

94 ---------- 

95 return_private : :obj:`bool` 

96 Whether to return also private functions or not. 

97 Default=False. 

98 

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. 

102 

103 .. note:: 

104 

105 This function will not list functions 

106 from ``tests``, ``externals``, and ``data`` by default. 

107 

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. 

111 

112 

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 

140 

141 

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. 

146 

147 This function returns a list of all classes defined in Nilearn. 

148 

149 .. note:: 

150 

151 ``modules_to_ignore`` and ``modules_to_consider`` cannot 

152 be specified simultaneously. 

153 

154 Parameters 

155 ---------- 

156 return_private : :obj:`bool`, default=False 

157 Whether to return also private classes or not. 

158 

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. 

162 

163 .. note:: 

164 

165 This function will not list classes from 

166 ``tests``, ``externals``, and ``data`` by default. 

167 

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. 

171 

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 

200 

201 

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]