Python code coverage for Lib/importlib/util.py

#	count	content
1	n/a	"""Utility code for constructing importers, etc."""
2	n/a	from . import abc
3	n/a	from ._bootstrap import module_from_spec
4	n/a	from ._bootstrap import _resolve_name
5	n/a	from ._bootstrap import spec_from_loader
6	n/a	from ._bootstrap import _find_spec
7	n/a	from ._bootstrap_external import MAGIC_NUMBER
8	n/a	from ._bootstrap_external import cache_from_source
9	n/a	from ._bootstrap_external import decode_source
10	n/a	from ._bootstrap_external import source_from_cache
11	n/a	from ._bootstrap_external import spec_from_file_location
12	n/a
13	n/a	from contextlib import contextmanager
14	n/a	import functools
15	n/a	import sys
16	n/a	import types
17	n/a	import warnings
18	n/a
19	n/a
20	n/a	def resolve_name(name, package):
21	n/a	"""Resolve a relative module name to an absolute one."""
22	n/a	if not name.startswith('.'):
23	n/a	return name
24	n/a	elif not package:
25	n/a	raise ValueError(f'no package specified for {repr(name)} '
26	n/a	'(required for relative module names)')
27	n/a	level = 0
28	n/a	for character in name:
29	n/a	if character != '.':
30	n/a	break
31	n/a	level += 1
32	n/a	return _resolve_name(name[level:], package, level)
33	n/a
34	n/a
35	n/a	def _find_spec_from_path(name, path=None):
36	n/a	"""Return the spec for the specified module.
37	n/a
38	n/a	First, sys.modules is checked to see if the module was already imported. If
39	n/a	so, then sys.modules[name].__spec__ is returned. If that happens to be
40	n/a	set to None, then ValueError is raised. If the module is not in
41	n/a	sys.modules, then sys.meta_path is searched for a suitable spec with the
42	n/a	value of 'path' given to the finders. None is returned if no spec could
43	n/a	be found.
44	n/a
45	n/a	Dotted names do not have their parent packages implicitly imported. You will
46	n/a	most likely need to explicitly import all parent packages in the proper
47	n/a	order for a submodule to get the correct spec.
48	n/a
49	n/a	"""
50	n/a	if name not in sys.modules:
51	n/a	return _find_spec(name, path)
52	n/a	else:
53	n/a	module = sys.modules[name]
54	n/a	if module is None:
55	n/a	return None
56	n/a	try:
57	n/a	spec = module.__spec__
58	n/a	except AttributeError:
59	n/a	raise ValueError('{}.__spec__ is not set'.format(name)) from None
60	n/a	else:
61	n/a	if spec is None:
62	n/a	raise ValueError('{}.__spec__ is None'.format(name))
63	n/a	return spec
64	n/a
65	n/a
66	n/a	def find_spec(name, package=None):
67	n/a	"""Return the spec for the specified module.
68	n/a
69	n/a	First, sys.modules is checked to see if the module was already imported. If
70	n/a	so, then sys.modules[name].__spec__ is returned. If that happens to be
71	n/a	set to None, then ValueError is raised. If the module is not in
72	n/a	sys.modules, then sys.meta_path is searched for a suitable spec with the
73	n/a	value of 'path' given to the finders. None is returned if no spec could
74	n/a	be found.
75	n/a
76	n/a	If the name is for submodule (contains a dot), the parent module is
77	n/a	automatically imported.
78	n/a
79	n/a	The name and package arguments work the same as importlib.import_module().
80	n/a	In other words, relative module names (with leading dots) work.
81	n/a
82	n/a	"""
83	n/a	fullname = resolve_name(name, package) if name.startswith('.') else name
84	n/a	if fullname not in sys.modules:
85	n/a	parent_name = fullname.rpartition('.')[0]
86	n/a	if parent_name:
87	n/a	# Use builtins.__import__() in case someone replaced it.
88	n/a	parent = __import__(parent_name, fromlist=['__path__'])
89	n/a	return _find_spec(fullname, parent.__path__)
90	n/a	else:
91	n/a	return _find_spec(fullname, None)
92	n/a	else:
93	n/a	module = sys.modules[fullname]
94	n/a	if module is None:
95	n/a	return None
96	n/a	try:
97	n/a	spec = module.__spec__
98	n/a	except AttributeError:
99	n/a	raise ValueError('{}.__spec__ is not set'.format(name)) from None
100	n/a	else:
101	n/a	if spec is None:
102	n/a	raise ValueError('{}.__spec__ is None'.format(name))
103	n/a	return spec
104	n/a
105	n/a
106	n/a	@contextmanager
107	n/a	def _module_to_load(name):
108	n/a	is_reload = name in sys.modules
109	n/a
110	n/a	module = sys.modules.get(name)
111	n/a	if not is_reload:
112	n/a	# This must be done before open() is called as the 'io' module
113	n/a	# implicitly imports 'locale' and would otherwise trigger an
114	n/a	# infinite loop.
115	n/a	module = type(sys)(name)
116	n/a	# This must be done before putting the module in sys.modules
117	n/a	# (otherwise an optimization shortcut in import.c becomes wrong)
118	n/a	module.__initializing__ = True
119	n/a	sys.modules[name] = module
120	n/a	try:
121	n/a	yield module
122	n/a	except Exception:
123	n/a	if not is_reload:
124	n/a	try:
125	n/a	del sys.modules[name]
126	n/a	except KeyError:
127	n/a	pass
128	n/a	finally:
129	n/a	module.__initializing__ = False
130	n/a
131	n/a
132	n/a	def set_package(fxn):
133	n/a	"""Set __package__ on the returned module.
134	n/a
135	n/a	This function is deprecated.
136	n/a
137	n/a	"""
138	n/a	@functools.wraps(fxn)
139	n/a	def set_package_wrapper(args, *kwargs):
140	n/a	warnings.warn('The import system now takes care of this automatically.',
141	n/a	DeprecationWarning, stacklevel=2)
142	n/a	module = fxn(args, *kwargs)
143	n/a	if getattr(module, '__package__', None) is None:
144	n/a	module.__package__ = module.__name__
145	n/a	if not hasattr(module, '__path__'):
146	n/a	module.__package__ = module.__package__.rpartition('.')[0]
147	n/a	return module
148	n/a	return set_package_wrapper
149	n/a
150	n/a
151	n/a	def set_loader(fxn):
152	n/a	"""Set __loader__ on the returned module.
153	n/a
154	n/a	This function is deprecated.
155	n/a
156	n/a	"""
157	n/a	@functools.wraps(fxn)
158	n/a	def set_loader_wrapper(self, args, *kwargs):
159	n/a	warnings.warn('The import system now takes care of this automatically.',
160	n/a	DeprecationWarning, stacklevel=2)
161	n/a	module = fxn(self, args, *kwargs)
162	n/a	if getattr(module, '__loader__', None) is None:
163	n/a	module.__loader__ = self
164	n/a	return module
165	n/a	return set_loader_wrapper
166	n/a
167	n/a
168	n/a	def module_for_loader(fxn):
169	n/a	"""Decorator to handle selecting the proper module for loaders.
170	n/a
171	n/a	The decorated function is passed the module to use instead of the module
172	n/a	name. The module passed in to the function is either from sys.modules if
173	n/a	it already exists or is a new module. If the module is new, then __name__
174	n/a	is set the first argument to the method, __loader__ is set to self, and
175	n/a	__package__ is set accordingly (if self.is_package() is defined) will be set
176	n/a	before it is passed to the decorated function (if self.is_package() does
177	n/a	not work for the module it will be set post-load).
178	n/a
179	n/a	If an exception is raised and the decorator created the module it is
180	n/a	subsequently removed from sys.modules.
181	n/a
182	n/a	The decorator assumes that the decorated function takes the module name as
183	n/a	the second argument.
184	n/a
185	n/a	"""
186	n/a	warnings.warn('The import system now takes care of this automatically.',
187	n/a	DeprecationWarning, stacklevel=2)
188	n/a	@functools.wraps(fxn)
189	n/a	def module_for_loader_wrapper(self, fullname, args, *kwargs):
190	n/a	with _module_to_load(fullname) as module:
191	n/a	module.__loader__ = self
192	n/a	try:
193	n/a	is_package = self.is_package(fullname)
194	n/a	except (ImportError, AttributeError):
195	n/a	pass
196	n/a	else:
197	n/a	if is_package:
198	n/a	module.__package__ = fullname
199	n/a	else:
200	n/a	module.__package__ = fullname.rpartition('.')[0]
201	n/a	# If __package__ was not set above, __import__() will do it later.
202	n/a	return fxn(self, module, args, *kwargs)
203	n/a
204	n/a	return module_for_loader_wrapper
205	n/a
206	n/a
207	n/a	class _LazyModule(types.ModuleType):
208	n/a
209	n/a	"""A subclass of the module type which triggers loading upon attribute access."""
210	n/a
211	n/a	def __getattribute__(self, attr):
212	n/a	"""Trigger the load of the module and return the attribute."""
213	n/a	# All module metadata must be garnered from __spec__ in order to avoid
214	n/a	# using mutated values.
215	n/a	# Stop triggering this method.
216	n/a	self.__class__ = types.ModuleType
217	n/a	# Get the original name to make sure no object substitution occurred
218	n/a	# in sys.modules.
219	n/a	original_name = self.__spec__.name
220	n/a	# Figure out exactly what attributes were mutated between the creation
221	n/a	# of the module and now.
222	n/a	attrs_then = self.__spec__.loader_state['__dict__']
223	n/a	original_type = self.__spec__.loader_state['__class__']
224	n/a	attrs_now = self.__dict__
225	n/a	attrs_updated = {}
226	n/a	for key, value in attrs_now.items():
227	n/a	# Code that set the attribute may have kept a reference to the
228	n/a	# assigned object, making identity more important than equality.
229	n/a	if key not in attrs_then:
230	n/a	attrs_updated[key] = value
231	n/a	elif id(attrs_now[key]) != id(attrs_then[key]):
232	n/a	attrs_updated[key] = value
233	n/a	self.__spec__.loader.exec_module(self)
234	n/a	# If exec_module() was used directly there is no guarantee the module
235	n/a	# object was put into sys.modules.
236	n/a	if original_name in sys.modules:
237	n/a	if id(self) != id(sys.modules[original_name]):
238	n/a	raise ValueError(f"module object for {original_name!r} "
239	n/a	"substituted in sys.modules during a lazy "
240	n/a	"load")
241	n/a	# Update after loading since that's what would happen in an eager
242	n/a	# loading situation.
243	n/a	self.__dict__.update(attrs_updated)
244	n/a	return getattr(self, attr)
245	n/a
246	n/a	def __delattr__(self, attr):
247	n/a	"""Trigger the load and then perform the deletion."""
248	n/a	# To trigger the load and raise an exception if the attribute
249	n/a	# doesn't exist.
250	n/a	self.__getattribute__(attr)
251	n/a	delattr(self, attr)
252	n/a
253	n/a
254	n/a	class LazyLoader(abc.Loader):
255	n/a
256	n/a	"""A loader that creates a module which defers loading until attribute access."""
257	n/a
258	n/a	@staticmethod
259	n/a	def __check_eager_loader(loader):
260	n/a	if not hasattr(loader, 'exec_module'):
261	n/a	raise TypeError('loader must define exec_module()')
262	n/a
263	n/a	@classmethod
264	n/a	def factory(cls, loader):
265	n/a	"""Construct a callable which returns the eager loader made lazy."""
266	n/a	cls.__check_eager_loader(loader)
267	n/a	return lambda args, kwargs: cls(loader(args, **kwargs))
268	n/a
269	n/a	def __init__(self, loader):
270	n/a	self.__check_eager_loader(loader)
271	n/a	self.loader = loader
272	n/a
273	n/a	def create_module(self, spec):
274	n/a	return self.loader.create_module(spec)
275	n/a
276	n/a	def exec_module(self, module):
277	n/a	"""Make the module load lazily."""
278	n/a	module.__spec__.loader = self.loader
279	n/a	module.__loader__ = self.loader
280	n/a	# Don't need to worry about deep-copying as trying to set an attribute
281	n/a	# on an object would have triggered the load,
282	n/a	# e.g. ``module.__spec__.loader = None`` would trigger a load from
283	n/a	# trying to access module.__spec__.
284	n/a	loader_state = {}
285	n/a	loader_state['__dict__'] = module.__dict__.copy()
286	n/a	loader_state['__class__'] = module.__class__
287	n/a	module.__spec__.loader_state = loader_state
288	n/a	module.__class__ = _LazyModule