Python code coverage for Lib/importlib/abc.py

#	count	content
1	n/a	"""Abstract base classes related to import."""
2	n/a	from . import _bootstrap
3	n/a	from . import _bootstrap_external
4	n/a	from . import machinery
5	n/a	try:
6	n/a	import _frozen_importlib
7	n/a	except ImportError as exc:
8	n/a	if exc.name != '_frozen_importlib':
9	n/a	raise
10	n/a	_frozen_importlib = None
11	n/a	try:
12	n/a	import _frozen_importlib_external
13	n/a	except ImportError as exc:
14	n/a	_frozen_importlib_external = _bootstrap_external
15	n/a	import abc
16	n/a
17	n/a
18	n/a	def _register(abstract_cls, *classes):
19	n/a	for cls in classes:
20	n/a	abstract_cls.register(cls)
21	n/a	if _frozen_importlib is not None:
22	n/a	try:
23	n/a	frozen_cls = getattr(_frozen_importlib, cls.__name__)
24	n/a	except AttributeError:
25	n/a	frozen_cls = getattr(_frozen_importlib_external, cls.__name__)
26	n/a	abstract_cls.register(frozen_cls)
27	n/a
28	n/a
29	n/a	class Finder(metaclass=abc.ABCMeta):
30	n/a
31	n/a	"""Legacy abstract base class for import finders.
32	n/a
33	n/a	It may be subclassed for compatibility with legacy third party
34	n/a	reimplementations of the import system. Otherwise, finder
35	n/a	implementations should derive from the more specific MetaPathFinder
36	n/a	or PathEntryFinder ABCs.
37	n/a	"""
38	n/a
39	n/a	@abc.abstractmethod
40	n/a	def find_module(self, fullname, path=None):
41	n/a	"""An abstract method that should find a module.
42	n/a	The fullname is a str and the optional path is a str or None.
43	n/a	Returns a Loader object or None.
44	n/a	"""
45	n/a
46	n/a
47	n/a	class MetaPathFinder(Finder):
48	n/a
49	n/a	"""Abstract base class for import finders on sys.meta_path."""
50	n/a
51	n/a	# We don't define find_spec() here since that would break
52	n/a	# hasattr checks we do to support backward compatibility.
53	n/a
54	n/a	def find_module(self, fullname, path):
55	n/a	"""Return a loader for the module.
56	n/a
57	n/a	If no module is found, return None. The fullname is a str and
58	n/a	the path is a list of strings or None.
59	n/a
60	n/a	This method is deprecated in favor of finder.find_spec(). If find_spec()
61	n/a	exists then backwards-compatible functionality is provided for this
62	n/a	method.
63	n/a
64	n/a	"""
65	n/a	if not hasattr(self, 'find_spec'):
66	n/a	return None
67	n/a	found = self.find_spec(fullname, path)
68	n/a	return found.loader if found is not None else None
69	n/a
70	n/a	def invalidate_caches(self):
71	n/a	"""An optional method for clearing the finder's cache, if any.
72	n/a	This method is used by importlib.invalidate_caches().
73	n/a	"""
74	n/a
75	n/a	_register(MetaPathFinder, machinery.BuiltinImporter, machinery.FrozenImporter,
76	n/a	machinery.PathFinder, machinery.WindowsRegistryFinder)
77	n/a
78	n/a
79	n/a	class PathEntryFinder(Finder):
80	n/a
81	n/a	"""Abstract base class for path entry finders used by PathFinder."""
82	n/a
83	n/a	# We don't define find_spec() here since that would break
84	n/a	# hasattr checks we do to support backward compatibility.
85	n/a
86	n/a	def find_loader(self, fullname):
87	n/a	"""Return (loader, namespace portion) for the path entry.
88	n/a
89	n/a	The fullname is a str. The namespace portion is a sequence of
90	n/a	path entries contributing to part of a namespace package. The
91	n/a	sequence may be empty. If loader is not None, the portion will
92	n/a	be ignored.
93	n/a
94	n/a	The portion will be discarded if another path entry finder
95	n/a	locates the module as a normal module or package.
96	n/a
97	n/a	This method is deprecated in favor of finder.find_spec(). If find_spec()
98	n/a	is provided than backwards-compatible functionality is provided.
99	n/a
100	n/a	"""
101	n/a	if not hasattr(self, 'find_spec'):
102	n/a	return None, []
103	n/a	found = self.find_spec(fullname)
104	n/a	if found is not None:
105	n/a	if not found.submodule_search_locations:
106	n/a	portions = []
107	n/a	else:
108	n/a	portions = found.submodule_search_locations
109	n/a	return found.loader, portions
110	n/a	else:
111	n/a	return None, []
112	n/a
113	n/a	find_module = _bootstrap_external._find_module_shim
114	n/a
115	n/a	def invalidate_caches(self):
116	n/a	"""An optional method for clearing the finder's cache, if any.
117	n/a	This method is used by PathFinder.invalidate_caches().
118	n/a	"""
119	n/a
120	n/a	_register(PathEntryFinder, machinery.FileFinder)
121	n/a
122	n/a
123	n/a	class Loader(metaclass=abc.ABCMeta):
124	n/a
125	n/a	"""Abstract base class for import loaders."""
126	n/a
127	n/a	def create_module(self, spec):
128	n/a	"""Return a module to initialize and into which to load.
129	n/a
130	n/a	This method should raise ImportError if anything prevents it
131	n/a	from creating a new module. It may return None to indicate
132	n/a	that the spec should create the new module.
133	n/a	"""
134	n/a	# By default, defer to default semantics for the new module.
135	n/a	return None
136	n/a
137	n/a	# We don't define exec_module() here since that would break
138	n/a	# hasattr checks we do to support backward compatibility.
139	n/a
140	n/a	def load_module(self, fullname):
141	n/a	"""Return the loaded module.
142	n/a
143	n/a	The module must be added to sys.modules and have import-related
144	n/a	attributes set properly. The fullname is a str.
145	n/a
146	n/a	ImportError is raised on failure.
147	n/a
148	n/a	This method is deprecated in favor of loader.exec_module(). If
149	n/a	exec_module() exists then it is used to provide a backwards-compatible
150	n/a	functionality for this method.
151	n/a
152	n/a	"""
153	n/a	if not hasattr(self, 'exec_module'):
154	n/a	raise ImportError
155	n/a	return _bootstrap._load_module_shim(self, fullname)
156	n/a
157	n/a	def module_repr(self, module):
158	n/a	"""Return a module's repr.
159	n/a
160	n/a	Used by the module type when the method does not raise
161	n/a	NotImplementedError.
162	n/a
163	n/a	This method is deprecated.
164	n/a
165	n/a	"""
166	n/a	# The exception will cause ModuleType.__repr__ to ignore this method.
167	n/a	raise NotImplementedError
168	n/a
169	n/a
170	n/a	class ResourceLoader(Loader):
171	n/a
172	n/a	"""Abstract base class for loaders which can return data from their
173	n/a	back-end storage.
174	n/a
175	n/a	This ABC represents one of the optional protocols specified by PEP 302.
176	n/a
177	n/a	"""
178	n/a
179	n/a	@abc.abstractmethod
180	n/a	def get_data(self, path):
181	n/a	"""Abstract method which when implemented should return the bytes for
182	n/a	the specified path. The path must be a str."""
183	n/a	raise IOError
184	n/a
185	n/a
186	n/a	class InspectLoader(Loader):
187	n/a
188	n/a	"""Abstract base class for loaders which support inspection about the
189	n/a	modules they can load.
190	n/a
191	n/a	This ABC represents one of the optional protocols specified by PEP 302.
192	n/a
193	n/a	"""
194	n/a
195	n/a	def is_package(self, fullname):
196	n/a	"""Optional method which when implemented should return whether the
197	n/a	module is a package. The fullname is a str. Returns a bool.
198	n/a
199	n/a	Raises ImportError if the module cannot be found.
200	n/a	"""
201	n/a	raise ImportError
202	n/a
203	n/a	def get_code(self, fullname):
204	n/a	"""Method which returns the code object for the module.
205	n/a
206	n/a	The fullname is a str. Returns a types.CodeType if possible, else
207	n/a	returns None if a code object does not make sense
208	n/a	(e.g. built-in module). Raises ImportError if the module cannot be
209	n/a	found.
210	n/a	"""
211	n/a	source = self.get_source(fullname)
212	n/a	if source is None:
213	n/a	return None
214	n/a	return self.source_to_code(source)
215	n/a
216	n/a	@abc.abstractmethod
217	n/a	def get_source(self, fullname):
218	n/a	"""Abstract method which should return the source code for the
219	n/a	module. The fullname is a str. Returns a str.
220	n/a
221	n/a	Raises ImportError if the module cannot be found.
222	n/a	"""
223	n/a	raise ImportError
224	n/a
225	n/a	@staticmethod
226	n/a	def source_to_code(data, path='<string>'):
227	n/a	"""Compile 'data' into a code object.
228	n/a
229	n/a	The 'data' argument can be anything that compile() can handle. The'path'
230	n/a	argument should be where the data was retrieved (when applicable)."""
231	n/a	return compile(data, path, 'exec', dont_inherit=True)
232	n/a
233	n/a	exec_module = _bootstrap_external._LoaderBasics.exec_module
234	n/a	load_module = _bootstrap_external._LoaderBasics.load_module
235	n/a
236	n/a	_register(InspectLoader, machinery.BuiltinImporter, machinery.FrozenImporter)
237	n/a
238	n/a
239	n/a	class ExecutionLoader(InspectLoader):
240	n/a
241	n/a	"""Abstract base class for loaders that wish to support the execution of
242	n/a	modules as scripts.
243	n/a
244	n/a	This ABC represents one of the optional protocols specified in PEP 302.
245	n/a
246	n/a	"""
247	n/a
248	n/a	@abc.abstractmethod
249	n/a	def get_filename(self, fullname):
250	n/a	"""Abstract method which should return the value that __file__ is to be
251	n/a	set to.
252	n/a
253	n/a	Raises ImportError if the module cannot be found.
254	n/a	"""
255	n/a	raise ImportError
256	n/a
257	n/a	def get_code(self, fullname):
258	n/a	"""Method to return the code object for fullname.
259	n/a
260	n/a	Should return None if not applicable (e.g. built-in module).
261	n/a	Raise ImportError if the module cannot be found.
262	n/a	"""
263	n/a	source = self.get_source(fullname)
264	n/a	if source is None:
265	n/a	return None
266	n/a	try:
267	n/a	path = self.get_filename(fullname)
268	n/a	except ImportError:
269	n/a	return self.source_to_code(source)
270	n/a	else:
271	n/a	return self.source_to_code(source, path)
272	n/a
273	n/a	_register(ExecutionLoader, machinery.ExtensionFileLoader)
274	n/a
275	n/a
276	n/a	class FileLoader(_bootstrap_external.FileLoader, ResourceLoader, ExecutionLoader):
277	n/a
278	n/a	"""Abstract base class partially implementing the ResourceLoader and
279	n/a	ExecutionLoader ABCs."""
280	n/a
281	n/a	_register(FileLoader, machinery.SourceFileLoader,
282	n/a	machinery.SourcelessFileLoader)
283	n/a
284	n/a
285	n/a	class SourceLoader(_bootstrap_external.SourceLoader, ResourceLoader, ExecutionLoader):
286	n/a
287	n/a	"""Abstract base class for loading source code (and optionally any
288	n/a	corresponding bytecode).
289	n/a
290	n/a	To support loading from source code, the abstractmethods inherited from
291	n/a	ResourceLoader and ExecutionLoader need to be implemented. To also support
292	n/a	loading from bytecode, the optional methods specified directly by this ABC
293	n/a	is required.
294	n/a
295	n/a	Inherited abstractmethods not implemented in this ABC:
296	n/a
297	n/a	* ResourceLoader.get_data
298	n/a	* ExecutionLoader.get_filename
299	n/a
300	n/a	"""
301	n/a
302	n/a	def path_mtime(self, path):
303	n/a	"""Return the (int) modification time for the path (str)."""
304	n/a	if self.path_stats.__func__ is SourceLoader.path_stats:
305	n/a	raise IOError
306	n/a	return int(self.path_stats(path)['mtime'])
307	n/a
308	n/a	def path_stats(self, path):
309	n/a	"""Return a metadata dict for the source pointed to by the path (str).
310	n/a	Possible keys:
311	n/a	- 'mtime' (mandatory) is the numeric timestamp of last source
312	n/a	code modification;
313	n/a	- 'size' (optional) is the size in bytes of the source code.
314	n/a	"""
315	n/a	if self.path_mtime.__func__ is SourceLoader.path_mtime:
316	n/a	raise IOError
317	n/a	return {'mtime': self.path_mtime(path)}
318	n/a
319	n/a	def set_data(self, path, data):
320	n/a	"""Write the bytes to the path (if possible).
321	n/a
322	n/a	Accepts a str path and data as bytes.
323	n/a
324	n/a	Any needed intermediary directories are to be created. If for some
325	n/a	reason the file cannot be written because of permissions, fail
326	n/a	silently.
327	n/a	"""
328	n/a
329	n/a	_register(SourceLoader, machinery.SourceFileLoader)