Coverage for src/_griffe/importer.py: 96.08%

1# This module contains utilities to dynamically import objects. 

2# These utilities are used by our [`Inspector`][griffe.Inspector] to dynamically import objects 

3# specified as Python paths, like `package.module.Class.method`. 

4 

5from __future__ import annotations 

6 

7import sys 

8from contextlib import contextmanager 

9from importlib import import_module 

10from typing import TYPE_CHECKING, Any, Iterator, Sequence 

11 

12if TYPE_CHECKING: 

13 from pathlib import Path 

14 

15 

16def _error_details(error: BaseException, objpath: str) -> str: 

17 return f"With sys.path = {sys.path!r}, accessing {objpath!r} raises {error.__class__.__name__}: {error}" 

18 

19 

20@contextmanager 

21def sys_path(*paths: str | Path) -> Iterator[None]: 

22 """Redefine `sys.path` temporarily. 

23 

24 Parameters: 

25 *paths: The paths to use when importing modules. 

26 If no paths are given, keep `sys.path` untouched. 

27 

28 Yields: 

29 Nothing. 

30 """ 

31 if not paths: 

32 yield 

33 return 

34 old_path = sys.path 

35 sys.path = [str(path) for path in paths] 

36 try: 

37 yield 

38 finally: 

39 sys.path = old_path 

40 

41 

42def dynamic_import(import_path: str, import_paths: Sequence[str | Path] | None = None) -> Any: 

43 """Dynamically import the specified object. 

44 

45 It can be a module, class, method, function, attribute, 

46 nested arbitrarily. 

47 

48 It works like this: 

49 

50 - for a given object path `a.b.x.y` 

51 - it tries to import `a.b.x.y` as a module (with `importlib.import_module`) 

52 - if it fails, it tries again with `a.b.x`, storing `y` 

53 - then `a.b`, storing `x.y` 

54 - then `a`, storing `b.x.y` 

55 - if nothing worked, it raises an error 

56 - if one of the iteration worked, it moves on, and... 

57 - it tries to get the remaining (stored) parts with `getattr` 

58 - for example it gets `b` from `a`, then `x` from `b`, etc. 

59 - if a single attribute access fails, it raises an error 

60 - if everything worked, it returns the last obtained attribute 

61 

62 Since the function potentially tries multiple things before succeeding, 

63 all errors happening along the way are recorded, and re-emitted with 

64 an `ImportError` when it fails, to let users know what was tried. 

65 

66 IMPORTANT: The paths given through the `import_paths` parameter are used 

67 to temporarily patch `sys.path`: this function is therefore not thread-safe. 

68 

69 IMPORTANT: The paths given as `import_paths` must be *correct*. 

70 The contents of `sys.path` must be consistent to what a user of the imported code 

71 would expect. Given a set of paths, if the import fails for a user, it will fail here too, 

72 with potentially unintuitive errors. If we wanted to make this function more robust, 

73 we could add a loop to "roll the window" of given paths, shifting them to the left 

74 (for example: `("/a/a", "/a/b", "/a/c/")`, then `("/a/b", "/a/c", "/a/a/")`, 

75 then `("/a/c", "/a/a", "/a/b/")`), to make sure each entry is given highest priority 

76 at least once, maintaining relative order, but we deem this unnecessary for now. 

77 

78 Parameters: 

79 import_path: The path of the object to import. 

80 import_paths: The (sys) paths to import the object from. 

81 

82 Raises: 

83 ModuleNotFoundError: When the object's module could not be found. 

84 ImportError: When there was an import error or when couldn't get the attribute. 

85 

86 Returns: 

87 The imported object. 

88 """ 

89 module_parts: list[str] = import_path.split(".") 

90 object_parts: list[str] = [] 

91 errors = [] 

92 

93 with sys_path(*(import_paths or ())): 

94 while module_parts: 

95 module_path = ".".join(module_parts) 

96 try: 

97 module = import_module(module_path) 

98 except BaseException as error: # noqa: BLE001 

99 # pyo3's PanicException can only be caught with BaseException. 

100 # We do want to catch base exceptions anyway (exit, interrupt, etc.). 

101 errors.append(_error_details(error, module_path)) 

102 object_parts.insert(0, module_parts.pop(-1)) 

103 else: 

104 break 

105 else: 

106 raise ImportError("; ".join(errors)) 

107 

108 # Sometimes extra dependencies are not installed, 

109 # so importing the leaf module fails with a ModuleNotFoundError, 

110 # or later `getattr` triggers additional code that fails. 

111 # In these cases, and for consistency, we always re-raise an ImportError 

112 # instead of an any other exception (it's called "dynamic import" after all). 

113 # See https://github.com/mkdocstrings/mkdocstrings/issues/380 

114 value = module 

115 for part in object_parts: 

116 try: 

117 value = getattr(value, part) 

118 except BaseException as error: # noqa: BLE001 

119 errors.append(_error_details(error, module_path + ":" + ".".join(object_parts))) 

120 raise ImportError("; ".join(errors)) # noqa: B904 

121 

122 return value