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