imphookapi.py 19 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452
  1. #-----------------------------------------------------------------------------
  2. # Copyright (c) 2005-2021, PyInstaller Development Team.
  3. #
  4. # Distributed under the terms of the GNU General Public License (version 2
  5. # or later) with exception for distributing the bootloader.
  6. #
  7. # The full license is in the file COPYING.txt, distributed with this software.
  8. #
  9. # SPDX-License-Identifier: (GPL-2.0-or-later WITH Bootloader-exception)
  10. #-----------------------------------------------------------------------------
  11. """
  12. Classes facilitating communication between PyInstaller and import hooks.
  13. PyInstaller passes instances of classes defined by this module to corresponding functions defined by external import
  14. hooks, which commonly modify the contents of these instances before returning. PyInstaller then detects and converts
  15. these modifications into appropriate operations on the current `PyiModuleGraph` instance, thus modifying which
  16. modules will be frozen into the executable.
  17. """
  18. from PyInstaller.building.datastruct import TOC
  19. from PyInstaller.building.utils import format_binaries_and_datas
  20. from PyInstaller.lib.modulegraph.modulegraph import (RuntimeModule, RuntimePackage)
  21. class PreSafeImportModuleAPI(object):
  22. """
  23. Metadata communicating changes made by the current **pre-safe import module hook** (i.e., hook run immediately
  24. _before_ a call to `ModuleGraph._safe_import_module()` recursively adding the hooked module, package,
  25. or C extension and all transitive imports thereof to the module graph) back to PyInstaller.
  26. Pre-safe import module hooks _must_ define a `pre_safe_import_module()` function accepting an instance of this
  27. class, whose attributes describe the subsequent `ModuleGraph._safe_import_module()` call creating the hooked
  28. module's graph node.
  29. Each pre-safe import module hook is run _only_ on the first attempt to create the hooked module's graph node and
  30. then subsequently ignored. If this hook successfully creates that graph node, the subsequent
  31. `ModuleGraph._safe_import_module()` call will observe this fact and silently return without attempting to
  32. recreate that graph node.
  33. Pre-safe import module hooks are typically used to create graph nodes for **runtime modules** (i.e.,
  34. modules dynamically defined at runtime). Most modules are physically defined in external `.py`-suffixed scripts.
  35. Some modules, however, are dynamically defined at runtime (e.g., `six.moves`, dynamically defined by the
  36. physically defined `six.py` module). However, `ModuleGraph` only parses `import` statements residing in external
  37. scripts. `ModuleGraph` is _not_ a full-fledged, Turing-complete Python interpreter and hence has no means of
  38. parsing `import` statements performed by runtime modules existing only in-memory.
  39. 'With great power comes great responsibility.'
  40. Attributes (Immutable)
  41. ----------------------------
  42. The following attributes are **immutable** (i.e., read-only). For safety, any attempts to change these attributes
  43. _will_ result in a raised exception:
  44. module_graph : PyiModuleGraph
  45. Current module graph.
  46. parent_package : Package
  47. Graph node for the package providing this module _or_ `None` if this module is a top-level module.
  48. Attributes (Mutable)
  49. -----------------------------
  50. The following attributes are editable.
  51. module_basename : str
  52. Unqualified name of the module to be imported (e.g., `text`).
  53. module_name : str
  54. Fully-qualified name of this module (e.g., `email.mime.text`).
  55. """
  56. def __init__(self, module_graph, module_basename, module_name, parent_package):
  57. self._module_graph = module_graph
  58. self.module_basename = module_basename
  59. self.module_name = module_name
  60. self._parent_package = parent_package
  61. # Immutable properties. No corresponding setters are defined.
  62. @property
  63. def module_graph(self):
  64. """
  65. Current module graph.
  66. """
  67. return self._module_graph
  68. @property
  69. def parent_package(self):
  70. """
  71. Parent Package of this node.
  72. """
  73. return self._parent_package
  74. def add_runtime_module(self, module_name):
  75. """
  76. Add a graph node representing a non-package Python module with the passed name dynamically defined at runtime.
  77. Most modules are statically defined on-disk as standard Python files. Some modules, however, are dynamically
  78. defined in-memory at runtime (e.g., `gi.repository.Gst`, dynamically defined by the statically defined
  79. `gi.repository.__init__` module).
  80. This method adds a graph node representing such a runtime module. Since this module is _not_ a package,
  81. all attempts to import submodules from this module in `from`-style import statements (e.g., the `queue`
  82. submodule in `from six.moves import queue`) will be silently ignored. To circumvent this, simply call
  83. `add_runtime_package()` instead.
  84. Parameters
  85. ----------
  86. module_name : str
  87. Fully-qualified name of this module (e.g., `gi.repository.Gst`).
  88. Examples
  89. ----------
  90. This method is typically called by `pre_safe_import_module()` hooks, e.g.:
  91. def pre_safe_import_module(api):
  92. api.add_runtime_module(api.module_name)
  93. """
  94. self._module_graph.add_module(RuntimeModule(module_name))
  95. def add_runtime_package(self, package_name):
  96. """
  97. Add a graph node representing a non-namespace Python package with the passed name dynamically defined at
  98. runtime.
  99. Most packages are statically defined on-disk as standard subdirectories containing `__init__.py` files. Some
  100. packages, however, are dynamically defined in-memory at runtime (e.g., `six.moves`, dynamically defined by
  101. the statically defined `six` module).
  102. This method adds a graph node representing such a runtime package. All attributes imported from this package
  103. in `from`-style import statements that are submodules of this package (e.g., the `queue` submodule in `from
  104. six.moves import queue`) will be imported rather than ignored.
  105. Parameters
  106. ----------
  107. package_name : str
  108. Fully-qualified name of this package (e.g., `six.moves`).
  109. Examples
  110. ----------
  111. This method is typically called by `pre_safe_import_module()` hooks, e.g.:
  112. def pre_safe_import_module(api):
  113. api.add_runtime_package(api.module_name)
  114. """
  115. self._module_graph.add_module(RuntimePackage(package_name))
  116. def add_alias_module(self, real_module_name, alias_module_name):
  117. """
  118. Alias the source module to the target module with the passed names.
  119. This method ensures that the next call to findNode() given the target module name will resolve this alias.
  120. This includes importing and adding a graph node for the source module if needed as well as adding a reference
  121. from the target to the source module.
  122. Parameters
  123. ----------
  124. real_module_name : str
  125. Fully-qualified name of the **existing module** (i.e., the module being aliased).
  126. alias_module_name : str
  127. Fully-qualified name of the **non-existent module** (i.e., the alias to be created).
  128. """
  129. self._module_graph.alias_module(real_module_name, alias_module_name)
  130. def append_package_path(self, directory):
  131. """
  132. Modulegraph does a good job at simulating Python's, but it cannot handle packagepath `__path__` modifications
  133. packages make at runtime.
  134. Therefore there is a mechanism whereby you can register extra paths in this map for a package, and it will be
  135. honored.
  136. Parameters
  137. ----------
  138. directory : str
  139. Absolute or relative path of the directory to be appended to this package's `__path__` attribute.
  140. """
  141. self._module_graph.append_package_path(self.module_name, directory)
  142. class PreFindModulePathAPI(object):
  143. """
  144. Metadata communicating changes made by the current **pre-find module path hook** (i.e., hook run immediately
  145. _before_ a call to `ModuleGraph._find_module_path()` finding the hooked module's absolute path) back to PyInstaller.
  146. Pre-find module path hooks _must_ define a `pre_find_module_path()` function accepting an instance of this class,
  147. whose attributes describe the subsequent `ModuleGraph._find_module_path()` call to be performed.
  148. Pre-find module path hooks are typically used to change the absolute path from which a module will be
  149. subsequently imported and thus frozen into the executable. To do so, hooks may overwrite the default
  150. `search_dirs` list of the absolute paths of all directories to be searched for that module: e.g.,
  151. def pre_find_module_path(api):
  152. api.search_dirs = ['/the/one/true/package/providing/this/module']
  153. Each pre-find module path hook is run _only_ on the first call to `ModuleGraph._find_module_path()` for the
  154. corresponding module.
  155. Attributes
  156. ----------
  157. The following attributes are **mutable** (i.e., modifiable). All changes to these attributes will be immediately
  158. respected by PyInstaller:
  159. search_dirs : list
  160. List of the absolute paths of all directories to be searched for this module (in order). Searching will halt
  161. at the first directory containing this module.
  162. Attributes (Immutable)
  163. ----------
  164. The following attributes are **immutable** (i.e., read-only). For safety, any attempts to change these attributes
  165. _will_ result in a raised exception:
  166. module_name : str
  167. Fully-qualified name of this module.
  168. module_graph : PyiModuleGraph
  169. Current module graph. For efficiency, this attribute is technically mutable. To preserve graph integrity,
  170. this attribute should nonetheless _never_ be modified. While read-only `PyiModuleGraph` methods (e.g.,
  171. `findNode()`) are safely callable from within pre-find module path hooks, methods modifying the graph are
  172. _not_. If graph modifications are required, consider an alternative type of hook (e.g., pre-import module
  173. hooks).
  174. """
  175. def __init__(
  176. self,
  177. module_graph,
  178. module_name,
  179. search_dirs,
  180. ):
  181. # Mutable attributes.
  182. self.search_dirs = search_dirs
  183. # Immutable attributes.
  184. self._module_graph = module_graph
  185. self._module_name = module_name
  186. # Immutable properties. No corresponding setters are defined.
  187. @property
  188. def module_graph(self):
  189. """
  190. Current module graph.
  191. """
  192. return self._module_graph
  193. @property
  194. def module_name(self):
  195. """
  196. Fully-qualified name of this module.
  197. """
  198. return self._module_name
  199. class PostGraphAPI(object):
  200. """
  201. Metadata communicating changes made by the current **post-graph hook** (i.e., hook run for a specific module
  202. transitively imported by the current application _after_ the module graph of all `import` statements performed by
  203. this application has been constructed) back to PyInstaller.
  204. Post-graph hooks may optionally define a `post_graph()` function accepting an instance of this class,
  205. whose attributes describe the current state of the module graph and the hooked module's graph node.
  206. Attributes (Mutable)
  207. ----------
  208. The following attributes are **mutable** (i.e., modifiable). All changes to these attributes will be immediately
  209. respected by PyInstaller:
  210. module_graph : PyiModuleGraph
  211. Current module graph.
  212. module : Node
  213. Graph node for the currently hooked module.
  214. 'With great power comes great responsibility.'
  215. Attributes (Immutable)
  216. ----------
  217. The following attributes are **immutable** (i.e., read-only). For safety, any attempts to change these attributes
  218. _will_ result in a raised exception:
  219. __name__ : str
  220. Fully-qualified name of this module (e.g., `six.moves.tkinter`).
  221. __file__ : str
  222. Absolute path of this module. If this module is:
  223. * A standard (rather than namespace) package, this is the absolute path of this package's directory.
  224. * A namespace (rather than standard) package, this is the abstract placeholder `-`. (Don't ask. Don't tell.)
  225. * A non-package module or C extension, this is the absolute path of the corresponding file.
  226. __path__ : list
  227. List of the absolute paths of all directories comprising this package if this module is a package _or_ `None`
  228. otherwise. If this module is a standard (rather than namespace) package, this list contains only the absolute
  229. path of this package's directory.
  230. co : code
  231. Code object compiled from the contents of `__file__` (e.g., via the `compile()` builtin).
  232. analysis: build_main.Analysis
  233. The Analysis that load the hook.
  234. Attributes (Private)
  235. ----------
  236. The following attributes are technically mutable but private, and hence should _never_ be externally accessed or
  237. modified by hooks. Call the corresponding public methods instead:
  238. _added_datas : list
  239. List of the `(name, path)` 2-tuples or TOC objects of all external data files required by the current hook,
  240. defaulting to the empty list. This is equivalent to the global `datas` hook attribute.
  241. _added_imports : list
  242. List of the fully-qualified names of all modules imported by the current hook, defaulting to the empty list.
  243. This is equivalent to the global `hiddenimports` hook attribute.
  244. _added_binaries : list
  245. List of the `(name, path)` 2-tuples or TOC objects of all external C extensions imported by the current hook,
  246. defaulting to the empty list. This is equivalent to the global `binaries` hook attribute.
  247. """
  248. def __init__(self, module_name, module_graph, analysis):
  249. # Mutable attributes.
  250. self.module_graph = module_graph
  251. self.module = module_graph.find_node(module_name)
  252. assert self.module is not None # should not occur
  253. # Immutable attributes.
  254. self.___name__ = module_name
  255. self.___file__ = self.module.filename
  256. self._co = self.module.code
  257. self._analysis = analysis
  258. # To enforce immutability, convert this module's package path if any into an immutable tuple.
  259. self.___path__ = tuple(self.module.packagepath) \
  260. if self.module.packagepath is not None else None
  261. #FIXME: Refactor "_added_datas", "_added_binaries", and "_deleted_imports" into sets. Since order of
  262. #import is important, "_added_imports" must remain a list.
  263. # Private attributes.
  264. self._added_binaries = []
  265. self._added_datas = []
  266. self._added_imports = []
  267. self._deleted_imports = []
  268. # Immutable properties. No corresponding setters are defined.
  269. @property
  270. def __file__(self):
  271. """
  272. Absolute path of this module's file.
  273. """
  274. return self.___file__
  275. @property
  276. def __path__(self):
  277. """
  278. List of the absolute paths of all directories comprising this package if this module is a package _or_ `None`
  279. otherwise. If this module is a standard (rather than namespace) package, this list contains only the absolute
  280. path of this package's directory.
  281. """
  282. return self.___path__
  283. @property
  284. def __name__(self):
  285. """
  286. Fully-qualified name of this module (e.g., `six.moves.tkinter`).
  287. """
  288. return self.___name__
  289. @property
  290. def co(self):
  291. """
  292. Code object compiled from the contents of `__file__` (e.g., via the `compile()` builtin).
  293. """
  294. return self._co
  295. @property
  296. def analysis(self):
  297. """
  298. build_main.Analysis that calls the hook.
  299. """
  300. return self._analysis
  301. # Obsolete immutable properties provided to preserve backward compatibility.
  302. @property
  303. def name(self):
  304. """
  305. Fully-qualified name of this module (e.g., `six.moves.tkinter`).
  306. **This property has been deprecated by the `__name__` property.**
  307. """
  308. return self.___name__
  309. @property
  310. def graph(self):
  311. """
  312. Current module graph.
  313. **This property has been deprecated by the `module_graph` property.**
  314. """
  315. return self.module_graph
  316. @property
  317. def node(self):
  318. """
  319. Graph node for the currently hooked module.
  320. **This property has been deprecated by the `module` property.**
  321. """
  322. return self.module
  323. # TODO: This incorrectly returns the list of the graph nodes of all modules *TRANSITIVELY* (rather than directly)
  324. # imported by this module. Unfortunately, this implies that most uses of this property are currently broken
  325. # (e.g., "hook-PIL.SpiderImagePlugin.py"). We only require this for the aforementioned hook, so contemplate
  326. # alternative approaches.
  327. @property
  328. def imports(self):
  329. """
  330. List of the graph nodes of all modules directly imported by this module.
  331. """
  332. return self.module_graph.iter_graph(start=self.module)
  333. def add_imports(self, *module_names):
  334. """
  335. Add all Python modules whose fully-qualified names are in the passed list as "hidden imports" upon which the
  336. current module depends.
  337. This is equivalent to appending such names to the hook-specific `hiddenimports` attribute.
  338. """
  339. # Append such names to the current list of all such names.
  340. self._added_imports.extend(module_names)
  341. def del_imports(self, *module_names):
  342. """
  343. Remove the named fully-qualified modules from the set of imports (either hidden or visible) upon which the
  344. current module depends.
  345. This is equivalent to appending such names to the hook-specific `excludedimports` attribute.
  346. """
  347. self._deleted_imports.extend(module_names)
  348. def add_binaries(self, list_of_tuples):
  349. """
  350. Add all external dynamic libraries in the passed list of `(name, path)` 2-tuples as dependencies of the
  351. current module. This is equivalent to adding to the global `binaries` hook attribute.
  352. For convenience, the `list_of_tuples` may also be a single TOC or TREE instance.
  353. """
  354. if isinstance(list_of_tuples, TOC):
  355. self._added_binaries.extend(i[:2] for i in list_of_tuples)
  356. else:
  357. self._added_binaries.extend(format_binaries_and_datas(list_of_tuples))
  358. def add_datas(self, list_of_tuples):
  359. """
  360. Add all external data files in the passed list of `(name, path)` 2-tuples as dependencies of the current
  361. module. This is equivalent to adding to the global `datas` hook attribute.
  362. For convenience, the `list_of_tuples` may also be a single TOC or TREE instance.
  363. """
  364. if isinstance(list_of_tuples, TOC):
  365. self._added_datas.extend(i[:2] for i in list_of_tuples)
  366. else:
  367. self._added_datas.extend(format_binaries_and_datas(list_of_tuples))